OrcaRouter Lite

Router LLM self-hosted con rete di sicurezza gestita. Compatibile con OpenAI. BYOK. Workspace singolo. Streaming. model="auto".

Lingue

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

OrcaRouter Lite è l'edizione open source single-workspace di OrcaRouter. Eseguilo sul tuo laptop, integralo nel tuo prodotto, oppure usa direttamente l'api.orcarouter.ai ospitato per la long tail di modelli di cui non vuoi gestire le chiavi.

Perché noi? LiteLLM è una libreria; OpenRouter è closed-source e ospitato; Ollama è solo locale. Noi siamo il server self-hosted con fallback gestito — una frase che nessuno di loro può dire.

Quickstart in 60 secondi

Due modi per usare OrcaRouter:

Strada A — Self-hosted (BYOK)

Esegui Lite sulla tua macchina; porta le tue chiavi provider.

git clone https://github.com/Continuum-AI-Corp/OrcaRouter-Lite.git
cd OrcaRouter-Lite
cp .env.example .env
# aggiungi almeno 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 chiave sk-orca-* stampata all'avvio.

Strada B — Hosted (account richiesto)

Niente clone, niente docker. Registrati, ottieni una chiave, punta qualsiasi SDK OpenAI all'hosted.

# 1. Registrati su https://www.orcarouter.ai e copia la tua chiave sk-orca-*
# 2. Usa https://api.orcarouter.ai/v1 come URL base

Account richiesto. L'hosted gestisce routing, fatturazione e la long tail di provider — fatturato per token sul tuo account OrcaRouter. Vedi docs.orcarouter.ai/introduction.

Poi chiamalo da qualsiasi SDK OpenAI

Gli esempi qui sotto usano l'URL base localhost della Strada A — sostituisci con https://api.orcarouter.ai/v1 se sei sulla Strada 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!"}]}'

Apri http://localhost:8000/ per la dashboard — provider, routing, analytics, chiavi (solo Strada A).

Perché?

model="auto" — la feature di punta

Invia model="auto" e OrcaRouter sceglie il modello più economico tra i provider configurati che soddisfa i requisiti di capacità della richiesta (tools, vision, modalità JSON). Niente regole di routing manuali; niente acrobazie con i rate-limit; niente ottimizzazione costo if x: ... nel tuo codice.

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:..."}},
    ]}],
)
# → instrada al modello più economico VISION-capable coperto dalle tue chiavi

Il modello risolto viene esposto a chi chiama tramite l'header di risposta x-orca-resolved-model, così puoi loggare/mostrare cosa è stato effettivamente usato.

Hosted come upstream (Lite + hosted)

Hai già Lite in esecuzione? Imposta ORCAROUTER_API_KEY con il tuo sk-orca-* di www.orcarouter.ai, e l'hosted diventa un provider in più nella catena di routing — coprendo i modelli che le tue chiavi locali non hanno:

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

Casi d'uso:

• Prova-prima-di-comprare — nessuna chiave provider locale necessaria
• Logging locale — l'hosted gestisce il routing, Lite memorizza le righe RequestLog per la dashboard
• Failover — i provider locali falliscono, l'hosted è la rete di sicurezza

Streaming

Formato SSE compatibile OpenAI con il framing standard data: ... \n\n e un sentinel terminale [DONE] — drop-in per qualsiasi SDK che già fa streaming da 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)

Catalogo modelli

Oltre 100 modelli di chat vengono caricati all'avvio dal database di prezzi mantenuto dalla community di LiteLLM — nessuna lista di modelli da mantenere a mano. Ogni voce espone:

• id (es. gpt-4o, claude-3-5-sonnet-latest)
• provider (mappato sulle tue chiavi configurate)
• Flag di capacità: supports_tools, supports_vision, supports_json_mode
• Costo per token input/output (alimenta il widget risparmi + model="auto")

GET /v1/models restituisce il catalogo nel formato OpenAI.

Deploy altrove

Piattaforma	One-click
Railway
Fly.io	fly launch --dockerfile Dockerfile
Render	Collega il repo, root dir = .
Docker nudo	docker run -p 8000:8000 -e OPENAI_API_KEY=... ghcr.io/... (immagine in arrivo)

Cosa c'è nella scatola

• POST /v1/chat/completions — proxy + streaming + model="auto" + cache prompt cross-provider
• GET /v1/models — catalogo modelli scopribile (100+ modelli da litellm.model_cost)
• GET/PUT/DELETE /v1/providers/{provider} — imposta / lista / revoca chiavi provider cifrate
• GET/PUT /v1/routing — cambia strategia (balanced / cheapest / fastest / quality)
• GET /v1/analytics/{recent,spend,latency,savings,unreachable} — analytics locali, nessuna telemetria esce dalla scatola
• GET /v1/hosted — stato del fallback hosted (alimenta la card "Get $5 free credit" della dashboard)
• GET/POST/DELETE /v1/keys/... — lista / ruota / revoca chiavi API
• Dashboard single-page su /
• SQLite di default; Postgres opt-in via DATABASE_URL; Redis opzionale

Cache prompt cross-provider

Le richieste deterministiche (temperature=0 o seed fissato) vengono servite dalla cache alle ripetizioni — funziona su ogni provider, non solo Anthropic. Il backend è Redis se REDIS_URL è impostato, altrimenti un LRU in-process. Gli hit della cache tornano istantaneamente con x-orca-cache: HIT e costano $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 ...  # stesso payload di nuovo
HTTP/1.1 200 OK
x-orca-cache: HIT          ← servito dalla cache, nessuna chiamata upstream

Widget risparmi

GET /v1/analytics/savings?baseline=gpt-4o&days=7 riporta quanto sarebbe costato il tuo traffico con sempre-GPT-4 rispetto a quanto è effettivamente costato. La dashboard lo mostra come tile.

Integrazioni

Configurazioni drop-in per Continue.dev, Aider, Cursor, LangChain, LlamaIndex, Vercel AI SDK e qualsiasi tool che parli il protocollo OpenAI Chat Completions. Vedi integrations/.

Cosa volutamente non c'è

Questa è l'edizione single-workspace. Per design, niente:

• multi-tenancy, RBAC, SSO
• fatturazione, wallet, punti, programma partner
• console di amministrazione, log di audit, trust & safety
• deploy multi-pod / Kubernetes
• email / Slack / webhook per gli alert

Per quelli, vedi il prodotto hosted o la (futura) edizione Teams.

Testing

Costruito test-first. Ogni comportamento spedito qui ha avuto prima un test che falliva.

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

Architettura

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 compatibili OpenAI
• Streaming (SSE)
• Routing model="auto" più-economico-capace
• Hosted-come-upstream
• BYOK cifrato a riposo
• Dashboard analytics locale
• CI (GitHub Actions)
• Caching prompt cross-provider
• Integrazioni Continue.dev / Aider / LangChain / Cursor / Vercel AI SDK
• Benchmark pubblico + claim sui risparmi
• Proxy embeddings + image-gen

Vedi DEMO.md per la demo di failover.

Licenza

MIT. Vedi LICENSE.