NVIDIA-NeMo/Switchyard

Kết luận: fit · Công nghệ: llm-gateway · model-routing · openai-compatible · anthropic-compatible · benchmarking

Switchyard là một LLM gateway/router giúp định tuyến lưu lượng giữa nhiều model và nhà cung cấp, nhưng vẫn giữ tương thích API kiểu OpenAI và Anthropic. Với ~1722 stars, đây là dự án đáng chú ý cho các hệ thống cần fallback, benchmarking, và tối ưu chi phí/độ trễ mà không phải đổi nhiều code ở lớp ứng dụng. Phù hợp nhất khi bạn đang xây lớp trung gian cho AI app hoặc muốn chuẩn hóa cách gọi nhiều provider.

📖 Giới thiệu chi tiết

🧩 Nó là gì?

NVIDIA-NeMo/Switchyard là một LLM gateway/router: một lớp trung gian đứng giữa ứng dụng AI của bạn và các model AI để quyết định request nên đi tới model/provider nào.

Nói đơn giản: app của bạn vẫn gọi API kiểu OpenAI hoặc Anthropic như cũ, còn Switchyard lo phần “chuyển hướng”, “dịch định dạng”, đo hiệu năng và tối ưu chi phí phía sau.

🎯 Giải quyết vấn đề gì? Dành cho ai?

Khi làm ứng dụng dùng LLM, bạn thường gặp các câu hỏi như:

• Nên gọi model rẻ hay model mạnh?
• Nếu provider A lỗi thì có thể chuyển sang provider B không?
• Làm sao benchmark nhiều model mà không sửa nhiều code?
• Làm sao cho tool như Claude Code hoặc Codex CLI dùng được model open-source?
• Làm sao giữ API kiểu OpenAI/Anthropic nhưng backend có thể là vLLM, NVIDIA NIM, Ollama, OpenRouter hoặc endpoint tương thích OpenAI?

Switchyard sinh ra để giải quyết các việc đó.

Dự án này phù hợp với:

• Người đang xây AI app cần gọi nhiều LLM provider.
• Team muốn có một lớp trung gian để quản lý model, routing, fallback, metrics.
• Người muốn chạy coding agent như Claude Code, Codex CLI, OpenClaw qua model khác.
• Developer Rust muốn nhúng thuật toán routing LLM vào hệ thống riêng.

Không cần hiểu quá phức tạp: nếu app của bạn đang “gọi thẳng một model”, thì Switchyard giúp bạn biến nó thành “gọi qua một trạm điều phối thông minh”.

⚙️ Hoạt động ra sao?

• App hoặc agent gửi request theo API quen thuộc: OpenAI Chat Completions, OpenAI Responses hoặc Anthropic Messages.
• Switchyard nhận request đó như một proxy, tức là một cổng trung gian.
• Nó chọn backend/model phù hợp dựa trên cấu hình routing.
• Nếu backend dùng định dạng khác, Switchyard dịch request sang định dạng backend hiểu được.
• Backend xử lý xong, Switchyard dịch response ngược lại về định dạng mà client ban đầu mong muốn.
• Trong quá trình chạy, nó ghi lại metrics như số request, lỗi, độ trễ, token và overhead routing.

Các kiểu routing chính:

• passthrough: gửi thẳng tới một target, không quyết định phức tạp.
• random: chia traffic theo tỉ lệ cố định, hữu ích cho A/B test hoặc benchmark.
• llm_classifier: dùng một LLM để phân loại request rồi chọn model phù hợp.
• stage_router: dựa vào tín hiệu trong hội thoại, ví dụ tool result hoặc lỗi, để quyết định route.
• escalation: chạy model yếu trước, sau đó một “judge” đánh giá xem có cần gửi lại sang model mạnh hơn không.

Kiến trúc dễ hình dung:

Client / Agent
   |
   | OpenAI / Anthropic API
   v
Switchyard
   |
   | routing + translation + fallback + metrics
   v
Model backends: vLLM, NVIDIA NIM, Ollama, OpenRouter, OpenAI-compatible endpoint

🆚 Khi nào nên dùng / không nên

Nên dùng Switchyard khi:

