API REST de Ollama

Qué cubre este artículo sobre la API REST de Ollama

• Los endpoints disponibles en Ollama.
• Cómo generar texto, chatear y crear embeddings.
• Diferencia entre la API nativa y la compatible con OpenAI.
• Ejemplos con cURL y Python.
• Consejos para integración y resolución de problemas.

Introducción: API REST de Ollama

Ollama ofrece una potente API REST que permite a aplicaciones externas y agentes acceder a modelos locales. La API está disponible en dos variantes: la API nativa de Ollama y un endpoint compatible con OpenAI. Ambas opciones facilitan la integración de Ollama en herramientas existentes, scripts y frameworks de agentes.

Este artículo muestra los principales endpoints, ejemplos y trampa comunes que encontrarás en el camino.

Conceptos clave

• Endpoint: ruta URL de la API.
• Generate: generación de texto única a partir de un prompt.
• Chat: conversación multiturn con mensajes.
• Embedding: conversión de texto a vector.
• Streaming: la respuesta se envía token por token.
• Compatible con OpenAI: el endpoint sigue el esquema de OpenAI.
• Model: nombre del modelo de lenguaje cargado.

Fundamentos de la API

La API escucha por defecto en:

http://localhost:11434

Para el endpoint compatible con OpenAI, añade /v1:

http://localhost:11434/v1

Obtener modelos disponibles

curl http://localhost:11434/api/tags

Respuesta:

{
  "models": [
    {
      "name": "llama3.1:latest",
      "model": "llama3.1:latest",
      "size": 4928300400,
      "parameter_size": "8.0B"
    }
  ]
}

Generar texto

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.1",
  "prompt": "Explica la API REST de Ollama en tres oraciones.",
  "stream": false
}'

Respuesta:

{
  "model": "llama3.1",
  "response": "La API REST de Ollama permite...",
  "done": true
}

Endpoint de chat

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.1",
  "messages": [
    {"role": "system", "content": "Eres un asistente útil."},
    {"role": "user", "content": "¿Qué es la API REST de Ollama?"}
  ],
  "stream": false
}'

Respuesta:

{
  "model": "llama3.1",
  "message": {
    "role": "assistant",
    "content": "La API REST de Ollama es..."
  },
  "done": true
}

Embeddings

curl http://localhost:11434/api/embed -d '{
  "model": "nomic-embed-text",
  "input": "Este es un texto de ejemplo."
}'

Respuesta:

{
  "model": "nomic-embed-text",
  "embeddings": [[0.12, -0.34, 0.56, ...]]
}

Endpoint compatible con OpenAI

Muchas herramientas y SDKs esperan el esquema de OpenAI. Ollama proporciona:

http://localhost:11434/v1/chat/completions

Ejemplo:

curl http://localhost:11434/v1/chat/completions -H "Content-Type: application/json" -d '{
  "model": "llama3.1",
  "messages": [
    {"role": "user", "content": "Hola Ollama."}
  ],
  "temperature": 0.7
}'

Ejemplo en Python

import requests

url = "http://localhost:11434/api/chat"
payload = {
    "model": "llama3.1",
    "messages": [
        {"role": "user", "content": "Explica las APIs REST."}
    ],
    "stream": False
}

resp = requests.post(url, json=payload)
print(resp.json()["message"]["content"])

Streaming

Para un streaming real, establece stream en true y procesa las líneas recibidas:

import requests
import json

url = "http://localhost:11434/api/chat"
payload = {
    "model": "llama3.1",
    "messages": [{"role": "user", "content": "Cuéntame un chiste."}],
    "stream": True
}

resp = requests.post(url, json=payload, stream=True)
for line in resp.iter_lines():
    if line:
        data = json.loads(line)
        print(data.get("message", {}).get("content", ""), end="")

Parámetros

Parámetros importantes:

• temperature: creatividad.
• top_p: nucleus sampling.
• top_k: limitación de tokens top-k.
• num_predict: número máximo de tokens.
• num_ctx: longitud del contexto.
• repeat_penalty: penalización por repetición.
• seed: reproducibilidad.

Acceso desde la red

Por defecto, Ollama escucha solo en 127.0.0.1. Para permitir acceso desde la red, establece:

export OLLAMA_HOST=0.0.0.0:11434

En Docker:

-e OLLAMA_HOST=0.0.0.0:11434

Importante: Ollama no ofrece autenticación propia. Asegura el acceso mediante firewall o VPN.

Integración en otras herramientas

• Open WebUI: OLLAMA_BASE_URL=http://localhost:11434
• OpenClaw: endpoint nativo http://localhost:11434, no /v1.
• LangChain: clases Ollama u ChatOllama.
• Continue.dev: endpoint http://localhost:11434/v1 con API key ollama.

Trampas comunes

• Endpoint incorrecto: OpenClaw necesita /api, no /v1.
• Modelo no cargado: ejecuta ollama pull antes.
• Memoria insuficiente: el modelo no carga o se interrumpe.
• No procesar streaming: stream: true entrega múltiples líneas JSON.
• Falta acceso a la red: establece OLLAMA_HOST y verifica el firewall.
• El cliente OpenAI rechaza la conexión: ingresa API key ollama u sk-ollama.

Enlaces e información adicional

• BotServ.de Funciones de Ollama
• BotServ.de Configurar Ollama
• BotServ.de Administración de Open WebUI
• BotServ.de Gestionar Ollama en Open WebUI

FAQ: API REST de Ollama

¿Cuál es el endpoint correcto? Para clientes puros de Ollama usa /api/chat o /api/generate. Para herramientas compatibles con OpenAI usa /v1/chat/completions.

¿Necesito una clave API? No, Ollama no autentica. Para herramientas externas, algunos ingresan ollama como clave.

¿Puedo usar múltiples modelos simultáneamente? Sí, pero Ollama solo mantiene un modelo en memoria en cada momento, el que se está usando actualmente.

¿Cómo obtengo embeddings? A través de /api/embed con un modelo de embedding como nomic-embed-text.

¿Es posible el streaming? Sí, establece stream: true y procesa las líneas entrantes.

Fuentes y lecturas adicionales

• Ollama API Docs: https://github.com/ollama/ollama/blob/main/docs/api.md
• OpenAI API Reference: https://platform.openai.com/docs/api-reference

Resumen: API REST de Ollama

La API REST de Ollama permite acceder a modelos locales a través de HTTP. La API nativa ofrece generate, chat e embed, mientras que el endpoint /v1 proporciona compatibilidad con clientes OpenAI. Si utilizas correctamente el endpoint, los nombres de modelos, streaming y parámetros, puedes integrar Ollama sin fricciones en Open WebUI, agentes, sistemas RAG y tus propios scripts. Es especialmente importante entender la diferencia entre el endpoint nativo y el compatible con OpenAI.