# User Guide (Tiếng Việt) 🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/USER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USER_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/USER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USER_GUIDE.md) --- 🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/USER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USER_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/USER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USER_GUIDE.md) Hướng dẫn đầy đủ về cách cấu hình nhà cung cấp, tạo tổ hợp, tích hợp công cụ CLI và triển khai OmniRoute. --- ## Mục lục - [Tổng quan về giá](#-pricing-at-a-glance) - [Các trường hợp sử dụng](#-use-cases) - [Thiết lập nhà cung cấp](#-provider-setup) - [Tích hợp CLI](#-cli-integration) - [Triển khai](#-deployment) - [Các mô hình có sẵn](#-available-models) - [Tính năng nâng cao](#-advanced-features) - [Tự động định tuyến (Không cần cấu hình)](#-auto-routing-zero-config) - [Tích hợp MCP & A2A](#-mcp--a2a-integration) - [Hệ thống kỹ năng](#-skills-system) - [Hệ thống bộ nhớ](#-memory-system) - [Webhook](#-webhooks) - [Tác nhân đám mây](#-cloud-agents) - [Quản lý bằng lập trình](#-programmatic-management) - [CLI nội bộ](#-internal-cli) - [Ứng dụng máy tính để bàn (Electron)](#-desktop-application-electron) --- ## 💰 Tổng quan về giá | Gói | Nhà cung cấp | Chi phí | Chu kỳ đặt lại hạn mức | Phù hợp nhất | | --------------- | ----------------- | -------------------- | -------------------------- | ----------------------------- | | **💳 ĐĂNG KÝ** | Claude Code (Pro) | $20/tháng | 5 giờ + hằng tuần | Người đã đăng ký | | | Codex (Plus/Pro) | $20-200/tháng | 5 giờ + hằng tuần | Người dùng OpenAI | | | GitHub Copilot | $10-19/tháng | Hằng tháng | Người dùng GitHub | | **🔑 API KEY** | DeepSeek | Trả theo mức sử dụng | Không có | Suy luận chi phí thấp | | | Groq | Trả theo mức sử dụng | Không có | Suy luận siêu nhanh | | | xAI (Grok) | Trả theo mức sử dụng | Không có | Khả năng suy luận của Grok 4 | | | Mistral | Trả theo mức sử dụng | Không có | Mô hình lưu trữ tại EU | | | Perplexity | Trả theo mức sử dụng | Không có | Tăng cường bằng tìm kiếm | | | Together AI | Trả theo mức sử dụng | Không có | Mô hình mã nguồn mở | | | Fireworks AI | Trả theo mức sử dụng | Không có | Tạo hình ảnh FLUX nhanh | | | Cerebras | Trả theo mức sử dụng | Không có | Tốc độ ở quy mô wafer | | | Cohere | Trả theo mức sử dụng | Không có | Command R+ RAG | | | NVIDIA NIM | Trả theo mức sử dụng | Không có | Mô hình dành cho doanh nghiệp | | | Baidu Qianfan | Trả theo mức sử dụng | Không có | Mô hình ERNIE | | **💰 GIÁ RẺ** | GLM-4.7 | $0.6/1M | Hằng ngày lúc 10AM | Phương án dự phòng tiết kiệm | | | MiniMax M2.1 | $0.2/1M | Cuốn chiếu 5 giờ | Lựa chọn rẻ nhất | | | Kimi K2 | Cố định $9/tháng | 10M token/tháng | Chi phí dễ dự đoán | | **🆓 MIỄN PHÍ** | Qoder | $0 | Theo giới hạn nhà cung cấp | Kiểm tra danh mục hiện tại | | | Kiro | $0 | ~50 tín dụng/tháng | Claude miễn phí | --- ## 🎯 Các trường hợp sử dụng ### Trường hợp 1: "Tôi có gói đăng ký Claude Pro" **Vấn đề:** Hạn mức hết hạn khi chưa sử dụng, bị giới hạn tốc độ trong lúc lập trình cường độ cao ``` Combo: "maximize-claude" 1. cc/claude-opus-4-7 (tận dụng tối đa gói đăng ký) 2. glm/glm-4.7 (phương án dự phòng giá rẻ khi hết hạn mức) 3. if/qwen3.8-max-preview (phương án dự phòng khẩn cấp miễn phí) Chi phí hằng tháng: $20 (gói đăng ký) + ~$5 (dự phòng) = tổng cộng $25 so với $20 + chạm giới hạn = bực bội ``` ### Trường hợp 2: "Tôi muốn chi phí bằng không" **Vấn đề:** Không đủ khả năng chi trả cho các gói đăng ký, cần AI lập trình đáng tin cậy ``` Combo: "zero-cost" 1. if/kimi-k2.7-code (được liệt kê là có quyền truy cập miễn phí; có thể áp dụng giới hạn tốc độ) 2. kr/qwen3-coder-next (phương án dự phòng Kiro miễn phí) Chi phí hằng tháng: $0 Chất lượng: hãy xác minh mô hình, giới hạn, quyền riêng tư và SLA cho khối lượng công việc của bạn ``` ### Trường hợp 3: "Tôi cần lập trình 24/7, không bị gián đoạn" **Vấn đề:** Có thời hạn gấp, không thể chấp nhận thời gian ngừng hoạt động ``` Combo: "always-on" 1. cc/claude-opus-4-7 (chất lượng tốt nhất) 2. cx/gpt-5.5 (gói đăng ký thứ hai) 3. glm/glm-4.7 (giá rẻ, đặt lại hằng ngày) 4. minimax/MiniMax-M2.1 (rẻ nhất, đặt lại sau 5 giờ) 5. if/deepseek-v4-flash (được liệt kê là có quyền truy cập miễn phí; có thể áp dụng giới hạn tốc độ) Kết quả: 5 lớp dự phòng giúp tăng khả năng phục hồi; tính khả dụng của dịch vụ đầu nguồn không được đảm bảo Chi phí hằng tháng: $20-200 (gói đăng ký) + $10-20 (dự phòng) ``` ### Trường hợp 4: "Tôi muốn AI MIỄN PHÍ trong OpenClaw" **Vấn đề:** Cần trợ lý AI trong các ứng dụng nhắn tin, hoàn toàn miễn phí ``` Combo: "openclaw-free" 1. if/qwen3.8-max-preview (được liệt kê là có quyền truy cập miễn phí; có thể áp dụng giới hạn tốc độ) 2. if/deepseek-v4-flash (được liệt kê là có quyền truy cập miễn phí; có thể áp dụng giới hạn tốc độ) 3. if/kimi-k2.7-code (được liệt kê là có quyền truy cập miễn phí; có thể áp dụng giới hạn tốc độ) Chi phí hằng tháng: $0 Truy cập qua: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... ``` --- ## 📖 Thiết lập nhà cung cấp Để thêm hàng loạt kết nối khóa API từ tệp CSV hoặc JSON, hãy sử dụng **Bảng điều khiển → Nhà cung cấp → Nhập từ tệp**. Các cột được xác định theo vị trí (`provider,name,apiKey,baseUrl,priority`); `provider` phải tồn tại sẵn dưới dạng nhà cung cấp được quản lý hoặc một nút tương thích. Xem [Nhập nhà cung cấp từ tệp CSV hoặc JSON](../providers/CSV-IMPORT.md). ### 🔐 Nhà cung cấp theo gói đăng ký #### Claude Code (Pro/Max) ```bash Bảng điều khiển → Nhà cung cấp → Kết nối Claude Code → Đăng nhập OAuth → Tự động làm mới token → Theo dõi hạn mức 5 giờ + hàng tuần Mô hình: cc/claude-opus-4-7 cc/claude-sonnet-4-6 cc/claude-haiku-4-5-20251001 ``` **Mẹo chuyên nghiệp:** Dùng Opus cho các tác vụ phức tạp, Sonnet khi cần tốc độ. OmniRoute theo dõi hạn mức theo từng mô hình! Không có trình duyệt trên máy chủ OmniRoute? Chạy `claude setup-token` ở bất kỳ đâu đã đăng nhập Claude Code và dán token có thời hạn một năm vào tab **Setup Token**. Xem [Claude Code với setup token](../providers/CLAUDE_CODE_SETUP_TOKEN.md). Các tuyến Claude và tương thích với Claude Code duy trì mức nỗ lực suy luận `max` cho các mô hình Opus và Sonnet. Các mô hình Haiku không chấp nhận mức nỗ lực `max`, vì vậy OmniRoute sẽ hạ yêu cầu đó xuống ngân sách suy luận cao trước khi gửi đến dịch vụ thượng nguồn. #### OpenAI Codex (Plus/Pro) ```bash Bảng điều khiển → Nhà cung cấp → Kết nối Codex → Đăng nhập OAuth (cổng 1455) → Đặt lại sau 5 giờ + hàng tuần Mô hình: cx/gpt-5.5 cx/gpt-5.4 cx/gpt-5.3-codex cx/gpt-5.3-codex-spark ``` #### GitHub Copilot ```bash Bảng điều khiển → Nhà cung cấp → Kết nối GitHub → OAuth qua GitHub → Đặt lại hàng tháng (ngày 1 mỗi tháng) Mô hình: gh/gpt-5.5 gh/gpt-5.4 gh/claude-sonnet-4.6 gh/claude-opus-4.7 gh/gemini-3.1-pro-preview ``` ### 💰 Nhà cung cấp giá rẻ #### GLM-4.7 (Đặt lại hàng ngày, $0.6/1M) 1. Đăng ký: [Zhipu AI](https://open.bigmodel.cn) 2. Lấy khóa API từ Coding Plan 3. Bảng điều khiển → Thêm khóa API: Nhà cung cấp: `glm`, Khóa API: `your-key` **Sử dụng:** `glm/glm-4.7` — **Mẹo chuyên nghiệp:** Coding Plan cung cấp hạn mức gấp 3 lần với chi phí bằng 1/7! Đặt lại hàng ngày lúc 10:00 sáng. #### MiniMax M2.1 (Đặt lại sau 5 giờ, $0.20/1M) 1. Đăng ký: [MiniMax](https://www.minimax.io) 2. Lấy khóa API → Bảng điều khiển → Thêm khóa API **Sử dụng:** `minimax/MiniMax-M2.1` — **Mẹo chuyên nghiệp:** Lựa chọn rẻ nhất cho ngữ cảnh dài (1M token)! #### Kimi K2 (Cố định $9/tháng) 1. Đăng ký gói: [Moonshot AI](https://platform.kimi.ai?aff=omniroute) 2. Lấy khóa API → Bảng điều khiển → Thêm khóa API **Sử dụng:** `kimi/kimi-k2.5` — **Mẹo chuyên nghiệp:** Mức cố định $9/tháng cho 10M token = chi phí thực tế $0.90/1M! #### Baidu Qianfan / ERNIE 1. Đăng ký: [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop) 2. Tạo khóa API Qianfan → Bảng điều khiển → Thêm khóa API: Nhà cung cấp: `qianfan` **Sử dụng:** `qianfan/ernie-5.1`, `qianfan/ernie-x1.1` hoặc một ID mô hình Qianfan tương thích với OpenAI khác. ### 🆓 Nhà cung cấp MIỄN PHÍ Các nhà cung cấp miễn phí không yêu cầu xác thực có một công tắc bên cạnh **Không yêu cầu xác thực** trên trang nhà cung cấp của họ. Việc tắt công tắc sẽ vô hiệu hóa nhà cung cấp đó, xóa nhà cung cấp khỏi các chế độ xem nhà cung cấp đã cấu hình/thu gọn và xóa các mô hình của nhà cung cấp khỏi `/v1/models`. #### Qoder (9 mô hình MIỄN PHÍ) ```bash Bảng điều khiển → Kết nối Qoder → Đăng nhập OAuth → Quyền truy cập phụ thuộc vào các giới hạn hiện tại của nhà cung cấp Mô hình: 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 MIỄN PHÍ) ```bash Bảng điều khiển → Kết nối Kiro → AWS Builder ID hoặc Google/GitHub → ~50 tín dụng/tháng Mô hình: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 ``` --- ## 🎨 Tổ hợp Bạn có thể sắp xếp lại các thẻ tổ hợp trực tiếp trong **Bảng điều khiển → Tổ hợp** bằng cách kéo tay cầm trên mỗi thẻ. Thứ tự được lưu trong SQLite và khôi phục khi tải lại. ### Ví dụ 1: Tối đa hóa gói đăng ký → Phương án dự phòng giá rẻ ``` Bảng điều khiển → Tổ hợp → Tạo mới Tên: premium-coding Mô hình: 1. cc/claude-opus-4-7 (Gói đăng ký chính) 2. glm/glm-4.7 (Phương án dự phòng giá rẻ, $0.6/1M) 3. minimax/MiniMax-M2.7 (Phương án dự phòng rẻ nhất, $0.3/1M) Sử dụng trong CLI: premium-coding ``` ### Ví dụ 2: Chỉ miễn phí (Không tốn chi phí) ``` Tên: free-combo Mô hình: 1. if/kimi-k2.7-code (được liệt kê là có quyền truy cập miễn phí; có thể áp dụng giới hạn của nhà cung cấp) 2. kr/qwen3-coder-next (phương án dự phòng Kiro miễn phí) Chi phí: hiện được liệt kê là $0; các điều khoản và tính khả dụng có thể thay đổi ``` --- ## 🔧 Tích hợp CLI ### Cursor IDE **Sử dụng Cursor làm ứng dụng khách OmniRoute** (định tuyến trò chuyện Cursor thông qua OmniRoute): ``` Cài đặt → Mô hình → Nâng cao: URL cơ sở API OpenAI: http://localhost:20128/v1 Khóa API OpenAI: [từ bảng điều khiển omniroute] Mô hình: cc/claude-opus-4-7 ``` **Sử dụng OmniRoute làm nhà cung cấp Cursor** (OmniRoute gọi đến dịch vụ Cursor thượng nguồn): ưu tiên **Bảng điều khiển → Nhà cung cấp → Cursor → Đăng nhập bằng Cursor**. Trong Docker, hãy xem [`docs/providers/CURSOR-DOCKER.md`](../providers/CURSOR-DOCKER.md). ### Claude Code Chỉnh sửa `~/.claude/settings.json`: ```json { "env": { "ANTHROPIC_BASE_URL": "http://localhost:20128", "ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key" } } ``` Hãy sử dụng điểm cuối gốc tương thích với Claude tại đây. Không thêm `/v1` vào `ANTHROPIC_BASE_URL`. ### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` ### OpenClaw Chỉnh sửa `~/.openclaw/openclaw.json`: ```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" }] } } } } ``` **Hoặc sử dụng Bảng điều khiển:** Công cụ CLI → OpenClaw → Tự động cấu hình ### Cline / Continue / RooCode ``` Nhà cung cấp: Tương thích với OpenAI URL cơ sở: http://localhost:20128/v1 Khóa API: [từ bảng điều khiển] Mô hình: cc/claude-opus-4-7 ``` --- ## 🚀 Triển khai ### Cài đặt npm toàn cục (Khuyến nghị) ```bash npm install -g omniroute # Tạo thư mục cấu hình mkdir -p ~/.omniroute # Tạo tệp .env (xem .env.example) cp .env.example ~/.omniroute/.env # Khởi động máy chủ omniroute # Hoặc với cổng tùy chỉnh: omniroute --port 3000 ``` CLI tự động tải `.env` từ `~/.omniroute/.env` hoặc `./.env`. ### Chế độ khay hệ thống Khởi động OmniRoute trong khay hệ thống: ```bash omniroute serve --tray ``` Lệnh sẽ kết thúc sau khi máy chủ và khay hệ thống sẵn sàng. Máy chủ tiếp tục chạy mà không cần cửa sổ dòng lệnh. Chế độ khay hệ thống hỗ trợ macOS, Windows và các phiên Linux có giao diện đồ họa. Chế độ khay hệ thống không tự động mở bảng điều khiển. Sử dụng menu khay hệ thống cho các thao tác sau: - Mở bảng điều khiển. - Mở `/dashboard/logs`. - Thay đổi chế độ tự động khởi động. - Dừng OmniRoute. Không kết hợp `--tray` với các tùy chọn sau: - `--daemon` - `--log` - `--no-recovery` Các chế độ này yêu cầu quyền sở hữu tiến trình khác nhau. Bật khởi động cùng hệ thống vào lần đăng nhập máy tính tiếp theo: ```bash omniroute autostart enable ``` Tính năng tự động khởi động sử dụng chế độ khay hệ thống trên macOS, Windows và các phiên Linux có giao diện đồ họa. Linux không có giao diện đồ họa sử dụng dịch vụ người dùng systemd hiện có. Tắt khởi động cùng hệ thống khi đăng nhập: ```bash omniroute autostart disable ``` ### Gỡ cài đặt Khi không còn cần OmniRoute, chúng tôi cung cấp hai tập lệnh nhanh để gỡ bỏ sạch sẽ: | Lệnh | Hành động | | ------------------------ | --------------------------------------------------------------------------------------------------- | | `npm run uninstall` | Gỡ ứng dụng khỏi hệ thống nhưng **giữ lại cơ sở dữ liệu và cấu hình của bạn** trong `~/.omniroute`. | | `npm run uninstall:full` | Gỡ ứng dụng VÀ **xóa vĩnh viễn tất cả cấu hình, khóa và cơ sở dữ liệu**. | > Lưu ý: Để chạy các lệnh này, hãy chuyển đến thư mục dự án OmniRoute (nếu bạn đã sao chép kho lưu trữ) rồi chạy chúng. Ngoài ra, nếu đã cài đặt toàn cục, bạn chỉ cần chạy `npm uninstall -g omniroute`. ### Triển khai trên 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 # Hoặc: pm2 start npm --name omniroute -- start ``` ### Triển khai bằng PM2 (Bộ nhớ thấp) Đối với máy chủ có RAM hạn chế, hãy sử dụng tùy chọn giới hạn bộ nhớ: ```bash # Với giới hạn 512MB (mặc định) pm2 start npm --name omniroute -- start # Hoặc với giới hạn bộ nhớ tùy chỉnh OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start # Hoặc sử dụng ecosystem.config.js pm2 start ecosystem.config.js ``` Tạo `ecosystem.config.js`: ```javascript 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 ```bash # Xây dựng image (mặc định = runner-cli với codex/claude/droid được cài đặt sẵn) docker build -t omniroute:cli . # Chế độ di động (khuyến nghị) docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` Đối với chế độ tích hợp với máy chủ có các tệp nhị phân CLI, hãy xem phần Docker trong tài liệu chính. ### Void Linux (xbps-src) Người dùng Void Linux có thể đóng gói và cài đặt OmniRoute theo cách nguyên bản bằng framework biên dịch chéo `xbps-src`. Quy trình này tự động hóa việc xây dựng bản độc lập Node.js cùng với các liên kết native `better-sqlite3` bắt buộc.
Xem template xbps-src ```bash # Tệp template cho '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 " 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() { # Xác định kiến trúc CPU đích cho 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) Cài đặt tất cả dependency – bỏ qua script NODE_ENV=development npm ci --ignore-scripts # 2) Xây dựng gói độc lập Next.js npm run build # 3) Sao chép tài nguyên tĩnh vào gói độc lập cp -r .next/static .next/standalone/.next/static [ -d public ] && cp -r public .next/standalone/public || true # 4) Biên dịch liên kết native better-sqlite3 local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch") # 5) Đặt liên kết đã biên dịch vào gói độc lập 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) Xóa các gói sharp dành riêng cho từng kiến trúc rm -rf .next/standalone/node_modules/@img # 7) Sao chép các dependency runtime của pino bị quá trình phân tích tĩnh Next.js bỏ sót: 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 # Ngăn hook sau cài đặt xóa các thư mục app router Next.js trống 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 } ```
### Biến môi trường | Biến | Mặc định | Mô tả | | --------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `JWT_SECRET` | `omniroute-default-secret-change-me` | Khóa bí mật dùng để ký JWT (**phải thay đổi trong môi trường production**) | | `INITIAL_PASSWORD` | `CHANGEME` | Mật khẩu đăng nhập lần đầu | | `DATA_DIR` | `~/.omniroute` | Thư mục dữ liệu (cơ sở dữ liệu, mức sử dụng, nhật ký) | | `PORT` | mặc định của framework | Cổng dịch vụ (`20128` trong các ví dụ) | | `HOSTNAME` | mặc định của framework | Máy chủ để liên kết (Docker mặc định là `0.0.0.0`) | | `NODE_ENV` | mặc định của runtime | Đặt thành `production` khi triển khai | | `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | URL cơ sở công khai được cung cấp cho bảng điều khiển và máy chủ (thay thế `BASE_URL` cũ) | | `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | URL cơ sở của điểm cuối đồng bộ đám mây (thay thế `CLOUD_URL` cũ) | | `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Khóa bí mật HMAC dành cho các khóa API được tạo | | `REQUIRE_API_KEY` | `false` | Bắt buộc sử dụng khóa API Bearer trên `/v1/*` | | `ALLOW_API_KEY_REVEAL` | `false` | Cho phép người dùng bảng điều khiển đã xác thực xem toàn bộ giá trị khóa API được lưu trữ khi có yêu cầu | | `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Chu kỳ làm mới phía máy chủ cho dữ liệu Giới hạn Nhà cung cấp được lưu đệm; các nút làm mới trên UI vẫn kích hoạt đồng bộ thủ công | | `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Tắt ảnh chụp nhanh SQLite tự động trước khi ghi/nhập/khôi phục; sao lưu thủ công vẫn hoạt động | | `APP_LOG_TO_FILE` | `true` | Bật ghi nhật ký ứng dụng và nhật ký kiểm tra vào ổ đĩa | | `AUTH_COOKIE_SECURE` | `false` | Bắt buộc cookie xác thực có thuộc tính `Secure` (khi đặt sau proxy ngược HTTPS) | | `CLOUDFLARED_BIN` | chưa đặt | Sử dụng tệp nhị phân `cloudflared` hiện có thay vì tải xuống bản được quản lý | | `CLOUDFLARED_PROTOCOL` | `http2` | Giao thức truyền tải cho Quick Tunnels được quản lý (`http2`, `quic` hoặc `auto`) | | `OMNIROUTE_MEMORY_MB` | `512` | Giới hạn heap của Node.js tính bằng MB | | `PROMPT_CACHE_MAX_SIZE` | `50` | Số mục tối đa trong bộ nhớ đệm prompt | | `SEMANTIC_CACHE_MAX_SIZE` | `100` | Số mục tối đa trong bộ nhớ đệm ngữ nghĩa | Để xem tài liệu tham khảo đầy đủ về các biến môi trường, hãy xem [README](../README.md). --- ## 📊 Các mô hình khả dụng
Xem tất cả các mô hình khả dụng > Danh sách bên dưới được tuyển chọn từ `open-sse/config/providerRegistry.ts` cho v3.8.0. Các danh mục đám mây (Gemini, OpenRouter, v.v.) được đồng bộ hóa động — để xem toàn bộ danh mục hiện hành, hãy mở **Bảng điều khiển → Nhà cung cấp → [nhà cung cấp] → Mô hình khả dụng** hoặc gọi `GET /api/models/catalog`. > > Nếu danh sách tích hợp sẵn của một nhà cung cấp đã không còn đồng bộ, hãy sử dụng **Nhập từ /models** trên trang đó (hoặc bật **Tự động đồng bộ**) để lấy danh mục hiện hành từ nguồn thượng nguồn. Điều này đã được xác minh trong v3.8.50 đối với LLM7.io (`gemini-3.1-flash-lite`) và UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`); quyền truy cập ẩn danh của Pollinations vẫn bị giới hạn từ phía thượng nguồn trong cùng đợt kiểm thử. **Claude Code (`cc/`)** — OAuth Pro/Max: `cc/claude-opus-4-8`, `cc/claude-opus-4-7`, `cc/claude-opus-4-6`, `cc/claude-opus-4-5-20251101`, `cc/claude-sonnet-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` **Codex (`cx/`)** — OAuth Plus/Pro: `cx/gpt-5.5` (+ các mức nỗ lực: `gpt-5.5-xhigh`, `gpt-5.5-high`, `gpt-5.5-medium`, `gpt-5.5-low`), `cx/gpt-5.4`, `cx/gpt-5.4-mini`, `cx/gpt-5.3-codex`, `cx/gpt-5.3-codex-spark` **GitHub Copilot (`gh/`)** — OAuth: `gh/gpt-5.5`, `gh/gpt-5.4`, `gh/gpt-5.4-mini`, `gh/gpt-5-mini`, `gh/gpt-5.3-codex`, `gh/claude-opus-4.7`, `gh/claude-opus-4.6`, `gh/claude-opus-4-5-20251101`, `gh/claude-sonnet-4.6`, `gh/claude-sonnet-4.5`, `gh/claude-haiku-4.5`, `gh/gemini-3.1-pro-preview`, `gh/gemini-3-flash-preview`, `gh/oswe-vscode-prime` **Kiro (`kr/`)** — OAuth MIỄN PHÍ: sử dụng danh mục hiện hành được hiển thị trong **Bảng điều khiển → Nhà cung cấp → Kiro → Mô hình khả dụng**. Tính khả dụng phụ thuộc vào tài khoản và gói dịch vụ. **Qoder (`if/`)** — OAuth MIỄN PHÍ: `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/tháng cố định hoặc trả theo mức sử dụng: `kimi/kimi-k2.6`, `kimi/kimi-k2.5` **DeepSeek (`ds/`)** — Khóa API: `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash` **Groq (`groq/`)** — Siêu nhanh: `groq/llama-3.3-70b-versatile`, `groq/meta-llama/llama-4-maverick-17b-128e-instruct`, `groq/qwen/qwen3-32b`, `groq/openai/gpt-oss-120b` **xAI (`xai/`)** — Grok nguyên bản: `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/`)** — Được lưu trữ tại EU: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/devstral-latest`, `mistral/codestral-latest` **Perplexity (`pplx/`)** — Được tăng cường bằng tìm kiếm: `pplx/sonar-deep-research`, `pplx/sonar-reasoning-pro`, `pplx/sonar-pro`, `pplx/sonar` **Together AI (`together/`)** — Mã nguồn mở: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free` (miễn phí), `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/`)** — Suy luận nhanh: `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/`)** — Quy mô wafer: `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b` **Cohere (`cohere/`)** — Tập trung vào 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/`)** — Dành cho doanh nghiệp: `nvidia/z-ai/glm-5.1`, `nvidia/minimaxai/minimax-m2.7`, `nvidia/google/gemma-4-31b-it`, `nvidia/mistralai/mistral-small-4-119b-2603`, `nvidia/mistralai/mistral-large-3-675b-instruct-2512`, `nvidia/qwen/qwen3.5-397b-a17b`, `nvidia/deepseek-ai/deepseek-v4-pro`, `nvidia/openai/gpt-oss-120b`, `nvidia/nvidia/nemotron-3-super-120b-a12b` **Baidu Qianfan (`qianfan/`)** — ERNIE: `qianfan/ernie-5.1`, `qianfan/ernie-5.0-thinking-latest`, `qianfan/ernie-x1.1` **Ollama Cloud (`ollama-cloud/`)**: `ollama-cloud/deepseek-v4-pro`, `ollama-cloud/deepseek-v4-flash`, `ollama-cloud/kimi-k2.6`, `ollama-cloud/glm-5.1`, `ollama-cloud/minimax-m2.7`, `ollama-cloud/gemma4:31b`, `ollama-cloud/qwen3.5:397b` **Gemini (Google Cloud `gemini/`)**: Được đồng bộ trực tiếp từ Google theo từng khóa API — không có danh sách tĩnh. Kết nối một khóa trong **Bảng điều khiển → Nhà cung cấp**, sau đó sử dụng **Mô hình khả dụng** để nhập danh mục hiện tại (ví dụ: `gemini/gemini-3-pro`, `gemini/gemini-3-flash`). **Các nhà cung cấp tương thích khác** (được chọn): `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (thông qua `aws-bedrock`), `azure-ai`, `openrouter` (danh mục chuyển tiếp), `siliconflow`, `hyperbolic`, `huggingface`, `featherless-ai`, `cloudflare-ai`, `scaleway`, `deepinfra`, `vercel-ai-gateway`, `bazaarlink`, `friendliai`, `nous-research`, `reka`, `volcengine`, `ai21`, `gigachat`. Mỗi nhà cung cấp duy trì danh sách mô hình riêng trong `providerRegistry.ts` và có thể được tự động đồng bộ khi nhà cung cấp công khai điểm cuối `/models`. **Lưu ý về ID mô hình:** OmniRoute sử dụng ID gốc của nhà cung cấp (`claude-opus-4-8`, `gpt-5.5`, `glm-5.1`, `MiniMax-M2.7`, `kimi-k2.5`, `grok-4.20-0309-reasoning`). Một số ID bao gồm phiên bản có dấu chấm vì đó là định dạng mà API thượng nguồn yêu cầu. Nếu một mô hình không được liệt kê ở trên, hãy chạy `omniroute models --search ` hoặc truy cập `GET /api/models/catalog` để xác nhận tính khả dụng.
--- ## 🧩 Tính năng nâng cao ### Mô hình tùy chỉnh Thêm bất kỳ ID mô hình nào vào bất kỳ nhà cung cấp nào mà không cần chờ cập nhật ứng dụng: ```bash # Qua 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"}' # Liệt kê: curl http://localhost:20128/api/provider-models?provider=openai # Xóa: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2" ``` Hoặc sử dụng Bảng điều khiển: **Nhà cung cấp → [Nhà cung cấp] → Mô hình tùy chỉnh**. Lưu ý: - Các nhà cung cấp tương thích với OpenRouter và OpenAI/Anthropic chỉ được quản lý từ **Mô hình khả dụng**. Việc thêm thủ công, nhập và tự động đồng bộ đều đưa mô hình vào cùng một danh sách mô hình khả dụng, vì vậy không có phần Mô hình tùy chỉnh riêng cho các nhà cung cấp đó. - Phần **Mô hình tùy chỉnh** dành cho các nhà cung cấp không hỗ trợ tính năng nhập mô hình khả dụng được quản lý. ### Nhà cung cấp tùy chỉnh tương thích với OpenAI Bất kỳ cổng nào hỗ trợ API OpenAI (proxy tự lưu trữ, vLLM, trình tổng hợp của bên thứ ba) đều có thể được thêm dưới dạng một nút nhà cung cấp riêng: 1. **Nhà cung cấp → Thêm nhà cung cấp tương thích với OpenAI**. 2. **Tên**: nhãn hiển thị cho nút. 3. **Tiền tố**: tên định tuyến. Máy khách gọi mô hình theo dạng `/`, vì vậy một nút có tiền tố `mygw` sẽ phục vụ `mygw/gpt-4o-mini`. Bắt buộc; không có giới hạn ký tự. 4. **Loại API**: họ endpoint mà cổng cung cấp (Chat Completions, Responses, Embeddings, âm thanh, hình ảnh). 5. **URL cơ sở**: gốc API, cho đến và bao gồm `/v1` (ví dụ: `https://gateway.example.com/v1`), không phải đường dẫn đầy đủ `/chat/completions`. Các cổng có đường dẫn không chuẩn sẽ thiết lập chúng trong **Cài đặt nâng cao** (đường dẫn trò chuyện, đường dẫn mô hình). 6. Trường **Khóa API (để kiểm tra)** chỉ dùng để kiểm tra kết nối. Sau khi tạo nút, hãy mở nút đó và sử dụng **Thêm kết nối** để lưu khóa sẽ được các yêu cầu sử dụng. Nút nhận một ID nội bộ có dạng `openai-compatible--`; bạn không bao giờ cần nhập ID này, tiền tố chính là tên công khai. #### Tiền tố dành riêng Tiền tố không được trùng với ID hoặc bí danh của một nhà cung cấp tích hợp sẵn (ví dụ: `openai`, `cf`), cũng không được trùng với ID của một nhà cung cấp đã ngừng hoạt động. Trình phân giải mô hình kiểm tra ID và bí danh tích hợp sẵn trước các nút tùy chỉnh, vì vậy nút sử dụng một trong những tiền tố đó sẽ không bao giờ nhận được lưu lượng: `/model` sẽ được chuyển đến nhà cung cấp tích hợp sẵn, hoặc bị từ chối an toàn nếu nhà cung cấp đó đã ngừng hoạt động. Việc tạo hoặc chỉnh sửa nút với tiền tố như vậy sẽ bị từ chối với thông báo: ```text prefix: "" là tiền tố nhà cung cấp dành riêng — hãy chọn một tiền tố khác (không thể sử dụng ID/bí danh dành riêng cho các nút tùy chỉnh vì các yêu cầu như /model sẽ được định tuyến đến một nhà cung cấp tích hợp sẵn hoặc bị từ chối an toàn khi nhà cung cấp đó ngừng hoạt động) ``` Hãy chọn một tiền tố riêng biệt (`mygw`, `acme-proxy`). Nếu các yêu cầu đến một nút tùy chỉnh thất bại với lỗi nêu tên một nhà cung cấp tích hợp sẵn hoặc thông tin xác thực của nhà cung cấp đó, hãy kiểm tra xem tiền tố của nút có phải là tiền tố dành riêng hay không: các nút được lưu trước khi quy tắc này tồn tại vẫn được lưu trữ, nhưng tiền tố của chúng sẽ định tuyến đến nhà cung cấp tích hợp sẵn. Hãy chỉnh sửa nút và đặt cho nó một tiền tố mới. ### Kết chuỗi các cổng OmniRoute ngang hàng Một cổng OmniRoute khác có thể được thêm dưới dạng nhà cung cấp **Tùy chỉnh tương thích với OpenAI**. Hãy sử dụng URL cơ sở `/v1` của cổng ngang hàng và một khóa API chuyên dụng với đặc quyền tối thiểu do cổng đó cấp. Đối với chuỗi hai chiều hoặc nhiều chặng, hãy bật cơ chế bảo vệ vòng lặp tùy chọn trên mọi cổng: ```bash # gateway-a OMNIROUTE_INSTANCE_ID=gateway-a OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1 OMNIROUTE_PEER_MAX_HOPS=4 ``` ```bash # gateway-b OMNIROUTE_INSTANCE_ID=gateway-b OMNIROUTE_PEER_URLS=http://gateway-a:20128/v1 OMNIROUTE_PEER_MAX_HOPS=4 ``` Chỉ các yêu cầu được gửi đến URL cổng ngang hàng nằm rõ ràng trong danh sách cho phép mới nhận được tiêu đề `X-OmniRoute-Peer-Trace`. Cổng sẽ từ chối ID phiên bản bị lặp lại hoặc khi ngân sách số chặng đã cạn bằng HTTP `508 Loop Detected`; các nhà cung cấp thượng nguồn thông thường không nhận được siêu dữ liệu ngang hàng. Kết chuỗi cổng ngang hàng không phải là sao chép cơ sở dữ liệu hoặc chuyển đổi dự phòng máy chủ. Mỗi cổng duy trì trạng thái SQLite, bộ nhớ đệm, bộ đếm giới hạn tốc độ và phiên độc lập. Hãy sử dụng proxy ngược có kiểm tra tình trạng hoặc cơ chế chuyển đổi dự phòng phía máy khách để bảo đảm tính sẵn sàng chủ động/thụ động hoặc chủ động/chủ động, và không bao giờ gắn một cơ sở dữ liệu SQLite vào nhiều phiên bản OmniRoute đang chạy. ### Tuyến nhà cung cấp chuyên dụng Định tuyến yêu cầu trực tiếp đến một nhà cung cấp cụ thể kèm xác thực mô hình: ```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 ``` Tiền tố nhà cung cấp sẽ tự động được thêm nếu còn thiếu. Các mô hình không khớp sẽ trả về `400`. ### Cấu hình proxy mạng ```bash # Đặt proxy toàn cục curl -X PUT http://localhost:20128/api/settings/proxy \ -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}' # Proxy theo từng nhà cung cấp curl -X PUT http://localhost:20128/api/settings/proxy \ -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}' # Kiểm tra proxy curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` **Thứ tự ưu tiên:** Theo khóa → Theo tổ hợp → Theo nhà cung cấp → Toàn cục → Môi trường. ### API danh mục mô hình ```bash curl http://localhost:20128/api/models/catalog ``` Trả về các mô hình được nhóm theo nhà cung cấp cùng với loại (`chat`, `embedding`, `image`). ### Đồng bộ đám mây - Đồng bộ nhà cung cấp, tổ hợp và cài đặt giữa các thiết bị - Tự động đồng bộ trong nền với thời gian chờ + dừng sớm khi có lỗi - Ưu tiên `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL` phía máy chủ trong môi trường production ### Đường hầm nhanh Cloudflare - Khả dụng trong **Dashboard → Endpoints** cho Docker và các bản triển khai tự lưu trữ khác - Tạo một URL `https://*.trycloudflare.com` tạm thời để chuyển tiếp đến endpoint `/v1` tương thích với OpenAI hiện tại của bạn - Lần bật đầu tiên chỉ cài đặt `cloudflared` khi cần; các lần khởi động lại sau đó sẽ tái sử dụng cùng một tệp nhị phân được quản lý - Quick Tunnels không được tự động khôi phục sau khi OmniRoute hoặc container khởi động lại; hãy bật lại chúng từ dashboard khi cần - URL của tunnel chỉ tồn tại tạm thời và thay đổi mỗi khi bạn dừng/khởi động tunnel - Quick Tunnels được quản lý mặc định sử dụng giao thức truyền tải HTTP/2 để tránh các cảnh báo ồn ào về bộ đệm UDP của QUIC trong những container có tài nguyên hạn chế - Đặt `CLOUDFLARED_PROTOCOL=quic` hoặc `auto` nếu bạn muốn ghi đè lựa chọn giao thức truyền tải được quản lý - Đặt `CLOUDFLARED_BIN` nếu bạn muốn sử dụng tệp nhị phân `cloudflared` đã được cài đặt sẵn thay vì bản tải xuống được quản lý - Các bảng Cloudflare Quick Tunnel, Tailscale Funnel và ngrok Tunnel có thể được hiển thị hoặc ẩn trong **Settings → Appearance**. Việc ẩn một bảng không dừng tunnel đang chạy. ### Trí tuệ LLM Gateway (Giai đoạn 9) - **Bộ nhớ đệm ngữ nghĩa** — Tự động lưu vào bộ nhớ đệm các phản hồi không truyền phát có temperature=0 (bỏ qua bằng `X-OmniRoute-No-Cache: true`) - **Tính lũy đẳng của yêu cầu** — Loại bỏ các yêu cầu trùng lặp trong vòng 5 giây thông qua header `Idempotency-Key` hoặc `X-Request-Id` - **Theo dõi tiến trình** — Chủ động bật các sự kiện SSE `event: progress` thông qua header `X-OmniRoute-Progress: true` --- ### Sân chơi trình dịch Truy cập qua **Dashboard → Translator**. Gỡ lỗi và trực quan hóa cách OmniRoute chuyển đổi các yêu cầu API giữa các nhà cung cấp. | Chế độ | Mục đích | | ---------------- | -------------------------------------------------------------------------------------------------- | | **Playground** | Chọn định dạng nguồn/đích, dán một yêu cầu và xem ngay đầu ra đã được chuyển đổi | | **Chat Tester** | Gửi tin nhắn trò chuyện trực tiếp qua proxy và kiểm tra toàn bộ chu trình yêu cầu/phản hồi | | **Test Bench** | Chạy kiểm thử hàng loạt trên nhiều tổ hợp định dạng để xác minh tính chính xác của việc chuyển đổi | | **Live Monitor** | Theo dõi các bản chuyển đổi theo thời gian thực khi yêu cầu đi qua proxy | **Trường hợp sử dụng:** - Gỡ lỗi nguyên nhân khiến một tổ hợp máy khách/nhà cung cấp cụ thể gặp lỗi - Xác minh rằng các thẻ suy luận, lệnh gọi công cụ và lời nhắc hệ thống được chuyển đổi chính xác - So sánh sự khác biệt về định dạng giữa OpenAI, Claude, Gemini và các định dạng Responses API --- ### Chiến lược định tuyến Cấu hình qua **Dashboard → Settings → Routing**. Dashboard hiển thị sáu chiến lược được sử dụng nhiều nhất; các combo và bộ định tuyến tự động hỗ trợ nội bộ một tập hợp rộng hơn. **Các chiến lược hiển thị trên dashboard (định tuyến cấp tài khoản):** | Chiến lược | Mô tả | | ------------------------------ | --------------------------------------------------------------------------------------------------------------- | | **Fill First** | Sử dụng các tài khoản theo thứ tự ưu tiên — tài khoản chính xử lý mọi yêu cầu cho đến khi không khả dụng | | **Round Robin** | Luân phiên qua tất cả tài khoản với giới hạn duy trì có thể cấu hình (mặc định: 3 lệnh gọi cho mỗi tài khoản) | | **P2C (Power of Two Choices)** | Chọn 2 tài khoản ngẫu nhiên và định tuyến đến tài khoản khỏe hơn — cân bằng tải có xét đến tình trạng hoạt động | | **Random** | Chọn ngẫu nhiên một tài khoản cho mỗi yêu cầu bằng thuật toán xáo trộn Fisher-Yates | | **Least Used** | Định tuyến đến tài khoản có dấu thời gian `lastUsedAt` cũ nhất, giúp phân phối lưu lượng đồng đều | | **Cost Optimized** | Định tuyến đến tài khoản có giá trị ưu tiên thấp nhất, tối ưu cho các nhà cung cấp có chi phí thấp nhất | **Các chiến lược combo và tự động nâng cao** (có thể cấu hình cho từng combo hoặc qua tiền tố `auto/*` — xem [AUTO-COMBO.md](../routing/AUTO-COMBO.md)): - `priority` — thứ tự nghiêm ngặt, không bao giờ luân phiên - `weighted` — phân chia lưu lượng theo tỷ lệ dựa trên trọng số của từng mô hình - `fill-first` — sử dụng hết mô hình đầu tiên cho đến khi đạt giới hạn - `round-robin` / `strict-random` / `random` - `p2c` (Power of Two Choices) - `least-used` và `cost-optimized` - `auto` — dựa trên điểm số trên tất cả ứng viên - `lkgp` (Last Known Good Provider) — cố định vào nhà cung cấp thành công gần nhất, sau đó chuyển về các quy tắc dự phòng - `context-optimized` — chọn mô hình có cửa sổ ngữ cảnh còn trống lớn nhất - `context-relay` — nối chuỗi các mô hình có ngữ cảnh dài cho những lượt tiếp theo #### Header phiên duy trì bên ngoài Để duy trì mối liên kết với phiên bên ngoài (ví dụ: các tác nhân Claude Code/Codex phía sau reverse proxy), hãy gửi: ```http X-Session-Id: your-session-key ``` OmniRoute cũng chấp nhận `x_session_id` và trả về khóa phiên thực tế trong `X-OmniRoute-Session-Id`. Nếu bạn sử dụng Nginx và gửi các header có dạng dấu gạch dưới, hãy bật: ```nginx underscores_in_headers on; ``` #### Bí danh mô hình dùng ký tự đại diện Tạo các mẫu ký tự đại diện để ánh xạ lại tên mô hình: ``` Mẫu: claude-sonnet-* → Đích: cc/claude-sonnet-4-6 Mẫu: gpt-* → Đích: gh/gpt-5.3-codex ``` Ký tự đại diện hỗ trợ `*` (bất kỳ chuỗi ký tự nào) và `?` (một ký tự đơn). #### Chuỗi dự phòng Định nghĩa các chuỗi dự phòng toàn cục áp dụng cho mọi yêu cầu: ``` Chuỗi: production-fallback 1. cc/claude-opus-4-7 2. gh/gpt-5.3-codex 3. glm/glm-4.7 ``` --- ### Các tổ hợp nhà cung cấp và mẫu định tuyến phổ biến Dưới đây là các mẫu ví dụ để kết hợp nhiều nhà cung cấp và định tuyến giữa chúng trong OmniRoute: #### 1. Combo tác nhân lập trình: Suy luận cao cấp với phương án dự phòng theo chi phí/tốc độ Lý tưởng cho các tác nhân lập trình (OpenCode, Claude Code, Cursor, Cline). Ban đầu định tuyến đến các mô hình suy luận tiên tiến, sau đó chuyển sang các mô hình lập trình nhanh khi hết hạn ngạch hoặc xảy ra lỗi. - **Dashboard**: Combos → New Combo → Name: `agent-coding` → Strategy: `Priority` - **Mô hình**: 1. `claude/claude-sonnet-4-6` (Tác nhân lập trình chính) 2. `openai/gpt-4o` (Phương án dự phòng thứ cấp có năng lực cao) 3. `deepseek/deepseek-v4-flash` (Phương án dự phòng hiệu quả cao, tiết kiệm chi phí) ```bash # Ví dụ qua 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. Combo tự động chuyển đổi dự phòng thuộc gói miễn phí Kết hợp nhiều nhà cung cấp thuộc gói miễn phí và không yêu cầu khóa để tối đa hóa thời gian hoạt động mà không phát sinh chi phí API. - **Chiến lược**: `Least Used` hoặc `Round Robin` (phân phối tải giữa các hạn ngạch) - **Mô hình**: 1. `groq/llama-3.3-70b-versatile` 2. `gemini/gemini-2.5-flash` 3. `cerebras/gpt-oss-120b` ```bash # Ví dụ qua 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. Quy trình đa phương thức / thị giác và văn bản Kết hợp các mô hình thị giác chuyên biệt với khả năng tạo văn bản tốc độ cao cho các quy trình liên quan đến việc hiểu hình ảnh và tạo mã. - **Mẫu**: Một combo `Priority` liệt kê các mô hình hỗ trợ thị giác trước và một mô hình văn bản/mã có thông lượng cao ở cuối. - **Mô hình**: 1. `gemini/gemini-2.5-pro` (Khả năng hiểu hình ảnh/đa phương thức mạnh mẽ) 2. `openai/gpt-4o` (Cân bằng giữa khả năng thị giác và sử dụng công cụ) 3. `deepseek/deepseek-v4-flash` (Tạo văn bản/mã) --- ### Khả năng phục hồi và bộ ngắt mạch Cấu hình qua **Bảng điều khiển → Cài đặt → Khả năng phục hồi**. OmniRoute triển khai khả năng phục hồi ở cấp nhà cung cấp với năm thành phần: 1. **Hàng đợi yêu cầu và điều tiết nhịp độ** — Điều tiết yêu cầu ở cấp hệ thống: - **Số yêu cầu mỗi phút (RPM)** — Số yêu cầu tối đa mỗi phút cho mỗi tài khoản - **Thời gian tối thiểu giữa các yêu cầu** — Khoảng cách tối thiểu tính bằng mili giây giữa các yêu cầu - **Số yêu cầu đồng thời tối đa** — Số yêu cầu đồng thời tối đa cho mỗi tài khoản 2. **Thời gian tạm ngưng kết nối** — Cấu hình theo từng loại xác thực cho một kết nối sau các lỗi có thể thử lại: - **Thời gian tạm ngưng cơ sở** — Khoảng thời gian tạm ngưng mặc định cho các lỗi từ dịch vụ thượng nguồn có thể thử lại - **Sử dụng gợi ý thử lại từ thượng nguồn** — Tuân theo `Retry-After` có thẩm quyền hoặc các gợi ý đặt lại khi được cung cấp - **Số bước lùi tối đa** — Mức lùi theo cấp số nhân tối đa cho các lỗi lặp lại 3. **Bộ ngắt mạch nhà cung cấp** — Theo dõi các lỗi đầu cuối của nhà cung cấp, đánh dấu một nhà cung cấp là suy giảm khi đạt ngưỡng cảnh báo đã cấu hình và mở bộ ngắt mạch khi đạt ngưỡng lỗi đã cấu hình: - **Ngưỡng suy giảm** — Số lỗi liên tiếp của nhà cung cấp trước khi chuyển sang `DEGRADED` - **Ngưỡng lỗi** — Số lỗi liên tiếp của nhà cung cấp trước khi chuyển sang `OPEN` - **Thời gian chờ đặt lại** — Khoảng thời gian trước khi nhà cung cấp được kiểm tra lại - **CLOSED** (Khỏe mạnh) — Các yêu cầu được xử lý bình thường - **DEGRADED** — Các yêu cầu vẫn được xử lý trong khi hệ thống theo dõi mức lỗi gia tăng - **OPEN** — Nhà cung cấp tạm thời bị chặn sau nhiều lỗi liên tiếp - **HALF_OPEN** — Kiểm tra xem nhà cung cấp đã khôi phục hay chưa Giới hạn tốc độ `429` trong phạm vi kết nối vẫn nằm trong **Thời gian tạm ngưng kết nối** và không được tính vào bộ ngắt mạch nhà cung cấp. Trạng thái thời gian chạy của bộ ngắt mạch nhà cung cấp chỉ được hiển thị tại **Bảng điều khiển → Tình trạng**. 4. **Chờ hết thời gian tạm ngưng** — Nếu mọi kết nối ứng viên đều đang trong thời gian tạm ngưng, OmniRoute có thể chờ thời gian tạm ngưng sớm nhất kết thúc và tự động thử lại cùng một yêu cầu của máy khách. 5. **Tự động phát hiện giới hạn tốc độ** — Khi các nhà cung cấp thượng nguồn trả về khoảng thời gian chờ rõ ràng, các gợi ý đó sẽ ghi đè thời gian tạm ngưng kết nối cục bộ nếu cài đặt này được bật. **Mẹo chuyên nghiệp:** Sử dụng trang **Tình trạng** để kiểm tra và đặt lại các bộ ngắt mạch nhà cung cấp đang hoạt động sau sự cố gián đoạn. Trang Khả năng phục hồi chỉ thay đổi cấu hình. --- ### Xuất / Nhập cơ sở dữ liệu Quản lý các bản sao lưu cơ sở dữ liệu tại **Bảng điều khiển → Cài đặt → Hệ thống và lưu trữ**. | Hành động | Mô tả | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Xuất cơ sở dữ liệu** | Tải cơ sở dữ liệu SQLite hiện tại xuống dưới dạng tệp `.sqlite` | | **Xuất tất cả (.tar.gz)** | Tải xuống một kho lưu trữ sao lưu đầy đủ bao gồm: cơ sở dữ liệu, cài đặt, combo, kết nối nhà cung cấp (không có thông tin xác thực), siêu dữ liệu khóa API | | **Nhập cơ sở dữ liệu** | Tải lên tệp `.sqlite` để thay thế cơ sở dữ liệu hiện tại. Một bản sao lưu trước khi nhập sẽ tự động được tạo trừ khi `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Xuất cơ sở dữ liệu curl -o backup.sqlite http://localhost:20128/api/db-backups/export # API: Xuất tất cả (kho lưu trữ đầy đủ) curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll # API: Nhập cơ sở dữ liệu curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` **Xác thực khi nhập:** Tệp được nhập sẽ được xác thực về tính toàn vẹn (kiểm tra pragma của SQLite), các bảng bắt buộc (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) và kích thước (tối đa 100MB). **Trường hợp sử dụng:** - Di chuyển OmniRoute giữa các máy - Tạo bản sao lưu bên ngoài để phục hồi sau thảm họa - Chia sẻ cấu hình giữa các thành viên trong nhóm (xuất tất cả → chia sẻ kho lưu trữ) --- ### Bảng điều khiển cài đặt Trang cài đặt được sắp xếp thành **7 thẻ** để dễ dàng điều hướng: | Tab | Nội dung | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Chung** | Công cụ lưu trữ hệ thống, hành vi mặc định, khả năng hiển thị đường hầm Endpoint | | **Giao diện** | Điều khiển chủ đề (sáng/tối/hệ thống), khả năng hiển thị thanh bên, tùy chọn bật/tắt bảng cho các thẻ đường hầm Cloudflare/Tailscale/ngrok | | **AI** | Ngân sách suy luận (chuyển tiếp nguyên trạng / tự động loại bỏ / tùy chỉnh / thích ứng — xem [THINKING_BUDGET.md](./THINKING_BUDGET.md)), lời nhắc hệ thống toàn cục, thống kê bộ nhớ đệm lời nhắc | | **Bảo mật** | Cài đặt đăng nhập/mật khẩu, kiểm soát truy cập IP, xác thực API cho `/models`, chặn nhà cung cấp, cơ chế bảo vệ chống chèn lời nhắc | | **Định tuyến** | Chiến lược định tuyến toàn cục (lấp đầy trước / luân phiên / P2C / ngẫu nhiên / ít được dùng nhất / tối ưu chi phí), bí danh mô hình có ký tự đại diện, chuỗi dự phòng, mặc định cho tổ hợp | | **Khả năng phục hồi** | Hàng đợi yêu cầu, thời gian chờ kết nối, cấu hình bộ ngắt mạch nhà cung cấp và hành vi chờ hết thời gian tạm ngưng | | **Nâng cao** | Cấu hình proxy toàn cục (HTTP/SOCKS5), ghi đè proxy theo từng nhà cung cấp | Phần Chung không còn lặp lại các ghi chú chỉ đọc về nhật ký và bộ nhớ đệm. Các cài đặt lưu giữ và tối ưu hóa cơ sở dữ liệu được duy trì thông qua `/api/settings/database`; việc xóa bộ nhớ đệm thủ công sử dụng `DELETE /api/cache`. Giới hạn số hàng của nhật ký yêu cầu và nhật ký proxy được kiểm soát bởi `CALL_LOGS_TABLE_MAX_ROWS` và `PROXY_LOGS_TABLE_MAX_ROWS`. --- ### Quản lý chi phí & ngân sách Truy cập qua **Bảng điều khiển → Chi phí**. | Tab | Mục đích | | ------------- | -------------------------------------------------------------------------------------------------------------------- | | **Ngân sách** | Đặt giới hạn chi tiêu cho từng khóa API với ngân sách hằng ngày/hằng tuần/hằng tháng và theo dõi theo thời gian thực | | **Định giá** | Xem và chỉnh sửa các mục định giá mô hình — chi phí trên mỗi 1K token đầu vào/đầu ra theo từng nhà cung cấp | ```bash # API: Đặt ngân sách curl -X POST http://localhost:20128/api/usage/budget \ -H "Content-Type: application/json" \ -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}' # API: Lấy trạng thái ngân sách hiện tại curl http://localhost:20128/api/usage/budget ``` **Theo dõi chi phí:** Mỗi yêu cầu đều ghi lại mức sử dụng token và tính toán chi phí bằng bảng giá. Xem thông tin chi tiết trong **Bảng điều khiển → Mức sử dụng** theo nhà cung cấp, mô hình và khóa API. --- ### Phiên âm thanh OmniRoute hỗ trợ phiên âm thanh thông qua endpoint tương thích với OpenAI: ```bash POST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data # Ví dụ với 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` là tuyến Deepgram gốc và cần khóa API Deepgram. Nếu chỉ cấu hình OpenRouter, hãy sử dụng `openrouter/deepgram/nova-3`. Các nhà cung cấp **chuyển giọng nói thành văn bản (phiên âm)**: - `openai/` (tương thích với whisper) - `groq/` (Groq Whisper Turbo) - `deepgram/` (họ Nova) - `assemblyai/` - `nvidia/` (Parakeet, Canary) - `huggingface/` (các biến thể whisper) - `qwen/` Các nhà cung cấp **chuyển văn bản thành giọng nói (`POST /v1/audio/speech`)**: - `openai/` (tts-1, tts-1-hd) - `hyperbolic/` - `deepgram/` (Aura) - `nvidia/` (Magpie TTS) - `elevenlabs/` - `huggingface/` - `inworld/` - `cartesia/` - `playht/` - `kie/` - `aws-polly/` - `xiaomi-mimo/` - `coqui/`, `tortoise/` - `qwen/` Các định dạng âm thanh được hỗ trợ để phiên âm: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. Định dạng đầu ra TTS phụ thuộc vào nhà cung cấp (mp3, wav, opus, pcm, mulaw). --- ### Chiến lược cân bằng tổ hợp Cấu hình cân bằng theo từng tổ hợp trong **Bảng điều khiển → Tổ hợp → Tạo/Chỉnh sửa → Chiến lược**. | Chiến lược | Mô tả | | --------------------- | -------------------------------------------------------------------------- | | **Luân phiên** | Lần lượt xoay vòng qua các mô hình | | **Ưu tiên** | Luôn thử mô hình đầu tiên; chỉ dùng phương án dự phòng khi xảy ra lỗi | | **Ngẫu nhiên** | Chọn ngẫu nhiên một mô hình từ tổ hợp cho mỗi yêu cầu | | **Có trọng số** | Định tuyến theo tỷ lệ dựa trên trọng số được gán cho từng mô hình | | **Ít được dùng nhất** | Định tuyến đến mô hình có ít yêu cầu gần đây nhất (sử dụng số liệu tổ hợp) | | **Tối ưu chi phí** | Định tuyến đến mô hình khả dụng rẻ nhất (sử dụng bảng giá) | Có thể đặt các giá trị mặc định toàn cục cho tổ hợp trong **Bảng điều khiển → Cài đặt → Định tuyến → Mặc định cho tổ hợp**. Theo mặc định, thời gian chờ của mục tiêu trong tổ hợp kế thừa thời gian chờ yêu cầu hiện tại. Chỉ sử dụng **Thời gian chờ mục tiêu (giây)** trong phần mặc định cho tổ hợp hoặc trên một tổ hợp riêng lẻ khi giới hạn ngắn hơn cho từng mục tiêu cần kích hoạt chuyển sang phương án dự phòng nhanh hơn. Các tối ưu hóa tổ hợp có độ trễ bằng không là tùy chọn. Hãy để **Tối ưu hóa độ trễ bằng không** ở trạng thái tắt nhằm ngăn các tính năng về độ trễ này cho các mục tiêu dự phòng chạy đua, bỏ qua mục tiêu dựa trên lịch sử TTFT hoặc nén các yêu cầu dự phòng; việc bật tính năng này cho phép phòng hộ đã cấu hình, bỏ qua theo TTFT dự đoán và nén phương án dự phòng chủ động để đánh đổi độ trung thực của định tuyến/yêu cầu lấy độ trễ đuôi thấp hơn. Tắt **Bộ đệm token suy luận** khi các nhà cung cấp thượng nguồn yêu cầu giới hạn nghiêm ngặt về `max_tokens` / `maxOutputTokens`. Khi được bật, định tuyến kết hợp chỉ bổ sung khoảng dự phòng cho mô hình suy luận đối với các mô hình có giới hạn đầu ra đã biết và giữ nguyên giới hạn token của máy khách khi giá trị đã thêm bộ đệm an toàn vượt quá giới hạn đó. Nếu giới hạn của máy khách đã cao hơn một giới hạn đã biết, OmniRoute sẽ hạ giới hạn xuống mức đó trước khi gửi yêu cầu thượng nguồn. --- ### Bảng điều khiển tình trạng Truy cập qua **Bảng điều khiển → Tình trạng**. Tổng quan tình trạng hệ thống theo thời gian thực với 6 thẻ: | Thẻ | Nội dung hiển thị | | --------------------------- | -------------------------------------------------------------------------------------- | | **Trạng thái hệ thống** | Thời gian hoạt động, phiên bản, mức sử dụng bộ nhớ, thư mục dữ liệu | | **Tình trạng nhà cung cấp** | Trạng thái thời gian chạy của bộ ngắt mạch nhà cung cấp toàn cục | | **Giới hạn tốc độ** | Thời gian chờ kết nối đang áp dụng cho từng tài khoản cùng thời gian còn lại | | **Khóa đang hoạt động** | Các khóa theo phạm vi mô hình và trường hợp loại trừ tạm thời đang hoạt động | | **Bộ nhớ đệm chữ ký** | Thống kê bộ nhớ đệm loại bỏ trùng lặp (khóa đang hoạt động, tỷ lệ truy cập thành công) | | **Số liệu độ trễ** | Tổng hợp độ trễ p50/p95/p99 theo từng nhà cung cấp | **Mẹo chuyên nghiệp:** Trang Tình trạng tự động làm mới sau mỗi 10 giây. Hãy sử dụng thẻ bộ ngắt mạch để xác định những nhà cung cấp đang gặp sự cố. --- ## 🤖 Tự động định tuyến (Không cần cấu hình) OmniRoute tích hợp sẵn một **bộ tự động định tuyến dựa trên điểm số**, giúp chọn mô hình tốt nhất cho từng yêu cầu trên tất cả các nhà cung cấp đã kết nối — không cần duy trì tổ hợp nào. Chỉ cần gửi yêu cầu với một trong các tiền tố `auto/*`, OmniRoute sẽ tự động tạo một tổ hợp ảo, chấm điểm các ứng viên dựa trên độ trễ, chi phí, tỷ lệ thành công, mức độ phù hợp với ngữ cảnh, mức độ phù hợp của mô hình với tác vụ, các lỗi gần đây, hạn ngạch và trạng thái bộ ngắt mạch. | Tiền tố | Tiêu chí tối ưu hóa | | -------------- | ------------------------------------------------------------------------------------------------------------ | | `auto` | Mặc định cân bằng (độ trễ × chi phí × tỷ lệ thành công) | | `auto/coding` | Tác vụ lập trình: ưu tiên Claude, GPT-5, GLM, Kimi, Qwen Coder, các mô hình lập trình DeepSeek | | `auto/cheap` | Chi phí $/token thấp nhất, chấp nhận độ trễ cao hơn | | `auto/fast` | Độ trễ thấp nhất, bỏ qua chi phí | | `auto/offline` | Chỉ dùng nhà cung cấp cục bộ (Ollama, vLLM, llama.cpp) — hữu ích cho các hệ thống cách ly mạng | | `auto/smart` | Ưu tiên chất lượng suy luận (Opus, GPT-5 xhigh, R1, suy luận GLM 5.1) | | `auto/lkgp` | "Nhà cung cấp tốt gần nhất" — cố định vào nhà cung cấp thành công gần nhất, sau đó dự phòng theo các quy tắc | Ví dụ: ```bash 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": "Tái cấu trúc hàm Python này" }], "stream": true }' ``` Bộ tự động định tuyến được mô tả đầy đủ trong [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — bao gồm cách điều chỉnh trọng số chấm điểm, đưa nhà cung cấp vào danh sách đen và kiểm tra các quyết định định tuyến trong **Bảng điều khiển → Tổ hợp tự động**. --- ## 🔌 Tích hợp MCP & A2A OmniRoute vừa là một **máy chủ MCP** (Giao thức Ngữ cảnh Mô hình), vừa là một **máy chủ A2A** (JSON-RPC 2.0 từ tác nhân đến tác nhân). Mọi IDE hoặc máy chủ tác nhân tương thích với MCP đều có thể gọi trực tiếp các công cụ OmniRoute — không cần lớp bao bọc bổ sung. ### Các phương thức truyền tải MCP - **SSE**: `http://localhost:20128/api/mcp/sse` - **HTTP có thể phát luồng**: `http://localhost:20128/api/mcp/stream` - **stdio**: `omniroute --mcp` (dành cho các plugin IDE ưu tiên stdio) ### Kết nối Claude Desktop Chỉnh sửa `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) hoặc tệp tương đương trên Windows/Linux: ```json { "mcpServers": { "omniroute": { "command": "omniroute", "args": ["--mcp"] } } } ``` ### Kết nối Cursor / Continue / VS Code MCP Sử dụng URL SSE `http://localhost:20128/api/mcp/sse` và khóa API Bearer được tạo trong **Bảng điều khiển → Khóa API**. ### Phạm vi MCP hiện định nghĩa 32 phạm vi có tên. Mỗi khóa Bearer có thể được giới hạn ở các phạm vi cụ thể — xem [MCP-SERVER.md](../frameworks/MCP-SERVER.md) để biết danh sách phạm vi và công cụ chính thức, cũng như [A2A-SERVER.md](../frameworks/A2A-SERVER.md) để biết lược đồ JSON-RPC. --- ## 🧠 Hệ thống kỹ năng OmniRoute cung cấp một **framework kỹ năng** có khả năng mở rộng (`src/lib/skills/`) để các agent và endpoint A2A có thể chạy các quy trình dành riêng cho từng lĩnh vực (ví dụ: `code-review`, `summarize`, `extract-facts`, `web-research`). - **Giao diện Marketplace** — Duyệt và cài đặt kỹ năng từ **Dashboard → Skills** - **Phạm vi theo từng khóa** — Giới hạn những kỹ năng mà mỗi API key có thể gọi - **Kỹ năng tùy chỉnh** — Thêm một tệp TypeScript vào `src/lib/a2a/skills/`, đăng ký tệp đó và kỹ năng sẽ có thể được gọi ngay lập tức qua A2A Tài liệu tham khảo đầy đủ: [SKILLS.md](../frameworks/SKILLS.md). --- ## 💾 Hệ thống bộ nhớ OmniRoute lưu trữ **bộ nhớ hội thoại dài hạn** bằng cơ chế truy xuất kết hợp: - **SQLite FTS5** để tìm kiếm từ khóa trong các lượt hội thoại trước đây - **Kho vector Qdrant** (tùy chọn) để truy hồi theo ngữ nghĩa - **Tự động trích xuất dữ kiện** — các thực thể, tùy chọn và quyết định được tóm tắt sau mỗi phiên rồi lưu vào bảng `memory_facts` - Bộ nhớ được phân tách theo từng API key và từng phiên Quản lý bộ nhớ trong **Dashboard → Memory** (tìm kiếm, chỉnh sửa, xuất, xóa sạch). Giao diện HTTP (`/api/memory/*`) cho phép các agent gửi và truy vấn dữ kiện theo chương trình — xem [MEMORY.md](../frameworks/MEMORY.md). --- ## 🔔 Webhook Đăng ký nhận các sự kiện OmniRoute để giám sát và tự động hóa theo thời gian thực. - Tạo webhook trong **Dashboard → Webhooks** với URL đích và khóa bí mật ký HMAC - Các sự kiện khả dụng: `request.completed`, `request.failed`, `provider.unavailable`, `budget.exceeded`, `combo.switched`, `circuit_breaker.opened`, `circuit_breaker.closed` - Mỗi payload đều bao gồm `X-OmniRoute-Signature` (HMAC-SHA256) để xác minh - Thử lại: 3 lần với thời gian chờ tăng theo cấp số nhân, sau đó chuyển vào hàng đợi thư lỗi Schema đầy đủ có trong [WEBHOOKS.md](../frameworks/WEBHOOKS.md). --- ## ☁️ Agent đám mây OmniRoute tích hợp với các agent lập trình trên đám mây (**OpenAI Codex Cloud**, **Devin**, **Jules**, **Antigravity**), cho phép bạn gửi các tác vụ chạy dài từ cùng một dashboard dùng để quản lý việc định tuyến cục bộ. - Tạo tác vụ trong **Dashboard → Cloud Agents** hoặc qua `POST /api/v1/agents/tasks` - Theo dõi trạng thái, nhật ký và các artifact của từng tác vụ - Sử dụng API key riêng của bạn cho từng nhà cung cấp — thông tin xác thực không bao giờ rời khỏi phiên bản OmniRoute Tài liệu tham khảo đầy đủ: [CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md). --- ## 🛠️ Quản lý theo chương trình Bạn có thể quản lý mọi tài nguyên OmniRoute (nhà cung cấp, combo, khóa, cài đặt) qua HTTP bằng **khóa Bearer có phạm vi `manage`**. Tạo khóa trong **Dashboard → API Keys → New Key → Scope: manage**, sau đó: ```bash # Liệt kê các nhà cung cấp curl http://localhost:20128/api/providers \ -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" # Thêm kết nối nhà cung cấp 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" }' # Tạo combo 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" }] }' # Liệt kê/tạo API key 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"] }' ``` Xem [API_REFERENCE.md](../reference/API_REFERENCE.md) để biết danh mục endpoint đầy đủ cùng các schema yêu cầu/phản hồi. --- ## 💻 CLI nội bộ OmniRoute cung cấp một CLI nội bộ (`omniroute …`) để thiết lập, chẩn đoán và kiểm soát thời gian chạy. CLI này **tách biệt với trang "Công cụ CLI" trong bảng điều khiển**, nơi cấu hình các CLI của bên thứ ba (Claude Code, Cursor, Codex, Cline, …) để chúng có thể giao tiếp với OmniRoute. ```bash omniroute setup # Trình hướng dẫn tương tác (mật khẩu, nhà cung cấp, tổ hợp) omniroute setup --non-interactive # Phù hợp với CI omniroute doctor # Chẩn đoán tình trạng (thư mục dữ liệu, DB, nhà cung cấp, cổng) omniroute providers available # Liệt kê các nhà cung cấp được hỗ trợ omniroute providers list # Liệt kê các kết nối đã cấu hình omniroute providers test # Kiểm tra trực tiếp kết nối với nhà cung cấp omniroute combos list # Liệt kê các tổ hợp omniroute combos switch # Đặt tổ hợp mặc định omniroute models # Liệt kê các mô hình khả dụng (--json, --search) omniroute keys add | list | remove # Quản lý khóa API từ terminal omniroute backup # Tạo bản chụp nhanh cấu hình + DB omniroute restore [] # Khôi phục từ bản chụp nhanh omniroute health # Tình trạng chi tiết (bộ ngắt mạch, bộ nhớ đệm, bộ nhớ) omniroute quota # Mức sử dụng hạn ngạch của nhà cung cấp omniroute mcp status # Trạng thái máy chủ MCP omniroute a2a status # Trạng thái máy chủ A2A omniroute tunnel list|create|stop # Đường hầm Cloudflare/Tailscale/ngrok omniroute reset-password # Đặt lại mật khẩu quản trị viên omniroute --mcp # Khởi động máy chủ MCP qua stdio omniroute --port 3000 # Khởi động máy chủ trên một cổng tùy chỉnh ``` Mẹo: kết hợp `omniroute doctor --json` với công cụ giám sát của bạn để cảnh báo khi kết nối với nhà cung cấp gặp sự cố. --- ## 🖥️ Ứng dụng máy tính (Electron) OmniRoute có sẵn dưới dạng ứng dụng máy tính gốc dành cho Windows, macOS và Linux. ### Cài đặt ```bash # Từ thư mục electron: cd electron npm install # Chế độ phát triển (kết nối với máy chủ phát triển Next.js đang chạy): npm run dev # Chế độ sản xuất (sử dụng bản dựng độc lập): npm start ``` ### Tạo bộ cài đặt ```bash cd electron npm run build # Nền tảng hiện tại npm run build:win # Windows (.exe NSIS) npm run build:mac # macOS (.dmg universal) npm run build:linux # Linux (.AppImage) ``` Đầu ra → `electron/dist-electron/` ### Các tính năng chính | Tính năng | Mô tả | | ------------------------------- | ------------------------------------------------------------------- | | **Mức độ sẵn sàng của máy chủ** | Thăm dò máy chủ trước khi hiển thị cửa sổ (không có màn hình trống) | | **Khay hệ thống** | Thu nhỏ vào khay, thay đổi cổng, thoát từ menu khay | | **Quản lý cổng** | Thay đổi cổng máy chủ từ khay (tự động khởi động lại máy chủ) | | **Chính sách bảo mật nội dung** | CSP hạn chế thông qua các tiêu đề phiên | | **Một phiên bản duy nhất** | Mỗi lần chỉ có thể chạy một phiên bản ứng dụng | | **Chế độ ngoại tuyến** | Máy chủ Next.js đi kèm hoạt động mà không cần internet | ### Biến môi trường | Biến | Mặc định | Mô tả | | --------------------- | -------- | --------------------------------------- | | `OMNIROUTE_PORT` | `20128` | Cổng máy chủ | | `OMNIROUTE_MEMORY_MB` | `512` | Giới hạn heap của Node.js (64–16384 MB) | 📖 Tài liệu đầy đủ: [`electron/README.md`](../../electron/README.md)