BroadRouter
Bắt đầu

Chuyển sang API tương thích OpenAI: checklist khi chuyển đổi

Đội ngũ BroadNet Inference · 5 phút đọc · Đăng ngày · Cập nhật

Để chuyển sang API tương thích OpenAI, hãy đổi ba thiết lập (base_url, api_key và model) rồi kiểm tra những gì khác biệt: model ID, cách token suy luận tính vào max_tokens, cách streaming báo usage, lỗi nào nên retry, giới hạn tốc độ và bảo mật key. Với BroadNet Inference, base URL là https://inference.broadnet.ai/v1.

Phần lớn nhà cung cấp LLM giờ đều dùng định dạng OpenAI API. Điều đó khiến việc chuyển đổi trông như chỉ cần sửa một dòng, và để nhận câu trả lời đầu tiên thì đúng là vậy. Còn để chạy traffic production, hãy đi qua danh sách này. Mỗi mục đều đến từ một cách chuyển đổi đã thực sự bị hỏng.

0. Ứng dụng của bạn hiện đang dùng gì?

Trước khi thay đổi bất cứ thứ gì, hãy ghi lại những gì ứng dụng phụ thuộc vào. Tìm trong code mọi lời gọi SDK và liệt kê ra. Nếu bạn gọi Whisper API của OpenAI, lưu ý OpenAI ghi whisper-1 sẽ ngừng hoạt động vào ngày 26 tháng 2 năm 2027; các lựa chọn thay thế Whisper API đề cập phần âm thanh.

Tính năng Tìm ở đâu Test sau khi chuyển
Chat completions Mọi chat.completions.create Cùng prompt, so sánh câu trả lời
Streaming stream=True Chunk đến đủ, kết thúc bằng [DONE], có usage
Tool calling tools= Tool call được parse và chạy
Đầu ra có cấu trúc response_format= JSON validate đúng schema của bạn
Hình ảnh Phần hình ảnh trong message Model chấp nhận
Chép lời âm thanh audio.transcriptions Văn bản và ngôn ngữ đúng
Embeddings, file, batch Các endpoint khác Kiểm tra nhà cung cấp có hỗ trợ không

Dòng cuối rất quan trọng. “Tương thích OpenAI” thường ưu tiên chat completions trước. Danh mục của BroadNet Inference có các model chat trên /v1/chat/completions và model chuyển giọng nói thành văn bản trên /v1/audio/transcriptions; nếu bạn dùng endpoint khác, hãy giữ chúng ở nhà cung cấp hiện tại hoặc tìm chỗ thay thế.

1. Ba thiết lập nào thay đổi?

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)

Tên của thiết lập base URL khác nhau theo thư viện: base_url trong Python SDK và ChatOpenAI của LangChain, baseURL trong Node.js SDK. Theo README, Python SDK còn đọc biến môi trường OPENAI_BASE_URL. Hãy kiểm tra xem môi trường có còn giá trị cũ không, nếu không request có thể đi tới nhà cung cấp cũ mà không báo lỗi.

Giữ API key trong biến môi trường hoặc secret manager, đừng bao giờ để trong code. Cài đặt cho từng SDK: Python, Node.js, LangChain. Để tự dựng và test request đầu tiên, hãy dùng công cụ dựng request API. Để áp dụng thay đổi base URL, key và model vào code có sẵn, hãy dán code vào công cụ hỗ trợ chuyển từ OpenAI sang BroadNet, công cụ này cũng liệt kê những gì cần kiểm tra.

2. Model ID mới là gì?

Mỗi nhà cung cấp đặt tên model theo cách riêng. Trên BroadNet Inference:

Model ID
DeepSeek V4.1 Flash broadnet/deepseek-v4.1-flash
GLM 5.3 broadnet/glm-5.3
Qwen3.8 27B broadnet/qwen3.8-27b
Gemma 4 VL 26B broadnet/gemma-4-26b-a4b

Đặt model ID trong cấu hình, không phải trong code, để lần đổi sau chỉ là một lần deploy chứ không phải viết lại. Giới hạn và giá của từng model có trên trang riêng: DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B và Gemma 4 VL 26B.

3. Vì sao câu trả lời rỗng sau khi chuyển?

Đây là bất ngờ phổ biến nhất. DeepSeek V4.1 Flash, GLM 5.3 và Qwen3.8 27B suy luận trước khi trả lời, và token suy luận được tính vào max_tokens. Giới hạn 256 vốn chạy tốt trên model không suy luận có thể bị dùng hết cho phần suy nghĩ, nên câu trả lời trả về rỗng. Hãy để 1.000 token trở lên, hoặc đặt reasoning_effort là low cho việc đơn giản. Giải thích đầy đủ.

4. Streaming còn báo usage không?

Stream dùng Server-Sent Events và kết thúc bằng data: [DONE]. Usage token chỉ có trong chunk cuối nếu bạn yêu cầu:

stream = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash", messages=messages,
    stream=True, stream_options={"include_usage": True},
)

Không có nó, dashboard chi phí của bạn hiển thị số 0. Nếu stream kết thúc trước [DONE], hãy coi là chưa hoàn chỉnh. Hướng dẫn streaming.

5. Nên retry những lỗi nào?

Mã Ý nghĩa Hành động
401 Key sai hoặc đã bị thu hồi, hoặc đã dùng hết hạn mức trả theo mức dùng Sửa, không retry
402 Số dư hoặc ngân sách Nạp tiền, không retry
403 Bị từ chối do chính sách model, route hoặc IP Sửa chỗ không khớp
413 Request quá lớn Thu nhỏ, không retry
429 Giới hạn tốc độ, đồng thời hoặc chi tiêu Backoff rồi retry
5xx Lỗi phía server Retry với backoff có giới hạn

