Một API key, nhiều nhà cung cấp mà không làm phức tạp client
Cách một gateway giữ giao diện OpenAI-compatible ổn định trong khi định tuyến, kiểm tra capability và failover ở phía server.
Cập nhật
Giữ contract public thật nhỏ#
Client chỉ nên cần ba thứ: một Base URL, một API key của hệ thống và một public model ID. Tên connection, credential upstream, thứ tự fallback và trạng thái cooldown là chi tiết vận hành nội bộ, không phải contract dành cho người dùng.
Thiết kế này giúp ứng dụng không phải thay code mỗi khi đội vận hành đổi nhà cung cấp hoặc điều chỉnh route. Nó cũng tạo một ranh giới bảo mật rõ ràng: secret của upstream không bao giờ xuất hiện trong dashboard hay response công khai.
Một request được định tuyến như thế nào#
Trước khi chọn provider, gateway lần lượt kiểm tra:
- API key, subscription và scope còn hợp lệ.
- Public model hoặc alias có nằm trong quyền truy cập của plan hay không.
- Candidate có hỗ trợ capability mà request yêu cầu hay không.
- Connection có active, đã kiểm thử cấu hình và còn khả dụng hay không.
- Quota và rate limit có cho phép request tiếp tục hay không.
Chỉ những candidate vượt qua toàn bộ bộ lọc mới được đưa vào policy định tuyến. Vì vậy, round robin không có nghĩa là chọn ngẫu nhiên giữa mọi connection; nó xoay vòng trong tập candidate đang hợp lệ.
Failover cần có ranh giới#
Gateway có thể thử candidate tiếp theo khi gặp timeout, lỗi kết nối, quota upstream cạn hoặc một số lỗi tạm thời như 429, 502, 503 và 504. Gateway không nên fallback mù với mọi lỗi 4xx: một request sai định dạng vẫn phải được trả về cho client để sửa.
Với streaming, ranh giới còn chặt hơn. Fallback chỉ an toàn trước khi response được commit. Sau khi byte đầu tiên đã được gửi cho client, gateway không tự phát lại request vì có thể tạo output trùng lặp.
Checklist tích hợp cho client#
- Dùng public model ID từ endpoint model discovery thay vì hard-code provider account.
- Đặt timeout phía client dài hơn thời gian xử lý bình thường nhưng vẫn có giới hạn.
- Chỉ retry request khi lỗi và phương thức sử dụng cho phép retry an toàn.
- Log request ID, status và latency; không log API key hoặc nội dung nhạy cảm.
- Theo dõi trang trạng thái khi tỷ lệ lỗi tăng đồng loạt.
Một gateway tốt không làm biến mất độ phức tạp của hệ thống phân tán. Nó gom độ phức tạp đó vào một lớp server có thể quan sát, kiểm thử và vận hành nhất quán.