API tương thích OpenAI: Danh sách kiểm tra khi chuyển đổi cho lập trình viên

API tương thích OpenAI cho phép bạn giữ nguyên client library hiện có trong khi đổi dịch vụ phía sau. Điều này hữu ích khi bạn muốn đánh giá mô hình, kiểm soát chi phí hoặc gom nhiều nhà cung cấp về một chỗ. Nhưng không vì thế mà mọi endpoint, tham số hay tính năng của ứng dụng đều hoạt động giống hệt nhau.

Một cuộc chuyển đổi an toàn bắt đầu từ chính những yêu cầu mà ứng dụng của bạn thực sự gửi đi. Hãy coi khả năng tương thích như một danh sách kiểm tra cho một mô hình và một route cụ thể, chứ không phải nhãn dán cho cả một nền tảng.

Hướng dẫn này dùng cấu hình của cheapaimodel làm ví dụ cụ thể. Các ví dụ dựa trên tài liệu công khai đã xem ngày 26 tháng 10 năm 2026; đây không phải kết quả kiểm thử API có xác thực.

1. Tách bốn kiểu tương thích

Lớp	Câu hỏi cần trả lời	Bằng chứng cần thu thập
Client	SDK có gửi được yêu cầu đến dịch vụ này không?	Base URL tùy chỉnh và phương thức xác thực đã được ghi trong tài liệu
Giao thức	Máy chủ có hiểu đúng dạng yêu cầu không?	Tài liệu về endpoint và tham số
Mô hình	Mô hình bạn chọn có hỗ trợ tính năng đó không?	Danh sách khả năng riêng của mô hình và một bài kiểm thử có mục tiêu
Ứng dụng	Kết quả trả về có đáp ứng quy trình của bạn không?	Các ca kiểm thử hồi quy, kết quả đã kiểm chứng và chỉ số vận hành

Một yêu cầu hoàn thành văn bản thành công chỉ trả lời được một phần nhỏ trong danh sách này. Nó không chứng minh rằng đầu vào hình ảnh, tool call, structured output hay trạng thái hội thoại sẽ hoạt động.

Hãy ghi rõ những khả năng mà ứng dụng của bạn bắt buộc phải có trước khi chọn dịch vụ thay thế. Tách tính năng bắt buộc khỏi tính năng cho tiện. Nếu không, một bài smoke test chỉ chạy văn bản với chi phí thấp có thể che mất một khoảng trống tích hợp tốn kém.

2. Cấu hình key, Base URL và mô hình cùng nhau

cheapaimodel ghi https://api.cheapaimodel.ai/v1 là Base URL cho SDK OpenAI. Hãy dùng API key của gateway, không dùng key của nhà cung cấp khác. Tránh đưa /chat/completions vào Base URL vì SDK tự thêm đường dẫn tài nguyên. Tên miền của website không phải là host API. Xem hướng dẫn Base URL.

Một cấu hình tối giản trông như sau:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CHEAPAIMODEL_API_KEY"],
    base_url="https://api.cheapaimodel.ai/v1",
)

result = client.chat.completions.create(
    model="deepseek-v4-1-flash",
    messages=[{"role": "user", "content": "Reply with one short greeting."}],
)
print(result.choices[0].message.content)

Mã định danh mô hình theo hướng dẫn SDK của gateway; mỗi trang mô hình liệt kê mã định danh và giá, ví dụ DeepSeek V4.1 Flash. Đừng cho rằng nhà cung cấp khác dùng cùng mã định danh cho cùng một dòng mô hình. Hãy giữ ba giá trị cấu hình này cạnh nhau trong phần cài đặt triển khai để một thay đổi thiếu sót không vô tình gửi key mới đến endpoint cũ.

Đừng để key trong bundle frontend, tệp đã commit hay nhật ký gỡ lỗi. Dùng một key riêng cho môi trường chuyển đổi để bạn có thể thu hồi độc lập.

3. Phân biệt Chat Completions và Responses

Hãy xem phương thức SDK mà ứng dụng của bạn gọi. client.chat.completions.create(...) và client.responses.create(...) là hai giao diện khác nhau. Một cài đặt được mô tả là “tương thích OpenAI” trong ứng dụng có thể dùng một trong hai.

cheapaimodel liệt kê cả hai route, nhưng tài liệu nói rằng endpoint được hỗ trợ phụ thuộc vào mô hình. Hãy kiểm tra tổ hợp route/mô hình thay vì cho rằng có cái này thì chắc chắn có cái kia. Xem tài liệu API và FAQ.

Với mỗi route, hãy ghi lại:

• Các trường trong yêu cầu mà ứng dụng của bạn gửi đi.
• Các trường trong phản hồi mà ứng dụng đọc.
• Cách ứng dụng truyền lịch sử hội thoại hoặc trạng thái.
• Những công cụ hoặc tùy chọn định dạng mà ứng dụng yêu cầu.
• Cách trình phân tích streaming nhận biết khi nào hoàn tất.

