# دليل المستخدم

🌐 **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)

---

## 💰 لمحة سريعة عن الأسعار

| الطبقة                             | مقدم                                | التكلفة                | إعادة ضبط الحصص         | الأفضل لـ                              |
| ---------------------------------- | ----------------------------------- | ---------------------- | ----------------------- | -------------------------------------- |
| **💳الإشتراك**                     | كلود كود (برو)                      | 20 دولارًا شهريًا      | 5 ساعات + أسبوعي        | اشتركت بالفعل                          |
|                                    | الدستور الغذائي (زائد / برو)        | 20-200 دولار شهريًا    | 5 ساعات + أسبوعي        | مستخدمي OpenAI                         |
|                                    | الجوزاء CLI                         | **مجاني**              | 180 ألف/شهر + 1 ألف/يوم | الجميع!                                |
|                                    | جيثب مساعد الطيار                   | 10-19 دولارًا شهريًا   | شهري                    | مستخدمي جيثب                           |
| **🔑 مفتاح واجهة برمجة التطبيقات** | ديب سيك                             | الدفع لكل استخدام      | لا شيء                  | الاستدلال الرخيص                       |
|                                    | جروك                                | الدفع لكل استخدام      | لا شيء                  | الاستدلال فائق السرعة                  |
|                                    | xAI (جروك)                          | الدفع لكل استخدام      | لا شيء                  | جروك 4 المنطق                          |
|                                    | ميسترال                             | الدفع لكل استخدام      | لا شيء                  | النماذج التي يستضيفها الاتحاد الأوروبي |
|                                    | الحيرة                              | الدفع لكل استخدام      | لا شيء                  | البحث المعزز                           |
|                                    | معا منظمة العفو الدولية             | الدفع لكل استخدام      | لا شيء                  | نماذج مفتوحة المصدر                    |
|                                    | الألعاب النارية منظمة العفو الدولية | الدفع لكل استخدام      | لا شيء                  | صور التدفق السريع                      |
|                                    | المخيخ                              | الدفع لكل استخدام      | لا شيء                  | سرعة على نطاق الرقاقة                  |
|                                    | كوهير                               | الدفع لكل استخدام      | لا شيء                  | الأمر R+ RAG                           |
|                                    | نفيديا نيم                          | الدفع لكل استخدام      | لا شيء                  | نماذج المؤسسات                         |
| **💰 رخيص**                        | جي إل إم-4.7                        | 0.6 دولار/1 مليون      | يوميا 10 صباحا          | نسخة احتياطية للميزانية                |
|                                    | ميني ماكس M2.1                      | 0.2 دولار/1 مليون      | المتداول لمدة 5 ساعات   | الخيار الأرخص                          |
|                                    | كيمي ك2                             | 9 دولارات شهريًا مسطحة | 10 مليون رمز/شهر        | التكلفة المتوقعة                       |
| **🆓مجانًا**                       | اي فلو                              | $0                     | غير محدود               | 8 نماذج مجانية                         |
|                                    | كوين                                | $0                     | غير محدود               | 3 نماذج مجانية                         |
|                                    | كيرو                                | $0                     | غير محدود               | كلود مجاني                             |

**💡 نصيحة احترافية:** ابدأ مع مجموعة Gemini CLI (180 ألفًا مجانًا شهريًا) + مجموعة 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: "أريد تكلفة صفرية"

**المشكلة:** لا أستطيع تحمل تكلفة الاشتراكات، وتحتاج إلى ترميز يعتمد على الذكاء الاصطناعي

```
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 ساعة طوال أيام الأسبوع، دون انقطاع"

**المشكلة:** المواعيد النهائية، لا أستطيع تحمل فترات التوقف عن العمل

```
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: "أريد ذكاءً اصطناعيًا مجانيًا في OpenClaw"

**المشكلة:** تحتاج إلى مساعد الذكاء الاصطناعي في تطبيقات المراسلة، مجانًا تمامًا

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

