Chuyển đến nội dung chính
OrcaRouter có thể thử nhiều mô hình theo thứ tự cho đến khi một cái thành công. Hữu ích cho khả năng phục hồi (nếu một nhà cung cấp đang bị throttle hoặc gặp sự cố) và kiểm soát chi phí (ưu tiên mô hình rẻ hơn, dự phòng sang mô hình mạnh hơn nếu cần).

​
Cách dùng

Đặt một danh sách model ID có thứ tự trong extra_body.models và đặt extra_body.route thành "fallback". Trường chính model vẫn quan trọng — nó là lần thử đầu tiên — nhưng OrcaRouter sẽ bỏ qua nó để ưu tiên chuỗi nếu chuỗi có mặt. 
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "..."}],
    extra_body={
        "models": ["openai/gpt-4o", "anthropic/claude-haiku-4.5", "google/gemini-2.5-pro"],
        "route": "fallback",
    },
)

​
Quy tắc

  • Tối đa 5 mô hình trong chuỗi. Phần thừa bị cắt bỏ âm thầm.
  • Khuyến nghị: tất cả mô hình trong một chuỗi nên có cùng loại endpoint (tất cả chat, hoặc tất cả image). Trộn mô hình chat với mô hình image sẽ không làm gateway sập, nhưng dự phòng thực sự phục vụ yêu cầu phải khớp endpoint bạn đã gọi (ví dụ nếu bạn gọi /v1/chat/completions, chỉ các mô hình chat trong chuỗi mới dùng được).
  • Hành vi dự phòng:
    • Các mục orcarouter/{name} không giải được (tên sai, router bị tắt) sẽ bị bỏ qua âm thầm.
    • Các mô hình mà khóa gọi không thể truy cập (không khớp danh sách trắng mô hình) sẽ bị bỏ qua âm thầm.
    • Khi mô hình chính thất bại tại upstream (5xx / 429 / lỗi mạng), mục tiếp theo trong chuỗi sẽ được thử.
    • Yêu cầu chỉ thất bại khi mọi mục trong chuỗi đã dùng hết.
    • Lưu ý streaming: một khi đã gửi bất kỳ byte phản hồi nào đến client, dự phòng không còn có thể kích hoạt — nếu upstream rớt giữa luồng, client sẽ thấy một luồng bị cắt cụt, không phải retry minh bạch trên mô hình tiếp theo.
  • Việc tính phí được thực hiện cho mô hình thực sự phục vụ phản hồi, theo giá của mô hình đó — không phải giá của mô hình chính.
  • extra_body.route phải đúng là "fallback" để chuỗi được kích hoạt. Bất kỳ giá trị nào khác (hoặc bị thiếu) → chuỗi bị bỏ qua và chỉ dùng model ở cấp cao nhất.

​
Làm sao biết mô hình nào đã phục vụ phản hồi

Kiểm tra các header phản hồi X-Orca-Fallback-Level và X-Orca-Fallback-Model. Xem Header phản hồi. 
response = client.chat.completions.with_raw_response.create(...)
served_by = response.headers.get("X-Orca-Fallback-Model", "primary")
# "primary" nghĩa là level 0; ngược lại là tên mô hình dự phòng

​
Khi nào không nên dùng

Nếu bạn muốn OrcaRouter tự động chọn mô hình rẻ nhất có sẵn mà không cần viết chuỗi, dùng orcarouter/auto thay thế. Chuỗi dự phòng dành cho trường hợp bạn muốn kiểm soát thứ tự một cách rõ ràng.