OrcaRouter Lite

Enrutador LLM autoalojado con red de seguridad gestionada. Compatible con OpenAI. BYOK. Workspace único. Streaming. model="auto".

model="auto" absorbe una caída de proveedor en tiempo real — sin cambiar el código. Cómo se grabó: DEMO.md.

Idiomas

• English
• 日本語
• 中文
• 한국어
• Deutsch
• Français
• Español
• Italiano
• Русский
• Português
• Tiếng Việt
• हिन्दी

OrcaRouter Lite es la edición open source de un solo workspace de OrcaRouter. Ejecútalo en tu portátil, intégralo en tu producto o usa directamente el api.orcarouter.ai alojado para la larga cola de modelos cuyas claves no quieres gestionar.

¿Por qué nosotros? LiteLLM es una librería; OpenRouter es de código cerrado y alojado; Ollama es solo local. Nosotros somos el servidor autoalojado con respaldo gestionado — una frase que ninguno de ellos puede decir.

Inicio rápido en 60 segundos

Dos formas de usar OrcaRouter:

Camino A — Autoalojado (BYOK)

Ejecuta Lite en tu propia máquina; trae tus propias claves de proveedor.

git clone https://github.com/Continuum-AI-Corp/OrcaRouter-Lite.git
cd OrcaRouter-Lite
cp .env.example .env
# añade al menos una: OPENAI_API_KEY=sk-...  (o ORCAROUTER_API_KEY=...)

docker compose up
# logs: ✓ orcarouter-lite ready. API key: sk-orca-abc123...

URL base: http://localhost:8000/v1. Usa la clave sk-orca-* que se imprime al arrancar.

Camino B — Alojado (requiere cuenta)

Sin clonar, sin docker. Regístrate, obtén una clave, apunta cualquier SDK de OpenAI al servicio alojado.

# 1. Regístrate en https://www.orcarouter.ai y copia tu clave sk-orca-*
# 2. Usa https://api.orcarouter.ai/v1 como URL base

Requiere cuenta. El servicio alojado se encarga del enrutamiento, la facturación y la larga cola de proveedores — facturado por token en tu cuenta de OrcaRouter. Consulta docs.orcarouter.ai/introduction.

Luego invócalo desde cualquier SDK de OpenAI

Los ejemplos de abajo usan la URL base de localhost del Camino A — cámbiala por https://api.orcarouter.ai/v1 si estás en el Camino B.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="sk-orca-abc123...",
)
r = client.chat.completions.create(
    model="auto",  # o "gpt-4o-mini", "claude-3-5-sonnet-latest", ...
    messages=[{"role": "user", "content": "Hello!"}],
)
print(r.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:8000/v1",
  apiKey: "sk-orca-abc123...",
});

const r = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(r.choices[0].message.content);

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-abc123..." \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'

Abre http://localhost:8000/ para el panel — proveedores, enrutamiento, analítica, claves (solo Camino A).

¿Por qué?

model="auto" — la característica estrella

Envía model="auto" y OrcaRouter elige el modelo más barato entre los proveedores configurados que cumpla los requisitos de capacidad de la solicitud (tools, vision, modo JSON). Sin reglas de enrutamiento manuales; sin acrobacias con rate-limits; sin optimización de costes con if x: ... en tu código.

client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "What's in this image?"},
        {"type": "image_url", "image_url": {"url": "data:..."}},
    ]}],
)
# → enruta al modelo más barato compatible con VISION que cubran tus claves

El modelo resuelto se expone de vuelta a quien llama a través de la cabecera de respuesta x-orca-resolved-model, para que puedas registrar/mostrar lo que realmente se usó.

Alojado como upstream (Lite + alojado)

¿Ya tienes Lite en marcha? Configura ORCAROUTER_API_KEY con tu sk-orca-* de www.orcarouter.ai y el alojado pasa a ser un proveedor más en la cadena de enrutamiento — cubriendo modelos que tus claves locales no tienen:

# .env
ORCAROUTER_API_KEY=sk-orca-hosted-abc...

Casos de uso:

• Probar antes de comprar — sin necesidad de claves de proveedor locales
• Logging local — el alojado gestiona el enrutamiento, Lite guarda filas de RequestLog para el panel
• Failover — los proveedores locales fallan, el alojado es la red de seguridad

Streaming

Formato SSE compatible con OpenAI con el framing estándar data: ... \n\n y un sentinel terminal [DONE] — drop-in para cualquier SDK que ya transmita desde OpenAI.

for chunk in client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True,
):
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Endpoints de protocolos nativos (Anthropic + Gemini)

Lite habla tres protocolos de entrada sobre un único pipeline de enrutamiento. Los clientes que solo hablan los formatos wire de Anthropic o Gemini se conectan directamente — sin necesidad de un SDK de OpenAI:

# Claude Code, apuntando a Lite (sin sufijo /v1 en la URL base)
export ANTHROPIC_BASE_URL=http://localhost:8000
export ANTHROPIC_API_KEY=sk-orca-...
claude

# SDK google-genai, apuntando a Lite
from google import genai
from google.genai.types import HttpOptions
client = genai.Client(api_key="sk-orca-...",
                      http_options=HttpOptions(base_url="http://localhost:8000"))
client.models.generate_content(model="auto", contents="Hello!")

Las solicitudes se traducen en la entrada hacia el mismo pipeline interno, así que model="auto", la caché de prompts entre proveedores (compartida entre protocolos), las estrategias de enrutamiento y el panel de analítica funcionan todos de forma idéntica. Guías: integrations/claude-code.md, integrations/gemini-sdk.md.

Catálogo de modelos

