# LocalAI

Führen Sie eine selbst gehostete OpenAI-kompatible API mit LocalAI aus.

{% hint style="success" %}
Alle Beispiele können auf GPU-Servern ausgeführt werden, die über [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Serveranforderungen

| Parameter | Minimum          | Empfohlen |
| --------- | ---------------- | --------- |
| RAM       | 8GB              | 16GB+     |
| VRAM      | 6GB              | 8GB+      |
| Netzwerk  | 200Mbps          | 500Mbps+  |
| Startzeit | **5–10 Minuten** | -         |

{% hint style="warning" %}
**Wichtig:** LocalAI benötigt beim ersten Start 5–10 Minuten zur vollständigen Initialisierung. HTTP 502 in dieser Zeit ist normal – der Dienst lädt Modelle herunter und lädt sie.
{% endhint %}

{% hint style="info" %}
LocalAI ist ressourcenschonend. Für den Betrieb von LLMs (Modelle ab 7B) wählen Sie Server mit 16GB+ RAM und 8GB+ VRAM.
{% endhint %}

## Was ist LocalAI?

LocalAI bietet:

* Drop-in-Ersatz für die OpenAI API
* Unterstützung für mehrere Modellformate
* Erzeugung von Text, Bildern, Audio und Embeddings
* Keine GPU erforderlich (aber mit GPU schneller)

## Unterstützte Modelle

| Typ        | Formate     | Beispiele           |
| ---------- | ----------- | ------------------- |
| LLM        | GGUF, GGML  | Llama, Mistral, Phi |
| Embeddings | GGUF        | all-MiniLM, BGE     |
| Bilder     | Diffusers   | SD 1.5, SDXL        |
| Audio      | Whisper     | Speech-to-Text      |
| TTS        | Piper, Bark | Text-zu-Sprache     |

## Schnelle Bereitstellung

**Docker-Image:**

```
localai/localai:master-aio-gpu-nvidia-cuda-12
```

**Ports:**

```
22/tcp
8080/http
```

**Kein Befehl erforderlich** - Server startet automatisch.

### Überprüfen, ob es funktioniert

Nach der Bereitstellung finden Sie Ihre `http_pub` URL in **Meine Bestellungen** und testen:

```bash
# Prüfen, ob der Dienst bereit ist
curl https://your-http-pub.clorecloud.net/readyz

# Verfügbare Modelle auflisten
curl https://your-http-pub.clorecloud.net/v1/models

# Version abrufen
curl https://your-http-pub.clorecloud.net/version
```

{% hint style="warning" %}
Wenn Sie HTTP 502 erhalten, warten Sie 5–10 Minuten – LocalAI benötigt länger zur Initialisierung als andere Dienste.
{% endhint %}

## Vorinstallierte Modelle

LocalAI wird mit mehreren sofort verfügbaren Modellen ausgeliefert:

| Modellname                 | Typ        | Beschreibung               |
| -------------------------- | ---------- | -------------------------- |
| `gpt-4`                    | Chat       | Allzweck-LLM               |
| `gpt-4o`                   | Chat       | Allzweck-LLM               |
| `gpt-4o-mini`              | Chat       | Kleineres, schnelleres LLM |
| `whisper-1`                | STT        | Speech-to-Text             |
| `tts-1`                    | TTS        | Text-zu-Sprache            |
| `text-embedding-ada-002`   | Embeddings | 384-dimensionale Vektoren  |
| `jina-reranker-v1-base-en` | Reranking  | Dokument-Reranking         |

{% hint style="info" %}
Diese Modelle funktionieren sofort nach dem Start ohne zusätzliche Konfiguration.
{% endhint %}

## Zugriff auf Ihren Dienst

Bei Bereitstellung auf CLORE.AI greifen Sie auf LocalAI über die `http_pub` URL:

```bash
# Chat-Vervollständigung
curl https://your-http-pub.clorecloud.net/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "gpt-4",
        "messages": [{"role": "user", "content": "Hello!"}]
    }'
```

{% hint style="info" %}
Alle `localhost:8080` Die untenstehenden Beispiele funktionieren, wenn über SSH verbunden. Für externen Zugriff ersetzen Sie durch Ihre `https://your-http-pub.clorecloud.net/` URL.
{% endhint %}

## Docker-Bereitstellung (Alternative)

```bash
docker run -d \
    --gpus all \
    -p 8080:8080 \
    -v /workspace/models:/models \
    -e THREADS=4 \
    -e CONTEXT_SIZE=4096 \
    localai/localai:master-aio-gpu-nvidia-cuda-12
```

## Modelle herunterladen

### Aus der Modellgalerie

LocalAI verfügt über eine integrierte Modellgalerie:

```bash
# Verfügbare Modelle auflisten
curl http://localhost:8080/models/available

# Aus der Galerie installieren
curl http://localhost:8080/models/apply -d '{"id": "mistral-7b-instruct"}'
```

### Von Hugging Face

```bash
mkdir -p /workspace/models

# Llama 3.1 8B GGUF
wget https://huggingface.co/bartowski/Meta-Llama-3.1-8B-Instruct-GGUF/resolve/main/Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf \
    -O /workspace/models/llama-3.1-8b.gguf

# Mistral 7B GGUF
wget https://huggingface.co/bartowski/Mistral-7B-Instruct-v0.3-GGUF/resolve/main/Mistral-7B-Instruct-v0.3-Q4_K_M.gguf \
    -O /workspace/models/mistral-7b.gguf
```

## Modellkonfiguration

Erstellen Sie für jedes Modell eine YAML-Konfig:

**models/llama-3.1-8b.yaml:**

```yaml
name: llama-3.1-8b
backend: llama-cpp
parameters:
  model: llama-3.1-8b.gguf
  context_size: 4096
  threads: 8
  gpu_layers: 35
template:
  chat: |
    {{.Input}}
    ### Antwort:
  completion: |
    {{.Input}}
```

## API-Nutzung

### Chat-Completions (OpenAI-kompatibel)

```python
import openai

# Für externen Zugriff verwenden Sie Ihre http_pub-URL:
client = openai.OpenAI(
    base_url="https://your-http-pub.clorecloud.net/v1",
    api_key="nicht benötigt"
)

# Oder über SSH-Tunnel:
# client = openai.OpenAI(base_url="http://localhost:8080/v1", api_key="not-needed")

response = client.chat.completions.create(
    model="mistral-7b",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Erkläre Quantencomputing in einfachen Worten."}
    ],
    temperature=0.7,
    max_tokens=500
)

print(response.choices[0].message.content)
```

### Streaming

```python
stream = client.chat.completions.create(
    model="mistral-7b",
    messages=[{"role": "user", "content": "Schreibe ein Gedicht über KI"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

### Embeddings

```python
response = client.embeddings.create(
    model="all-minilm",
    input="The quick brown fox jumps over the lazy dog"
)

embedding = response.data[0].embedding
print(f"Embedding dimension: {len(embedding)}")
```

### Bildgenerierung

```python
response = client.images.generate(
    model="stablediffusion",
    prompt="a beautiful sunset over mountains",
    size="512x512",
    n=1
)

image_url = response.data[0].url
```

## cURL-Beispiele

### Chat

```bash
curl https://your-http-pub.clorecloud.net/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "mistral-7b",
        "messages": [{"role": "user", "content": "Hello!"}]
    }'
