Skip to content

USER_GUIDE.md

Latest commit

 

History

History
1305 lines (936 loc) · 76.4 KB

USER_GUIDE.md

File metadata and controls

1305 lines (936 loc) · 76.4 KB
Raw

User Guide (Română)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

Ghid complet pentru configurarea furnizorilor, crearea combinațiilor, integrarea instrumentelor CLI și implementarea OmniRoute.

Cuprins

💰 Prețuri pe scurt

Nivel Furnizor Cost Resetarea cotei Recomandat pentru
💳 ABONAMENT Claude Code (Pro) $20/lună La 5 ore + săptămânal Utilizatori deja abonați
Codex (Plus/Pro) $20-200/lună La 5 ore + săptămânal Utilizatori OpenAI
GitHub Copilot $10-19/lună Lunar Utilizatori GitHub
🔑 CHEIE API DeepSeek Plată per utilizare Fără Raționament ieftin
Groq Plată per utilizare Fără Inferență ultrarapidă
xAI (Grok) Plată per utilizare Fără Raționament cu Grok 4
Mistral Plată per utilizare Fără Modele găzduite în UE
Perplexity Plată per utilizare Fără Căutare îmbunătățită
Together AI Plată per utilizare Fără Modele open-source
Fireworks AI Plată per utilizare Fără Imagini FLUX generate rapid
Cerebras Plată per utilizare Fără Viteză la scara plachetei
Cohere Plată per utilizare Fără RAG cu Command R+
NVIDIA NIM Plată per utilizare Fără Modele pentru companii
Baidu Qianfan Plată per utilizare Fără Modele ERNIE
💰 IEFTIN GLM-4.7 $0.6/1M Zilnic, la ora 10:00 Variantă de rezervă economică
MiniMax M2.1 $0.2/1M Fereastră glisantă de 5 ore Cea mai ieftină opțiune
Kimi K2 $9/lună, tarif fix 10M tokenuri/lună Cost previzibil
🆓 GRATUIT Qoder $0 Se aplică limitele furnizorului Verificarea catalogului actual
Kiro $0 ~50 de credite/lună Claude gratuit

🎯 Cazuri de utilizare

Cazul 1: „Am un abonament Claude Pro”

Problemă: Cota expiră neutilizată, iar în timpul sesiunilor intensive de programare sunt atinse limitele de rată

Combinație: "maximize-claude"
  1. cc/claude-opus-4-7        (folosește integral abonamentul)
  2. glm/glm-4.7               (variantă de rezervă ieftină când cota se epuizează)
  3. if/qwen3.8-max-preview       (variantă gratuită de urgență)

Cost lunar: $20 (abonament) + ~$5 (rezervă) = $25 în total
față de $20 + atingerea limitelor = frustrare

Cazul 2: „Nu vreau niciun cost”

Problemă: Nu-mi permit abonamente și am nevoie de un AI fiabil pentru programare

Combinație: "zero-cost"
  1. if/kimi-k2.7-code          (acces listat drept gratuit; se pot aplica limite de rată)
  2. kr/qwen3-coder-next        (variantă de rezervă gratuită prin Kiro)

Cost lunar: $0
Calitate: verificați modelul, limitele, confidențialitatea și SLA-ul pentru volumul dvs. de lucru

Cazul 3: „Am nevoie să programez non-stop, fără întreruperi”

Problemă: Am termene-limită și nu-mi permit perioade de nefuncționare

Combinație: "always-on"
  1. cc/claude-opus-4-7        (cea mai bună calitate)
  2. cx/gpt-5.5                (al doilea abonament)
  3. glm/glm-4.7               (ieftin, se resetează zilnic)
  4. minimax/MiniMax-M2.1      (cel mai ieftin, resetare la 5 ore)
  5. if/deepseek-v4-flash       (acces listat drept gratuit; se pot aplica limite de rată)

Rezultat: 5 niveluri de rezervă sporesc reziliența; disponibilitatea serviciilor din amonte nu este garantată
Cost lunar: $20-200 (abonamente) + $10-20 (rezervă)

Cazul 4: „Vreau AI GRATUIT în OpenClaw”

Problemă: Am nevoie de un asistent AI în aplicațiile de mesagerie, complet gratuit

Combinație: "openclaw-free"
  1. if/qwen3.8-max-preview     (acces listat drept gratuit; se pot aplica limite de rată)
  2. if/deepseek-v4-flash       (acces listat drept gratuit; se pot aplica limite de rată)
  3. if/kimi-k2.7-code          (acces listat drept gratuit; se pot aplica limite de rată)

Cost lunar: $0
Acces prin: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

📖 Configurarea furnizorilor

Pentru a adăuga în bloc conexiuni cu chei API dintr-un fișier CSV sau JSON, utilizați Panou de control → Furnizori → Importă din fișier. Coloanele sunt poziționale (provider,name,apiKey,baseUrl,priority); provider trebuie să existe deja ca furnizor gestionat sau ca nod compatibil. Consultați Importarea furnizorilor dintr-un fișier CSV sau JSON.

🔐 Furnizori pe bază de abonament

Claude Code (Pro/Max)

Panou de control → Furnizori → Conectează Claude Code
→ Autentificare OAuth → Reîmprospătare automată a tokenului
→ Monitorizarea cotei pe 5 ore + săptămânale

Modele:
  cc/claude-opus-4-7
  cc/claude-sonnet-4-6
  cc/claude-haiku-4-5-20251001

Sfat util: Utilizați Opus pentru sarcini complexe și Sonnet pentru viteză. OmniRoute monitorizează cota pentru fiecare model!

Rutele compatibile cu Claude și Claude Code păstrează nivelul de efort de raționament max pentru modelele Opus și Sonnet. Modelele Haiku nu acceptă nivelul de efort max, astfel încât OmniRoute reduce solicitarea la un buget ridicat de raționament înainte de a o trimite furnizorului din amonte.

OpenAI Codex (Plus/Pro)

Panou de control → Furnizori → Conectează Codex
→ Autentificare OAuth (portul 1455)
→ Resetare la 5 ore + săptămânală

Modele:
  cx/gpt-5.5
  cx/gpt-5.4
  cx/gpt-5.3-codex
  cx/gpt-5.3-codex-spark

GitHub Copilot

Panou de control → Furnizori → Conectează GitHub
→ OAuth prin GitHub
→ Resetare lunară (în prima zi a lunii)

Modele:
  gh/gpt-5.5
  gh/gpt-5.4
  gh/claude-sonnet-4.6
  gh/claude-opus-4.7
  gh/gemini-3.1-pro-preview

💰 Furnizori ieftini

GLM-4.7 (resetare zilnică, $0.6/1M)

  1. Înregistrați-vă: Zhipu AI
  2. Obțineți cheia API din Coding Plan
  3. Panou de control → Adaugă cheie API: Furnizor: glm, Cheie API: your-key

Utilizare: glm/glm-4.7 — Sfat util: Coding Plan oferă o cotă de 3 ori mai mare la 1/7 din cost! Se resetează zilnic la ora 10:00.

MiniMax M2.1 (resetare la 5 ore, $0.20/1M)

  1. Înregistrați-vă: MiniMax
  2. Obțineți cheia API → Panou de control → Adaugă cheie API