---

## 📖 إعداد الموفر

### 🔐 مقدمي الاشتراكات

#### كلود كود (برو/ماكس)

```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 (180 ألفًا شهريًا مجانًا!)

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

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

**أفضل قيمة:** طبقة مجانية ضخمة! استخدم هذا قبل المستويات المدفوعة.

#### مساعد جيثب

```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 من خطة الترميز
3. لوحة المعلومات → إضافة مفتاح واجهة برمجة التطبيقات: الموفر: `glm`، مفتاح واجهة برمجة التطبيقات: `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` — **نصيحة احترافية:** الخيار الأرخص للسياق الطويل (مليون رمز)!

#### كيمي K2 (شقة بقيمة 9 دولارات في الشهر)

1. الاشتراك: [Moonshot AI](https://platform.moonshot.ai/)
2. احصل على مفتاح API → لوحة المعلومات → إضافة مفتاح API

**الاستخدام:** `kimi/kimi-latest` — **نصيحة احترافية:** سعر ثابت قدره 9 دولارات شهريًا مقابل 10 ملايين رمز مميز = 0.90 دولارًا أمريكيًا/التكلفة الفعلية لمليون واحد!

### 🆓 مقدمي الخدمة مجانًا

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

#### كوين (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

### بيئة تطوير متكاملة للمؤشر

```
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"
}
```

### كوديكس سطر الأوامر

```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 → التكوين التلقائي

### كلاين / متابعة / 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`                       | دليل البيانات (ديسيبل، الاستخدام، السجلات)                       |
| `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`                              | فرض مفتاح Bearer API على `/v1/*`                                 |
| `ENABLE_REQUEST_LOGS` | `false`                              | تمكين سجلات الطلب/الاستجابة                                      |
| `AUTH_COOKIE_SECURE`  | `false`                              | فرض ملف تعريف ارتباط المصادقة `Secure` (خلف الوكيل العكسي HTTPS) |

للحصول على مرجع متغير البيئة الكامل، راجع [README](../README.md).

---

## 📊 الموديلات المتوفرة

<details>
<summary><b>عرض جميع الموديلات المتاحة</b></summary>

**كود كلود (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`

**المخطوطة (`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 (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`

**GLM (`glm/`)** — 0.6 دولار/1 مليون: `glm/glm-4.7`

**ميني ماكس (`minimax/`)** — 0.2 دولار/1 مليون: `minimax/MiniMax-M2.1`

**iFlow (`if/`)** — مجانًا: `if/kimi-k2-thinking`، `if/qwen3-coder-plus`، `if/deepseek-r1`

**كوين (`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/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`

** معًا الذكاء الاصطناعي (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`

**الذكاء الاصطناعي للألعاب النارية (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`

** سيريبراس (`cerebras/`)**: `cerebras/llama-3.3-70b`

**الترابط (`cohere/`)**: `cohere/command-r-plus-08-2024`

** نفيديا نيم (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`

</details>

---

## 🧩 ميزات متقدمة

### نماذج مخصصة

أضف أي معرف نموذج إلى أي مزود دون انتظار تحديث التطبيق:

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

**الأسبقية:** خاص بالمفتاح ← خاص بالسرد والسرد ← خاص بالموفر ← عالمي ← البيئة.

### واجهة برمجة تطبيقات الكتالوج النموذجي

```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`)
- **صلاحية الطلب** — إلغاء تكرار الطلبات خلال 5 ثوانٍ عبر رأس `Idempotency-Key` أو `X-Request-Id`
- **تتبع التقدم** — الاشتراك في أحداث SSE `event: progress` عبر رأس `X-OmniRoute-Progress: true`

---

### ملعب المترجم

الوصول عبر **لوحة المعلومات → المترجم**. تصحيح الأخطاء وتصور كيفية قيام OmniRoute بترجمة طلبات واجهة برمجة التطبيقات (API) بين مقدمي الخدمة.

| الوضع                | الغرض                                                                         |
| -------------------- | ----------------------------------------------------------------------------- |
| **ساحة اللعب**       | حدد تنسيقات المصدر/الهدف، والصق طلبًا، وشاهد المخرجات المترجمة على الفور      |
| ** اختبار الدردشة ** | أرسل رسائل الدردشة المباشرة من خلال الوكيل وافحص دورة الطلب/الاستجابة الكاملة |
| ** مقعد الاختبار **  | قم بإجراء اختبارات مجمعة عبر مجموعات تنسيقات متعددة للتحقق من صحة الترجمة     |
| **مراقبة حية**       | شاهد الترجمات في الوقت الفعلي أثناء تدفق الطلبات عبر الوكيل                   |

**حالات الاستخدام:**

- تصحيح سبب فشل مجموعة محددة من العميل/الموفر
- التحقق من ترجمة علامات التفكير واستدعاءات الأدوات ومطالبات النظام بشكل صحيح
- مقارنة اختلافات التنسيق بين تنسيقات OpenAI وClaude وGemini وResponsions API

---

### استراتيجيات التوجيه

قم بالتكوين عبر **لوحة المعلومات → الإعدادات → التوجيه**.

| استراتيجية               | الوصف                                                                                    |
| ------------------------ | ---------------------------------------------------------------------------------------- |
| ** املأ أولا **          | يستخدم الحسابات بترتيب الأولوية — يعالج الحساب الأساسي جميع الطلبات حتى تصبح غير متاحة   |
| ** راوند روبن **         | للتنقل عبر جميع الحسابات بحد ثابت قابل للتكوين (الافتراضي: 3 مكالمات لكل حساب)           |
| **P2C (قوة الاختيارين)** | يختار حسابين عشوائيين ويوجهك إلى الحساب الأكثر صحة - الأرصدة محملة بالوعي الصحي          |
| **عشوائي**               | تحديد حساب عشوائيًا لكل طلب باستخدام خلط 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)** — الحد الأقصى للطلبات في الدقيقة لكل حساب
   - **الحد الأدنى للوقت بين الطلبات** — الحد الأدنى للفجوة بالمللي ثانية بين الطلبات
   - **الحد الأقصى للطلبات المتزامنة** — الحد الأقصى للطلبات المتزامنة لكل حساب
   - انقر **تحرير** للتعديل، ثم **حفظ** أو **إلغاء**. تستمر القيم عبر واجهة برمجة تطبيقات المرونة.

3. **قاطع الدائرة** — يتتبع حالات الفشل لكل مزود ويفتح الدائرة تلقائيًا عند الوصول إلى الحد الأدنى:
   - **مغلق** (صحي) — تتدفق الطلبات بشكل طبيعي
   - **مفتوح** — تم حظر الموفر مؤقتًا بعد الفشل المتكرر
   - **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)، والجداول المطلوبة (`provider_connections`، `provider_nodes`، `combos`، `api_keys`)، والحجم (100 ميجابايت كحد أقصى).

**حالات الاستخدام:**

- ترحيل OmniRoute بين الأجهزة
- إنشاء نسخ احتياطية خارجية للتعافي من الكوارث
- مشاركة التكوينات بين أعضاء الفريق (تصدير الكل → مشاركة الأرشيف)

---

### لوحة تحكم الإعدادات

يتم تنظيم صفحة الإعدادات في 5 علامات تبويب لسهولة التنقل:

| علامة التبويب        | المحتويات                                                                                                                    |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **الأمن**            | إعدادات تسجيل الدخول/كلمة المرور، والتحكم في الوصول إلى IP، ومصادقة API لـ `/models`، وحظر الموفر                            |
| **التوجيه**          | استراتيجية التوجيه العالمية (6 خيارات)، والأسماء المستعارة لنماذج أحرف البدل، والسلاسل الاحتياطية، وافتراضيات التحرير والسرد |
| **المرونة**          | ملفات تعريف الموفر، وحدود الأسعار القابلة للتحرير، وحالة قاطع الدائرة، والسياسات والمعرفات المقفلة                           |
| **الذكاء الاصطناعي** | تكوين ميزانية التفكير، والحقن الفوري للنظام العالمي، وإحصائيات ذاكرة التخزين المؤقت السريعة                                  |
| **متقدم**            | تكوين الوكيل العالمي (HTTP/SOCKS5)                                                                                           |

---

### إدارة التكاليف والميزانية

الوصول عبر **لوحة التحكم ← التكاليف**.

| علامة التبويب | الغرض                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------ |
| **الميزانية** | قم بتعيين حدود الإنفاق لكل مفتاح API باستخدام ميزانيات يومية/أسبوعية/شهرية وتتبع في الوقت الفعلي |
| **التسعير**   | عرض وتحرير إدخالات تسعير النموذج - التكلفة لكل ألف رمز إدخال/إخراج لكل مزود                      |

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

**تتبع التكلفة:** يقوم كل طلب بتسجيل استخدام الرمز المميز وحساب التكلفة باستخدام جدول التسعير. عرض التفاصيل في **لوحة المعلومات → الاستخدام** حسب الموفر والطراز ومفتاح واجهة برمجة التطبيقات.

---

### النسخ الصوتي

يدعم 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`.

---

### استراتيجيات موازنة التحرير والسرد

قم بتكوين التوازن لكل مجموعة في **لوحة المعلومات → المجموعات → إنشاء/تحرير → الإستراتيجية**.

| استراتيجية          | الوصف                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| **جولة روبن**       | يدور عبر النماذج بالتتابع                                                                      |
| **الأولوية**        | يحاول دائمًا النموذج الأول؛ لا يعود إلا على الخطأ                                              |
| **عشوائي**          | يختار نموذجًا عشوائيًا من المجموعة لكل طلب                                                     |
| **المرجح**          | تعتمد المسارات بشكل متناسب على الأوزان المخصصة لكل نموذج                                       |
| **الأقل استخدامًا** | التوجيهات إلى النموذج الذي يحتوي على أقل عدد من الطلبات الأخيرة (يستخدم مقاييس التحرير والسرد) |
| **التكلفة الأمثل**  | الطرق إلى أرخص طراز متاح (يستخدم جدول التسعير)                                                 |

يمكن ضبط إعدادات التحرير والسرد العامة في **لوحة المعلومات → الإعدادات → التوجيه → إعدادات التحرير والسرد الافتراضية**.

---

### لوحة المعلومات الصحية

الوصول عبر **لوحة التحكم → الصحة**. نظرة عامة على صحة النظام في الوقت الحقيقي مع 6 بطاقات:

| بطاقة                              | ما يظهر                                                        |
| ---------------------------------- | -------------------------------------------------------------- |
| **حالة النظام**                    | وقت التشغيل، الإصدار، استخدام الذاكرة، دليل البيانات           |
| ** صحة المزود **                   | حالة قاطع الدائرة الكهربائية لكل مزود (مغلق/مفتوح/نصف مفتوح)   |
| ** حدود المعدل **                  | فترات تهدئة حد المعدل النشط لكل حساب مع الوقت المتبقي          |
| ** عمليات التأمين النشطة **        | تم حظر مقدمي الخدمة مؤقتًا بواسطة سياسة التأمين                |
| ** ذاكرة التخزين المؤقت للتوقيع ** | إحصائيات إلغاء البيانات المكررة (المفاتيح النشطة، معدل الدخول) |
| ** قياس زمن الوصول **              | p50/p95/p99 تجميع زمن الوصول لكل مزود                          |

**نصيحة احترافية:** يتم تحديث صفحة الصحة تلقائيًا كل 10 ثوانٍ. استخدم بطاقة قاطع الدائرة لتحديد مقدمي الخدمة الذين يواجهون مشكلات.