```

### Embeddings

```bash
curl https://your-http-pub.clorecloud.net/v1/embeddings \
    -H "Content-Type: application/json" \
    -d '{
        "model": "text-embedding-ada-002",
        "input": "Ihr Text hier"
    }'
```

Antwort:

```json
{
  "data": [{"embedding": [0.1, -0.2, ...], "index": 0}],
  "model": "text-embedding-ada-002",
  "usage": {"prompt_tokens": 4, "total_tokens": 4}
}
```

### Text-zu-Sprache (TTS)

```bash
curl https://your-http-pub.clorecloud.net/v1/audio/speech \
    -H "Content-Type: application/json" \
    -d '{
        "model": "tts-1",
        "input": "Hallo, willkommen bei LocalAI!",
        "voice": "alloy"
    }' \
    --output speech.wav
```

Verfügbare Stimmen: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`

### Speech-to-Text (STT)

```bash
curl https://your-http-pub.clorecloud.net/v1/audio/transcriptions \
    -F "file=@audio.mp3" \
    -F "model=whisper-1"
```

Antwort:

```json
{"text": "Hier transkribierter Text..."}
```

### Reranking

Reranke Dokumente nach Relevanz zu einer Anfrage:

```bash
curl https://your-http-pub.clorecloud.net/v1/rerank \
    -H "Content-Type: application/json" \
    -d '{
        "model": "jina-reranker-v1-base-en",
        "query": "Was ist maschinelles Lernen?",
        "documents": [
            "Maschinelles Lernen ist ein Teilgebiet der KI",
            "Das Wetter ist heute schön",
            "Deep Learning verwendet neuronale Netze"
        ],
        "top_n": 2
    }'
```

Antwort:

```json
{
  "results": [
    {"index": 0, "relevance_score": 0.95},
    {"index": 2, "relevance_score": 0.82}
  ]
}
```

## Vollständige API-Referenz

### Standardendpunkte (OpenAI-kompatibel)

| Endpunkt                   | Methode | Beschreibung                 |
| -------------------------- | ------- | ---------------------------- |
| `/v1/models`               | GET     | Verfügbare Modelle auflisten |
| `/v1/chat/completions`     | POST    | Chat-Vervollständigung       |
| `/v1/completions`          | POST    | Textvervollständigung        |
| `/v1/embeddings`           | POST    | Embeddings erzeugen          |
| `/v1/audio/speech`         | POST    | Text-zu-Sprache              |
| `/v1/audio/transcriptions` | POST    | Speech-to-Text               |
| `/v1/images/generations`   | POST    | Bildgenerierung              |

### Zusätzliche Endpunkte

