API de Ollama en Python, luego un endpoint alojado

Configura el cliente de Python

Instala primero Ollama, inícialo y extrae un modelo desde una terminal: ollama pull llama3. El servidor escucha en http://localhost:11434. Luego instala el paquete de Python en un entorno virtual:

Copypython -m venv .venv
source .venv/bin/activate
pip install ollama openai

El paquete ollama se comunica con las rutas nativas de Ollama bajo /api. El paquete openai es para la segunda parte de este tutorial, donde el objetivo es un endpoint alojado. Si prefieres una herramienta visual antes de programar, consulta las notas sobre el uso de Ollama con una GUI.

Verifica la instalación ejecutando ollama list en la terminal. Si tu modelo aparece allí, Python lo encontrará. Si obtienes un error de conexión más tarde, probablemente el servidor no se esté ejecutando.

Tu primera llamada de chat

Este es el básico de la API de Ollama en Python en un solo fragmento: un mensaje del sistema, un mensaje del usuario y dos opciones.

Copyimport ollama

resp = ollama.chat(
    model="llama3",
    messages=[
        {"role": "system", "content": "Answer in one short paragraph."},
        {"role": "user", "content": "What is a context window?"},
    ],
    options={"temperature": 0.4, "num_ctx": 8192},
)
print(resp["message"]["content"])

La respuesta es un objeto similar a un diccionario; el texto está en message.content. En options puedes configurar parámetros de generación. temperature controla la aleatoriedad y num_ctx establece la longitud del contexto para esa llamada. Ollama usa por defecto un contexto bastante pequeño a menos que lo aumentes, lo cual sorprende a quienes pegan documentos largos y obtienen respuestas que ignoran el inicio.

Para chat multironda, mantén una lista de mensajes y añade cada respuesta tú mismo. Ollama, como la mayoría de las APIs de chat, es sin estado entre llamadas.

Respuestas en streaming

Sin streaming esperas la respuesta completa. Con stream=True la función devuelve un generador y imprimes piezas a medida que llegan:

Copyimport ollama

for part in ollama.chat(
    model="llama3",
    messages=[{"role": "user", "content": "Explain recursion with a cooking analogy."}],
    stream=True,
):
    print(part["message"]["content"], end="", flush=True)

Cada parte contiene un pequeño message.content. La última parte tiene done establecido en true e incluye tiempos y recuentos de tokens. Para aplicaciones web, reenvía estas piezas al navegador mediante eventos enviados por el servidor o un websocket.

Errores que realmente verás

Dos fallos cubren la mayoría de los problemas de principiantes.

Copyimport ollama

try:
    ollama.chat(model="llama3", messages=[{"role": "user", "content": "hi"}])
except ollama.ResponseError as exc:
    if exc.status_code == 404:
        print("Model missing. Run: ollama pull llama3")
    else:
        raise
except ConnectionError:
    print("Cannot reach Ollama. Is the server running on port 11434?")

Un 404 de ResponseError significa que el nombre del modelo no coincide con algo que hayas extraído. Los nombres incluyen etiquetas, por lo que llama3 y llama3:70b son modelos diferentes. Un error de conexión significa que el servidor no está activo, o que estás dentro de un contenedor donde localhost apunta al contenedor, no al host. En ese caso pasa un cliente con el host correcto: ollama.Client(host="http://host.docker.internal:11434").

Más patrones se recopilan en errores comunes de la API de Ollama.

Mismo programa, endpoint alojado

Los modelos locales están limitados por tu memoria y velocidad. Cuando un script debe ejecutarse en un servidor, manejar muchos trabajos en paralelo o usar una ventana más grande, un endpoint alojado es más fácil. El truco es escribir el programa contra el SDK de OpenAI y tratar la URL base, la clave y el modelo como configuración:

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.ollamansfw.com/v1"),
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt, history=None):
    messages = (history or []) + [{"role": "user", "content": prompt}]
    out = ""
    for chunk in client.chat.completions.create(model=MODEL, messages=messages, stream=True):
        if chunk.choices and chunk.choices[0].delta.content:
            piece = chunk.choices[0].delta.content
            out += piece
            print(piece, end="", flush=True)
    return out

ask("Explain recursion with a cooking analogy.")

Para Ollama local, establece LLM_BASE_URL=http://localhost:11434/v1, LLM_API_KEY=ollama (se acepta cualquier cadena no vacía allí) y LLM_MODEL=llama3. Para la API alojada, usa los valores predeterminados anteriores, tu clave real y el modelo uncensored. Nada más en el código cambia.

Obtén una clave en la página de claves de API. Las cuentas nuevas pueden reclamar un crédito de prueba de $0,50 con un clic, sin pago, válido por 7 días. El modelo es un modelo de pesos abiertos de un proveedor independiente, ajustado para responder sin rechazos de contenido para uso adulto lícito. Es solo texto y no es una API oficial de ningún gran laboratorio.

Ejecutando muchos prompts en paralelo

Un modelo local en una máquina suele manejar una petición a la vez, por lo que los bucles son secuenciales. Un endpoint alojado permite concurrencia, lo que hace que el trabajo por lotes sea mucho más rápido. Mantén el recuento de trabajadores por debajo del límite de tu clave: 8 peticiones simultáneas para una clave completa, 2 para una clave de prueba.

Copyfrom concurrent.futures import ThreadPoolExecutor
from openai import OpenAI

client = OpenAI(base_url="https://api.ollamansfw.com/v1", api_key="YOUR_KEY")

def summarize(text):
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Summarize in one line: " + text}],
        max_tokens=60,
    )
    return r.choices[0].message.content

docs = ["first text", "second text", "third text"]
with ThreadPoolExecutor(max_workers=6) as pool:
    results = list(pool.map(summarize, docs))
print(results)

Seis workers dejan margen por debajo del límite de 8. Si un worker recibe un 429, el SDK de OpenAI reintenta un par de veces por defecto, pero añade tu propia lógica de backoff para ejecuciones largas. Recuerda también que cada petición en streaming ocupa su espacio hasta que finalice, así que no mezcles un chat largo en streaming con un lote grande en la misma clave de prueba.

Diferencias a planificar

• Sin opciones solo locales. num_ctx y keep_alive no tienen significado en el lado alojado. La ventana es de 100.000 tokens, prompt y completado juntos.
• Límites de tasa. Una clave completa permite 8 peticiones simultáneas y 300 peticiones por minuto; una clave de prueba permite 2 y 60. Más allá de eso obtienes 429 con rate_limited o concurrency. Reintenta después de una pausa; en sobrecarga temporal la respuesta lleva Retry-After: 5.
• Coste. La entrada es $0,15 por 1M de tokens y la salida es $0,50 por 1M. Un script que envía 2.000 prompts de 600 de entrada y 400 de salida gasta 2.000 x (600 x $0,15 + 400 x $0,50) / 1M = 2.000 x $0,00029 = $0,58.
• Facturación. Crédito prepago, desde $20 hasta $500, pagado con cripto (USDT en TRC20 o USDC en Base). Las peticiones fallidas o rechazadas no se cobran.

Para una comparación lado a lado de endpoints, lee nuestra nota de precios de API o la documentación.

Más guías

• API de Ollama vs API de OpenAI: Endpoints y Código
• Cómo usar Ollama con una GUI (y un respaldo alojado)