Ollama Python-bibliotheek: aan de slag met LLM’s lokaal

Cloud-LLM-API’s zijn krachtig, maar ze hebben hun keerzijden: prijs op basis van gebruik, snelheidslimieten en de voortdurende onzekerheid over waar je gegevens worden verwerkt. Voor developers die met gevoelige data werken of veel experimenteren, kan die beperking al snel wrijving opleveren.

Hier komen local-first-benaderingen om de hoek kijken. De Ollama Python-bibliotheek haalt die wrijving weg door grote taalmodellen lokaal te draaien, terwijl je er via heldere, Python-native code mee kunt communiceren. Zo houd je volledige controle over performance, kosten en privacy.

In dit artikel neem ik je mee door de complete Ollama Python-bibliotheek-API, van eenvoudige tekstgeneratie met generate() tot tool calling en vision-modellen.

Bekijk ook zeker onze andere recente Ollama-tutorials:

• Gemma 4-tutorial: een lokale AI-coding agent bouwen met Gradio en Ollama
• Qwen 3.5 Small Models-tutorial: bouw een video-naar-game-generator met Ollama
• OpenClaw gebruiken met Ollama: een lokale data-analist bouwen
• Claude Code gebruiken met lokale modellen in Ollama

Vereisten om Ollama met Python te draaien

Zorg voordat je begint dat je het volgende op je apparaat hebt ingesteld:

• Python 3.8 of hoger

• Ollama gedownload vanaf de website, geïnstalleerd en draaiend (ollama serve)

• Minstens één model gepulld (bijv. ollama pull llama3.2)

Deze vereisten zijn belangrijk omdat de Python SDK slechts een client is; de daadwerkelijke inferentie gebeurt in de Ollama-runtime. Als de runtime niet beschikbaar is of er geen geschikt model aanwezig is, mislukken aanroepen.

Overweeg ook om Docker met Ollama te gebruiken voor consistente versies.

Wat is de Ollama Python-bibliotheek?

De Ollama Python-bibliotheek is de officiële SDK die de Ollama REST API verpakt in een simpele, Pythonic interface. Met andere woorden: hij zet low-level HTTP-verzoeken en JSON-payloads om in high-level Python-functies, zodat je je kunt richten op de intentie in plaats van op de transportdetails.

Naarmate je applicatie groeit, haalt deze abstractie herhaalde request-constructies weg, standaardiseert hoe responses worden afgehandeld en centraliseert foutafhandeling op één plek.

Ter vergelijking: een ruwe aanvraag ziet er zo uit:

import requests

response = requests.post(
    "http://localhost:11434/api/generate",
    json={
        "model": "llama3.2",
        "prompt": "Explain recursion"
    }
)

Dit werkt, maar wordt al snel omslachtig en foutgevoelig. Met de SDK wordt dezelfde taak zo:

import ollama

response = ollama.generate(
    model='llama3.2',
    prompt='Explain recursion'
)

Hoe de bibliotheek met de Ollama-server communiceert

Onder de motorkap wordt elke SDK-aanroep een HTTP-verzoek naar de Ollama-server op http://localhost:11434. Je Python-script fungeert als client, terwijl de Ollama-runtime als server fungeert die modellen host en uitvoert.

Die scheiding is belangrijk omdat het model zo als dedicated service kan draaien, wat resourcemanagement (CPU/GPU) efficiënter maakt en het mogelijk maakt dat meerdere applicaties dezelfde modelinstantie delen.

Als je met een andere machine wilt verbinden, kun je een custom client configureren:

from ollama import Client

client = Client(host='http://remote-server:11434')
response = client.generate(model='llama3.2', prompt='Hello')

De bibliotheek installeren en configureren

Installeren is eenvoudig en vereist minimale dependencies:

pip install ollama

Na installatie is het verstandig om de connectiviteit te verifiëren door beschikbare modellen op te sommen. 

Zo controleer je of je Python-omgeving, SDK en Ollama-runtime allemaal correct verbonden zijn.

Voer hiervoor het volgende uit:

import ollama

print(ollama.list())

Tekst genereren met generate()

De functie generate() is ontworpen voor stateless taken, wat betekent dat elk verzoek onafhankelijk wordt afgehandeld zonder geheugen van eerdere interacties. Daardoor is het ideaal voor taken als samenvatten, herschrijven of codegeneratie.

Omdat er geen context behouden blijft, hangt de kwaliteit van de output volledig af van hoe duidelijk de prompt is geschreven.

Basis tekstgeneratie

Het volgende voorbeeld laat de simpelste workflow zien: stuur een prompt, ontvang een response en haal de gegenereerde tekst eruit.

