By OmniRoute: Kiến trúc gateway AI đa nhà cung cấp và nén ngữ cảnh
Tóm tắt nhanh:
OmniRoute là gateway mã nguồn mở triển khai cục bộ (local-first), gom 358 nhà cung cấp mô hình trí tuệ nhân tạo về một cổng giao tiếp HTTP chuẩn OpenAI trên port mặc định 20128. Hệ thống kết hợp cơ chế chuyển mạch dự phòng 4 tầng tự động từ tài khoản thuê bao cố định đến API trả phí và gói miễn phí, cùng các engine nén dữ liệu đầu vào RTK và Caveman giúp giảm lượng token tiêu thụ. Thiết kế bảo mật phân cấp cô lập các API khởi tạo tiến trình hệ thống trong phạm vi route guard nội bộ và mã hóa dữ liệu nhạy cảm bằng chuẩn AES-256-GCM.
Vì sao việc điều phối đa nhà cung cấp cần proxy nội bộ
Proxy AI cục bộ loại bỏ phân mảnh xác thực, xung đột SDK và ngắt quãng do rate limit. Khi kỹ sư dùng nhiều mô hình, phân tán API key trong từng CLI gây khó khăn bảo trì.
SaaS gateway tiềm ẩn nguy cơ rò rỉ mã nguồn và prompt qua bên thứ ba. Triển khai proxy ngay trên máy trạm giúp kiểm soát toàn diện khóa bí mật và lưu lượng dữ liệu.
| Mô hình kiến trúc | Vị trí mạng | Quản lý chứng thực | Kiểm soát chuyển mạch | Nén tải trọng token |
|---|---|---|---|---|
| SDK trực tiếp | Phân tán tại client | Rải rác theo từng ứng dụng | Thủ công qua try-catch client | Prompt thô chưa nén |
| SaaS gateway proxy | Đám mây bên thứ ba | Lưu trên máy chủ bên ngoài | Cấu hình qua control plane đám mây | Middleware đám mây tùy chọn |
| Proxy cục bộ (OmniRoute) | Giao diện loopback nội bộ | SQLite nội bộ với AES-256-GCM | Tự động chuyển mạch 4 tầng | Tích hợp sẵn engine RTK và Caveman |
Theo tài liệu ports.ts L1-L28, OmniRoute lắng nghe mặc định tại cổng 20128, cung cấp các endpoint chuẩn /v1/chat/completions, /v1/models và Anthropic /v1/messages. Client chỉ cần trỏ về một URL cục bộ duy nhất, trong khi OmniRoute tự động phân giải đích đến và chuẩn hóa luồng stream. Toàn bộ mã nguồn dự án được phân phối theo giấy phép LICENSE L1-L21 chuẩn MIT.
Cơ chế cascade chuyển mạch dự phòng qua bốn tầng tài nguyên
OmniRoute phân bổ tài nguyên kết nối thành chuỗi ưu tiên 4 tầng, tối ưu gói thuê bao trước khi dùng API tính phí. Theo tierTypes.ts L1-L25, các đích đến phân vào các nhóm miễn phí, giá rẻ và cao cấp. Khi gọi nhóm mô hình ảo, router kiểm tra tính khả dụng và hạn mức từng nhánh trước khi phát lệnh.
Hiện thực tại fallbackPolicy.ts L1-L48, router lưu chuỗi fallback trong SQLite qua bảng domain, tuần tự giải quyết ứng viên thay thế theo thứ tự ưu tiên khi nhà cung cấp chính gặp sự cố.
Hệ thống phân tầng tài nguyên:
- Tầng 1 (Thuê bao cố định): Gói tổ chức OAuth, web session bridge và thuê bao trả trước.
- Tầng 2 (API trả phí trực tiếp): Khóa API thương mại từ các nhà cung cấp mô hình lớn và gateway khu vực.
- Tầng 3 (Dịch vụ chi phí thấp): Endpoint suy luận giảm giá và năng lực điện toán spot.
- Tầng 4 (Nhóm miễn phí): Hạn mức dùng thử và endpoint cộng đồng không cần khóa.
# Gửi yêu cầu chat completion đến nhóm mô hình auto qua curl
curl -s http://localhost:20128/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [
{"role": "system", "content": "Bạn là trợ lý đánh giá mã nguồn."},
{"role": "user", "content": "Kiểm tra cấp phát bộ nhớ trong đoạn mã này."}
],
"temperature": 0.2
}'Nếu một endpoint trả về lỗi HTTP 429 hoặc gián đoạn kết nối, OmniRoute kích hoạt ngắt mạch nội bộ trong errorConfig.ts L25-L55. Fallback policy sẽ nạp danh sách dự phòng từ SQLite. Tùy chiến lược cấu hình (priority, round-robin, random, hoặc least-used), hệ thống chuyển tiếp request sang nhánh tiếp theo mà không làm đứt luồng SSE của client.
Các engine nén token tích hợp: Caveman, RTK và OmniGlyph
OmniRoute tích hợp các engine nén giúp giảm 15% đến 95% token tùy tác vụ. Lịch sử của AI agent lập trình thường chứa nhiều log terminal, kết quả test và Git diff làm đầy ngữ cảnh.
Hệ thống đăng ký engine module tại registry.ts L1-L40, cung cấp giao diện compress(input, config). Theo COMPRESSION_ENGINES.md L9-L50, pipeline hỗ trợ các chế độ:
rtk(Repetitive Token Trimmer / Knowledge): Bóc tách mã điều khiển terminal, gộp thanh tiến trình lặp lại, cắt tỉa danh sách tệp dư thừa và giữ nguyên định danh mã nguồn.caveman: Áp dụng kỹ thuật cô đọng ngôn ngữ tự nhiên vào ngữ cảnh hội thoại, lược bỏ câu chào hỏi nhưng giữ trọn chỉ thị kỹ thuật.omniglyph: Chuyển đổi khối ngữ cảnh lịch sử thành token hình ảnh cô đọng cho các nhà cung cấp hỗ trợ thị giác đa phương thức.stacked: Thực thi chuỗi biến đổi tuần tự, đưa log thô quartktrước khi cô đọng quacaveman.
// Cấu hình minh họa kích hoạt pipeline nén dạng xếp tầng
const compressionConfig = {
mode: "stacked",
engines: ["rtk", "caveman"],
rtk: {
stripAnsi: true,
collapseRepetitiveLogs: true,
maxStackFrameDepth: 12
},
caveman: {
condenseHistory: true,
preserveSystemPrompt: true
}
};
export default compressionConfig;Các bộ xử lý nén vận hành bên trong tiến trình Node.js cục bộ trước khi truyền dữ liệu qua mạng, đảm bảo prompt không cần gọi thêm dịch vụ xử lý phụ trợ từ bên ngoài.
Ranh giới bảo mật: Route guard cục bộ và mã hóa AES-256-GCM
OmniRoute áp dụng ủy quyền route 3 tầng và mã hóa cấp trường để ngăn ngừa rủi ro chạy lệnh ngoài ý muốn. Theo routeGuard.ts L1-L35, kiến trúc bảo mật duy trì 3 tầng kiểm soát:
- Tầng 1 (LOCAL_ONLY): Giới hạn nghiêm ngặt cho loopback (
127.0.0.1,localhost,::1). Các route khởi tạo tiến trình hệ thống, thăm dò nhị phân CLI hoặc quản lý subprocess (như/api/mcp/và/api/cli-tools/) sẽ từ chối truy cập ngoài localhost với mã HTTP 403 Forbidden. - Tầng 2 (ALWAYS_PROTECTED): Các thao tác thay đổi dữ liệu, xóa database và cập nhật token bắt buộc phải xác thực phiên đăng nhập.
- Tầng 3 (MANAGEMENT): Các route quản trị thông thường yêu cầu đăng nhập mật khẩu khi được bật.
Dựa trên triển khai trong encryption.ts L30-L55, các thông tin nhạy cảm lưu trong SQLite được bảo vệ bằng mã hóa đối xứng xác thực. OmniRoute dùng AES-256-GCM với muối dẫn xuất tĩnh (omniroute-field-encryption-v1) qua scryptSync, cố định thẻ xác thực đầy đủ 16 byte (AUTH_TAG_LENGTH = 16). Cơ chế này ngăn chặn giả mạo cắt ngắn thẻ tag GCM và cô lập dữ liệu an toàn.
Tích hợp Model Context Protocol và hỗ trợ AI agent
Theo tài liệu MCP-SERVER.md L9-L43, OmniRoute tích hợp máy chủ Model Context Protocol cung cấp 110 công cụ chuyên biệt qua stdio, Server-Sent Events và streamable HTTP. Các môi trường AI như Claude Code, Cursor hay Cline dùng giao diện này để kiểm tra máy chủ, theo dõi hạn mức và đổi mô hình linh hoạt.
{
"mcpServers": {
"omniroute": {
"command": "omniroute",
"args": ["--mcp"],
"env": {
"PORT": "20128"
}
}
}
}Các nhóm công cụ chính:
- Điều khiển định tuyến: Giám sát chuỗi fallback, chuyển đổi combo mô hình và theo dõi circuit breaker.
- Đo lường token: Theo dõi hạn mức nhóm miễn phí và tỷ lệ nén token.
- Bộ nhớ ngữ cảnh: Lưu trữ và truy vấn ngữ cảnh dài hạn qua các bảng vector SQLite.
- Quản lý cache: Xóa bộ đệm phản hồi ngữ nghĩa và làm mới kết nối.
Nhờ giao diện MCP, các AI agent có thể chủ động điều chỉnh chiến lược định tuyến trực tiếp bằng code trong các tác vụ dài hạn.
Quy trình triển khai và kiểm thử thực tế
Theo quy định trong package.json L66-L70, việc cài đặt và vận hành OmniRoute yêu cầu Node.js phiên bản 22 trở lên trên máy chủ. Lập trình viên có thể triển khai gateway qua npm hoặc nhân bản từ kho mã nguồn.
# Cài đặt toàn cục qua npm package manager
npm install -g omniroute
# Khởi chạy dịch vụ gateway trên cổng loopback mặc định 20128
omniroute --port 20128Sau khi khởi động, lập trình viên xác minh cổng lắng nghe HTTP phản hồi chính xác trước khi định tuyến editor:
# Kiểm tra tình trạng dịch vụ và danh sách nhà cung cấp khả dụng
curl -s http://localhost:20128/api/monitoring/health
# Kiểm tra cổng đang lắng nghe trên macOS hoặc Linux
lsof -iTCP:20128 -sTCP:LISTENNếu cổng 20128 đang được tiến trình khác sử dụng, kỹ sư có thể giải phóng cổng hoặc chỉ định cổng khác thông qua biến môi trường PORT hoặc OMNIROUTE_PORT trước khi khởi chạy.
Rào cản vận hành, tiêu hao bộ nhớ và độ trễ
Proxy cục bộ đòi hỏi tài nguyên hệ thống nhất định. Khi vận hành liên tục cùng IDE, OmniRoute tiêu tốn từ 180MB đến 450MB RAM tùy kích thước bộ đệm SQLite và số lượng kết nối đồng thời.
Duyệt chuỗi fallback khi dịch vụ ngoài bị chậm sẽ làm tăng độ trễ mạng. Từ góc nhìn vận hành, yêu cầu gặp sự cố ở Tầng 1 trước khi hoàn tất ở Tầng 2 chịu độ trễ của cả hai lần kết nối. Ngoài ra, tính ổn định của nhóm miễn phí phụ thuộc chính sách bên ngoài.
Kỹ sư cũng cần lưu ý mức nén: rút gọn prompt quá mức có thể làm mất ngữ cảnh quan trọng trong mã nguồn phức tạp. Bạn nên kiểm tra kỹ các quy tắc nén trên tác vụ thứ yếu trước khi áp dụng rộng rãi.
