Qwen API do Alibaba Cloud Bailian (Model Studio) cung cấp; DashScope là hệ thống giao diện gốc của nó. Bailian đồng thời cung cấp giao diện tương thích OpenAI và giao diện gốc DashScope. Với phần lớn đội ngũ, dùng giao diện tương thích OpenAI là tiết kiệm công nhất: SDK, khung Agent và chuỗi công cụ hiện có thường chỉ cần đổi ba chỗ: API Key, Base URL và tên mô hình.
Cái bẫy thật sự không nằm ở “gọi được hay không”, mà ở khu vực của Base URL, tên mô hình có hợp lệ không, phân tích truyền phát thế nào, và khi di chuyển từ OpenAI thì tham số nào không thể bê nguyên. Bài viết dùng yêu cầu tối thiểu để chạy thông đường truyền, sau đó bổ sung gọi công cụ, xử lý lỗi và danh sách di chuyển.
Lưu ý: Qwen, Tongyi Qianwen, Alibaba Cloud, Bailian (Model Studio) và DashScope là nhãn hiệu hoặc tên sản phẩm của Tập đoàn Alibaba và các công ty liên kết; bài viết chỉ nhằm giải thích kỹ thuật, không có quan hệ trực thuộc, đại lý hay cấp phép với Tập đoàn Alibaba. Base URL, tên mô hình, độ dài ngữ cảnh và cách tính phí có thể điều chỉnh; vui lòng căn cứ tài liệu chính thức của Alibaba Cloud Bailian và bảng giá mô hình trên site.
1. Chuẩn bị trước khi tích hợp
Trước khi bắt đầu, xác nhận ba thứ:
- Một API Key khả dụng, khớp với khu vực mục tiêu.
- Base URL đúng; địa chỉ Trung Quốc đại lục, site quốc tế và cổng không được trộn lẫn.
- Một tên mô hình hiện đang thực sự khả dụng, không sao chép ví dụ trong bài cũ.
Nên dùng curl xác minh xác thực và mạng trước, rồi mới tích hợp SDK. Như vậy khi lỗi dễ phân biệt là vấn đề khóa, địa chỉ hay mã.
2. Base URL: chọn khu vực trước, chọn tên miền sau
Đường dẫn của giao diện tương thích OpenAI cố định là /compatible-mode/v1; giao diện chat ghép thêm /chat/completions. Tên miền phân theo khu vực, các cách viết phổ biến như sau:
| Tình huống | Base URL tương thích OpenAI | Ghi chú |
|---|---|---|
| Trung Quốc đại lục (Bắc Kinh, tên miền chia sẻ cũ) | https://dashscope.aliyuncs.com/compatible-mode/v1 |
Tương thích mã cũ, hiện vẫn dùng được |
| Singapore (site quốc tế) | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 |
Tài khoản và khóa của site quốc tế |
| Virginia, Hoa Kỳ | https://dashscope-us.aliyuncs.com/compatible-mode/v1 |
Chỉ IPv4, năng lực căn cứ tài liệu |
| Hồng Kông, Trung Quốc | https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1 |
Khu vực và khóa độc lập |
| Không gian nghiệp vụ riêng | https://{WorkspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1 |
Khuyến nghị cho sản xuất, thông lượng và cô lập tốt hơn |
| ZSQH AI Gateway | https://ai.zhongshangqihang.com/v1 |
Đầu mối đa mô hình thống nhất |
Vài điểm then chốt. Thứ nhất, API Key gắn với khu vực; gọi khác khu vực thường trả về 401 và invalid_api_key, nghĩa là khóa và địa chỉ không khớp chứ không phải khóa mất hiệu lực. Thứ hai, tài khoản Trung Quốc đại lục và tài khoản site quốc tế là hai hệ thống; khóa, hóa đơn và danh sách mô hình không dùng chung. Thứ ba, tên miền riêng của không gian nghiệp vụ chỉ chấp nhận khóa của chính không gian đó, nhưng thông lượng và cô lập lưu lượng tốt hơn, phù hợp sản xuất; tên miền chia sẻ cũ thuận tiện cho việc dùng chéo không gian và kiểm thử nhanh.
Nếu đội dùng nhiều mô hình cùng lúc và không muốn tự duy trì khu vực, hạn mức và nhiều bộ khóa, có thể tạo khóa thống nhất tại ZSQH AI Gateway, rồi đổi Base URL thành địa chỉ ở dòng cuối bảng trên.
3. Chọn tên mô hình
Danh sách mô hình của Bailian cập nhật rất nhanh. Lấy trang mô hình chính thức hiện tại làm ví dụ, phần sinh văn bản liệt kê các mô hình Qwen gồm qwen3.8-max, qwen3.7-plus và qwen3.8-flash. Từ cách đặt tên có thể hiểu đại khái: max thiên về giới hạn năng lực, plus thiên về cân bằng, flash thiên về độ trễ thấp và chi phí thấp; định vị và độ dài ngữ cảnh cụ thể căn cứ tài liệu mô hình chính thức, giá có thể điều chỉnh, căn cứ trang bảng giá mô hình.
Khi chọn, đừng chỉ nhìn “mạnh nhất”. Các nhiệm vụ như hỏi đáp chăm sóc khách hàng, phân loại hàng loạt, kiểm duyệt nội dung thường dùng bậc độ trễ thấp sẽ kinh tế hơn; phân tích tài liệu dài, Agent phức tạp mới dùng cấu hình cao. Hãy biến tên mô hình thành mục cấu hình thay vì viết cứng trong mã, việc chuyển đổi về sau sẽ nhẹ nhàng hơn nhiều.
Còn hai cái bẫy dễ gặp. Các cách viết như qwen-max, qwen-plus trong hướng dẫn cũ có thể đã điều chỉnh; trước khi tích hợp hãy xác nhận trong danh sách mô hình của bảng điều khiển. Khi cần năng lực vector, dùng dòng embedding (ví dụ qwen3.7-text-embedding); nó không cùng kiểu thân yêu cầu với giao diện chat. Qwen-Audio không hỗ trợ giao thức tương thích OpenAI, cần dùng giao diện gốc DashScope.
4. Chạy thông lần gọi đầu bằng curl
Trước hết chuẩn bị biến môi trường để khóa không xuất hiện trong lịch sử lệnh:
export DASHSCOPE_API_KEY="your_key_here"
curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-max",
"messages": [
{"role": "system", "content": "Bạn là trợ lý kỹ thuật ngắn gọn."},
{"role": "user", "content": "Giải thích API gateway là gì trong ba câu."}
],
"temperature": 0.7
}'
Khi trả về bình thường, chú ý ba trường: choices[0].message.content là câu trả lời, usage là mức dùng lần này, finish_reason cho biết lý do kết thúc. Nếu trả về 401, kiểm tra khóa và khu vực trước; nếu trả về 404 và ModelNotFound, kiểm tra tên mô hình và khu vực đó có mở mô hình này không.
5. Gọi bằng SDK Python và truyền phát
SDK OpenAI cần phiên bản 1.0 trở lên. Trỏ Base URL tới Bailian, cách gọi cơ bản giống OpenAI:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
stream = client.chat.completions.create(
model="qwen3.8-max",
messages=[{"role": "user", "content": "Viết một đoạn giới thiệu sản phẩm, không quá một trăm từ."}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
Truyền phát cần lưu ý: khối đầu tiên có thể chỉ có thông tin vai trò, content rỗng; đừng giả định mỗi khối đều có văn bản. Sau khi thêm stream_options={"include_usage": True}, mức dùng sẽ xuất hiện ở khối cuối. Khi nối HTTP trực tiếp, phản hồi ở định dạng SSE, kết thúc bằng data: [DONE]. Sau khi người dùng đóng trang, máy chủ nên hủy yêu cầu thượng nguồn càng sớm càng tốt để tránh tiếp tục sinh và tính phí.
6. Gọi công cụ và khác biệt tham số
Gọi công cụ dùng định dạng tools và tool_choice của OpenAI. Sau khi mô hình trả về message.tool_calls, cần phân tích function.arguments của từng lời gọi theo JSON, thực thi hàm cục bộ, rồi gửi kết quả lại bằng tin nhắn role: "tool". Trong quy trình nhiều lượt, mỗi lượt yêu cầu đều phải mang theo tools. Môi trường sản xuất phải kiểm tra tham số, kiểm tra quyền và kiểm soát thời gian chờ, không được tin tuyệt đối tham số do mô hình sinh.
Tài liệu tương thích chính thức hiện có hai giới hạn với công cụ: chỉ một số mô hình được liệt kê là hỗ trợ, và tools tạm thời không thể dùng đồng thời với stream=True. Danh sách mô hình và năng lực liên tục cập nhật; trước khi lên tuyến nhất định phải kiểm thử với mô hình mục tiêu; nếu nghiệp vụ bắt buộc vừa truyền phát vừa gọi công cụ, có thể cân nhắc giao diện gốc DashScope hoặc biến gọi công cụ thành bước không truyền phát.
Khi di chuyển từ OpenAI, còn các khác biệt tham số sau cần chú ý:
messages: chỉmessages[0]có thể là vai trò system; user và assistant thường phải xen kẽ, tin cuối cùng phải là user.temperature: phạm vi giá trị là [0, 2); chính thức không khuyến nghị đặt 0.top_p: phạm vi giá trị là (0, 1.0).seed: dùng số nguyên không dấu 64 bit.stop: phần tử mảng không được trộn ID token và chuỗi.system_fingerprint: hiện trả về chuỗi rỗng.- Các tham số mở rộng như
enable_search: thường truyền quaextra_body, và không phải mô hình nào cũng hỗ trợ. - Các trường như
response_format,frequency_penalty: tài liệu tương thích không xác nhận, đừng giả định hành vi giống OpenAI.
7. Đối chiếu lỗi thường gặp
| Hiện tượng | Mã lỗi thường gặp | Nguyên nhân có thể | Cách xử lý |
|---|---|---|---|
| 401 | InvalidApiKey / invalid_api_key |
Sai khóa, không khớp khu vực, trộn khóa theo gói | Đối chiếu khu vực và loại của khóa với Base URL |
| 404 | ModelNotFound / model_not_found |
Sai tên mô hình, khu vực không có mô hình, chưa mở | Xem danh sách mô hình trong bảng điều khiển |
| 404 | model_not_supported |
Mô hình không hỗ trợ chế độ tương thích OpenAI | Chuyển sang giao diện gốc DashScope |
| 403 | AccessDenied / Workspace.AccessDenied |
Thiếu quyền không gian hoặc mô hình | Kiểm tra cấp quyền không gian nghiệp vụ |
| 403 | AllocationQuota.FreeTierOnly |
Đã dùng hết hạn mức miễn phí | Nạp tiền hoặc điều chỉnh gói |
| 429 | Dòng Throttling |
Vượt tần suất yêu cầu, Token hoặc đồng thời | Giảm đồng thời, thử lại có lùi, xin hạn mức |
| 400 | Arrearage |
Tài khoản chậm thanh toán | Nạp tiền rồi thử lại |
| 400 | Range of input length... |
Đầu vào vượt giới hạn ngữ cảnh | Nén lời nhắc hoặc chia đoạn |
| 400 | DataInspectionFailed |
Đầu vào hoặc đầu ra bị chặn an toàn nội dung | Điều chỉnh nội dung rồi thử lại |
Thử lại chỉ có hiệu quả với 429, 5xx và quá thời gian mạng. 401, 403, 404 và lỗi tham số thử lại không tốt hơn mà còn lãng phí thời gian và hạn mức. Khi xử lý sự cố, hãy ghi Request ID trong phản hồi, tra nhật ký bảng điều khiển sẽ nhanh hơn nhiều so với đoán mò.
8. Danh sách kiểm tra khi di chuyển từ OpenAI
- Sao lưu lời nhắc, tham số mô hình và bộ đánh giá hiện có.
- Tạo Qwen Key mới khớp khu vực mục tiêu, không dùng lại khóa của hãng khác.
- Chuyển Base URL và tên mô hình thành mục cấu hình.
- Kiểm tra quy tắc vai trò
messages, xác nhận đầu là system, cuối là user. - Kiểm tra cách phân tích truyền phát và thống kê usage.
- Chạy một vòng hồi quy gọi công cụ với công cụ thật.
- Dùng cùng một bộ mẫu so sánh chất lượng đầu ra, độ trễ và mức dùng.
- Điều chỉnh thử lại, thời gian chờ và đồng thời, quan sát một tuần rồi mới chuyển toàn bộ.
- Ghi Request ID trong nhật ký, giữ công tắc quay lui.
9. Câu hỏi thường gặp (FAQ)
1. Qwen API có tương thích OpenAI không?
Phần lớn giao diện chat thường dùng tương thích, nhưng vẫn có khác biệt về ràng buộc khu vực, thứ tự vai trò, phạm vi tham số và giới hạn gọi công cụ. Nên kiểm chứng từng mục theo tài liệu tương thích OpenAI chính thức, đừng giả định mọi tham số hành xử giống nhau.
2. Trung Quốc đại lục và site quốc tế có dùng chung một khóa được không?
Không. Tài khoản, khóa, tên miền tích hợp và hóa đơn của hai site độc lập với nhau. Gọi khác khu vực hoặc khác site thường trả về 401 và invalid_api_key.
3. Nên dùng tên miền cũ hay tên miền riêng của không gian nghiệp vụ?
Kiểm thử nhanh có thể dùng tên miền chia sẻ cũ; môi trường sản xuất nên dùng tên miền riêng của không gian nghiệp vụ, thông lượng và cô lập lưu lượng tốt hơn. Điều quan trọng là khóa phải khớp khu vực và không gian nghiệp vụ của tên miền.
4. Tên mô hình đúng nhưng vẫn trả về model_not_found, vì sao?
Nguyên nhân thường gặp là khu vực đó không có mô hình này, mô hình chưa được mở, tên không khớp chữ hoa chữ thường, hoặc đang truy cập phiên bản đã ngừng cung cấp. Căn cứ danh sách mô hình hiện tại trong bảng điều khiển.
5. tools có dùng cùng stream được không?
Tài liệu tương thích chính thức hiện ghi hai bên không thể dùng đồng thời, và gọi công cụ chỉ được liệt kê hỗ trợ ở một số mô hình. Năng lực và giới hạn sẽ cập nhật theo mô hình; trước khi lên tuyến hãy kiểm thử với mô hình mục tiêu, hoặc chuyển sang giao diện gốc DashScope.
