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

Cloud-LLM-API’s zijn krachtig, maar ze hebben ook nadelen: afrekening op gebruik, snelheidslimieten en voortdurende onzekerheid over waar je data wordt verwerkt. Voor ontwikkelaars die met gevoelige data werken of veel experimenteren, kunnen deze beperkingen al snel voor frictie zorgen.

Hier springen local-first benaderingen eruit. De Ollama Python-bibliotheek haalt die frictie weg door grote taalmodellen lokaal te laten draaien terwijl je er via nette, Python-native code mee interacteert. 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 visiemodellen.

Ik raad je ook aan om onze andere recente Ollama-tutorials te bekijken:

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

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 van de website, geïnstalleerd en draaiend (ollama serve)

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

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

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 eenvoudige, Pythonic interface. Met andere woorden: het verandert low-level HTTP-verzoeken en JSON-payloads in high-level Python-functies, zodat je je kunt focussen op intentie in plaats van transportdetails.

Naarmate je applicatie groeit, haalt deze abstractie repetitieve requestconstructie weg, standaardiseert de afhandeling van responses en centraliseert foutafhandeling op één plek.

Ter vergelijking: een ruwe request kan er zo uitzien:

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:

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-request naar de Ollama-server op http://localhost:11434. Je Python-script fungeert als client, terwijl de Ollama-runtime als server optreedt die modellen host en uitvoert.

Die scheiding is belangrijk omdat het het model laat draaien als een toegewijde service, waardoor resourcebeheer (CPU/GPU) efficiënter wordt en meerdere applicaties dezelfde modelinstantie kunnen delen.

Als je met een andere machine moet verbinden, kun je een aangepaste 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

Installatie 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. 

Dit helpt je te bevestigen dat je Python-omgeving, SDK en Ollama-runtime allemaal correct verbonden zijn.

Voer daarvoor het volgende uit:

import ollama

print(ollama.list())

Tekst genereren met generate()

De functie generate() is ontworpen voor stateloze taken: elke request wordt onafhankelijk afgehandeld zonder geheugen van eerdere interacties. Dit maakt het ideaal voor taken zoals 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 eenvoudigste 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 uitvoeringstijd en tokenaantallen, wat handig is bij het optimaliseren van performance.

Output aanpassen met parameters

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

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

Hier zijn enkele 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
    }
)

Gesprekken bouwen met chat()

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

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

Single-turn chatverzoeken

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

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

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

Meerstapscontext behouden

Om context te behouden, sla je expliciet de volledige gespreksgeschiedenis op en stuur je die bij elke request opnieuw mee. Zo bepaal jij precies 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 vooraf 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 deze 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 requests 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 opvragen 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 programmatisch binnenhalen en verwijderen

Modellen kunnen rechtstreeks vanuit Python worden gedownload of verwijderd, waardoor je dependencies dynamisch makkelijker beheert.

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. Daarmee kun je teksten vergelijken op basis van gelijkenis in plaats van exacte bewoording.

Tekstembeddings maken

Het volgende voorbeeld zet tekst om in een vectorrepresentatie die kan worden gebruikt voor zoeken of clusteren.

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

embedding = response['embeddings'][0]

Een basis similariteitszoeker bouwen

Als embeddings eenmaal zijn gegenereerd, kun je similariteit meten met cosinus-similariteit, 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 interacteren of gestructureerde data teruggeven.

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 zulke 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 ophalen

Gestructureerde outputs zorgen ervoor dat responses consistent in een machineleesbaar formaat zoals JSON worden teruggegeven.

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

Geavanceerd: visiemodellen en Ollama Cloud in Python

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

Afbeeldingen naar visiemodellen sturen

Visiemodellen kunnen zowel tekst als afbeeldingen verwerken, wat taken mogelijk maakt zoals afbeeldingsbeschrijving en visuele analyse.

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

Cloudmodellen draaien vanuit Python

Voor grotere modellen die niet lokaal kunnen draaien, biedt Ollama Cloud gehoste inferentie. Je moet hiervoor inloggen bij Ollama Cloud.

ollama signin

Nadat je bent ingelogd, kun je zo chatten met cloud-gehoste modellen:

from ollama import Client
import os

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

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

Foutafhandeling van de meest voorkomende Ollama Python-valkuilen

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

ResponseError-excepties afhandelen

De Ollama SDK werpt 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, missende modellen, onvoldoende geheugen of overschreden contextlimieten.

• Server draait niet: Start met ollama serve

• Model niet gevonden: Voer ollama pull uit

• Te weinig geheugen: Gebruik kleinere modellen of kwantisatie

• Contextproblemen: Pas num_ctx aan

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

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

Door deze parameter te beheren voorkom je dat de LLM eerdergenoemde content (meestal vanaf het begin) afkapt of ongemerkt belangrijke instructies of data verliest.

Tot slot

De Ollama Python-bibliotheek biedt een complete interface voor het 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 als elk ander component in je stack.

Uit mijn eigen ervaring met Ollama heb ik het gevoel dat het een goed alternatief is zonder cloud-LLM’s te hoeven gebruiken. Zo kan ik opensourcemodellen vrijer inzetten. Als je ook meer opties zoekt om tussen modellen te wisselen, is Ollama een goede toegangspoort tot al dat aanbod.

Wil je je skills verdiepen, volg dan onze cursus Developing LLM Applications with LangChain of ga voor de Associate AI Engineer for Developers-certificering.