Khắc phục sự cố API tương thích OpenAI sẽ dễ hơn nhiều khi bạn ngừng coi mọi request thất bại là "nhà cung cấp đang gặp sự cố." Phần lớn các lần di chuyển thất bại đến từ một trong sáu lớp: key, base URL, họ endpoint, tên model, hành vi streaming hoặc billing/readback.
Flatkey giúp các đội ngũ giữ quyền truy cập model, routing, billing, phân tích sử dụng và kiểm soát vận hành ở một nơi, nhưng một client tương thích OpenAI vẫn cần cấu hình chính xác. Một request có thể trông đúng trong SDK nhưng vẫn lỗi vì client đang trỏ tới root /v1 sai, alias model thuộc về một họ endpoint khác, hoặc stream đang bị proxy đệm lại.
Hãy dùng hướng dẫn khắc phục sự cố API tương thích OpenAI này như một đường dẫn debug sạch trước khi bạn thay đổi mã ứng dụng. Bắt đầu với curl, xác minh một request không streaming, thêm SDK, rồi thêm streaming, tools và lưu lượng production từng lớp một.
Đường dẫn khắc phục sự cố API tương thích OpenAI trong năm phút
Trước khi bạn kiểm tra mã framework, hãy bắt lấy request nhỏ nhất đáng lẽ phải hoạt động. Với Flatkey, hãy dùng base URL hiển thị trong console hiện tại của bạn. Trang chủ Flatkey công khai hiện hiển thị một request tới https://router.flatkey.ai/v1/chat/completions, nghĩa là các client SDK thường nên nhận root /v1 làm base URL và SDK sẽ nối thêm /chat/completions.
export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-model-alias"
curl -sS "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{"role": "user", "content": "Reply with exactly: ok"}
]
}'
Nếu request này thất bại, vấn đề không nằm ở framework ứng dụng của bạn. Hãy sửa key, base URL, họ endpoint hoặc alias model trước. Nếu nó thành công, hãy sao chép cùng các giá trị đó vào SDK và tiếp tục debug từ đó.
Quy tắc khắc phục sự cố API tương thích OpenAI nhanh nhất rất đơn giản: đừng kiểm tra streaming, tools, chế độ JSON, retry, hoặc một workflow agent hoàn chỉnh cho đến khi một request văn bản không streaming đơn giản thành công.
Đọc lỗi như một lớp, không phải một phán quyết
Dùng mã trạng thái để quyết định cần thay đổi gì tiếp theo.
| Triệu chứng | Lớp có khả năng | Kiểm tra gì trước tiên |
|---|---|---|
401, invalid_api_key, hoặc lỗi xác thực |
Key và header auth | Định dạng Bearer, nguồn key, khoảng trắng bị sao chép, key của nhà cung cấp so với key của gateway |
403 hoặc bị từ chối quyền |
Tài khoản, dự án hoặc chính sách | IP allowlist, tư cách thành viên dự án, phê duyệt model, quyền endpoint |
404, model_not_found, hoặc model không xác định |
Danh mục model và họ endpoint | Alias model chính xác, trạng thái đã bật của model, /chat/completions so với /responses hoặc một endpoint khác |
400 request không hợp lệ |
Cấu trúc payload | Các trường bắt buộc, tham số không được hỗ trợ, schema tool, định dạng message |
| Stream kết nối nhưng không có token nào xuất hiện | Đường dẫn streaming | stream: true, SSE parser, proxy đệm, hỗ trợ stream của endpoint |
| Request thành công nhưng thiếu usage | Readback và billing | Request so sánh không streaming, bản ghi dashboard, hành vi của sự kiện stream cuối cùng |
429, 500, 502, 503, hoặc 504 |
Tốc độ, năng lực hoặc upstream | Backoff, khối lượng request, trang trạng thái, chính sách retry, route dự phòng |
Hướng dẫn lỗi của chính OpenAI coi 401 là vấn đề xác thực, 429 là vấn đề tốc độ hoặc quota, và các phản hồi 500/503 là điều kiện máy chủ hoặc quá tải có thể retry. Một gateway tương thích OpenAI có thể thêm chi tiết riêng, vì vậy hãy giữ nguyên response body và request ID khi bạn leo thang xử lý.
Sửa 401 trước khi đổi model
401 là lối rẽ khắc phục sự cố API tương thích OpenAI phổ biến nhất vì nó trông giống như vấn đề về model hoặc route trong khi thường là vấn đề auth.
Kiểm tra theo thứ tự sau:
- Request có đúng một header
Authorization: Bearer .... - Key là key của Flatkey khi gọi Flatkey, không phải key OpenAI, Anthropic, Google hoặc key test trực tiếp.
- Key không có dấu ngoặc kép bị sao chép, newline, tiền tố vô hình hoặc khoảng trắng cuối.
- Key được nạp từ môi trường mà tiến trình thực sự chạy trong đó, không chỉ từ shell của bạn.
- Tài khoản, dự án, nhóm hoặc chính sách IP cho phép route này.
Hãy dùng một kiểm tra shell ngắn không in ra key:
test -n "$FLATKEY_API_KEY" && echo "key is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c
Nếu curl hoạt động nhưng SDK trả về 401, hãy kiểm tra tên biến môi trường. Python client của OpenAI đọc OPENAI_API_KEY theo mặc định, và Node client cũng đọc OPENAI_API_KEY theo mặc định. Nếu ứng dụng của bạn vẫn export OPENAI_API_KEY với một key cũ từ nhà cung cấp trực tiếp, SDK có thể bỏ qua key gateway mới của bạn trừ khi bạn truyền api_key hoặc apiKey một cách rõ ràng.
Sửa base URL mà không nhân đôi endpoint
Lỗi base URL thường rơi vào hai kiểu:
- SDK nhận toàn bộ endpoint, chẳng hạn
https://router.flatkey.ai/v1/chat/completions, rồi lại nối thêm/chat/completionsmột lần nữa. - SDK chỉ nhận domain, chẳng hạn
https://router.flatkey.ai, và không bao giờ đi tới route/v1tương thích OpenAI.
Với Python, hãy truyền base_url hoặc đặt OPENAI_BASE_URL. Mã nguồn chính thức của Python client cũng sẽ quay về https://api.openai.com/v1 khi không cung cấp base URL tùy chỉnh.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["FLATKEY_MODEL"],
messages=[{"role": "user", "content": "Reply with exactly: ok"}],
)
print(response.choices[0].message.content)
Với Node, hãy truyền baseURL hoặc đặt OPENAI_BASE_URL. Tài liệu chính thức của Node client mô tả baseURL là phần ghi đè cho gốc API OpenAI mặc định.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: process.env.FLATKEY_MODEL!,
messages: [{ role: "user", content: "Reply with exactly: ok" }],
});
console.log(response.choices[0]?.message?.content);
Nếu bước khắc phục sự cố API tương thích OpenAI này vẫn thất bại, hãy ghi log base URL đã được phân giải khi khởi động tiến trình. Đừng ghi log key.
Tách tên model khỏi các họ endpoint
"Model not found" có thể có nghĩa là alias sai, nhưng cũng có thể là alias đang được gửi tới sai họ endpoint. Một model hoạt động cho chat completions có thể không được cung cấp qua Responses, Messages, ảnh, video hoặc embeddings với cùng dạng payload.
Hãy chạy danh sách kiểm tra này trước khi đổi tên model trong môi trường production:
| Kiểm tra | Vì sao điều này quan trọng |
|---|---|
| Xác nhận alias model chính xác trong Flatkey console hiện tại | Alias của gateway có thể khác với tên marketing của nhà cung cấp trực tiếp |
| Xác nhận họ endpoint | /v1/chat/completions và /v1/responses có dạng request khác nhau |
| Loại bỏ các tham số tùy chọn | Một tùy chọn không được hỗ trợ có thể che mất vấn đề thực sự của model |
| Thử một request ngắn không streaming | Một request đơn giản giúp cô lập route khỏi việc phân tích stream |
| Ghi lại body lỗi và dấu thời gian | Đánh giá hỗ trợ và kiểm tra audit cần model, route và lỗi chính xác |
Tài liệu model bên ngoài của OpenAI dùng cùng một ý tưởng cho các endpoint tùy chỉnh: cung cấp URL endpoint, chỉ định model slug, và chạy một lệnh xác minh. Hãy coi thiết lập gateway của bạn theo cùng cách. Giữ một map model được phê duyệt nhỏ trong code thay vì để mọi service tự dùng chuỗi model thô.
Gỡ lỗi streaming sau khi non-streaming hoạt động
Streaming nên là bài kiểm tra ở giai đoạn thứ hai. Tài liệu tham chiếu OpenAI Chat Completions trả về либо một đối tượng hoàn tất chat JSON hoặc một chuỗi streamed gồm các đối tượng chunk hoàn tất chat. Responses API cũng hỗ trợ text/event-stream khi bật stream.
Dùng một probe stream trực tiếp:
curl -N "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"stream": true,
"messages": [
{"role": "user", "content": "Đếm từ một đến năm thật chậm."}
]
}'
Nếu request không streaming hoạt động còn stream thì không, hãy kiểm tra đường dẫn stream:
- Xác nhận response dùng content type tương thích SSE.
- Tắt middleware của API client đệm toàn bộ response trước khi trả về.
- Tắt buffering của reverse proxy cho route này.
- Kiểm tra xem bộ phân tích frontend của bạn có đang mong đợi các chunk Chat Completions trong khi route của bạn trả về các event Responses hay không.
- So sánh với checklist streaming Flatkey hiện có tại
/blog/openai-compatible-streaming-sse-test.
Bước khắc phục sự cố API tương thích OpenAI này đặc biệt quan trọng trong các công cụ serverless và automation. Một số wrapper trả về trạng thái HTTP thành công trong khi che giấu việc không có token nào đến được phía gọi cho tới khi stream đóng lại.
Chỉ thêm tool sau khi request cơ bản đã sạch
Tool calling thêm một lớp lỗi nữa. Một gateway, route hoặc model được chọn có thể chấp nhận các tin nhắn chat thuần túy nhưng từ chối schema của tool, tool_choice, parallel tool calls hoặc các cài đặt đầu ra có cấu trúc nghiêm ngặt.
Hãy dùng một thang ba request:
- Request văn bản thuần với cùng model.
- Cùng request đó với một schema function rất nhỏ.
- Schema tool production đầy đủ.
Nếu request 1 hoạt động và request 2 thất bại, thì bạn không còn đang gỡ lỗi auth hay base URL nữa. Bạn đang gỡ lỗi khả năng của model, họ endpoint hoặc hỗ trợ schema. Hãy bỏ các trường tùy chọn, rút ngắn phần mô tả và xác minh xem route model được chọn có hỗ trợ hành vi tool bạn cần hay không.
Chứng minh khả năng đọc lại usage và billing
Đừng kết thúc việc khắc phục sự cố API tương thích OpenAI ở chỗ "phản hồi trả về văn bản." Đối với việc di chuyển lên môi trường production, bạn còn cần chứng minh rằng yêu cầu đó có thể được nhìn thấy ở nơi các nhóm tài chính và vận hành sẽ xem xét.
Sau một bài kiểm tra nhanh thành công, hãy ghi lại:
| Bằng chứng | Điều nó chứng minh |
|---|---|
| Dấu thời gian và tuyến của yêu cầu | Đường gateway nào đã nhận lưu lượng |
| Model alias | Model đã được cấu hình nào được yêu cầu |
| Trạng thái phản hồi và request ID | Những gì bộ phận hỗ trợ có thể truy vết |
| Đối tượng usage hoặc số lượng token | Ứng dụng có thể ghi nhận các yếu tố tạo chi phí hay không |
| Dashboard hoặc bản đọc lại từ billing | Finance có thể đối soát chi tiêu hay không |
| Sự kiện fallback hoặc retry, nếu có | Chính sách định tuyến có thay đổi đường đi hay không |
Flatkey được định vị xoay quanh một khóa, giá cả rõ ràng, hóa đơn hợp nhất, và một dashboard cho keys, usage, và routing. Khi di chuyển, hãy kết hợp bài kiểm tra nhanh của kỹ sư với kiểm tra đọc lại usage trong console trước khi bạn chuyển lưu lượng thực.
Quy trình khắc phục sự cố an toàn cho production
Hãy dùng chuỗi bước này khi quá trình di chuyển API tương thích OpenAI đang gặp lỗi:
- Chạy một yêu cầu curl không streaming với base URL hiện tại trong console, một key, và một model alias đã được phê duyệt.
- Khắc phục mọi lỗi 401 hoặc 403 trước khi thay đổi payload.
- Khắc phục cách ghép base URL trước khi thay đổi phiên bản SDK.
- Khắc phục model alias và họ endpoint trước khi thay đổi chính sách retry.
- Thêm SDK với
api_keyhoặcapiKeyvàbase_urlhoặcbaseURLmột cách rõ ràng. - Thêm streaming và xác minh rằng client nhận được các sự kiện tăng dần.
- Thêm tools hoặc structured output từng tính năng một.
- Kiểm tra usage và bản đọc lại billing.
- Chuyển các giá trị đang hoạt động vào một cấu hình sẵn sàng cho rollback.
Trình tự đó giúp việc khắc phục sự cố API tương thích OpenAI không biến thành một phiên đoán mò. Mỗi bước hoặc là xác minh một lớp, hoặc là cho bạn một lỗi nhỏ hơn để sửa.
Khi nào Flatkey hữu ích
Flatkey hữu ích khi vấn đề gốc là sự phình to trong vận hành: quá nhiều provider keys, quyền truy cập model không nhất quán, usage khó kiểm tra, và các luồng billing tách biệt. Một gateway hợp nhất không loại bỏ nhu cầu kiểm tra họ endpoint, model alias, streaming, tools, và billing readback, nhưng nó cho đội ngũ một nơi để chuẩn hóa các kiểm tra đó.
Nếu bạn đang di chuyển một ứng dụng, hãy ghép hướng dẫn này với hướng dẫn di chuyển tương thích OpenAI của Flatkey tại /blog/openai-compatible-api-migration và danh sách kiểm tra smoke test tại /blog/ai-api-smoke-test-checklist.
Khi bạn sẵn sàng kiểm tra quy trình với một Flatkey key, hãy bắt đầu tại /sign-up và giữ bài kiểm tra nhanh đầu tiên đủ nhỏ để có thể xem xét thủ công.
Câu hỏi thường gặp
Tại sao API tương thích OpenAI của tôi trả về 401 khi key đã được đặt?
Quy trình có thể đang đọc một biến môi trường khác với biến bạn đã thay đổi, hoặc key có thể thuộc về nhà cung cấp sai. Hãy kiểm tra tên biến đã được resolve, header Authorization: Bearer, khoảng trắng bị sao chép kèm theo, và bất kỳ chính sách tài khoản hoặc IP nào.
Base URL của SDK có nên bao gồm /chat/completions không?
Thường là không. Hãy đưa cho SDK base URL /v1, sau đó để SDK tự nối endpoint. Việc truyền toàn bộ endpoint thường tạo ra các đường dẫn bị lặp.
Tại sao một model hoạt động khi không streaming nhưng lại lỗi với stream: true?
Đường base route có thể đúng trong khi đường streaming bị chặn bởi middleware buffering, sai lệch bộ phân tích SSE, hoặc một tổ hợp route/model không hỗ trợ streaming. Hãy kiểm tra với curl -N trước khi gỡ lỗi mã frontend.
Tại sao lỗi "model not found" lại xảy ra với một model name hợp lệ?
Alias có thể hợp lệ trong một họ endpoint nhưng không hợp lệ trong họ khác, hoặc gateway có thể hiển thị một alias khác với provider trực tiếp. Hãy xác nhận cùng lúc alias hiện tại trong console và họ endpoint.
Tôi nên kiểm tra gì trước khi gửi lưu lượng production?
Hãy kiểm tra một yêu cầu không streaming, một yêu cầu SDK, một luồng stream, một lệnh gọi tool đại diện nếu ứng dụng của bạn dùng tools, một đường lỗi, và một bản ghi billing/readback. Sau đó giữ một cấu hình rollback cho tuyến provider trước đó.
Khắc phục sự cố API tương thích OpenAI không phải là ghi nhớ mọi lỗi của từng nhà cung cấp. Đó là việc chứng minh con đường từ key đến base URL, từ base URL đến họ endpoint, từ họ endpoint đến model alias, và từ phản hồi thành công đến bản ghi usage. Khi các lớp đó rõ ràng, việc chuyển lưu lượng qua Flatkey sẽ trở thành một quá trình di chuyển có kiểm soát thay vì một phiên gỡ lỗi giữa đêm.
