Nếu ứng dụng của bạn đã sử dụng một OpenAI compatible API, việc chuyển sang Flatkey không nên bắt đầu bằng việc viết lại. Cách tiếp cận được kiểm soát sẽ nhỏ hơn: lấy một khóa Flatkey, trỏ SDK tương thích OpenAI của bạn tới https://router.flatkey.ai/v1, chọn một model ID từ danh mục Flatkey, và xác minh yêu cầu đầu tiên trong logs, quotas, và billing trước khi bạn gửi traffic thực.
Giá trị thực tế của một OpenAI compatible API là như vậy. Nó cho phép một nhóm giữ cùng mô hình tư duy cho các yêu cầu phổ biến trong khi chuyển quyền truy cập nhà cung cấp ra sau một cổng duy nhất. Nội dung sản phẩm công khai của Flatkey được xây dựng xoay quanh cách tiếp cận đó: một API key, một base URL, pricing rõ ràng, unified billing, và một dashboard duy nhất cho keys, usage, và routing.
Hướng dẫn này trình bày runbook di chuyển. Nó bao gồm thay đổi base URL, các ví dụ SDK, ánh xạ model ID, smoke tests, kiểm tra endpoint, xem xét usage-log, thiết lập quota, xác minh billing, và rollback. Hãy dùng nó khi bạn đang chuyển một workflow kiểu Chat Completions hiện có sang Flatkey hoặc chuẩn hóa một stack đa mô hình sau một endpoint OpenAI compatible API duy nhất.
Câu trả lời nhanh: Điều gì thay đổi trong quá trình di chuyển sang API tương thích OpenAI?
Đối với hầu hết các client chat tương thích OpenAI hiện có, lần di chuyển đầu tiên là một thay đổi cấu hình, không phải viết lại ứng dụng.
| Cài đặt | Trước đây | Với Flatkey |
|---|---|---|
| Khóa API | Khóa riêng của nhà cung cấp OpenAI, Gemini, DeepSeek, hoặc proxy | Khóa API Flatkey |
| Base URL | URL mặc định của nhà cung cấp hoặc một base URL tương thích OpenAI khác | https://router.flatkey.ai/v1 |
| Điểm cuối chat | /v1/chat/completions |
/v1/chat/completions thông qua Flatkey |
| Mô hình | ID mô hình của nhà cung cấp hiện tại | ID mô hình Flatkey được chọn từ trang giá/bảng điều khiển |
| Xác thực | Chỉ cần một phản hồi thành công | Phản hồi + log sử dụng + chi phí + hạn mức + rollback |
Từ quan trọng là "compatible". Một OpenAI compatible API không đảm bảo rằng mọi nhà cung cấp, mô hình, điểm cuối và tham số đều hoạt động chính xác như OpenAI. Điều đó có nghĩa là API tuân theo đủ mẫu yêu cầu và phản hồi của OpenAI để các lệnh gọi client phổ biến hoạt động khi base URL, khóa và mô hình là chính xác. Danh sách kiểm tra di chuyển của bạn nên xác minh chính xác các tính năng mà ứng dụng của bạn sử dụng.
Tại sao các endpoint tương thích OpenAI đang trở thành lớp di chuyển
Kết quả tìm kiếm cho OpenAI compatible API chủ yếu là tài liệu chính thức, tài liệu nhà cung cấp, plugin, tài liệu máy chủ cục bộ và các câu hỏi từ cộng đồng. Điều đó hoàn toàn hợp lý. Các nhà phát triển không chỉ hỏi “tương thích là gì?” Họ đang cố gắng chuyển mã giữa các nhà cung cấp mô hình mà không phải thay đổi mọi điểm gọi.
Tài liệu Gemini của Google hiển thị các ví dụ thư viện OpenAI thiết lập một base URL tương thích OpenAI của Gemini và gọi chat completions. Tài liệu API chính thức của DeepSeek hiển thị các ví dụ OpenAI SDK với base URL của DeepSeek và các model ID như deepseek-chat và deepseek-reasoner. Mẫu hình rất rõ ràng: nhiều nhà cung cấp đang gặp gỡ các nhà phát triển ngay tại nơi các SDK hiện có của họ đang hoạt động.
Flatkey sử dụng cùng ý tưởng di chuyển đó cho một mục tiêu khác. Thay vì trỏ OpenAI compatible API của một nhà cung cấp tới một tài khoản nhà cung cấp duy nhất, Flatkey cung cấp cho các đội ngũ một base URL tương thích OpenAI duy nhất để truy cập đa mô hình, hợp nhất thanh toán và hiển thị trên bảng điều khiển.
Bước 1: Kiểm kê Client Bạn Đang Có
Trước khi thay đổi base URL, hãy ghi lại những gì ứng dụng hiện tại của bạn thực sự sử dụng. Một quá trình di chuyển API tương thích OpenAI gọn gàng bắt đầu từ hình dạng lời gọi thực tế, không phải từ một ứng dụng mẫu mới.
| Kiểm tra | Cần Ghi Lại |
|---|---|
| SDK | Python, Node, HTTP trực tiếp, LangChain, LiteLLM, Vercel AI SDK, hoặc một wrapper khác. |
| Endpoint | Chat Completions, Responses, embeddings, images, video, hoặc endpoint gốc của nhà cung cấp. |
| Model ID | Chuỗi chính xác được dùng trong production và bất kỳ mô hình dự phòng nào. |
| Cấu trúc tin nhắn | System prompts, developer messages, tool messages, nội dung đa phương thức, hoặc chỉ văn bản thuần túy. |
| Tham số | Streaming, temperature, max tokens, lời gọi tool, đầu ra JSON, response format, seed, timeout, retries. |
| Khả năng quan sát | Nơi bạn xem độ trễ, mức sử dụng token, request ID, lỗi, và chi phí hiện tại. |
| Rollback | Bạn có thể khôi phục key API/base URL/model cũ nhanh đến mức nào. |
Bản kiểm kê này giúp quá trình di chuyển diễn ra trung thực. Nếu ứng dụng của bạn chỉ gửi các tin nhắn chat đơn giản, bài kiểm tra Flatkey đầu tiên có thể giữ ở mức nhỏ. Nếu ứng dụng của bạn phụ thuộc vào streaming, lời gọi tool, chế độ JSON, images, video, hoặc Responses API, hãy coi mỗi tính năng là một bài smoke test riêng biệt.
Bước 2: Đặt Base URL Sau Một Lớp Cấu Hình Duy Nhất
Không rải base URL mới tương thích với OpenAI khắp codebase. Hãy đặt nó trong một biến môi trường hoặc một factory của SDK.
Các biến môi trường được khuyến nghị:
FLATKEY_API_KEY="sk-fk-your-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_MODEL="replace-with-publish-day-model-id"
ROLLBACK_OPENAI_BASE_URL="https://api.openai.com/v1"
ROLLBACK_MODEL="your-previous-model-id"Sử dụng OPENAI_BASE_URL thường tiện vì nhiều SDK wrapper đã hỗ trợ quy ước này. Sử dụng FLATKEY_API_KEY và FLATKEY_MODEL giúp làm rõ credential mới và lựa chọn model.
Đây là cách Flatkey phù hợp với ý định tìm kiếm openai compatible base url. Việc di chuyển nên có thể được rà soát trong một diff duy nhất: base URL, key, model và các bước xác minh.
Bước 3: Chạy kiểm tra nhanh Curl
Bắt đầu bằng một yêu cầu HTTP trực tiếp trước khi thay đổi ứng dụng của bạn. Điều này giúp cô lập các vấn đề về key, base URL, endpoint và model ID.
Chỉ là mẫu: người rà soát nên chạy với một key Flatkey hợp lệ và model ID ngày phát hành đã được xác nhận.
curl -sS "https://router.flatkey.ai/v1/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{
"role": "user",
"content": "Trả lời bằng một câu xác nhận rằng kiểm tra nhanh Flatkey này đã hoạt động."
}
]
}'Một kiểm tra nhanh hữu ích chứng minh nhiều hơn là chỉ 200 OK. Với quá trình di chuyển sang API tương thích OpenAI, hãy kiểm tra:
- Phản hồi có một thông điệp assistant có thể sử dụng.
- Tên model là model bạn định kiểm tra.
- Mức sử dụng xuất hiện trong dashboard Flatkey hoặc nhật ký sử dụng.
- Số token và chi phí hiển thị đủ rõ để xem xét thanh toán.
- Thông báo lỗi dễ hiểu nếu model ID hoặc key sai.
- Base URL và model cũ vẫn có thể được khôi phục nhanh chóng.
Bước 4: Thay đổi cấu hình Python OpenAI SDK
Nếu ứng dụng Python của bạn đã sử dụng OpenAI SDK, hãy giữ việc khởi tạo client tập trung.
Chỉ là mẫu: người duyệt nên thực thi trước khi xuất bản.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ.get("OPENAI_BASE_URL", "https://router.flatkey.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["FLATKEY_MODEL"],
messages=[
{
"role": "user",
"content": "Xác nhận yêu cầu API tương thích OpenAI này được định tuyến qua Flatkey.",
}
],
)
print(response.choices[0].message.content)
print(response.usage)Chi tiết Python quan trọng ở đây là base_url. Trong một quá trình di chuyển OpenAI compatible API gọn gàng, mã ứng dụng không nên biết liệu base URL trỏ trực tiếp đến OpenAI, một endpoint tương thích của nhà cung cấp hay Flatkey. Nó nên gọi client dùng chung và để cấu hình quyết định tuyến đường.
Bước 5: Thay đổi cấu hình OpenAI SDK cho Node
Đối với các ứng dụng Node, cấu hình tương đương sử dụng baseURL.
Chỉ là mẫu: người duyệt cần thực hiện trước khi xuất bản.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.OPENAI_BASE_URL || "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: process.env.FLATKEY_MODEL,
messages: [
{
role: "user",
content: "Xác nhận yêu cầu API tương thích OpenAI này được định tuyến qua Flatkey.",
},
],
});
console.log(response.choices[0].message.content);
console.log(response.usage);Đây là cùng một mẫu di chuyển được thấy trên các tài liệu của nhà cung cấp: giữ nguyên SDK, đặt một base URL khác, cung cấp một API key tương thích, và chọn một model ID tồn tại trên nền tảng đích.
Bước 6: Ánh xạ Model ID một cách có chủ đích
Chuỗi model là nơi nhiều lượt chuyển đổi OpenAI compatible API thất bại. Một base URL có thể tương thích trong khi model ID vẫn phụ thuộc vào từng nhà cung cấp.
Đừng giả định:
- Tên model cũ của bạn tồn tại trong Flatkey.
- Alias model của một nhà cung cấp trỏ đến cùng phiên bản phía sau một gateway.
- Mọi model tương thích đều hỗ trợ cùng một họ endpoint.
- Một model dùng được cho chat cũng dùng được cho vision, tools, images, video, hoặc Responses.
Thay vào đó, hãy dùng bảng ánh xạ này trước khi kiểm thử cấp ứng dụng đầu tiên:
| Ứng dụng hiện tại đang dùng | Kiểm tra trên Flatkey |
|---|---|
| Chat văn bản | Chọn một model Flatkey hỗ trợ OpenAI chat endpoint. |
| Chat streaming | Kiểm thử streaming riêng với cùng prompt và ngân sách timeout. |
| Gọi tool/function | Xác minh model và endpoint đã chọn hỗ trợ định dạng tool-call mà ứng dụng của bạn gửi. |
| Đầu ra JSON | Kiểm thử chính xác response_format hoặc mẫu structured-output của bạn. |
| Đầu vào vision/image | Xác nhận model đã chọn chấp nhận định dạng đầu vào hình ảnh mà SDK của bạn gửi. |
| Responses API | Xác nhận endpoint/model của Flatkey hỗ trợ /v1/responses cho trường hợp sử dụng của bạn. |
| Tạo ảnh hoặc video | Xem đây là một lượt chuyển đổi endpoint riêng biệt, không phải migration chat-completions. |
Ảnh chụp nhanh về giá của Flatkey vào ngày 11 tháng 6 năm 2026 cho thấy các họ endpoint cho OpenAI chat completions, OpenAI Responses, Anthropic messages, Gemini, tạo ảnh, và OpenAI video. Điều đó hữu ích như bằng chứng để người xem duyệt nội dung, nhưng bài viết vẫn nên thúc đẩy người đọc xác nhận chính xác model và tính năng mà họ dự định dùng vào ngày xuất bản.
Bước 7: Xác minh Nhật ký, Hạn mức và Thanh toán
Một phản hồi OpenAI compatible API thành công chỉ là điểm kiểm tra đầu tiên. Lý do để chuyển qua Flatkey không chỉ là hình dạng của request; mà còn là lớp vận hành xung quanh quyền truy cập mô hình.
Sau bài kiểm tra nhanh, hãy xác minh:
| Hạng mục | Cần kiểm tra gì |
|---|---|
| Nhật ký sử dụng | Request xuất hiện cùng dấu thời gian, mô hình, mức sử dụng token, trạng thái và chi tiết lỗi nếu có. |
| Thanh toán | Chi phí hiển thị và khớp với mô hình/đơn vị giá dự kiến. |
| Hạn mức | Có thể đặt một hạn mức nhỏ cho khóa mới hoặc tuyến kiểm thử trước khi triển khai rộng hơn. |
| Định tuyến | Request được định tuyến qua đường dẫn Flatkey dự kiến, không phải cấu hình trực tiếp nhà cung cấp đã lỗi thời. |
| Hành vi lỗi | Lỗi khóa sai, mô hình sai và tham số không được hỗ trợ phải đủ rõ để bộ phận hỗ trợ xử lý. |
| Khôi phục | Khôi phục base URL/mô hình trước đó hoạt động mà không cần thay đổi mã. |
Đây là lúc một cổng OpenAI compatible API trở nên hữu ích hơn một endpoint thô của nhà cung cấp. Việc đổi base URL nên mang lại khả năng quan sát tốt hơn, chứ không chỉ là một upstream khác.
Bước 8: Triển khai theo từng giai đoạn
Đừng chuyển tất cả quy trình cùng lúc. Hãy dùng cách triển khai theo từng giai đoạn:
- Chạy một bài kiểm tra nhanh curl trực tiếp.
- Chạy một bài kiểm tra nhanh SDK trong môi trường local hoặc staging.
- Phát lại một bộ prompt đã biết với số lượng nhỏ và so sánh cấu trúc đầu ra.
- Chỉ bật streaming hoặc các tham số nâng cao sau khi lệnh gọi cơ bản chạy thành công.
- Đặt hạn mức thấp cho khóa thử nghiệm.
- Gửi một tỷ lệ nhỏ lưu lượng không quan trọng.
- So sánh lỗi, độ trễ, mức sử dụng token và chi phí.
- Tăng lưu lượng chỉ sau khi log và thanh toán khớp với kỳ vọng.
Quy trình này giữ lời hứa về OpenAI compatible API gắn với thực tế sản xuất. Tính tương thích không phải là khẩu hiệu; đó là kết quả kiểm thử cho các lệnh gọi mà ứng dụng của bạn thực sự gửi đi.
Danh sách kiểm tra di chuyển
Dùng đây làm tài sản cho trang xuất bản.
| Bước | Xong? | Ghi chú |
|---|---|---|
| SDK và endpoint hiện tại đã được tài liệu hóa | Python, Node, HTTP, wrapper, chat, responses, image, video, v.v. | |
| Khóa Flatkey đã được tạo | Hãy dùng một khóa kiểm thử riêng nếu có thể. | |
| Base URL được tập trung hóa | https://router.flatkey.ai/v1 nên nằm trong cấu hình, không phải rải rác trong mã. |
|
| Model ID được chọn từ Flatkey | Xác nhận model ID cho ngày xuất bản từ bảng giá hoặc dashboard. | |
| Kiểm thử nhanh Curl đạt | Template phải được reviewer kiểm thử trước khi xuất bản. | |
| Kiểm thử nhanh SDK Python hoặc Node đạt | Hãy dùng SDK mà ứng dụng của bạn thực sự chạy. | |
| Các tính năng streaming/tool/JSON/vision đã được kiểm thử | Chỉ kiểm thử những tính năng bạn dùng. | |
| Nhật ký sử dụng hiển thị được | Xác nhận model, trạng thái, token và lỗi trong dashboard. | |
| Đơn vị thanh toán và giá được xem xét | Đừng cho rằng đơn vị giá của nhà cung cấp là giống hệt nhau. | |
| Giới hạn quota đã được thiết lập | Giữ lưu lượng di chuyển ở mức giới hạn. | |
| Các biến môi trường để rollback đã sẵn sàng | Base URL cũ và model có thể được khôi phục mà không cần thay đổi mã. |
Các lỗi thường gặp
Lỗi di chuyển API tương thích OpenAI phổ biến nhất là thay đổi base URL và cho rằng mọi chi tiết khác đều giống hệt. Hãy tránh những bẫy sau:
- Hardcode base URL của Flatkey trong nhiều tệp.
- Giữ lại ID model cũ của nhà cung cấp mà Flatkey không định tuyến.
- Chỉ kiểm thử non-streaming trong khi production dùng streaming.
- Bỏ qua các bài kiểm thử tool-call hoặc đầu ra JSON.
- Di chuyển các endpoint hình ảnh/video như thể chúng là endpoint chat-completions.
- Quên cập nhật retries, timeout budgets và phân tích lỗi.
- Tuyên bố việc di chuyển đã xong trước khi usage và billing hiển thị được.
Flatkey giúp giảm tình trạng phân tán account của nhà cung cấp và routing, nhưng không loại bỏ nhu cầu phải kiểm thử di chuyển cẩn thận.
Khi Flatkey Phù Hợp
Flatkey là lựa chọn phù hợp khi đội ngũ của bạn muốn một OpenAI compatible API base URL cho truy cập đa mô hình thay vì các tài khoản nhà cung cấp riêng biệt, khóa, thanh toán và kiểm tra định tuyến.
Sử dụng Flatkey khi:
- Ứng dụng của bạn đã sử dụng SDK tương thích với OpenAI.
- Bạn muốn một khóa cho các mô hình từ nhiều nhà cung cấp như GPT, Claude, Gemini, DeepSeek, Qwen, Seedance 2.0 và GPT Image.
- Bạn muốn usage, billing, keys và routing hiển thị trong một dashboard duy nhất.
- Bạn muốn giới hạn quota trước khi lưu lượng tăng lên.
- Bạn muốn việc chuyển đổi mô hình và hành vi cân bằng tải được xử lý bởi lớp gateway.
- Bạn muốn lộ trình chuyển đổi là "đổi base URL, xác minh mô hình, theo dõi usage" thay vì "viết lại phần tích hợp mô hình."
Sử dụng tài khoản nhà cung cấp trực tiếp hoặc proxy tự triển khai khi bạn cần các hợp đồng đặc thù của nhà cung cấp, logic định tuyến hoàn toàn tùy chỉnh, hoặc kiểm soát gateway cục bộ trong hạ tầng.
Câu hỏi thường gặp
API tương thích với OpenAI có giống OpenAI không?
Không. Một API tương thích với OpenAI tuân theo mẫu yêu cầu và phản hồi kiểu OpenAI cho các endpoint được hỗ trợ, nhưng nhà cung cấp, ID model, xác thực, hỗ trợ tính năng, giá cả và hành vi lỗi có thể khác nhau.
Tôi có cần thay SDK của mình để dùng Flatkey không?
Thường là không đối với các lần chuyển đổi chat-completions phổ biến. Nếu SDK của bạn hỗ trợ base URL tùy chỉnh, bạn thường có thể giữ nguyên SDK và thay đổi cấu hình. Đó là điểm hấp dẫn cốt lõi của việc chuyển sang API tương thích với OpenAI.
Base URL tương thích OpenAI của Flatkey là gì?
Sử dụng https://router.flatkey.ai/v1 làm base URL tương thích với OpenAI. Với chat completions, endpoint đầy đủ là https://router.flatkey.ai/v1/chat/completions.
Tôi có thể giữ nguyên tên model hiện có của mình không?
Chỉ khi ID model đó có sẵn và được hỗ trợ thông qua Flatkey. Hãy kiểm tra bảng giá hoặc dashboard, sau đó thử chính xác ID model trước khi triển khai.
Tôi nên chuyển Chat Completions hay Responses trước?
Hãy chuyển endpoint mà ứng dụng hiện tại của bạn đang dùng. Các ứng dụng Chat Completions hiện có có thể bắt đầu với /v1/chat/completions. Nếu ứng dụng của bạn dùng Responses API, hãy kiểm thử riêng /v1/responses và xác nhận model đã chọn hỗ trợ các tính năng bạn cần.
Tôi hoàn nguyên như thế nào?
Giữ nguyên base URL cũ, API key và model trong cấu hình cho đến khi log, chi phí, hạn mức và hành vi ứng dụng của Flatkey được xác minh. Hoàn nguyên nên chỉ là thay đổi biến môi trường, không phải viết lại code.
Lấy một khóa
Nếu bạn đã có một ứng dụng được xây dựng xung quanh một API tương thích OpenAI, Flatkey giúp việc chuyển đổi trở nên nhỏ gọn: lấy một khóa, thay đổi base URL, chọn một mô hình, chạy kiểm tra nhanh, và theo dõi mức sử dụng trong một bảng điều khiển duy nhất.
Lấy một khóa, rồi dùng https://router.flatkey.ai/v1 làm base URL cho bài kiểm tra chuyển đổi Flatkey đầu tiên của bạn.
