Ollama-API in Python, dann ein gehosteter Endpunkt

Python-Client einrichten

Installiere zuerst Ollama selbst, starte es und ziehe ein Modell über ein Terminal: ollama pull llama3. Der Server hört auf http://localhost:11434. Installiere dann das Python-Paket in einer virtuellen Umgebung:

Copypython -m venv .venv
source .venv/bin/activate
pip install ollama openai

Das ollama-Paket kommuniziert mit den nativen Endpunkten von Ollama unter /api. Das openai-Paket ist für den zweiten Teil dieses Tutorials gedacht, in dem das Ziel ein gehosteter Endpunkt ist. Wenn du vor dem Coden ein visuelles Tool bevorzugst, sieh dir die Hinweise zur Verwendung von Ollama mit einer GUI an.

Überprüfe die Installation, indem du ollama list im Terminal ausführst. Wenn dein Modell dort erscheint, findet Python es. Wenn du später einen Verbindungsfehler erhältst, läuft der Server wahrscheinlich nicht.

Dein erster Chat-Aufruf

Dies sind die Grundlagen der Ollama-API in Python in einem Snippet: eine Systemnachricht, eine Benutzernachricht und zwei Optionen.

Copyimport ollama

resp = ollama.chat(
    model="llama3",
    messages=[
        {"role": "system", "content": "Answer in one short paragraph."},
        {"role": "user", "content": "What is a context window?"},
    ],
    options={"temperature": 0.4, "num_ctx": 8192},
)
print(resp["message"]["content"])

Die Antwort ist ein dictionary-ähnliches Objekt; der Text steht in message.content. In options kannst du Generierungsparameter festlegen. temperature steuert die Zufälligkeit und num_ctx legt die Kontextlänge für diesen Aufruf fest. Ollama verwendet standardmäßig einen ziemlich kleinen Kontext, es sei denn, du erhöhst ihn, was Nutzer überrascht, die lange Dokumente einfügen und Antworten erhalten, die den Anfang ignorieren.

Für Multi-Turn-Chats behalte eine Liste von Nachrichten bei und hänge jede Antwort selbst an. Ollama ist wie die meisten Chat-APIs zwischen Aufrufen zustandslos.

Streaming-Antworten

Ohne Streaming wartest du auf die vollständige Antwort. Mit stream=True gibt die Funktion einen Generator zurück und du gibst die Teile aus, sobald sie eintreffen:

Copyimport ollama

for part in ollama.chat(
    model="llama3",
    messages=[{"role": "user", "content": "Explain recursion with a cooking analogy."}],
    stream=True,
):
    print(part["message"]["content"], end="", flush=True)

Jeder Teil enthält ein kleines message.content. Der letzte Teil hat done auf true gesetzt und enthält Zeitangaben sowie Token-Anzahlen. Für Web-Apps sendest du diese Teile über Server-Sent-Events oder ein WebSocket an den Browser.

Fehler, die du tatsächlich siehst

Zwei Fehlerquellen decken die meisten Anfängerprobleme ab.

Copyimport ollama

try:
    ollama.chat(model="llama3", messages=[{"role": "user", "content": "hi"}])
except ollama.ResponseError as exc:
    if exc.status_code == 404:
        print("Model missing. Run: ollama pull llama3")
    else:
        raise
except ConnectionError:
    print("Cannot reach Ollama. Is the server running on port 11434?")

Ein 404 von ResponseError bedeutet, dass der Modellname nicht mit einem von dir gezogenen Modell übereinstimmt. Die Namen enthalten Tags, daher sind llama3 und llama3:70b verschiedene Modelle. Ein Verbindungsfehler bedeutet, dass der Server nicht läuft oder du dich in einem Container befindest, in dem localhost auf den Container und nicht auf den Host verweist. In diesem Fall übergib einen Client mit dem richtigen Host: ollama.Client(host="http://host.docker.internal:11434").

Weitere Muster findest du in häufigen Ollama-API-Fehler.

Dasselbe Programm, gehosteter Endpunkt

