GLM-5.3-Flash tương thích với OpenAI, có nghĩa là cách nhanh nhất để thực hiện một cuộc gọi thành công là trỏ một client bạn đã có đến một URL cơ sở khác và thay đổi một chuỗi. Phần thực sự mới là đầu vào hình ảnh: đây là mẫu GLM-5 đầu tiên chấp nhận hình ảnh trong cùng một yêu cầu với văn bản của bạn, và hình dạng payload gây khó khăn cho mọi người.
Hướng dẫn này bao gồm việc lấy khóa, thực hiện cuộc gọi văn bản, gửi hình ảnh, kiểm soát mức độ nỗ lực suy luận, truyền trực tuyến và gọi công cụ. Mỗi ví dụ đều sử dụng ID mô hình glm-5.3-flash.
Nếu bạn muốn biết thông tin cơ bản về mô hình này trước khi kết nối, hãy bắt đầu với bài giải thích GLM-5.3-Flash của chúng tôi. Nếu bạn đang chạy mô hình lớn hơn, hướng dẫn API GLM-5.3 bao gồm mô hình đó, và những khác biệt dưới đây là có thật: ID mô hình khác, bảng giá khác, và một đường dẫn hình ảnh mà GLM-5.3 không có sẵn một cách tự nhiên.
Lấy khóa API
Tạo tài khoản tại z.ai, mở phần khóa API trong bảng điều khiển và tạo một khóa. Đặt nó vào môi trường của bạn thay vì mã nguồn:
export ZAI_API_KEY="your-key-here"
URL cơ sở cho API tiêu chuẩn là:
https://api.z.ai/api/paas/v4/
Có một URL cơ sở riêng biệt được sử dụng bởi các điểm cuối của kế hoạch mã hóa, điều này quan trọng nếu bạn đang kết nối Claude Code hoặc Cline thay vì gọi trực tiếp API. Cài đặt đó được đề cập trong hướng dẫn Claude Code và Cline của chúng tôi.
Cuộc gọi đầu tiên của bạn
Vì điểm cuối tương thích với OpenAI, SDK OpenAI chính thức hoạt động mà không cần sửa đổi:
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["ZAI_API_KEY"],
base_url="https://api.z.ai/api/paas/v4/",
)
response = client.chat.completions.create(
model="glm-5.3-flash",
messages=[
{"role": "user", "content": "Giải thích KV cache là gì trong hai câu."}
],
)
print(response.choices[0].message.content)
Điều tương tự trong curl:
curl https://api.z.ai/api/paas/v4/chat/completions \
-H "Authorization: Bearer $ZAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3-flash",
"messages": [
{"role": "user", "content": "Giải thích KV cache là gì trong hai câu."}
]
}'
Và trong Node:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.ZAI_API_KEY,
baseURL: "https://api.z.ai/api/paas/v4/",
});
const response = await client.chat.completions.create({
model: "glm-5.3-flash",
messages: [
{ role: "user", content: "Giải thích KV cache là gì trong hai câu." },
],
});
console.log(response.choices[0].message.content);
Không có gì ở đây là đặc thù của GLM ngoại trừ URL cơ sở và chuỗi mô hình. Đó là mục đích của một giao diện tương thích với OpenAI, và đó là lý do tại sao việc hoán đổi mô hình đủ rẻ để thực sự đáng để thử nghiệm với khối lượng công việc của riêng bạn.
Gửi hình ảnh
Đây là phần không tồn tại đối với GLM-5.3. Đầu vào hình ảnh hoạt động thông qua các khối nội dung: thay vì content là một chuỗi đơn giản, nó trở thành một mảng các khối có kiểu.
response = client.chat.completions.create(
model="glm-5.3-flash",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Ảnh chụp màn hình này cho thấy một lỗi hiển thị. Bố cục có vấn đề gì?",
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/screenshots/broken-layout.png"
},
},
],
}
],
)
Ba quy tắc chi phối payload này:
Trường URL chấp nhận URL công khai hoặc URL dữ liệu base64. Nếu hình ảnh của bạn là cục bộ hoặc riêng tư, hãy mã hóa nó:
import base64
with open("broken-layout.png", "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
image_block = {
"type": "image_url",
"image_url": {"url": f"data:image/png;base64,{encoded}"},
}
Nhiều hình ảnh có nghĩa là nhiều khối. Không có lối tắt mảng-URL. Để so sánh một thiết kế với việc triển khai của nó, hãy gửi hai khối image_url trong cùng một mảng nội dung:
content = [
{"type": "text", "text": "Hình ảnh thứ hai có khớp với thiết kế trong hình ảnh đầu tiên không?"},
{"type": "image_url", "image_url": {"url": design_data_url}},
{"type": "image_url", "image_url": {"url": built_data_url}},
]
Thứ tự mang ý nghĩa. Mô hình đọc mảng nội dung theo trình tự, vì vậy hãy đặt văn bản định khung nhiệm vụ trước các hình ảnh mà nó đề cập. “So sánh hai cái này” theo sau là hai hình ảnh đọc tốt hơn là hai hình ảnh theo sau là một câu hỏi.
Tài liệu của Z.ai cũng liệt kê đầu vào video và tệp bằng cách sử dụng cùng cơ chế khối nội dung. Video là mới hơn và ít được sử dụng rộng rãi hơn đầu vào hình ảnh, vì vậy hãy xác thực nó với phương tiện của riêng bạn trước khi bạn xây dựng một tính năng dựa trên nó.
Để xử lý sâu hơn về mặt thị giác, bao gồm quy trình làm việc từ ảnh chụp màn hình sang mã và đặt hình ảnh cùng với một tài liệu dài trong cùng một cửa sổ 1 triệu token, hãy xem hướng dẫn thị giác GLM-5.3-Flash của chúng tôi.
Kiểm soát nỗ lực suy luận
GLM-5.3-Flash hiển thị ba chế độ suy nghĩ thông qua reasoning_effort:
response = client.chat.completions.create(
model="glm-5.3-flash",
messages=[{"role": "user", "content": "Tái cấu trúc hàm này để dễ hiểu hơn."}],
extra_body={"reasoning_effort": "low"},
)
Các giá trị được chấp nhận là low, high và max. Mặc định là max, điều này đáng để biết vì nó là chế độ tốn kém. Nếu bạn đang chạy phân loại hoặc trích xuất khối lượng lớn mà câu trả lời không cần cân nhắc kỹ lưỡng, việc đặt low một cách rõ ràng sẽ cắt giảm đáng kể số lượng token đầu ra của bạn.
Đây là một thay đổi so với GLM-5.2, chỉ hiển thị High và Max. Bậc low là mới, và đối với công việc hàng loạt nhạy cảm về chi phí, nó có lẽ là tham số hữu ích nhất trên mô hình.
Lưu ý rằng reasoning_effort nằm trong extra_body khi bạn sử dụng OpenAI Python SDK, vì nó không phải là một phần của schema OpenAI tiêu chuẩn. Trong curl thô, nó chỉ là một trường cấp cao nhất.
Các tham số lấy mẫu được khuyến nghị
Z.ai công bố các giá trị mặc định khác nhau tùy thuộc vào những gì bạn đang làm:
| Trường hợp sử dụng | nhiệt độ | top_p |
|---|---|---|
| Chung | 1.0 | 0.95 |
| Mã hóa | 0.95 | 1.0 |
Những giá trị này đủ gần nhau để sự khác biệt là không đáng kể đối với hầu hết các ứng dụng, nhưng nếu bạn đang nhận được đầu ra mã không nhất quán, cấu hình mã hóa là thứ đáng thử.
Truyền trực tuyến
Các ngữ nghĩa truyền trực tuyến OpenAI tiêu chuẩn được áp dụng:
stream = client.chat.completions.create(
model="glm-5.3-flash",
messages=[{"role": "user", "content": "Viết một tập lệnh bash để xoay vòng nhật ký."}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
Hãy đặt kỳ vọng ở đây. GLM-5.3-Flash tạo ra khoảng 49 token mỗi giây theo Artificial Analysis, chậm hơn so với phiên bản lớn hơn của nó là GLM-5.3 với khoảng 86. Thời gian phản hồi token đầu tiên tốt ở mức 1.52 giây, vì vậy phản hồi bắt đầu nhanh chóng và sau đó đến đều đặn chứ không phải nhanh chóng. Nếu bạn đang truyền trực tuyến đến giao diện người dùng, cấu hình đó là ổn. Nếu bạn đang tạo tài liệu dài trong một công việc hàng loạt, hãy cân nhắc ngân sách cho nó.
Gọi công cụ
Các công cụ sử dụng schema OpenAI tiêu chuẩn:
tools = [
{
"type": "function",
"function": {
"name": "get_deployment_status",
"description": "Trả về trạng thái hiện tại của một triển khai được đặt tên.",
"parameters": {
"type": "object",
"properties": {
"service": {
"type": "string",
"description": "Tên dịch vụ, ví dụ: 'checkout-api'.",
}
},
"required": ["service"],
},
},
}
]
response = client.chat.completions.create(
model="glm-5.3-flash",
messages=[{"role": "user", "content": "checkout-api có ổn không?"}],
tools=tools,
)
call = response.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)
Các điểm chuẩn tác nhân mà Z.ai đã công bố khi ra mắt rất tập trung vào việc sử dụng công cụ, với AutomationBench đạt 48.8 so với 26.2 của GLM-5.2. Đó là các con số của nhà cung cấp, nhưng hướng đi này phù hợp với việc mô hình được điều chỉnh cho các vòng lặp gọi công cụ hơn là trò chuyện một lượt.
Nếu bạn đang tạo các định nghĩa công cụ từ một API mà bạn đã sở hữu, bài đăng của chúng tôi về việc biến thông số kỹ thuật OpenAPI thành công cụ tác nhân bao gồm cách thực hiện mà không cần viết tay schema.
Xử lý lỗi đáng viết
Ba chế độ lỗi chiếm phần lớn các vấn đề sản xuất trên điểm cuối này.
Giới hạn tốc độ. Thử lại với hàm lùi lũy thừa và jitter. Khoảng thời gian thử lại cố định trên nhiều worker tạo ra các lần thử lại đồng bộ, đó là cách cổ điển để biến một giới hạn ngắn thành một giới hạn kéo dài.
import time, random
from openai import RateLimitError
def call_with_retry(**kwargs):
for attempt in range(5):
try:
return client.chat.completions.create(**kwargs)
except RateLimitError:
if attempt == 4:
raise
time.sleep((2 ** attempt) + random.random())
Tràn ngữ cảnh. Cửa sổ 1 triệu token đủ lớn để mọi người ngừng đếm, và sau đó một tài liệu dài cộng với một vài hình ảnh độ phân giải cao sẽ vượt qua nó. Hình ảnh tiêu tốn ngữ cảnh, và lỗi xuất hiện tại thời điểm yêu cầu thay vì khi bạn tập hợp lời nhắc. Theo dõi ngân sách token của bạn khi nhập vào.
Đầu ra bị cắt cụt. Nếu một phản hồi dừng giữa câu, hãy kiểm tra finish_reason trên lựa chọn. Giá trị length có nghĩa là bạn đã đạt đến giới hạn đầu ra, chứ không phải mô hình đã bỏ cuộc. Với việc con số đầu ra tối đa vẫn còn gây tranh cãi giữa các nguồn, điều này đáng để kiểm tra rõ ràng hơn là giả định.
Đọc mức sử dụng token
Mỗi phản hồi đều mang một đối tượng usage, và đó là nguồn đáng tin cậy duy nhất cho biết một cuộc gọi thực sự tốn bao nhiêu:
print(response.usage.prompt_tokens, response.usage.completion_tokens)
Đặc biệt chú ý đến số lượng hoàn thành. Với reasoning_effort ở mức mặc định max của nó, các token suy luận được tính phí như đầu ra, vì vậy một câu trả lời ngắn gọn có thể mang theo một số lượng hoàn thành lớn đằng sau nó. So sánh con số đó giữa các cấp độ nỗ lực trên các lời nhắc của riêng bạn là cách nhanh nhất để quyết định cài đặt nào bạn thực sự cần.
Chi phí
Giá niêm yết là 0.15 USD cho mỗi triệu token đầu vào, 0.50 USD cho mỗi triệu token đầu ra và 0.03 USD cho mỗi triệu token đầu vào được lưu vào bộ nhớ cache. Chương trình giảm giá ra mắt 50% kéo dài đến ngày 9 tháng 9 năm 2026, giảm một nửa các mức giá đó xuống còn 0.075 USD, 0.25 USD và 0.015 USD.
Giá khác nhau giữa các nhà bán lại. OpenRouter, Cloudflare Workers AI, Vercel AI Gateway, DeepInfra, và những nơi khác đều cung cấp mô hình này với mức giá riêng của họ. Phân tích chi phí của chúng tôi giải thích chi phí và những thay đổi khi chương trình giảm giá kết thúc. Xác minh bất kỳ con số nào với nhà cung cấp bạn thực sự sử dụng trước khi lập ngân sách dựa trên nó.
Kiểm tra tích hợp
Hai điều về API này gây khó chịu khi xác minh thủ công. Payload đa phương thức dài dòng, vì vậy một khối hình ảnh base64 trong lệnh curl rất khó viết và tệ hơn khi chạy lại. Và việc hoán đổi mô hình chính là loại thay đổi làm thay đổi hình dạng phản hồi một cách âm thầm.
Apidog xử lý cả hai. Lưu cuộc gọi văn bản, cuộc gọi hình ảnh và cuộc gọi công cụ dưới dạng một bộ sưu tập, đính kèm các xác nhận vào các trường phản hồi mà ứng dụng của bạn thực sự đọc, và lưu khóa API dưới dạng biến môi trường thay vì dán vào một shell. Khi chương trình giảm giá ra mắt kết thúc và bạn đang quyết định liệu có nên tiếp tục sử dụng Flash hay chuyển sang GLM-5.3, bạn có thể thay đổi ID mô hình ở một nơi và chạy lại bộ thử nghiệm đối với cả hai.
Điều đó biến một quá trình di chuyển mô hình thành một sự khác biệt mà bạn có thể nhìn thấy thay vì một điều bạn hy vọng sẽ hoạt động.
FAQ
ID mô hình chính xác là gì? glm-5.3-flash trên API của Z.ai. Trên OpenRouter là z-ai/glm-5.3-flash.
SDK OpenAI có thực sự hoạt động mà không cần thay đổi không? Có, đối với hoàn thành cuộc trò chuyện, truyền trực tuyến và gọi công cụ. Các tham số không chuẩn như reasoning_effort cần extra_body trong Python SDK.
Tôi có thể gửi bao nhiêu hình ảnh trong một yêu cầu? Nhiều hình ảnh, mỗi hình ảnh là một khối image_url riêng. Giới hạn thực tế đến từ ngân sách ngữ cảnh của bạn chứ không phải một số lượng cố định.
Tại sao phản hồi của tôi lại dài dòng và chậm chạp? reasoning_effort mặc định là max. Đặt nó thành low cho công việc không cần cân nhắc kỹ lưỡng.
Độ dài đầu ra tối đa là bao nhiêu? Các nguồn không đồng ý: OpenRouter liệt kê 131.072 token và thẻ Hugging Face chỉ ra 163.840. Hãy kiểm tra nhà cung cấp của bạn trước khi dựa vào việc tạo ra các thế hệ rất dài.