Skip to content

USER_GUIDE.md

Latest commit

 

History

History
1393 lines (997 loc) · 76.4 KB

USER_GUIDE.md

File metadata and controls

1393 lines (997 loc) · 76.4 KB
Raw

User Guide (Hrvatski)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇺 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 · 🇷🇴 ro · 🇷🇺 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 · 🇭🇺 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 · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

Potpuni vodič za konfiguriranje pružatelja usluga, izradu kombinacija, integraciju CLI alata i implementaciju OmniRoutea.

Sadržaj

💰 Pregled cijena

Razina Pružatelj usluge Trošak Resetiranje kvote Najbolje za
💳 PRETPLATA Claude Code (Pro) $20/mj 5h + tjedno Već ste pretplaćeni
Codex (Plus/Pro) $20-200/mj 5h + tjedno Korisnici OpenAI-a
GitHub Copilot $10-19/mj Mjesečno Korisnici GitHub-a
🔑 API KLJUČ DeepSeek Plaćanje po korištenju Nema Jeftino zaključivanje
Groq Plaćanje po korištenju Nema Ultra-brzo zaključivanje
xAI (Grok) Plaćanje po korištenju Nema Zaključivanje s Grok 4
Mistral Plaćanje po korištenju Nema Modeli hostirani u EU
Perplexity Plaćanje po korištenju Nema Pretraga uz podršku AI-a
Together AI Plaćanje po korištenju Nema Modeli otvorenog koda
Fireworks AI Plaćanje po korištenju Nema Brze FLUX slike
Cerebras Plaćanje po korištenju Nema Brzina razine wafer-a
Cohere Plaćanje po korištenju Nema Command R+ RAG
NVIDIA NIM Plaćanje po korištenju Nema Poslovni modeli
Baidu Qianfan Plaćanje po korištenju Nema ERNIE modeli
💰 JEFTINO GLM-4.7 $0.6/1M Dnevno 10h ujutro Proračunska rezerva
MiniMax M2.1 $0.2/1M Rotacija svakih 5 sati Najjeftinija opcija
Kimi K2 $9/mj fiksno 10M tokena/mj Predvidljiv trošak
🆓 BESPLATNO Qoder $0 Vrijede ograničenja pružatelja Provjerite trenutni katalog
Kiro $0 ~50 kredita/mj Claude besplatno

🎯 Slučajevi korištenja

Slučaj 1: "Imam pretplatu na Claude Pro"

Problem: Kvota istječe neiskorištena, ograničenja stope prilikom intenzivnog programiranja

Kombinacija: "maximize-claude"
  1. cc/claude-opus-4-7        (potpuno iskoristite pretplatu)
  2. glm/glm-4.7               (jeftina rezerva kad kvota istekne)
  3. if/qwen3.8-max-preview       (besplatna rezerva za hitne slučajeve)

Mjesečni trošak: $20 (pretplata) + ~$5 (rezerva) = $25 ukupno
u odnosu na $20 + dosezanje ograničenja = frustracija

Slučaj 2: "Želim nulti trošak"

Problem: Ne mogu si priuštiti pretplate, treba pouzdana AI podrška za programiranje

Kombinacija: "zero-cost"
  1. if/kimi-k2.7-code          (navedeni besplatan pristup; mogu se primjenjivati ograničenja stope)
  2. kr/qwen3-coder-next        (Kiro besplatna rezerva)

Mjesečni trošak: $0
Kvaliteta: provjerite model, ograničenja, privatnost i SLA za vaše radno opterećenje

Slučaj 3: "Trebam programiranje 24/7, bez prekida"

Problem: Rokovi, ne mogu si priuštiti prekide u radu

Kombinacija: "always-on"
  1. cc/claude-opus-4-7        (najbolja kvaliteta)
  2. cx/gpt-5.5                (druga pretplata)
  3. glm/glm-4.7               (jeftino, dnevno resetiranje)
  4. minimax/MiniMax-M2.1      (najjeftinije, resetiranje na 5h)
  5. if/deepseek-v4-flash       (navedeni besplatan pristup; mogu se primjenjivati ograničenja stope)

Rezultat: 5 razina rezerve proširuje otpornost sustava; dostupnost izvora nije zagarantirana
Mjesečni trošak: $20-200 (pretplate) + $10-20 (rezerva)

Slučaj 4: "Želim BESPLATNI AI u OpenClaw"

Problem: Potreban AI asistent u aplikacijama za razmjenu poruka, potpuno besplatno

Kombinacija: "openclaw-free"
  1. if/qwen3.8-max-preview     (navedeni besplatan pristup; mogu se primjenjivati ograničenja stope)
  2. if/deepseek-v4-flash       (navedeni besplatan pristup; mogu se primjenjivati ograničenja stope)
  3. if/kimi-k2.7-code          (navedeni besplatan pristup; mogu se primjenjivati ograničenja stope)

Mjesečni trošak: $0
Pristup putem: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

📖 Postavljanje pružatelja usluga

Za skupno dodavanje veza s API ključevima iz CSV ili JSON datoteke upotrijebite Nadzorna ploča → Pružatelji usluga → Uvezi iz datoteke. Stupci su pozicijski (provider,name,apiKey,baseUrl,priority); provider već mora postojati kao upravljani pružatelj usluga ili kompatibilni čvor. Pogledajte Uvoz pružatelja usluga iz CSV ili JSON datoteke.

🔐 Pretplatnički pružatelji usluga

Claude Code (Pro/Max)

Nadzorna ploča → Pružatelji usluga → Poveži Claude Code
→ OAuth prijava → Automatsko osvježavanje tokena
→ Praćenje 5-satne i tjedne kvote

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

Profesionalni savjet: Upotrebljavajte Opus za složene zadatke, a Sonnet za brzinu. OmniRoute prati kvotu za svaki model!

Nemate preglednik na OmniRoute domaćinu? Pokrenite claude setup-token bilo gdje gdje ste prijavljeni u Claude Code i zalijepite jednogodišnji token u karticu Token za postavljanje. Pogledajte Claude Code s tokenom za postavljanje.

Rute kompatibilne s Claudeom i Claude Codeom zadržavaju max razinu intenziteta razmišljanja za modele Opus i Sonnet. Modeli Haiku ne prihvaćaju max razinu intenziteta, pa OmniRoute taj zahtjev prije slanja nadređenom pružatelju spušta na visok proračun za razmišljanje.

OpenAI Codex (Plus/Pro)

Nadzorna ploča → Pružatelji usluga → Poveži Codex
→ OAuth prijava (priključak 1455)
→ Ponovno postavljanje nakon 5 sati i tjedan dana

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

GitHub Copilot

Nadzorna ploča → Pružatelji usluga → Poveži GitHub
→ OAuth putem GitHuba
→ Mjesečno ponovno postavljanje (1. u mjesecu)

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

💰 Povoljni pružatelji usluga

GLM-4.7 (dnevno ponovno postavljanje, $0.6/1M)

  1. Registrirajte se: Zhipu AI
  2. Preuzmite API ključ iz plana Coding Plan
  3. Nadzorna ploča → Dodaj API ključ: Pružatelj usluga: glm, API ključ: your-key