Lokale Modelle sind durch deinen Speicher und deine Geschwindigkeit begrenzt. Wenn ein Skript auf einem Server ausgeführt werden muss, viele parallele Aufgaben bearbeiten muss oder ein größeres Kontextfenster benötigt, ist ein gehosteter Endpunkt einfacher. Der Trick besteht darin, das Programm gegen die OpenAI SDK zu schreiben und Basis-URL, Schlüssel und Modell als Konfiguration zu behandeln:

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.ollamansfw.com/v1"),
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt, history=None):
    messages = (history or []) + [{"role": "user", "content": prompt}]
    out = ""
    for chunk in client.chat.completions.create(model=MODEL, messages=messages, stream=True):
        if chunk.choices and chunk.choices[0].delta.content:
            piece = chunk.choices[0].delta.content
            out += piece
            print(piece, end="", flush=True)
    return out

ask("Explain recursion with a cooking analogy.")

Für lokales Ollama setze LLM_BASE_URL=http://localhost:11434/v1, LLM_API_KEY=ollama (dort wird jede nicht-leere Zeichenkette akzeptiert) und LLM_MODEL=llama3. Für die gehostete API verwende die oben genannten Standards, deinen echten Schlüssel und das Modell uncensored. Nichts anderes im Code ändert sich.

Hole dir einen Schlüssel auf der API-Schlüsselseite. Neue Konten können mit einem Klick ein $0,50 Trial-Guthaben beanspruchen, ohne Zahlungspflicht, gültig für 7 Tage. Das Modell ist ein Open-Weight-Modell eines unabhängigen Anbieters, das darauf abgestimmt ist, ohne Inhaltsfilter für die rechtmäßige Nutzung durch Erwachsene zu antworten. Es ist nur Text und keine offizielle API eines großen Labors.

Viele Prompts parallel ausführen

Ein lokales Modell auf einem Rechner bearbeitet normalerweise eine Anfrage nach der anderen, daher sind Schleifen sequenziell. Ein gehosteter Endpunkt ermöglicht Parallelität, was Batch-Arbeit deutlich beschleunigt. Halte die Anzahl der Worker unter dem Limit deines Schlüssels: 8 parallele Anfragen für einen Vollschlüssel, 2 für einen Trial-Schlüssel.

Copyfrom concurrent.futures import ThreadPoolExecutor
from openai import OpenAI

client = OpenAI(base_url="https://api.ollamansfw.com/v1", api_key="YOUR_KEY")

def summarize(text):
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Summarize in one line: " + text}],
        max_tokens=60,
    )
    return r.choices[0].message.content

docs = ["first text", "second text", "third text"]
with ThreadPoolExecutor(max_workers=6) as pool:
    results = list(pool.map(summarize, docs))
print(results)

Sechs Worker lassen Spielraum unter dem Limit von 8. Wenn ein Worker einen 429-Fehler erhält, wiederholt die OpenAI SDK standardmäßig ein paar Mal, aber füge deine eigene Backoff-Logik für lange Läufe hinzu. Denke auch daran, dass jede gestreamte Anfrage ihren Slot bis zum Ende des Streams belegt, also vermische keinen langen Streaming-Chat und einen großen Batch auf demselben Trial-Schlüssel.

Unterschiede, auf die du dich vorbereiten solltest

• Keine lokal-only-Optionen. num_ctx und keep_alive haben auf der gehosteten Seite keine Bedeutung. Das Kontextfenster beträgt 100.000 Token, Prompt und Completion zusammen.
• Ratenlimits. Ein Vollschlüssel erlaubt 8 parallele Anfragen und 300 Anfragen pro Minute; ein Trial-Schlüssel erlaubt 2 und 60. Darüber hinaus erhältst du einen 429-Fehler mit rate_limited oder concurrency. Wiederhole nach einer Pause; bei vorübergehender Überlastung enthält die Antwort Retry-After: 5.
• Kosten. Input kostet $0,15 pro 1M Token und Output kostet $0,50 pro 1M. Ein Skript, das 2.000 Prompts mit 600 Input- und 400 Output-Token sendet, gibt 2.000 x (600 x $0,15 + 400 x $0,50) / 1M = 2.000 x $0,00029 = $0,58 aus.
• Abrechnung. Prepaid-Guthaben, von $20 bis $500, bezahlt mit Krypto (USDT auf TRC20 oder USDC auf Base). Fehlgeschlagene oder verweigerte Anfragen werden nicht berechnet.

Für einen direkten Vergleich der Endpunkte lies unsere API-Preisanmerkung oder die Dokumentation.

Weitere Anleitungen

• Ollama-API vs. OpenAI-API: Endpunkte und Code
• So nutzt du Ollama mit einer GUI (und einem gehosteten Fallback)