# Ръководство за потребителя

🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md)

Пълно ръководство за конфигуриране на доставчици, създаване на комбинации, интегриране на CLI инструменти и внедряване на OmniRoute.

---

## Съдържание

- [Pricing at a Glance](#-pricing-at-a-glance)
- [Use Cases](#-use-cases)
- [Provider Setup](#-provider-setup)
- [CLI Integration](#-cli-integration)
- [Deployment](#-deployment)
- [Available Models](#-available-models)
- [Advanced Features](#-advanced-features)

---

## 💰 Ценообразуването с един поглед

| Ниво               | Доставчик         | Цена                  | Нулиране на квота       | Най-добро за              |
| ------------------ | ----------------- | --------------------- | ----------------------- | ------------------------- |
| **💳 АБОНАМЕНТ**   | Claude Code (Pro) | $20/месец             | 5 часа + седмично       | Вече сте абонирани        |
|                    | Codex (Plus/Pro)  | $20-200/месец         | 5 часа + седмично       | Потребители на OpenAI     |
|                    | Gemini CLI        | **БЕЗПЛАТНО**         | 180K/месец + 1K/ден     | всички!                   |
|                    | Копилот на GitHub | $10-19/месец          | Месечно                 | Потребители на GitHub     |
| **🔑 КЛЮЧ ЗА API** | DeepSeek          | Плащане за използване | Няма                    | Евтини разсъждения        |
|                    | Groq              | Плащане за използване | Няма                    | Свръхбърз извод           |
|                    | xAI (Grok)        | Плащане за използване | Няма                    | Грок 4 разсъждения        |
|                    | Мистрал           | Плащане за използване | Няма                    | Хоствани в ЕС модели      |
|                    | Недоумение        | Плащане за използване | Няма                    | Разширено търсене         |
|                    | Заедно AI         | Плащане за използване | Няма                    | Модели с отворен код      |
|                    | Фойерверки AI     | Плащане за използване | Няма                    | Бързи FLUX изображения    |
|                    | Мозъци            | Плащане за използване | Няма                    | Скорост на вафла          |
|                    | Cohere            | Плащане за използване | Няма                    | Команда R+ RAG            |
|                    | NVIDIA NIM        | Плащане за използване | Няма                    | Корпоративни модели       |
| **💰 ЕВТИНО**      | GLM-4.7           | $0,6/1 милион         | Ежедневно 10 сутринта   | Резервно копие на бюджета |
|                    | MiniMax M2.1      | $0,2/1 милион         | 5-часово търкаляне      | Най-евтиният вариант      |
|                    | Кими К2           | $9/месец апартамент   | 10 милиона токена/месец | Предвидими разходи        |
| **🆓 БЕЗПЛАТНО**   | iFlow             | $0                    | Неограничен             | 8 модела безплатно        |
|                    | Куен              | $0                    | Неограничен             | 3 модела безплатно        |
|                    | Киро              | $0                    | Неограничен             | Клод безплатно            |

**💡 Професионален съвет:** Започнете с Gemini CLI (180K безплатно/месец) + iFlow (неограничено безплатно) комбинация = $0 цена!

---

## 🎯 Случаи на употреба

### Случай 1: „Имам абонамент за Claude Pro“

**Проблем:** Квотата изтича неизползвана, ограничения на скоростта по време на тежко кодиране

```
Combo: "maximize-claude"
  1. cc/claude-opus-4-6        (use subscription fully)
  2. glm/glm-4.7               (cheap backup when quota out)
  3. if/kimi-k2-thinking       (free emergency fallback)

Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
```

### Случай 2: „Искам нулеви разходи“

**Проблем:** Не мога да си позволя абонаменти, имам нужда от надеждно AI кодиране

```
Combo: "free-forever"
  1. gc/gemini-3-flash         (180K free/month)
  2. if/kimi-k2-thinking       (unlimited free)
  3. qw/qwen3-coder-plus       (unlimited free)

Monthly cost: $0
Quality: Production-ready models
```

### Случай 3: „Имам нужда от кодиране 24/7, без прекъсвания“

**Проблем:** Крайни срокове, не мога да си позволя престой

```
Combo: "always-on"
  1. cc/claude-opus-4-6        (best quality)
  2. cx/gpt-5.2-codex          (second subscription)
  3. glm/glm-4.7               (cheap, resets daily)
  4. minimax/MiniMax-M2.1      (cheapest, 5h reset)
  5. if/kimi-k2-thinking       (free unlimited)

Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
```

### Случай 4: „Искам БЕЗПЛАТЕН AI в OpenClaw“

**Проблем:** Имате нужда от AI асистент в приложенията за съобщения, напълно безплатно

```
Combo: "openclaw-free"
  1. if/glm-4.7                (unlimited free)
  2. if/minimax-m2.1           (unlimited free)
  3. if/kimi-k2-thinking       (unlimited free)

Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
```

---

## 📖 Настройка на доставчик

### 🔐 Доставчици на абонаменти

#### Claude Code (Pro/Max)

```bash
Dashboard → Providers → Connect Claude Code
→ OAuth login → Auto token refresh
→ 5-hour + weekly quota tracking

Models:
  cc/claude-opus-4-6
  cc/claude-sonnet-4-5-20250929
  cc/claude-haiku-4-5-20251001
```

**Професионален съвет:** Използвайте Opus за сложни задачи, Sonnet за скорост. OmniRoute проследява квота за модел!

#### OpenAI Codex (Plus/Pro)

```bash
Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 5-hour + weekly reset

Models:
  cx/gpt-5.2-codex
  cx/gpt-5.1-codex-max
```

#### Gemini CLI (БЕЗПЛАТНО 180K/месец!)

```bash
Dashboard → Providers → Connect Gemini CLI
→ Google OAuth
→ 180K completions/month + 1K/day

Models:
  gc/gemini-3-flash-preview
  gc/gemini-2.5-pro
```

**Най-добра стойност:** Огромно безплатно ниво! Използвайте това преди платените нива.

#### Копилот на GitHub

```bash
Dashboard → Providers → Connect GitHub
→ OAuth via GitHub
→ Monthly reset (1st of month)

Models:
  gh/gpt-5
  gh/claude-4.5-sonnet
  gh/gemini-3-pro
```

### 💰 Евтини доставчици

#### GLM-4.7 (Ежедневно нулиране, $0,6/1 млн.)

1. Регистрирайте се: [Zhipu AI](https://open.bigmodel.cn/)
2. Вземете API ключ от Coding Plan
3. Табло → Добавяне на API ключ: Доставчик: `glm`, API ключ: `your-key`

**Използване:** `glm/glm-4.7` — **Професионален съвет:** Планът за кодиране предлага 3× квота на цена 1/7! Нулирайте всеки ден в 10:00 ч.

#### MiniMax M2.1 (5 часа нулиране, $0,20/1 млн.)

1. Регистрирайте се: [MiniMax](https://www.minimax.io/)
2. Вземете API ключ → Табло → Добавете API ключ

**Използване:** `minimax/MiniMax-M2.1` — **Професионален съвет:** Най-евтината опция за дълъг контекст (1M токени)!

#### Kimi K2 ($9/месец фиксиран)

1. Абонирайте се: [Moonshot AI](https://platform.moonshot.ai/)
2. Вземете API ключ → Табло → Добавете API ключ

**Използване:** `kimi/kimi-latest` — **Професионален съвет:** Фиксирани $9/месец за 10 милиона токена = $0,90/1 милион ефективна цена!

### 🆓 БЕЗПЛАТНИ доставчици

#### iFlow (8 БЕЗПЛАТНИ модела)

```bash
Dashboard → Connect iFlow → OAuth login → Unlimited usage

Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1
```

#### Qwen (3 БЕЗПЛАТНИ модела)

```bash
Dashboard → Connect Qwen → Device code auth → Unlimited usage

Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
```

#### Киро (Клод БЕЗПЛАТНО)

```bash
Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited

Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
```

---

## 🎨 Комбота

### Пример 1: Увеличаване на абонамента → Евтино архивиране

```
Dashboard → Combos → Create New

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

Use in CLI: premium-coding
```

### Пример 2: Само безплатно (нулева цена)

```
Name: free-combo
Models:
  1. gc/gemini-3-flash-preview (180K free/month)
  2. if/kimi-k2-thinking (unlimited)
  3. qw/qwen3-coder-plus (unlimited)

Cost: $0 forever!
```

---

## 🔧 CLI интеграция

### Курсор IDE

```
Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [from omniroute dashboard]
  Model: cc/claude-opus-4-6
```

### Клод Код

Редактиране на `~/.claude/config.json`:

```json
{
  "anthropic_api_base": "http://localhost:20128/v1",
  "anthropic_api_key": "your-omniroute-api-key"
}
```

### Codex CLI

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

### OpenClaw

Редактиране на `~/.openclaw/openclaw.json`:

```json
{
  "agents": {
    "defaults": {
      "model": { "primary": "omniroute/if/glm-4.7" }
    }
  },
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://localhost:20128/v1",
        "apiKey": "your-omniroute-api-key",
        "api": "openai-completions",
        "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
      }
    }
  }
}
```

**Или използвайте таблото за управление:** CLI инструменти → OpenClaw → Автоматично конфигуриране

### Cline / Продължи / RooCode

```
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
```

---

## 🚀 Внедряване

### Внедряване на VPS

```bash
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
# Or: pm2 start npm --name omniroute -- start
```

### Докер

```bash
# Build image (default = runner-cli with codex/claude/droid preinstalled)
docker build -t omniroute:cli .

# Portable mode (recommended)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```

За интегриран в хост режим с двоични файлове на CLI вижте раздела Docker в основните документи.

### Променливи на средата

| Променлива            | По подразбиране                        | Описание                                                                     |
| --------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
| `JWT_SECRET`          | `omniroute-default-secret-change-me`   | Тайна за подписване на JWT (**промяна в производството**)                    |
| `INITIAL_PASSWORD`    | `123456`                               | Първа парола за влизане                                                      |
| `DATA_DIR`            | `~/.omniroute`                         | Директория с данни (db, използване, регистрационни файлове)                  |
| `PORT`                | рамка по подразбиране                  | Сервизен порт (`20128` в примерите)                                          |
| `HOSTNAME`            | рамка по подразбиране                  | Свързване на хост (Docker по подразбиране е `0.0.0.0`)                       |
| `NODE_ENV`            | по подразбиране по време на изпълнение | Задайте `production` за внедряване                                           |
| `BASE_URL`            | `http://localhost:20128`               | Вътрешен основен URL адрес от страната на сървъра                            |
| `CLOUD_URL`           | `https://omniroute.dev`                | Основен URL адрес на крайна точка за синхронизиране в облак                  |
| `API_KEY_SECRET`      | `endpoint-proxy-api-key-secret`        | HMAC тайна за генерирани API ключове                                         |
| `REQUIRE_API_KEY`     | `false`                                | Прилагане на API ключ на носител на `/v1/*`                                  |
| `ENABLE_REQUEST_LOGS` | `false`                                | Разрешава регистрационни файлове за заявки/отговори                          |
| `AUTH_COOKIE_SECURE`  | `false`                                | Принудително `Secure` бисквитка за удостоверяване (зад HTTPS обратен прокси) |

За пълната справка за променливите на средата вижте [README](../README.md).

---

## 📊 Налични модели

<details>
<summary><b>Вижте всички налични модели</b></summary>

**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`

**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`

**Gemini CLI (`gc/`)** — БЕЗПЛАТНО: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`

**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`

**GLM (`glm/`)** — $0,6/1 млн.: `glm/glm-4.7`

**MiniMax (`minimax/`)** — $0,2/1 млн.: `minimax/MiniMax-M2.1`

**iFlow (`if/`)** — БЕЗПЛАТНО: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`

**Qwen (`qw/`)** — БЕЗПЛАТНО: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`

**Киро (`kr/`)** — БЕЗПЛАТНО: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`

**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`

**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`

**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`

**Мистрал (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`

**Недоумение (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`

**Заедно AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`

**Фойерверки AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`

**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`

**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`

**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`

</details>

---

## 🧩 Разширени функции

### Персонализирани модели

Добавете всеки ID на модел към всеки доставчик, без да чакате актуализация на приложението:

```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}'

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

Или използвайте таблото за управление: **Доставчици → [Доставчик] → Персонализирани модели**.

### Специализирани маршрути на доставчик

Насочвайте заявките директно към конкретен доставчик с валидиране на модела:

```bash
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
```

Префиксът на доставчика се добавя автоматично, ако липсва. Несъответстващите модели връщат `400`.

### Конфигурация на мрежов прокси

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

**Приоритет:** Специфичен за ключ → Специфичен за комбинация → Специфичен за доставчик → Глобален → Среда.

### API за каталог на модели

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

Връща модели, групирани по доставчик с типове (`chat`, `embedding`, `image`).

### Облачно синхронизиране

- Синхронизиране на доставчици, комбинации и настройки на всички устройства
- Автоматична фонова синхронизация с изчакване + бързо отказване
- Предпочитане на сървъра `BASE_URL`/`CLOUD_URL` в производството

### LLM Gateway Intelligence (Фаза 9)

- **Семантичен кеш** — Автоматично кешира нестрийминг, температура=0 отговори (заобикаляне с `X-OmniRoute-No-Cache: true`)
- **Request Idempotency** — Дедупликира заявките в рамките на 5s чрез `Idempotency-Key` или `X-Request-Id` заглавка
- **Проследяване на напредъка** — Включване на SSE `event: progress` събития чрез `X-OmniRoute-Progress: true` заглавка

---

### Площадка за преводачи

Достъп чрез **Табло → Преводач**. Отстранете грешки и визуализирайте как OmniRoute превежда API заявки между доставчици.

| Режим               | Цел                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------- |
| **Детска площадка** | Изберете изходни/целеви формати, поставете заявка и незабавно вижте преведения резултат              |
| **Чат тестер**      | Изпращайте чат съобщения на живо през проксито и проверявайте пълния цикъл на заявка/отговор         |
| **Тестова стенда**  | Изпълнете групови тестове в множество комбинации от формати, за да проверите правилността на превода |
| **Монитор на живо** | Гледайте преводи в реално време, докато заявките преминават през проксито                            |

**Случаи на употреба:**

- Отстраняване на грешки защо конкретна комбинация клиент/доставчик е неуспешна
- Проверете дали мислещите тагове, извикванията на инструменти и системните подкани се превеждат правилно
- Сравнете разликите във форматите между форматите OpenAI, Claude, Gemini и Responses API

---

### Стратегии за маршрутизиране

Конфигурирайте чрез **Табло → Настройки → Маршрутизация**.

| Стратегия                    | Описание                                                                                                       |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Първо попълване**          | Използва акаунти в приоритетен ред — основният акаунт обработва всички заявки, докато стане недостъпен         |
| **Round Robin**              | Преминава през всички акаунти с конфигурируем лепкав лимит (по подразбиране: 3 обаждания на акаунт)            |
| **P2C (Сила на два избора)** | Избира 2 произволни акаунта и маршрути към по-здравословния — балансира натоварването с осъзнаване на здравето |
| **Произволно**               | Произволно избира акаунт за всяка заявка чрез разбъркване на Fisher-Yates                                      |
| **Най-малко използвани**     | Насочва към акаунта с най-стария `lastUsedAt` времеви печат, разпределяйки трафика равномерно                  |
| **Оптимизирани разходи**     | Маршрути към акаунта с най-ниска стойност на приоритет, оптимизиране за доставчици с най-ниска цена            |

#### Псевдоними на модели със заместващи символи

Създайте шаблони със заместващи знаци, за да пренасочите имената на моделите:

```
Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-5-20250929
Pattern: gpt-*               →  Target: gh/gpt-5.1-codex
```

Заместващите знаци поддържат `*` (всякакви знаци) и `?` (единичен знак).

#### Резервни вериги

Дефинирайте глобални резервни вериги, които се прилагат за всички заявки:

```
Chain: production-fallback
  1. cc/claude-opus-4-6
  2. gh/gpt-5.1-codex
  3. glm/glm-4.7
```

---

### Устойчивост и прекъсвачи

Конфигурирайте чрез **Табло → Настройки → Устойчивост**.

OmniRoute прилага устойчивост на ниво доставчик с четири компонента:

1. **Профили на доставчици** — Конфигурация за всеки доставчик за:
   - Праг на повреда (колко повреда преди отваряне)
   - Продължителност на изчакване
   - Чувствителност на откриване на ограничение на скоростта
   - Параметри на експоненциално забавяне

2. **Редактируеми ограничения на скоростта** — Настройки по подразбиране на системно ниво, които могат да се конфигурират в таблото за управление:
   - **Заявки в минута (RPM)** — Максимален брой заявки в минута за акаунт
   - **Минимално време между заявките** — Минимална разлика в милисекунди между заявките
   - **Максимални едновременни заявки** — Максимални едновременни заявки за акаунт
   - Щракнете върху **Редактиране**, за да промените, след това върху **Запазване** или **Отказ**. Стойностите се запазват чрез API за устойчивост.

3. **Прекъсвач на веригата** — Проследява повреди на доставчик и автоматично отваря веригата при достигане на праг:
   - **ЗАТВОРЕНО** (здравословно) — Заявките протичат нормално
   - **OPEN** — Доставчикът е временно блокиран след повтарящи се повреди
   - **HALF_OPEN** — Тестване дали доставчикът се е възстановил

4. **Правила и заключени идентификатори** — Показва състоянието на прекъсвача и заключените идентификатори с възможност за принудително отключване.

5. **Автоматично откриване на ограничение на скоростта** — Наблюдава заглавките `429` и `Retry-After`, за да избегне проактивно достигане на ограниченията на скоростта на доставчика.

**Професионален съвет:** Използвайте бутона **Нулиране на всички**, за да изчистите всички прекъсвачи и изчаквания, когато доставчикът се възстанови от прекъсване.

---

### Експорт/импорт на база данни

Управлявайте резервни копия на бази данни в **Табло → Настройки → Система и съхранение**.

| Действие                             | Описание                                                                                                                                          |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Експортиране на база данни**       | Изтегля текущата база данни SQLite като `.sqlite` файл                                                                                            |
| **Експортиране на всички (.tar.gz)** | Изтегля пълен резервен архив, включително: база данни, настройки, комбинации, връзки с доставчик (без идентификационни данни), API ключ метаданни |
| **Импортиране на база данни**        | Качете файл `.sqlite`, за да замените текущата база данни. Автоматично се създава резервно копие преди импортиране                                |

```bash
# 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"
```

**Проверка на импортиране:** Импортираният файл се валидира за цялост (проверка на SQLite pragma), необходими таблици (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) и размер (макс. 100MB).

**Случаи на употреба:**

- Мигрирайте OmniRoute между машини
- Създаване на външни резервни копия за възстановяване след бедствие
- Споделяне на конфигурации между членовете на екипа (експортиране на всички → споделяне на архив)

---

### Табло за управление на настройките

Страницата с настройки е организирана в 5 раздела за лесна навигация:

| Раздел             | Съдържание                                                                                                                                          |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Сигурност**      | Настройки за вход/парола, IP контрол на достъпа, API удостоверяване за `/models` и блокиране на доставчик                                           |
| **Маршрутизиране** | Стратегия за глобално маршрутизиране (6 опции), псевдоними на модели със заместващи символи, резервни вериги, комбинирани настройки по подразбиране |
| **Устойчивост**    | Профили на доставчици, редактируеми лимити на скоростта, състояние на прекъсвача, политики и заключени идентификатори                               |
| **AI**             | Обмисляне на конфигурация на бюджета, инжектиране на глобална система, статистика на бързия кеш                                                     |
| **Разширено**      | Глобална прокси конфигурация (HTTP/SOCKS5)                                                                                                          |

---

### Управление на разходите и бюджета

Достъп чрез **Табло → Разходи**.

| Раздел     | Цел                                                                                                            |
| ---------- | -------------------------------------------------------------------------------------------------------------- |
| **Бюджет** | Задайте лимити на разходите за API ключ с дневни/седмични/месечни бюджети и проследяване в реално време        |
| **Цени**   | Преглеждайте и редактирайте записи за ценообразуване на модела — цена за 1K входно/изходни токени на доставчик |

```bash
# 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
```

**Проследяване на разходите:** Всяка заявка регистрира използването на токени и изчислява разходите с помощта на таблицата с цените. Вижте разбивки в **Табло за управление → Използване** по доставчик, модел и API ключ.

---

### Аудио транскрипция

OmniRoute поддържа аудио транскрипция чрез OpenAI-съвместима крайна точка:

```bash
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=deepgram/nova-3"
```

Налични доставчици: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).

Поддържани аудио формати: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.

---

### Комбинирани стратегии за балансиране

Конфигурирайте балансирането за комбо в **Табло за управление → Комбота → Създаване/Редактиране → Стратегия**.

| Стратегия                    | Описание                                                                         |
| ---------------------------- | -------------------------------------------------------------------------------- |
| **Round-Robin**              | Върти се през моделите последователно                                            |
| **Приоритет**                | Винаги пробва първия модел; връща се само при грешка                             |
| **Произволно**               | Избира произволен модел от комбинацията за всяка заявка                          |
| **Претеглено**               | Маршрути пропорционално въз основа на зададени тегла за модел                    |
| **Най-малко използвани**     | Насочва към модела с най-малко скорошни заявки (използва комбинирани показатели) |
| **Оптимизиран за разходите** | Маршрути до най-евтиния наличен модел (използва ценова таблица)                  |

Глобалните настройки по подразбиране на комбинацията могат да бъдат зададени в **Табло → Настройки → Маршрут → Настройки по подразбиране на комбинация**.

---

### Здравно табло

Достъп чрез **Табло → Здраве**. Преглед на здравето на системата в реално време с 6 карти:

| Карта                        | Какво показва                                                              |
| ---------------------------- | -------------------------------------------------------------------------- |
| **Състояние на системата**   | Време на работа, версия, използване на паметта, директория с данни         |
| **Здраве на доставчика**     | Състояние на прекъсвача за всеки доставчик (затворен/отворен/полуотворен)  |
| **Ограничения на скоростта** | Активен лимит на изчакване за акаунт с оставащо време                      |
| **Активни блокировки**       | Доставчици, временно блокирани от политиката за блокиране                  |
| **Кеш на подписа**           | Статистика на кеша за дедупликация (активни ключове, процент на попадения) |
| **Телеметрия за забавяне**   | p50/p95/p99 агрегиране на латентност за доставчик                          |

**Професионален съвет:** Страницата Health се опреснява автоматично на всеки 10 секунди. Използвайте картата на прекъсвача, за да идентифицирате кои доставчици имат проблеми.