• Bạn muốn đổi hoặc thử nhiều model mà không sửa nhiều code ở ứng dụng chính.
• Bạn cần routing giữa model rẻ/mạnh, model local/cloud, hoặc nhiều provider.
• Bạn muốn benchmark model bằng cách chia traffic.
• Bạn muốn coding agent vẫn dùng API quen thuộc nhưng request thực tế đi tới model khác.
• Bạn đang xây gateway/proxy LLM cho team hoặc sản phẩm.

Không nên dùng Switchyard khi:

• App của bạn chỉ gọi đúng một model, không cần fallback, benchmark hay routing.
• Bạn cần một giải pháp production thật ổn định ngay lập tức.
• Bạn không muốn vận hành thêm một proxy/server trung gian.
• Bạn chưa cần tối ưu chi phí, độ trễ hoặc chọn model linh hoạt.

So với gọi trực tiếp OpenAI/Anthropic SDK:

• Gọi trực tiếp đơn giản hơn, ít thành phần hơn.
• Switchyard linh hoạt hơn khi cần nhiều provider, nhiều model, routing và đo metrics.

So với tự viết gateway riêng:

• Tự viết có thể khớp 100% nhu cầu nội bộ.
• Switchyard giúp bạn có sẵn phần khó: dịch protocol, routing algorithm, metrics và cấu trúc proxy.

🚀 Bắt đầu nhanh

Có 3 cách dùng chính:

• Launcher Path: chạy Claude Code, Codex CLI hoặc OpenClaw thông qua Switchyard.
• Server Path: chạy Switchyard như một proxy độc lập.
• Library Path: nhúng routing vào app Rust của bạn.

Cách nhanh nhất để thử với launcher:

curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"
uv tool install --python 3.10 "nemo-switchyard[cli]"

export OPENROUTER_API_KEY=«bí mật đã ẩn»  # pragma: allowlist secret

switchyard launch claude --model switchyard
switchyard launch codex --model switchyard
switchyard launch openclaw --model switchyard

Nếu muốn chạy server proxy độc lập:

cargo install --locked switchyard-server

switchyard-server --help

Tạo file routes.toml, kiểm tra cấu hình rồi chạy server:

export OPENROUTER_API_KEY=«bí mật đã ẩn»  # pragma: allowlist secret

switchyard-server --config routes.toml --dry-run
switchyard-server --config routes.toml --host 127.0.0.1 --port 4000

Kiểm tra server còn sống không:

curl http://localhost:4000/health

Ví dụ cấu hình tối thiểu dạng ý tưởng cho routes.toml:

# routes.toml
# Ví dụ minh họa: cấu hình thực tế có thể cần chỉnh theo provider/model bạn dùng.

[clients.openrouter]
type = "openai"
base_url = "https://openrouter.ai/api/v1"
api_key_env = "OPENROUTER_API_KEY"

[targets.default]
client = "openrouter"
model = "openai/gpt-4o-mini"

[routes.switchyard]
type = "passthrough"
target = "default"

Nếu bạn viết app Rust và muốn nhúng routing:

[dependencies]
switchyard-libsy = { git = "https://github.com/NVIDIA-NeMo/Switchyard.git" }
switchyard-protocol = { git = "https://github.com/NVIDIA-NeMo/Switchyard.git" }

✅ Điểm mạnh & ⚠️ Hạn chế

✅ Điểm mạnh:

• Giữ tương thích API kiểu OpenAI và Anthropic, giúp app ít phải sửa code.
• Hỗ trợ routing qua nhiều model/provider, phù hợp benchmark và tối ưu chi phí.
• Có protocol translation giữa OpenAI Chat, Anthropic Messages và OpenAI Responses.
• Có metrics cho request, lỗi, latency, token và routing overhead.
• Có thể chạy như launcher, server proxy hoặc thư viện Rust.
• Hữu ích khi muốn dùng Claude Code, Codex CLI, OpenClaw với backend khác như vLLM, NVIDIA NIM, Ollama hoặc OpenRouter.

⚠️ Hạn chế:

• Dự án đang ở trạng thái pre-alpha, API và thuật toán có thể thay đổi nhiều trước v1.0.
• README cảnh báo đây là phần mềm thử nghiệm, không nên dùng cho production.
• Cần hiểu và quản lý thêm cấu hình route, target, client và provider key.
• Chạy qua proxy trung gian có thể thêm một chút độ trễ và độ phức tạp vận hành.
• Nếu nhu cầu chỉ là gọi một model duy nhất, Switchyard có thể hơi “quá tay”.