Tutorial de Python con Ollama: conecta modelos con el paquete ollama y OpenAI SDK

Instalación

pip install ollama

Asegúrate primero de que el servicio de Ollama esté en ejecución y de haber descargado el modelo que quieras usar (por ejemplo, ollama pull qwen3:8b).

Conversación básica

from ollama import chat

response = chat(
    model="qwen3:8b",
    messages=[
        {"role": "system", "content": "Responde en español."},
        {"role": "user", "content": "Explica qué es el aprendizaje automático en tres puntos."},
    ],
)

print(response.message.content)

También puedes acceder al objeto de respuesta como si fuera un diccionario: response["message"]["content"].

Salida en streaming

Muestra el texto a medida que se genera:

from ollama import chat

stream = chat(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "Escribe un ejemplo de presentación personal de 100 palabras"}],
    stream=True,
)

for chunk in stream:
    print(chunk.message.content, end="", flush=True)
print()

Conversación con varios turnos: crea un chat en la terminal

El modelo no recuerda el historial por sí solo; debes guardar todos los mensajes de cada turno en una lista:

from ollama import chat

messages = [{"role": "system", "content": "Eres un asistente amable. Responde en español."}]

while True:
    user_input = input("Tú:").strip()
    if user_input in {"exit", "quit", "salir"}:
        break
    messages.append({"role": "user", "content": user_input})

    reply = ""
    print("AI：", end="", flush=True)
    for chunk in chat(model="qwen3:8b", messages=messages, stream=True):
        piece = chunk.message.content
        reply += piece
        print(piece, end="", flush=True)
    print()

    messages.append({"role": "assistant", "content": reply})

Cuanto más larga sea la conversación, más contenido se enviará y puede que se supere la longitud del contexto. En la práctica, puedes conservar solo los turnos más recientes o resumir la conversación anterior.

Parámetros y modo de razonamiento

response = chat(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "¿Cuál es la suma de los números del 1 al 100?"}],
    options={"temperature": 0.2, "num_ctx": 8192},
    think=True,
    keep_alive="30m",
)

print("Razonamiento:", response.message.thinking)
print("Respuesta:", response.message.content)

Leer imágenes

response = chat(
    model="gemma3",
    messages=[{
        "role": "user",
        "content": "¿Qué hay en esta imagen?",
        "images": ["./photo.jpg"],   # También puedes pasar bytes o una cadena base64
    }],
)
print(response.message.content)

Otras funciones

import ollama

ollama.generate(model="qwen3:8b", prompt="Presenta Taipéi en una frase")  # Generación única
ollama.list()                                               # Modelos descargados
ollama.ps()                                                 # Modelos cargados
ollama.pull("nomic-embed-text")                             # Descargar un modelo
ollama.show("qwen3:8b")                                     # Información del modelo
ollama.embed(model="nomic-embed-text", input="Hola")       # Embeddings de texto

Conectarse a otro host

from ollama import Client

client = Client(host="http://192.168.1.50:11434")
response = client.chat(model="qwen3:8b", messages=[{"role": "user", "content": "Hola"}])
print(response.message.content)

También puedes configurar la variable de entorno OLLAMA_HOST; la función chat() predeterminada la usará.

Modo asíncrono

Úsalo en frameworks asíncronos como FastAPI:

import asyncio
from ollama import AsyncClient


async def main():
    client = AsyncClient()
    response = await client.chat(
        model="qwen3:8b",
        messages=[{"role": "user", "content": "Hola"}],
    )
    print(response.message.content)


asyncio.run(main())

Manejo de errores

import ollama

try:
    ollama.chat(model="not-exist", messages=[{"role": "user", "content": "hi"}])
except ollama.ResponseError as e:
    print("Error:", e.error, e.status_code)
    if e.status_code == 404:
        print("El modelo no existe; ejecuta primero ollama pull")
except ConnectionError:
    print("No se puede conectar con Ollama; comprueba que el servicio esté en ejecución")

Usar OpenAI Python SDK

Si tu programa ya usa OpenAI SDK, solo tienes que cambiar base_url:

pip install openai

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",  # Es obligatorio, pero Ollama no lo comprueba
)

completion = client.chat.completions.create(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "Hola, preséntate"}],
)
print(completion.choices[0].message.content)

Así puedes cambiar el mismo programa entre modelos locales y API en la nube. Frameworks como LangChain y LlamaIndex también pueden conectarse a Ollama de la misma manera.

En la siguiente sección se explica cómo usar JavaScript / Node.js.

Actualizado 12 de octubre de 2026