Đừng thay đổi endpoint và trình phân tích phản hồi một cách độc lập. Một cuộc migration là chưa hoàn tất nếu việc tạo nội dung thành công nhưng ứng dụng lại đọc sai trường và hiển thị câu trả lời trống.

4. Kiểm tra tham số thay vì chuyển tiếp mọi thứ

Hãy tạo một bản kiểm kê nhỏ từ các yêu cầu đại diện, đã xóa thông tin xác thực và nội dung cá nhân. Bao gồm cả những trường tùy chọn do framework thêm vào, không chỉ những trường hiển thị trong mã của bạn.

Kiểm tra riêng giới hạn token, các tùy chọn điều khiển suy luận, tùy chọn lấy mẫu, công cụ và định dạng đầu ra. Một tham số được chấp nhận chưa chắc đã là tham số có tác dụng. Tài liệu tham chiếu Chat Completions hiện tại của DeepSeek có ghi những cài đặt mà hành vi phụ thuộc vào chế độ tư duy, cùng với các trường đã bị bỏ và không còn tác dụng.

Đầu ra có cấu trúc cần được kiểm tra riêng. OpenAI phân biệt chế độ JSON với Structured Outputs ràng buộc theo schema. Một yêu cầu theo dạng OpenAI không truyền được những đảm bảo đó sang mọi máy chủ tương thích. Hãy kiểm tra nhà cung cấp bạn chọn có hỗ trợ định dạng đã ghi trong tài liệu hay không, rồi xác thực kết quả trong ứng dụng của bạn. Xem hướng dẫn về đầu ra có cấu trúc của OpenAI.

5. Kiểm tra các đường dẫn lỗi và hành vi streaming

Hãy dùng một bộ kiểm thử hồi quy gọn nhẹ thay vì một prompt hoành tráng duy nhất:

Trường hợp	Điều cần quan sát
Yêu cầu văn bản ngắn	Nội dung dùng được đến được ứng dụng
Hội thoại nhiều lượt	Ngữ cảnh trước đó liên quan được giữ lại
Phản hồi streaming	Các delta ghép lại đúng và thấy rõ khi bị ngắt
Quy trình dùng công cụ, nếu cần	Tham số được xác thực trước khi thực thi
Phản hồi có cấu trúc, nếu cần	Đầu ra sai hoặc thiếu bị từ chối
Model hoặc key không hợp lệ	Người vận hành nhận được thông báo lỗi dễ đọc
Yêu cầu chậm hoặc bị ngắt	Hành vi hết thời gian chờ và thử lại có giới hạn

Hãy chạy những kiểm thử này trong môi trường không phải production và có hạn mức chi tiêu rõ ràng. Ghi lại request ID khi có, mã trạng thái HTTP, độ trễ, trạng thái kết thúc và kết quả xác thực. Tuyệt đối không ghi log thông tin xác thực. Hãy che nội dung của khách hàng trừ khi chính sách ghi log của bạn cho phép rõ ràng.

6. Giữ các giao thức và dịch vụ khác tách riêng

Khả năng tương thích với Anthropic Messages là một hợp đồng tích hợp riêng. Không thể suy ra từ khả năng tương thích với OpenAI. cheapaimodel ghi một quy ước Base URL khác cho SDK của Anthropic, vì các SDK này tự thêm đường dẫn /v1/messages của riêng chúng. Hãy làm theo cấu hình đã ghi trong tài liệu thay vì dùng lại một URL một cách máy móc.

Cũng hãy kiểm tra riêng embeddings, storage, xử lý theo lô và mọi công cụ được host. Việc ghi đè Base URL toàn cục có thể chuyển hướng nhiều client hơn mức bạn muốn. Hãy ưu tiên cấu hình riêng cho từng client khi ứng dụng của bạn dùng nhiều dịch vụ.

7. Triển khai với một quyết định có thể đảo ngược

Bắt đầu với lưu lượng nội bộ hoặc một khối lượng công việc hẹp. So sánh tỷ lệ hoàn thành tác vụ và chi phí cho mỗi kết quả được chấp nhận, không chỉ giá token. So sánh bảng giá LLM API của chúng tôi là điểm khởi đầu cho phần bảng giá; bộ kiểm thử hồi quy của bạn cung cấp bằng chứng về chất lượng.

Giữ nguyên cấu hình trước đó, đặt ngưỡng rollback và tránh tự động chuyển nhà cung cấp cho các quy trình có tác dụng phụ cho đến khi kiểm soát được việc thực thi trùng lặp.

Quá trình chuyển đổi sẵn sàng khi các tính năng bắt buộc đều đạt, lỗi vẫn dễ hiểu và ứng dụng có thể quay lại cấu hình trước đó một cách an toàn. Tái sử dụng SDK chỉ là khởi đầu của quá trình đó, không phải tiêu chí nghiệm thu.