Biblioteca de Python de Ollama: primeros pasos con LLMs en local

Las APIs de LLM en la nube son potentes, pero implican concesiones: precios por uso, límites de tasa y la incertidumbre constante sobre dónde se procesan tus datos. Para quienes desarrollan con datos sensibles o hacen mucha experimentación, estas restricciones pronto se convierten en fricción.

Ahí es donde brillan los enfoques local‑first. La biblioteca de Python de Ollama elimina esa fricción al permitirte ejecutar modelos de lenguaje grandes en tu máquina, interactuando con ellos con código limpio y nativo de Python. Así mantienes el control total sobre rendimiento, coste y privacidad.

En este artículo, te guiaré por toda la API de la biblioteca de Python de Ollama, desde la generación de texto con generate() hasta llamadas a herramientas y modelos de visión.

También te recomiendo revisar nuestros últimos tutoriales de Ollama:

• Tutorial de Gemma 4: crea un agente local de IA para programar con Gradio y Ollama
• Tutorial de Qwen 3.5 Small: genera juegos a partir de vídeos con Ollama
• Usar OpenClaw con Ollama: construye un analista de datos local
• Usar Claude Code con modelos locales de Ollama

Requisitos previos para ejecutar Ollama con Python

Antes de empezar, asegúrate de tener lo siguiente configurado en tu equipo:

• Python 3.8 o superior

• Ollama descargado desde su web, instalado y en ejecución (ollama serve)

• Al menos un modelo descargado (p. ej., ollama pull llama3.2)

Estos requisitos importan porque el SDK de Python es solo un cliente; la inferencia real ocurre en el runtime de Ollama. Si el runtime no está disponible o no hay un modelo adecuado, las llamadas fallarán.

También puedes plantearte usar Docker con Ollama para mantener la consistencia entre versiones.

¿Qué es la biblioteca de Python de Ollama?

La biblioteca de Python de Ollama es el SDK oficial que envuelve la API REST de Ollama en una interfaz simple y «pythónica». En otras palabras, convierte peticiones HTTP de bajo nivel y cargas útiles JSON en funciones de Python de alto nivel para que te centres en la intención y no en los detalles de transporte.

A medida que tu aplicación crece, esta abstracción evita construir peticiones repetitivas, estandariza el manejo de respuestas y centraliza la gestión de errores en un único lugar.

Por comparación, una petición en crudo podría ser así:

import requests

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

Funciona, pero enseguida se vuelve verboso y propenso a errores. Con el SDK, la misma tarea queda en:

import ollama

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

Cómo se comunica la biblioteca con el servidor de Ollama

Bajo el capó, cada llamada del SDK se convierte en una petición HTTP al servidor de Ollama en http://localhost:11434. Tu script de Python actúa como cliente, mientras que el runtime de Ollama actúa como servidor que aloja y ejecuta los modelos.

Esta separación es clave porque permite ejecutar el modelo como un servicio dedicado, lo que hace más eficiente la gestión de recursos (CPU/GPU) y posibilita que varias aplicaciones compartan la misma instancia del modelo.

Si necesitas conectar con otra máquina, puedes configurar un cliente personalizado:

from ollama import Client

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

Instalación y configuración de la biblioteca

La instalación es directa y requiere dependencias mínimas:

pip install ollama

Tras instalar, es buena práctica verificar la conectividad listando los modelos disponibles.

Así confirmas que tu entorno de Python, el SDK y el runtime de Ollama están correctamente conectados.

Para ello, ejecuta lo siguiente:

import ollama

print(ollama.list())

Generación de texto con generate()

La función generate() está pensada para tareas «sin estado», es decir, cada petición se gestiona de forma independiente sin memoria de interacciones previas. Es ideal para tareas como resumir, reescribir o generar código.

Como no se conserva contexto, la calidad del resultado depende por completo de lo claro que esté el prompt.

Generación básica de texto

El siguiente ejemplo muestra el flujo más simple: envía un prompt, recibe una respuesta y extrae el texto generado.

import ollama

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

print(response['response'])

La respuesta también incluye metadatos como tiempo de ejecución y conteos de tokens, útiles para optimizar el rendimiento.

Personalizar la salida con parámetros

El comportamiento de generación se ajusta con parámetros de muestreo, que controlan cómo selecciona tokens el modelo.

Temperaturas bajas producen resultados más deterministas; valores altos introducen más variabilidad. Puedes usar parámetros como top_p y num_predict para afinar la diversidad y la longitud de la salida.

Estos son algunos parámetros importantes que puedes utilizar:

Aquí tienes un ejemplo del uso de los parámetros top_p, temperature y 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
    }
)

Crear conversaciones con chat()

A diferencia de generate(), la API chat() admite interacciones con estado trabajando con una secuencia de mensajes. Así el modelo mantiene contexto a lo largo de varios turnos.

Cada mensaje incluye un rol, como user, assistant o system, que ayuda a estructurar la conversación.

Peticiones de chat de un solo turno

Incluso una interacción de un solo turno usa el formato de mensajes, lo que sienta las bases para conversaciones más complejas.

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

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

Mantener el contexto en múltiples turnos

