Các lỗi LiteLLM thường gặp: Timeout, cảnh báo ngân sách và lỗi nhà cung cấp

Các lỗi LiteLLM thường gặp: Timeout, cảnh báo ngân sách và lỗi nhà cung cấp

Hầu hết các lỗi LiteLLM thường gặp ban đầu đều trông giống vấn đề của nhà cung cấp: một yêu cầu bị timeout, cảnh báo ngân sách không bao giờ đến, hoặc một mô hình vốn hoạt động bình thường đột ngột trả về 404 hay 503. Cách khắc phục nhanh nhất là xác định lớp kiểm soát gặp lỗi trước khi thay đổi cơ chế thử lại hoặc đổi mô hình.

Hãy sử dụng hướng dẫn này để phân biệt thời hạn phía máy khách, chính sách gateway LiteLLM, cấu hình mô hình, năng lực nhà cung cấp và cơ chế thực thi chi tiêu. Hướng dẫn bao gồm một quy trình xử lý sự cố nhỏ mà bạn có thể lặp lại cho timeout, kiểm soát ngân sách và lỗi nhà cung cấp.

Trả lời nhanh: Lưu lại một yêu cầu thất bại, phân loại lỗi, tái tạo lỗi đó bằng một lệnh gọi tối giản và chỉ thay đổi từng cơ chế kiểm soát một lần. Hãy bắt đầu với loại ngoại lệ đã chuẩn hóa của LiteLLM, siêu dữ liệu yêu cầu và ID lệnh gọi — không chỉ mã trạng thái HTTP.

LiteLLM ánh xạ nhiều lỗi của nhà cung cấp sang các loại ngoại lệ tương thích OpenAI và hiển thị trạng thái HTTP, thông báo cũng như nhà cung cấp gốc trên ngoại lệ. Điều đó giúp việc khắc phục sự cố các lỗi LiteLLM thường gặp dễ dàng hơn khi bạn giữ nguyên ngữ cảnh lỗi ban đầu thay vì thay thế bằng một mã 500 chung chung. Xem tài liệu tham chiếu về ánh xạ ngoại lệ LiteLLM để biết ánh xạ hiện tại.

Ma trận các lỗi LiteLLM thường gặp

Bảng này là tài sản giá trị chính trong hướng dẫn về các lỗi LiteLLM thường gặp này: nó biến một lỗi gateway mơ hồ thành quan sát cụ thể tiếp theo.

Quy trình phân loại lỗi LiteLLM thường gặp trong năm phút

Trước khi chỉnh sửa config.yaml, hãy lưu một lỗi đại diện. Che giấu bí mật và nội dung prompt khi cần, nhưng giữ lại các trường vận hành.

1. Ghi lại danh tính yêu cầu. Lưu timestamp, môi trường, route, model được yêu cầu, trạng thái HTTP, loại ngoại lệ LiteLLM, thông báo lỗi, tên nhà cung cấp và số lần thử của máy khách.
2. Ghi lại danh tính gateway. Lưu x-litellm-call-id khi có. LiteLLM mô tả header này là cách tốt nhất để theo dõi một yêu cầu xuyên suốt các hệ thống logging. Đồng thời ghi lại x-litellm-model-id, x-litellm-model-api-base và các header phiên bản nếu phản hồi của bạn hiển thị chúng. tài liệu logging của LiteLLM liệt kê các header hiện tại.
3. Phân loại lỗi. Đây là yêu cầu không hợp lệ, vấn đề xác thực/quyền, giới hạn ngân sách/tốc độ, timeout hay lỗi dịch vụ upstream? Đừng đưa mọi lỗi 4xx vào cùng một nhóm thử lại.
4. Tạo một bản tái lập tối giản, không dùng môi trường production. Sử dụng cùng virtual key và model_name công khai mà ứng dụng sử dụng. Loại bỏ tính đồng thời dành riêng cho ứng dụng và các lệnh gọi công cụ trước khi kiểm tra một yêu cầu cơ bản.
5. Chỉ thay đổi một lớp. Việc sửa tên mô hình, thay đổi timeout và thay đổi fallback trong cùng một deployment khiến kết quả cuối cùng không thể giải thích được.