Python SDK chính thức đã tự retry một số lỗi: README nói lỗi kết nối, 408, 409, 429 và 5xx mặc định được retry hai lần với exponential backoff ngắn. Hãy đặt max_retries một cách tường minh để hành vi này là một quyết định, không phải mặc định. Ghi log request ID của mọi response để bộ phận hỗ trợ có thể lần ra vấn đề. Tất cả các mã.

6. Giới hạn tốc độ mới là gì?

Hãy nắm giới hạn mới trước khi traffic đến. Một key trả theo mức dùng của BroadNet cho phép 30 request mỗi phút và 4 request đang chạy cùng lúc. Gói không giới hạn chạy một request tại một thời điểm cho mỗi phiên. Hãy chỉnh kích thước worker pool cho khớp, nếu không bạn sẽ gặp 429 ngay ngày đầu; công cụ tính giới hạn tốc độ giúp tính kích thước. Tính kích thước cho agent chạy song song.

7. Prompt của bạn còn vừa không?

Kiểm tra context window: 1.048.576 token với DeepSeek V4.1 Flash và GLM 5.3, 262.144 với Qwen3.8 27B, 32.768 với Gemma 4 VL 26B. Prompt vừa với model cũ có thể không vừa với cửa sổ nhỏ hơn; hãy kiểm tra bằng công cụ tính context window. Đặt phần nội dung prompt ổn định lên đầu để hưởng giá đầu vào từ cache.

8. Còn key và lưu giữ dữ liệu thì sao?

Khóa key production vào IP máy chủ của bạn bằng danh sách IP cho phép. Hỏi nhà cung cấp mới họ lưu giữ những gì; xem checklist ZDR.

9. Chuyển hẳn sang an toàn thế nào?

  1. Gửi bản sao request thật của một ngày tới cả hai nhà cung cấp.
  2. So sánh câu trả lời trên một mẫu, cùng độ trễ, lỗi và chi phí mỗi request.
  3. Chuyển 10% traffic, theo dõi một ngày, rồi chuyển phần còn lại.
  4. Giữ nhà cung cấp cũ làm phương án dự phòng (fallback) trong một tuần.

Nếu bạn chạy nhiều dịch vụ, một proxy như LiteLLM cho phép đổi nhà cung cấp ở một chỗ thay vì trong từng ứng dụng.

Những lỗi thường gặp khi chuyển đổi là gì?

  • Thiếu /v1 trong base URL. Request trả về 404. Hãy dùng URL đầy đủ.
  • Tên model cũ trong cấu hình. Nhà cung cấp mới không biết chúng.
  • Còn field riêng của nhà cung cấp trong request. Field mà chỉ nhà cung cấp cũ hiểu có thể bị từ chối hoặc bỏ qua. Hãy xóa chúng khỏi các client dùng chung.
  • Chỉ test một prompt. Hãy chạy danh sách ở bước 0, từng tính năng một.
  • Chuyển vào thứ Sáu. Hãy chừa thời gian theo dõi trọn một ngày traffic thật.

BroadNet Inference phù hợp ở đâu

BroadNet Inference là đích thay thế trực tiếp cho các ứng dụng dùng chat completions và chép lời âm thanh qua OpenAI SDK: đổi ba thiết lập và đi qua danh sách trên. Danh mục chỉ có model chat và model chuyển giọng nói thành văn bản, nên nếu bạn phụ thuộc vào endpoint khác như embeddings hay lưu trữ file, hãy giữ chúng ở nhà cung cấp khác. Tài khoản mới bắt đầu với $5 tín dụng ban đầu. Trong các model chat, chỉ Gemma 4 VL 26B chạy được bằng khoản này (nó cũng dùng được cho hai model Transcribe), nên chạy thử song song (shadow test) trên DeepSeek, GLM hay Qwen cần nạp thêm tiền.

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

Có cần SDK khác không?

Không. Các SDK chính thức của OpenAI cho Python và Node.js nhận base URL tùy chỉnh. Các framework xây trên chúng, như ChatOpenAI của LangChain, cũng vậy.

Đổi base URL trong OpenAI SDK thế nào?

Truyền base_url cho client trong Python hoặc baseURL trong Node.js, hoặc đặt biến môi trường OPENAI_BASE_URL. Với BroadNet Inference, giá trị là https://inference.broadnet.ai/v1, còn key đặt trong api_key.

Vì sao nhận phản hồi rỗng sau khi chuyển?

Các model suy luận như DeepSeek V4.1 Flash, GLM 5.3 và Qwen3.8 27B suy nghĩ trước khi trả lời, và phần suy nghĩ được tính vào max_tokens. Hãy tăng max_tokens lên 1.000 trở lên, hoặc đặt reasoning_effort là low.

Vì sao gặp lỗi 404 hoặc model not found sau khi chuyển?

Thường là model ID vẫn mang tên của nhà cung cấp cũ, hoặc base URL thiếu đường dẫn /v1. Hãy dùng đúng model ID của nhà cung cấp mới và base URL đầy đủ.

Nên retry những lỗi nào?

Retry 429 và 5xx với exponential backoff có giới hạn. Sửa 401, 402 và 413 trước khi gửi lại. Hướng dẫn về lỗi trên trang này liệt kê mọi mã.

Tương thích OpenAI có nghĩa là giống hệt không?

Không. Cấu trúc request và response giống nhau, nhưng model ID, tham số được hỗ trợ, giới hạn, các field usage và chi tiết lỗi có thể khác. Hãy test mọi tính năng ứng dụng của bạn dùng.

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