SDK oficial de Ollama en Python

Instalación y requisitos

La librería oficial de Ollama para Python se publica en PyPI con el nombre ollama (pypi.org/project/ollama). Proporciona funciones y clases para llamar a la API REST de Ollama sin escribir peticiones HTTP a mano. Requiere Python 3.8+ y que el servidor de Ollama esté en ejecución (aplicación de escritorio o ollama serve) en http://localhost:11434 por defecto.

Instala con pip install ollama. Si usas un entorno virtual, actívalo antes. No confundas este paquete con ollama-python u otros wrappers no oficiales: el cliente mantenido por Ollama es solo ollama.

Tras la instalación, importas las funciones o el cliente y usas el mismo modelo que ya tienes descargado (por ejemplo ollama pull gemma3). La API del SDK refleja la API REST de Ollama: chat, generate y embeddings se invocan con nombres y parámetros alineados con los endpoints.

# Comprobar que el servidor responde (opcional)
import ollama
models = ollama.list()
print(models)

Si el servidor no está en marcha o no hay modelos, las llamadas fallarán. Para modelos en la nube (sufijo :cloud), necesitas tener configurada la autenticación con Ollama Cloud (API key o ollama signin) y, si aplica, un cliente con la URL y cabeceras adecuadas.

Chat desde Python

La función ollama.chat() corresponde al endpoint /api/chat: envías una lista de messages con role y content (por ejemplo user, assistant, system) y recibes la respuesta del modelo. Es la opción adecuada para conversaciones con historial o asistentes.

Ejemplo básico (respuesta completa, sin streaming):

from ollama import chat

response = chat(
    model="llama3.2",
    messages=[
        {"role": "system", "content": "Responde en una sola frase."},
        {"role": "user", "content": "¿Qué es un LLM?"},
    ],
)
print(response["message"]["content"])
# Alternativa: response.message.content si usas el objeto tipado

El valor devuelto incluye el mensaje del asistente en response["message"]["content"]. Para el siguiente turno, añades ese mensaje y el nuevo mensaje del usuario a messages y vuelves a llamar a chat().

Streaming: si pasas stream=True, chat() devuelve un generador que produce fragmentos de la respuesta. Así puedes mostrar el texto conforme se genera.

from ollama import chat

stream = chat(
    model="llama3.2",
    messages=[{"role": "user", "content": "Explica en dos líneas qué es Ollama."}],
    stream=True,
)
for chunk in stream:
    part = chunk.get("message", {}).get("content", "")
    print(part, end="", flush=True)
print()

Usa chat cuando necesites mantener contexto entre turnos (asistentes, chatbots). Para un solo prompt sin historial, generate es más directo.

Puedes pasar options (por ejemplo temperature, top_p, num_predict) en la llamada a chat() para ajustar la generación, igual que en la API REST.

Generate para un solo prompt

La función ollama.generate() equivale al endpoint /api/generate: envías un prompt único y el modelo devuelve la respuesta. No mantiene historial de mensajes, por lo que sirve para completar texto, traducir una frase o generar contenido a partir de un único input.

from ollama import generate

response = generate(
    model="llama3.2",
    prompt="Escribe un haiku sobre la programación.",
)
print(response["response"])

Con stream=True obtienes un generador de fragmentos (cada elemento tiene un campo response con el trozo de texto). Las options (temperature, top_p, num_predict, etc.) se pasan como argumentos adicionales en generate().

flowchart LR
  A[Código Python] --> B[ollama.chat / generate / embed]
  B --> C[httpx]
  C --> D[Servidor Ollama]
  D --> C
  C --> B
  B --> A

El SDK usa httpx por debajo. Las llamadas salen desde tu script hacia el servidor Ollama (local o la URL que configures) y la respuesta se devuelve a tu código.

Embeddings con embed()

Para obtener vectores (embeddings) de uno o varios textos, usa ollama.embed(). Corresponde a POST /api/embed y requiere un modelo de embeddings (por ejemplo nomic-embed-text), no un modelo de chat o generate.

Un solo texto:

from ollama import embed

result = embed(
    model="nomic-embed-text",
    input="El cielo es azul por la dispersión de Rayleigh.",
)
vector = result["embeddings"][0]
print(len(vector))

Varios textos en una llamada (útil para indexar párrafos o comparar similitud):

from ollama import embed

texts = [
    "Instalación de Ollama en Windows",
    "Cómo descargar modelos con ollama pull",
    "Recetas de cocina mediterránea",
]
result = embed(model="nomic-embed-text", input=texts)
for i, vec in enumerate(result["embeddings"]):
    print(f"Texto {i}: {len(vec)} dimensiones")

Usa siempre un modelo de embeddings para embed(). Los modelos de lenguaje (llama3.2, gemma3, etc.) no están pensados para producir embeddings de calidad, los vectores tienen dimensiones y semántica distintas.

Con estos vectores puedes construir flujos RAG o búsqueda semántica: indexar documentos, generar el embedding de la consulta del usuario y recuperar los fragmentos más similares antes de llamar a chat() o generate() con ese contexto.

Cliente personalizado y uso asíncrono

Por defecto las funciones de nivel módulo (chat, generate, embed) usan localhost:11434. Si tu servidor está en otra URL, usas cabeceras o despliegas en Ollama Cloud, puedes crear un Client (síncrono) o AsyncClient (asíncrono) y pasarle host y, si hace falta, headers.

Cliente síncrono:

from ollama import Client

client = Client(host="http://localhost:11434")
response = client.chat(
    model="llama3.2",
    messages=[{"role": "user", "content": "Hola."}],
)
print(response.message.content)

Los argumentos extra del constructor se pasan a httpx (timeouts, cabeceras, etc.), así que puedes configurar la conexión según tu entorno.

Cliente asíncrono: con AsyncClient las mismas operaciones son async y devuelven corrutinas. Útil en aplicaciones con asyncio (servidores web, bots, pipelines concurrentes).

import asyncio
from ollama import AsyncClient

async def main():
    client = AsyncClient()
    response = await client.chat(
        model="llama3.2",
        messages=[{"role": "user", "content": "¿Qué es Python?"}],
    )
    print(response.message.content)

asyncio.run(main())

Con stream=True en el cliente asíncrono obtienes un async generator: usas async for part in ... para consumir los fragmentos de la respuesta.

Errores: si el servidor devuelve un error (modelo inexistente, timeout, etc.), el SDK lanza ollama.ResponseError. Puedes capturarla y usar e.status_code y e.error para decidir si hacer ollama.pull(model) o notificar al usuario.

import ollama

try:
    response = ollama.chat(model="no-existe", messages=[{"role": "user", "content": "Hola"}])
except ollama.ResponseError as e:
    print("Error:", e.error)
    if e.status_code == 404:
        ollama.pull("no-existe")

Con el paquete ollama tienes chat, generate y embed listos para usar desde Python, con streaming, opciones de generación y la posibilidad de configurar Client o AsyncClient para servidores remotos o entornos asíncronos.