Dưới đây là một lệnh thăm dò tối giản chung cho proxy LiteLLM tương thích OpenAI:

curl -i --request POST "$LITELLM_PROXY_URL/v1/chat/completions" \
  --header "Authorization: Bearer $LITELLM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "support-chat",
    "messages": [{"role": "user", "content": "Reply with OK."}],
    "max_tokens": 16
  }'

Điểm mấu chốt không phải là support-chat là một tên mô hình phổ quát. Mà là bài kiểm tra phải sử dụng tên công khai được cấu hình trong gateway của bạn, sau đó lưu lại header và nội dung phản hồi để so sánh với yêu cầu ứng dụng đã thất bại.

Lỗi timeout: tìm thời hạn thực sự đã hết

Timeout là một trong những Lỗi LiteLLM thường gặp dễ gây hiểu lầm nhất vì một yêu cầu có thể hết hạn ở nhiều lớp:

• Bên gọi có thể hủy trước.
• Deployment hoặc router LiteLLM có thể áp dụng thời hạn ngắn hơn.
• request_timeout của proxy có thể dừng một lệnh gọi upstream chạy lâu.
• Nhà cung cấp, bộ cân bằng tải hoặc đường truyền mạng có thể đóng yêu cầu.
• Một phản hồi dạng stream có thể bắt đầu thành công rồi bị treo giữa các chunk.

Tài liệu ánh xạ ngoại lệ của LiteLLM ghi nhận các lỗi timeout là openai.APITimeoutError. Đối với các route native và pass-through, tài liệu timeout hiện tại mô tả thứ tự ưu tiên giữa các cài đặt request, deployment, router và proxy. Hãy kiểm tra phiên bản tài liệu khớp với deployment của bạn trước khi áp dụng thay đổi cấu hình.

Bắt đầu với ngân sách thời hạn, không phải một con số lớn hơn

Chọn tổng độ trễ mà luồng người dùng của bạn có thể chấp nhận, rồi phân bổ ngược lại. Ví dụ, một trải nghiệm tương tác có thể dành thời gian cho việc xếp hàng, một lần thử lại và hiển thị phản hồi, thay vì để lệnh gọi upstream sử dụng toàn bộ thời hạn mà người dùng nhìn thấy.

# Illustrative starting point — tune it to your workload and LiteLLM version.
litellm_settings:
  request_timeout: 60
  set_verbose: false
  json_logs: true

Ví dụ này được đặt ở mức thận trọng có chủ đích: nó tạo cho proxy một chế độ thất bại có giới hạn thay vì để các kết nối bị treo. Hướng dẫn cho môi trường production của LiteLLM khuyến nghị đặt timeout cho request và sử dụng logging có cấu trúc trong production.

Khi xảy ra timeout, hãy trả lời các câu hỏi này theo thứ tự:

Không để cơ chế thử lại timeout tự động lặp vô thời hạn. Chỉ nên thử lại khi công việc có thể lặp lại một cách an toàn và một lần thử thay thế vẫn có thể hoàn thành trong thời hạn của bên gọi. Nếu một request kích hoạt công cụ, ghi dữ liệu hoặc bắt đầu một stream hiển thị cho người dùng, hãy xác định ngữ nghĩa idempotency và khởi động lại trước.

Đối với các vấn đề xếp hàng hoặc năng lực do 429 gây ra và biểu hiện dưới dạng độ trễ dài, hãy kết hợp phần này với hướng dẫn RPM, TPM và retry của Flatkey. Timeout có thể là triệu chứng của cơ chế kiểm soát tiếp nhận bị quá tải, chứ không phải là cài đặt thời lượng request.

Cảnh báo ngân sách: tách biệt thông báo khỏi thực thi

