> ## Documentation Index
> Fetch the complete documentation index at: https://gomodel.enterpilot.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# llama.cpp-Server: Anbindung an ein LLM-Gateway

> Leiten Sie OpenAI-kompatible GoModel-Requests an eine llama.cpp-Instanz von llama-server weiter (derselbe Provider-Typ funktioniert auch für LM Studio).

`llama-server` von llama.cpp spricht direkt die OpenAI-API, und GoModel hat dafür einen eigenen
Provider-Typ `llamacpp`: Der API-Key ist optional (llama-server läuft meist ohne Key), und
Provider-eigene Endpunkte wie `/health` und `/rerank` sind über Passthrough erreichbar.
Registrieren Sie llama.cpp **nicht** als `ollama`-Provider: Dieser Typ spricht die native API von
Ollama, die llama.cpp nicht implementiert.

Derselbe Provider-Typ eignet sich für LM Studio und jeden anderen einfachen OpenAI-kompatiblen
lokalen Server.

Starten Sie zuerst llama-server. Ohne `--alias` ist die Modell-ID in `/v1/models` der Pfad der
Modelldatei – setzen Sie einen Alias, damit Requests einen sauberen Namen verwenden können:

```bash theme={null}
llama-server -hf ggml-org/gemma-3-4b-it-GGUF --alias gemma-3-4b-it --port 8081
# fügen Sie --api-key token-abc123 hinzu, wenn llama-server Bearer-Authentifizierung verlangen soll
```

## Konfigurieren

Die Base-URL ist erforderlich und registriert den Provider – der Standardport von llama-server
(8080) kollidiert mit dem von GoModel, daher gibt es keinen Standardwert:

```bash theme={null}
LLAMACPP_BASE_URL=http://host.docker.internal:8081/v1   # /v1 einschließen
# LLAMACPP_API_KEY=token-abc123                         # nur, wenn llama-server mit --api-key gestartet wurde
GOMODEL_MASTER_KEY=change-me
```

> [!NOTE]
>
> Diese Beispiele gehen davon aus, dass GoModel in Docker läuft und llama-server auf dem Host unter
> `localhost:8081` – daher `host.docker.internal`. Läuft GoModel direkt auf dem Host, verwenden Sie
> `http://localhost:8081/v1`. Sie betreiben mehrere llama-server-Instanzen? Registrieren Sie jede
> unter einem Namen mit Suffix: `LLAMACPP_STUDIO_BASE_URL=...` erzeugt den Provider
> `llamacpp-studio`.

## Überprüfen

```bash theme={null}
curl -s http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llamacpp/gemma-3-4b-it",
    "messages": [{"role": "user", "content": "Reply with exactly ok."}]
  }'
```

`GET /v1/models` gibt die Modell-IDs von llama-server mit dem Provider-Namen als Präfix zurück.

## Embeddings

`/v1/embeddings` funktioniert über GoModel, solange llama-server den Endpunkt bedienen kann: Das
geladene Modell muss einen anderen Pooling-Typ als `none` verwenden. Spezielle Embedding-GGUFs
deklarieren das Pooling in der Regel in ihren Metadaten; andernfalls übergeben Sie
`--pooling mean` (oder `cls`/`last`). Das Flag `--embeddings` ist optional – es beschränkt den
Server ausschließlich auf Embeddings:

```bash theme={null}
llama-server -hf nomic-ai/nomic-embed-text-v1.5-GGUF --embeddings --alias nomic-embed-text-v1.5 --port 8081
```

```bash theme={null}
curl -s http://localhost:8080/v1/embeddings \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"model": "llamacpp/nomic-embed-text-v1.5", "input": "hello"}'
```

## Modell-Metadaten

Lokale GGUFs sind nicht im Upstream-Modellkatalog enthalten, daher liest GoModel, was es kann,
direkt aus llama-server und gibt es unter `GET /v1/models` aus:

* **Kontextfenster** – der von llama-server für das Modell gemeldete `n_ctx` pro Slot, also der
  Kontext, mit dem es *läuft* (`--ctx-size`, aufgeteilt auf `--parallel` Slots), nicht der, für den
  das GGUF trainiert wurde. Neuere Builds melden ihn als `meta.n_ctx` direkt in der Auflistung;
  ältere werden über `/props` danach gefragt. Antwortet keines von beiden – LM Studio oder ein
  Proxy, der `/props` verbirgt –, wird stattdessen der Trainingswert `n_ctx_train` des Modells
  verwendet. Dieser ist nur eine Obergrenze und kann größer sein als das, was der Server
  akzeptiert.
* **Modalitäten** – ein multimodaler Server (gestartet mit `--mmproj`) meldet `vision`, `video`
  und `audio` unter `/props`; die unterstützten werden zu Modell-Capabilities.

`/props` beschreibt das eine Modell, das der Server geladen hat, und wird daher nur bei einer
Auflistung mit genau einem Eintrag abgefragt. Im
[Router-Modus](https://github.com/ggml-org/llama.cpp/tree/master/tools/server), in dem ein Prozess
mehrere Modelle bereitstellt, trägt jedes Modell seinen eigenen `meta.n_ctx` und benötigt
überhaupt kein `/props`.

Beides sind Standardwerte, keine endgültigen Entscheidungen: Alles, was Sie in den
Modell-Metadaten des Providers deklarieren, hat Vorrang – siehe
[Modell-Metadaten](https://gomodel.enterpilot.io/docs/de/advanced/model-metadata.md).

## Modellklassifizierung

llama-server meldet nichts, was ein Chat-Modell von einem Embedding-Modell unterscheidet, daher
klassifiziert GoModel seine Modelle anhand der ID: Namen, die `embed` enthalten oder bekannten
Embedding-Familien entsprechen (`bge`, `e5`, `gte`, `minilm`), werden als Embedding-Modelle
eingeordnet, und Namen, die `rerank` enthalten, als Reranking-Modelle – bei IDs mit Namespace wird
das letzte Pfadsegment geprüft. Für alles, was unklassifiziert bleibt, deklarieren Sie `modes` in
den Modell-Metadaten des Providers. Kategorien wirken sich nur auf die Gruppierung im Dashboard
aus; `/v1/embeddings` routet unabhängig von der Kategorie zu jedem Modell, das der Provider
bereitstellt.

## Über Chat und Embeddings hinaus

* **Multimodaler Input** – Bild- und Audio-*Input* in Chat-Nachrichten funktioniert mit
  multimodalen Modellen, wenn llama-server mit einem Projector gestartet wird (`--mmproj`, wird
  mit `-hf` automatisch geladen, sofern verfügbar). Diese Requests laufen ganz normal über
  `/v1/chat/completions`.
* **Native Endpunkte** – die Provider-eigenen Routen von llama-server sind über
  [Passthrough](https://gomodel.enterpilot.io/docs/de/features/passthrough-api.md) unter `/p/llamacpp/...` erreichbar: Pfade im
  OpenAI-Format (`chat/completions`, `embeddings`, ...) werden von der `/v1`-Basis bedient, alles
  andere (`/health`, `/props`, `/tokenize`, `/infill`, ...) vom Server-Root. Bei einer Einrichtung
  mit Suffix verwenden Sie den Instanznamen, z. B. `/p/llamacpp-studio/health`.
* **Reranking** – llama-server bietet Reranking (starten Sie ihn mit einem Reranker-Modell und
  `--rerank --embedding --pooling rank`), GoModel hat jedoch keinen Rerank-Endpunkt; erreichen Sie
  es über Passthrough: `POST /p/llamacpp/rerank` (oder `/p/llamacpp/v1/rerank`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.