Việc di chuyển SDK đa mô hình không nên bắt đầu bằng việc thay thế mọi thư viện client trong ứng dụng của bạn. Nếu mã nguồn sản phẩm của bạn đã sử dụng SDK OpenAI Python hoặc Node cho các hoàn thành trò chuyện (chat completions), bước đi đầu tiên an toàn hơn là giữ ổn định bề mặt client đó, chuyển lựa chọn nhà cung cấp vào cấu hình, và chứng minh hành vi của Claude, Gemini và DeepSeek đằng sau một tuyến đường tương thích trước khi bạn mở rộng lưu lượng truy cập.
Flatkey được xây dựng cho các đội ngũ muốn có một khóa duy nhất, một lớp định tuyến tương thích với OpenAI, quyền truy cập mô hình qua nhiều nhà cung cấp, và xem xét việc sử dụng và thanh toán ở một nơi. Điều đó làm cho nó hữu ích cho việc di chuyển SDK đa mô hình, nhưng nó không loại bỏ nhu cầu kiểm tra các họ điểm cuối (endpoint families), bí danh mô hình (model aliases), streaming, gọi công cụ (tool calls), và hồ sơ sử dụng. Hãy coi mọi mẫu mã ở đây như một khuôn mẫu cho đến khi bạn xác thực nó bằng khóa Flatkey của riêng mình và danh mục mô hình hiện tại.
Mục tiêu thực tế rất đơn giản: giữ lại đối tượng yêu cầu mà ứng dụng của bạn đã biết, cô lập một vài giá trị phải thay đổi, và xây dựng một gói bằng chứng (proof packet) trước khi chuyển đổi.
Ma trận Quyết định Di chuyển SDK Đa mô hình
Sử dụng ma trận này trước khi bạn thay đổi mã nguồn. Nó tách biệt những gì có thể giữ ổn định khỏi những gì phải trở thành có thể cấu hình.
| Lớp | Giữ ổn định | Làm cho có thể cấu hình | Bằng chứng cần lưu |
|---|---|---|---|
| Client SDK | Đường dẫn import SDK OpenAI và gọi hoàn thành trò chuyện hiện có | Khóa API, URL cơ sở, thời gian chờ, chính sách thử lại | Phiên bản SDK và cấu hình khởi động đã được biên tập |
| Hình dạng yêu cầu | messages, model, stream, các tools cơ bản nơi được hỗ trợ | Các phần bổ sung dành riêng cho nhà cung cấp và các tham số không được hỗ trợ | Yêu cầu tối thiểu và phản hồi thô |
| Lựa chọn mô hình | Các bí danh cấp ứng dụng như support_chat hoặc analysis_fast | Bí danh mô hình cổng và họ điểm cuối | Ảnh chụp màn hình hoặc xuất danh mục mô hình |
| Vận hành | Nhật ký, ID yêu cầu và xử lý lỗi hiện có | Siêu dữ liệu về nhà cung cấp, tuyến đường, sử dụng, hạn ngạch và khôi phục | Bằng chứng từ bảng điều khiển/đọc lại |
| Phát hành | Đường dẫn triển khai ứng dụng hiện tại | Các biến môi trường cho việc triển khai theo tỷ lệ phần trăm và khôi phục | Người chịu trách nhiệm khôi phục và cấu hình trước đó |
Đây là nguyên tắc cốt lõi của việc di chuyển SDK đa mô hình: không trộn lẫn việc thay thế thư viện, di chuyển prompt, đánh giá nhà cung cấp, xác thực thanh toán và triển khai sản phẩm vào cùng một lần triển khai.
Tài liệu chính thức nói gì về tính tương thích
Các SDK của OpenAI đã hỗ trợ mẫu bạn cần. Tệp README của OpenAI Python hiện tại ghi lại client OpenAI và tùy chọn base_url, và tệp README của Node ghi lại client OpenAI tiêu chuẩn và các hoàn thành trò chuyện. Tài liệu tham khảo API của OpenAI nói rằng Chat Completions tạo ra một phản hồi mô hình cho một cuộc trò chuyện, hỗ trợ streaming, và trả về một đối tượng hoàn thành trò chuyện hoặc các đoạn stream.
Nếu bạn đang chia nhỏ việc triển khai theo môi trường chạy (runtime), hãy kết hợp danh sách kiểm tra này với hướng dẫn URL cơ sở tùy chỉnh của SDK OpenAI Python và hướng dẫn URL cơ sở của SDK OpenAI Node. Nếu quyết định đầu tiên là định tuyến nhà cung cấp thay vì thiết lập client, hãy sử dụng hướng dẫn định tuyến API Claude và GPT trước khi bạn chọn khối lượng công việc thử nghiệm.
Tính tương thích của nhà cung cấp khác nhau:
| Nhà cung cấp | Tín hiệu tương thích chính thức | Hàm ý di chuyển |
|---|---|---|
| OpenAI SDK | Python hỗ trợ base_url; Node sử dụng baseURL; Chat Completions có các trường messages, model, stream, tools, và usage. | Giữ lại trình bao bọc client OpenAI cho lát di chuyển đầu tiên. |
| Anthropic / Claude | Anthropic công bố một lớp tương thích SDK OpenAI, nhưng nói rằng nó chủ yếu dành cho việc kiểm thử và so sánh, không phải là con đường sản xuất lâu dài cho hầu hết các trường hợp sử dụng. API Messages gốc sử dụng /v1/messages, max_tokens, messages, và một tham số system ở cấp cao nhất. | Sử dụng tính tương thích để đánh giá nhanh, nhưng hãy kiểm tra các yêu cầu gốc của Claude trước khi dựa vào các tính năng dành riêng cho nhà cung cấp. |
| Google Gemini | Google cho biết các mô hình Gemini có thể truy cập được thông qua các thư viện OpenAI Python, TypeScript/JavaScript và REST bằng cách thay đổi khóa API, URL cơ sở và mô hình. | Gemini là một ứng cử viên tốt cho một bài kiểm tra sơ bộ (smoke test) theo dạng OpenAI, với việc lý luận và hành vi cụ thể của mô hình được xác minh riêng. |
| DeepSeek | DeepSeek cho biết định dạng API của họ tương thích với OpenAI và Anthropic; tài liệu gọi lần đầu của họ liệt kê các URL cơ sở của OpenAI và Anthropic cùng các ví dụ định dạng OpenAI. | DeepSeek có thể phù hợp với đường dẫn client OpenAI, nhưng việc ngừng sử dụng tên mô hình và các cài đặt tư duy cần được kiểm tra rõ ràng. |
| Flatkey | Trang mô hình công khai của Flatkey hiển thị các loại điểm cuối như openai, anthropic, và gemini; trang chủ hiển thị một tuyến đường hoàn thành trò chuyện tương thích với OpenAI. | Chọn các mô hình theo họ điểm cuối, không chỉ dựa vào tên nhà cung cấp. |
Bài học quan trọng là "tương thích với OpenAI" thường có nghĩa là client có thể gửi một yêu cầu có định dạng của OpenAI. Điều đó không có nghĩa là mọi tham số, lược đồ công cụ, kiểm soát suy luận, đầu vào đa phương tiện, hoặc trường sử dụng đều hoạt động giống hệt nhau giữa các nhà cung cấp.
Bước 1: Cố định Ranh giới Client
Bắt đầu quá trình di chuyển SDK đa mô hình bằng cách đặt client OpenAI đằng sau một factory cục bộ duy nhất. Factory này nên là nơi duy nhất biết về key, URL cơ sở, thời gian chờ, và bí danh mô hình.
import os
from openai import OpenAI
def make_llm_client() -> OpenAI:
return OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.getenv("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
timeout=float(os.getenv("LLM_TIMEOUT_SECONDS", "60")),
max_retries=int(os.getenv("LLM_MAX_RETRIES", "2")),
)
client = make_llm_client()
completion = client.chat.completions.create(
model=os.environ["FLATKEY_MODEL"],
messages=[
{"role": "system", "content": "Bạn trả lời bằng các ghi chú triển khai ngắn gọn."},
{"role": "user", "content": "Trả lời chính xác: migration probe ok"},
],
)
print(completion.choices[0].message.content)
Đối với Node:
import OpenAI from "openai";
export function makeLlmClient() {
return new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
timeout: Number(process.env.LLM_TIMEOUT_MS ?? 60000),
maxRetries: Number(process.env.LLM_MAX_RETRIES ?? 2),
});
}
const client = makeLlmClient();
const completion = await client.chat.completions.create({
model: process.env.FLATKEY_MODEL,
messages: [
{ role: "system", content: "Bạn trả lời bằng các ghi chú triển khai ngắn gọn." },
{ role: "user", content: "Trả lời chính xác: migration probe ok" },
],
});
console.log(completion.choices[0].message.content);
Ứng dụng nên gọi make_llm_client() hoặc makeLlmClient(), chứ không nên khởi tạo client ở nhiều nơi như controller, worker, và script. Ranh giới duy nhất đó là yếu tố cho phép quá trình di chuyển SDK đa mô hình có thể được hoàn tác.
Bước 2: Xây dựng Bản đồ Mô hình và Endpoint
Đừng trỏ mọi workload vào một tên mô hình mới duy nhất. Hãy bắt đầu với một bản đồ đặt tên cho workload, họ endpoint, nhà cung cấp hiện tại, nhà cung cấp mục tiêu, và giá trị để quay lui.
| Tải công việc | Họ Endpoint | Đường dẫn Hiện tại | Đường dẫn Mục tiêu | Phương án Quay lui |
|---|---|---|---|---|
| Chat hỗ trợ | Hoàn thành chat kiểu OpenAI | Mô hình OpenAI hiện tại | Bí danh chat Flatkey cho GPT, Claude, Gemini, hoặc DeepSeek | Key, URL cơ sở, và mô hình trước đó |
| Phân tích nội bộ | Hoàn thành chat kiểu OpenAI | Mô hình OpenAI hiện tại | Bí danh mô hình Flatkey được chọn cho suy luận và chi phí | Bí danh mô hình trước đó |
| Luồng công việc công cụ | Hoàn thành chat với công cụ | Mô hình tương thích công cụ hiện tại | Mô hình ứng viên với hành vi công cụ đã được xác minh | Vô hiệu hóa tuyến nhà cung cấp |
| Giao diện người dùng streaming | Luồng hoàn thành chat | Bộ phân tích luồng hiện tại | Nhà cung cấp ứng viên với bằng chứng luồng thô | Chuyển lưu lượng luồng trở lại |
| Tính năng Claude gốc | API Tin nhắn Anthropic | Client Claude gốc | Giữ lại client gốc nếu khả năng tương thích làm mất tính năng bắt buộc | Không di chuyển đường dẫn này |
Trang mô hình của Flatkey rất hữu ích ở đây vì nó hiển thị các loại endpoint. Nếu một mô hình được liệt kê dưới một họ endpoint gốc, đừng cho rằng nó có sẵn thông qua đường dẫn chat của OpenAI cho đến khi danh mục tài khoản và các bài kiểm tra sơ bộ (smoke test) của bạn chứng minh điều đó.
Bước 3: Chạy Kiểm tra Sơ bộ (Smoke Test) với Bốn Nhà cung cấp
Bài kiểm tra sơ bộ (smoke test) tối thiểu hữu ích cho việc di chuyển SDK đa mô hình có bốn hàng nhà cung cấp và cùng một prompt. Hãy giữ cho prompt đơn giản để phong cách phản hồi không che giấu các lỗi truyền tải.
| Kiểm tra | Yêu cầu | Điều kiện Đạt | Lỗi cần Phân loại |
|---|---|---|---|
| GPT hoặc mô hình OpenAI hiện tại | Yêu cầu có định dạng OpenAI hiện có thông qua Flatkey | Nhận được phản hồi, thấy được mức sử dụng, log liên kết đến bí danh mong đợi | Sai key, sai URL cơ sở, trùng lặp /v1, thiếu mô hình |
| Claude | Cùng yêu cầu có định dạng OpenAI thông qua bí danh Flatkey đã chọn | Nhận được phản hồi đơn giản; không có tính năng không được hỗ trợ trong yêu cầu | Ánh xạ tin nhắn hệ thống, lược đồ công cụ, các tính năng chỉ có trên Claude gốc |
| Gemini | Cùng yêu cầu có định dạng OpenAI thông qua bí danh Flatkey đã chọn | Nhận được phản hồi đơn giản; các mặc định suy luận có thể chấp nhận được | Bí danh mô hình, cài đặt suy luận, các giả định đa phương thức |
| DeepSeek | Cùng yêu cầu có định dạng OpenAI thông qua bí danh Flatkey đã chọn | Nhận được phản hồi đơn giản; bí danh nhạy cảm với việc ngừng hỗ trợ là phiên bản hiện tại | Đổi tên mô hình, cài đặt tư duy, bộ phân tích luồng |
Lưu lại phần thân yêu cầu thô, các header đã được biên tập, phần thân phản hồi, trạng thái HTTP, bí danh mô hình, ID yêu cầu nếu có, và mục sử dụng trên dashboard. Nếu bất kỳ nhà cung cấp nào cần một tham số khác, hãy chuyển tham số đó vào một hồ sơ nhà cung cấp thay vì rải các nhánh if provider == khắp ứng dụng của bạn.
Bước 4: Kiểm tra Streaming và Lệnh gọi Công cụ một cách Riêng biệt
Một yêu cầu hoàn thành đơn giản chỉ chứng minh được đường dẫn ít rủi ro nhất. Streaming và lệnh gọi công cụ là những hợp đồng riêng biệt.
Đối với streaming, hãy lưu:
| Bằng chứng | Tại sao nó quan trọng |
|---|---|
| Header phản hồi | Xác nhận liệu tuyến đường có trả về dữ liệu luồng sự kiện (event-stream) hay không. |
| Sự kiện đầu tiên | Phát hiện các vấn đề về bộ đệm hoặc trình phân tích cú pháp proxy. |
| Sự kiện cuối cùng | Xác nhận việc xử lý cuối luồng và hành vi sử dụng. |
| Đầu ra của trình phân tích cú pháp UI | Chứng minh rằng frontend của bạn không giả định hình dạng chunk của một nhà cung cấp cụ thể. |
Đối với các công cụ, hãy kiểm tra một schema nhỏ trước:
{
"type": "function",
"function": {
"name": "lookup_order_status",
"description": "Trả về trạng thái đơn hàng thử nghiệm.",
"parameters": {
"type": "object",
"properties": {
"order_id": { "type": "string" }
},
"required": ["order_id"]
}
}
}
Đừng sử dụng schema công cụ sản xuất lớn nhất của bạn làm bằng chứng đầu tiên. Ví dụ, tài liệu tương thích của Anthropic chỉ ra những hạn chế về khả năng tương thích với OpenAI và khuyến nghị sử dụng API Claude gốc để có bộ tính năng đầy đủ của Claude. Đó chính xác là loại chi tiết mà một danh sách kiểm tra di chuyển SDK đa mô hình nên nắm bắt trước khi triển khai.
Bước 5: Giữ hồ sơ nhà cung cấp nhỏ gọn
Hồ sơ nhà cung cấp nên mô tả sự khác biệt, không nên chứa logic nghiệp vụ.
{
"support_chat": {
"base_url_env": "FLATKEY_BASE_URL",
"model_env": "FLATKEY_SUPPORT_CHAT_MODEL",
"endpoint_family": "openai_chat_completions",
"stream": true,
"tools": "basic",
"fallback_alias": "support_chat_previous"
},
"analysis_fast": {
"base_url_env": "FLATKEY_BASE_URL",
"model_env": "FLATKEY_ANALYSIS_FAST_MODEL",
"endpoint_family": "openai_chat_completions",
"stream": false,
"tools": "none",
"fallback_alias": "analysis_fast_previous"
}
}
Giữ các tính năng gốc của nhà cung cấp ra khỏi đường dẫn client OpenAI được chia sẻ trừ khi bạn có các bài kiểm tra cho mọi nhà cung cấp mục tiêu. Nếu cần các trích dẫn của Claude, hành vi phương tiện truyền thông cụ thể của Gemini, các điều khiển suy nghĩ của DeepSeek, hoặc một điểm cuối hàng loạt gốc của nhà cung cấp, hãy tạo một adapter gốc có tên và giữ đường dẫn tương thích với OpenAI cho các khối lượng công việc thực sự phù hợp.
Bước 6: Chứng minh thanh toán và khôi phục
Một quá trình di chuyển trả về văn bản nhưng làm mất bằng chứng thanh toán là chưa hoàn thành. Trước khi tăng lưu lượng truy cập, hãy lưu:
| Kiểm tra hoạt động | Điều kiện đạt |
|---|---|
| Khả năng hiển thị việc sử dụng | Yêu cầu xuất hiện trong nhật ký hoặc phần sử dụng của Flatkey với ngữ cảnh tuyến đường/mô hình dự kiến. |
| Xem xét chi phí | Hồ sơ giá cả hoặc sử dụng đủ rõ ràng để bộ phận tài chính hoặc vận hành đối chiếu. |
| Hành vi hạn ngạch | Một hạn ngạch thử nghiệm thấp hoặc ngưỡng ngân sách hoạt động như mong đợi trong một khóa không phải sản xuất. |
| Phân loại lỗi | Các lỗi 401, 403, 404, 429, 5xx, và lỗi của nhà cung cấp được ánh xạ tới các hành động rõ ràng của người sở hữu. |
| Khôi phục | Một thay đổi môi trường sẽ trả lưu lượng truy cập về khóa/URL cơ sở/mô hình trước đó. |
Đây là lúc việc xem xét thanh toán và sử dụng thống nhất của Flatkey trở nên quan trọng. Mục tiêu không chỉ là truy cập vào nhiều mô hình hơn. Mục tiêu của việc di chuyển SDK đa mô hình là quyền truy cập mà bộ phận sản phẩm, vận hành và tài chính có thể kiểm tra sau khi lưu lượng truy cập được chuyển đổi.
Quy trình chuyển đổi để di chuyển SDK đa mô hình
Sử dụng thứ tự này cho lát cắt sản xuất đầu tiên:
- Chọn một khối lượng công việc có rủi ro thấp với một client OpenAI SDK hiện có.
- Thêm factory client và các biến môi trường mà không thay đổi nhà cung cấp hiện tại.
- Chứng minh mô hình hiện tại thông qua factory mới.
- Chứng minh một mục tiêu Claude, Gemini hoặc DeepSeek với một yêu cầu hoàn thành đơn giản.
- Chỉ chứng minh streaming và các công cụ nếu khối lượng công việc đó sử dụng chúng.
- Xác minh việc sử dụng, thanh toán, xử lý lỗi và khôi phục.
- Định tuyến một tỷ lệ nhỏ lưu lượng truy cập đến bí danh mô hình mới.
- Xem xét các lỗi theo nhà cung cấp và họ điểm cuối trước khi thêm khối lượng công việc tiếp theo.
Nếu khối lượng công việc đầu tiên cần các tính năng gốc của nhà cung cấp, hãy chọn một khối lượng công việc khác cho lần di chuyển SDK đa mô hình đầu tiên. Lát cắt đầu tiên nên chứng minh mô hình di chuyển, chứ không phải mọi khả năng của mô hình.
Câu hỏi thường gặp
Tôi có thể sử dụng một client OpenAI SDK cho Claude, Gemini và DeepSeek không?
Bạn thường có thể giữ một client OpenAI SDK cho các tuyến đường tương thích với OpenAI, nhưng bạn vẫn cần các bài kiểm tra cụ thể cho từng nhà cung cấp. Google và DeepSeek có tài liệu về quyền truy cập tương thích với OpenAI. Anthropic có tài liệu về một lớp tương thích OpenAI SDK, nhưng nói rằng nó chủ yếu dành cho việc kiểm tra và so sánh hơn là lựa chọn sản xuất lâu dài cho hầu hết các trường hợp sử dụng.
Tôi có nên di chuyển lưu lượng truy cập Responses API theo cách tương tự không?
Chỉ khi cổng đích và mô hình đích hỗ trợ rõ ràng họ điểm cuối mà bạn đang sử dụng. Chat Completions và Responses không phải là cùng một hợp đồng. Bắt đầu với họ điểm cuối mà ứng dụng của bạn đã sử dụng, sau đó tạo một kế hoạch kiểm tra riêng cho Responses.
Sai lầm phổ biến nhất khi di chuyển SDK đa mô hình là gì?
Sai lầm phổ biến nhất là coi việc thay đổi URL cơ sở là toàn bộ quá trình di chuyển. Một quá trình di chuyển SDK đa mô hình thực sự cũng xác minh tên mô hình, họ điểm cuối, streaming, công cụ, việc sử dụng, hạn ngạch, xử lý lỗi và khôi phục.
Khi nào tôi nên giữ lại một SDK gốc của nhà cung cấp?
Giữ lại một SDK gốc của nhà cung cấp khi khối lượng công việc của bạn phụ thuộc vào các tính năng cụ thể của nhà cung cấp mà lớp tương thích không hỗ trợ. Các tính năng gốc của Claude, đường dẫn phương tiện truyền thông cụ thể của Gemini, hoặc các điều khiển suy luận cụ thể của DeepSeek có thể là lý do để tạo một adapter riêng.
Danh sách kiểm tra cuối cùng
Trước khi bạn gọi quá trình di chuyển là hoàn tất, hãy xác nhận rằng bạn đã:
| Mục | Hoàn thành khi |
|---|---|
| Client factory | Tất cả các đường dẫn ứng dụng đều sử dụng một trình bao bọc SDK OpenAI hoặc một bộ điều hợp gốc được đặt tên. |
| Tách cấu hình | Khóa API, URL cơ sở, bí danh mô hình, thời gian chờ, số lần thử lại và chủ sở hữu tuyến đường được điều khiển bởi môi trường. |
| Bằng chứng nhà cung cấp | Các ứng viên GPT, Claude, Gemini và DeepSeek đã được kiểm tra với bằng chứng thô đã lưu. |
| Bằng chứng tính năng | Streaming và các công cụ đã được kiểm tra riêng biệt với trò chuyện thông thường. |
| Bằng chứng hoạt động | Việc sử dụng, thanh toán, hạn ngạch, nhật ký và lỗi đều hiển thị cho đúng chủ sở hữu. |
| Bằng chứng khôi phục | Một thay đổi được ghi lại sẽ trả lại khối lượng công việc về tuyến đường trước đó. |
Việc di chuyển SDK đa mô hình hoạt động tốt nhất khi nó diễn ra một cách đơn giản: một khối lượng công việc nhỏ, một ranh giới client, một bản đồ mô hình và bằng chứng cho mỗi nhà cung cấp bạn thêm vào. Khi bạn đã sẵn sàng chạy các thử nghiệm đó thông qua một tuyến đường thống nhất, hãy lấy khóa Flatkey và bắt đầu với một đường dẫn trò chuyện tương thích với OpenAI có rủi ro thấp.