Hành vi ngân sách gây ra tỷ lệ không tương xứng các Lỗi LiteLLM thường gặp vì các nhóm thường gộp ba biện pháp kiểm soát khác nhau vào từ “cảnh báo”. Chúng không thể thay thế cho nhau.

Kiểm tra ngân sách đầu tiên: có cơ sở dữ liệu không?

Tài liệu ngân sách hiện tại của LiteLLM nêu rõ: ngân sách proxy của nó được thực thi dựa trên chi tiêu đọc từ cơ sở dữ liệu. Trên một deployment không có DB, max_budget toàn cục đã cấu hình không hoạt động như một mức trần chi tiêu đáng tin cậy; hành vi ngân sách của virtual key, team và user cũng phụ thuộc vào cơ sở dữ liệu.

Điều đó dẫn đến một mẫu lỗi phổ biến: một nhóm đặt max_budget, thấy cảnh báo khởi động hoặc giá trị cấu hình, rồi cho rằng lưu lượng production sẽ dừng tại ngưỡng đó. Đây sẽ không phải là biện pháp kiểm soát đáng tin cậy nếu thiếu thiết lập theo dõi chi tiêu cần thiết.

# Chỉ là chính sách minh họa. Xác thực bằng khóa không dùng cho môi trường production trước khi triển khai.
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  fail_closed_budget_enforcement: true

litellm_settings:
  max_budget: 100
  budget_duration: 30d

Hãy xem fail_closed_budget_enforcement là một quyết định về độ tin cậy, không phải giải pháp sao chép-dán. Tài liệu LiteLLM hiện tại giải thích rằng việc kiểm tra ngân sách nghiêm ngặt hơn có thể từ chối yêu cầu khi không thể xác minh chi tiêu; hãy kiểm thử hành vi lỗi của cơ sở dữ liệu và Redis cho quá trình triển khai của bạn trước khi bật rộng rãi.

Kiểm thử luồng ngân sách, không chỉ bảng điều khiển

Sử dụng một khóa hoặc nhóm dùng một lần trong môi trường không phải production và xác minh trình tự này:

1. Xác nhận proxy có thể đọc và ghi kho lưu trữ chi tiêu.
2. Tạo một ngân sách cứng có chủ ý nhỏ trong đúng phạm vi: khóa, nhóm, người dùng, dự án hoặc người dùng cuối.
3. Gửi một yêu cầu tối thiểu qua proxy.
4. Gửi yêu cầu thứ hai chắc chắn vượt ngưỡng.
5. Kiểm tra độc lập ngoại lệ trả về, bản ghi chi tiêu, khoảng thời gian đặt lại và kênh cảnh báo.
6. Xác nhận ứng dụng xử lý việc chặn do ngân sách mà không thử lại như thể đó là tình trạng quá tải nhà cung cấp tạm thời.

LiteLLM cũng ghi lại các khoảng thời gian ngân sách và các biện pháp kiểm soát ngân sách theo từng mô hình. Hãy chính xác về lịch đặt lại: biện pháp bảo vệ hằng ngày và mức trần hằng tháng giải quyết các rủi ro khác nhau.

Cảnh báo ngân sách Azure và cảnh báo ngân sách AWS là lớp dự phòng, không phải thay thế

Các từ khóa phụ Azure budget alerts và AWS budget alerts quan trọng vì cảnh báo thanh toán của nhà cung cấp đám mây bao phủ một ranh giới khác. Chúng có thể cảnh báo về chi tiêu của tài khoản nhà cung cấp hoặc gói đăng ký, bao gồm cả lưu lượng bỏ qua LiteLLM. Chúng không thay thế quyết định ở cấp gateway về việc liệu yêu cầu, khóa, tenant hoặc mô hình này có nên được chấp nhận ngay bây giờ hay không.

Hãy sử dụng cả hai lớp khi phù hợp:

