Ollama API in Python, daarna een gehost endpoint

Stel de Python-client in

Installeer eerst Ollama zelf, start het en haal een model op vanaf de terminal: ollama pull llama3. De server luistert op http://localhost:11434. Installeer vervolgens het Python-pakket in een virtuele omgeving:

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

Het ollama-pakket communiceert met de native routes van Ollama onder /api. Het openai-pakket is voor de tweede helft van deze tutorial, waar het doel een gehost endpoint is. Als je liever een visuele tool gebruikt voordat je gaat coderen, zie de notities over Ollama gebruiken met een GUI.

Controleer de installatie door ollama list uit te voeren in de terminal. Als je model daar verschijnt, zal Python het vinden. Als je later een verbindingsfout krijgt, draait de server waarschijnlijk niet.

Je eerste chatverzoek

Dit zijn de basisprincipes van de ollama api python in één snippet: een systeembericht, een gebruikersbericht en twee opties.

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"])

Het antwoord is een dictionary-achtig object; de tekst staat in message.content. In options kun je generatieparameters instellen. temperature bepaalt de willekeurigheid en num_ctx stelt de contextlengte in voor dat verzoek. Ollama gebruikt standaard een vrij kleine context, tenzij je deze verhoogt, wat verrassend is voor mensen die lange documenten plakken en antwoorden krijgen die het begin negeren.

Voor multi-turn chat houd je een lijst van berichten bij en voeg je elk antwoord zelf toe. Ollama, net als de meeste chat-API's, is stateless tussen verzoeken.

Streaming-antwoorden

Zonder streaming wacht je op het volledige antwoord. Met stream=True retourneert de functie een generator en print je stukken zoals ze binnenkomen:

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)

Elk onderdeel bevat een kleine message.content. Het laatste onderdeel heeft done ingesteld op true en bevat timing en token-tellingen. Voor webapps stuur je deze stukken door naar de browser via server-sent events of een websocket.

Fouten die je echt zult zien

Twee soorten fouten dekken de meeste beginnende problemen.

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?")

Een 404 van ResponseError betekent dat de modelnaam niet overeenkomt met iets dat je hebt opgehaald. Namen bevatten tags, dus llama3 en llama3:70b zijn verschillende modellen. Een verbindingsfout betekent dat de server niet draait, of dat je binnen een container zit waar localhost naar de container wijst, niet naar de host. Geef in dat geval een client met de juiste host door: ollama.Client(host="http://host.docker.internal:11434").

Meer patronen zijn verzameld in veelvoorkomende Ollama API fouten.

Zelfde programma, gehost endpoint

Lokale modellen zijn beperkt door je geheugen en snelheid. Wanneer een script op een server moet draaien, veel gelijktijdige taken moet afhandelen of een groter contextvenster nodig heeft, is een gehost endpoint makkelijker. De truc is om het programma te schrijven tegen de OpenAI SDK en base URL, sleutel en model als configuratie te behandelen:

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

Voor lokale Ollama stel je LLM_BASE_URL=http://localhost:11434/v1, LLM_API_KEY=ollama (elke niet-lege string wordt daar geaccepteerd) en LLM_MODEL=llama3 in. Voor de gehoste API gebruik je de standaardwaarden hierboven, je echte sleutel en model uncensored. Niets anders in de code verandert.

Haal een sleutel op op de API-sleutelpagina. Nieuwe accounts kunnen met één klik $0,50 proeftegoed claimen zonder betaling, geldig voor 7 dagen. Het model is een open-weight model van een onafhankelijke provider, afgestemd op antwoorden zonder inhoudelijke weigeringen voor wettelijk volwassen gebruik. Het is alleen tekst en geen officiële API van een groot lab.

Veel prompts parallel uitvoeren

Een lokaal model op één machine verwerkt meestal één request tegelijk, dus loops zijn sequentieel. Een gehost endpoint staat concurrency toe, wat batch werk veel sneller maakt. Houd het aantal workers onder de limiet van je sleutel: 8 gelijktijdige requests voor een volledige sleutel, 2 voor een trial sleutel.

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)

Zes workers laten marge onder de limiet van 8. Als een worker een 429 krijgt, probeert de OpenAI SDK standaard twee keer opnieuw, maar voeg je eigen backoff toe voor lange runs. Onthoud ook dat elke gestreamde request zijn slot vasthoudt tot de stream eindigt, dus meng geen lange streaming chat en grote batch op dezelfde trial-sleutel.

Verschillen om op te anticiperen

• Geen opties die alleen lokaal werken. num_ctx en keep_alive hebben geen betekenis aan de gehost kant. Het contextvenster is 100.000 tokens, prompt en completion samen.
• Snelheidslimieten. Een volledige sleutel staat 8 gelijktijdige requests en 300 requests per minuut toe; een trial-sleutel staat 2 en 60 toe. Daarboven krijg je 429 met rate_limited of concurrency. Probeer het opnieuw na een pauze; bij tijdelijke overbelasting draagt de response Retry-After: 5.
• Kosten. Invoer is $0,15 per 1M tokens en uitvoer is $0,50 per 1M. Een script dat 2.000 prompts stuurt van 600 invoer en 400 uitvoer tokens kost 2.000 x (600 x $0,15 + 400 x $0,50) / 1M = 2.000 x $0,00029 = $0,58.
• Facturatie. Vooruitbetaald tegoed, van $20 tot $500, betaald met crypto (USDT op TRC20 of USDC op Base). Mislukte of geweigerde requests worden niet in rekening gebracht.

Voor een zij-aan-zij vergelijking van endpoints, lees onze API prijsnotitie of de docs.

Meer handleidingen

• Ollama API vs OpenAI API: Endpoints en Code
• Hoe Ollama te gebruiken met een GUI (en een gehoste fallback)