Utilizare: minimax/MiniMax-M2.1 — Sfat util: Cea mai ieftină opțiune pentru context lung (1M de tokenuri)!

Kimi K2 (tarif fix de $9/lună)

  1. Abonați-vă: Moonshot AI
  2. Obțineți cheia API → Panou de control → Adaugă cheie API

Utilizare: kimi/kimi-k2.5 — Sfat util: Tariful fix de $9/lună pentru 10M de tokenuri înseamnă un cost efectiv de $0.90/1M!

Baidu Qianfan / ERNIE

  1. Înregistrați-vă: Baidu AI Cloud Qianfan
  2. Creați o cheie API Qianfan → Panou de control → Adaugă cheie API: Furnizor: qianfan

Utilizare: qianfan/ernie-5.1, qianfan/ernie-x1.1 sau un alt ID de model Qianfan compatibil cu OpenAI.

🆓 Furnizori GRATUIȚI

Furnizorii gratuiți care nu necesită autentificare au un comutator lângă Nu este necesară autentificarea pe pagina furnizorului. Dezactivarea acestuia dezactivează furnizorul, îl elimină din vizualizările configurată/compactă ale Furnizorilor și elimină modelele sale din /v1/models.

Qoder (9 modele GRATUITE)

Panou de control → Conectează Qoder → Autentificare OAuth → Accesul este supus limitelor actuale ale furnizorului

Modele: if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3

Kiro (Claude GRATUIT)

Panou de control → Conectează Kiro → AWS Builder ID sau Google/GitHub → ~50 de credite/lună

Modele: kr/claude-sonnet-4.5, kr/claude-haiku-4.5

🎨 Combinații

Poți reordona cardurile combinațiilor direct în Panou de control → Combinații, trăgând mânerul de pe fiecare card. Ordinea este stocată în SQLite și restaurată la reîncărcare.

Exemplul 1: Maximizarea abonamentului → Rezervă ieftină

Panou de control → Combinații → Creează una nouă

Nume: premium-coding
Modele:
  1. cc/claude-opus-4-7 (Abonament principal)
  2. glm/glm-4.7 (Rezervă ieftină, $0.6/1M)
  3. minimax/MiniMax-M2.7 (Alternativă de ultimă instanță cu cel mai mic cost, $0.3/1M)

Utilizare în CLI: premium-coding

Exemplul 2: Numai opțiuni gratuite (cost zero)

Nume: free-combo
Modele:
  1. if/kimi-k2.7-code (acces gratuit conform informațiilor afișate; se pot aplica limitele furnizorului)
  2. kr/qwen3-coder-next (alternativă gratuită Kiro)

Cost: afișat în prezent ca $0; termenii și disponibilitatea se pot modifica

🔧 Integrarea cu CLI

Cursor IDE

Utilizarea Cursor drept client OmniRoute (direcționează conversațiile Cursor prin OmniRoute):

Setări → Modele → Avansat:
  URL de bază pentru API-ul OpenAI: http://localhost:20128/v1
  Cheie API OpenAI: [din panoul de control OmniRoute]
  Model: cc/claude-opus-4-7

Utilizarea OmniRoute drept furnizor Cursor (OmniRoute apelează Cursor în amonte): este recomandat Panou de control → Furnizori → Cursor → Autentificare cu Cursor. În Docker, consultă docs/providers/CURSOR-DOCKER.md.

Claude Code

Editează ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
  }
}

Folosește aici punctul final rădăcină compatibil cu Claude. Nu adăuga /v1 la ANTHROPIC_BASE_URL.

Codex CLI

export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"

OpenClaw

Editează ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "model": { "primary": "omniroute/if/kimi-k2.7-code" }
    }
  },
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://localhost:20128/v1",
        "apiKey": "your-omniroute-api-key",
        "api": "openai-completions",
        "models": [{ "id": "if/kimi-k2.7-code", "name": "Kimi K2.7 Code" }]
      }
    }
  }
}

Sau folosește panoul de control: Instrumente CLI → OpenClaw → Configurare automată

Cline / Continue / RooCode

Furnizor: Compatibil cu OpenAI
URL de bază: http://localhost:20128/v1
Cheie API: [din panoul de control]
Model: cc/claude-opus-4-7

🚀 Implementare

Instalare globală cu npm (recomandat)

npm install -g omniroute

# Creează directorul de configurare
mkdir -p ~/.omniroute

# Creează fișierul .env (consultă .env.example)
cp .env.example ~/.omniroute/.env

# Pornește serverul
omniroute
# Sau cu un port personalizat:
omniroute --port 3000

CLI-ul încarcă automat .env din ~/.omniroute/.env sau ./.env.

Modul bară de sistem

Pornește OmniRoute în bara de sistem:

omniroute serve --tray

Comanda se încheie după ce serverul și pictograma din bara de sistem sunt pregătite.

Serverul continuă să ruleze fără terminal.

Modul bară de sistem este compatibil cu macOS, Windows și sesiunile grafice Linux. Modul bară de sistem nu deschide automat panoul de control.

Folosește meniul din bara de sistem pentru următoarele acțiuni:

  • Deschide panoul de control.
  • Deschide /dashboard/logs.
  • Modifică pornirea automată.
  • Oprește OmniRoute.

Nu combina --tray cu următoarele opțiuni:

  • --daemon
  • --log
  • --no-recovery

Aceste moduri necesită o administrare diferită a proceselor.

Activează pornirea la următoarea autentificare pe sistem:

omniroute autostart enable

Pornirea automată folosește modul bară de sistem pe macOS, Windows și în sesiunile grafice Linux. Sistemele Linux fără interfață grafică folosesc serviciul de utilizator systemd existent.

Dezactivează pornirea la autentificare:

omniroute autostart disable

Dezinstalare

Când nu mai ai nevoie de OmniRoute, punem la dispoziție două scripturi rapide pentru eliminarea completă:

Comandă Acțiune
npm run uninstall Elimină aplicația din sistem, dar păstrează baza de date și configurațiile în ~/.omniroute.
npm run uninstall:full Elimină aplicația ȘI șterge definitiv toate configurațiile, cheile și bazele de date.

Notă: Pentru a executa aceste comenzi, accesează directorul proiectului OmniRoute (dacă l-ai clonat) și rulează-le. Alternativ, dacă este instalat global, poți executa pur și simplu npm uninstall -g omniroute.

Implementare pe VPS

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build

export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/omniroute"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"

npm run start
# Sau: pm2 start npm --name omniroute -- start

Implementare cu PM2 (memorie redusă)

Pentru serverele cu memorie RAM limitată, folosește opțiunea de limitare a memoriei:

# Cu o limită de 512MB (implicită)
pm2 start npm --name omniroute -- start

# Sau cu o limită de memorie personalizată
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# Sau folosind ecosystem.config.js
pm2 start ecosystem.config.js

Creează ecosystem.config.js:

module.exports = {
  apps: [
    {
      name: "omniroute",
      script: "npm",
      args: "start",
      env: {
        NODE_ENV: "production",
        OMNIROUTE_MEMORY_MB: "512",
        JWT_SECRET: "your-secret",
        INITIAL_PASSWORD: "your-password",
      },
      node_args: "--max-old-space-size=512",
      max_memory_restart: "300M",
    },
  ],
};

