Hướng dẫn AI

Xây dựng cổng đại lý lập trình đa nhà cung cấp với My Free Code

Tìm hiểu cách cài đặt My Free Code v0.8, cấu hình mô hình từ nhà cung cấp hoặc mô hình cục bộ, kết nối các đại lý lập trình, quản lý định tuyến theo cấp và cơ chế dự phòng theo thứ tự, xem giao diện quản trị và bảo mật cổng để sử dụng cục bộ.

28 tháng 8, 2026Thời gian đọc khoảng 23 phút

Xây dựng cổng đại lý lập trình đa nhà cung cấp với My Free Code

My Free Code làm được gì

My Free Code v0.8 là một gateway độc lập, hỗ trợ nhiều nhà cung cấp cho Claude Code và các coding agent khác. Gateway chạy FastAPI cục bộ, tiếp nhận yêu cầu từ agent, chọn model đã cấu hình, chuyển đổi yêu cầu cho nhà cung cấp tương ứng và truyền phản hồi về client theo luồng. Dự án không liên kết với Anthropic.

Gateway hỗ trợ giao thức Anthropic Messages tại /v1/messages, tính token Anthropic tại /v1/messages/count_tokens và endpoint tương thích với OpenAI Responses tại /v1/responses. Gateway cũng cung cấp chức năng khám phá model qua /v1/models, endpoint kiểm tra trạng thái tại /health, giao diện Admin cục bộ tại /admin và các API quản trị đã xác thực dưới /api/admin/*.

Tính năng chính

Nhiều giao thức agent: Tiếp nhận các yêu cầu tương thích với Anthropic Messages và OpenAI Responses qua một gateway duy nhất.
Khả năng của agent: Xử lý Server-Sent Events dạng streaming, định nghĩa công cụ, lệnh gọi công cụ, kết quả công cụ, hình ảnh và truyền nguyên trạng metadata suy luận.
Định tuyến theo tier Claude: Gán các model upstream khác nhau cho yêu cầu Fable, Opus, Sonnet và Haiku.
Định tuyến bền bỉ: Sử dụng cơ chế dự phòng model theo thứ tự, trì hoãn dựa trên trạng thái nhà cung cấp, kiểm soát đồng thời theo từng nhà cung cấp và kiểm soát theo cửa sổ giới hạn tốc độ.
Danh tính model ổn định: Giữ nguyên danh tính model công khai của gateway ngay cả khi bộ định tuyến gửi yêu cầu đến nhà cung cấp khác.
Chuẩn hóa suy luận: Giữ riêng ý định suy nghĩ theo kiểu Claude khỏi các trường yêu cầu đặc thù của từng nhà cung cấp.
Hỗ trợ model cục bộ: Kết nối Ollama, LM Studio hoặc llama.cpp qua các endpoint tương thích với OpenAI.
Trình khởi chạy agent: Chuẩn bị môi trường proxy cho Claude Code, Codex, Pi, OpenCode, Cline, Hermes, DeepSeek Harness, Grok Build và Muse Code.

Danh mục nhà cung cấp bao gồm nhiều dịch vụ đám mây và runtime cục bộ. Các nhà cung cấp phổ biến tương thích với OpenAI sử dụng chung một phương thức truyền tải, trong khi các nhà cung cấp có cơ chế xác thực hoặc giao thức đặc thù cần adapter riêng. Vì vậy, một mục trong danh mục không nên được hiểu là tuyên bố về khả năng hỗ trợ toàn diện nếu chưa có cấu hình riêng cho nhà cung cấp.

Kiến trúc hoạt động như thế nào

             Coding Agents / IDEs
                      |
          +-----------+-----------+
          |                       |
    Anthropic Messages       OpenAI Responses
          |                       |
          +-----------+-----------+
                      |
                FastAPI Gateway
                      |
                Model Router
                      |
          +-----------+-----------+
          |                       |
       Primary                  Fallbacks
          |                       |
          +-----------+-----------+
                      |
              Provider Runtime
                      |
       +--------------+--------------+
       |              |              |
 OpenAI-compatible  Specialized   Local
     adapter          adapter     runtime
       |              |              |
     APIs          provider API  Ollama/LM Studio

Thiết kế tách biệt các giao thức wire đầu vào khỏi việc định tuyến và tích hợp nhà cung cấp. Các adapter HTTP tiếp nhận yêu cầu, tầng ứng dụng chọn và thực thi một tuyến, còn runtime nhà cung cấp giao tiếp với transport tương thích OpenAI dùng chung, adapter chuyên biệt hoặc runtime cục bộ. Các trình khởi chạy CLI vẫn là một tầng riêng, có nhiệm vụ cấu hình môi trường client và ủy quyền việc thực thi cho coding agent đã cài đặt.

Cài đặt Gateway

Điều kiện tiên quyết

Python 3.10 trở lên.
Một bản sao cục bộ của repository.
Thông tin xác thực cho các nhà cung cấp từ xa mà bạn dự định sử dụng.
Client coding agent bạn muốn khởi chạy, đã được cài đặt và có sẵn trên PATH.

1. Tạo môi trường ảo

python -m venv .venv

2. Kích hoạt và cài đặt các dependency

Trên Windows PowerShell, chạy:

.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
copy .env.example .env

Trên macOS hoặc Linux, chạy:

source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env

3. Khởi động My Free Code

python -m my_free_code

Theo mặc định, gateway khả dụng tại http://127.0.0.1:8082. Bạn có thể kiểm tra dịch vụ qua http://127.0.0.1:8082/health và mở giao diện Admin cục bộ tại http://127.0.0.1:8082/admin.

Cấu hình Model và Nhà cung cấp

Chỉnh sửa tệp .env được tạo để chọn model mặc định, gán model cho các tier Claude và xác định danh sách dự phòng theo thứ tự. Ví dụ sau sử dụng model từ nhiều nhà cung cấp:

MODEL=open_router/openrouter/free
MODEL_SONNET=deepseek/deepseek-chat
MODEL_HAIKU=groq/llama-3.3-70b-versatile
MODEL_OPUS=nvidia_nim/meta/llama-3.3-70b-instruct
FALLBACK_MODELS=deepseek/deepseek-chat,ollama/llama3.1

Thêm API key tương ứng của các nhà cung cấp vào .env. Sử dụng .env.example làm tài liệu tham chiếu cho các trường cấu hình được hỗ trợ. Khởi động lại gateway sau khi thay đổi môi trường.

MODEL chọn model chung của gateway. Các biến dành riêng cho tier như MODEL_SONNET, MODEL_HAIKU và MODEL_OPUS cho phép bộ định tuyến chuyển các tier model Claude đến những dịch vụ upstream khác nhau. FALLBACK_MODELS là danh sách các lựa chọn thay thế được phân tách bằng dấu phẩy và sắp xếp theo thứ tự.

Kết nối Claude Code

Tùy chọn 1: Đặt môi trường thủ công

Trong Windows PowerShell, trỏ Claude Code đến gateway cục bộ tương thích với Anthropic:

$env:ANTHROPIC_BASE_URL="http://127.0.0.1:8082"
$env:ANTHROPIC_AUTH_TOKEN="local"
$env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
claude

Base URL chuyển hướng các yêu cầu của Claude Code đến My Free Code, trong khi tính năng khám phá mô hình cho phép ứng dụng truy vấn danh mục mô hình của gateway.

Tùy chọn 2: Sử dụng bộ điều hợp launcher

python -m my_free_code.cli.mfc claude

Launcher chuẩn bị môi trường proxy cục bộ, sau đó chuyển tiếp các tham số đến ứng dụng Claude Code đã cài đặt. Launcher không tự cài đặt ứng dụng này.

Khởi chạy các tác nhân lập trình khác

Cùng một lớp trừu tượng launcher hỗ trợ thêm một số ứng dụng:

python -m my_free_code.cli.mfc codex
python -m my_free_code.cli.mfc pi
python -m my_free_code.cli.mfc opencode
python -m my_free_code.cli.mfc cline
python -m my_free_code.cli.mfc hermes
python -m my_free_code.cli.mfc deepseek-harness
python -m my_free_code.cli.mfc grok
python -m my_free_code.cli.mfc muse

Trước khi chạy một trong các lệnh này, hãy xác nhận ứng dụng tương ứng đã được cài đặt và có thể truy cập qua PATH. Launcher chỉ thiết lập môi trường gateway và gọi chương trình hiện có.

Hiểu về cơ chế dự phòng theo thứ tự

Giả sử môi trường chứa cấu hình định tuyến sau:

MODEL_SONNET=deepseek/deepseek-chat
FALLBACK_MODELS=groq/llama-3.3-70b-versatile,ollama/llama3.1

Yêu cầu Sonnet trước tiên được gửi đến deepseek/deepseek-chat. Nếu lần thử đó thất bại trước khi tạo ra đầu ra, bộ định tuyến sẽ thử groq/llama-3.3-70b-versatile. Nếu lần thử thứ hai cũng thất bại trước khi có đầu ra, nó sẽ thử ollama/llama3.1.

Claude Code
    |
    v
deepseek/deepseek-chat
    |
    | failure before output
    v
groq/llama-3.3-70b-versatile
    |
    | failure before output
    v
ollama/llama3.1

Khi phản hồi dạng streaming đã bắt đầu gửi đầu ra, gateway không âm thầm chuyển sang nhà cung cấp khác. Điều này tránh việc lặp lại một lượt hoặc kết hợp các phản hồi chưa hoàn chỉnh từ những mô hình khác nhau.

Sử dụng mô hình cục bộ

Ollama

Khởi động riêng một dịch vụ Ollama, sau đó cấu hình base URL tương thích với OpenAI và mô hình:

OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
MODEL=ollama/llama3.1

LM Studio

Khởi động máy chủ cục bộ LM Studio và sử dụng:

LM_STUDIO_BASE_URL=http://127.0.0.1:1234/v1
MODEL=lmstudio/qwen3.5-coder

llama.cpp

Chạy máy chủ llama.cpp và cấu hình:

LLAMACPP_BASE_URL=http://127.0.0.1:8080/v1
MODEL=llamacpp/my-model

Các runtime cục bộ cũng có thể xuất hiện trong FALLBACK_MODELS, cho phép mô hình cục bộ đóng vai trò phương án thay thế khi yêu cầu từ xa thất bại trước khi phát ra đầu ra.

Cấu hình hành vi suy luận

Gateway tiếp nhận ý định suy nghĩ theo kiểu Claude và chuẩn hóa ý định đó trước khi bộ điều hợp nhà cung cấp chuyển đổi yêu cầu. Các chế độ được hỗ trợ:

auto
on
off

Có thể đặt thêm một mức độ nỗ lực:

low
medium
high

Việc tách biệt này giúp chính sách suy luận hướng đến tác nhân không phụ thuộc vào các trường riêng của từng nhà cung cấp. Mỗi bộ điều hợp có thể ánh xạ chế độ và mức độ nỗ lực đã chuẩn hóa sang các trường được nhà cung cấp thượng nguồn tương ứng tài liệu hóa.

Giám sát gateway

Mở Admin UI cục bộ tại:

http://127.0.0.1:8082/admin

API Admin JSON có xác thực bao gồm:

GET /api/admin/status
GET /api/admin/models
GET /api/admin/providers

Sử dụng các endpoint này để kiểm tra trạng thái gateway, danh mục mô hình và các nhà cung cấp đã cấu hình. Các endpoint quản trị yêu cầu xác thực và nên được giữ riêng tư.

Mẹo nâng cao

Giữ danh tính mô hình công khai ổn định

Một yêu cầu có thể được định tuyến đến mô hình theo từng cấp hoặc nhà cung cấp dự phòng, nhưng gateway vẫn giữ danh tính mô hình công khai ổn định. Vì vậy, ứng dụng khách có thể tương tác với mô hình gateway mà không cần theo dõi mọi quyết định định tuyến thượng nguồn.

Thiết kế thứ tự dự phòng có chủ đích

Đặt các mô hình trong FALLBACK_MODELS theo đúng thứ tự cần thử. Hãy cân nhắc khả năng cung cấp của từng nhà cung cấp và việc runtime cục bộ có nên là phương án cuối cùng hay không. Lưu ý rằng cơ chế dự phòng chỉ diễn ra trước khi đầu ra streaming được xác nhận.

Tôn trọng khác biệt giữa các nhà cung cấp

Nhiều nhà cung cấp sử dụng giao thức truyền tải tương thích với OpenAI, nhưng các cơ chế xác thực hoặc giao thức bất thường cần bộ điều hợp chuyên biệt. Hãy xác nhận bộ điều hợp và thông tin xác thực của nhà cung cấp liên quan đã sẵn sàng, thay vì giả định mọi mục trong danh mục đều hoạt động giống nhau.

Sử dụng trực tiếp các endpoint giao thức khi cần

Gửi yêu cầu Anthropic Messages đến /v1/messages.
Đếm token định dạng Anthropic qua /v1/messages/count_tokens.
Sử dụng giao diện tương thích với OpenAI Responses tại /v1/responses.
Khám phá các mô hình qua /v1/models.
Kiểm tra tình trạng dịch vụ qua /health.

Chạy bộ kiểm thử

pytest -q

Kho lưu trữ bao gồm các bài kiểm thử xác định cho việc định tuyến, chuyển đổi giao thức, xác thực, suy luận, danh mục mô hình và các thành phần streaming. Hãy chạy chúng sau khi thay đổi mã gateway, định tuyến hoặc nhà cung cấp.

Hướng dẫn bảo mật

My Free Code được thiết kế để sử dụng cục bộ. Hãy áp dụng các biện pháp phòng ngừa sau:

Giữ HOST=127.0.0.1 để dịch vụ chỉ liên kết với máy cục bộ.
Đặt PROXY_AUTH_TOKEN đủ khó đoán.
Không bao giờ đưa tệp .env vào hệ thống quản lý mã nguồn.
Không công khai trực tiếp các endpoint Admin trên Internet.
Giữ thông tin xác thực của nhà cung cấp trong môi trường hoặc cấu hình. Gateway không gửi thông tin xác thực của nhà cung cấp này cho nhà cung cấp khác.

Kết luận

My Free Code cung cấp một lớp tương thích và định tuyến cục bộ giữa các tác nhân lập trình với nhiều nhà cung cấp mô hình đám mây hoặc cục bộ. Sau khi cài đặt các phần phụ thuộc Python, cấu hình mô hình và thông tin xác thực, rồi khởi động gateway, bạn có thể kết nối Claude Code hoặc một ứng dụng khách được hỗ trợ khác, gán mô hình theo từng cấp Claude và xây dựng một chuỗi dự phòng có kiểm soát. Các lớp giao thức, định tuyến, nhà cung cấp và trình khởi chạy được tách biệt cũng giúp dự án dễ kiểm tra và thử nghiệm hơn.