Các bài kiểm thử di chuyển base URL của AI API nên được thực hiện trước khi thay đổi biến môi trường, chứ không phải sau khi lưu lượng truy cập sản phẩm bắt đầu thất bại. Việc thay đổi một baseURL hoặc base_url duy nhất có thể đồng thời chuyển xác thực, lựa chọn mô hình, streaming, gọi công cụ, hồ sơ sử dụng, hành vi hạn ngạch và kiểm soát khôi phục sang một đường dẫn mới.
Flatkey được thiết kế cho các đội ngũ muốn có một khóa, một lớp định tuyến tương thích với OpenAI, và việc xem xét thanh toán và sử dụng rõ ràng hơn giữa các nhà cung cấp mô hình. Trang chủ công khai của Flatkey được kiểm tra vào ngày 7 tháng 7 năm 2026 đã hiển thị tuyến đường ví dụ https://router.flatkey.ai/v1/chat/completions, trong khi các trang mô hình và giá cả hiện tại đã công khai bối cảnh mô hình, điểm cuối, nhà cung cấp và thanh toán để xem xét. Hãy coi những trang đó là bằng chứng cho ngày di chuyển, sau đó chạy các bài kiểm thử sơ bộ (smoke test) trên tài khoản của riêng bạn trước khi chuyển lưu lượng truy cập.
Sử dụng hướng dẫn này như một chuỗi các bài kiểm thử di chuyển base URL của AI API một cách thực tế. Mục tiêu không phải là chứng minh mọi đường dẫn của ứng dụng. Mục tiêu là chứng minh đường dẫn an toàn nhỏ nhất thông qua base URL mới, sau đó thêm các tính năng từng lớp một.
7 bài kiểm thử di chuyển Base URL của AI API
Chạy các bài kiểm thử theo thứ tự này. Mỗi bài kiểm thử nên tạo ra bằng chứng mà bạn có thể đính kèm vào một phiếu triển khai.
| Kiểm thử | Điều nó chứng minh | Bằng chứng cần lưu |
|---|---|---|
| 1. Soạn thảo xác thực và base URL | Khóa, máy chủ, gốc /v1, và đường dẫn điểm cuối được kết nối đúng cách. |
Ảnh chụp môi trường đã biên tập, mã trạng thái, nội dung phản hồi, thời gian yêu cầu. |
| 2. Danh mục mô hình và họ điểm cuối | Bí danh mô hình đã chọn thuộc về điểm cuối bạn đang gọi. | Ảnh chụp màn hình hoặc xuất danh mục, bí danh mô hình, họ điểm cuối. |
| 3. Hoàn thành trò chuyện đơn giản | Một yêu cầu tối thiểu không streaming hoạt động mà không có sự phức tạp của SDK hoặc ứng dụng. | Lệnh Curl, ID phản hồi, văn bản đầu ra, đối tượng sử dụng nếu được trả về. |
| 4. Tương đương SDK | SDK của ứng dụng xây dựng cùng một tuyến đường mà curl đã chứng minh. | Base URL đã giải quyết, phiên bản SDK, phản hồi, nhật ký cấu hình khởi động không có bí mật. |
| 5. Streaming hoặc SSE | Các sự kiện tăng dần đến máy khách mà không bị đệm hoặc không khớp bộ phân tích cú pháp. | Mẫu luồng thô, loại nội dung, thời gian của token đầu tiên, sự kiện cuối cùng. |
| 6. Gọi công cụ hoặc hàm | Tuyến đường đã chọn hỗ trợ lược đồ công cụ và hành vi lựa chọn công cụ của bạn. | Yêu cầu lược đồ nhỏ, đầu ra gọi công cụ, nội dung lỗi nếu không được hỗ trợ. |
| 7. Sử dụng, hạn ngạch và khôi phục | Đường dẫn mới có thể nhìn thấy được đối với các hoạt động, và lỗi có thể được đảo ngược nhanh chóng. | Đọc lại từ bảng điều khiển, kết quả hạn ngạch, cấu hình trước đó, người sở hữu khôi phục. |
Đừng bỏ qua các bài kiểm thử ban đầu chỉ vì một trình bao bọc framework đã hoạt động trong môi trường staging. Hầu hết các bài kiểm thử di chuyển base URL của AI API thất bại vì SDK âm thầm đọc một khóa khác, nhận sai gốc base URL, hoặc gửi một mô hình hợp lệ đến sai họ điểm cuối.
Kiểm thử 1: Soạn thảo xác thực và Base URL
Bắt đầu bên ngoài ứng dụng. Bạn cần chứng minh rằng khóa và base URL có thể tiếp cận được hình dạng điểm cuối đơn giản nhất.
Lỗi phổ biến với base URL là truyền toàn bộ điểm cuối cho SDK. Đối với một SDK tương thích với OpenAI, base URL thường là gốc API, chẳng hạn như https://router.flatkey.ai/v1, và SDK sẽ nối thêm /chat/completions, /responses, hoặc một điểm cuối khác. Việc truyền https://router.flatkey.ai/v1/chat/completions làm base URL có thể tạo ra một đường dẫn bị trùng lặp.
Sử dụng một kiểm tra môi trường đã được biên tập trước:
test -n "$FLATKEY_API_KEY" && echo "FLATKEY_API_KEY is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c
printf '%s\n' "$FLATKEY_BASE_URL"
Sau đó thực hiện một yêu cầu trực tiếp:
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-current-flatkey-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: base url ok"}
]
}'
Nếu điều này trả về 401, hãy sửa khóa và tiêu đề xác thực trước khi thay đổi mô hình. Nếu nó trả về 404, hãy kiểm tra máy chủ, gốc /v1, và xem đường dẫn điểm cuối có bị trùng lặp không. Nếu nó trả về 403, hãy kiểm tra tài khoản, dự án, mô hình, khu vực, hoặc chính sách IP. Tài liệu về mã lỗi của OpenAI coi 401 là xác thực, 429 là giới hạn tốc độ hoặc hạn ngạch, và 500 hoặc 503 là các điều kiện máy chủ hoặc quá tải; một cổng kết nối có thể thêm chi tiết hơn, vì vậy hãy lưu lại nội dung phản hồi.
Kiểm thử 2: Danh mục mô hình và Họ điểm cuối
Một base URL tương thích với OpenAI không làm cho mọi tên mô hình đều có thể di động được. OpenAI API có một điểm cuối List models, và các điểm cuối Chat Completions và Responses của nó sử dụng các hình dạng yêu cầu khác nhau. Một cổng kết nối hoặc một tuyến đường tương thích với nhà cung cấp có thể công khai một mô hình cho một họ điểm cuối này nhưng không cho họ khác.
Trước khi bạn thay đổi cấu hình sản phẩm, hãy tạo một bản đồ mô hình nhỏ:
| Trường | Ví dụ |
|---|---|
| Bí danh ứng dụng | support_chat |
| Bí danh cổng | support-chat-primary |
| Mô hình nhà cung cấp hoặc bí danh mô hình Flatkey | Giá trị console hiện tại |
| Họ điểm cuối | chat, responses, images, embeddings, hoặc video |
| Chủ sở hữu | Nền tảng, sản phẩm AI, tự động hóa, hoặc đội hỗ trợ |
| Giá trị khôi phục | Mô hình trước đó và URL cơ sở trước đó |
Điều kiện đạt không phải là "tên mô hình trông có vẻ đúng". Điều kiện đạt là console Flatkey, thư mục mô hình, hoặc danh mục nhà cung cấp hiện tại hiển thị chính xác bí danh cho họ điểm cuối mà bạn dự định gọi. Liên kết công việc này với việc quản trị mô hình rộng hơn của bạn bằng hướng dẫn tên mô hình tương thích OpenAI.
Kiểm thử 3: Hoàn thành Chat đơn giản
Bài kiểm thử di chuyển base URL của AI API thứ ba là yêu cầu tạo nội dung thực tế nhỏ nhất. Giữ nó ở chế độ không truyền trực tiếp (non-streaming). Không bao gồm các công cụ, lược đồ JSON, tệp, hình ảnh, thử lại, hoặc phần mềm trung gian của ứng dụng.
Lưu:
| Trường | Tại sao nó quan trọng |
|---|---|
| Trạng thái HTTP | Xác nhận tuyến đã chấp nhận yêu cầu. |
| ID phản hồi hoặc ID yêu cầu | Cho phép bộ phận hỗ trợ theo dõi yêu cầu. |
| Mô hình đã trả về | Hiển thị mô hình hoặc bí danh nào đã xử lý yêu cầu. |
| Văn bản đầu ra | Xác nhận phản hồi đã được tạo ra. |
| Đối tượng sử dụng | Bắt đầu đối chiếu thanh toán và token. |
Nếu yêu cầu đơn giản thất bại, đừng gỡ lỗi streaming vội. Sử dụng hướng dẫn khắc phục sự cố API tương thích OpenAI để cô lập các vấn đề về khóa, tuyến, họ điểm cuối và bí danh mô hình trước.
Kiểm thử 4: Tương đương SDK
Sau khi curl hoạt động, hãy chứng minh rằng SDK xây dựng cùng một tuyến. Tài liệu chính thức hiện tại của OpenAI hướng các nhà phát triển đến các SDK chính thức cho JavaScript và Python. OpenAI cookbook cũng cho thấy việc sử dụng điểm cuối tùy chỉnh nơi một client được tạo với một token và một URL cơ sở tùy chỉnh. Để di chuyển, hãy làm điều này một cách rõ ràng trong mã thay vì dựa vào các giá trị OPENAI_API_KEY hoặc OPENAI_BASE_URL còn sót lại.
Mẫu Python:
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: sdk ok"}],
)
print(response.choices[0].message.content)
print(response.usage)
Mẫu Node:
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: sdk ok" }],
});
console.log(response.choices[0]?.message?.content);
console.log(response.usage);
Ghi lại URL cơ sở đã được giải quyết khi khởi động quy trình, nhưng không ghi lại khóa. Nếu curl thành công và SDK thất bại, hãy kiểm tra thứ tự ưu tiên của biến môi trường, phiên bản SDK, việc nối đường dẫn, các tiêu đề tổ chức/dự án, và hành vi proxy trước khi thay đổi mô hình.
Kiểm thử 5: Streaming hoặc SSE
Streaming là nơi nhiều quá trình di chuyển trông có vẻ ổn ở lớp HTTP nhưng lại thất bại trong ứng dụng. Tham chiếu Chat Completions của OpenAI trả về một đối tượng JSON hoặc các đoạn hoàn thành chat được truyền trực tiếp (streamed) khi streaming được bật. Responses API cũng có thể trả về text/event-stream, với tên sự kiện khác với các đoạn Chat Completions.
Chạy lệnh này sau khi yêu cầu không truyền trực tiếp hoạt động:
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": "Count from one to five slowly."}
]
}'
Điều kiện đạt:
| Kiểm tra | Điều kiện đạt |
|---|---|
| Loại nội dung | Luồng tương thích SSE, không phải là phản hồi JSON được đệm trừ khi được mong đợi. |
| Sự kiện đầu tiên | Client nhận được một sự kiện tăng dần trước khi phản hồi đầy đủ hoàn tất. |
| Bộ phân tích cú pháp | Các đoạn Chat Completions không được phân tích cú pháp như các sự kiện Responses, hoặc ngược lại. |
| Sự kiện cuối cùng | Client thấy việc hoàn thành và không làm rò rỉ các kết nối đang mở. |
| Xử lý việc sử dụng | Ứng dụng của bạn biết liệu việc sử dụng có xuất hiện trong sự kiện cuối cùng, một phản hồi đầy đủ, hay đọc lại từ bảng điều khiển. |
Để phân tích cú pháp luồng sâu hơn, hãy so sánh với bài kiểm thử SSE streaming tương thích OpenAI hiện có.
Kiểm thử 6: Gọi công cụ hoặc hàm
Việc gọi công cụ làm tăng rủi ro về lược đồ và khả năng. Hướng dẫn gọi hàm của OpenAI mô tả một luồng nhiều bước: gửi công cụ, nhận một lệnh gọi công cụ, thực thi mã ứng dụng, trả về đầu ra của công cụ, sau đó nhận phản hồi cuối cùng của mô hình. Một quá trình di chuyển URL cơ sở có thể thất bại ở bất kỳ ranh giới nào trong số đó ngay cả khi văn bản thuần túy hoạt động.
Đừng bắt đầu với toàn bộ bề mặt công cụ sản xuất của bạn. Hãy sử dụng một hàm nhỏ:
{
"model": "your-current-flatkey-model-alias",
"messages": [
{"role": "user", "content": "Use the tool for order A123."}
],
"tools": [
{
"type": "function",
"function": {
"name": "lookup_order",
"description": "Return a test order status.",
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"}
},
"required": ["order_id"],
"additionalProperties": false
}
}
}
],
"tool_choice": "auto"
}
Nếu điều này thất bại trong khi trò chuyện thông thường hoạt động, bạn không còn đang gỡ lỗi base URL nữa. Bạn đang gỡ lỗi khả năng của mô hình, họ điểm cuối (endpoint family), độ nghiêm ngặt của schema, tool_choice, hoặc hỗ trợ cổng (gateway) cho tuyến đường đã chọn. Hướng dẫn tương thích gọi công cụ (tool-calling) đã được công bố bao gồm một danh sách kiểm tra nhà cung cấp lớn hơn.
Kiểm thử 7: Mức sử dụng, Hạn ngạch và Quay lui
Các bài kiểm thử di chuyển base URL của AI API cuối cùng mang tính vận hành. Một phản hồi được tạo ra là không đủ nếu bộ phận tài chính không thể đối chiếu nó, hạn ngạch không hoạt động như mong đợi, hoặc việc quay lui đòi hỏi một thay đổi mã khẩn cấp.
Sau một lần kiểm thử sơ bộ (smoke test) thành công, hãy xác minh:
| Lĩnh vực | Nội dung cần kiểm tra |
|---|---|
| Đọc lại mức sử dụng | Yêu cầu xuất hiện trong phần sử dụng, nhật ký, thanh toán hoặc bảng điều khiển của Flatkey. |
| Các trường token | Các trường sử dụng prompt, completion, total, cached hoặc dành riêng cho tuyến đường được ghi lại ở nơi ứng dụng của bạn mong đợi. |
| Hành vi hạn ngạch | Một khóa có giới hạn thấp được kiểm soát hoặc khóa staging tạo ra một phản hồi hạn ngạch/tỷ lệ có thể nhận biết được. |
| Chính sách thử lại | 429, 500, 502, 503, và 504 tuân theo các quy tắc backoff và fallback của bạn. |
| Quay lui | Base URL cũ, khóa cũ, mô hình cũ và người sở hữu đã sẵn sàng trước khi chuyển đổi. |
Sử dụng một tệp quay lui đủ đơn giản để thực thi dưới áp lực:
# active
AI_API_BASE_URL=https://router.flatkey.ai/v1
AI_API_MODEL=your-current-flatkey-model-alias
# rollback
AI_API_BASE_URL_ROLLBACK=https://previous-provider.example/v1
AI_API_MODEL_ROLLBACK=previous-production-model
AI_API_ROLLBACK_OWNER=platform-oncall
Đừng dựa vào trí nhớ để quay lui. Lưu trữ cấu hình trước đó, cờ tính năng (feature flag), lệnh triển khai và lệnh xác minh trong cùng một phiếu triển khai với các bài kiểm thử di chuyển base URL của AI API.
Gói Bằng chứng cần lưu giữ
Đối với mỗi môi trường, hãy giữ một gói bằng chứng trả lời các câu hỏi sau:
| Câu hỏi | Bằng chứng |
|---|---|
| Điều gì đã thay đổi? | Base URL cũ, base URL mới, mô hình cũ, mô hình mới, phiên bản SDK. |
| Ai sở hữu nó? | Người sở hữu kỹ thuật, người sở hữu vận hành, người phê duyệt tài chính/mua sắm nếu cần. |
| Điều gì đã vượt qua? | Bảy bài kiểm thử, dấu thời gian, ID phản hồi, bản ghi sử dụng và ảnh chụp màn hình tuyến đường. |
| Điều gì đã thất bại? | Mã trạng thái, nội dung phản hồi, kết quả thử lại và quyết định. |
| Kế hoạch quay lui là gì? | Cấu hình trước đó, người sở hữu, thời gian dự kiến để hoàn nguyên và kiểm thử sơ bộ sau khi quay lui. |
Đây là lợi thế thực tế của việc chạy các bài kiểm thử di chuyển base URL của AI API trước khi chuyển đổi. Sản phẩm tạo ra (artifact) hữu ích cho việc xem xét triển khai, ứng phó sự cố, đối chiếu sử dụng và làm bằng chứng mua sắm.
Vai trò của Flatkey
Flatkey có thể giảm sự phân tán trong quá trình di chuyển bằng cách tập trung quyền truy cập mô hình, định tuyến, thanh toán, phân tích sử dụng và xem xét vận hành đằng sau một khóa duy nhất. Điều đó không loại bỏ sự cần thiết phải kiểm thử. Nó cung cấp cho nhóm một điểm kiểm soát duy nhất nơi các bộ phận kỹ thuật, tài chính và vận hành có thể kiểm tra cùng một bằng chứng về tuyến đường.
Trước khi bạn di chuyển, hãy xem lại các trang mô hình Flatkey và giá cả trực tiếp, xác nhận base URL của console hiện tại và bắt đầu với một bài kiểm thử tuyến đường nhỏ. Nếu bạn vẫn đang lên kế hoạch cho việc chuyển đổi rộng hơn, hãy kết hợp hướng dẫn này với hướng dẫn di chuyển API tương thích OpenAI. Khi bạn đã sẵn sàng để chạy các bài kiểm thử của riêng mình, hãy lấy một khóa và giữ cho yêu cầu đầu tiên đủ nhỏ để kiểm tra bằng tay.
Câu hỏi thường gặp
Kiểm thử di chuyển base URL của AI API là gì?
Kiểm thử di chuyển base URL của AI API là các bước kiểm tra trước khi chuyển đổi để chứng minh rằng gốc API mới hoạt động cho việc xác thực, định tuyến mô hình, trò chuyện thông thường, sử dụng SDK, streaming, công cụ, đọc lại mức sử dụng, hành vi hạn ngạch và quay lui.
Tôi nên kiểm thử curl hay SDK trước?
Hãy kiểm thử curl trước. Curl chứng minh khóa, URL, đường dẫn điểm cuối và bí danh mô hình hoạt động mà không bị ảnh hưởng bởi hành vi của framework. Sau đó, kiểm thử SDK với các giá trị tương tự.
Base URL có nên bao gồm /chat/completions không?
Thường là không. Cung cấp cho SDK gốc API như /v1, sau đó để SDK tự nối thêm điểm cuối. Chỉ sử dụng điểm cuối đầy đủ cho các yêu cầu curl trực tiếp.
Tại sao streaming thất bại trong khi trò chuyện thông thường hoạt động?
Streaming có thể thất bại vì tuyến đường đệm các phản hồi, bộ phân tích cú pháp phía máy khách mong đợi hình dạng sự kiện sai, middleware tiêu thụ luồng, hoặc họ điểm cuối đã chọn không hỗ trợ hình dạng luồng bạn đang sử dụng.
Nếu tôi chưa thể chạy các yêu cầu Flatkey trực tiếp thì sao?
Hãy giữ các đoạn mã làm mẫu, xác thực tài liệu công khai và cấu hình console, và không chuyển lưu lượng sản xuất cho đến khi một khóa thực sự chứng minh được bảy bài kiểm thử di chuyển base URL của AI API trong môi trường của riêng bạn.
Kết luận
Thay đổi URL cơ sở của AI API là một quá trình di chuyển trên môi trường production, chứ không phải là một chỉnh sửa chuỗi đơn thuần. Chạy các bài kiểm thử di chuyển URL cơ sở của AI API theo thứ tự: xác thực, danh mục mô hình, trò chuyện đơn giản, tính tương đương của SDK, truyền phát, công cụ, và việc sử dụng cộng với khả năng quay lui. Khi cả bảy bài kiểm thử đều vượt qua, việc thay đổi URL cơ sở sẽ trở thành một quá trình chuyển đổi có kiểm soát thay vì một phiên gỡ lỗi muộn màng.