Para mantener el contexto, debes almacenar y reenviar explícitamente el historial completo de la conversación en cada petición. Así controlas por completo qué recuerda el modelo.

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)

Usar system prompts para dar forma al comportamiento

Un system prompt define de antemano el comportamiento del modelo, como el tono, las restricciones o el 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 y soporte asíncrono en la biblioteca de Python de Ollama

En aplicaciones interactivas, la capacidad de respuesta es tan importante como la corrección. Ollama admite streaming y ejecución asíncrona para mejorar el rendimiento y la experiencia de usuario.

Respuestas en streaming en tiempo real

El streaming te permite procesar la salida de forma incremental según se genera, en lugar de esperar a la respuesta completa.

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

Usar AsyncClient en aplicaciones async

La ejecución asíncrona permite a tu aplicación gestionar varias peticiones en paralelo sin bloquear. Necesitarás la biblioteca asyncio de Python para implementarlo.

Veamos un ejemplo:

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())

Gestión de modelos de Ollama desde Python

El SDK de Ollama también ofrece herramientas para gestionar modelos de forma programática, especialmente útil en entornos automatizados.

Listar e inspeccionar modelos locales

Puedes recuperar la lista de modelos disponibles e inspeccionar sus propiedades, como tamaño y configuración.

models = ollama.list()
print(models)

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

Descargar y eliminar modelos por código

Puedes descargar o eliminar modelos directamente desde Python, lo que facilita gestionar dependencias de forma dinámica.

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

Generar y usar embeddings con la biblioteca de Python de Ollama

Los embeddings representan texto como vectores numéricos que capturan el significado semántico. Así puedes comparar textos por similitud y no por coincidencia exacta.

Crear embeddings de texto

El siguiente ejemplo convierte texto en una representación vectorial que puedes usar para búsqueda o clustering.

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

embedding = response['embeddings'][0]

Construir una búsqueda básica por similitud

Una vez generados los embeddings, la similitud puede medirse con la similitud del coseno, que compara el ángulo entre vectores.

Aquí tienes un ejemplo sencillo de la función de búsqueda:

import numpy as np

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

Llamadas a herramientas y salida estructurada en la biblioteca de Python de Ollama

Para crear aplicaciones más avanzadas, a menudo los modelos necesitan interactuar con funciones externas o devolver datos estructurados.

Implementar llamadas a herramientas con funciones de Python

Las llamadas a herramientas permiten que el modelo invoque funciones de Python predefinidas según la intención del usuario.

Vamos a crear una función que use estas herramientas:

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

Obtener respuestas JSON estructuradas

Las salidas estructuradas garantizan respuestas consistentes y legibles por máquina, como JSON.

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

Avanzado: modelos de visión y Ollama Cloud en Python

Ollama admite modelos multimodales y ejecución en la nube para casos de uso más avanzados.

Enviar imágenes a modelos de visión

Los modelos de visión procesan texto e imágenes, permitiendo tareas como descripción de imágenes y análisis visual.

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

Ejecutar modelos en la nube desde Python

Para modelos más grandes que no pueden ejecutarse en local, Ollama Cloud ofrece inferencia alojada.

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'}
)

Gestión de errores: los fallos más comunes en Python con Ollama

Al crear aplicaciones reales, gestionar los errores de forma explícita evita fallos silenciosos y mejora la fiabilidad.

Manejar excepciones ResponseError

El SDK de Ollama lanza excepciones estructuradas para errores del servidor, lo que te permite inspeccionar qué salió mal.

import ollama

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

Depurar problemas de conexión y de modelos

Los problemas más habituales son: servidor no iniciado, modelos ausentes, memoria insuficiente o límites de contexto superados.

• Servidor no iniciado: Arranca con ollama serve

• Modelo no encontrado: Ejecuta ollama pull

• Falta de memoria: Usa modelos más pequeños o cuantización

• Problemas de contexto: Ajusta num_ctx

num_ctx controla el número máximo de tokens que el modelo puede «ver» a la vez, incluyendo:

• tu prompt
• instrucciones del sistema
• historial de conversación
• documentos recuperados (RAG)
• y los propios tokens generados por el modelo

Gestionar este parámetro ayudará a evitar que el LLM trunque contenido anterior (normalmente desde el inicio) o pierda instrucciones o datos importantes sin avisar.

Conclusiones

La biblioteca de Python de Ollama ofrece una interfaz completa para trabajar con LLMs locales y en la nube, desde la generación de texto hasta capacidades avanzadas como embeddings, llamadas a herramientas y entradas multimodales. Los LLMs se convierten en un servicio local contra el que puedes programar, probar y escalar como cualquier otro componente de tu stack.

En mi experiencia con Ollama, me ha parecido una buena alternativa cuando no quieres depender de LLMs en la nube. Por ejemplo, puedo usar modelos de código abierto con más libertad. Si también buscas más opciones para alternar entre modelos, Ollama es una excelente puerta de entrada para acceder a todo esto.

Si quieres profundizar en tus habilidades, te recomiendo nuestro curso Developing LLM Applications with LangChain o la certificación Associate AI Engineer for Developers.