API compatible con OpenAI en Ollama

Qué cubre este artículo sobre la API compatible con OpenAI de Ollama

• Qué endpoints ofrece Ollama en formato OpenAI.
• Cómo migrar código existente de OpenAI a Ollama.
• Diferencias y limitaciones.
• Ejemplos en Python y curl.
• Consejos para producción.

Introducción: API compatible con OpenAI en Ollama

Ollama no solo proporciona su propia API, sino también endpoints que siguen el formato de OpenAI. Esto resulta especialmente útil si ya has construido aplicaciones usando la librería cliente de OpenAI y deseas cambiar a una instancia local de Ollama. En lugar de api.openai.com, simplemente usas la dirección local de Ollama con la ruta /v1.

Este artículo muestra qué endpoints están disponibles, cómo funciona la migración y qué aspectos debes considerar.

Conceptos clave

• OpenAI API: Interfaz de OpenAI para chat, completiones e incrustaciones.
• Endpoint compatible con OpenAI: API que replica el esquema de OpenAI.
• /v1: Ruta en Ollama para solicitudes compatibles con OpenAI.
• Chat Completions: Conversaciones multiturno.
• Embeddings: Representaciones vectoriales de texto.
• API-Key: Clave de autenticación, en Ollama frecuentemente un marcador de posición.
• Base URL: Dirección de la API, por ejemplo http://localhost:11434/v1.

Endpoints disponibles

Ollama implementa muchos endpoints de OpenAI:

• POST /v1/chat/completions para chat.
• POST /v1/completions para completación de texto.
• POST /v1/embeddings para incrustaciones.
• GET /v1/models para listar modelos.

No todas las características de OpenAI como functions, tools o vision están disponibles en todos los modelos. Esto depende del modelo y la versión de Ollama.

Dirección del endpoint

http://localhost:11434/v1

Para Ollama en otra máquina:

http://ollama-server.local:11434/v1

Ejemplo en Python con cliente OpenAI

pip install openai

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"
)

response = client.chat.completions.create(
    model="llama3.1",
    messages=[
        {"role": "user", "content": "Explica Ollama en tres oraciones."}
    ]
)

print(response.choices[0].message.content)

Streaming

stream = client.chat.completions.create(
    model="llama3.1",
    messages=[{"role": "user", "content": "Cuéntame un chiste."}],
    stream=True
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Embeddings

response = client.embeddings.create(
    model="nomic-embed-text",
    input="Ollama es una plataforma de IA local."
)

print(response.data[0].embedding[:5])

Ejemplo con curl

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

Listar modelos

curl http://localhost:11434/v1/models

Diferencias respecto a la API real de OpenAI

• Autenticación: Ollama no requiere una clave API real, pero espera un valor cualquiera.
• Rate Limiting: Generalmente no existe en entornos locales.
• Nombres de modelos: Los nombres de modelos de OpenAI deben reemplazarse con modelos de Ollama.
• Tools y Functions: No todos los modelos soportan Function Calling.
• Vision: Solo ciertos modelos multimodales como llava procesan imágenes.
• Streaming: Generalmente está soportado.
• RAG: Debe implementarse en la aplicación.

Migrar una aplicación existente

Pasos:

1. Establecer base_url a http://localhost:11434/v1.
2. Establecer api_key a un valor arbitrario como "ollama".
3. Reemplazar nombres de modelos de OpenAI con nombres de Ollama.
4. Verificar características que Ollama aún no soporta.
5. Adaptar el manejo de errores, ya que los mensajes pueden diferir.

Cuándo es útil la API compatible con OpenAI

• Ejecutar código existente localmente sin cambios mayores.
• Hacer aplicaciones más amigables con la privacidad sin grandes refactorizaciones.
• Comparar entre OpenAI y modelos locales.
• Prototipos que luego irán a producción con Ollama.

Cuándo preferir la API nativa de Ollama

• Si necesitas utilizar todas las características de Ollama como Modelfiles, Pull, Delete y Generate.
• Si requieres extensiones específicas de Ollama.
• Si la aplicación se desarrolla originalmente para Ollama.

Seguridad

• Ollama sin autenticación por defecto.
• No expongas públicamente a internet.
• Si es necesario, coloca un proxy inverso con autenticación adelante.
• La clave API en el cliente no es un secreto real, solo un marcador de posición.
• Realiza la comunicación en la red local o a través de VPN/Tailscale.

Trampa comunes

• Puerto incorrecto: El estándar es 11434.
• Modelo no descargado: Ejecuta ollama pull llama3.1 antes.
• Falta api_key: El cliente de OpenAI necesita un valor, aunque Ollama lo ignore.
• Endpoints incorrectos: /v1/chat/completions, no /api/chat.
• Modelos de vision: No todos los modelos procesan imágenes.
• Tools no soportados: El modelo debe ser capaz de Function Calling.
• Problemas CORS: Las solicitudes del navegador a localhost pueden bloquearse.

Enlaces y recursos adicionales

• BotServ.de Ollama REST API
• BotServ.de Librerías de API Ollama
• BotServ.de Seguridad en Ollama
• BotServ.de Proxy inverso Docker

Preguntas frecuentes: API compatible con OpenAI en Ollama

¿Necesito una clave API real de OpenAI? No, cualquier valor como ollama es suficiente.

¿Están disponibles todas las características de OpenAI? No, tools, vision y ciertos parámetros dependen del modelo.

¿Puedo usar streaming? Sí, normalmente se soporta streaming via SSE.

¿Qué modelos funcionan? Todos los modelos locales de Ollama, accesibles por su nombre.

¿Es la API idéntica a la de OpenAI? Casi, pero hay limitaciones y mensajes de error diferentes.

Referencias y lecturas adicionales

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

Resumen: API compatible con OpenAI en Ollama

Los endpoints /v1 de Ollama permiten ejecutar código existente de OpenAI localmente casi sin cambios. Si estableces base_url a http://localhost:11434/v1 y la clave API a un marcador de posición, puedes usar modelos como llama3.1 o qwen2.5 en lugar de modelos de OpenAI. Lo importante es verificar la disponibilidad del modelo, las características faltantes como tools o vision, y asegurar tu instancia local de Ollama. Para características puras de Ollama, la API nativa sigue siendo la mejor opción, pero para migraciones y prototipos, la compatibilidad con OpenAI es muy práctica.