Ollama REST API

Was dieser Artikel über die Ollama REST API behandelt

• Welche Endpunkte Ollama bietet.
• Wie man generiert, chattet und Embeddings erzeugt.
• Unterschied zwischen nativer und OpenAI-kompatibler API.
• Beispiele in cURL und Python.
• Tipps für Integration und Fehlerbehebung.

Einleitung: Ollama REST API

Ollama bietet eine leistungsfähige REST API, über die externe Anwendungen und Agenten auf lokale Modelle zugreifen können. Die API ist in zwei Varianten verfügbar: die native Ollama-API und ein OpenAI-kompatibler Endpunkt. Beide Varianten ermöglichen es, Ollama in bestehende Tools, Skripte und Agenten-Frameworks einzubinden.

Dieser Artikel zeigt die wichtigsten Endpunkte, Beispiele und typische Stolpersteine.

Wichtige Begriffe

• Endpoint: URL-Pfad der API.
• Generate: Einzelne Textgenerierung aus einem Prompt.
• Chat: Mehrturnige Konversation mit Nachrichten.
• Embedding: Umwandlung von Text in einen Vektor.
• Streaming: Antwort wird Token für Token gesendet.
• OpenAI-kompatibel: Endpoint folgt dem OpenAI-Schema.
• Model: Bezeichnung des geladenen Sprachmodells.

API-Grundlagen

Die API lauscht standardmäßig auf:

http://localhost:11434

Für den OpenAI-kompatiblen Endpunkt fügt man /v1 hinzu:

http://localhost:11434/v1

Verfügbare Modelle abrufen

curl http://localhost:11434/api/tags

Antwort:

{
  "models": [
    {
      "name": "llama3.1:latest",
      "model": "llama3.1:latest",
      "size": 4928300400,
      "parameter_size": "8.0B"
    }
  ]
}

Text generieren

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.1",
  "prompt": "Erkläre die Ollama REST API in drei Sätzen.",
  "stream": false
}'

Antwort:

{
  "model": "llama3.1",
  "response": "Die Ollama REST API ermöglicht...",
  "done": true
}

Chat-Endpunkt

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.1",
  "messages": [
    {"role": "system", "content": "Du bist ein hilfreicher Assistent."},
    {"role": "user", "content": "Was ist die Ollama REST API?"}
  ],
  "stream": false
}'

Antwort:

{
  "model": "llama3.1",
  "message": {
    "role": "assistant",
    "content": "Die Ollama REST API ist..."
  },
  "done": true
}

Embeddings

curl http://localhost:11434/api/embed -d '{
  "model": "nomic-embed-text",
  "input": "Dies ist ein Beispieltext."
}'

Antwort:

{
  "model": "nomic-embed-text",
  "embeddings": [[0.12, -0.34, 0.56, ...]]
}

OpenAI-kompatibler Endpunkt

Viele Tools und SDKs erwarten das OpenAI-Schema. Ollama bietet:

http://localhost:11434/v1/chat/completions

Beispiel:

curl http://localhost:11434/v1/chat/completions -H "Content-Type: application/json" -d '{
  "model": "llama3.1",
  "messages": [
    {"role": "user", "content": "Hallo Ollama."}
  ],
  "temperature": 0.7
}'

Beispiel in Python

import requests

url = "http://localhost:11434/api/chat"
payload = {
    "model": "llama3.1",
    "messages": [
        {"role": "user", "content": "Erkläre REST APIs."}
    ],
    "stream": False
}

resp = requests.post(url, json=payload)
print(resp.json()["message"]["content"])

Streaming

Für echtes Streaming setzt man stream auf true und verarbeitet die empfangenen Zeilen:

import requests
import json

url = "http://localhost:11434/api/chat"
payload = {
    "model": "llama3.1",
    "messages": [{"role": "user", "content": "Erzähle mir einen Witz."}],
    "stream": True
}

resp = requests.post(url, json=payload, stream=True)
for line in resp.iter_lines():
    if line:
        data = json.loads(line)
        print(data.get("message", {}).get("content", ""), end="")

Parameter

Wichtige Parameter:

• temperature: Kreativität.
• top_p: Nucleus-Sampling.
• top_k: Begrenzung der Top-K-Tokens.
• num_predict: Maximale Anzahl Tokens.
• num_ctx: Kontextlänge.
• repeat_penalty: Wiederholungsstrafe.
• seed: Reproduzierbarkeit.

Netzwerkzugriff

Standardmäßig lauscht Ollama nur auf 127.0.0.1. Für Netzwerkzugriff setze:

export OLLAMA_HOST=0.0.0.0:11434

In Docker:

-e OLLAMA_HOST=0.0.0.0:11434

Achtung: Ollama bietet keine eigene Authentifizierung. Zugriff über Firewall oder VPN absichern.

Integration in andere Tools

• Open WebUI: OLLAMA_BASE_URL=http://localhost:11434
• OpenClaw: nativer Endpoint http://localhost:11434, nicht /v1.
• LangChain: Ollama oder ChatOllama-Klassen.
• Continue.dev: Endpoint http://localhost:11434/v1 mit API-Key ollama.

Typische Stolpersteine

• Falscher Endpunkt: OpenClaw braucht /api, nicht /v1.
• Modell nicht geladen: ollama pull vorab ausführen.
• Zu wenig Speicher: Modell lädt nicht oder bricht ab.
• Streaming nicht verarbeiten: stream: true liefert mehrere JSON-Zeilen.
• Netzwerkzugriff fehlt: OLLAMA_HOST setzen, Firewall prüfen.
• OpenAI-Client verweigert Verbindung: API-Key ollama oder sk-ollama eingeben.

Weiterführende Links und Infos

• BotServ.de Ollama Funktionen
• BotServ.de Ollama einrichten
• BotServ.de Open WebUI Administration
• BotServ.de Ollama in Open WebUI verwalten

FAQ: Ollama REST API

Welcher Endpunkt ist der richtige? Für reine Ollama-Clients /api/chat oder /api/generate. Für OpenAI-kompatible Tools /v1/chat/completions.

Brauche ich einen API-Key? Nein, Ollama authentifiziert nicht. Für externe Tools geben manche ollama als Key ein.

Kann ich mehrere Modelle gleichzeitig nutzen? Ja, aber Ollama hält nur jeweils ein Modell im Speicher, das gerade genutzt wird.

Wie erhalte ich Embeddings? Über /api/embed mit einem Embedding-Modell wie nomic-embed-text.

Ist Streaming möglich? Ja, setze stream: true und verarbeite die eingehenden Zeilen.

Quellen und weiterführende Literatur

• Ollama API Docs: https://github.com/ollama/ollama/blob/main/docs/api.md
• OpenAI API Reference: https://platform.openai.com/docs/api-reference

Zusammenfassung: Ollama REST API

Die Ollama REST API ermöglicht den Zugriff auf lokale Modelle über HTTP. Die native API bietet generate, chat und embed, während der /v1-Endpunkt Kompatibilität zu OpenAI-Clients bietet. Wer Endpunkt, Modellnamen, Streaming und Parameter richtig nutzt, kann Ollama nahtlos in Open WebUI, Agenten, RAG-Systeme und eigene Skripte integrieren. Besonders wichtig ist der Unterschied zwischen nativem und OpenAI-kompatiblem Endpunkt.