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

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:

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:

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

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

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:

llama-server -hf nomic-ai/nomic-embed-text-v1.5-GGUF --embeddings --alias nomic-embed-text-v1.5 --port 8081

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, 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.

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 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).

​Konfigurieren

​Überprüfen

​Embeddings

​Modell-Metadaten

​Modellklassifizierung

​Über Chat und Embeddings hinaus

Konfigurieren

Überprüfen

Embeddings

Modell-Metadaten

Modellklassifizierung

Über Chat und Embeddings hinaus