• Chính sách ngân sách LiteLLM bảo vệ tuyến và tenant mà gateway có thể nhận diện.
• Cảnh báo ngân sách Azure hoặc cảnh báo ngân sách AWS giám sát chi tiêu tài khoản đám mây phía thượng nguồn.
• Sổ cái sử dụng gateway đối soát hai lớp này và hiển thị lưu lượng đã bỏ qua đường dẫn dự kiến.

Đối với chi tiêu OpenAI, tính năng kiểm tra tỷ lệ ghi nhận chi tiêu của LiteLLM có thể so sánh chi tiêu được theo dõi với OpenAI Organization Costs API. Tính năng này hiện có các điều kiện tiên quyết riêng theo nhà cung cấp, vì vậy hãy đọc tài liệu theo phiên bản trước khi coi đây là tính năng đối soát đa nhà cung cấp phổ quát.

Nếu nhu cầu vận hành rộng hơn một triển khai LiteLLM duy nhất, hãy xem hướng dẫn đánh giá bảng điều khiển thanh toán AI hợp nhất để biết các câu hỏi cần đặt ra về khóa, ngân sách, phân bổ, cảnh báo và đối soát.

Lỗi nhà cung cấp: xác minh riêng tên mô hình công khai và deployment thượng nguồn

Lỗi nhà cung cấp là các LiteLLM Common Errors dễ thấy nhất, nhưng thường là lỗi cấu hình gateway. Client thường gọi model_name công khai mà bạn cung cấp. Sau đó, LiteLLM phân giải tên đó thành mô hình nhà cung cấp, deployment, endpoint, thông tin xác thực và các tham số riêng của nhà cung cấp.

model_list:
  - model_name: support-chat       # Tên mà client yêu cầu
    litellm_params:
      model: azure/<deployment-name>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: os.environ/AZURE_API_VERSION

model_name và litellm_params.model là các khái niệm được chủ ý tách biệt. Khi client nhận lỗi mô hình không hợp lệ, trước tiên hãy so sánh chính xác tên được yêu cầu với model_name. Tài liệu quản lý mô hình của LiteLLM phân biệt tên mô hình công khai với mô hình nhà cung cấp và cung cấp quy trình kiểm tra kết nối cho các mô hình đã cấu hình.

Bảng quyết định cho lỗi nhà cung cấp

Loại ngoại lệ phải quyết định hành động tiếp theo. tài liệu tham chiếu ngoại lệ của LiteLLM ánh xạ các tình trạng 401, 402, 403, 404, 408, 429, 500 và 503 vào các lớp đã chuẩn hóa; tài liệu này cũng cung cấp các trường dành riêng cho nhà cung cấp để điều tra sâu hơn.

Thử lại, phương án dự phòng và thời gian làm nguội: khôi phục mà không che giấu sự cố

Thử lại và phương án dự phòng có thể giảm các lỗi dễ thấy, nhưng chúng cũng có thể biến lỗi cấu hình thành độ trễ, chi phí hoặc công việc trùng lặp. Việc xử lý tốt các Lỗi LiteLLM thường gặp sử dụng chính sách khác nhau cho cấu hình không hợp lệ và cho sự gián đoạn ngắn từ nhà cung cấp.

LiteLLM ghi nhận một cách phân chia hữu ích:

• Thử lại cố gắng khôi phục trong nhóm mô hình hiện tại.
• Phương án dự phòng chuyển sang nhóm mô hình khác sau số lần thử lại đã cấu hình.
• Thời gian làm nguội cô lập một deployment đang lỗi trong khi các lựa chọn thay thế lành mạnh vẫn khả dụng.

Dưới đây là một cấu hình minh họa nhỏ dựa trên hướng dẫn chuyển đổi dự phòng giữa các nhà cung cấp của LiteLLM:

model_list:
  - model_name: primary-chat
    litellm_params:
      model: openai/<primary-model>
      api_key: os.environ/PRIMARY_PROVIDER_KEY

  - model_name: backup-chat
    litellm_params:
      model: azure/<backup-deployment>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: os.environ/AZURE_API_VERSION

