Phân loại lỗi cổng LLM là sự khác biệt giữa một sự cố được kiểm soát và một cơn bão thử lại tốn kém. Một cổng không nên coi mọi lệnh gọi mô hình thất bại là cùng một loại lỗi từ nhà cung cấp. Thông tin xác thực không hợp lệ, hết hạn ngạch, quá tải nhà cung cấp, yêu cầu không đúng định dạng, từ chối vì lý do an toàn, hết thời gian chờ và hủy bỏ từ phía máy khách đều cần các đường dẫn khôi phục khác nhau.
Lỗi phổ biến là gửi mọi thất bại vào cùng một vòng lặp thử lại và dự phòng. Điều đó có thể che giấu một khóa đã bị thu hồi, đốt cháy giới hạn chi tiêu, định tuyến nội dung không an toàn đến một nhà cung cấp khác, hoặc lặp lại công việc sau khi một phản hồi truyền trực tuyến đã bắt đầu. Một hệ thống phân loại lỗi cổng LLM thực tế cung cấp cho các đội kỹ thuật, sản phẩm và tài chính một ngôn ngữ chung để mô tả những gì đã xảy ra và những gì cổng nên làm tiếp theo.
Flatkey phù hợp với mô hình hoạt động này vì trang web công khai hiện tại của nó định vị sản phẩm như một bề mặt cổng duy nhất cho việc truy cập mô hình, định tuyến, thanh toán, phân tích sử dụng và kiểm soát hoạt động. Sử dụng bề mặt chia sẻ đó để phân loại các lỗi trước khi chọn hành vi thử lại, xếp hàng, dự phòng hoặc đóng khi thất bại.
Phân loại lỗi cổng LLM trong một bảng
Bắt đầu với loại lỗi, không chỉ riêng trạng thái HTTP. Cùng một họ trạng thái có thể có ý nghĩa khác nhau giữa các nhà cung cấp, SDK và hình dạng điểm cuối.
| Loại lỗi | Tín hiệu phổ biến | Thử lại? | Dự phòng? | Hành động của chủ sở hữu |
|---|---|---|---|---|
| Xác thực và quyền | 401, 403, khóa không hợp lệ, khóa bị thu hồi, dự án sai, IP không được ủy quyền, quyền bị từ chối |
Không tự động thử lại | Không | Xoay vòng hoặc sửa chữa thông tin xác thực, dự án, danh sách cho phép hoặc quyền |
| Hạn ngạch và giới hạn tốc độ | 429, giới hạn tốc độ, hết hạn ngạch, giới hạn chi tiêu, giới hạn token/yêu cầu, RESOURCE_EXHAUSTED |
Đôi khi, với backoff có giới hạn hoặc xếp hàng | Chỉ trong các quy tắc chi phí và chất lượng đã được phê duyệt | Giảm đồng thời, kiểm tra mức sử dụng, tăng giới hạn hoặc ngừng chi tiêu |
| Nhà cung cấp và vận chuyển | 500, 503, 529, quá tải, hết thời gian chờ, đặt lại kết nối, lỗi kết nối SDK |
Đôi khi, nếu có tính bất biến và trong thời hạn | Đôi khi, trước khi có đầu ra một phần và trong hợp đồng | Kiểm tra trạng thái nhà cung cấp, sức khỏe định tuyến, ngân sách thời gian chờ và khuếch đại thử lại |
| Yêu cầu và xác thực | 400, 422, JSON không đúng định dạng, mô hình không hợp lệ, tham số không được hỗ trợ, ngữ cảnh quá dài |
Không, trừ khi yêu cầu được thay đổi | Hiếm khi | Sửa lược đồ, kích thước prompt, hình dạng điểm cuối hoặc khả năng của mô hình |
| An toàn và chính sách | từ chối, chặn kiểm duyệt, chặn prompt, finishReason: SAFETY, lỗi chính sách nội dung |
Không tự động thử lại | Không dự phòng bỏ qua | Hiển thị thông báo an toàn cho người dùng, ghi lại bối cảnh an toàn, yêu cầu đầu vào đã sửa đổi khi thích hợp |
| Hủy bỏ từ máy khách và thời hạn | người dùng hủy bỏ, hết thời gian chờ của máy khách, thời hạn của máy chủ, luồng bị ngắt kết nối | Không thử lại một cách mù quáng | Chỉ khi không có đầu ra hoặc tác dụng phụ nào được thực hiện | Dừng công việc, đánh dấu hủy bỏ, bảo toàn trạng thái đầu ra một phần |
Hệ thống phân loại lỗi cổng LLM này được cố ý định hướng hành động. Nó không chỉ dán nhãn lỗi cho các bảng điều khiển. Nó quyết định khi nào hệ thống có thể chi tiêu nhiều token hơn, khi nào nó phải yêu cầu chủ sở hữu sửa chữa trạng thái và khi nào nó nên dừng lại.
Phân loại trước khi thử lại
Tài liệu chính thức của nhà cung cấp hỗ trợ việc phân tách các loại lỗi này. Hướng dẫn về lỗi của OpenAI phân biệt giữa xác thực không hợp lệ, khóa API không chính xác, lỗi danh sách IP cho phép, giới hạn tốc độ, hết hạn ngạch hoặc thanh toán, lỗi máy chủ, quá tải, lỗi kết nối SDK, hết thời gian chờ SDK, yêu cầu không đúng định dạng, từ chối quyền và các ngoại lệ giới hạn tốc độ. Hướng dẫn về giới hạn tốc độ của nó khuyến nghị sử dụng backoff theo cấp số nhân ngẫu nhiên nhưng cũng lưu ý rằng các yêu cầu thất bại vẫn được tính vào giới hạn mỗi phút.
Tài liệu về lỗi của Anthropic phân tách invalid_request_error, authentication_error, permission_error, not_found_error, request_too_large, rate_limit_error, api_error, và overloaded_error. Anthropic cũng ghi lại các giới hạn tốc độ 429 với hướng dẫn retry-after, và hướng dẫn về lý do dừng của nó bao gồm refusal như một điều kiện dừng ở cấp độ mô hình.
Khắc phục sự cố Gemini ánh xạ các lỗi xác thực và quyền riêng biệt với lỗi 429 RESOURCE_EXHAUSTED, lỗi nội bộ 500 và tình trạng không khả dụng 503. Tài liệu về giới hạn tốc độ của Gemini mô tả các chiều kích về yêu cầu, token, yêu cầu hàng ngày và chi tiêu. Cài đặt an toàn của Gemini cũng hiển thị các khối prompt, finishReason của ứng viên và safetyRatings, bao gồm finishReason là SAFETY khi nội dung phản hồi bị chặn.
Bằng chứng đó dẫn đến một quy tắc đơn giản: một hệ thống phân loại lỗi cổng LLM nên chuẩn hóa các tín hiệu dành riêng cho nhà cung cấp thành các trường quyết định trước khi cổng chọn một hành động.
Lỗi xác thực và quyền truy cập
Các lỗi xác thực và quyền truy cập nên dừng lại ngay lập tức. Việc thử lại một khóa không hợp lệ hoặc một dự án bị cấm thường chỉ tạo thêm nhiễu mà không thay đổi kết quả.
Chuẩn hóa các tín hiệu này vào lớp xác thực:
| Tín hiệu | Ý nghĩa có thể | Hành vi của cổng |
|---|---|---|
401 xác thực không hợp lệ |
Khóa sai, hết hạn, bị thu hồi, định dạng sai hoặc từ dự án không đúng | Không thử lại; cảnh báo chủ sở hữu khóa |
401 vấn đề về tư cách thành viên tổ chức hoặc dự án |
Người gọi không thuộc tổ chức hoặc dự án được yêu cầu | Không thử lại; chuyển đến chủ sở hữu tài khoản |
401 hoặc 403 danh sách IP cho phép hoặc vấn đề về quyền truy cập |
Yêu cầu đến từ mạng không đúng hoặc thiếu quyền truy cập điểm cuối | Không thử lại; hiển thị bằng chứng về quyền truy cập |
Lỗi authentication_error hoặc permission_error của nhà cung cấp |
Xác thực hoặc từ chối truy cập dành riêng cho nhà cung cấp | Không chuyển sang phương án dự phòng; sửa thông tin xác thực hoặc cấp quyền |
Trong một cổng, các lỗi xác thực nên bao gồm owner_key, credential_id, project_id, provider, endpoint_family, requested_model, và route_id. Tránh ghi lại các bí mật thô. Sự cố cần trả lời được khóa nào đã thất bại, tuyến nào đã cố gắng thực hiện cuộc gọi, và ai có thể khắc phục nó.
Chuyển sang phương án dự phòng thường là sai lầm đối với các lỗi xác thực. Nếu một nhóm chưa phê duyệt một nhà cung cấp, việc âm thầm chuyển sang một nhà cung cấp khác có thể bỏ qua các chính sách về mua sắm, ranh giới dữ liệu hoặc mô hình. Phản ứng được kiểm soát là một lỗi rõ ràng, một cảnh báo cho chủ sở hữu, và một lộ trình khắc phục.
Lỗi hạn ngạch và giới hạn tốc độ
Lỗi hạn ngạch và giới hạn tốc độ là loại lỗi thường bị ảnh hưởng nhiều nhất bởi logic thử lại không rõ ràng. Lỗi 429 có thể có nghĩa là điều chỉnh tốc độ đột biến, giới hạn yêu cầu mỗi phút, giới hạn token mỗi phút, giới hạn yêu cầu hàng ngày, hết ngân sách hàng tháng, hết tín dụng trả trước, hoặc giới hạn dựa trên chi tiêu. Những trường hợp đó không có chung một con đường phục hồi.
Sử dụng hệ thống phân loại lỗi cổng LLM này cho các quyết định về hạn ngạch:
| Tín hiệu hạn ngạch | Lộ trình thử lại | Lộ trình xếp hàng | Lộ trình dừng |
|---|---|---|---|
429 với Retry-After |
Tôn trọng header nếu nó phù hợp với thời hạn của quy trình làm việc | Xếp hàng các công việc không tương tác cho đến thời gian thử lại | Dừng nếu thời gian chờ vượt quá thời hạn |
| 429 không có gợi ý thời gian chờ | Sử dụng backoff ngẫu nhiên có giới hạn cho một ngân sách thử lại nhỏ | Giảm đồng thời cho chủ sở hữu, tuyến, hoặc họ điểm cuối | Dừng nếu các lần thử lặp lại làm tăng mức sử dụng mỗi phút |
| Chiều giới hạn token | Giảm prompt, output, kích thước lô, hoặc đồng thời | Xếp hàng các công việc lớn và chạy lại với các lô nhỏ hơn | Dừng nếu yêu cầu không thể phù hợp với hợp đồng mô hình hoặc ngữ cảnh |
| Hết chi tiêu hoặc tín dụng | Không tự động thử lại | Chỉ xếp hàng nếu chủ sở hữu tài chính đã phê duyệt nạp tiền hoặc tăng ngân sách | Thất bại và đóng lại, lưu giữ bằng chứng chi phí |
| Hết hạn ngạch hàng ngày/dự án | Không thử lại trong vòng lặp ngắn | Trì hoãn các công việc theo lô cho đến khi đặt lại chỉ khi được phép | Thất bại và đóng lại đối với các yêu cầu hướng tới người dùng |
Điều quan trọng là phải phân biệt giữa việc điều chỉnh tốc độ tạm thời và việc hết ngân sách. Backoff hữu ích khi nhà cung cấp yêu cầu bạn giảm tốc độ. Backoff không hữu ích khi tài khoản không có tín dụng hoặc công việc không thể phù hợp với ngân sách token có sẵn.
Kết hợp phần này với chiến lược thử lại AI API của Flatkey khi bạn cần một danh sách kiểm tra thử lại sâu hơn. Giữ cho các lần thử lại hiển thị trong nhật ký để bộ phận tài chính và vận hành có thể thấy chi tiêu token trùng lặp.
Lỗi nhà cung cấp và truyền tải
Lỗi nhà cung cấp và truyền tải khác với lỗi hạn ngạch. Chúng có nghĩa là yêu cầu có thể hợp lệ, khóa có thể hợp lệ, và ngân sách có thể có sẵn, nhưng tuyến không thể hoàn thành cuộc gọi.
Các tín hiệu phổ biến bao gồm:
| Tín hiệu | Ý nghĩa | Quyết định của cổng |
|---|---|---|
500 hoặc lỗi api_error của nhà cung cấp |
Lỗi nội bộ phía nhà cung cấp | Thử lại trong thời gian ngắn nếu là idempotent; kiểm tra trạng thái nếu lặp lại |
503 không khả dụng hoặc quá tải |
Tình trạng dung lượng, bảo trì hoặc ngừng hoạt động của nhà cung cấp | Backoff hoặc chuyển sang phương án dự phòng trước khi có đầu ra một phần |
Lỗi overloaded_error của Anthropic hoặc HTTP 529 |
Quá tải dành riêng cho nhà cung cấp | Xem như là dung lượng của nhà cung cấp, không phải hạn ngạch của khách hàng |
| Lỗi kết nối SDK | Đường dẫn mạng, proxy, TLS, DNS, hoặc tường lửa thất bại | Chỉ thử lại khi đường dẫn truyền tải có khả năng là tạm thời |
| Hết thời gian chờ SDK | Yêu cầu vượt quá ngân sách thời gian chờ | Chỉ thử lại nếu thời hạn quy trình làm việc và tính idempotent cho phép |
| Mất kết nối streaming | Đầu ra một phần có thể đã tồn tại | Chỉ tiếp tục với chính sách stream rõ ràng |
Chuyển sang phương án dự phòng của nhà cung cấp có thể hữu ích ở đây, nhưng nó cần một hợp đồng. Tuyến dự phòng phải bảo toàn hình dạng điểm cuối, công cụ, nhu cầu đầu ra có cấu trúc, cửa sổ ngữ cảnh, ranh giới dữ liệu, phê duyệt mô hình và giới hạn chi phí. Nếu streaming đã phát ra các token có thể nhìn thấy, hành vi an toàn hơn thường là dừng lại và hiển thị một lỗi được kiểm soát thay vì ghép nối đầu ra từ một tuyến khác.
Sử dụng độ tin cậy của API AI streaming để khôi phục dành riêng cho streaming, và sử dụng đánh giá dự phòng mô hình trước khi biến lỗi của nhà cung cấp thành thay đổi định tuyến tự động.
Lỗi yêu cầu và xác thực
Lỗi yêu cầu và xác thực thường không phải là sự cố từ nhà cung cấp. Chúng có nghĩa là người gọi đã gửi một thứ gì đó mà điểm cuối không thể xử lý.
Các ví dụ bao gồm thiếu các trường bắt buộc, JSON không đúng định dạng, các tham số không được hỗ trợ, họ điểm cuối sai, ID mô hình không hợp lệ, ngữ cảnh quá dài, lược đồ công cụ không được hỗ trợ, phương thức không tương thích, hoặc đầu vào tệp/hình ảnh/video không đáp ứng hợp đồng điểm cuối.
Gateway nên ghi lại các trường sau:
| Trường | Tại sao nó quan trọng |
|---|---|
endpoint_family |
Phân tách các định dạng trò chuyện, phản hồi, tin nhắn tương thích với OpenAI, Gemini, hình ảnh và video |
requested_model |
Xác định tên mô hình không hợp lệ hoặc không được hỗ trợ |
request_schema_version |
Cho thấy liệu client và gateway có bất đồng hay không |
parameter_name |
Chỉ cho các kỹ sư đến trường bị lỗi |
input_token_estimate |
Phân tách đầu vào không đúng định dạng khỏi tràn ngữ cảnh |
client_sdk và sdk_version |
Tìm các vấn đề về di chuyển và tương thích |
Không thử lại các lỗi xác thực không thay đổi. Hoặc chuyển đổi yêu cầu thành một định dạng hợp lệ hoặc trả về một lỗi dành cho nhà phát triển nêu rõ trường cần sửa. Khi một gateway hỗ trợ nhiều họ điểm cuối, lỗi xác thực đặc biệt quan trọng vì một yêu cầu có thể hợp lệ với nhà cung cấp này nhưng không hợp lệ với nhà cung cấp khác.
Lỗi an toàn và chính sách
Lỗi an toàn và chính sách cần có một lớp riêng vì việc thử lại và dự phòng có thể vô tình làm suy yếu các rào cản bảo vệ. Một từ chối an toàn không phải là thời gian ngừng hoạt động của nhà cung cấp. Một khối kiểm duyệt không phải là hết hạn ngạch. Một đầu ra bị chặn không phải là lý do để tiếp tục lấy mẫu cho đến khi gateway tìm thấy một tuyến đường phát ra nội dung bị cấm.
Chuẩn hóa các tín hiệu này vào lớp an toàn:
| Tín hiệu | Bằng chứng theo kiểu nhà cung cấp | Hành vi của Gateway |
|---|---|---|
| Mô hình từ chối | Đầu ra có cấu trúc của OpenAI tiết lộ các từ chối; lý do dừng của Anthropic bao gồm refusal |
Trình bày một phản hồi an toàn và không bỏ qua bằng cách dự phòng |
| Khối kiểm duyệt | Tài liệu an toàn của OpenAI khuyến nghị kiểm duyệt; lỗi hình ảnh có thể tiết lộ moderation_blocked |
Ghi lại ngữ cảnh danh mục an toàn và yêu cầu đầu vào đã sửa đổi khi thích hợp |
| Khối lời nhắc | Cài đặt an toàn của Gemini tiết lộ promptFeedback.blockReason |
Trả về một thông báo được kiểm soát trước khi gửi công việc tiếp theo |
| Khối đầu ra | Gemini có thể trả về finishReason: SAFETY và xếp hạng an toàn; nội dung bị chặn không được trả về |
Không thử lại một cách mù quáng; ghi lại rằng đầu ra đã bị chặn |
| Quy tắc chính sách hoặc tuân thủ | Chính sách dành riêng cho ứng dụng, mua sắm, ranh giới dữ liệu, tuổi tác, hoặc quy tắc quy trình công việc được quy định | Thất bại đóng hoặc chuyển đến đánh giá của con người |
Quy tắc thực tế rất đơn giản: một hệ thống phân loại lỗi gateway LLM không bao giờ nên coi an toàn là một sự cố có thể phục hồi của nhà cung cấp. Dự phòng chỉ có thể chấp nhận được khi tuyến đường dự phòng duy trì chính sách an toàn tương tự hoặc nghiêm ngặt hơn và mục tiêu là hoàn thành một phiên bản an toàn của nhiệm vụ, chứ không phải để bỏ qua khối chặn.
Bản ghi lỗi đã được chuẩn hóa
Một hệ thống phân loại lỗi gateway LLM hữu ích sẽ biến các lỗi cụ thể của nhà cung cấp thành một bản ghi bền vững duy nhất.
| Trường được chuẩn hóa | Giá trị ví dụ | Công dụng |
|---|---|---|
error_class |
auth, quota, provider, request, safety, cancelled |
Điều khiển việc nhóm runbook và dashboard |
http_status |
401, 403, 429, 500, 503, 529 |
Bảo toàn tín hiệu giao thức |
provider_error_type |
rate_limit_error, overloaded_error, RESOURCE_EXHAUSTED, moderation_blocked |
Bảo toàn ý nghĩa cụ thể của nhà cung cấp |
provider_error_code |
insufficient_quota, invalid_api_key, SAFETY |
Hỗ trợ phân nhánh chính xác |
retry_after_ms |
Độ trễ lấy từ header hoặc null | Ngăn chặn việc đoán thời gian thử lại |
retryable |
true hoặc false |
Tách biệt chính sách mã khỏi văn bản giao diện người dùng |
fallback_allowed |
true hoặc false |
Thực thi hợp đồng định tuyến |
fail_closed_reason |
quota_exhausted, safety_block, contract_mismatch |
Giải thích lý do tại sao gateway dừng lại |
requested_model và served_model |
ID hoặc bí danh của mô hình | Hiển thị liệu định tuyến có thay đổi hành vi không |
endpoint_family |
openai, anthropic, gemini, image-generation |
Làm cho các vấn đề di chuyển trở nên rõ ràng |
partial_output_committed |
true hoặc false |
Ngăn chặn đầu ra trùng lặp hiển thị cho người dùng |
usage_units và estimated_cost |
tokens, images, seconds, dollars | Làm cho chi phí thử lại trở nên rõ ràng |
request_id và provider_request_id |
ID của gateway và nhà cung cấp | Hỗ trợ các phiếu yêu cầu hỗ trợ và xem xét sự cố |
Đừng rút gọn bản ghi này thành một chuỗi duy nhất như "Lệnh gọi LLM không thành công". Chuỗi đó không đủ để quyết định xem có nên xoay vòng khóa, chờ đợi, nạp lại, dự phòng, sửa đổi lời nhắc hay dừng lại.
Một bộ phân loại TypeScript đơn giản
Bộ phân loại không cần biết mọi chi tiết của nhà cung cấp ngay từ ngày đầu tiên. Hãy bắt đầu với các nhóm rõ ràng và một giá trị mặc định an toàn khi có lỗi.
type ErrorClass =
| "auth"
| "quota"
| "provider"
| "request"
| "safety"
| "cancelled"
| "unknown";
type GatewayErrorInput = {
httpStatus?: number;
providerErrorType?: string;
providerErrorCode?: string;
finishReason?: string;
stopReason?: string;
clientCancelled?: boolean;
timeout?: boolean;
};
function classifyGatewayError(error: GatewayErrorInput): ErrorClass {
const type = (error.providerErrorType || "").toLowerCase();
const code = (error.providerErrorCode || "").toLowerCase();
const stop = (error.stopReason || "").toLowerCase();
const finish = (error.finishReason || "").toLowerCase();
if (error.clientCancelled) return "cancelled";
if (error.httpStatus === 401 || error.httpStatus === 403) return "auth";
if (type.includes("auth") || type.includes("permission")) return "auth";
if (code.includes("invalid_api_key") || code.includes("ip_not_authorized")) {
return "auth";
}
if (error.httpStatus === 429) return "quota";
if (type.includes("rate_limit") || code.includes("quota")) return "quota";
if (code.includes("resource_exhausted")) return "quota";
if (stop === "refusal" || finish === "safety") return "safety";
if (code.includes("moderation") || code.includes("blocked")) return "safety";
if (error.httpStatus === 400 || error.httpStatus === 422) return "request";
if (type.includes("invalid_request") || type.includes("bad_request")) {
return "request";
}
if (error.timeout) return "provider";
if ([500, 502, 503, 504, 529].includes(error.httpStatus || 0)) {
return "provider";
}
if (type.includes("overloaded") || type.includes("api_error")) {
return "provider";
}
return "unknown";
}
Chỉ sử dụng đoạn mã này như một điểm khởi đầu. Các bộ phân loại trong môi trường sản xuất nên giữ các ánh xạ dành riêng cho nhà cung cấp trong cấu hình, các bộ kiểm thử (test fixtures) và quá trình xem xét sự cố, chứ không chỉ chôn vùi trong mã ứng dụng.
Runbook: thử lại, xếp hàng, dự phòng hoặc đóng khi lỗi
Khi đã biết được loại lỗi, gateway có thể chọn hành động.
| Loại | Hành động mặc định | Điều kiện thử lại | Điều kiện dự phòng | Điều kiện thất bại-đóng |
|---|---|---|---|---|
| Xác thực | Dừng và cảnh báo chủ sở hữu | Không, trừ khi vừa làm mới thông tin xác thực | Không | Luôn luôn cho đến khi khóa hoặc quyền được sửa |
| Hạn ngạch | Lùi lại, xếp hàng đợi, hoặc dừng theo chiều giới hạn | Giới hạn tốc độ tạm thời phù hợp với thời hạn và ngân sách thử lại | Lộ trình được phê duyệt giữ nguyên chi phí, chất lượng và ranh giới dữ liệu | Vượt quá chi tiêu, tín dụng, hạn ngạch hàng ngày hoặc thời hạn |
| Nhà cung cấp | Lùi lại hoặc định tuyến vòng qua lỗi tạm thời của nhà cung cấp | Lệnh gọi Idempotent, không có đầu ra một phần, thời hạn vẫn còn | Tồn tại lộ trình tương đương được phê duyệt | Lỗi lặp lại, đầu ra một phần, hoặc quy trình làm việc có rủi ro cao |
| Yêu cầu | Trả về lỗi xác thực cho nhà phát triển | Chỉ sau khi yêu cầu bị thay đổi | Chỉ khi một điểm cuối/mô hình tương thích được chọn rõ ràng | Lược đồ không hợp lệ, tràn ngữ cảnh, khả năng không được hỗ trợ |
| An toàn | Trả về phản hồi an toàn hoặc yêu cầu sửa đổi | Không đối với nội dung không thay đổi | Chỉ với chính sách tương tự hoặc nghiêm ngặt hơn, không bao giờ để bỏ qua | Lời nhắc/đầu ra bị chặn, từ chối, quy tắc tuân thủ |
| Đã hủy | Dừng công việc và bảo toàn trạng thái | Không | Chỉ khi người dùng khởi động lại một cách rõ ràng | Người dùng hủy bỏ, hết hạn, máy khách bị ngắt kết nối |
Bảng này là trung tâm hoạt động của hệ thống phân loại lỗi cổng LLM. Nó cho cổng biết khi nào công việc tiếp theo là an toàn và khi nào công việc tiếp theo trở thành rủi ro.
Cách áp dụng điều này trong Flatkey
Sử dụng hệ thống phân loại này như một danh sách kiểm tra triển khai thay vì một dự án bảng điều khiển một lần.
- Chọn một quy trình làm việc, chẳng hạn như trò chuyện hỗ trợ, trích xuất hàng loạt, công việc đánh giá hoặc lưu lượng trợ lý mã.
- Xác định các họ điểm cuối được phép, mô hình, lộ trình dự phòng và giới hạn chi phí cho quy trình làm việc đó.
- Chuẩn hóa các lỗi của nhà cung cấp vào các trường ở trên.
- Làm cho các lỗi xác thực và quyền hiển thị với chủ sở hữu và không thể thử lại.
- Tách biệt giới hạn tốc độ tạm thời khỏi việc hết hạn ngạch, chi tiêu và giới hạn hàng ngày.
- Yêu cầu một hợp đồng dự phòng trước khi thay đổi nhà cung cấp hoặc mô hình.
- Xem việc từ chối vì lý do an toàn và kiểm duyệt là kết quả của chính sách, không phải là sự cố của nhà cung cấp.
- Ghi lại trạng thái đầu ra một phần trước bất kỳ lần thử lại hoặc dự phòng nào.
- Xem xét bằng chứng sử dụng và lộ trình trong Flatkey trước khi mở rộng sang nhiều quy trình làm việc hơn.
- Liên kết sổ tay vận hành đến bảng giá Flatkey để người vận hành có thể xác minh danh mục hiện tại và bề mặt chi phí.
Ảnh chụp nhanh API giá công khai của Flatkey vào ngày 3 tháng 7 năm 2026 đã trả về 45 hàng mô hình, sáu ID nhà cung cấp và các họ điểm cuối được hỗ trợ bao gồm openai, anthropic, gemini, và image-generation. Chỉ xem những thông tin đó là dữ kiện nguồn đã lỗi thời. Tính khả dụng của mô hình, giá cả và hành vi định tuyến nên được kiểm tra lại trước khi triển khai sản xuất.
Câu hỏi thường gặp
Hệ thống phân loại lỗi cổng LLM là gì?
Hệ thống phân loại lỗi cổng LLM là một tập hợp chuẩn hóa các loại lỗi cho lưu lượng truy cập giữa mô hình và nhà cung cấp. Nó phân tách các lỗi xác thực, hạn ngạch, nhà cung cấp, yêu cầu, an toàn và hủy bỏ để cổng có thể chọn hành vi thử lại, xếp hàng đợi, dự phòng hoặc thất bại-đóng.
Tại sao không thử lại mọi lỗi API LLM?
Việc thử lại mọi lỗi có thể làm cho sự cố trở nên tồi tệ hơn. Nó có thể khuếch đại giới hạn tốc độ, tiêu tốn nhiều token hơn sau khi hết hạn ngạch, che giấu lỗi thông tin xác thực, sao chép đầu ra một phần hoặc bỏ qua các khối an toàn. Hệ thống phân loại quyết định khi nào việc thử lại thực sự được phép.
Việc từ chối vì lý do an toàn có nên kích hoạt dự phòng không?
Không theo mặc định. Việc từ chối vì lý do an toàn, các khối kiểm duyệt, khối lời nhắc và finishReason: SAFETY nên được xem là kết quả của chính sách. Dự phòng không bao giờ nên được sử dụng để tìm một lộ trình an toàn yếu hơn.
Cổng LLM nên phân loại lỗi hạn ngạch như thế nào?
Tách biệt việc điều chỉnh tốc độ tạm thời khỏi việc hết chi tiêu, tín dụng trả trước, giới hạn hàng ngày, giới hạn token và giới hạn dự án. Việc điều chỉnh tốc độ tạm thời có thể sử dụng lùi lại có giới hạn hoặc hàng đợi. Ngân sách đã hết thường sẽ thất bại-đóng cho đến khi chủ sở hữu phê duyệt thêm dung lượng.
Flatkey giúp gì với hệ thống phân loại lỗi cổng LLM?
Flatkey cung cấp cho các nhóm một bề mặt cổng duy nhất để truy cập mô hình, định tuyến, thanh toán, phân tích sử dụng và kiểm soát hoạt động. Sử dụng nó để giữ các loại lỗi đã được chuẩn hóa gắn liền với khóa của chủ sở hữu, họ điểm cuối, mô hình được yêu cầu, mô hình được phục vụ và bằng chứng sử dụng.
Bắt đầu với một quy trình làm việc, xác định hệ thống phân loại lỗi cổng LLM của bạn, sau đó nhận một khóa và kiểm tra các trường hợp xác thực, hạn ngạch, nhà cung cấp, yêu cầu, an toàn và hủy bỏ trước khi lưu lượng sản xuất phụ thuộc vào việc phục hồi tự động.
