Ollama Python API: Integration und Chatbot-Entwicklung (2026)

Ollama stellt eine lokale REST-API an Port 11434 bereit, die jede Programmiersprache aufrufen kann. Für Python gibt es zwei saubere Ansätze: die offizielle ollama-Bibliothek (ein schlankes Wrapper um die HTTP-API) und direkte requests- oder httpx-Aufrufe. Beide bieten dieselbe Funktionalität: Chat-Completions, Streaming, Embeddings und Modellverwaltung, ohne Daten an externe Server zu senden.
Diese Anleitung beginnt mit den Grundlagen und führt durch praktische Muster: einstufige Generierung, mehrstufiger Chat mit Verlauf, Streaming-Antworten, Embeddings für Vektorsuche und der Aufbau eines einfachen CLI-Chatbots. Alle Beispiele verwenden lokal laufendes Ollama. Falls Ollama noch nicht installiert ist, zunächst der Ollama-Einrichtungsanleitung folgen.
Die Code-Beispiele funktionieren mit jedem in der Ollama-Bibliothek verfügbaren Modell. Die Beispiele verwenden llama3.3, aber mistral, gemma3, codellama oder jedes andere gezogene Modell kann als Ersatz dienen.
Voraussetzungen
- Ollama installiert und laufend (Port 11434 erreichbar)
- Mindestens ein Modell gezogen: `ollama pull llama3.3`
- Python 3.9+ installiert
- `pip` für die Installation der ollama-Bibliothek verfügbar
- Grundlegende Python-Kenntnisse (Funktionen, Schleifen, Dictionaries)
Inhaltsverzeichnis
Ollama-Python-Bibliothek installieren
Die offizielle ollama-Python-Bibliothek umhüllt die REST-API mit einer übersichtlichen Schnittstelle, die die Ollama-CLI-Befehle widerspiegelt.
Mit pip installieren:
pip install ollamaVor dem Testen von Python-Code sicherstellen, dass Ollama läuft:
ollama serve &
curl http://localhost:11434
# Erwartet: Ollama is runningVerfügbare Modelle prüfen
Die gezogenen Modelle auflisten:
import ollama
models = ollama.list()
for model in models['models']:
print(model['name'], model['size'])Beispielausgabe:
llama3.3:latest 4.9 GB
mistral:latest 4.1 GB
nomic-embed-text:latest 274 MBConnectionRefusedError läuft Ollama nicht. Mit ollama serve in einem separaten Terminal starten (oder sudo systemctl start ollama unter Linux).Einfache Textgenerierung und Chat
Einstufige Generierung
Der einfachste Anwendungsfall: einen Prompt senden, eine Antwort erhalten.
import ollama
response = ollama.generate(
model='llama3.3',
prompt='Erkläre in zwei Sätzen, was eine REST-API ist.'
)
print(response['response'])Die Funktion generate gibt ein Dictionary zurück. Der generierte Text befindet sich in response['response']. Weitere nützliche Schlüssel:
| Schlüssel | Wert |
|---|---|
response | Der generierte Text |
model | Verwendeter Modellname |
total_duration | Gesamtzeit in Nanosekunden |
eval_count | Anzahl generierter Token |
eval_duration | Zeit für die Token-Generierung |
Mehrstufiger Chat mit Verlauf
Für Gespräche ollama.chat() verwenden und eine Liste von Nachrichten übergeben. Jede Nachricht hat eine role (user oder assistant) und einen content:
import ollama
messages = [
{'role': 'user', 'content': 'Was ist die Hauptstadt von Deutschland?'},
]
response = ollama.chat(model='llama3.3', messages=messages)
assistant_reply = response['message']['content']
print(assistant_reply)
# Antwort zum Verlauf hinzufügen und Folgefrage stellen
messages.append({'role': 'assistant', 'content': assistant_reply})
messages.append({'role': 'user', 'content': 'Wie viele Einwohner hat diese Stadt?'})
response = ollama.chat(model='llama3.3', messages=messages)
print(response['message']['content'])Das Modell nutzt den vollständigen Nachrichtenverlauf für den Kontext. Die Folgefrage "Wie viele Einwohner hat diese Stadt?" funktioniert, weil "diese Stadt" sich auf Berlin aus dem Gesprächsverlauf bezieht.
python messages = [ {'role': 'system', 'content': 'Sie sind ein präziser technischer Assistent. Halten Sie Antworten unter 3 Sätzen.'}, {'role': 'user', 'content': 'Was ist Docker?'}, ] ``Streaming-Antworten
Streaming gibt Token aus, sobald sie generiert werden, anstatt auf die vollständige Antwort zu warten. Dies verbessert die wahrgenommene Reaktionszeit erheblich.
Streaming mit ollama.chat()
import ollama
stream = ollama.chat(
model='llama3.3',
messages=[{'role': 'user', 'content': 'Schreibe eine Python-Funktion, die prüft, ob eine Zahl eine Primzahl ist.'}],
stream=True,
)
for chunk in stream:
print(chunk['message']['content'], end='', flush=True)
print() # Zeilenumbruch nach Streamingstream=True setzt, um einen Generator zu erhalten. Jedes chunk enthält ein Teil-message['content']. Das flush=True erzwingt die sofortige Ausgabe.
Streaming mit der REST-API direkt
Wenn requests statt der offiziellen Bibliothek bevorzugt wird:
import requests
import json
response = requests.post(
'http://localhost:11434/api/chat',
json={
'model': 'llama3.3',
'messages': [{'role': 'user', 'content': 'Was ist 37 * 48?'}],
'stream': True,
},
stream=True,
)
for line in response.iter_lines():
if line:
chunk = json.loads(line)
print(chunk['message']['content'], end='', flush=True)
if chunk.get('done'):
break
print()Die REST-API streamt zeilenweise JSON. Jede Zeile ist ein JSON-Objekt mit einem message-Schlüssel und einem done-Boolean, der beim letzten Chunk true ist.
Embeddings für Vektorsuche generieren
Ollama generiert Embeddings für den Einsatz in semantischer Suche, RAG-Pipelines und Clustering. Das beste Embedding-Modell in Ollamas Bibliothek ist nomic-embed-text (274 MB, 768-dimensionale Vektoren).
Embedding-Modell ziehen
ollama pull nomic-embed-textEin Embedding generieren
import ollama
response = ollama.embeddings(
model='nomic-embed-text',
prompt='Wie installiert man Ollama auf Ubuntu?',
)
embedding = response['embedding']
print(f"Vektor-Dimensionen: {len(embedding)}")
print(f"Erste 5 Werte: {embedding[:5]}")Vektor-Dimensionen: 768
Erste 5 Werte: [-0.024, 0.031, -0.008, 0.017, -0.041]Einfaches semantisches Ähnlichkeitsbeispiel
import ollama
import numpy as np
def get_embedding(text: str) -> list[float]:
response = ollama.embeddings(model='nomic-embed-text', prompt=text)
return response['embedding']
def cosine_similarity(a: list[float], b: list[float]) -> float:
a, b = np.array(a), np.array(b)
return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))
# Semantische Ähnlichkeit vergleichen
query = "Wie führe ich LLMs lokal aus?"
doc1 = "Ollama ermöglicht es, große Sprachmodelle auf der eigenen Hardware auszuführen."
doc2 = "Python ist eine beliebte Programmiersprache für Data Science."
query_emb = get_embedding(query)
score1 = cosine_similarity(query_emb, get_embedding(doc1))
score2 = cosine_similarity(query_emb, get_embedding(doc2))
print(f"Anfrage vs. Dok1 Ähnlichkeit: {score1:.4f}") # ~0.87
print(f"Anfrage vs. Dok2 Ähnlichkeit: {score2:.4f}") # ~0.42Numpy installieren: pip install numpy.
| Ähnlichkeitswert | Bedeutung |
|---|---|
| 0,90 - 1,00 | Nahezu identische Bedeutung |
| 0,75 - 0,90 | Stark verwandt |
| 0,50 - 0,75 | Mäßig verwandt |
| Unter 0,50 | Nicht verwandt |
CLI-Chatbot in 30 Zeilen bauen
Ein vollständiger Kommandozeilen-Chatbot, der den Gesprächsverlauf beibehält, Antworten streamt und sauber bei /beenden oder Strg+C endet:
import ollama
def chat():
model = 'llama3.3'
messages = [
{
'role': 'system',
'content': 'Sie sind ein hilfreicher Assistent. Antworten Sie präzise und direkt.',
}
]
print(f"Chatbot (Modell: {model}). '/beenden' eingeben zum Beenden.\n")
while True:
try:
user_input = input("Sie: ").strip()
except (KeyboardInterrupt, EOFError):
print("\nAuf Wiedersehen!")
break
if not user_input:
continue
if user_input.lower() == '/beenden':
print("Auf Wiedersehen!")
break
messages.append({'role': 'user', 'content': user_input})
print("Assistent: ", end='', flush=True)
full_reply = ''
stream = ollama.chat(model=model, messages=messages, stream=True)
for chunk in stream:
token = chunk['message']['content']
print(token, end='', flush=True)
full_reply += token
print()
messages.append({'role': 'assistant', 'content': full_reply})
if __name__ == '__main__':
chat()Als chatbot.py speichern und ausführen:
python chatbot.pyDer Chatbot pflegt während der Sitzung eine messages-Liste, um den Kontext zu merken.
python import sys model = sys.argv[1] if len(sys.argv) > 1 else 'llama3.3' ` Dann ausführen: python chatbot.py mistral`Fehlerbehebung
| Problem | Ursache | Lösung |
|---|---|---|
| ConnectionRefusedError: [Errno 111] Verbindung verweigert | Ollama läuft nicht oder hört auf einer anderen Adresse | Ollama starten: ollama serve (oder sudo systemctl start ollama unter Linux). Prüfen: curl http://localhost:11434. Falls Ollama auf einem Remote-Server läuft: ollama.Client(host="http://SERVER_IP:11434") verwenden. |
| Modell "llama3.3" nicht gefunden | Das Modell wurde noch nicht in die lokale Ollama-Instanz gezogen. | Modell zuerst ziehen: ollama pull llama3.3. Verfügbare Modelle prüfen: ollama list. Den Modellnamen im Code genau mit der Ausgabe von ollama list abgleichen. |
| Generierung sehr langsam (10+ Sekunden pro Antwort) | Das Modell läuft nur auf der CPU, die GPU wird nicht genutzt. | GPU-Nutzung prüfen: ollama run llama3.3 und GPU-Speichernutzung beobachten. Für NVIDIA: nvidia-smi. Falls GPU verfügbar, aber nicht genutzt: CUDA-Toolkit installieren. |
| Streaming-Chunks kommen als leere Zeichenketten | Das Modell hat die Generierung abgeschlossen, aber die Schleife läuft über das `done`-Signal hinaus. | Bei REST-API-Aufrufen auf chunk.get("done") == True prüfen und die Schleife beenden. Die offizielle ollama-Bibliothek behandelt dies automatisch. |
| Embeddings haben andere Dimensionen als erwartet | Verwendung eines Chat-Generierungsmodells für Embeddings statt eines dedizierten Embedding-Modells. | nomic-embed-text (768 Dimensionen) oder mxbai-embed-large (1024 Dimensionen) für Embeddings verwenden. Zuerst ollama pull nomic-embed-text ausführen. |
Alternativen
| Tool | Art | Preis | Ideal für |
|---|---|---|---|
| OpenAI Python SDK | Cloud-API (Python-Bibliothek) | $0,002-0,06 pro 1K Token | Produktionsanwendungen, bei denen Latenz und Qualität wichtiger sind als Kosten. |
| LangChain mit Ollama | Python-Framework | Kostenlos (Open Source) | Aufbau komplexer Chains, RAG-Pipelines und Agenten auf lokalen Ollama-Modellen. |
| LlamaIndex mit Ollama | Python-Framework | Kostenlos (Open Source) | Dokumentenverarbeitung, Vektorindizierung und Abfrage-Pipelines für private Daten. |
| Groq API | Cloud-API | Kostenloses Kontingent (großzügige Rate Limits) | Entwickler, die schnelle Cloud-Inferenz ohne lokale Hardware wünschen. |
Häufige Fragen
Was ist der Unterschied zwischen ollama.generate() und ollama.chat()?
ollama.generate() nimmt einen einzelnen prompt-String entgegen und gibt eine Completion zurück. Es wird kein Gesprächskontext zwischen Aufrufen gespeichert.
ollama.chat() nimmt eine Liste von Nachrichten mit role- und content-Feldern entgegen. Es ist für mehrstufige Gespräche konzipiert, bei denen das Modell frühere Austausche berücksichtigen soll. generate für einmalige Aufgaben (Zusammenfassung, Code-Generierung) und chat für interaktive Gespräche verwenden.
Wie verbindet man sich von Python aus mit einer Ollama-Instanz auf einem Remote-Server?
Die Klasse ollama.Client verwenden und die Host-URL übergeben:
import ollama
client = ollama.Client(host='http://IHRE_SERVER_IP:11434')
response = client.chat(model='llama3.3', messages=[{'role': 'user', 'content': 'Hallo'}])Der Server muss Ollama laufend haben und Port 11434 in seiner Firewall offen. Standardmäßig hört Ollama nur auf localhost. Auf dem Server OLLAMA_HOST=0.0.0.0 setzen, um Remote-Verbindungen zu akzeptieren.
Kann man Ollama mit LangChain in Python verwenden?
Ja. LangChain hat eine integrierte ChatOllama-Integration:
from langchain_ollama import ChatOllama
from langchain_core.messages import HumanMessage
llm = ChatOllama(model="llama3.3")
response = llm.invoke([HumanMessage(content="Was ist LangChain?")])
print(response.content)Installieren: pip install langchain-ollama. Dies ermöglicht das gesamte LangChain-Ökosystem (Chains, Agenten, RAG-Pipelines) mit lokalen Ollama-Modellen.
Wie setzt man einen System-Prompt mit Ollama in Python?
Eine Nachricht mit role: "system" als erstes Element in der Nachrichtenliste hinzufügen:
messages = [
{'role': 'system', 'content': 'Sie sind ein Python-Experte. Fügen Sie immer Typ-Annotationen in Code-Beispiele ein.'},
{'role': 'user', 'content': 'Schreiben Sie eine Funktion zum Sortieren einer Liste von Dictionaries nach einem Schlüssel.'},
]
response = ollama.chat(model='llama3.3', messages=messages)Die Systemnachricht setzt die Persona und Einschränkungen des Modells. Sie gilt für das gesamte Gespräch.
Welches ist das beste Embedding-Modell für Ollama in Python?
Die beiden besten Optionen sind:
- nomic-embed-text (274 MB, 768 Dimensionen): schnell, klein, gute allgemeine Embeddings. Am besten für die meisten RAG-Anwendungsfälle.
- mxbai-embed-large (669 MB, 1024 Dimensionen): höhere Embedding-Qualität, besser für präzise semantische Suche, langsamer als nomic.
Mit ollama pull nomic-embed-text ziehen und ollama.embeddings(model='nomic-embed-text', prompt='Ihr Text') verwenden.
Wie zählt man Token für Ollama-Antworten in Python?
Die Ollama-API-Antwort enthält Token-Zählungen in den Metadaten:
response = ollama.chat(model='llama3.3', messages=[...])
print(f"Prompt-Token: {response['prompt_eval_count']}")
print(f"Antwort-Token: {response['eval_count']}")
print(f"Gesamt-Token: {response['prompt_eval_count'] + response['eval_count']}")Streaming-Antworten enthalten Token-Zählungen nur im letzten Chunk, bei dem done True ist.

Verfasst von
AmaraKI-Expertin bei KI Tool Entdeckung. Spezialisiert auf Self-Hosting, lokale KI-Modelle und KI-Automatisierung. Zuletzt aktualisiert: 7. April 2026