Se cargan más de 100 modelos de chat al arrancar desde la base de datos de precios mantenida por la comunidad de LiteLLM — sin lista de modelos que mantener manualmente. Cada entrada expone:

• id (p. ej. gpt-4o, claude-3-5-sonnet-latest)
• provider (mapeado a tus claves configuradas)
• Flags de capacidad: supports_tools, supports_vision, supports_json_mode
• Coste por token de entrada/salida (alimenta el widget de ahorro + model="auto")

GET /v1/models devuelve el catálogo en formato OpenAI.

Despliegue en otros sitios

Plataforma	One-click
Railway
Fly.io	fly launch --dockerfile Dockerfile
Render	Conecta el repo, directorio raíz = .
Docker pelado	docker run -p 8000:8000 -e OPENAI_API_KEY=... ghcr.io/... (imagen próximamente)

Qué incluye

• POST /v1/chat/completions — proxy + streaming + model="auto" + caché de prompts entre proveedores
• POST /v1/messages — ingress de la API Messages de Anthropic (Claude Code / los SDK de Anthropic se conectan directamente; + /count_tokens)
• POST /v1beta/models/{model}:generateContent — ingress de la API de Gemini (el SDK google-genai se conecta directamente; + :streamGenerateContent, GET /v1beta/models)
• GET /v1/models — catálogo de modelos descubrible (100+ modelos desde litellm.model_cost)
• GET/PUT/DELETE /v1/providers/{provider} — crea / lista / revoca claves de proveedor cifradas
• GET/PUT /v1/routing — cambia la estrategia (balanced / cheapest / fastest / quality)
• GET /v1/analytics/{recent,spend,latency,savings,unreachable} — analítica local, sin telemetría que salga de la caja
• GET /v1/hosted — estado del respaldo alojado (alimenta la tarjeta "Get $5 free credit" del panel)
• GET/POST/DELETE /v1/keys/... — lista / rota / revoca claves de API
• Panel de una sola página en /
• SQLite por defecto; Postgres opt-in vía DATABASE_URL; Redis opcional

Caché de prompts entre proveedores

Las solicitudes deterministas (temperature=0 o seed fijado) se sirven desde caché en repeticiones — funciona con todos los proveedores, no solo Anthropic. El backend es Redis si REDIS_URL está definido, en caso contrario un LRU en proceso. Los aciertos de caché se devuelven al instante con x-orca-cache: HIT y cuestan $0.

$ curl ... -d '{"model":"auto","messages":[...], "temperature": 0}' -i
HTTP/1.1 200 OK
x-orca-cache: MISS
x-orca-resolved-model: gpt-4o-mini

$ curl ...  # mismo payload otra vez
HTTP/1.1 200 OK
x-orca-cache: HIT          ← servido desde caché, sin llamada upstream

Widget de ahorros

GET /v1/analytics/savings?baseline=gpt-4o&days=7 informa de lo que tu tráfico habría costado con siempre-GPT-4 frente a lo que costó realmente. El panel lo muestra como una tarjeta.

Integraciones

Configuraciones drop-in para Claude Code, SDK de Gemini, Continue.dev, Aider, Cursor, LangChain, LlamaIndex, Vercel AI SDK y cualquier herramienta que hable el protocolo de Chat Completions de OpenAI — además de los formatos wire nativos de Anthropic y Gemini. Consulta integrations/.

Lo que deliberadamente no incluye

Esta es la edición de un solo workspace. Por diseño, sin:

• multi-tenant, RBAC, SSO
• facturación, monederos, puntos, programa de partners
• consola de administración, logs de auditoría, trust & safety
• despliegue multi-pod / Kubernetes
• email / Slack / webhooks para alertas

Para eso, consulta el producto alojado o la (próxima) edición Teams.

Pruebas

Construido con test-first. Cada comportamiento entregado aquí tuvo primero un test fallando.

pip install -e ".[dev]"
PYTHONPATH=. pytest -v
# 403 passed

Las filas de slice muestran los tests añadidos cuando se entregó cada slice; el total es la suite completa actual.

Arquitectura

app/
├── main.py             FastAPI factory + lifespan + SPA mount
├── config.py           Settings (~15 fields)
├── deps.py             DI helpers
├── seed.py             First-run bootstrap
├── auto_routing.py     model="auto" capability + cost scoring
├── router_cache.py     Single-workspace router
├── prompt_cache.py     Cross-provider exact-match cache (Redis or in-memory LRU)
├── schemas.py          OpenAI-compatible request schema
├── middleware/auth.py  sk-orca-* validation
└── routes/
    ├── chat.py         /v1/chat/completions  (blocking + streaming)
    ├── models.py       /v1/models
    ├── providers.py    BYOK CRUD
    ├── routing.py      strategy config
    ├── analytics.py    recent / spend / latency / savings / unreachable
    ├── keys.py         list / rotate / revoke API keys
    ├── hosted.py       /v1/hosted — hosted-fallback status for the dashboard
    └── health.py

packages/
├── litellm_adapter/    Router wrapper + 100+ model catalog
├── auth/               hashing + AES-256-GCM
└── db/                 models + engine + session

Roadmap

• Chat completions compatibles con OpenAI
• Streaming (SSE)
• Enrutamiento del más barato capaz con model="auto"
• Hosted-como-upstream
• BYOK cifrado en reposo
• Panel local de analítica
• CI (GitHub Actions)
• Caché de prompts entre proveedores
• Integraciones con Continue.dev / Aider / LangChain / Cursor / Vercel AI SDK
• Benchmark público + reclamo de ahorros
• Proxy de embeddings + generación de imágenes

Consulta DEMO.md para la demo de failover.

Licencia

MIT. Consulta LICENSE.