litellm_settings:
  num_retries: 1
  request_timeout: 30
  fallbacks: [{"primary-chat": ["backup-chat"]}]
  allowed_fails: 3
  cooldown_time: 30

Chỉ xác thực điều này bằng một lỗi nhà cung cấp có chủ đích trong môi trường không phải production. Tài liệu LiteLLM cảnh báo rằng các cờ fallback giả lập cũ không kiểm thử các yêu cầu proxy; một lỗi thực tế, được kiểm soát là con đường xác thực proxy phù hợp.

Không đưa các tình trạng 404, xác thực, quyền truy cập, schema và chính sách nội dung vào vòng lặp thử lại chung, trừ khi bạn đã thiết kế rõ một phản hồi riêng biệt. Tài liệu định tuyến của LiteLLM hỗ trợ các chính sách thử lại theo từng lỗi, bao gồm không thử lại đối với NotFoundError; điều đó ngăn tên mô hình không hợp lệ trở thành một sự cố kéo dài.

Trước khi bật phương án dự phòng giữa các nhà cung cấp, hãy xác thực hợp đồng sản phẩm:

• Hành vi cửa sổ ngữ cảnh và ngữ nghĩa gọi công cụ
• Hỗ trợ đầu ra có cấu trúc và định dạng phản hồi
• Yêu cầu về nơi lưu trữ dữ liệu, lưu giữ dữ liệu và chính sách khách hàng
• Hành vi an toàn và kỳ vọng về chính sách nội dung
• Giới hạn về độ trễ và chi phí
• Tính idempotent của các tác dụng phụ ở hạ nguồn

Phương án dự phòng phải có thể quan sát được sau yêu cầu, không được âm thầm. LiteLLM ghi nhận các trường như các fallback đã thử và nhóm mô hình ban đầu trong metadata nhật ký chi tiêu. Hãy theo dõi tỷ lệ fallback, tỷ lệ thành công cuối cùng, độ trễ do thử lại/fallback bổ sung và chi phí của tuyến thực sự phục vụ yêu cầu.

Để có thiết kế định tuyến rộng hơn, xem cẩm nang định tuyến dự phòng của Flatkey. Quy tắc vẫn như vậy: chỉ định tuyến khi phương án thay thế vẫn đáp ứng hợp đồng của quy trình làm việc.

Danh sách kiểm tra sẵn sàng ứng phó sự cố cho các vấn đề LiteLLM

Thực hiện danh sách kiểm tra này trước khi kết thúc một sự cố hoặc tuyên bố một trong các Lỗi LiteLLM thường gặp đã được khắc phục.

Khi nào nên đơn giản hóa bề mặt định tuyến

Một số nhóm muốn dùng LiteLLM vì nó tập trung hóa cấu hình mô hình, mức sử dụng và chính sách độ tin cậy. Những nhóm khác muốn vận hành ít hạ tầng gateway hơn. Câu trả lời đúng phụ thuộc vào bên sở hữu chính sách định tuyến, thông tin xác thực nhà cung cấp, việc thực thi ngân sách và vòng lặp ứng phó sự cố.

Flatkey hữu ích khi một ứng dụng cần một bề mặt tích hợp tương thích với OpenAI trên các tuyến mô hình được hỗ trợ, đồng thời giữ việc định tuyến, rà soát mức sử dụng và thanh toán gần nhau hơn. Nó không loại bỏ nhu cầu phân loại timeout, chặn ngân sách hoặc lỗi nhà cung cấp; nó giảm số lượng tích hợp máy khách đặc thù theo nhà cung cấp mà ứng dụng của bạn phải duy trì. Hãy bắt đầu với một khóa API cho nhiều mô hình AI hoặc hướng dẫn nhanh về API Flatkey khi bạn muốn đánh giá mô hình vận hành đó.

Để xem hướng dẫn thiết lập đầy đủ và ví dụ cấu hình, hãy xem hướng dẫn về proxy LiteLLM của chúng tôi.