Upotreba: glm/glm-4.7 — Profesionalni savjet: Coding Plan nudi 3× veću kvotu uz 1/7 cijene! Ponovno se postavlja svakog dana u 10:00.

MiniMax M2.1 (ponovno postavljanje nakon 5 h, $0.20/1M)

  1. Registrirajte se: MiniMax
  2. Preuzmite API ključ → Nadzorna ploča → Dodaj API ključ

Upotreba: minimax/MiniMax-M2.1 — Profesionalni savjet: Najjeftinija opcija za dugi kontekst (1M tokena)!

Kimi K2 (fiksno $9 mjesečno)

  1. Pretplatite se: Moonshot AI
  2. Preuzmite API ključ → Nadzorna ploča → Dodaj API ključ

Upotreba: kimi/kimi-k2.5 — Profesionalni savjet: Fiksnih $9 mjesečno za 10M tokena = efektivni trošak od $0.90/1M!

Baidu Qianfan / ERNIE

  1. Registrirajte se: Baidu AI Cloud Qianfan
  2. Izradite Qianfan API ključ → Nadzorna ploča → Dodaj API ključ: Pružatelj usluga: qianfan

Upotreba: qianfan/ernie-5.1, qianfan/ernie-x1.1 ili neki drugi identifikator Qianfan modela kompatibilnog s OpenAI-jem.

🆓 BESPLATNI pružatelji usluga

Besplatni pružatelji usluga koji ne zahtijevaju autentifikaciju imaju prekidač pokraj opcije Autentifikacija nije potrebna na svojoj stranici. Isključivanjem se taj pružatelj usluga onemogućuje, uklanja iz konfiguriranih/sažetih prikaza pružatelja usluga te se njegovi modeli uklanjaju iz /v1/models.

Qoder (9 BESPLATNIH modela)

Nadzorna ploča → Poveži Qoder → OAuth prijava → Pristup podliježe trenutačnim ograničenjima pružatelja usluga

Modeli: 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 BESPLATNO)

Nadzorna ploča → Poveži Kiro → AWS Builder ID ili Google/GitHub → ~50 kredita mjesečno

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

🎨 Kombinacije

Kartice kombinacija možete preslagati direktno u Dashboard → Combos povlačenjem ručke na svakoj kartici. Redoslijed se pohranjuje u SQLite i vraća prilikom ponovnog učitavanja.

Primjer 1: Maksimalno iskoristi pretplatu → jeftina rezerva

Dashboard → Combos → Create New

Name: premium-coding
Models:
  1. cc/claude-opus-4-7 (Subscription primary)
  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
  3. minimax/MiniMax-M2.7 (Cheapest fallback, $0.3/1M)

Use in CLI: premium-coding

Primjer 2: Samo besplatno (nulti trošak)

Name: free-combo
Models:
  1. if/kimi-k2.7-code (listed free access; provider limits may apply)
  2. kr/qwen3-coder-next (Kiro free fallback)

Cost: currently listed as $0; terms and availability may change

🔧 CLI integracija

Cursor IDE

Korištenje Cursora kao OmniRoute klijenta (usmjeravanje Cursor chata kroz OmniRoute):

Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [iz omniroute nadzorne ploče]
  Model: cc/claude-opus-4-7

Korištenje OmniRoutea kao Cursor providera (OmniRoute poziva Cursor uzvodno): preferira se Dashboard → Providers → Cursor → Login with Cursor. U Dockeru pogledajte docs/providers/CURSOR-DOCKER.md.

Claude Code

Uredite ~/.claude/settings.json:

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

Ovdje koristite root endpoint kompatibilan s Claudeom. Ne dodajte /v1 na ANTHROPIC_BASE_URL.

Codex CLI

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

OpenClaw

Uredite ~/.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" }]
      }
    }
  }
}

Ili koristite Dashboard: CLI Tools → OpenClaw → Auto-config

Cline / Continue / RooCode

Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [iz nadzorne ploče]
Model: cc/claude-opus-4-7

🚀 Postavljanje (Deployment)

Globalna npm instalacija (preporučeno)

npm install -g omniroute

# Kreirajte direktorij za konfiguraciju
mkdir -p ~/.omniroute

# Kreirajte .env datoteku (pogledajte .env.example)
cp .env.example ~/.omniroute/.env

# Pokrenite server
omniroute
# Ili s prilagođenim portom:
omniroute --port 3000

CLI automatski učitava .env iz ~/.omniroute/.env ili ./.env.

Tray način rada

Pokrenite OmniRoute u sistemskoj traci (tray):

omniroute serve --tray

Naredba se vraća nakon što su server i tray spremni.

Server nastavlja s radom bez terminala.

Tray način rada podržava macOS, Windows i grafičke Linux sesije. Tray način rada ne otvara automatski nadzornu ploču.

Koristite tray izbornik za sljedeće radnje:

  • Otvorite nadzornu ploču.
  • Otvorite /dashboard/logs.
  • Promijenite automatsko pokretanje.
  • Zaustavite OmniRoute.

Ne kombinirajte --tray s ovim opcijama:

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

Ovi načini rada zahtijevaju različito vlasništvo nad procesom.

Omogućite pokretanje pri sljedećoj prijavi na računalo:

omniroute autostart enable

Automatsko pokretanje koristi tray način rada na macOS, Windows i grafičkim Linux sesijama. Headless Linux koristi postojeću systemd korisničku uslugu.

Isključite pokretanje pri prijavi:

omniroute autostart disable

Deinstalacija

Kada vam OmniRoute više ne treba, nudimo dvije brze skripte za čisto uklanjanje:

Naredba Radnja
npm run uninstall Uklanja sistemsku aplikaciju, ali zadržava vašu bazu podataka i konfiguracije u ~/.omniroute.
npm run uninstall:full Uklanja aplikaciju I trajno briše sve konfiguracije, ključeve i baze podataka.

Napomena: Za pokretanje ovih naredbi otiđite u mapu OmniRoute projekta (ako ste ga klonirali) i pokrenite ih. Alternativno, ako je instaliran globalno, jednostavno pokrenite npm uninstall -g omniroute.

VPS postavljanje

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
# Ili: pm2 start npm --name omniroute -- start

PM2 postavljanje (mala memorija)

Za servere s ograničenom RAM memorijom koristite opciju ograničenja memorije:

# S ograničenjem od 512MB (zadano)
pm2 start npm --name omniroute -- start

# Ili s prilagođenim ograničenjem memorije
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# Ili koristeći ecosystem.config.js
pm2 start ecosystem.config.js

Kreirajte 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

# Izgradnja slike (zadano = runner-cli s predinstaliranim codex/claude/droid)
docker build -t omniroute:cli .

# Prijenosni način rada (preporučeno)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli

Za način rada integriran s hostom uz CLI binarne datoteke, pogledajte odjeljak o Dockeru u glavnoj dokumentaciji.

Void Linux (xbps-src)

