Chiến lược fallback AI API: xây dựng ma trận lỗi provider
Policy theo giai đoạn để chọn retry, same-contract fallback, dừng, đối soát Side Effect hoặc điều tra route.
Retry AI API, fallback route và thay thế model là ba hành động khác nhau. Retry lặp một attempt dưới cùng contract. Route fallback gửi model và protocol được yêu cầu sang một đường dẫn đủ điều kiện khác. Model Substitution đổi model, vì vậy quality, price, latency, hành vi Tool, Context Limit và output format đều có thể thay đổi.
Một policy đáng tin cậy phải xác định hành động được phép trước khi incident xảy ra. Quyết định cần dựa trên Failure Class, giai đoạn response, Idempotency của toàn bộ operation và số attempt còn nằm trong deadline của người dùng.
Tách retry, fallback và thay thế model
Dùng tên khác nhau trong configuration, log và runbook.
| Hành động | Thành phần thay đổi | Mục đích phù hợp | Rủi ro chính |
|---|---|---|---|
| Same-route retry | Thời gian và Attempt Number | Khôi phục lỗi tạm thời ngắn trên cùng route | Tiếp tục tạo tải lên dependency không khỏe |
| Same-contract fallback | Upstream Channel, Account hoặc Group có thứ tự | Giữ nguyên model và protocol khi một đường dẫn lỗi | Incompatibility ẩn giữa các route được cho là tương đương |
| Model substitution | Model ID hoặc Model Policy được đặt tên | Đánh đổi quality, cost hoặc availability đã được sản phẩm duyệt | Thay đổi hành vi và Billing âm thầm |
Không gọi cả ba là “retry”. Đội vận hành cần biết request được lặp lại, chuyển đường dẫn hay được model khác trả lời. Với người dùng, Model Substitution phải là Product Contract rõ ràng, không phải shortcut khôi phục vô hình.
Một số gateway hỗ trợ Provider hoặc Model Step theo thứ tự. Ví dụ, tài liệu fallback của Cloudflare cho biết Step nào tạo response thành công. Điều đáng học không phải policy cụ thể của vendor, mà là giữ Attempt-level Evidence mỗi khi route thay đổi.
Áp dụng bốn gate trước khi replay request
Chỉ Status Code không tạo thành Retry Policy. Hãy đánh giá:
- Failure Class: lỗi tạm thời, vĩnh viễn, do caller hay có kết quả không xác định?
- Response Phase: lỗi trước Header, trước output hiệu quả hay sau khi đã giao output?
- Idempotency: toàn bộ operation có thể lặp mà không tạo Side Effect trùng không?
- Attempt Budget: còn đủ Wall-clock Time và attempt chưa dùng không?
Retry Strategy của Google Cloud cũng tách hai điều cơ bản cho API nói chung: response cho biết retry có thể hữu ích hay không, còn Idempotency quyết định việc replay có an toàn hay không. 408, 429, 5xx, Socket Timeout và Disconnect thường là lỗi tạm thời, nhưng operation không idempotent cần điều kiện chặt hơn.
Trong AI Workflow, Idempotency vượt ra ngoài HTTP Request tới model. Replay Prompt có thể đề xuất lại email, refund, deploy hoặc Database Write. Tool Execution cần Stable Idempotency Key và result được lưu bền vững, ngay cả khi Inference chỉ Read-only.
Bắt đầu bằng Failure Matrix
Ma trận sau là Application Policy thận trọng. Gateway có thể đã thực hiện Same-contract Channel Failover nội bộ trước khi ứng dụng nhận terminal result, vì vậy cần phối hợp hai layer.
| Lỗi hoặc giai đoạn | Same-route retry | Same-contract fallback | Dừng hoặc điều tra | Lý do |
|---|---|---|---|---|
| Client Validation Error, Unsupported Field, Malformed Request | Không | Không | Sửa request | Lặp cùng contract không hợp lệ sẽ không thành công |
| Gateway Authentication, Authorization, Quota, Policy Denial | Không | Không | Sửa Account hoặc Policy | Provider Route khác không được vượt qua quyết định của gateway |
| Upstream Credential/Account Failure trước output | Không trên route lỗi | Có, nếu có Channel đã xác minh | Cô lập và điều tra Channel | Có thể loại credential lỗi mà vẫn giữ contract |
Network Failure hoặc 408 trước output |
Tối đa một attempt có giới hạn nếu idempotent | Có | Dừng tại deadline | Có thể tạm thời, nhưng kết quả sau Disconnect có thể mơ hồ |
429 trước output |
Retry trì hoãn theo Retry-After |
Có nếu route tương đương còn capacity | Dừng khi hết budget | Lặp ngay làm Rate Limit nặng hơn |
500, 502, 503, 504 trước output |
Có giới hạn và Backoff | Có | Điều tra route lỗi lặp lại | Thường tạm thời nhưng không chứng minh mọi route an toàn |
| Provider Response Schema-invalid trước downstream output | Thường không | Chỉ tới route đã xác minh cùng Schema | Cô lập hoặc kiểm tra Compatibility | Lặp implementation không tương thích hiếm khi giúp |
| Model Refusal hoặc Policy-safe Completion | Không | Không | Trả kết quả | Refusal hợp lệ không phải lỗi hạ tầng |
Caller Cancellation hoặc downstream 499 |
Không | Không | Dừng ngay | Caller không còn cần công việc |
| Partial Stream sau visible content hoặc Tool Arguments | Không replay trong suốt | Không fallback trong suốt | Đánh dấu Partial, ứng dụng quyết định | Stream thứ hai có thể lặp hoặc mâu thuẫn output |
| Không rõ Tool Side Effect đã hoàn tất | Không trước Reconciliation | Không trước Reconciliation | Kiểm tra Idempotency Record hoặc hệ thống đích | Re-inference có thể đề xuất lại cùng Side Effect |
503 trước mọi output khác hoàn toàn với kết nối đóng sau khi 400 token đã hiển thị.
Xem lúc stream bắt đầu là Commit Boundary
Trước Downstream Output, gateway có thể bỏ attempt lỗi và thử route khác mà không lộ hai câu trả lời. Sau byte có ý nghĩa đầu tiên, transparent replay không còn an toàn.
Khởi động lại stream có thể:
- lặp phần đầu câu trả lời;
- tạo phần tiếp theo khác;
- phát Function Call trùng với Call ID mới;
- thay đổi Usage và Cost mà không có ranh giới rõ;
- khiến Client không biết Event thuộc Attempt nào.
Nếu stream hỏng sau khi output bắt đầu, trả Terminal Partial hoặc Transport Error cùng Request Identity ban đầu. Ứng dụng có thể đưa nút “thử lại” rõ ràng, tiếp tục từ checkpoint an toàn hoặc bỏ partial output. Không nối Model Stream mới vào stream cũ như thể không có lỗi.
Với Function Calling, hãy lưu Tool Call Identity đã chấp nhận và Side-effect Result trước khi retry có thể tạo lại chúng. So sánh Function Calling giải thích quan hệ giữa Call ID và Application Idempotency.
Giới hạn backoff theo attempt và tổng thời gian
Exponential Backoff phân bố attempts theo thời gian; Jitter tránh việc nhiều client retry đồng loạt sau một outage chung.
delay_cap = min(max_delay, base_delay * 2^retry_index)
sleep_for = random_between(0, delay_cap)
Tuân theo Retry-After hợp lệ nếu nó còn nằm trong deadline. Backoff không phải quyền retry: Failure và Idempotency Gate phải qua trước.
Đặt Total Budget thay vì chỉ Retry Count:
- số attempt tối đa cho một User Action;
- Elapsed Time tối đa gồm Queue và Backoff;
- attempt trước và sau khi chọn Fallback Group;
- thời gian tối thiểu còn lại để tạo câu trả lời hữu ích;
- truyền Caller Cancellation tới mọi active attempt.
Với request tương tác có deadline 15 giây, ba attempt mỗi cái 10 giây không phải policy có thể thực thi. Batch Workload có thể dùng budget dài hơn nhưng vẫn cần Terminal Deadline và Durable Job Identity.
Ngăn Retry Amplification giữa các layer
Nếu SDK thử ba lần, gateway thử ba route cho mỗi request và Upstream Proxy gọi hai lần mỗi route:
3 client attempts × 3 gateway attempts × 2 upstream attempts = 18 provider calls
Một User Action biến thành 18 Provider Calls. Trong outage, Queueing, Rate Limit, chi phí và Recovery Time đều tăng.
Phân công Retry Ownership rõ ràng:
- gateway sở hữu Same-contract Channel Failover tức thời;
- ứng dụng quyết định toàn bộ User Action có thể lặp không;
- SDK Automatic Retries bị tắt hoặc giới hạn nếu gateway đã retry;
- Async Jobs dùng một Durable Job ID và Attempt Ledger;
- không layer nào bắt đầu attempt sau Caller Cancellation.
Ghi cả Attempt Number tại layer hiện tại và Stable End-to-end Request ID. Nếu không, mỗi thành phần chỉ có vẻ thử hai hoặc ba lần trong khi độ khuếch đại tổng bị ẩn.
Xác minh fallback thực sự giữ contract
Cùng một Model Name công khai không chứng minh hai route hoạt động giống nhau. Trước khi thêm Channel vào Fallback Set trong suốt, cần bằng chứng:
| Phạm vi contract | Bằng chứng cần có |
|---|---|
| Model Identity | Requested Model khả dụng mà không Silent Mapping |
| Endpoint | Request Responses hoặc Chat Completions được chấp nhận đúng configuration |
| Streaming | Event Types, Termination, Usage và Cancellation hoạt động |
| Structured Output | JSON Schema subset cần thiết và Strict Behavior hoạt động |
| Function Calling | Tools, Call IDs, Argument Streaming và Results Round-trip |
| Limits | Context, Output, Rate và Concurrency phù hợp Workload |
| Errors | Status và Error Bodies phân loại được mà không lộ Secrets |
| Usage and Cost | Tokens, Cache Fields, Service Tier và Price Policy rõ ràng |
| Safety and Region | Policy, Data Path và Residency vẫn phù hợp |
Nếu route trượt một yêu cầu bắt buộc, nó không phải fallback trong suốt cho workload đó. Route vẫn có thể dùng dưới Product Policy riêng và rõ ràng.
Đổi model luôn là quyết định sản phẩm. Cần xác định model được phép, Quality Floor, Price Ceiling, Tool Contract và User-visible Disclosure. Không âm thầm chuyển sang model rẻ hoặc yếu hơn chỉ vì route lỗi.
Hiểu fallback semantics hiện tại của Modelflare
Modelflare tìm đường dẫn đủ điều kiện cho model mà API Client yêu cầu. API Key thường có một Primary Group và có thể có danh sách Fallback Groups theo thứ tự. Smart API Key đánh giá Groups khả dụng theo Routing Strategy. Cả hai không được âm thầm thay Requested Model.
Group-level RPM Admission xảy ra trước Billing và Upstream Request. Nếu Group được chọn đã đầy, một Fallback Group theo thứ tự hoặc Smart Routing Candidate có thể được đánh giá; nếu không còn Group đủ điều kiện, request trả 429.
Trong Group, Channel Priority định nghĩa thứ tự Account Failover. Sau Upstream Error, Channel lỗi bị loại và việc chọn tiếp tục. Channel Failover hiện tại độc lập với RetryTimes và AutomaticRetryStatusCodes; nó dừng khi thành công, hết route, Caller Cancellation hoặc Downstream Output đã bắt đầu.
Đây là Same-model Path Decision nội bộ, không phải quyền cho Client thêm loop vô hạn. Xem Reliable AI API Routing để thiết kế Group và Channel, cùng AI API Error Troubleshooting để tách Gateway Policy Error khỏi Upstream Failure.
Giữ evidence cho từng attempt
200 cuối không chứng minh route đầu thành công. Final Channel ID cũng không mô tả attempts thất bại. Ít nhất hãy giữ:
- Stable Request ID và Caller-visible Correlation ID;
- Attempt Sequence và Group/Channel Reference;
- Model và Endpoint Contract của từng attempt;
- Failure Status, Error Class và Stream Phase;
- Downstream Output đã bắt đầu hay chưa;
- Timing Milestones và Cancellation State;
- Input, Output và Cached-token Usage nếu có;
- Cost Attribution cho từng attempt hoàn tất hoặc billable;
- Terminal Reason: Success, Exhausted, Cancelled, Partial hoặc Policy Stop.
Không lưu API Keys, Raw Prompts, Raw Responses hoặc Provider Credentials chỉ để chẩn đoán fallback. Redacted Error Classes và Timing Metadata thường đã đủ; Request Archives chỉ nên hạn chế, ngắn hạn và bật rõ ràng cho điều tra lỗi.
Diễn tập policy trước production traffic
Dùng Protocol Boundary thật với input an toàn, xác định:
- vô hiệu Primary Channel trước Headers và kiểm tra Same-model Path tiếp theo;
- trả Rate Limit và xác minh Attempt Limits cùng
Retry-After; - hủy Caller và chứng minh không attempt mới nào bắt đầu;
- ngắt stream sau output và ngăn transparent replay;
- gửi Invalid Request và xác nhận fallback không che lỗi;
- lặp Tool Workflow và xác nhận chỉ một Side Effect;
- dùng hết mọi route và kiểm tra một Terminal Error rõ ràng;
- xem Attempt Ledger rồi đối soát Usage và Cost.
Triển khai trước cho workload nhỏ. Theo dõi riêng Attempt Count, Success-after-fallback và Raw Success Rate, đồng thời giữ cách nhanh để loại route không khỏe. Mục tiêu không phải tối đa hóa fallback, mà là khôi phục an toàn trong deadline hữu hạn, giữ nguyên contract model và có evidence cho mọi attempt.