BroadRouter
Bắt đầu

Chuyển khỏi OpenAI API: hướng dẫn code bằng Python, Node, cURL

Đội ngũ BroadNet Inference · 6 phút đọc · Đăng ngày

Hãy đổi base URL, API key và model ID của client. Với lệnh gọi Chat Completions, vậy là đủ. Code dùng Responses API phải viết lại sang Chat Completions: input thành messages, output_text thành choices[0].message.content, và định nghĩa công cụ bớt một cấp lồng. Giữ embeddings trên một client riêng nếu nhà cung cấp mới không có, rồi chạy smoke test trước khi chuyển traffic.

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ạng broadnet/glm-5.3.
  • Câu trả lời rỗng từ model suy luận khi max_tokens nhỏ.
  • 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.

Câu hỏi thường gặp

Có cần SDK khác để dùng API tương thích OpenAI không?

Không. Hãy giữ package openai chính thức và truyền một base_url (Python) hoặc baseURL (Node) khác, cùng key của nhà cung cấp mới. Đối tượng request và phản hồi giữ nguyên với các endpoint mà nhà cung cấp hỗ trợ.

API tương thích OpenAI có hỗ trợ Responses API không?

Một số có; nhiều nơi chỉ hỗ trợ Chat Completions. Hãy kiểm tra danh sách endpoint của nhà cung cấp. BroadNet Inference ghi trong tài liệu /v1/chat/completions và /v1/audio/transcriptions, nên code Responses phải viết lại sang Chat Completions.

Embeddings của tôi sẽ ra sao khi chuyển đổi?

Chúng sẽ hỏng nếu nhà cung cấp mới không có endpoint embeddings mà bạn đã đổi base URL cho toàn bộ ứng dụng. BroadNet không bán embeddings, nên hãy giữ một client embeddings trỏ tới nhà cung cấp embeddings của bạn. Đừng bao giờ trộn vector từ hai model embedding trong cùng một index.

Nên gửi max_tokens hay max_completion_tokens?

OpenAI đánh dấu max_tokens là ngừng hỗ trợ, thay bằng max_completion_tokens. Nhiều nhà cung cấp tương thích lại ghi max_tokens trong tài liệu, và tài liệu của BroadNet dùng max_tokens. Hãy gửi đúng tham số nhà cung cấp ghi trong tài liệu và xác nhận giới hạn có tác dụng trong smoke test.

Các helper đầu ra có cấu trúc của OpenAI có còn hoạt động không?

Chỉ khi nhà cung cấp nhận response_format kèm json_schema trên model bạn dùng. 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, nên hãy test, và tiếp tục validate kết quả đã parse.

Đọc dạng MarkdownHỏi ChatGPTHỏi ClaudeHỏi Perplexity