---
title: "Chuyển sang API tương thích OpenAI: checklist chuyển đổi"
description: "Đổi base_url là phần dễ. Thứ hay hỏng là model ID, token suy luận, usage khi streaming, lỗi, giới hạn tốc độ và key. Checklist kèm code cho từng bước."
url: https://broadrouter.com/vi/blog/openai-compatible-api-migration-checklist/
lang: vi
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Được dịch từ tiếng Anh với sự hỗ trợ của AI. [Đọc bản gốc tiếng Anh](https://broadrouter.com/blog/openai-compatible-api-migration-checklist/) (cập nhật ngày 2026-11-16).

# 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 2026-11-14 · Cập nhật 2026-11-16

Để 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.

## Ý chính

-   Có ba thiết lập thay đổi: `base_url`, `api_key` và `model`.
-   Liệt kê mọi endpoint và field mà ứng dụng dùng trước khi chuyển, rồi test từng cái.
-   Model suy luận tính cả phần suy nghĩ vào `max_tokens`; giới hạn nhỏ sẽ trả về câu trả lời rỗng.
-   Hãy yêu cầu usage trong stream bằng `stream_options`, nếu không bạn sẽ mất dấu chi phí.
-   Xác định mã lỗi nào cần retry, mã nào cần sửa trước khi chuyển traffic production.
-   Chạy song song nhà cung cấp cũ và mới trên traffic thật trong một ngày trước khi chuyển hẳn.

**Trong trang này**

1.  0\. Ứng dụng của bạn hiện đang dùng gì?
2.  1\. Ba thiết lập nào thay đổi?
3.  2\. Model ID mới là gì?
4.  3\. Vì sao câu trả lời rỗng sau khi chuyển?
5.  4\. Streaming còn báo usage không?
6.  5\. Nên retry những lỗi nào?
7.  6\. Giới hạn tốc độ mới là gì?
8.  7\. Prompt của bạn còn vừa không?
9.  8\. Còn key và lưu giữ dữ liệu thì sao?
10.  9\. Chuyển hẳn sang an toàn thế nào?
11.  Những lỗi thường gặp khi chuyển đổi là gì?
12.  BroadNet Inference phù hợp ở đâu

Phần lớn nhà cung cấp LLM giờ đều dùng [định dạng OpenAI API](https://broadrouter.com/vi/glossary/openai-compatible-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](https://broadrouter.com/vi/blog/whisper-api-alternative/) đề 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?

```python
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](https://broadrouter.com/vi/glossary/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](https://github.com/openai/openai-python), 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](https://broadrouter.com/vi/glossary/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](https://broadrouter.com/vi/guides/openai-python-sdk/), [Node.js](https://broadrouter.com/vi/guides/openai-node-sdk/), [LangChain](https://broadrouter.com/vi/guides/langchain-openai-base-url/). Để tự dựng và test request đầu tiên, hãy dùng [công cụ dựng request API](https://broadrouter.com/tools/api-request-builder/). Để á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](https://broadrouter.com/tools/openai-to-broadnet-migration/), 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](https://broadrouter.com/vi/models/deepseek-v4.1-flash/), [GLM 5.3](https://broadrouter.com/vi/models/glm-5.3/), [Qwen3.8 27B](https://broadrouter.com/vi/models/qwen3.8-27b/) và [Gemma 4 VL 26B](https://broadrouter.com/vi/models/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](https://broadrouter.com/vi/glossary/reasoning-tokens/) được tính vào [`max_tokens`](https://broadrouter.com/vi/glossary/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 đủ](https://broadrouter.com/vi/guides/reasoning-tokens-empty-response/).

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

[Stream](https://broadrouter.com/vi/glossary/streaming/) 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:

```python
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](https://broadrouter.com/vi/guides/streaming-chat-completions/).

## 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ã](https://broadrouter.com/vi/guides/errors-and-retries/).

## 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 độ](https://broadrouter.com/tools/llm-rate-limit-calculator/) giúp tính kích thước. [Tính kích thước cho agent chạy song song](https://broadrouter.com/vi/blog/run-parallel-coding-agents-flat-rate/).

## 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](https://broadrouter.com/tools/context-window-calculator/). Đặt phần nội dung prompt ổn định lên đầu để hưởng [giá đầu vào từ cache](https://broadrouter.com/vi/blog/cached-input-tokens-explained/).

## 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](https://broadrouter.com/vi/guides/api-keys-ip-allow-lists/). Hỏi nhà cung cấp mới họ lưu giữ những gì; xem [checklist ZDR](https://broadrouter.com/vi/blog/zero-data-retention-llm-api-checklist/).

## 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](https://broadrouter.com/vi/guides/litellm-proxy-custom-provider/) 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ông cụ miễn phí cho chủ đề này (tiếng Anh)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[Công cụ miễn phí (tiếng Anh)](https://broadrouter.com/tools/)

## Thuật ngữ trong bài này

[Tool calling (gọi tool, function calling)](https://broadrouter.com/vi/glossary/tool-calling/)

Tool calling, còn gọi là function calling, là tính năng của API LLM trong đó model trả về một yêu cầu có cấu trúc để chạy một hàm do nhà phát triển định nghĩa, kèm đối số JSON. Ứng dụng chạy hàm rồi gửi kết quả lại; model không bao giờ tự chạy code.

[Chuyển giọng nói thành văn bản (speech-to-text)](https://broadrouter.com/vi/glossary/speech-to-text/)

Chuyển giọng nói thành văn bản, hay nhận dạng giọng nói tự động (ASR), là công nghệ biến lời nói thành chữ viết. API nhận tệp hoặc luồng âm thanh, trả về bản chép lời, thường tính theo phút. Độ chính xác đo bằng tỷ lệ lỗi từ, thay đổi theo giọng, phương ngữ và chất lượng ghi âm.

[Embedding (vector nhúng)](https://broadrouter.com/vi/glossary/embeddings/)

Embedding là danh sách số thực (vector) mà một model tạo ra để biểu diễn đoạn văn bản, hình ảnh hay đầu vào khác. Đầu vào có nghĩa tương tự nhận vector gần nhau, nên khoảng cách giữa vector dùng được để xếp hạng kết quả tìm kiếm, gom cụm tài liệu hoặc tìm mục liên quan.

[Streaming (trả phản hồi dạng luồng)](https://broadrouter.com/vi/glossary/streaming/)

Streaming là cách trả phản hồi của model ngôn ngữ thành từng chunk nhỏ ngay trong lúc nó đang được sinh, thay vì một câu trả lời trọn vẹn ở cuối. Các API tương thích OpenAI stream qua server-sent events khi request đặt stream là true.

[Token](https://broadrouter.com/vi/glossary/token/)

Token là đơn vị văn bản mà model ngôn ngữ đọc và viết: một từ, một phần của từ, một dấu câu hoặc một chuỗi byte do tokenizer của model tạo ra. API LLM đếm, giới hạn và thường tính phí theo token.

[Trả theo mức dùng (pay-as-you-go)](https://broadrouter.com/vi/glossary/pay-as-you-go/)

Trả theo mức dùng (pay-as-you-go) là mô hình giá mà bạn chỉ trả cho những gì đã dùng, đo theo đơn vị như token, request hoặc phút âm thanh, không có gói đăng ký hay cam kết tối thiểu. Hầu hết API LLM tính phí theo cách này, trừ vào số dư trả trước hoặc qua hóa đơn định kỳ.

[Base URL](https://broadrouter.com/vi/glossary/base-url/)

Base URL là địa chỉ gốc cố định của một API, như https://api.example.com/v1, mà client đặt trước mọi đường dẫn endpoint, như /chat/completions. Trong SDK tương thích OpenAI, đổi base URL cùng với API key và model ID sẽ trỏ cùng một đoạn code sang nhà cung cấp khác.

[Chat Completions API](https://broadrouter.com/vi/glossary/chat-completions-api/)

Chat Completions API là endpoint HTTP của OpenAI, POST /v1/chat/completions, nhận tên model và danh sách message có gắn vai trò rồi trả về message tiếp theo của model. Cấu trúc request và response của nó đã trở thành định dạng chung mà các nhà cung cấp và SDK tương thích OpenAI dùng lại.

## 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 tiếp

-   [Base URL của API tương thích OpenAI: 14 nhà cung cấp, đã kiểm tra](https://broadrouter.com/vi/blog/openai-compatible-api-base-urls/)
-   [OpenRouter hay gói giá cố định cho AI agent: bên nào rẻ hơn?](https://broadrouter.com/vi/blog/openrouter-alternative-flat-rate/)
-   [Khi nào context window 1M token đáng dùng (và khi nào không)](https://broadrouter.com/vi/blog/million-token-context-window-guide/)
-   [API LLM không lưu giữ dữ liệu: checklist 10 câu hỏi](https://broadrouter.com/vi/blog/zero-data-retention-llm-api-checklist/)
-   [Phần cứng GPU và cách phục vụ model của BroadNet, theo lời BroadNet](https://broadrouter.com/vi/blog/broadnet-gpu-fleet-and-serving/)
-   [Cache phản hồi API LLM để giảm chi phí: cache khớp chính xác (Python)](https://broadrouter.com/vi/blog/cache-llm-responses-cut-cost/)
-   [Hướng dẫn: Dùng OpenAI Python SDK với BroadNet Inference](https://broadrouter.com/vi/guides/openai-python-sdk/)
-   [Hướng dẫn: Dùng OpenAI Node.js SDK với BroadNet Inference](https://broadrouter.com/vi/guides/openai-node-sdk/)
-   [Hướng dẫn: Dùng LangChain với BroadNet Inference](https://broadrouter.com/vi/guides/langchain-openai-base-url/)
-   [Hướng dẫn: Mã lỗi BroadNet Inference và khi nào nên thử lại](https://broadrouter.com/vi/guides/errors-and-retries/)
-   [Hướng dẫn: Streaming chat completions và xử lý khi mất kết nối](https://broadrouter.com/vi/guides/streaming-chat-completions/)
-   [Hướng dẫn: Vì sao model suy luận trả về câu trả lời rỗng](https://broadrouter.com/vi/guides/reasoning-tokens-empty-response/)
-   [Hướng dẫn: Kết nối LiteLLM tới BroadNet Inference (SDK và proxy)](https://broadrouter.com/vi/guides/litellm-proxy-custom-provider/)

Hãy thử với khối lượng công việc thực tế của bạn. Tài khoản mới được tặng US$5 tín dụng ban đầu cho Gemma và chuyển giọng nói thành văn bản. DeepSeek, GLM và Qwen3.8 cần nạp tiền.

[Bắt đầu](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=vi-blog-openai-compatible-api-migration-checklist&utm_content=page-cta) ·

**Nguồn**

-   [Tài liệu tham chiếu API BroadNet Inference (tiếng Anh)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=vi-blog-openai-compatible-api-migration-checklist&utm_content=sources)
-   [README của OpenAI Python SDK (base\_url, OPENAI\_BASE\_URL, retry; truy cập ngày 2026-11-14)](https://github.com/openai/openai-python)
