Chuyển một ứng dụng từ OpenAI sang nhà cung cấp tương thích OpenAI là một thay đổi code nhỏ nếu bạn dùng Chat Completions, và là một lần viết lại nếu bạn dùng Responses API. Bài viết này đưa ra chính xác các thay đổi bằng Python, Node và cURL, cách xử lý Responses, công cụ, đầu ra có cấu trúc và embeddings, cùng một smoke test cần chạy trước khi chuyển bất kỳ traffic nào. Ví dụ dùng BroadNet Inference tại https://inference.broadnet.ai/v1; các bước tương tự áp dụng cho mọi nhà cung cấp.
Đây là phần code đi kèm checklist chuyển đổi, vốn bàn về giới hạn tốc độ, lỗi và kế hoạch chuyển giao. Về base URL của các nhà cung cấp khác, xem danh sách base URL tương thích OpenAI đã kiểm tra.
Cài đặt client thay đổi những gì?
Ba giá trị: base URL, API key và model ID.
Python
import os
from openai import OpenAI
# before: client = OpenAI() # reads OPENAI_API_KEY, calls api.openai.com
client = OpenAI(
base_url="https://inference.broadnet.ai/v1",
api_key=os.environ["BROADNET_API_KEY"],
)
r = client.chat.completions.create(
model="broadnet/gemma-4-26b-a4b", # was e.g. "gpt-..."
messages=[{"role": "user", "content": "Reply with one short sentence."}],
)
print(r.choices[0].message.content)
Node
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://inference.broadnet.ai/v1",
apiKey: process.env.BROADNET_API_KEY,
});
const r = await client.chat.completions.create({
model: "broadnet/gemma-4-26b-a4b",
messages: [{ role: "user", content: "Reply with one short sentence." }],
});
console.log(r.choices[0].message.content);
cURL
curl https://inference.broadnet.ai/v1/chat/completions \
-H "Authorization: Bearer $BROADNET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"broadnet/gemma-4-26b-a4b","messages":[{"role":"user","content":"Reply with one short sentence."}]}'
Hãy chú ý đường dẫn: base URL đã kết thúc bằng /v1, nên SDK chỉ thêm /chat/completions. Lặp /v1 hai lần là lỗi đầu tiên phổ biến nhất.
Có thể chuyển mà không đụng vào code không?
Có, với code Chat Completions. Python SDK đọc OPENAI_BASE_URL khi không có base_url được truyền vào, còn client Node đặt baseURL mặc định là process.env['OPENAI_BASE_URL']. Cả hai đều đọc OPENAI_API_KEY. Đặt hai biến môi trường là chuyển được mọi lệnh gọi.
Đó cũng chính là rủi ro. Mọi lệnh gọi đều chuyển theo, kể cả embeddings, moderation, tải file lên và bất cứ thứ gì nhà cung cấp mới có thể không có. Chỉ dùng cách chuyển bằng biến môi trường khi ứng dụng của bạn chỉ gọi chat và không gì khác.
Nếu code của tôi dùng Responses API thì sao?
README của các SDK OpenAI giờ gọi Responses API là API chính; README Python gọi Chat Completions là “the previous standard (supported indefinitely)” (bản dịch: tiêu chuẩn trước đây (được hỗ trợ vô thời hạn)). Nhiều nhà cung cấp tương thích chỉ cài đặt Chat Completions. BroadNet ghi trong tài liệu POST /v1/chat/completions và POST /v1/audio/transcriptions, nên các lệnh gọi Responses cần viết lại. Bảng ánh xạ:
| Responses API | Chat Completions |
|---|---|
client.responses.create(...) |
client.chat.completions.create(...) |
instructions="..." |
Message đầu tiên {"role": "system", "content": "..."} |
input="..." hoặc một danh sách item |
messages=[...] |
response.output_text |
response.choices[0].message.content |
max_output_tokens |
max_tokens (tài liệu BroadNet) hoặc max_completion_tokens |
text={"format": {...}} |
response_format={...} |
previous_response_id, conversations |
Tự gửi lại toàn bộ lịch sử message |
Công cụ {"type": "function", "name": ...} |
Công cụ {"type": "function", "function": {"name": ...}} |
Item đầu ra function_call, trả lời bằng function_call_output và call_id |
message.tool_calls, trả lời bằng role tool và tool_call_id |
| Công cụ có sẵn (web search, file search) | Không có; tự chạy công cụ của bạn |
Trước và sau với một lệnh gọi đơn giản:
# Before: Responses API
r = client.responses.create(model="gpt-...", instructions="Be brief.", input="What is RAG?")
text = r.output_text
# After: Chat Completions
r = client.chat.completions.create(
model="broadnet/gemma-4-26b-a4b",
messages=[{"role": "system", "content": "Be brief."},
{"role": "user", "content": "What is RAG?"}],
)
text = r.choices[0].message.content
Thay đổi lớn nhất về cấu trúc là trạng thái. Responses có thể giữ trạng thái hội thoại phía OpenAI bằng previous_response_id. Chat Completions không có trạng thái phía server, nên code của bạn phải lưu danh sách message và gửi toàn bộ ở mỗi lượt. Hãy tính trước chi phí đó: toàn bộ lịch sử là token đầu vào ở mọi lệnh gọi.
Lệnh gọi công cụ thay đổi thế nào?
Trong Chat Completions, định nghĩa công cụ lồng hàm dưới khóa function, và kết quả được gửi lại dưới dạng message tool:
import json
tools = [{
"type": "function",
"function": {
"name": "get_order",
"description": "Look up an order by ID.",
"parameters": {"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"]},
},
}]
messages = [{"role": "user", "content": "Where is order A-1042?"}]
r = client.chat.completions.create(model="broadnet/glm-5.3", messages=messages, tools=tools)
msg = r.choices[0].message
if msg.tool_calls:
messages.append(msg) # keep the assistant turn
for call in msg.tool_calls:
args = json.loads(call.function.arguments) # a JSON string: parse and validate it
messages.append({"role": "tool", "tool_call_id": call.id,
"content": json.dumps(lookup_order(args["order_id"]))})
r = client.chat.completions.create(model="broadnet/glm-5.3", messages=messages, tools=tools)
Model quan trọng hơn cấu trúc. Tài liệu của BroadNet chỉ liệt kê công cụ cho GLM 5.3 và Qwen3.8 27B. Đừng trỏ vòng lặp công cụ tới model mà tài liệu không liệt kê công cụ, và hãy validate tham số trước khi chạy bất cứ thứ gì. Bài gọi công cụ với model mở có một vòng lặp đầy đủ kèm validate.
Còn đầu ra có cấu trúc thì sao?
client.chat.completions.parse(..., response_format=MyPydanticModel) và zodResponseFormat của Node đều gửi response_format kèm một JSON schema. Chúng chỉ hoạt động nếu nhà cung cấp nhận cấu trúc đó trên model đó. BroadNet liệt kê đầu ra có cấu trúc cho GLM 5.3 và Qwen3.8 27B nhưng không nêu tên tham số request. Hãy chạy bài test bốn bước trong JSON mode và json_schema một lần cho mỗi model, và tiếp tục validate kết quả đã parse dù nhà cung cấp hứa hẹn gì.
Embeddings sẽ ra sao?
Nếu bạn đổi base URL trên một client dùng chung và nhà cung cấp không có endpoint embeddings, mọi lệnh gọi client.embeddings.create đều thất bại. BroadNet không bán embeddings. Hãy giữ hai client:
chat = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
embed = OpenAI(api_key=os.environ["OPENAI_API_KEY"]) # or any embeddings provider
vec = embed.embeddings.create(model="text-embedding-3-small", input=query).data[0].embedding
answer = chat.chat.completions.create(model="broadnet/glm-5.3", messages=build_prompt(query, search(vec)))
Đừng bao giờ trộn vector từ hai model embedding trong cùng một index. Nếu bạn cũng đổi nhà cung cấp embedding, hãy embed lại toàn bộ kho dữ liệu. Công cụ tính chi phí embedding tính giá cho việc đó.
Điều tương tự áp dụng cho mọi thứ không phải chat: tạo hình ảnh, chuyển văn bản thành giọng nói, moderation, Batch API và lưu trữ file. BroadNet không cung cấp thứ nào trong số đó. Chuyển giọng nói thành văn bản thì chuyển được: client.audio.transcriptions.create hoạt động với /v1/audio/transcriptions cùng file WAV hoặc MP3 và trường language (hướng dẫn chuyển giọng nói tiếng Ả Rập thành văn bản).
Code streaming thay đổi thế nào?
Responses API stream các sự kiện có kiểu, như response.output_text.delta và response.completed. Chat Completions stream các chunk, và văn bản nằm trong choices[0].delta.content. Usage không được gửi trừ khi bạn yêu cầu, và khi đó nó đến trong chunk cuối có danh sách choices rỗng.
// Before (Responses): for await (const e of stream) if (e.type === "response.output_text.delta") out(e.delta);
const stream = await client.chat.completions.create({
model: "broadnet/gemma-4-26b-a4b",
messages: [{ role: "user", content: "Count from one to three." }],
stream: true,
stream_options: { include_usage: true },
});
for await (const chunk of stream) {
const text = chunk.choices[0]?.delta?.content;
if (text) process.stdout.write(text);
if (chunk.usage) console.log("\ntokens:", chunk.usage.total_tokens); // last chunk
}
Hai thói quen giữ code stream an toàn sau khi chuyển. Hãy kiểm tra choices[0] trước khi dùng, vì chunk usage không có choices. Và coi một stream kết thúc trước dòng data: [DONE] cuối cùng là chưa hoàn chỉnh; tài liệu của BroadNet khuyên ghi lại X-Request-ID và quyết định xem gửi request mới có an toàn không. Bài streaming chat completions có mẫu đầy đủ bằng Python.
Xử lý lỗi và retry có thay đổi không?
Các lớp lỗi của SDK giữ nguyên: AuthenticationError cho 401, RateLimitError cho 429, APIStatusError cho phần còn lại. Điều thay đổi là ý nghĩa của từng mã trạng thái ở nhà cung cấp mới. Trên BroadNet, lỗi 401 có thể nghĩa là đã hết hạn mức trả theo mức dùng, không chỉ là key sai, còn 402 nghĩa là không đủ số dư cho một lần mua. Cả hai đều không hết khi retry. Lỗi 429 có thể đến từ giới hạn tốc độ, đồng thời, tốc độ token hoặc chi tiêu. Hãy retry 429 và 5xx có backoff, và sửa mọi lỗi còn lại. Hướng dẫn lỗi và retry có bảng đầy đủ.
SDK mặc định retry lỗi kết nối, 408, 409, 429 và 5xx hai lần. Nếu bạn thêm vòng retry của riêng mình, hãy đặt max_retries=0 trên client để hai cơ chế không chồng lên nhau.
Tham số nào hoạt động khác?
| Tham số | Cần kiểm tra gì |
|---|---|
max_tokens / max_completion_tokens |
OpenAI ngừng hỗ trợ max_tokens; tài liệu BroadNet vẫn dùng nó. Trên model suy luận, nó bao gồm cả phần suy nghĩ, nên giá trị nhỏ sẽ trả về câu trả lời rỗng (vì sao) |
reasoning_effort |
BroadNet ghi trong tài liệu giá trị low; hãy test các giá trị khác trước khi dựa vào |
stream_options: {"include_usage": true} |
Có trong tài liệu BroadNet; usage đến trong chunk cuối |
n, logprobs, seed, logit_bias |
Không có trong tài liệu BroadNet; hãy test, hoặc bỏ đi |
store, metadata |
Tính năng lưu trữ của OpenAI; bỏ đi |
Phần nội dung image_url |
Chỉ trên các model được liệt kê hỗ trợ hình ảnh: DeepSeek V4.1 Flash, Qwen3.8 27B, Gemma 4 VL 26B |
Test việc chuyển đổi như thế nào?
Hãy chạy một smoke test ngắn với nhà cung cấp mới trước khi chuyển bất kỳ traffic nào. Bài test này kiểm tra chat thông thường, usage khi streaming, ngân sách suy luận và xác thực. Thêm một trường hợp gọi công cụ nếu bạn dùng công cụ.
import os, openai
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=0)
FAST, REASONING = "broadnet/gemma-4-26b-a4b", "broadnet/qwen3.8-27b"
msg = [{"role": "user", "content": "Reply with the word ok."}]
# 1. Plain chat returns text and usage
r = client.chat.completions.create(model=FAST, messages=msg)
assert r.choices[0].message.content and r.usage.prompt_tokens > 0
# 2. Streaming reports usage in the last chunk
chunks = list(client.chat.completions.create(model=FAST, messages=msg, stream=True,
stream_options={"include_usage": True}))
assert chunks[-1].usage is not None
# 3. A reasoning model needs room: a tiny budget can come back empty
r = client.chat.completions.create(model=REASONING, messages=msg, max_tokens=2000)
assert r.choices[0].finish_reason == "stop" and r.choices[0].message.content
# 4. A bad key raises AuthenticationError (401), which you should not retry
bad = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key="invalid", max_retries=0)
try:
bad.chat.completions.create(model=FAST, messages=msg)
raise AssertionError("expected 401")
except openai.AuthenticationError:
pass
print("smoke test passed")
Sau đó hãy so sánh chất lượng, không chỉ cấu trúc. Chạy lại một mẫu prompt thực tế trên cả hai nhà cung cấp và chấm điểm câu trả lời; bài đánh giá LLM trước khi chuyển đổi chỉ cách làm. Công cụ chuyển từ OpenAI sang BroadNet giúp bạn viết lại một đoạn code và liệt kê những tính năng nó đang dùng.
Thứ gì hay hỏng nhất?
- Base URL toàn cục, kéo theo cả lệnh gọi embeddings và file.
- Helper chỉ có ở Responses, như
output_text, còn sót trong code giờ đã gọi Chat Completions. - Model ID. Tên
gpt-...không tồn tại ở nơi khác. Trên BroadNet, chúng có dạngbroadnet/glm-5.3. - Câu trả lời rỗng từ model suy luận khi
max_tokensnhỏ. - Giới hạn tốc độ. Key trả theo mức dùng của BroadNet cho phép 30 request mỗi phút và 4 request đồng thời. Job khối lượng lớn cần hàng đợi (xử lý lỗi 429).
BroadNet Inference phù hợp ở đâu?
BroadNet Inference phù hợp với ứng dụng dùng OpenAI cho chat và chép lời: trợ lý, trích xuất, tóm tắt, dịch và giọng nói tiếng Ả Rập. Nó cũng hợp với ứng dụng muốn dùng gói giá cố định DeepSeek V4.1 Flash cho agent. Đây là lựa chọn sai nếu bạn phụ thuộc vào trạng thái phía server của Responses API, công cụ có sẵn, embeddings, tạo hình ảnh, chuyển văn bản thành giọng nói, giọng nói thời gian thực hoặc Batch API. Hãy chuyển những phần đó sang nhà cung cấp có hỗ trợ, hoặc giữ chúng trên OpenAI và chỉ chuyển các lệnh gọi chat. Gemma 4 VL 26B và cả hai model chép lời chạy được bằng tín dụng ban đầu $5; GLM 5.3, Qwen3.8 27B và DeepSeek V4.1 Flash cần nạp tiền trước.