Docker

# Construiește imaginea (implicit = runner-cli cu codex/claude/droid preinstalate)
docker build -t omniroute:cli .

# Mod portabil (recomandat)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli

Pentru modul integrat cu gazda, cu binare CLI, consultă secțiunea Docker din documentația principală.

Void Linux (xbps-src)

Utilizatorii Void Linux pot împacheta și instala OmniRoute în mod nativ folosind cadrul de compilare încrucișată xbps-src. Acesta automatizează compilarea autonomă Node.js împreună cu legăturile native better-sqlite3 necesare.

Vizualizați șablonul xbps-src 
# Fișier șablon pentru „omniroute”
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Universal AI gateway with smart routing for multiple LLM providers"
maintainer="zenobit <zenobit@disroot.org>"
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false

do_build() {
	# Determină arhitectura procesorului țintă pentru node-gyp
	local _gyp_arch
	case "$XBPS_TARGET_MACHINE" in
		aarch64*) _gyp_arch=arm64 ;;
		armv7*|armv6*) _gyp_arch=arm ;;
		i686*) _gyp_arch=ia32 ;;
		*) _gyp_arch=x64 ;;
	esac

	# 1) Instalează toate dependențele – omite scripturile
	NODE_ENV=development npm ci --ignore-scripts

	# 2) Construiește pachetul autonom Next.js
	npm run build

	# 3) Copiază resursele statice în pachetul autonom
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) Compilează legătura nativă better-sqlite3
	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")

	# 5) Plasează legătura compilată în pachetul autonom
	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
	mkdir -p "$_bs3_release"
	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"

	# 6) Elimină pachetele sharp specifice arhitecturii
	rm -rf .next/standalone/node_modules/@img

	# 7) Copiază dependențele de execuție pino omise de analiza statică Next.js:
	for _mod in pino-abstract-transport split2 process-warning; do
		cp -r "node_modules/$_mod" .next/standalone/node_modules/
	done
}

do_check() {
	npm run test:unit
}

do_install() {
	vmkdir usr/lib/omniroute/.next
	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone

	# Împiedică eliminarea directoarelor goale ale routerului aplicației Next.js de către mecanismul post-instalare
	for _d in \
		.next/standalone/.next/server/app/dashboard \
		.next/standalone/.next/server/app/dashboard/settings \
		.next/standalone/.next/server/app/dashboard/providers; do
		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
	done

	cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
	vbin "${WRKDIR}/omniroute"
}

post_install() {
	vlicense LICENSE
}

Variabile de mediu