Korisnici Void Linuxa mogu pakirati i instalirati OmniRoute nativno koristeći xbps-src framework za cross-kompilaciju. Ovo automatizira samostalnu (standalone) Node.js izgradnju zajedno s potrebnim nativnim vezama better-sqlite3.

Pregledajte xbps-src predložak 
# Template file for '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() {
	# Odredi ciljnu CPU arhitekturu za 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) Instaliraj sve ovisnosti – preskoči skripte
	NODE_ENV=development npm ci --ignore-scripts

	# 2) Izgradi Next.js standalone paket
	npm run build

	# 3) Kopiraj statičke resurse u standalone
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) Kompajliraj better-sqlite3 nativnu vezu
	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) Postavi kompajliranu vezu u standalone paket
	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) Ukloni arhitekturno specifične sharp pakete
	rm -rf .next/standalone/node_modules/@img

	# 7) Kopiraj pino runtime ovisnosti izostavljene Next.js statičkom analizom:
	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

	# Spriječi uklanjanje praznih Next.js app router direktorija post-install kukom
	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
}

Varijable okoline

Varijabla Zadano Opis
JWT_SECRET omniroute-default-secret-change-me Tajni ključ za JWT potpisivanje (promijeniti u produkciji)
INITIAL_PASSWORD CHANGEME Lozinka za prvu prijavu
DATA_DIR ~/.omniroute Direktorij podataka (baza podataka, korištenje, zapisnici)
PORT zadano iz frameworka Port usluge (20128 u primjerima)
HOSTNAME zadano iz frameworka Host za vezivanje (Docker zadano koristi 0.0.0.0)
NODE_ENV zadano tijekom izvođenja Postavite production za postavljanje
NEXT_PUBLIC_BASE_URL http://localhost:20128 Javna osnovna URL adresa prikazana na nadzornoj ploči i izložena serveru (zamjenjuje zastarjeli BASE_URL)
NEXT_PUBLIC_CLOUD_URL https://omniroute.dev Osnovna URL adresa krajnje točke sinkronizacije s oblakom (zamjenjuje zastarjeli CLOUD_URL)
API_KEY_SECRET endpoint-proxy-api-key-secret HMAC tajni ključ za generirane API ključeve
REQUIRE_API_KEY false Zahtijeva Bearer API ključ na /v1/*
ALLOW_API_KEY_REVEAL false Dopušta autentificiranim korisnicima nadzorne ploče otkrivanje potpunih pohranjenih vrijednosti API ključeva na zahtjev
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES 70 Učestalost obnavljanja na strani servera za predmemorirane podatke o Provider Limits; gumbi za obnavljanje u sučelju i dalje pokreću ručnu sinkronizaciju
DISABLE_SQLITE_AUTO_BACKUP false Isključuje automatske SQLite snapshotove prije pisanja/uvoza/vraćanja; ručne sigurnosne kopije i dalje rade
APP_LOG_TO_FILE true Omogućuje izlaz aplikacijskih i revizijskih zapisnika na disk
AUTH_COOKIE_SECURE false Prisiljava Secure autentifikacijski kolačić (iza HTTPS reverse proxyja)
CLOUDFLARED_BIN nepostavljeno Koristi postojeću cloudflared binarnu datoteku umjesto upravljanog preuzimanja
CLOUDFLARED_PROTOCOL http2 Transport za upravljane Quick Tunnels (http2, quic ili auto)
OMNIROUTE_MEMORY_MB 512 Ograničenje Node.js heap-a u MB
PROMPT_CACHE_MAX_SIZE 50 Maksimalan broj unosa u predmemoriji prompta
SEMANTIC_CACHE_MAX_SIZE 100 Maksimalan broj unosa u semantičkoj predmemoriji

Za potpuni popis varijabli okoline pogledajte README.

📊 Dostupni modeli

Prikaži sve dostupne modele

Donji popis sažet je iz open-sse/config/providerRegistry.ts za v3.8.0. Katalozi u oblaku (Gemini, OpenRouter itd.) sinkroniziraju se dinamički — za potpuni katalog uživo otvorite Nadzorna ploča → Pružatelji → [provider] → Dostupni modeli ili pozovite GET /api/models/catalog.

Ako je ugrađeni popis nekog pružatelja zastario, upotrijebite Uvezi iz /models na toj stranici (ili omogućite Auto-Sync) kako biste povukli aktualni upstream katalog. Ovo je potvrđeno u v3.8.50 za LLM7.io (gemini-3.1-flash-lite) i UncloseAI (solidrust/Hermes-3-Llama-3.1-8B-AWQ); anonimni pristup Pollinationsu ostao je ograničen na strani upstreama tijekom istog testnog prolaza.

Claude Code (cc/) — Pro/Max OAuth: 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/) — Plus/Pro OAuth: cx/gpt-5.5 (+ razine napora: 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/) — BESPLATNI OAuth: koristite katalog uživo prikazan pod Nadzorna ploča → Pružatelji → Kiro → Dostupni modeli. Dostupnost ovisi o računu i planu.

Qoder (if/) — BESPLATNI OAuth: 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 $/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 $/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/) — 9 $/mj. paušalno ili po upotrebi: kimi/kimi-k2.6, kimi/kimi-k2.5

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

Groq (groq/) — Ultra-brzo: 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/) — Izvorni Grok: 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/) — Hostano u EU: mistral/mistral-large-latest, mistral/mistral-medium-3-5, mistral/mistral-small-latest, mistral/devstral-latest, mistral/codestral-latest

Perplexity (pplx/) — Prošireno pretragom: pplx/sonar-deep-research, pplx/sonar-reasoning-pro, pplx/sonar-pro, pplx/sonar

Together AI (together/) — Otvoreni kôd: together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free (besplatno), 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/) — Brza inferencija: 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/) — Wafer-scale: cerebras/zai-glm-4.7, cerebras/gpt-oss-120b

Cohere (cohere/) — Fokusirano na 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/) — Enterprise: 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.5-super-vl-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/): Sinkronizira se uživo po API ključu s Googlea — bez statičnog popisa. Povežite ključ u Nadzorna ploča → Pružatelji, a zatim upotrijebite Dostupni modeli za uvoz trenutačnog kataloga (npr. gemini/gemini-3-pro, gemini/gemini-3-flash).

Ostali kompatibilni pružatelji (odabrano): cohere, databricks, snowflake, together, vertex, alibaba, alibaba-cn, bedrock (putem aws-bedrock), azure-ai, openrouter (katalog prosljeđivanja), siliconflow, hyperbolic, huggingface, featherless-ai, cloudflare-ai, scaleway, deepinfra, vercel-ai-gateway, bazaarlink, friendliai, nous-research, reka, volcengine, ai21, gigachat. Svaki održava vlastiti popis modela u providerRegistry.ts i može se automatski sinkronizirati kada pružatelj izloži endpoint /models.

Napomena o ID-jevima modela: OmniRoute koristi izvorne ID-jeve pružatelja (claude-opus-4-8, gpt-5.5, glm-5.1, MiniMax-M2.7, kimi-k2.5, grok-4.20-0309-reasoning). Neki ID-jevi uključuju verzije s točkama jer ih upstream API tako očekuje. Ako model nije gore naveden, pokrenite omniroute models --search <term> ili pozovite GET /api/models/catalog kako biste potvrdili dostupnost.

🧩 napredne značajke

Prilagođeni modeli

Dodajte bilo koji model ID bilo kojem pružatelju usluga bez čekanja na ažuriranje aplikacije:

# Via 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"}'

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

Ili upotrijebite nadzornu ploču:** Dobavljači → [Dobavljač] → Prilagođeni modeli** .

Bilješke:

  • OpenRouter i OpenAI/Anthropic-compatible pružateljima se upravlja iz** Dostupni modeli** samo. Ručno dodavanje, uvoz i automatska sinkronizacija sve se nalazi na istom popisu dostupnih modela, tako da ne postoji poseban odjeljak prilagođenih modela za te pružatelje usluga.
  • The** Prilagođeni modeli** odjeljak namijenjen je pružateljima koji ne izlažu upravljani uvoz dostupnog modela.

Prilagođeni pružatelji kompatibilni s OpenAI-jem

Bilo koji pristupnik koji govori OpenAI API (proxy s vlastitim hostom, vLLM, agregator treće strane) može se dodati kao vlastiti čvor pružatelja:

  1. Pružatelji → Dodaj OpenAI kompatibilan .
  2. Ime : oznaka prikaza za čvor.
  3. Prefiks : naziv usmjeravanja. Klijenti nazivaju modele <prefix>/<model>, tako da čvor s prefiksom mygw služi mygw/gpt-4o-mini. Potreban; nema ograničenja znakova.
  4. API Vrsta : obitelj krajnjih točaka koju pristupnik služi (završeci razgovora, odgovori, ugradnje, zvuk, slike).
  5. Baza URL : API korijen, do i uključujući /v1 (na primjer https://gateway.example.com/v1), ne puna /chat/completions staza. Gateways s nestandardnim stazama postavite ih pod** Napredne postavke** (put za chat, put za modele).
  6. TheAPI ključ (za provjeru) polje samo testira vezu. Nakon što stvorite čvor, otvorite ga i koristite** Dodaj vezu** za pohranjivanje ključa koji će zahtjevi koristiti.

Čvor dobiva interni ID u obliku openai-compatible-<apiType>-<uuid>; ne morate ga nikada upisati, prefiks je javno ime.

Rezervirani prefiksi

Prefiks ne može biti ID ili pseudonim ugrađenog pružatelja usluga (na primjer openai, cf), niti ID povučenog pružatelja usluga. Razrešivač modela provjerava ugrađene ID-ove i pseudonime prije prilagođenih čvorova, tako da čvor koji koristi jedan od tih prefiksa nikada ne bi primio promet: <prefix>/model bi umjesto toga išao ugrađenom pružatelju ili se ne bi zatvorio ako bi se taj pružatelj povukao. Stvaranje ili uređivanje čvora s takvim prefiksom odbija se s:

prefix: "<prefix>" is a reserved provider prefix — choose a different prefix (reserved ids/aliases cannot be used for custom nodes because requests like <prefix>/model route to a built-in provider or fail closed when retired)

Odaberite poseban prefiks (mygw, acme-proxy). Ako zahtjevi prema prilagođenom čvoru ne uspije uz pogrešku koja imenuje ugrađenog pružatelja usluga ili njegove vjerodajnice, provjerite je li prefiks čvora rezerviran: čvorovi spremljeni prije nego što je ovo pravilo postojalo i dalje su pohranjeni, ali njihovi prefiksi usmjeravaju prema ugrađenom pružatelju usluga. Uredite čvor i dajte mu novi prefiks.

Opcije pristupnika za svaku vezu

Ovi ključevi idu u providerSpecificData veze (na primjer putem PUT /api/providers/{id}):

  • toolNameMaxLength (cijeli broj, 1–1024) — za OpenAI chat-format kompatibilne veze čiji pristupnik odbija duga imena alata. Dulja imena šalju se kao kratki aliasi i vraćaju u odgovor.
  • quotaEndpoint — krajnja točka quota/credits pristupnika, pročitajte za traku kvote nadzorne ploče i usmjeravanje s obzirom na kvote. Radi na OpenAI- i Anthropic-kompatibilnim vezama; puni oblik je dokumentiran u open-sse/services/usage/openaiCompatible.ts.
{
  "toolNameMaxLength": 64,
  "quotaEndpoint": {
    "url": "https://gateway.example.com/key/info",
    "auth": "bearer",
    "quotas": {
      "budget": { "used": "$.info.spend", "total": "$.info.max_budget", "currency": "USD" }
    }
  }
}

Ulančavanje OmniRoute ravnopravnih

Drugi OmniRoute pristupnik može se dodati kao** Prilagođeno OpenAI-kompatibilno** davatelj usluga. Koristite ravnopravnu /v1 bazu URL i namjenski API ključ s najmanjom privilegijom koji je izdao taj ravnopravni uređaj.

Za recipročne lance ili lance s više skokova, omogućite opt-in loop guard na svakom pristupniku:

# 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

Samo zahtjevi poslani izričito dopuštenom peer URL primaju X-OmniRoute-Peer-Trace zaglavlje. Gateway odbija ponovljenu instancu ID ili iscrpljeni proračun skoka sa HTTP 508 Loop Detected; obični uzvodni pružatelji usluga ne primaju ravnopravne metapodatke.

Peer lančano nije replikacija baze podataka ili failover hosta. Svaki gateway čuva neovisno SQLite stanje, predmemorije, brojače stopa i sesije. Za dostupnost active/passive ili active/active koristite provjereni obrnuti proxy ili klijentski failover i nikada ne montirajte jednu SQLite bazu podataka u više pokrenutih OmniRoute instanci.

Namjenske rute pružatelja usluga

Usmjerite zahtjeve izravno određenom pružatelju uz provjeru valjanosti modela:

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

Prefiks pružatelja automatski se dodaje ako nedostaje. Neusklađeni modeli vraćaju 400.

Konfiguracija mrežnog proxyja

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

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

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

Prednost: Specifično za ključ → Specifično za kombinaciju → Specifično za pružatelja → Globalno → okruženje.

Katalog modela API

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

Vraća modele grupirane prema pružatelju s tipovima (chat, embedding, image).

Sinkronizacija u oblaku

  • Sinkronizirajte pružatelje usluga, kombinacije i postavke na svim uređajima
  • Automatska pozadinska sinkronizacija s vremenskim ograničenjem + fail-fast
  • Radije NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URL na strani poslužitelja u proizvodnji

Cloudflare Brzi tunel

  • Dostupno u** Kontrolna ploča → Krajnje točke** za Docker i druge samodomaćene implementacije
  • Stvara privremeni https://*.trycloudflare.com URL koji prosljeđuje vašoj trenutnoj /v1 točki kompatibilnoj s OpenAI-jem
  • Prvo omogući instaliranje cloudflared samo kada je potrebno; kasnije ponovno pokretanje ponovno koristi istu upravljanu binarnu datoteku
  • Brzi tuneli se ne vraćaju automatski nakon ponovnog pokretanja OmniRoute ili spremnika; ponovno ih omogućite s nadzorne ploče kada je potrebno
  • Tunel URLs je efemeran i mijenja se svaki put kada stop/start tunelom
  • Upravljani brzi tuneli zadano postavljaju HTTP/2 prijenos kako bi izbjegli bučna upozorenja QUIC UDP međuspremnika u ograničenim spremnicima
  • Postavite CLOUDFLARED_PROTOCOL=quic ili auto ako želite poništiti izbor upravljanog transporta
  • Postavite CLOUDFLARED_BIN ako radije koristite unaprijed instaliranu cloudflared binarnu datoteku umjesto upravljanog preuzimanja
  • Cloudflare Quick Tunnel, Tailscale Funnel i ngrok Tunnel mogu se prikazati ili sakriti u** Postavke → Izgled** . Skrivanje ploče ne zaustavlja tunel koji radi.

LLM Gateway Intelligence (faza 9)

  • Semantička predmemorija — Automatski predmemorira odgovore bez strujanja, temperaturu = 0 (zaobići sa X-OmniRoute-No-Cache: true)
  • Idempotencija zahtjeva — Deduplicira zahtjeve unutar 5 s putem Idempotency-Key ili X-Request-Id zaglavlja
  • Praćenje napretka — Opt-in SSE event: progress događaji putem X-OmniRoute-Progress: true zaglavlja

Prevoditeljsko igralište

Pristup putem** Nadzorna ploča → prevoditelj** . Otklonite pogreške i vizualizirajte kako OmniRoute prevodi API zahtjeve između pružatelja usluga.

Način rada Svrha
Igralište Odaberite source/target formate, zalijepite zahtjev i odmah pogledajte prevedeni izlaz
Chat Tester Šaljite poruke chata uživo putem proxyja i pregledajte cijeli request/response ciklus
Ispitni stol Pokrenite skupne testove u više kombinacija formata da biste provjerili točnost prijevoda
Monitor uživo Gledajte prijevode u stvarnom vremenu dok zahtjevi prolaze kroz proxy

Slučajevi upotrebe:

  • Otkrijte zašto određena client/provider kombinacija ne uspijeva
  • Provjerite prevode li se oznake za razmišljanje, pozivi alata i upiti sustava ispravno
  • Usporedite razlike u formatu između formata OpenAI, Claude, Gemini i Responses API

Strategije usmjeravanja

Konfigurirajte putem** Nadzorna ploča → Postavke → Usmjeravanje** . Nadzorna ploča otkriva šest najčešće korištenih strategija; kombinacije i automatski usmjerivač interno podržavaju širi skup.

Strategije vidljive na nadzornoj ploči (usmjeravanje na razini računa):

Strategija Opis
Prvo ispunite Koristi račune prema redoslijedu prioriteta — primarni račun obrađuje sve zahtjeve dok ne postane nedostupan
Razigravanje Kruži kroz sve račune s podesivim ljepljivim ograničenjem (zadano: 3 poziva po računu)
P2C (Moć dva izbora) Odabire 2 nasumična računa i usmjerava na zdraviji — uravnotežuje opterećenje sa sviješću o zdravlju
Slučajno Nasumično odabire račun za svaki zahtjev koristeći Fisher-Yatesovo miješanje
Najmanje korišteno Usmjerava prema računu s najstarijom lastUsedAt vremenskom oznakom, ravnomjerno raspoređujući promet
Optimizirani troškovi Usmjerava prema računu s najnižom vrijednošću prioriteta, optimizirajući za pružatelje s najnižom cijenom

Napredne kombinirane i automatske strategije (podesivo po kombinaciji ili putem auto/* prefiksa — vidi AUTO-COMBO.md ):

  • priority — strogi red, nikad kružno
  • weighted — proporcionalni promet podijeljen po težinama po modelu
  • fill-first — pražnjenje prvog modela dok se ne dostignu ograničenja
  • round-robin / strict-random / random
  • p2c (Moć dva izbora)
  • least-used i cost-optimized
  • auto — vođeno bodovanjem svih kandidata
  • lkgp (Last Known Good Provider) — pričvršćuje na posljednjeg uspješnog pružatelja, a zatim se vraća na pravila
  • context-optimized — odabire model s najvećim prozorom slobodnog konteksta
  • context-relay — lanci dugokontekstualnih modela za naknadne zaokrete

Vanjsko ljepljivo zaglavlje sesije

Za vanjski afinitet sesije (na primjer, Claude Code/Codex agenti iza obrnutih proxyja), pošaljite:

X-Session-Id: your-session-key

OmniRoute također prihvaća x_session_id i vraća efektivni ključ sesije u X-OmniRoute-Session-Id.

Ako koristite Nginx i šaljete zaglavlja obrazaca podvlake, omogućite:

underscores_in_headers on;

Zamjenski nazivi modela

Stvorite uzorke zamjenskih znakova za ponovno mapiranje naziva modela:

Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-6
Pattern: gpt-*               →  Target: gh/gpt-5.3-codex

Zamjenski znakovi podržavaju * (bilo koje znakove) i ? (jedan znak).

Zamjenski lanci

Definirajte globalne rezervne lance koji se primjenjuju na sve zahtjeve:

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

Uobičajene kombinacije pružatelja usluga i obrasci usmjeravanja

Ovdje su primjeri uzoraka za kombiniranje više pružatelja usluga i usmjeravanje između njih u OmniRoute:

1. Kombinacija agenta za kodiranje: vrhunsko rasuđivanje uz pomoć Cost/Speed

Idealno za agente za kodiranje (OpenCode, Claude kod, Cursor, Cline). U početku usmjerava na granične modele razmišljanja, vraćajući se na modele brzog kodiranja u slučaju iscrpljenosti kvote ili grešaka.

  • Nadzorna ploča : Kombinacije → Nova kombinacija → Naziv: agent-coding → Strategija: Priority
  • Modeli :
    1. claude/claude-sonnet-4-6 (primarni agent za kodiranje)
    2. openai/gpt-4o (Sekundarna zamjena visokog kapaciteta)
    3. deepseek/deepseek-v4-flash (visokoučinkovita, isplativa zamjena)
# Example via API
curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent-coding",
    "strategy": "priority",
    "models": [
      { "model": "claude/claude-sonnet-4-6" },
      { "model": "openai/gpt-4o" },
      { "model": "deepseek/deepseek-v4-flash" }
    ]
  }'

2. Free-Tier Auto Failover Combo

Povezuje više besplatnih pružatelja usluga bez ključa kako bi se maksimalno povećalo vrijeme rada bez troškova API.

  • Strategija : Least Used ili Round Robin (distribuira opterećenje preko kvota)
  • Modeli :
    1. groq/llama-3.3-70b-versatile
    2. gemini/gemini-2.5-flash
    3. cerebras/gpt-oss-120b
# Example via CLI
omniroute combo create free-stack \
  --models "groq/llama-3.3-70b-versatile,gemini/gemini-2.5-flash,cerebras/gpt-oss-120b" \
  --strategy round-robin

3. Multimodalni / Vision & Text Pipeline

Uparivanje specijaliziranih modela vida s brzom generacijom teksta za tijekove rada koji uključuju razumijevanje slike i generiranje koda.

  • Uzorak : Kombinacija Priority koja prvo navodi modele s vidom, a zadnji model text/code visoke propusnosti.
  • Modeli :
    1. gemini/gemini-2.5-pro (jako image/multimodal razumijevanje)
    2. openai/gpt-4o (uravnotežena vizija i korištenje alata)
    3. deepseek/deepseek-v4-flash (Text/code generacija)

Otpornost i prekidači

Konfigurirajte putem** Nadzorna ploča → Postavke → Otpornost** .

OmniRoute implementira otpornost na razini pružatelja usluga s pet komponenti:

  1. Red čekanja i tempo zahtjeva — Oblikovanje zahtjeva na razini sustava:

    • Zahtjevi po minuti (RPM) — Maksimalan broj zahtjeva po minuti po računu
    • Min. vrijeme između zahtjeva — Minimalni razmak u milisekundama između zahtjeva
    • Maks. istodobnih zahtjeva — Maksimalan broj istodobnih zahtjeva po računu

  2. Hlađenje veze — Konfiguracija po vrsti autentifikacije za jednu vezu nakon neuspjeha koji se mogu ponoviti:

    • Osnovno hlađenje — Zadani prozor za hlađenje za kvarove uzvoda koji se mogu ponovno pokušati
    • Koristite upstream savjete za ponovni pokušaj — Poštuje mjerodavne savjete Retry-After ili poništavanje ako su navedeni
    • Maks. koraci odustajanja — Maksimalna eksponencijalna razina povlačenja za opetovane kvarove

  3. Prekidač strujnog kruga dobavljača — Prati kvarove dobavljača s kraja na kraj, označava da je usluga degradiran na konfiguriranom pragu upozorenja i otvara prekidač kada se dosegne konfigurirani prag kvara:

    • Prag degradacije — Uzastopni kvarovi pružatelja prije ulaska DEGRADED
    • Prag neuspjeha — Uzastopni kvarovi pružatelja prije ulaska OPEN
    • Poništi vremensko ograničenje — Vremenski okvir prije ponovnog testiranja pružatelja usluga
    • CLOSED (Zdravo) — Zahtjevi teku normalno
    • DEGRADED — Zahtjevi i dalje teku dok se prate povišeni kvarovi
    • OPEN — Davatelj je privremeno blokiran nakon opetovanih kvarova
    • HALF_OPEN — Testiranje je li se pružatelj oporavio

    Ograničenja stope 429 s opsegom veze ostaju** Hlađenje veze** i ne računaju se prema razbijaču pružatelja usluga.

    Stanje izvođenja prekidača pružatelja prikazano je na** Nadzorna ploča → Zdravlje** samo.

  4. Pričekajte hlađenje — Ako se svaka kandidatska veza već hladi, OmniRoute može pričekati najranije hlađenje i automatski ponovno pokušati isti zahtjev klijenta.

  5. Automatsko otkrivanje ograničenja brzine — Kada pružatelji uzlaznih usluga vrate eksplicitne prozore čekanja, ti savjeti nadjačavaju hlađenje lokalne veze kada je postavka omogućena.

Stručni savjet: Koristite** Zdravlje** stranicu za pregled i resetiranje prekidača pružatelja usluga uživo nakon prekida. Stranica Resilience mijenja samo konfiguraciju.

Izvoz / uvoz baze podataka

Upravljanje sigurnosnim kopijama baze podataka u** Nadzorna ploča → Postavke → Sustav i pohrana** .

Akcijski Opis
Izvoz baze podataka Preuzima trenutnu SQLite bazu podataka kao .sqlite datoteku
Izvezi sve (.tar.gz) Preuzima punu sigurnosnu arhivu uključujući: bazu podataka, postavke, kombinacije, veze pružatelja (bez vjerodajnica), metapodatke API ključa
Uvoz baze podataka Prenesite .sqlite datoteku da biste zamijenili trenutnu bazu podataka. Sigurnosna kopija prije uvoza automatski se stvara osim ako DISABLE_SQLITE_AUTO_BACKUP=true 
# API: Export database
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API: Export all (full archive)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

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

Validacija uvoza: Uvezenoj se datoteci provjerava integritet (SQLite pragma check), potrebne tablice (provider_connections, provider_nodes, combos, api_keys) i veličina (maksimalno 100 MB).

Slučajevi upotrebe:

  • Migracija OmniRoute između računala
  • Stvorite vanjske sigurnosne kopije za oporavak od katastrofe
  • Dijelite konfiguracije između članova tima (izvezite svu arhivu dijeljenja → )

Nadzorna ploča postavki

Stranica s postavkama organizirana je u** 7 kartica** za jednostavnu navigaciju:

tab Sadržaj
General Alati za pohranu sustava, zadano ponašanje, vidljivost tunela krajnje točke
Izgled Kontrole teme (light/dark/system), vidljivost bočne trake, prekidači panela za kartice Cloudflare/Tailscale/ngrok tunela
AI Proračun za razmišljanje (prolazni / auto-strip / custom / adaptive — vidi THINKING_BUDGET.md ), globalni sistemski prompt, brza statistika predmemorije
Sigurnost Login/Password postavke, IP kontrola pristupa, API auth za /models, blokiranje pružatelja usluga, zaštita od brzog ubacivanja
Usmjeravanje Globalna strategija usmjeravanja (Fill First / Round Robin / P2C / Random / Least Used / Cost Optimized), zamjenski nazivi modela, rezervni lanci, zadane kombinacije
Elastičnost Red čekanja zahtjeva, hlađenje veze, konfiguracija prekidača pružatelja usluga i ponašanje čekanja na hlađenje
Napredno Globalna proxy konfiguracija (HTTP/SOCKS5), proxy nadjačavanja po pružatelju

Općenito više ne duplira zapise samo za čitanje i predmemoriju bilješki. Zadržavanje baze podataka i postavke optimizacije održavaju se kroz /api/settings/database; ručno brisanje predmemorije koristi DELETE /api/cache. Ograničenja redaka dnevnika zahtjeva i proxyja kontroliraju CALL_LOGS_TABLE_MAX_ROWS i PROXY_LOGS_TABLE_MAX_ROWS.

Upravljanje troškovima i proračunom

Pristup putem** Nadzorna ploča → Troškovi** .

tab Svrha
Proračun Postavite ograničenja potrošnje po API ključu sa daily/weekly/monthly proračunima i praćenjem u stvarnom vremenu
Cijene Pregledajte i uredite unose modela cijena — cijena po 1K input/output tokena po pružatelju 
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
  -H "Content-Type: application/json" \
  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'

# API: Get current budget status
curl http://localhost:20128/api/usage/budget

Praćenje troškova: Svaki zahtjev bilježi korištenje tokena i izračunava trošak pomoću tablice cijena. Pogledajte raščlambe u** Upotreba nadzorne ploče →** prema pružatelju, modelu i API ključu.

Audio transkripcija

OmniRoute podržava audio transkripciju putem OpenAI-kompatibilne endpoint:

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

# Example with 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 je izvorni Deepgramov put i treba Deepgram API ključ. Ako je konfiguriran samo OpenRouter, koristite openrouter/deepgram/nova-3.

Govor u tekst (transkripcija) pružatelji usluga:

  • openai/ (kompatibilan sa šapatom)
  • groq/ (Groq Whisper Turbo)
  • deepgram/ (obitelj Nova)
  • assemblyai/
  • nvidia/ (papagaj, kanarinac)
  • huggingface/ (varijante šapatom)
  • qwen/

Tekst u govor (POST /v1/audio/speech) pružatelji usluga:

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

Podržani audio formati za transkripciju: mp3, wav, m4a, flac, ogg, webm. TTS izlazni formati ovise o pružatelju (mp3, wav, opus, pcm, mulaw).

Kombinirane strategije balansiranja

Konfigurirajte balansiranje po kombinaciji** Nadzorna ploča → kombinacije → Create/Edit → strategija** .

Strategija Opis
Round-Robin Rotira kroz modele uzastopno
Prioritet Uvijek isprobava prvi model; vraća se samo na grešku
Slučajno Odabire slučajni model iz kombinacije za svaki zahtjev
Ponderirano Rute proporcionalno na temelju dodijeljenih težina po modelu
Najmanje korišteno Usmjerava do modela s najmanje nedavnih zahtjeva (koristi kombiniranu metriku)
Troškovno optimiziran Rute do najjeftinijeg dostupnog modela (koristi tablicu cijena)

Mogu se postaviti globalne zadane kombinacije** Nadzorna ploča → Postavke → Usmjeravanje → Combo Defaults** . Combo target timeout prema zadanim postavkama nasljeđuje trenutni timeout zahtjeva. Koristiti** Ciljano vrijeme čekanja (sekunde)** na zadanim postavkama kombinacije ili pojedinačnoj kombinaciji samo kada bi kraće ograničenje po cilju trebalo pokrenuti brže vraćanje.

Kombinirane optimizacije bez kašnjenja su opt-in. Otiđi** Optimizacije bez kašnjenja** onemogućeno kako bi se spriječilo da ove značajke latencije utrkuju rezervne ciljeve, preskaču ciljeve na temelju TTFT povijesti ili komprimiraju rezervne zahtjeve; omogućavanje omogućuje konfiguriranu zaštitu, prediktivno preskakanje TTFT -a i proaktivnu pomoćnu kompresiju za razmjenu vjernosti routing/request za nižu latenciju repa.

Onemogući** Međuspremnik tokena obrazloženja** kada uzvodni pružatelji usluga zahtijevaju stroga ograničenja max_tokens / maxOutputTokens. Kada je omogućeno, kombinirano usmjeravanje samo dodaje prostor za model rezoniranja za modele s poznatim ograničenjem izlaza i ostavlja ograničenje tokena klijenta nepromijenjenim kada bi vrijednost sigurnog međuspremnika premašila to ograničenje. Ako je ograničenje klijenta već iznad poznatog ograničenja, OmniRoute ga spušta na to ograničenje prije slanja uzlaznog zahtjeva.

Nadzorna ploča zdravlja

Pristup putem** Nadzorna ploča → Zdravlje** . Pregled stanja sustava u stvarnom vremenu sa 6 kartica:

Kartica Što pokazuje
Status sustava Vrijeme rada, verzija, upotreba memorije, direktorij podataka
Zdravlje pružatelja usluga Stanje izvođenja prekidača globalnog dobavljača
Ograničenja stope Hlađenja aktivne veze po računu s preostalim vremenom
Aktivna zaključavanja Aktivna zaključavanja i privremena isključenja na temelju modela
Predmemorija potpisa Statistika predmemorije za deduplikaciju (aktivni ključevi, stopa pogodaka)
Telemetrija kašnjenja p50/p95/p99 agregacija kašnjenja po pružatelju

Stručni savjet: Stranica Zdravlje automatski se osvježava svakih 10 sekundi. Upotrijebite karticu prekidača kako biste identificirali koji pružatelji usluga imaju problema.

🤖 Automatsko usmjeravanje (bez konfiguracije)

OmniRoute dolazi s usmjerivačem temeljenim na bodovanju koji automatski bira najbolji model za svaki zahtjev među svim povezanim pružateljima usluga — nema potrebe za održavanjem kombinacija. Samo pošaljite zahtjev s jednim od auto/* prefiksa i OmniRoute će u hodu sastaviti virtualnu kombinaciju, bodujući kandidate na temelju latencije, troška, stope uspjeha, prilagodbe konteksta, prikladnosti modela za zadatak, nedavnih neuspjeha, kvote i stanja sklopke za prekid (circuit-breaker).

Prefiks Optimizira za
auto Balansirana zadana postavka (latencija × trošak × stopa uspjeha)
auto/coding Zadaci kodiranja: preferira Claude, GPT-5, GLM, Kimi, Qwen Coder, DeepSeek coder modele
auto/cheap Najniža cijena po tokenu, prihvaća veću latenciju
auto/fast Najniža latencija, zanemaruje trošak
auto/offline Samo lokalni pružatelji (Ollama, vLLM, llama.cpp) — korisno za izolirane (air-gapped) sustave
auto/smart Prvenstveno kvaliteta zaključivanja (Opus, GPT-5 xhigh, R1, GLM 5.1 reasoning)
auto/lkgp "Last Known Good Provider" — vezuje se na posljednjeg uspješnog pružatelja, zatim se vraća na pravila

Primjer:

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": "Refaktoriraj ovu Python funkciju" }],
    "stream": true
  }'

Automatski usmjerivač je detaljno opisan u AUTO-COMBO.md — uključujući kako podesiti težine bodovanja, staviti pružatelje na crnu listu i pregledati odluke o usmjeravanju u Dashboard → Auto Combo.

🔌 Integracija s MCP i A2A

OmniRoute je istovremeno MCP poslužitelj (Model Context Protocol) i A2A poslužitelj (Agent-to-Agent JSON-RPC 2.0). Svaki IDE ili agentski host kompatibilan s MCP-om može izravno pozivati OmniRoute alate — bez potrebe za dodatnim omotačem.

MCP prijenosi

  • SSE: http://localhost:20128/api/mcp/sse
  • Streamable HTTP: http://localhost:20128/api/mcp/stream
  • stdio: omniroute --mcp (za IDE dodatke koji preferiraju stdio)

Povezivanje s Claude Desktop

Uredite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ili odgovarajuću datoteku na Windows/Linux sustavu:

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

Povezivanje s Cursor / Continue / VS Code MCP

Koristite SSE URL http://localhost:20128/api/mcp/sse i Bearer API ključ generiran u Dashboard → API Keys.

Opsezi (Scopes)

MCP trenutno definira 32 imenovana opsega. Svaki Bearer ključ može se ograničiti na određene opsege — pogledajte MCP-SERVER.md za autoritativni popis opsega i alata, te A2A-SERVER.md za JSON-RPC shemu.

🧠 Sustav vještina

OmniRoute izlaže proširivi okvir vještina (src/lib/skills/) tako da agenti i A2A krajnja točka mogu izvršavati domenski specifične rutine (npr. code-review, summarize, extract-facts, web-research).

  • Marketplace sučelje — Pregledajte i instalirajte vještine putem Dashboard → Skills
  • Opsezi po ključu — Ograničite koji API ključevi mogu pozivati koje vještine
  • Prilagođene vještine — Dodajte TypeScript datoteku u src/lib/a2a/skills/, registrirajte je, i odmah postaje pozivljiva putem A2A

Potpuna referenca: SKILLS.md.

💾 Sustav memorije

OmniRoute pohranjuje dugoročnu konverzacijsku memoriju s hibridnim dohvaćanjem:

  • SQLite FTS5 za pretraživanje po ključnim riječima kroz prošle interakcije
  • Qdrant vektorska pohrana (opcionalno) za semantičko dosjećanje
  • Automatsko izdvajanje činjenica — entiteti, preferencije i odluke sažimaju se nakon svake sesije i pohranjuju u tablicu memory_facts
  • Memorije su ograničene po API ključu i po sesiji

Upravljajte memorijom u Dashboard → Memory (pretraživanje, uređivanje, izvoz, brisanje). HTTP sučelje (/api/memory/*) omogućuje agentima programsko slanje i upitivanje činjenica — pogledajte MEMORY.md.

🔔 Webhooks

Pretplatite se na OmniRoute događaje za praćenje i automatizaciju u stvarnom vremenu.

  • Kreirajte webhook u Dashboard → Webhooks s ciljnim URL-om i HMAC tajnom za potpisivanje
  • Dostupni događaji: request.completed, request.failed, provider.unavailable, budget.exceeded, combo.switched, circuit_breaker.opened, circuit_breaker.closed
  • Svaki payload uključuje X-OmniRoute-Signature (HMAC-SHA256) za provjeru
  • Ponovni pokušaji: 3 pokušaja s eksponencijalnim odgađanjem, zatim red za neisporučene poruke (dead-letter queue)

Potpuna shema u WEBHOOKS.md.

☁️ Cloud Agenti

OmniRoute se integrira s cloud agentima za programiranje (OpenAI Codex Cloud, Devin, Jules, Antigravity) tako da možete pokretati dugotrajne zadatke iz istog nadzorne ploče koja upravlja vašim lokalnim usmjeravanjem.

  • Kreirajte zadatke u Dashboard → Cloud Agents ili putem POST /api/v1/agents/tasks
  • Praćenje statusa, zapisa i artefakata po zadatku
  • Vlastiti API ključ za svakog davatelja usluga — vjerodajnice nikada ne izlaze iz OmniRoute instance

Potpuna referenca: CLOUD_AGENT.md.

🛠️ Programsko upravljanje

Možete upravljati svakim OmniRoute resursom (davatelji usluga, kombinacije, ključevi, postavke) putem HTTP-a koristeći Bearer ključ s opsegom manage.

Generirajte ključ u Dashboard → API Keys → New Key → Scope: manage, zatim:

# Popis davatelja usluga
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# Dodavanje veze s davateljem usluga
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" }'

# Kreiranje kombinacije
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" }] }'

# Popis/kreiranje API ključeva
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"] }'

Pogledajte API_REFERENCE.md za potpuni katalog krajnjih točaka i sheme zahtjeva/odgovora.

💻 Interni CLI

OmniRoute isporučuje interni CLI (omniroute …) za postavljanje, dijagnostiku i kontrolu izvođenja. Ovo je odvojeno od stranice "CLI Tools" u nadzornoj ploči, koja konfigurira CLI alate trećih strana (Claude Code, Cursor, Codex, Cline, …) da mogu komunicirati s OmniRoute-om.

omniroute setup                    # Interaktivni čarobnjak (lozinka, dobavljači, kombinacije)
omniroute setup --non-interactive  # Prilagođeno za CI
omniroute doctor                   # Dijagnostika stanja (podatkovni direktorij, baza podataka, dobavljači, portovi)
omniroute providers available      # Ispis podržanih dobavljača
omniroute providers list           # Ispis konfiguriranih veza
omniroute providers test <id>      # Testiranje veze dobavljača u stvarnom vremenu
omniroute combos list              # Ispis kombinacija
omniroute combos switch <name>     # Postavljanje zadane kombinacije
omniroute models                   # Ispis dostupnih modela (--json, --search)
omniroute keys add | list | remove # Upravljanje API ključevima iz terminala
omniroute backup                   # Snimka konfiguracije i baze podataka
omniroute restore [<timestamp>]    # Vraćanje iz snimke
omniroute health                   # Detaljno stanje (breakeri, predmemorija, memorija)
omniroute quota                    # Iskorištenost kvote dobavljača
omniroute mcp status                # Status MCP servera
omniroute a2a status                # Status A2A servera
omniroute tunnel list|create|stop  # Cloudflare/Tailscale/ngrok tuneli
omniroute reset-password           # Resetiranje administratorske lozinke
omniroute --mcp                    # Pokretanje MCP servera preko stdio
omniroute --port 3000              # Pokretanje servera na prilagođenom portu

Savjet: kombinirajte omniroute doctor --json s vašim alatom za nadzor za obavijesti o neispravnim vezama s dobavljačima.

🖥️ Desktop aplikacija (Electron)

OmniRoute je dostupan kao izvorna desktop aplikacija za Windows, macOS i Linux.

Instalacija

# Iz direktorija electron:
cd electron
npm install

# Razvojni način rada (spajanje na pokrenuti Next.js razvojni server):
npm run dev

# Produkcijski način rada (koristi samostalnu (standalone) izgradnju):
npm start

Izgradnja instalacijskih paketa

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

Izlaz → electron/dist-electron/

Ključne značajke

Značajka Opis
Spremnost servera Provjerava server prije prikaza prozora (bez praznog zaslona)
Sistemska traka Umanjivanje u traku, promjena porta, izlaz iz izbornika trake
Upravljanje portovima Promjena porta servera iz trake (automatski ponovno pokreće server)
Politika sigurnosti sadržaja (Content Security Policy) Restriktivna CSP putem sesijskih zaglavlja
Jedinstvena instanca Samo jedna instanca aplikacije može biti pokrenuta u isto vrijeme
Izvanmrežni način rada Ugrađeni Next.js server radi bez internetske veze

Varijable okoline

Varijabla Zadano Opis
OMNIROUTE_PORT 20128 Port servera
OMNIROUTE_MEMORY_MB 512 Ograničenje memorijske hrpe (heap) za Node.js (64–16384 MB)

📖 Potpuna dokumentacija: electron/README.md