import ollama

response = ollama.generate(
    model='llama3.2',
    prompt='Write a Python docstring for a function that calculates factorial'
)

print(response['response'])

De response bevat ook metadata zoals executietijd en tokenaantallen, wat handig is bij performance-optimalisatie.

Output aanpassen met parameters

Het generatiegedrag kan worden bijgestuurd met samplingparameters, die bepalen hoe het model tokens kiest.

Lagere temperature-waarden leveren meer deterministische outputs op, terwijl hogere waarden meer variatie introduceren. Met parameters zoals top_p en num_predict kun je de diversiteit en lengte verder verfijnen.

Hier zijn een paar belangrijke parameters die je kunt gebruiken: 

Hier is een voorbeeld van het gebruik van de parameters top_p, temperature en num_predict:

response = ollama.generate(
    model='llama3.2',
    prompt='Explain machine learning in one paragraph',
    options={
        'temperature': 0.2,
        'top_p': 0.9,
        'num_predict': 100
    }
)

Conversaties bouwen met chat()

In tegenstelling tot generate() ondersteunt de chat()-API stateful interacties door met een reeks berichten te werken. Zo kan het model context behouden over meerdere beurten.

Elk bericht heeft een rol, zoals user, assistant of system, wat helpt om het gesprek te structureren.

Chatverzoeken met één beurt

Zelfs een interactie met één beurt gebruikt het berichtenformaat, wat de basis legt voor complexere gesprekken.

response = ollama.chat(
    model='llama3.2',
    messages=[
        {'role': 'user', 'content': 'Explain Python decorators'}
    ]
)

print(response['message']['content'])

Context behouden over meerdere beurten

Om context te behouden, sla je expliciet de volledige gespreksgeschiedenis op en stuur je die bij elk verzoek opnieuw mee. Zo houd je volledige controle over wat het model onthoudt.

messages = [
    {'role': 'user', 'content': 'What is recursion?'}
]

response = ollama.chat(model='llama3.2', messages=messages)
messages.append(response['message'])

messages.append({'role': 'user', 'content': 'Give an example in Python'})
response = ollama.chat(model='llama3.2', messages=messages)

Systeemprompts gebruiken om gedrag te sturen

Een systeemprompt wordt gebruikt om het gedrag van het model van tevoren te bepalen, zoals toon, beperkingen of rol.

messages = [
    {'role': 'system', 'content': 'You are a strict Python code reviewer.'},
    {'role': 'user', 'content': 'Review this code: def add(a,b): return a+b'}
]

Streaming en async-ondersteuning in de Ollama Python-bibliotheek

Voor interactieve applicaties is responsiviteit net zo belangrijk als correctheid. Ollama ondersteunt zowel streaming als asynchrone uitvoering om performance en gebruikerservaring te verbeteren.

Responses in realtime streamen

Met streaming kun je output stapsgewijs verwerken terwijl die wordt gegenereerd, in plaats van te wachten op de volledige response.

for chunk in ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Write a story'}],
    stream=True
):
    print(chunk['message']['content'], end='', flush=True)

AsyncClient gebruiken voor async-applicaties

Asynchrone uitvoering laat je applicatie meerdere verzoeken gelijktijdig afhandelen zonder te blokkeren. Je hebt hiervoor de asyncio Python-bibliotheek nodig.

Kijk hieronder naar een voorbeeld:

import asyncio
from ollama import AsyncClient

async def main():
    client = AsyncClient()
    async for chunk in await client.chat(
        model='llama3.2',
        messages=[{'role': 'user', 'content': 'Explain async programming'}],
        stream=True
    ):
        print(chunk['message']['content'], end='')

asyncio.run(main())

Ollama-modellen beheren vanuit Python

De Ollama SDK biedt ook tools om modellen programmatisch te beheren, wat vooral handig is in geautomatiseerde omgevingen.

Lokale modellen lijst en inspecteren

Je kunt de lijst met beschikbare modellen ophalen en hun eigenschappen inspecteren, zoals grootte en configuratie.

models = ollama.list()
print(models)

info = ollama.show('llama3.2')
print(info)

Modellen programmatiche pullen en verwijderen

Modellen kunnen rechtstreeks vanuit Python worden gedownload of verwijderd, zodat je dependencies dynamisch kunt beheren.

ollama.pull('llama3.2')
ollama.delete('llama3.2')

Embeddings genereren en gebruiken met de Ollama Python-bibliotheek

Embeddings representeren tekst als numerieke vectoren die semantische betekenis vastleggen. Zo kun je teksten vergelijken op basis van overeenkomst in plaats van exacte bewoording.