Câu hỏi thường gặp

Có phải tất cả các lỗi LiteLLM thường gặp đều an toàn để thử lại?

Không. Lỗi xác thực, quyền, mô hình không hợp lệ, tham số không được hỗ trợ, ngân sách và đa số lỗi thanh toán cần được sửa cấu hình hoặc tài khoản. Chỉ thử lại các điều kiện rõ ràng là tạm thời, với ngân sách nhỏ cho số lần thử và thời gian, và chỉ khi thao tác có thể lặp lại một cách an toàn.

Tại sao max_budget không dừng chi tiêu trong proxy LiteLLM của tôi?

Trước tiên, hãy xác minh rằng proxy có cơ chế theo dõi chi tiêu dựa trên cơ sở dữ liệu cần thiết để thực thi ngân sách. Sau đó, hãy xác nhận rằng lưu lượng truy cập đi đến LiteLLM thay vì gọi trực tiếp nhà cung cấp, và khóa, nhóm, người dùng hoặc dự án đã cấu hình chính là phạm vi thực sự thực hiện yêu cầu. Tài liệu về ngân sách của LiteLLM giải thích yêu cầu về cơ sở dữ liệu và cách hoạt động của phạm vi.

Cảnh báo ngân sách Azure hoặc AWS có đủ để ngăn ứng dụng vượt mức không?

Chúng là các biện pháp dự phòng hữu ích ở cấp tài khoản nhà cung cấp, nhưng không quyết định liệu một yêu cầu gateway cụ thể có nên được chấp nhận hay không. Hãy duy trì cảnh báo thanh toán của nhà cung cấp, sau đó bổ sung ngân sách gateway đã được kiểm thử và giới hạn sản phẩm ở cấp ứng dụng, nơi ngữ cảnh yêu cầu đã được biết.

Tôi nên lưu những gì từ một lệnh gọi LiteLLM bị lỗi?

Hãy lưu nội dung lỗi đã được làm sạch, lớp ngoại lệ đã chuẩn hóa, trạng thái HTTP, tên nhà cung cấp, mô hình được yêu cầu, dấu thời gian, môi trường, số lần thử của máy khách và x-litellm-call-id khi có. Tránh ghi log khóa API và nội dung prompt/phản hồi nhạy cảm.

Fallback có thể che giấu một cấu hình sai không?

Có. Fallback có thể khiến yêu cầu của khách hàng thành công trong khi tuyến chính vẫn tiếp tục thất bại. Đó là lý do tỷ lệ fallback, lỗi theo từng tuyến, nhóm mô hình cuối cùng, độ trễ và chi phí cần có cảnh báo hoặc bảng điều khiển. Hãy coi tỷ lệ fallback tăng là một tín hiệu vận hành, không phải là một bản sửa lỗi đã hoàn tất.

Kết luận chính

Cách khắc phục bền vững cho Các lỗi LiteLLM thường gặp không phải là một số lần thử lại cố định hoặc timeout lớn hơn. Đó là một vòng lặp vận hành có thể lặp lại: ghi nhận lỗi thực tế, xác định lớp chính sách, xác thực thay đổi nhỏ nhất nhưng an toàn và chứng minh đường phục hồi bằng một kiểm thử có kiểm soát. Điều đó giúp timeout được giới hạn, cảnh báo ngân sách có ý nghĩa và lỗi nhà cung cấp đủ rõ ràng để khắc phục.

Nguồn

• Ánh xạ ngoại lệ LiteLLM
• Ngân sách và giới hạn tốc độ của LiteLLM
• Chuyển đổi dự phòng nhà cung cấp và fallback của LiteLLM
• Định tuyến, thử lại, cooldown và đồng thời của LiteLLM
• Các phương pháp hay nhất cho môi trường production của LiteLLM
• Ghi log LiteLLM
• Kiểm tra tỷ lệ ghi nhận chi tiêu của LiteLLM