Chi phí tích hợp GLM API thấp hơn nhiều người tưởng: nó cung cấp giao diện tương thích OpenAI, SDK OpenAI 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à ở việc tên mô hình có hợp lệ không, xử lý truyền phát thế nào, gọi công cụ trả về định dạng gì, và khi di chuyển từ OpenAI thì tham số nào không thể bê nguyên.
Bài viết dùng một yêu cầu tối thiểu để chạy thông đường truyền, sau đó bổ sung truyền phát, gọi công cụ, xử lý lỗi và danh sách di chuyển. Mọi ví dụ đều có thể chạy trực tiếp sau khi thay khóa.
Lưu ý: Zhipu, GLM và BigModel là nhãn hiệu của chủ sở hữu tương ứng; 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 Zhipu. 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 nền tảng mở Zhipu 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, có loại khớp với giao diện cần gọi.
- Base URL đúng; địa chỉ chính thức và địa chỉ 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ếu là dự án mới, 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. Điền Base URL thế nào
Base URL của giao diện tương thích OpenAI chính thức của Zhipu thường được ghi là:
https://open.bigmodel.cn/api/paas/v4
Địa chỉ tương thích OpenAI của ZSQH AI Gateway là:
https://ai.zhongshangqihang.com/v1
Cả hai đều ghép theo đường dẫn /chat/completions của OpenAI. Lưu ý không ghép lặp đoạn phiên bản hoặc /chat/completions trong mã, cũng không tùy tiện thêm bớt dấu gạch chéo ở cuối rồi trộn lẫn.
| Cách tích hợp | Ví dụ Base URL | Tình huống phù hợp | Lưu ý |
|---|---|---|---|
| Zhipu chính thức | https://open.bigmodel.cn/api/paas/v4 |
Chỉ dùng GLM, cần tính năng mới nhất | Cần tài khoản chính thức và số dư |
| Cổng ZSQH | https://ai.zhongshangqihang.com/v1 |
Đầu mối đa mô hình thống nhất, hóa đơn thống nhất | Cần tạo khóa tại cổng |
3. Chọn tên mô hình
Dòng GLM được chia theo năng lực thành văn bản, thị giác, giọng nói, vector và các nhóm khác. Trong nhóm văn bản lại có nhiều bậc: có bậc thiên về hội thoại phổ thông và Agent, có bậc thiên về độ trễ thấp và đồng thời cao, có bậc hỗ trợ ngữ cảnh dài hơn. Lấy dòng GLM-5 hiện được tài liệu chính thức liệt kê làm ví dụ, các cách viết phổ biến gồm glm-5.3, glm-5.3-flash, glm-5.2; nhưng mô hình liên tục cập nhật, tên khả dụng thực tế căn cứ bảng điều khiển và 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 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.
Nếu nhiệm vụ liên quan hiểu hình ảnh, phải chọn mô hình hỗ trợ đầu vào thị giác; nếu liên quan truy xuất vector, dùng dòng embedding. Đường dẫn giao diện và tham số của mô hình văn bản, thị giác, vector không hoàn toàn giống nhau; đừng dùng cùng một thân yêu cầu áp cho tất cả. Trước khi lên tuyến, đưa các mô hình ứng viên vào cùng một bộ đánh giá, so sánh độ chính xác, độ trễ và mức dùng rồi mới quyết định mô hình chính và dự phòng.
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 GLM_API_KEY="your_key_here"
curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
-H "Authorization: Bearer $GLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3",
"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.6
}'
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à header trước; nếu trả về 1211, kiểm tra tên mô hình trước.
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 GLM, cách gọi cơ bản giống OpenAI:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("GLM_API_KEY"),
base_url="https://open.bigmodel.cn/api/paas/v4",
)
stream = client.chat.completions.create(
model="glm-5.3",
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,
)
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. Khi bật chế độ suy nghĩ, nội dung suy luận có thể xuất hiện ở trường reasoning_content, câu trả lời cuối vẫn ở content; cần xử lý tách biệt, tránh hiển thị trực tiếp quá trình suy luận cho người dùng cuối.
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 dưới dạng tin nhắn vai trò tool. Môi trường sản xuất phải kiểm tra tham số và kiểm soát thời gian chờ, không được tin tuyệt đối tham số do mô hình sinh.
Khi di chuyển từ OpenAI có vài khác biệt cần chú ý: phạm vi temperature thường từ 0 đến 1, truyền 0 có thể không có hiệu lực; giá trị mặc định khoảng 0,6; một số năng lực mới cần truyền qua extra_body. Tham số cụ thể căn cứ tài liệu tương thích OpenAI chính thức.
Trong tình huống truyền phát còn phải xử lý việc client ngắt kết nối. 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í; nếu nghiệp vụ bắt buộc sinh đầy đủ, hãy chuyển nhiệm vụ vào hàng đợi nền, đừng phụ thuộc kết nối frontend.
7. Đối chiếu lỗi thường gặp
| Hiện tượng | Nguyên nhân có thể | Cách xử lý |
|---|---|---|
| 401 / 1000 | Sai khóa, không khớp loại | Đối chiếu loại khóa và header |
| 1211 | Tên mô hình không tồn tại hoặc chưa mở | Xem mô hình khả dụng trong bảng điều khiển |
| 1261 | Đầu vào vượt giới hạn ngữ cảnh | Nén lời nhắc hoặc chia đoạn |
| 1302 / 1305 | Tài khoản bị giới hạn tốc độ hoặc nền tảng bận | Giảm đồng thời, thử lại có lùi |
| 1113 | Tài khoản chậm thanh toán | Nạp tiền rồi thử lại |
| Quá thời gian kết nối | DNS, proxy hoặc đường mạng | Dùng curl xác định lớp mạng trước |
Thử lại chỉ có hiệu quả với 429, 5xx và quá thời gian mạng. Các lỗi như 401, 1211, 1261 thử lại không tốt hơn mà còn lãng phí thời gian và hạn mức.
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 khóa riêng cho GLM, 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.
- Dùng cùng một bộ mẫu so sánh chất lượng đầu ra, độ trễ và mức dùng.
- Kiểm tra phân tích truyền phát, gọi công cụ và đầu ra JSON có tương thích khô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ộ.
9. Câu hỏi thường gặp (FAQ)
1. GLM API có hoàn toàn tương thích OpenAI không?
Phần lớn giao diện thường dùng tương thích, nhưng vẫn có khác biệt về phạm vi tham số, trường suy nghĩ và một số năng lực nâng cao. 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. Base URL có cần thêm dấu gạch chéo ở cuối không?
Tài liệu chính thức từng xuất hiện cả cách có và không có dấu gạch chéo; SDK thường tự xử lý. Điều quan trọng là không ghép lặp đường dẫn, chọn một cách viết và thống nhất trong dự án.
3. Truyền phát có lấy được quá trình suy luận không?
Một số mô hình ở chế độ suy nghĩ sẽ trả về reasoning_content. Có hiển thị hay không tùy thiết kế sản phẩm; với người dùng cuối thường chỉ hiển thị câu trả lời cuối.
4. Gọi công cụ có giống định dạng OpenAI không?
Định nghĩa công cụ và cấu trúc trả về cơ bản theo định dạng OpenAI, nhưng chi tiết tham số có thể thay đổi theo mô hình. Trước khi lên tuyến hãy chạy một vòng hồi quy với công cụ thật.
5. Tên mô hình của chính thức và cổng có giống nhau không?
Phần lớn trường hợp dùng cùng một bộ tên mô hình, nhưng việc cổng có mở một mô hình nào đó hoặc hỗ trợ một tham số nào đó phải căn cứ bảng điều khiển cổng và trang bảng giá mô hình.
