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

Las APIs en la nube de LLM son potentes, pero tienen contrapartidas: precios por uso, límites de peticiones y la incertidumbre constante sobre dónde se procesan tus datos. Para quienes trabajan con datos sensibles o hacen muchas pruebas, estas barreras pronto se vuelven un freno.

Aquí es donde destacan los enfoques local‑first. La biblioteca de Python de Ollama elimina esa fricción al permitirte ejecutar modelos de lenguaje grandes en tu equipo e interactuar con ellos con código Python limpio y nativo. Así ganas 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 las llamadas a herramientas y los modelos de visión.

También te recomiendo echar un vistazo a nuestros tutoriales más recientes de Ollama:

• Tutorial de Gemma 4: crea un agente de IA local para programar con Gradio y Ollama
• Tutorial de Qwen 3.5 Small Models: genera un Video‑to‑Game con Ollama
• Usar OpenClaw con Ollama: construyendo 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 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 coherencia de 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 sencilla y "pythónica". En otras palabras, convierte peticiones HTTP de bajo nivel y cargas 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 cómo se gestionan las respuestas y centraliza el manejo de errores.

Por comparación, una petición en bruto 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 verbosa y propensa a errores. Con el SDK, la misma tarea queda así:

import ollama

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

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

Internamente, 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, y el runtime de Ollama como servidor que aloja y ejecuta los modelos.

Esta separación es importante porque permite ejecutar el modelo como un servicio dedicado, gestionando mejor los recursos (CPU/GPU) y posibilitando que varias aplicaciones compartan la misma instancia del modelo.

Si necesitas conectarte a 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 sencilla y requiere pocas dependencias:

pip install ollama

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

Esto te ayuda a confirmar que tu entorno de Python, el SDK y el runtime de Ollama están correctamente conectados.

Para hacerlo, ejecuta lo siguiente:

import ollama

print(ollama.list())

Generar texto con generate()

La función generate() está pensada para tareas sin estado: cada petición se procesa de forma independiente, sin memoria de interacciones previas. Es ideal para tareas como resumir, reescritura o generación de código.

Como no se conserva contexto, la calidad de la salida depende totalmente de lo claro que esté escrito 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 el tiempo de ejecución y el recuento de tokens, útiles para optimizar el rendimiento.

Personalizar la salida con parámetros

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

Valores bajos de temperature producen salidas más deterministas, mientras que valores altos introducen más variabilidad. Puedes usar parámetros como top_p y num_predict para afinar la diversidad y la longitud.

Estos son algunos parámetros importantes que puedes usar:

Aquí tienes un ejemplo usando 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 el 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, sentando 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 contexto en varios turnos

Para mantener el contexto, guardas y reenvías explícitamente el historial completo de la conversación con cada petición. Así controlas 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 prompts de sistema para moldear el comportamiento

Un prompt de sistema sirve para definir 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 a medida que se genera, en vez 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 atender varias peticiones en paralelo sin bloqueo. Necesitarás usar la librería 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

Los modelos pueden descargarse o eliminarse 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 su significado. Permiten comparar textos por similitud en lugar de por coincidencia exacta.

Crear embeddings de texto

El siguiente ejemplo convierte un texto en una representación vectorial que puede usarse 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 por similitud básica

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 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 de inferencia en la nube para casos de uso más avanzados.

Enviar imágenes a modelos de visión

Los modelos de visión pueden procesar texto e imágenes, lo que habilita tareas como la descripción de imágenes y el 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. Requiere iniciar sesión en Ollama Cloud.

ollama signin

Después de iniciar sesión, puedes chatear con modelos alojados en la nube así:

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

Manejo de errores: errores más comunes en la biblioteca de Python de Ollama

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

Gestionar 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 comunes incluyen que el servidor no esté ejecutándose, modelos ausentes, memoria insuficiente o que se supere el límite de contexto.

• Servidor no iniciado: Arráncalo 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 la conversación
• documentos recuperados (RAG)
• y los propios tokens generados por el modelo

Gestionar este parámetro ayuda 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 en local y en la nube, desde la generación de texto hasta funciones 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 que es una buena opción para no depender siempre de LLMs en la nube. Por ejemplo, puedo usar modelos open source con más libertad. Si buscas más opciones para alternar entre modelos, Ollama es una buena puerta de entrada para acceder a todo esto.

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