Variabilă Valoare implicită Descriere
JWT_SECRET omniroute-default-secret-change-me Secret pentru semnarea JWT (modificați-l în producție)
INITIAL_PASSWORD CHANGEME Parola pentru prima autentificare
DATA_DIR ~/.omniroute Director de date (bază de date, utilizare, jurnale)
PORT valoarea implicită a cadrului Portul serviciului (20128 în exemple)
HOSTNAME valoarea implicită a cadrului Gazda de ascultare (valoarea implicită pentru Docker este 0.0.0.0)
NODE_ENV valoarea implicită a mediului Setați la production pentru implementare
NEXT_PUBLIC_BASE_URL http://localhost:20128 URL-ul de bază public afișat în panoul de control și expus serverului (înlocuiește vechiul BASE_URL)
NEXT_PUBLIC_CLOUD_URL https://omniroute.dev URL-ul de bază al punctului final pentru sincronizarea în cloud (înlocuiește vechiul CLOUD_URL)
API_KEY_SECRET endpoint-proxy-api-key-secret Secret HMAC pentru cheile API generate
REQUIRE_API_KEY false Impune o cheie API Bearer pentru /v1/*
ALLOW_API_KEY_REVEAL false Permite utilizatorilor autentificați ai panoului de control să afișeze la cerere valorile complete ale cheilor API stocate
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES 70 Intervalul de reîmprospătare pe server pentru datele memorate în cache privind limitele furnizorilor; butoanele de reîmprospătare din interfața de utilizare declanșează în continuare sincronizarea manuală
DISABLE_SQLITE_AUTO_BACKUP false Dezactivează instantaneele SQLite automate înainte de scriere/importare/restaurare; copiile de siguranță manuale funcționează în continuare
APP_LOG_TO_FILE true Activează scrierea pe disc a jurnalelor aplicației și de audit
AUTH_COOKIE_SECURE false Impune atributul Secure pentru cookie-ul de autentificare (în spatele unui proxy invers HTTPS)
CLOUDFLARED_BIN nesetat Utilizează un binar cloudflared existent în locul descărcării gestionate
CLOUDFLARED_PROTOCOL http2 Transportul pentru tunelurile rapide gestionate (http2, quic sau auto)
OMNIROUTE_MEMORY_MB 512 Limita heap-ului Node.js în MB
PROMPT_CACHE_MAX_SIZE 50 Numărul maxim de intrări în memoria cache pentru prompturi
SEMANTIC_CACHE_MAX_SIZE 100 Numărul maxim de intrări în memoria cache semantică

Pentru referința completă a variabilelor de mediu, consultați README.

📊 Modele disponibile

Vedeți toate modelele disponibile

Lista de mai jos este selectată din open-sse/config/providerRegistry.ts pentru v3.8.0. Cataloagele cloud (Gemini, OpenRouter etc.) sunt sincronizate dinamic — pentru catalogul complet și actualizat, deschideți Panou de control → Furnizori → [furnizor] → Modele disponibile sau apelați GET /api/models/catalog.

Dacă lista încorporată a unui furnizor nu mai este actualizată, utilizați Importați din /models pe pagina respectivă (sau activați Sincronizare automată) pentru a prelua catalogul actualizat din sursa din amonte. Acest lucru a fost verificat în v3.8.50 pentru LLM7.io (gemini-3.1-flash-lite) și UncloseAI (solidrust/Hermes-3-Llama-3.1-8B-AWQ); accesul anonim la Pollinations a rămas limitat de sursa din amonte în cadrul aceleiași serii de teste.

Claude Code (cc/) — OAuth Pro/Max: cc/claude-opus-4-8, cc/claude-opus-4-7, cc/claude-opus-4-6, cc/claude-opus-4-5-20251101, cc/claude-sonnet-4-6, cc/claude-sonnet-4-5-20250929, cc/claude-haiku-4-5-20251001

Codex (cx/) — OAuth Plus/Pro: cx/gpt-5.5 (+ niveluri de efort: gpt-5.5-xhigh, gpt-5.5-high, gpt-5.5-medium, gpt-5.5-low), cx/gpt-5.4, cx/gpt-5.4-mini, cx/gpt-5.3-codex, cx/gpt-5.3-codex-spark

GitHub Copilot (gh/) — OAuth: gh/gpt-5.5, gh/gpt-5.4, gh/gpt-5.4-mini, gh/gpt-5-mini, gh/gpt-5.3-codex, gh/claude-opus-4.7, gh/claude-opus-4.6, gh/claude-opus-4-5-20251101, gh/claude-sonnet-4.6, gh/claude-sonnet-4.5, gh/claude-haiku-4.5, gh/gemini-3.1-pro-preview, gh/gemini-3-flash-preview, gh/oswe-vscode-prime

Kiro (kr/) — OAuth GRATUIT: utilizați catalogul actualizat afișat în Panou de control → Furnizori → Kiro → Modele disponibile. Disponibilitatea depinde de cont și de abonament.

Qoder (if/) — OAuth GRATUIT: if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3

GLM (glm/, glm-cn/, zai/, glmt/) — 0,2–0,6 USD/1M: glm/glm-5.1, glm/glm-5, glm/glm-5-turbo, glm/glm-4.7, glm/glm-4.7-flash, glm/glm-4.6, glm/glm-4.6v, glm/glm-4.5, glm/glm-4.5v, glm/glm-4.5-air

MiniMax (minimax/, minimax-cn/) — 0,2 USD/1M: minimax/MiniMax-M2.7, minimax/MiniMax-M2.7-highspeed, minimax/MiniMax-M2.5, minimax/MiniMax-M2.5-highspeed

Kimi (kimi/, kimi-coding/, kimi-coding-apikey/) — tarif fix de 9 USD/lună sau plată per utilizare: kimi/kimi-k2.6, kimi/kimi-k2.5

DeepSeek (ds/) — cheie API: ds/deepseek-v4-pro, ds/deepseek-v4-flash

Groq (groq/) — ultrarapid: groq/llama-3.3-70b-versatile, groq/meta-llama/llama-4-maverick-17b-128e-instruct, groq/qwen/qwen3-32b, groq/openai/gpt-oss-120b

xAI (xai/) — Grok nativ: xai/grok-4.3, xai/grok-4.20-multi-agent-0309, xai/grok-4.20-0309-reasoning, xai/grok-4.20-0309-non-reasoning

Mistral (mistral/) — găzduit în UE: mistral/mistral-large-latest, mistral/mistral-medium-3-5, mistral/mistral-small-latest, mistral/devstral-latest, mistral/codestral-latest

Perplexity (pplx/) — îmbogățit cu funcții de căutare: pplx/sonar-deep-research, pplx/sonar-reasoning-pro, pplx/sonar-pro, pplx/sonar

Together AI (together/) — sursă deschisă: together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free (gratuit), together/meta-llama/Llama-Vision-Free, together/deepseek-ai/DeepSeek-R1-Distill-Llama-70B-Free, together/deepseek-ai/DeepSeek-R1, together/Qwen/Qwen3-235B-A22B, together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8

Fireworks AI (fireworks/) — inferență rapidă: fireworks/accounts/fireworks/models/kimi-k2p6, fireworks/accounts/fireworks/models/minimax-m2p7, fireworks/accounts/fireworks/models/qwen3p6-plus, fireworks/accounts/fireworks/models/glm-5p1, fireworks/accounts/fireworks/models/deepseek-v4-pro

Cerebras (cerebras/) — la scara unei plachete: cerebras/zai-glm-4.7, cerebras/gpt-oss-120b

Cohere (cohere/) — axat pe RAG: cohere/command-a-reasoning-08-2025, cohere/command-a-vision-07-2025, cohere/command-a-03-2025, cohere/command-r-08-2024

NVIDIA NIM (nvidia/) — pentru întreprinderi: nvidia/z-ai/glm-5.1, nvidia/minimaxai/minimax-m2.7, nvidia/google/gemma-4-31b-it, nvidia/mistralai/mistral-small-4-119b-2603, nvidia/mistralai/mistral-large-3-675b-instruct-2512, nvidia/qwen/qwen3.5-397b-a17b, nvidia/deepseek-ai/deepseek-v4-pro, nvidia/openai/gpt-oss-120b, nvidia/nvidia/nemotron-3-super-120b-a12b

Baidu Qianfan (qianfan/) — ERNIE: qianfan/ernie-5.1, qianfan/ernie-5.0-thinking-latest, qianfan/ernie-x1.1

Ollama Cloud (ollama-cloud/): ollama-cloud/deepseek-v4-pro, ollama-cloud/deepseek-v4-flash, ollama-cloud/kimi-k2.6, ollama-cloud/glm-5.1, ollama-cloud/minimax-m2.7, ollama-cloud/gemma4:31b, ollama-cloud/qwen3.5:397b

Gemini (Google Cloud gemini/): sincronizat în timp real din Google pentru fiecare cheie API — nu există o listă statică. Conectați o cheie în Panou de control → Furnizori, apoi utilizați Modele disponibile pentru a importa catalogul actual (de exemplu, gemini/gemini-3-pro, gemini/gemini-3-flash).

Alți furnizori compatibili (selecție): cohere, databricks, snowflake, together, vertex, alibaba, alibaba-cn, bedrock (prin aws-bedrock), azure-ai, openrouter (catalog transmis direct), siliconflow, hyperbolic, huggingface, featherless-ai, cloudflare-ai, scaleway, deepinfra, vercel-ai-gateway, bazaarlink, friendliai, nous-research, reka, volcengine, ai21, gigachat. Fiecare își menține propria listă de modele în providerRegistry.ts și poate fi sincronizat automat atunci când furnizorul expune un punct final /models.

Notă privind ID-urile modelelor: OmniRoute utilizează ID-uri native ale furnizorilor (claude-opus-4-8, gpt-5.5, glm-5.1, MiniMax-M2.7, kimi-k2.5, grok-4.20-0309-reasoning). Unele ID-uri includ versiuni cu puncte, deoarece acesta este formatul solicitat de API-ul din amonte. Dacă un model nu este enumerat mai sus, rulați omniroute models --search <term> sau accesați GET /api/models/catalog pentru a confirma disponibilitatea.

🧩 Funcționalități avansate

Modele personalizate

Adăugați orice ID de model la orice furnizor fără a aștepta o actualizare a aplicației:

# Prin API
curl -X POST http://localhost:20128/api/provider-models \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "modelId": "gpt-5.2", "modelName": "GPT-5.2"}'

# Listare: curl http://localhost:20128/api/provider-models?provider=openai
# Eliminare: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"

Sau utilizați Panoul de control: Furnizori → [Furnizor] → Modele personalizate.

Note:

  • Furnizorii compatibili cu OpenRouter și OpenAI/Anthropic sunt gestionați exclusiv din Modele disponibile. Adăugarea manuală, importarea și sincronizarea automată ajung toate în aceeași listă de modele disponibile, astfel că nu există o secțiune separată Modele personalizate pentru acești furnizori.
  • Secțiunea Modele personalizate este destinată furnizorilor care nu oferă importuri gestionate ale modelelor disponibile.

Înlănțuirea instanțelor OmniRoute

Un alt gateway OmniRoute poate fi adăugat drept furnizor Personalizat compatibil cu OpenAI. Utilizați URL-ul de bază /v1 al instanței asociate și o cheie API dedicată, cu privilegii minime, emisă de aceasta.

Pentru lanțurile reciproce sau cu mai multe etape, activați protecția opțională împotriva buclelor pe fiecare gateway:

# gateway-a
OMNIROUTE_INSTANCE_ID=gateway-a
OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4
# gateway-b
OMNIROUTE_INSTANCE_ID=gateway-b
OMNIROUTE_PEER_URLS=http://gateway-a:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4

Numai solicitările trimise către un URL de instanță asociată inclus explicit în lista de permisiuni primesc antetul X-OmniRoute-Peer-Trace. Un gateway respinge un ID de instanță repetat sau epuizarea numărului permis de etape cu HTTP 508 Loop Detected; furnizorii upstream obișnuiți nu primesc metadate despre instanțele asociate.

Înlănțuirea instanțelor nu reprezintă replicarea bazei de date sau preluarea automată în caz de eroare a gazdei. Fiecare gateway păstrează independent starea SQLite, cache-urile, contoarele de rată și sesiunile. Utilizați un proxy invers cu verificări de integritate sau mecanisme de preluare automată la nivelul clientului pentru disponibilitate activ/pasiv sau activ/activ și nu montați niciodată aceeași bază de date SQLite în mai multe instanțe OmniRoute aflate în execuție.

Rute dedicate furnizorilor

Direcționați solicitările direct către un anumit furnizor, cu validarea modelului:

POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations

Prefixul furnizorului este adăugat automat dacă lipsește. Modelele incompatibile returnează 400.

Configurarea proxy-ului de rețea

# Setați proxy-ul global
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'

# Proxy pentru fiecare furnizor
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'

# Testați proxy-ul
curl -X POST http://localhost:20128/api/settings/proxy/test \
  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'

Precedență: Specific cheii → Specific combinației → Specific furnizorului → Global → Mediu.

API-ul catalogului de modele

curl http://localhost:20128/api/models/catalog

Returnează modelele grupate după furnizor, împreună cu tipurile (chat, embedding, image).

Sincronizare în cloud

  • Sincronizați furnizorii, combinațiile și setările între dispozitive
  • Sincronizare automată în fundal, cu expirare și oprire rapidă în caz de eroare
  • În producție, preferați NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URL pe partea de server

Tunel rapid Cloudflare

  • Disponibil în Panou de control → Puncte finale pentru Docker și alte implementări autogăzduite
  • Creează un URL temporar https://*.trycloudflare.com care redirecționează către punctul final /v1 curent, compatibil cu OpenAI
  • La prima activare, instalează cloudflared numai dacă este necesar; repornirile ulterioare reutilizează același fișier binar gestionat
  • Tunelurile rapide nu sunt restaurate automat după repornirea OmniRoute sau a containerului; reactivați-le din panoul de control atunci când este necesar
  • URL-urile tunelurilor sunt efemere și se modifică de fiecare dată când opriți și porniți tunelul
  • Tunelurile rapide gestionate utilizează implicit transportul HTTP/2 pentru a evita avertismentele zgomotoase privind bufferul UDP QUIC în containere cu resurse limitate
  • Setați CLOUDFLARED_PROTOCOL=quic sau auto dacă doriți să suprascrieți alegerea transportului gestionat
  • Setați CLOUDFLARED_BIN dacă preferați să utilizați un fișier binar cloudflared preinstalat în locul descărcării gestionate
  • Panourile Cloudflare Quick Tunnel, Tailscale Funnel și ngrok Tunnel pot fi afișate sau ascunse în Setări → Aspect. Ascunderea unui panou nu oprește un tunel aflat în execuție.

Inteligența gateway-ului LLM (Faza 9)

  • Cache semantic — Stochează automat în cache răspunsurile fără streaming, cu temperature=0 (ocoliți folosind X-OmniRoute-No-Cache: true)
  • Idempotența solicitărilor — Deduplică solicitările într-un interval de 5s prin antetul Idempotency-Key sau X-Request-Id
  • Urmărirea progresului — Evenimente SSE opționale event: progress, activate prin antetul X-OmniRoute-Progress: true

Spațiu de testare pentru traducător

Accesați-l prin Panou de control → Traducător. Depanați și vizualizați modul în care OmniRoute traduce solicitările API între furnizori.

Mod Scop
Spațiu de testare Selectați formatele sursă/țintă, inserați o solicitare și vedeți instantaneu rezultatul tradus
Tester de chat Trimiteți mesaje de chat live prin proxy și inspectați întregul ciclu solicitare/răspuns
Banc de testare Rulați teste în lot pentru mai multe combinații de formate, pentru a verifica corectitudinea traducerii
Monitor live Urmăriți traducerile în timp real pe măsură ce solicitările trec prin proxy

Cazuri de utilizare:

  • Depanați motivul pentru care o anumită combinație client/furnizor eșuează
  • Verificați dacă etichetele de raționament, apelurile de instrumente și prompturile de sistem sunt traduse corect
  • Comparați diferențele de format dintre formatele OpenAI, Claude, Gemini și Responses API

Strategii de rutare

Configurați prin Panou de control → Setări → Rutare. Panoul de control afișează cele șase strategii utilizate cel mai frecvent; combinațiile și routerul automat acceptă intern un set mai larg.

Strategii vizibile în panoul de control (rutare la nivel de cont):

Strategie Descriere
Umplere prioritară Utilizează conturile în ordinea priorității — contul principal gestionează toate cererile până devine indisponibil
Round Robin Parcurge ciclic toate conturile, cu o limită configurabilă de persistență (implicit: 3 apeluri per cont)
P2C (Puterea a două opțiuni) Alege 2 conturi aleatorii și direcționează către cel mai sănătos — echilibrează sarcina ținând cont de starea acestora
Aleatoriu Selectează aleatoriu un cont pentru fiecare cerere folosind algoritmul de amestecare Fisher-Yates
Cel mai puțin utilizat Direcționează către contul cu cel mai vechi marcaj temporal lastUsedAt, distribuind traficul uniform
Optimizat pentru costuri Direcționează către contul cu cea mai mică valoare de prioritate, optimizând pentru furnizorii cu cele mai reduse costuri

Strategii avansate pentru combinații și rutare automată (configurabile pentru fiecare combinație sau prin prefixele auto/* — consultați AUTO-COMBO.md):

  • priority — ordine strictă, fără distribuire round-robin
  • weighted — împărțire proporțională a traficului pe baza ponderilor fiecărui model
  • fill-first — utilizează primul model până la atingerea limitelor
  • round-robin / strict-random / random
  • p2c (Puterea a două opțiuni)
  • least-used și cost-optimized
  • auto — selecție bazată pe scor dintre toți candidații
  • lkgp (Ultimul furnizor cunoscut ca funcțional) — fixează rutarea la ultimul furnizor care a răspuns cu succes, apoi recurge la reguli
  • context-optimized — alege modelul cu cea mai mare fereastră de context disponibilă
  • context-relay — înlănțuiește modele cu ferestre mari de context pentru schimburile ulterioare

Antet extern pentru sesiuni persistente

Pentru afinitatea externă a sesiunii (de exemplu, agenți Claude Code/Codex aflați în spatele unor proxy-uri inverse), trimiteți:

X-Session-Id: cheia-sesiunii-dvs

OmniRoute acceptă și x_session_id și returnează cheia efectivă a sesiunii în X-OmniRoute-Session-Id.

Dacă utilizați Nginx și trimiteți antete care conțin liniuțe de subliniere, activați:

underscores_in_headers on;

Aliasuri de modele cu metacaractere

Creați modele de potrivire cu metacaractere pentru a remapa numele modelelor:

Model: claude-sonnet-*     →  Destinație: cc/claude-sonnet-4-6
Model: gpt-*               →  Destinație: gh/gpt-5.3-codex

Metacaracterele acceptate sunt * (orice caractere) și ? (un singur caracter).

Lanțuri de rezervă

Definiți lanțuri globale de rezervă care se aplică tuturor cererilor:

Lanț: production-fallback
  1. cc/claude-opus-4-7
  2. gh/gpt-5.3-codex
  3. glm/glm-4.7

Reziliență și întrerupătoare de circuit

Configurați prin Panou de control → Setări → Reziliență.

OmniRoute implementează reziliența la nivel de furnizor prin cinci componente:

  1. Coadă de cereri și controlul ritmului — Modelarea cererilor la nivel de sistem:

    • Cereri pe minut (RPM) — Numărul maxim de cereri pe minut pentru fiecare cont
    • Timp minim între cereri — Intervalul minim, în milisecunde, dintre cereri
    • Număr maxim de cereri simultane — Numărul maxim de cereri simultane pentru fiecare cont

  2. Perioadă de așteptare a conexiunii — Configurare pentru fiecare tip de autentificare, aplicată unei singure conexiuni după erori care permit reîncercarea:

    • Perioadă de așteptare de bază — Fereastra implicită de așteptare pentru erorile serviciilor din amonte care permit reîncercarea
    • Utilizarea indicațiilor de reîncercare din amonte — Respectă indicațiile oficiale Retry-After sau cele de resetare atunci când sunt furnizate
    • Număr maxim de pași pentru temporizare — Nivelul maxim al temporizării exponențiale pentru erori repetate

  3. Întrerupător de circuit al furnizorului — Urmărește erorile complete ale furnizorului, marchează un furnizor ca degradat la pragul de avertizare configurat și deschide întrerupătorul când este atins pragul de eroare configurat:

    • Prag de degradare — Numărul de erori consecutive ale furnizorului înainte de intrarea în starea DEGRADED
    • Prag de eroare — Numărul de erori consecutive ale furnizorului înainte de intrarea în starea OPEN
    • Interval de resetare — Perioada după care furnizorul este testat din nou
    • CLOSED (Funcțional) — Cererile circulă normal
    • DEGRADED — Cererile continuă să circule în timp ce este urmărit numărul crescut de erori
    • OPEN — Furnizorul este blocat temporar după erori repetate
    • HALF_OPEN — Se testează dacă furnizorul și-a revenit

    Limitările de rată 429 specifice conexiunii rămân în Perioada de așteptare a conexiunii și nu sunt luate în calcul de întrerupătorul furnizorului.

    Starea de rulare a întrerupătorului furnizorului este afișată numai în Panou de control → Stare de funcționare.

  4. Așteptarea perioadei de suspendare — Dacă toate conexiunile candidate se află deja într-o perioadă de așteptare, OmniRoute poate aștepta încheierea celei mai apropiate perioade și poate reîncerca automat aceeași cerere a clientului.

  5. Detectarea automată a limitelor de rată — Când furnizorii din amonte returnează ferestre de așteptare explicite, acele indicații suprascriu perioada locală de așteptare a conexiunii dacă setarea este activată.

Sfat util: Utilizați pagina Stare de funcționare pentru a inspecta și reseta întrerupătoarele active ale furnizorilor după o întrerupere. Pagina Reziliență modifică doar configurația.

Exportarea/importarea bazei de date

Gestionați copiile de rezervă ale bazei de date în Panou de control → Setări → Sistem și stocare.

Acțiune Descriere
Exportă baza de date Descarcă baza de date SQLite curentă ca fișier .sqlite
Exportă tot (.tar.gz) Descarcă o arhivă completă de backup care include: baza de date, setările, combinațiile, conexiunile furnizorilor (fără credențiale), metadatele cheilor API
Importă baza de date Încarcă un fișier .sqlite pentru a înlocui baza de date curentă. Un backup anterior importului este creat automat, exceptând cazul în care DISABLE_SQLITE_AUTO_BACKUP=true 
# API: Exportă baza de date
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API: Exportă tot (arhivă completă)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

# API: Importă baza de date
curl -X POST http://localhost:20128/api/db-backups/import \
  -F "file=@backup.sqlite"

Validarea importului: Fișierul importat este validat în privința integrității (verificare pragma SQLite), a tabelelor obligatorii (provider_connections, provider_nodes, combos, api_keys) și a dimensiunii (maximum 100 MB).

Cazuri de utilizare:

  • Migrarea OmniRoute între dispozitive
  • Crearea de backupuri externe pentru recuperarea în caz de dezastru
  • Partajarea configurațiilor între membrii echipei (exportă tot → partajează arhiva)

Panoul de setări

Pagina de setări este organizată în 7 file pentru o navigare ușoară:

Filă Conținut
General Instrumente de stocare ale sistemului, comportament implicit, vizibilitatea tunelurilor endpoint
Aspect Comenzi pentru temă (luminoasă/întunecată/sistem), vizibilitatea barei laterale, comutatoare pentru panourile cardurilor de tunel Cloudflare/Tailscale/ngrok
IA Buget de gândire (transmitere / eliminare automată / personalizat / adaptivă — consultați THINKING_BUDGET.md), prompt global de sistem, statistici privind memoria cache a prompturilor
Securitate Setări de autentificare/parolă, controlul accesului IP, autentificare API pentru /models, blocarea furnizorilor, protecție împotriva injectării de prompturi
Rutare Strategie globală de rutare (Umplere prioritară / Round Robin / P2C / Aleatoriu / Cel mai puțin utilizat / Optimizat după cost), aliasuri de modele cu metacaractere, lanțuri de rezervă, valori implicite pentru combinații
Reziliență Coadă de solicitări, perioadă de așteptare pentru conexiuni, configurarea întrerupătorului furnizorului și comportamentul de așteptare a perioadei de răcire
Avansat Configurarea globală a proxy-ului (HTTP/SOCKS5), suprascrieri ale proxy-ului pentru fiecare furnizor

Secțiunea General nu mai duplică notele doar în citire despre jurnalizare și memoria cache. Setările de păstrare și optimizare a bazei de date sunt persistate prin /api/settings/database; golirea manuală a memoriei cache utilizează DELETE /api/cache. Limitele de rânduri pentru jurnalele solicitărilor și ale proxy-ului sunt controlate prin CALL_LOGS_TABLE_MAX_ROWS și PROXY_LOGS_TABLE_MAX_ROWS.

Gestionarea costurilor și a bugetului

Accesați prin Panou → Costuri.

Filă Scop
Buget Stabiliți limite de cheltuieli pentru fiecare cheie API, cu bugete zilnice/săptămânale/lunare și monitorizare în timp real
Prețuri Vizualizați și editați intrările de prețuri pentru modele — costul per 1.000 de tokenuri de intrare/ieșire pentru fiecare furnizor 
# API: Setează un buget
curl -X POST http://localhost:20128/api/usage/budget \
  -H "Content-Type: application/json" \
  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'

# API: Obține starea curentă a bugetului
curl http://localhost:20128/api/usage/budget

Urmărirea costurilor: Fiecare solicitare înregistrează utilizarea tokenurilor și calculează costul folosind tabelul de prețuri. Vizualizați defalcările în Panou → Utilizare, în funcție de furnizor, model și cheie API.

Transcriere audio

OmniRoute acceptă transcrierea audio prin endpointul compatibil cu OpenAI:

POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

# Exemplu cu curl
curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@audio.mp3" \
  -F "model=openai/whisper-1"

deepgram/nova-3 este ruta Deepgram nativă și necesită o cheie API Deepgram. Dacă este configurat doar OpenRouter, utilizați openrouter/deepgram/nova-3.

Furnizori pentru transformarea vorbirii în text (transcriere):

  • openai/ (compatibil cu Whisper)
  • groq/ (Groq Whisper Turbo)
  • deepgram/ (familia Nova)
  • assemblyai/
  • nvidia/ (Parakeet, Canary)
  • huggingface/ (variante Whisper)
  • qwen/

Furnizori pentru transformarea textului în vorbire (POST /v1/audio/speech):

  • openai/ (tts-1, tts-1-hd)
  • hyperbolic/
  • deepgram/ (Aura)
  • nvidia/ (Magpie TTS)
  • elevenlabs/
  • huggingface/
  • inworld/
  • cartesia/
  • playht/
  • kie/
  • aws-polly/
  • xiaomi-mimo/
  • coqui/, tortoise/
  • qwen/

Formate audio acceptate pentru transcriere: mp3, wav, m4a, flac, ogg, webm. Formatele de ieșire TTS depind de furnizor (mp3, wav, opus, pcm, mulaw).

Strategii de echilibrare a combinațiilor

Configurați echilibrarea pentru fiecare combinație în Panou → Combinații → Creare/Editare → Strategie.

Strategie Descriere
Round-Robin Parcurge modelele secvențial
Prioritate Încearcă întotdeauna primul model; recurge la următorul doar în caz de eroare
Aleatoriu Alege aleatoriu un model din combinație pentru fiecare solicitare
Ponderat Direcționează proporțional pe baza ponderilor atribuite fiecărui model
Cel mai puțin utilizat Direcționează către modelul cu cele mai puține solicitări recente (folosește metricile combinației)
Optimizat pentru costuri Direcționează către cel mai ieftin model disponibil (folosește tabelul de prețuri)

Valorile implicite globale pentru combinații pot fi configurate în Tablou de bord → Setări → Rutare → Valori implicite pentru combinații. În mod implicit, expirările țintelor combinației moștenesc expirarea solicitării curente. Folosiți Expirare țintă (secunde) în valorile implicite ale combinațiilor sau într-o combinație individuală numai atunci când o limită mai scurtă per țintă ar trebui să declanșeze mai rapid recurgerea la următoarea țintă.

Optimizările cu latență zero sunt opționale. Lăsați Optimizări cu latență zero dezactivate pentru a împiedica aceste funcții de latență să trimită simultan solicitări către țintele de rezervă, să omită ținte pe baza istoricului TTFT sau să comprime solicitările de rezervă; activarea acestei opțiuni permite trimiterea redundantă configurată, omiterile predictive bazate pe TTFT și comprimarea proactivă a solicitărilor de rezervă, sacrificând fidelitatea rutării/solicitărilor în schimbul unei latențe maxime mai reduse.

Dezactivați Memoria tampon pentru tokenurile de raționament atunci când furnizorii din amonte impun limite stricte pentru max_tokens / maxOutputTokens. Când este activată, rutarea combinațiilor adaugă spațiu suplimentar pentru modelele de raționament numai pentru modelele cu o limită de ieșire cunoscută și lasă neschimbată limita de tokenuri a clientului atunci când valoarea sigură cu memoria tampon ar depăși acea limită. Dacă limita clientului depășește deja o limită cunoscută, OmniRoute o reduce la acea limită înainte de a trimite solicitarea către furnizorul din amonte.

Tabloul de bord pentru starea sistemului

Accesați-l prin Tablou de bord → Stare. Prezentare generală în timp real a stării sistemului, cu 6 carduri:

Card Ce afișează
Starea sistemului Timpul de funcționare, versiunea, utilizarea memoriei, directorul de date
Starea furnizorilor Starea globală în timpul rulării a întrerupătorului de circuit pentru furnizori
Limite de rată Perioade active de așteptare ale conexiunilor pentru fiecare cont, cu timpul rămas
Blocări active Blocări active specifice modelelor și excluderi temporare
Cache de semnături Statistici ale cache-ului de deduplicare (chei active, rata de succes)
Telemetria latenței Agregarea latenței p50/p95/p99 pentru fiecare furnizor

Sfat util: Pagina Stare se reîmprospătează automat la fiecare 10 secunde. Folosiți cardul întrerupătorului de circuit pentru a identifica furnizorii care întâmpină probleme.

🤖 Rutare automată (fără configurare)

OmniRoute include un router automat bazat pe scoruri, care alege cel mai bun model pentru fiecare solicitare dintre toți furnizorii conectați — fără combinații de întreținut. Trimiteți pur și simplu solicitarea folosind unul dintre prefixele auto/*, iar OmniRoute va asambla dinamic o combinație virtuală, evaluând candidații în funcție de latență, cost, rata de succes, compatibilitatea cu dimensiunea contextului, adecvarea modelului pentru sarcină, eșecurile recente, cotă și starea mecanismului de întrerupere a circuitului.

Prefix Optimizează pentru
auto Opțiune implicită echilibrată (latență × cost × rata de succes)
auto/coding Sarcini de programare: preferă Claude, GPT-5, GLM, Kimi, Qwen Coder, programatoarele DeepSeek
auto/cheap Cel mai mic cost per token, acceptă o latență mai mare
auto/fast Cea mai mică latență, ignoră costul
auto/offline Numai furnizori locali (Ollama, vLLM, llama.cpp) — util pentru configurații izolate de rețea
auto/smart Calitatea raționamentului pe primul loc (Opus, GPT-5 xhigh, R1, raționament GLM 5.1)
auto/lkgp „Ultimul furnizor cunoscut ca funcțional” — fixează ultimul furnizor utilizat cu succes, apoi revine la reguli

Exemplu:

curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/coding",
    "messages": [{ "role": "user", "content": "Refactorizați această funcție Python" }],
    "stream": true
  }'

Routerul automat este descris în detaliu în AUTO-COMBO.md — inclusiv modul de ajustare a ponderilor de evaluare, de adăugare a furnizorilor pe lista neagră și de inspectare a deciziilor de rutare în Panou de control → Combinație automată.

🔌 Integrare MCP și A2A

OmniRoute este atât un server MCP (Model Context Protocol), cât și un server A2A (JSON-RPC 2.0 între agenți). Orice IDE sau gazdă de agenți compatibilă cu MCP poate apela direct instrumentele OmniRoute — fără a necesita un wrapper suplimentar.

Transporturi MCP

  • SSE: http://localhost:20128/api/mcp/sse
  • HTTP cu streaming: http://localhost:20128/api/mcp/stream
  • stdio: omniroute --mcp (pentru pluginurile IDE care preferă stdio)

Conectarea Claude Desktop

Editați ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) sau fișierul echivalent pe Windows/Linux:

{
  "mcpServers": {
    "omniroute": {
      "command": "omniroute",
      "args": ["--mcp"]
    }
  }
}

Conectarea Cursor / Continue / VS Code MCP

Utilizați URL-ul SSE http://localhost:20128/api/mcp/sse și o cheie API Bearer generată în Panou de control → Chei API.

Domenii de acces

MCP definește în prezent 32 de domenii de acces denumite. Fiecare cheie Bearer poate fi limitată la anumite domenii de acces — consultați MCP-SERVER.md pentru lista oficială a domeniilor de acces și a instrumentelor și A2A-SERVER.md pentru schema JSON-RPC.

🧠 Sistemul de abilități

OmniRoute oferă un cadru extensibil pentru abilități (src/lib/skills/), astfel încât agenții și endpointul A2A să poată executa rutine specifice domeniului (de exemplu, code-review, summarize, extract-facts, web-research).

  • Interfață Marketplace — Răsfoiți și instalați abilități din Panou de control → Abilități
  • Domenii per cheie — Restricționați abilitățile pe care le poate invoca fiecare cheie API
  • Abilități personalizate — Adăugați un fișier TypeScript în src/lib/a2a/skills/, înregistrați-l și acesta devine imediat invocabil prin A2A

Referință completă: SKILLS.md.

💾 Sistemul de memorie

OmniRoute păstrează memoria conversațională pe termen lung folosind regăsirea hibridă:

  • SQLite FTS5 pentru căutarea după cuvinte-cheie în interacțiunile anterioare
  • Depozit vectorial Qdrant (opțional) pentru regăsirea semantică
  • Extragere automată a faptelor — entitățile, preferințele și deciziile sunt rezumate după fiecare sesiune și stocate în tabelul memory_facts
  • Memoriile sunt delimitate pentru fiecare cheie API și fiecare sesiune

Gestionați memoriile în Panou de control → Memorie (căutare, editare, exportare, ștergere). Interfața HTTP (/api/memory/*) permite agenților să trimită și să interogheze fapte în mod programatic — consultați MEMORY.md.

🔔 Webhookuri

Abonați-vă la evenimentele OmniRoute pentru monitorizare și automatizare în timp real.

  • Creați un webhook în Panou de control → Webhookuri, folosind URL-ul țintă și secretul de semnare HMAC
  • Evenimente disponibile: request.completed, request.failed, provider.unavailable, budget.exceeded, combo.switched, circuit_breaker.opened, circuit_breaker.closed
  • Fiecare sarcină utilă include X-OmniRoute-Signature (HMAC-SHA256) pentru verificare
  • Reîncercări: 3 încercări cu întârziere exponențială, urmate de trimiterea în coada pentru mesaje nelivrate

Schema completă este disponibilă în WEBHOOKS.md.

☁️ Agenți în cloud

OmniRoute se integrează cu agenți de programare în cloud (OpenAI Codex Cloud, Devin, Jules, Antigravity), astfel încât să puteți expedia sarcini de lungă durată din același panou de control care gestionează rutarea locală.

  • Creați sarcini în Panou de control → Agenți în cloud sau prin POST /api/v1/agents/tasks
  • Urmăriți starea, jurnalele și artefactele fiecărei sarcini
  • Folosiți propria cheie API pentru fiecare furnizor — datele de autentificare nu părăsesc niciodată instanța OmniRoute

Referință completă: CLOUD_AGENT.md.

🛠️ Gestionare programatică

Puteți gestiona fiecare resursă OmniRoute (furnizori, combinații, chei, setări) prin HTTP, utilizând o cheie Bearer cu domeniul manage.

Generați cheia în Panou de control → Chei API → Cheie nouă → Domeniu: manage, apoi:

# Listează furnizorii
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# Adaugă o conexiune la un furnizor
curl -X POST http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "openai", "apiKey": "sk-...", "name": "main" }'

# Creează o combinație
curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "premium", "strategy": "priority", "models": [{ "model": "cc/claude-opus-4-7" }, { "model": "glm/glm-5.1" }] }'

# Listează/creează chei API
curl http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -d '{ "name": "ci-bot", "scopes": ["chat"] }'

Consultați API_REFERENCE.md pentru catalogul complet de endpointuri și schemele solicitărilor/răspunsurilor.

💻 CLI intern

OmniRoute include un CLI intern (omniroute …) pentru configurare, diagnosticare și control în timpul rulării. Acesta este separat de pagina „Instrumente CLI” din panoul de control, care configurează CLI-uri terțe (Claude Code, Cursor, Codex, Cline, …), astfel încât acestea să poată comunica cu OmniRoute.

omniroute setup                    # Expert interactiv (parolă, furnizori, combinații)
omniroute setup --non-interactive  # Adecvat pentru CI
omniroute doctor                   # Diagnosticarea stării (director de date, BD, furnizori, porturi)
omniroute providers available      # Listează furnizorii acceptați
omniroute providers list           # Listează conexiunile configurate
omniroute providers test <id>      # Testează în timp real conexiunea unui furnizor
omniroute combos list              # Listează combinațiile
omniroute combos switch <name>     # Setează combinația implicită
omniroute models                   # Listează modelele disponibile (--json, --search)
omniroute keys add | list | remove # Gestionează cheile API din terminal
omniroute backup                   # Creează un instantaneu al configurației + BD
omniroute restore [<timestamp>]    # Restaurează dintr-un instantaneu
omniroute health                   # Stare detaliată (întrerupătoare, cache, memorie)
omniroute quota                    # Utilizarea cotei furnizorului
omniroute mcp status               # Starea serverului MCP
omniroute a2a status               # Starea serverului A2A
omniroute tunnel list|create|stop  # Tuneluri Cloudflare/Tailscale/ngrok
omniroute reset-password           # Resetează parola de administrator
omniroute --mcp                    # Pornește serverul MCP prin stdio
omniroute --port 3000              # Pornește serverul pe un port personalizat

Sfat: utilizați omniroute doctor --json împreună cu instrumentul dumneavoastră de monitorizare pentru a primi alerte privind conexiunile nesănătoase ale furnizorilor.

🖥️ Aplicație desktop (Electron)

OmniRoute este disponibil ca aplicație desktop nativă pentru Windows, macOS și Linux.

Instalare

# Din directorul electron:
cd electron
npm install

# Mod de dezvoltare (se conectează la serverul de dezvoltare Next.js care rulează):
npm run dev

# Mod de producție (utilizează versiunea autonomă):
npm start

Crearea programelor de instalare

cd electron
npm run build          # Platforma curentă
npm run build:win      # Windows (.exe NSIS)
npm run build:mac      # macOS (.dmg universal)
npm run build:linux    # Linux (.AppImage)

Rezultat → electron/dist-electron/

Funcționalități principale

Funcționalitate Descriere
Disponibilitatea serverului Interoghează serverul înainte de afișarea ferestrei (fără ecran gol)
Zona de notificare Minimizare în zona de notificare, schimbarea portului și închidere din meniul acesteia
Gestionarea portului Schimbă portul serverului din zona de notificare (repornește automat serverul)
Politica de securitate a conținutului CSP restrictivă prin anteturile sesiunii
Instanță unică Poate rula o singură instanță a aplicației simultan
Mod offline Serverul Next.js inclus funcționează fără internet

Variabile de mediu

Variabilă Valoare implicită Descriere
OMNIROUTE_PORT 20128 Portul serverului
OMNIROUTE_MEMORY_MB 512 Limita heap-ului Node.js (64–16384 MB)

📖 Documentație completă: electron/README.md