Tekst-embeddings maken

Het volgende voorbeeld zet tekst om in een vectorrepresentatie die je kunt gebruiken voor search of clustering.

response = ollama.embed(
    model='nomic-embed-text',
    input='Ollama is a local LLM runtime'
)

embedding = response['embeddings'][0]

Een eenvoudige similariteitssearch bouwen

Als embeddings eenmaal gegenereerd zijn, kan similariteit worden gemeten met cosine similarity, die de hoek tussen vectoren vergelijkt.

Hier is een eenvoudig voorbeeld van de zoekfunctie:

import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

Tool calling en gestructureerde output in de Ollama Python-bibliotheek

Voor geavanceerdere applicaties moeten modellen vaak met externe functies interageren of gestructureerde data retourneren.

Tool calling implementeren met Python-functies

Met tool calling kan het model vooraf gedefinieerde Python-functies aanroepen op basis van de intentie van de gebruiker.

Laten we een functie maken die dergelijke tools gebruikt:

def get_weather(city: str) -> str:
    """Get current weather for a city"""
    return f"Weather in {city} is sunny"
response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'What is the weather in Paris?'}],
    tools=[get_weather]
)

Gestructureerde JSON-responses krijgen

Gestructureerde outputs zorgen ervoor dat responses consequent en machineleesbaar worden geretourneerd, zoals JSON.

response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Review: Great product, 5 stars!'}],
    format='json'
)

Gevorderd: vision-modellen en Ollama Cloud in Python

Ollama ondersteunt multimodale modellen en cloudgebaseerde inferentie voor geavanceerdere use-cases.

Afbeeldingen naar vision-modellen sturen

Vision-modellen kunnen zowel tekst als afbeeldingen verwerken, wat taken mogelijk maakt zoals beeldbeschrijving en visuele analyse.

response = ollama.chat(
    model='llama3.2-vision',
    messages=[{
        'role': 'user',
        'content': 'Describe this image',
        'images': ['image.jpg']
    }]
)

Cloudmodellen vanuit Python draaien

Voor grotere modellen die lokaal niet kunnen draaien, biedt Ollama Cloud gehoste inferentie.

ollama signin
ollama.chat(model='deepseek-v3.1:671b-cloud', messages=[...])
from ollama import Client

client = Client(
    host='https://ollama.com',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

Foutafhandeling van de meest voorkomende valkuilen in de Ollama Python-bibliotheek

Bij het bouwen van echte applicaties helpt expliciete foutafhandeling om stille fouten te voorkomen en de betrouwbaarheid te verbeteren.

ResponseError-excepties afhandelen

De Ollama SDK gooit gestructureerde excepties voor server-side fouten, zodat je kunt inspecteren wat er misging.

import ollama

try:
    ollama.generate(model='unknown', prompt='test')
except ollama.ResponseError as e:
    print(e.status_code, e.error)

Verbindings- en modelproblemen debuggen

Veelvoorkomende issues zijn: de server draait niet, ontbrekende modellen, onvoldoende geheugen of overschreden contextlimieten.

• Server draait niet: Start met ollama serve

• Model niet gevonden: Voer ollama pull uit

• Out of memory: Gebruik kleinere modellen of kwantisatie

• Contextproblemen: Pas num_ctx aan

num_ctx bepaalt het maximale aantal tokens dat het model tegelijk kan “zien”, waaronder:

• je prompt
• systeeminstructies
• gespreksgeschiedenis
• opgehaalde documenten (RAG)
• en de door het model zelf gegenereerde tokens 

Door deze parameter te managen voorkom je dat de LLM eerdere content afkapt (meestal aan het begin) of ongemerkt belangrijke instructies of data verliest.

Tot slot

De Ollama Python-bibliotheek biedt een complete interface voor werken met lokale en cloud-LLM’s, van eenvoudige tekstgeneratie tot geavanceerde mogelijkheden zoals embeddings, tool calling en multimodale input. LLM’s worden zo een lokale service waar je tegenaan kunt scripten, testen en schalen zoals elke andere component in je stack.

Uit mijn eigen ervaring met Ollama vind ik het een fijne optie om achter de hand te hebben zonder cloud-LLM’s te hoeven gebruiken. Zo kan ik bijvoorbeeld opensourcemodellen vrijer inzetten. Als je ook meer opties zoekt om tussen modellen te wisselen, is Ollama een goede gateway om overal toegang toe te krijgen.

Wil je je skills verder verdiepen? Volg dan onze cursus Developing LLM Applications with LangChain of behaal de certificering Associate AI Engineer for Developers.