| Endpunkt            | Methode | Beschreibung                        |
| ------------------- | ------- | ----------------------------------- |
| `/readyz`           | GET     | Readiness-Check                     |
| `/healthz`          | GET     | Health-Check                        |
| `/version`          | GET     | LocalAI-Version abrufen             |
| `/v1/rerank`        | POST    | Dokument-Reranking                  |
| `/models/available` | GET     | Galerie-Modelle auflisten           |
| `/models/apply`     | POST    | Modell aus der Galerie installieren |
| `/swagger/`         | GET     | Swagger-UI-Dokumentation            |
| `/metrics`          | GET     | Prometheus-Metriken                 |

#### Version abrufen

```bash
curl https://your-http-pub.clorecloud.net/version
```

Antwort:

```json
{"version": "v2.26.0"}
```

#### Swagger-Dokumentation

Öffnen Sie im Browser für interaktive API-Dokumentation:

```
https://your-http-pub.clorecloud.net/swagger/
```

## GPU-Beschleunigung

### CUDA-Backend

```yaml
# In der Modellkonfiguration
parameters:
  gpu_layers: 35  # Anzahl der Layer auf der GPU
  f16: true       # FP16 verwenden
```

### Vollständiges GPU-Offload

```yaml
parameters:
  gpu_layers: 99  # Alle Layer auf der GPU
  main_gpu: 0     # Primäre GPU-ID
```

## Mehrere Modelle

LocalAI kann mehrere Modelle gleichzeitig bedienen:

```
models/
├── llama-3.1-8b.yaml
├── llama-3.1-8b.gguf
├── mistral-7b.yaml
├── mistral-7b.gguf
├── whisper.yaml
└── whisper-base.bin
```

Greifen Sie über den Modellnamen in API-Aufrufen auf jedes zu.

## Performance-Tuning

### Für Geschwindigkeit

```yaml
parameters:
  threads: 8
  gpu_layers: 99
  batch_size: 512
  use_mmap: true
  use_mlock: true
```

### Für Speicher

```yaml
parameters:
  gpu_layers: 20  # Partielles Offload
  context_size: 2048  # Kleinere Kontextgröße
  batch_size: 256
```

## Benchmarks

| Modell          | GPU      | Tokens/sec |
| --------------- | -------- | ---------- |
| Llama 3.1 8B Q4 | RTX 3090 | \~100      |
| Mistral 7B Q4   | RTX 3090 | \~110      |
| Llama 3.1 8B Q4 | RTX 4090 | \~140      |
| Mixtral 8x7B Q4 | A100     | \~60       |

*Benchmarks aktualisiert Januar 2026.*

## Fehlerbehebung

### HTTP 502 auf http\_pub-URL

LocalAI benötigt länger zum Starten als andere Dienste. Warten Sie **5–10 Minuten** und versuchen Sie es erneut:

```bash
# Bereitschaft prüfen
curl https://your-http-pub.clorecloud.net/readyz

# Gesundheit prüfen
curl https://your-http-pub.clorecloud.net/healthz
```

### Modell wird nicht geladen

* Dateipfad in YAML prüfen
* GGUF-Formatkompatibilität überprüfen
* Verfügbaren VRAM prüfen

### Langsame Antworten

* Erhöhen Sie `gpu_layers`
* Aktivieren Sie `use_mmap`
* Reduzieren `context_size`

### Kein Speicher mehr

* Reduzieren `gpu_layers`
* Verwenden Sie kleinere Quantisierung (Q4 statt Q8)
* Batch-Größe reduzieren

### Probleme bei der Bildgenerierung

{% hint style="warning" %}
Stable Diffusion kann auf einigen GPU-Konfigurationen CUDA-Kompatibilitätsprobleme haben. Wenn Sie CUDA-Fehler bei der Bildgenerierung erhalten, ziehen Sie in Betracht, stattdessen ein dediziertes Stable-Diffusion-Bild zu verwenden.
{% endhint %}

## Kostenabschätzung

Typische CLORE.AI-Marktplatzpreise:

| GPU      | VRAM | Preis/Tag  | Geeignet für      |
| -------- | ---- | ---------- | ----------------- |
| RTX 3060 | 12GB | $0.15–0.30 | 7B-Modelle        |
| RTX 3090 | 24GB | $0.30–1.00 | 13B-Modelle       |
| RTX 4090 | 24GB | $0.50–2.00 | Schnelle Inferenz |
| A100     | 40GB | $1.50–3.00 | Große Modelle     |

*Preise in USD/Tag. Die Tarife variieren je nach Anbieter — prüfen Sie* [*CLORE.AI Marketplace*](https://clore.ai/marketplace) *auf aktuelle Preise.*

## Nächste Schritte

* [vLLM-Inferenz](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/vllm) - Höherer Durchsatz
* [Ollama-Anleitung](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/ollama) - Einfachere Einrichtung
* [RAG mit LangChain](https://docs.clore.ai/guides/guides_v2-de/fortgeschritten/api-integration) - Anwendungen erstellen