DEV Community: Sebastian Petrus

GLM-5.3-Flash Vision: Gửi Hình Ảnh Đến Mô Hình Ngữ Cảnh 1M

Sebastian Petrus — Thu, 27 Aug 2026 03:35:20 +0000

GLM-5.3-Flash: Kết hợp hình ảnh và ngữ cảnh 1M token

Hầu hết mô hình thị giác buộc bạn phải chọn: gửi một hình ảnh hoặc gửi nhiều văn bản. GLM-5.3-Flash không yêu cầu đánh đổi đó: nó nhận hình ảnh dưới dạng khối nội dung trong cùng yêu cầu với văn bản, bên trong cửa sổ ngữ cảnh 1.048.576 token.

Dùng thử Apidog ngay hôm nay

Sự kết hợp giữa đầu vào hình ảnh gốc và ngữ cảnh 1M token mở ra các quy trình làm việc mà từng khả năng riêng lẻ không thể đáp ứng.

Thị giác gốc, không qua bộ điều hợp

Các mô hình thị giác trước đây của Z.ai, như GLM-5V-Turbo và GLM-4.6V, dùng điểm cuối và ID mô hình riêng. GLM-5.3 lớn hơn định tuyến thị giác qua bộ điều hợp thay vì xử lý tự nhiên.

GLM-5.3-Flash là mô hình đầu tiên trong dòng GLM-5 coi hình ảnh là đầu vào hạng nhất: cùng một ID mô hình, dòng thanh toán, giới hạn tỷ lệ và cửa sổ ngữ cảnh cho cả văn bản lẫn hình ảnh.

Nếu bạn vẫn dùng đường dẫn cũ, hãy xem hướng dẫn GLM-5V-Turbo và hướng dẫn GLM-4.6V.

Tạo tải trọng đa phương thức

Thay vì content là chuỗi, hãy gửi một mảng khối nội dung:

from openai import OpenAI
import os

client = OpenAI(
    [REDACTED CREDENTIAL],
    base_url="https://api.z.ai/api/paas/v4/",
)

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What is wrong with this layout on mobile?"},
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/mobile-view.png"},
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)

Với ảnh cục bộ hoặc riêng tư, dùng URL dữ liệu base64:

import base64
from pathlib import Path

def image_block(path: str) -> dict:
    data = base64.b64encode(Path(path).read_bytes()).decode("utf-8")
    suffix = Path(path).suffix.lstrip(".").replace("jpg", "jpeg")
    return {
        "type": "image_url",
        "image_url": {"url": f"data:image/{suffix};base64,{data}"},
    }

Mỗi ảnh là một khối riêng:

content = [
    {
        "type": "text",
        "text": "Image 1 is the design. Image 2 is what we built. List the differences.",
    },
    image_block("design.png"),
    image_block("built.png"),
]

Thứ tự rất quan trọng. Đặt văn bản định khung trước ảnh, và gắn nhãn rõ ràng khi gửi nhiều ảnh để mô hình biết ảnh nào là thiết kế, ảnh nào là kết quả triển khai.

Thiết lập và xác thực cơ bản có trong hướng dẫn API GLM-5.3-Flash.

Quy trình làm việc nên triển khai

Gỡ lỗi ảnh chụp màn hình

Gửi ảnh kết xuất lỗi cùng mã nguồn tạo ra nó:

content = [
    {
        "type": "text",
        "text": "This component renders incorrectly below 400px. Here is the screenshot and the source.",
    },
    image_block("bug-mobile.png"),
    {"type": "text", "text": f"```
{% endraw %}
jsx\n{component_source}\n
{% raw %}
```"},
]

Mô hình có thể suy luận từ kết xuất thực tế thay vì mô tả bằng lời, giảm bước chuyển đổi vấn đề trực quan thành văn bản trong quá trình gỡ lỗi front-end.

So sánh thiết kế

Gửi ảnh thiết kế, ảnh triển khai và yêu cầu liệt kê khác biệt. Cách này hữu ích trong CI như một kiểm tra mềm cho hồi quy hình ảnh:

Công cụ so sánh ảnh cho biết pixel nào thay đổi.
Mô hình đánh giá liệu thay đổi đó có đáng chú ý hay không.
Con người nên quyết định cuối cùng; không nên chặn triển khai chỉ dựa vào đánh giá của mô hình.

Đối chiếu tài liệu với đặc tả

Đặt đặc tả dài dưới dạng văn bản và tạo phẩm đã kết xuất dưới dạng ảnh:

content = [
    {"type": "text", "text": f"Specification:\n\n{spec_text}"},
    {
        "type": "text",
        "text": "Below is the generated report. Does it satisfy every requirement above? List gaps.",
    },
    image_block("generated-report.png"),
]

Một đặc tả 40 trang cùng một hình ảnh trong một lời nhắc là trường hợp sử dụng thực tế của cửa sổ ngữ cảnh 1M token. Ghi chú phát hành của Z.ai cũng đề cập đến tài liệu văn phòng và nghiên cứu tài chính như các quy trình tác nhân mục tiêu.

Trích xuất biểu đồ và bảng điều khiển

Yêu cầu JSON có cấu trúc, rồi xác thực kết quả:

content = [
    {
        "type": "text",
        "text": "Extract the series in this chart as JSON: [{label, values: [...]}]. Return only JSON.",
    },
    image_block("quarterly.png"),
]

Xác thực theo lược đồ giúp bắt lỗi định dạng, nhưng không bảo đảm giá trị đọc từ biểu đồ là chính xác. Nếu số liệu quan trọng, hãy lấy từ dữ liệu nguồn thay vì ảnh. Với trích xuất tài liệu chuyên dụng, GLM-OCR để hiểu tài liệu có thể phù hợp hơn.

Video và tệp

Tài liệu của Z.ai liệt kê video và tệp cùng với hình ảnh, sử dụng cơ chế khối nội dung tương tự.

Tuy nhiên, hỗ trợ video còn mới, ít được sử dụng công khai và mức hỗ trợ có thể khác nhau giữa các nhà cung cấp API. Hãy kiểm thử trực tiếp với phương tiện và nhà cung cấp của bạn trước khi thiết kế ứng dụng dựa trên khả năng này.

Các hạn chế cần thiết kế phòng vệ

Số liệu từ biểu đồ. Mô hình có thể trả lời trôi chảy, đúng cấu trúc nhưng sai giá trị. Dùng dữ liệu gốc khi độ chính xác là bắt buộc.

Văn bản nhỏ. Ảnh giao diện dày đặc, bảng độ phân giải thấp và mã trong ảnh nén dễ giảm chất lượng. Hãy cắt vùng cần xem thay vì thu nhỏ toàn ảnh.

Độ chính xác không gian. Mô hình thường phát hiện được “nút chồng lên ô nhập liệu”, nhưng không đáng tin cậy với nhận định như “nút lệch trái 12 pixel”.

Nhầm lẫn thứ tự và tham chiếu. Khi có nhiều ảnh, mô hình có thể gán chi tiết cho nhầm ảnh. Gắn nhãn ảnh rõ ràng và giữ số lượng ảnh thấp khi cần độ chính xác.

Đây là các giới hạn phổ biến của mô hình ngôn ngữ thị giác. Điểm Chỉ số Thông minh 57 không loại bỏ chúng. Hãy thiết kế quy trình để câu trả lời sai được phát hiện trước khi bị thực thi.

Chi phí

Hình ảnh tiêu thụ token đầu vào và không có phụ phí hình ảnh riêng.

Giá niêm yết là 0,15 USD cho mỗi triệu token đầu vào, hoặc 0,075 USD trong thời gian ưu đãi ra mắt đến ngày 9 tháng 9 năm 2026. Ảnh độ phân giải cao dùng nhiều token hơn, nên hãy giảm kích thước nếu chi tiết nhỏ không phải mục tiêu.

reasoning_effort mặc định là max và được tính phí như token đầu ra. Với tác vụ trích xuất trực tiếp, low thường đủ và rẻ hơn. Xem thêm bảng phân tích giá GLM-5.3-Flash.

Kiểm soát chi phí ảnh

Cắt trước khi đổi kích thước: gửi vùng liên quan ở độ phân giải đầy đủ thay vì toàn bộ ảnh ở độ phân giải thấp.
Khớp độ phân giải với câu hỏi: kiểm tra bố cục có thể dùng ảnh nhỏ hơn; đọc thông báo lỗi cần ảnh rõ nét.
Không gửi lại ảnh không đổi: trong cuộc trò chuyện nhiều lượt, ảnh đã nằm trong ngữ cảnh không cần đính kèm lại.
**Chọn `reasoning_eff đợi cố định.
Xác thực đầu ra có cấu trúc bằng lược đồ thay vì chỉ kiểm tra bằng mắt.

Apidog hỗ trợ lưu tải trọng ảnh trong yêu cầu đã lưu, dùng biến môi trường cho khóa API và thêm assertion cho JSON trả về. Khi đổi mô hình hoặc nhà cung cấp cập nhật dịch vụ, chạy lại bộ kiểm thử sẽ cho biết đường dẫn thị giác còn hoạt động đúng hay không.

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

GLM-5.3 có hỗ trợ hình ảnh không? Không phải gốc. GLM-5.3 định tuyến thị giác qua bộ điều hợp riêng; Flash là mô hình đa phương thức gốc. Xem so sánh GLM-5.3-Flash và GLM-5.3.

Mỗi yêu cầu gửi được bao nhiêu ảnh? Nhiều ảnh, mỗi ảnh là một khối image_url riêng. Giới hạn thực tế là ngân sách ngữ cảnh.

Dùng URL hay base64? Cả hai đều hoạt động. Dùng URL công khai cho ảnh đã lưu trữ và truy cập được; dùng base64 cho ảnh cục bộ hoặc riêng tư.

Có chấp nhận video không? Z.ai có tài liệu về đầu vào video, nhưng khả năng này còn mới. Hãy xác minh với phương tiện và nhà cung cấp của bạn trước.

Ảnh có bị tính phí riêng không? Không. Ảnh tiêu thụ token đầu vào, nên độ phân giải ảnh ảnh hưởng trực tiếp đến chi phí.

Giá GLM-5.3-Flash: Chi Phí Trước và Sau Ưu Đãi Ra Mắt

Sebastian Petrus — Thu, 27 Aug 2026 03:34:17 +0000

GLM-5.3-Flash hiện được giảm giá 50%. Ưu đãi kết thúc vào ngày 9 tháng 9 năm 2026; sau đó, mọi dự báo chi phí dựa trên giá hiện tại sẽ tăng gấp đôi.

Bài viết này phân tích giá hiện tại, giá niêm yết sau ưu đãi, các lựa chọn thay thế và cách xác định mức chênh lệch có ảnh hưởng thực tế đến khối lượng công việc của bạn hay không. Các số liệu được xác minh ngày 27 tháng 8 năm 2026. Giá nhà cung cấp có thể thay đổi, vì vậy hãy kiểm tra lại trước khi cam kết ngân sách.

Hãy thử Apidog ngay hôm nay

Biểu giá

	Giá ra mắt (đến hết 9 tháng 9, 2026)	Giá niêm yết (sau đó)
Đầu vào	$0.075 / 1M tokens	$0.15 / 1M tokens
Đầu ra	$0.25 / 1M tokens	$0.50 / 1M tokens
Đầu vào được lưu trữ (cache)	$0.015 / 1M tokens	$0.03 / 1M tokens

Artificial Analysis công bố mức trung bình $0.10 cho mỗi triệu token, dựa trên tỷ lệ cache-input-output là 7:2:1. Đây là một con số hữu ích để so sánh, nhưng tỷ lệ token thực tế của bạn mới quyết định hóa đơn.

Chi phí thực tế

Giá trên mỗi triệu token khó hình dung, vì vậy dưới đây là ba ví dụ sử dụng giá niêm yết—mức cần dùng để lập kế hoạch sau ngày 9 tháng 9.

Bộ phân loại hỗ trợ

100.000 yêu cầu mỗi tháng.
Mỗi yêu cầu: khoảng 800 token đầu vào và 100 token đầu ra.
Tổng cộng: 80 triệu token đầu vào và 10 triệu token đầu ra.
Chi phí: $12 đầu vào + $5 đầu ra = $17 mỗi tháng.

Đặt reasoning_effort thành low có thể tiếp tục giảm chi phí đầu ra.

Trợ lý lập trình

500 phiên mỗi ngày.
Mỗi phiên: khoảng 15.000 token đầu vào, chủ yếu là ngữ cảnh tệp lặp lại, và 2.000 token đầu ra.
Tổng hàng tháng: 225 triệu token đầu vào và 30 triệu token đầu ra.
Không dùng cache: $33,75 + $15 = $48,75 mỗi tháng.
Nếu 70% đầu vào được cache: chi phí đầu vào giảm còn khoảng $14,85, đưa tổng chi phí xuống khoảng $30 mỗi tháng.

Hệ thống xử lý tài liệu có hình ảnh

10.000 tài liệu mỗi tháng.
Mỗi tài liệu: khoảng 40.000 token đầu vào, bao gồm nội dung hình ảnh, và 1.500 token đầu ra.
Tổng cộng: 400 triệu token đầu vào và 15 triệu token đầu ra.
Chi phí: $60 + $7,50 = $67,50 mỗi tháng.

Không có con số nào quá lớn. Đó chính là mục tiêu của mô hình này.

Cache là đòn bẩy lớn nhất

Với giá $0,03 cho mỗi triệu token so với $0,15 cho đầu vào mới, token được cache chỉ tốn một phần năm chi phí.

Các khối lượng công việc có những thành phần ổn định như:

Tiền tố lời nhắc.
System prompt.
Tài liệu được truy vấn lặp lại.
Cơ sở mã luôn nằm trong ngữ cảnh.

nên được cấu trúc sao cho phần tiền tố này giữ nguyên giữa các lần gọi.

Sai lầm phổ biến làm giảm tỷ lệ cache là đặt nội dung thay đổi ở đầu lời nhắc. Một dấu thời gian, request ID hoặc tên người dùng trong system prompt có thể làm mất hiệu lực cache của mọi nội dung phía sau.

Quy tắc thực tế: đặt nội dung ổn định trước, nội dung thay đổi ở cuối.

Z.ai cũng từng niêm yết cache input miễn phí trong một khoảng thời gian giới hạn. Hãy xem đây là chương trình khuyến mãi và xác minh điều khoản hiện tại, thay vì xây dựng kiến trúc phụ thuộc vào nó.

Đòn bẩy thứ hai: nỗ lực suy luận

reasoning_effort mặc định trên mô hình này là max—chế độ tốn kém nhất. Nếu không thiết lập tham số, bạn sẽ dùng mức này.

Ba chế độ hiện có:

low
high
max

Token suy luận được tính phí như token đầu ra. Vì vậy, một tác vụ không cần suy nghĩ nhiều vẫn có thể phát sinh chi phí cho những token mà người dùng không nhìn thấy.

Đối với phân loại, trích xuất, định tuyến và định dạng, low thường là lựa chọn đầu tiên nên thử. Đây là thay đổi chỉ cần một dòng code và có thể giảm đáng kể chi phí đầu ra.

Xem cách thiết lập trong hướng dẫn API của chúng tôi.

So sánh với các mô hình khác

So với mô hình “anh em” GLM-5.3, giá niêm yết trung bình là:

Mô hình	Trung bình trên 1 triệu token
GLM-5.3-Flash	$0,10
GLM-5.3	$0,90

GLM-5.3 đắt hơn khoảng chín lần cho chênh lệch ba điểm trên Chỉ số Trí tuệ của Artificial Analysis: 57 so với 60.

Bài so sánh đầy đủ của chúng tôi phân tích khi nào mức đánh đổi này không phù hợp. Tóm lại: GLM-5.3 có thể đáng chọn khi bạn truyền phản hồi dài đến người dùng đang chờ, vì tốc độ tạo token gần như nhanh gấp đôi.

So với GLM-5.2, Z.ai tuyên bố GLM-5.3-Flash có chi phí chỉ bằng khoảng một phần mười, với chi phí mỗi tác vụ là $0,045. Phân tích giá GLM-5.2 của chúng tôi cung cấp biểu giá cũ nếu bạn đang lập ngân sách cho việc di chuyển.

So với các mô hình đa phương thức giá rẻ từ nhà cung cấp khác, GLM-5.3-Flash có giá cạnh tranh và nổi bật nhờ giấy phép MIT, khiến tùy chọn tự host vẫn khả thi. Bài viết về giá Gemini 3.7 Flash đề cập đến lựa chọn tương đương gần nhất từ Google.

Giá giữa các nhà phân phối có thể khác nhau

GLM-5.3-Flash được cung cấp trực tiếp qua Z.ai, cũng như:

OpenRouter
Cloudflare Workers AI
Vercel AI Gateway
DeepInfra
Novita
GMICloud
Baseten
io.net

Các nhà cung cấp này không áp dụng cùng một mức giá. Ví dụ, AIHubMix niêm yết khoảng $0,113 cho đầu vào và $0,394 cho đầu ra—nằm giữa giá khuyến mãi và giá niêm yết của Z.ai. Một số nhà cung cấp có ưu đãi ra mắt, số khác thì không.

Nếu định tuyến qua một aggregator, hãy kiểm tra bảng giá của chính aggregator đó thay vì mặc định rằng nó phản ánh giá Z.ai. Cổng thống nhất có thể đi kèm biên lợi nhuận, và ở mức giá thấp như hiện nay, phần tăng thêm rất dễ bị bỏ qua.

Khi nào tự host có lợi?

Weights của mô hình được cấp phép MIT, vì vậy tự chạy mô hình là một lựa chọn thực tế. Tuy nhiên, giá API thấp khiến điểm hòa vốn khó đạt hơn.

Một ước tính sơ bộ:

Full-precision serving cần một node lớp H200 với 8 GPU.
Chi phí thuê cloud khoảng $24–$48 mỗi ngày.
Tương đương khoảng $1.000 mỗi tháng, bất kể node đang bận hay rảnh.

Với giá API niêm yết, $1.000 có thể mua khoảng 6,7 tỷ token đầu vào. Bạn cần khối lượng sử dụng rất lớn và liên tục trước khi chi phí cố định của một node vượt qua mức này.

Với phần lớn đội nhóm, tự host GLM-5.3-Flash phù hợp hơn vì:

Kiểm soát hạ tầng.
Yêu cầu lưu trú dữ liệu.
Điều kiện cấp phép.

Ngoại lệ là các phiên bản lượng tử hóa. GGUF đã có sẵn, và nếu chạy mô hình lượng tử hóa trên phần cứng bạn sở hữu, chi phí biên chủ yếu chỉ còn tiền điện. Hướng dẫn chạy cục bộ của chúng tôi phân tích khả năng của từng cấp phần cứng.

Lựa chọn khác: gói lập trình

Nếu bạn dùng mô hình với Claude Code hoặc Cline thay vì gọi API từ ứng dụng, định giá theo token có thể không phải mô hình phù hợp.

GLM Coding Plan bắt đầu từ khoảng $18 mỗi tháng, bao gồm GLM-5.3-Flash và được cho là cung cấp gấp ba hạn mức sử dụng so với GLM-5.3. Tài liệu Z.ai cũng cho biết các cuộc gọi ngoài giờ cao điểm tiêu thụ một nửa số điểm tiêu chuẩn.

Với một nhà phát triển sử dụng hàng ngày, gói cố định thường rẻ hơn và dễ dự đoán hơn API tính theo mức sử dụng.

Theo dõi chi phí đầu ra

Đầu vào thường thu hút nhiều chú ý hơn vì số lượng token lớn, nhưng đầu ra mới là nơi ngân sách dễ vượt dự kiến:

Đầu ra có giá cao hơn ba lần đầu vào: $0,50 so với $0,15 cho mỗi triệu token.
Token suy luận cũng được tính như đầu ra.

Một mô hình ở chế độ max có thể tạo ra nhiều token suy luận hơn đáng kể so với phần câu trả lời cuối cùng mà người dùng nhìn thấy. Vì vậy, ứng dụng có prompt ngắn nhưng phản hồi dài có thể phát sinh phần lớn chi phí từ đầu ra.

Mức trung bình $0,10 cho mỗi triệu token giả định tỷ lệ 7:2:1, nhưng nhiều khối lượng công việc thực tế không tuân theo tỷ lệ này.

Hãy đo lường thay vì ước tính. Mỗi phản hồi hoàn thành có đối tượng usage chứa số token của lần gọi đó. Bạn nên:

Ghi lại dữ liệu usage.
Tổng hợp theo ngày hoặc theo khối lượng công việc.
So sánh tỷ lệ thực tế với giả định ngân sách.
Điều chỉnh reasoning_effort và độ dài prompt dựa trên dữ liệu.

Nếu đầu ra chiếm khoảng 15% tổng số token, hãy kiểm tra reasoning_effort trước, sau đó tối ưu độ dài lời nhắc.

Việc cần làm trước ngày 9 tháng 9

1. Đo hỗn hợp token thực tế

Mức trung bình được giả định là 7:2:1. Nếu khối lượng công việc của bạn nặng về đầu ra, chi phí hiệu dụng sẽ gần $0,50 cho mỗi triệu token hơn là mức trung bình $0,10.

2. Kiểm tra tỷ lệ cache

Chênh lệch giá giữa input mới và input được cache là 5 lần. Đây là một trong những nơi có tiềm năng tiết kiệm lớn nhất.

3. Tính lại ngân sách theo giá niêm yết

Từ ngày 10 tháng 9, các mức giá sẽ tăng gấp đôi. Nếu một khối lượng công việc chỉ có lợi nhuận ở mức giá khuyến mãi, hãy xử lý vấn đề ngay bây giờ.

Để thu thập dữ liệu thực tế, hãy chạy các lệnh gọi đại diện dưới dạng collection đã lưu trong Apidog, sử dụng model ID từ biến môi trường. Đối tượng usage của mỗi phản hồi sẽ cung cấp số lượng token đầu vào, đầu ra và cache, đồng thời cho phép bạn chạy lại cùng một bộ kiểm thử với GLM-5.3 để so sánh hóa đơn thực tế thay vì chỉ dựa vào thông tin quảng cáo.

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

GLM-5.3-Flash có miễn phí không?

Không. Mô hình từng miễn phí khoảng một tuần khi chạy ẩn danh dưới tên “ox-alpha” trước khi ra mắt, nhưng chương trình đó đã kết thúc. Mức giảm giá 50% hiện tại không đồng nghĩa với miễn phí.

Chương trình giảm giá kết thúc chính xác khi nào?

Ngày 9 tháng 9 năm 2026. Giá niêm yết sẽ được áp dụng từ thời điểm đó.

Vì sao các website niêm yết giá khác nhau?

Một số hiển thị giá khuyến mãi, một số hiển thị giá niêm yết, còn các nhà phân phối tự đặt biên lợi nhuận. Hãy kiểm tra đúng nhà cung cấp mà ứng dụng của bạn thực sự gọi.

Đầu vào hình ảnh có tốn thêm phí không?

Hình ảnh tiêu thụ token ngữ cảnh và được tính như đầu vào. Không có phụ phí hình ảnh riêng, nhưng hình ảnh độ phân giải cao có thể tiêu thụ đáng kể token.

Tự host có rẻ hơn không?

Chỉ khi bạn có khối lượng sử dụng rất lớn và liên tục, hoặc chạy phiên bản lượng tử hóa trên phần cứng sẵn có. Với giá $0,15 cho mỗi triệu token đầu vào, việc thuê node H200 8 GPU rất khó biện minh chỉ dựa trên chi phí.

So sánh GLM-5.3-Flash và GLM-5.3: Bạn nên dùng phiên bản nào?

Sebastian Petrus — Thu, 27 Aug 2026 03:32:56 +0000

Z.ai đang bán hai mô hình gần như cùng tên, đều có cửa sổ ngữ cảnh 1M token nhưng giá chênh lệch gấp chín lần. Đừng chọn theo tên: GLM-5.3-Flash rẻ hơn, hỗ trợ hình ảnh nguyên bản và có hạn mức Gói Coding gấp 3 lần; GLM-5.3 mạnh hơn một chút về suy luận và tạo đầu ra nhanh gần gấp đôi.

Thử Apidog ngay hôm nay

Với đa số khối lượng công việc, hãy chọn Flash trước. Chỉ chọn GLM-5.3 khi bạn cần suy luận ổn định hơn hoặc đang stream đầu ra dài cho người dùng đang chờ.

So sánh nhanh

	GLM-5.3-Flash	GLM-5.3
Chỉ số thông minh (Artificial Analysis)	57	60
Giá trung bình / 1M token	$0.10	$0.90
Giá niêm yết input / output / 1M token	$0.15 / $0.50	$1.40 / $4.40
Tốc độ đầu ra	~49 token/giây	~86 token/giây
Thời gian đến token đầu tiên	1,52 giây	1,57 giây
Cửa sổ ngữ cảnh	1.048.576 token	1.048.576 token
Đầu vào hình ảnh nguyên bản	Có	Không, dùng bộ điều hợp
Tham số	320B tổng / 18B hoạt động	Lớn hơn, chưa công bố đầy đủ
Giấy phép	MIT, trọng số mở	Trọng số mở
Hạn mức Gói Coding	Gấp 3 lần	Gấp 1 lần

Số liệu tốc độ và chỉ số thông minh do Artificial Analysis đo lường. Giá là giá niêm yết của Z.ai, chưa tính ưu đãi ra mắt.

Vì sao Flash rẻ hơn 9 lần?

GLM-5.3-Flash là mô hình mixture-of-experts 320B, chỉ kích hoạt 18B tham số trên mỗi token. Kiến trúc chú ý lai tuyến tính và thưa thớt giúp Flash dùng ít tài nguyên chú ý hơn khoảng 3 lần và có KV cache nhỏ hơn khoảng 4,4 lần so với GLM-5.3, theo Z.ai.

KV cache nhỏ hơn đặc biệt quan trọng khi phục vụ ngữ cảnh dài. Đây là lý do Flash vẫn hỗ trợ 1M token nhưng có giá thấp hơn nhiều: chi phí phục vụ mỗi yêu cầu thực sự nhỏ hơn, không phải do cắt ngữ cảnh hoặc đơn giản hóa mô hình.

Chênh 3 điểm chỉ số có ý nghĩa gì?

57 so với 60 là khoảng cách nhỏ, nhất là khi mô hình trọng số mở trung bình cùng quy mô chỉ đạt khoảng 27 điểm. Tuy vậy, chênh lệch thường xuất hiện ở:

Chuỗi suy luận nhiều bước.
Tác vụ tác nhân dài và phức tạp.
Hướng dẫn mơ hồ hoặc thiếu ngữ cảnh.
Nội dung cần người đọc đánh giá trực tiếp.

Với trích xuất, phân loại, định tuyến, tóm tắt hoặc chỉnh sửa mã một tệp, sự khác biệt thường không đáng kể.

Một quy tắc đơn giản:

Có thể kiểm thử đầu ra bằng chương trình: ưu tiên Flash. Bạn có thể phát hiện lỗi và thử lại với chi phí thấp hơn nhiều.
Con người phải đánh giá chất lượng đầu ra: GLM-5.3 có thể đáng giá hơn nếu chất lượng suy luận ảnh hưởng trực tiếp đến kết quả.

Flash không nhanh hơn

Tên “Flash” dễ gây hiểu nhầm. GLM-5.3 tạo khoảng 86 token/giây, gần gấp đôi Flash với khoảng 49 token/giây. Thời gian đến token đầu tiên gần như giống nhau, nên phản hồi ngắn sẽ có cảm giác nhanh tương đương.

Tác động phụ thuộc vào độ dài đầu ra:

Phản hồi ngắn: gần như không khác biệt.
**Đầu ra 4.000 [REDACTED CREDENTIAL] Flash mất khoảng 82 giây; GLM-5.3 mất khoảng 47 giây.
Xử lý theo lô: Flash thường vẫn phù hợp hơn vì mức giá thấp cho phép chạy nhiều yêu cầu song song hơn.

Nếu đang stream câu trả lời dài cho người dùng, GLM-5.3 mang lại trải nghiệm tốt hơn. Đây là lý do rõ ràng nhất để trả thêm tiền.

Đa phương thức: lý do quyết định chọn Flash

GLM-5.3-Flash nhận hình ảnh, video và tệp trực tiếp trong cùng yêu cầu chat completion. GLM-5.3 không hỗ trợ thị giác nguyên bản mà dựa vào bộ điều hợp riêng.

Nếu ứng dụng cần đọc ảnh, kiểm tra giao diện, phân tích video hoặc đối chiếu tệp đặc tả với ảnh chụp sản phẩm, hãy dùng Flash. Bạn có thể đặt tài liệu dài, ảnh kết quả và yêu cầu kỹ thuật trong cùng một ngữ cảnh 1M token.

Xem hướng dẫn thị giác GLM-5.3-Flash để biết cấu trúc tải trọng và quy trình triển khai. Nếu đang duy trì hệ thống cũ, tham khảo hướng dẫn API GLM-5V-Turbo.

Gói Coding: Flash thường là lựa chọn mặc định

Trong Gói Coding GLM, Flash được báo cáo có hạn mức sử dụng gấp 3 lần GLM-5.3. Z.ai cũng cho biết yêu cầu ngoài giờ cao điểm chỉ tiêu thụ một nửa số điểm tiêu chuẩn.

Nếu dùng Claude Code hoặc Cline, hãy phân luồng:

Dùng Flash cho tác vụ thường ngày, khối lượng lớn và có thể kiểm thử.
Leo thang sang GLM-5.3 cho lỗi khó, suy luận dài hoặc đầu ra cần chất lượng cao hơn.
Xác minh hạn mức hiện tại trên Z.ai trước khi lập kế hoạch sử dụng.

Xem hướng dẫn thiết lập trong Claude Code và Cline với GLM-5.3-Flash.

Ưu đãi giá đến ngày 09/09/2026

Ưu đãi ra mắt giảm 50% cho GLM-5.3-Flash kéo dài đến hết ngày 09 tháng 9 năm 2026. Trong thời gian này, giá hiệu dụng là:

Input: $0.075 / 1M token
Output: $0.25 / 1M token

Điều này làm Flash rẻ hơn GLM-5.3 khoảng 18 lần. Sau ưu đãi, giá trở về $0.15 input và $0.50 output trên mỗi 1M token, tương đương chênh lệch khoảng 9 lần.

Ưu đãi quan trọng khi dự báo ngân sách, nhưng không thay đổi khuyến nghị cơ bản: Flash vẫn rẻ hơn đáng kể. Xem các số liệu chi tiết trong phân tích giá GLM-5.3-Flash.

Quy tắc chọn mô hình

Dùng GLM-5.3-Flash khi

Đầu vào có hình ảnh, video hoặc tệp.
Chi phí mỗi token là yếu tố cần tối ưu.
Bạn chạy trích xuất, phân loại hoặc định tuyến ở quy mô lớn.
Bạn muốn kéo dài hạn mức Gói Coding.
Bạn cần trọng số mở theo giấy phép MIT để tự lưu trữ.

Hướng dẫn chạy GLM-5.3-Flash cục bộ có yêu cầu phần cứng.

Dùng GLM-5.3 khi

Bạn stream đầu ra dài cho người dùng đang chờ.
Công việc cần suy luận dài hạn qua nhiều bước.
Chất lượng đầu ra do con người đánh giá thay vì kiểm thử tự động.

Dùng cả hai khi

Bạn có thể định tuyến theo loại tác vụ hoặc độ tin cậy:

Gửi phần lớn lưu lượng sang Flash.
Chuyển sang GLM-5.3 khi đầu ra lỗi, độ tin cậy thấp hoặc tác vụ thuộc nhóm suy luận khó.

Cả hai cùng dùng điểm cuối tương thích OpenAI, nên định tuyến chủ yếu là đổi model ID thay vì xây tích hợp mới.

Di chuyển từ GLM-5.3 sang Flash

Phần cơ học rất đơn giản. Điều cần đầu tư là xác thực trên dữ liệu thật.

Không thay đổi:

Base URL
Lược đồ xác thực
Hình dạng request và response
Streaming
Tool calling

Thay đổi:

Chi phí mỗi cuộc gọi giảm khoảng 9 lần.
Tốc độ tạo đầu ra giảm gần một nửa.
Chỉ số suy luận thấp hơn 3 điểm.
Có thêm đầu vào hình ảnh nguyên bản.

Trước khi chuyển toàn bộ lưu lượng, chạy prompt thực tế trên cả hai mô hình và so sánh:

Tính đúng đắn ở các trường hợp có thể kiểm thử.
Độ trễ end-to-end, không chỉ thời gian đến token đầu tiên.
Số token trong đối tượng usage.
Hành vi trên ngữ cảnh dài nhất của bạn.

Điểm cuối cùng thường quan trọng nhất. Hai mô hình có thể tương đương với prompt ngắn nhưng khác biệt đáng kể khi ngữ cảnh gần đầy.

Nếu cần bắt đầu từ mô hình cơ sở, đọc GLM-5.3 là gì và hướng dẫn API GLM-5.3.

Kiểm thử trên lưu lượng thật

Đừng chỉ tin bảng benchmark. Trỏ client tương thích OpenAI tới:

https://api.z.ai/api/paas/v4/

Sau đó chạy cùng tập prompt qua:

glm-5.3-flash
glm-5.3

So sánh đầu ra, độ trễ và lượng token trên chính lưu lượng bạn quan tâm. Hướng dẫn API GLM-5.3-Flash có phần thiết lập.

Trong Apidog, hãy lưu hai request trong cùng một collection, dùng biến môi trường cho model ID, thêm assertion cho các trường ứng dụng thực sự sử dụng, rồi chạy lại bộ kiểm thử khi ưu đãi hết hạn hoặc Z.ai phát hành bản sửa đổi mới.

FAQ

GLM-5.3-Flash có phải chỉ là GLM-5.3 nhỏ hơn không?

Không. Đây là mô hình cơ sở được huấn luyện riêng với kiến trúc chú ý khác, không phải phiên bản bị rút gọn.

Hai mô hình có cùng cửa sổ ngữ cảnh không?

Có. Cả hai đều hỗ trợ 1.048.576 token.

Mô hình nào tốt hơn cho lập trình?

Theo Z.ai, Flash đạt 84.3 trên Terminal-Bench 2.1 và 63.4 trên DeepSWE. GLM-5.3 nhỉnh hơn một chút về suy luận tổng quát. Với người dùng Gói Coding, hạn mức gấp 3 lần của Flash thường là yếu tố quyết định.

Có thể chuyển đổi mà không thay đổi mã không?

Có. Cả hai dùng cùng điểm cuối tương thích OpenAI; chỉ model ID khác nhau. Đầu vào hình ảnh là tính năng riêng của Flash.

Flash có giữ giá rẻ lâu dài không?

Lợi thế giá đến từ KV cache nhỏ hơn và chi phí chú ý thấp hơn, không chỉ từ khuyến mãi. Tuy nhiên, ưu đãi giảm 50% bổ sung sẽ hết hạn vào ngày 09 tháng 9 năm 2026.

Cách sử dụng API GLM-5.3-Flash (Với đầu vào hình ảnh)

Sebastian Petrus — Thu, 27 Aug 2026 03:31:52 +0000

Cách dùng API GLM-5.3-Flash: văn bản, hình ảnh, streaming và công cụ

GLM-5.3-Flash tương thích với OpenAI: chỉ cần trỏ client hiện có sang URL cơ sở mới và đổi ID mô hình. Điểm khác biệt quan trọng là đầu vào hình ảnh—mô hình GLM-5 đầu tiên nhận hình ảnh và văn bản trong cùng một yêu cầu.

Dùng thử Apidog ngay hôm nay

Bài này hướng dẫn lấy khóa API, gọi văn bản, gửi hình ảnh, điều chỉnh suy luận, streaming, gọi công cụ, xử lý lỗi và kiểm soát chi phí. Mọi ví dụ dùng glm-5.3-flash.

Tìm hiểu thêm trước khi tích hợp:

GLM-5.3-Flash là gì?
Hướng dẫn API GLM-5.3 cho mô hình lớn hơn

Lấy khóa API

Tạo tài khoản tại z.ai, mở mục API key trong dashboard và tạo khóa. Đặt khóa trong biến môi trường, không đưa vào mã nguồn:

export ZAI_API_KEY="your-key-here"

URL cơ sở của API tiêu chuẩn:

https://api.z.ai/api/paas/v4/

Nếu kết nối Claude Code hoặc Cline, hãy dùng URL cơ sở dành cho coding plan theo hướng dẫn Claude Code và Cline.

Thực hiện cuộc gọi đầu tiên

SDK OpenAI hoạt động trực tiếp với URL cơ sở mới.

Python

from openai import OpenAI
import os

client = OpenAI(
    [REDACTED CREDENTIAL],
    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)

cURL

curl https://api.z.ai/api/paas/v4/chat/completions \
  -H "[REDACTED CREDENTIAL] $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."}
    ]
  }'

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  [REDACTED CREDENTIAL],
  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);

Ngoài base_url và model, đây là API OpenAI tiêu chuẩn. Vì vậy, bạn có thể thử nghiệm việc chuyển đổi mô hình với chi phí tích hợp thấp.

Gửi hình ảnh

Khác với GLM-5.3, GLM-5.3-Flash nhận hình ảnh thông qua mảng khối nội dung. content không còn là một chuỗi đơn lẻ:

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"
                    },
                },
            ],
        }
    ],
)

Quy tắc payload đa phương thức

Dùng URL công khai hoặc URL dữ liệu Base64. Với ảnh cục bộ hoặc riêng tư, hãy mã hóa Base64:

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}"},
}

Mỗi ảnh là một khối image_url. Để so sánh thiết kế và bản triển khai:

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ự có ý nghĩa. Đặt hướng dẫn văn bản trước ảnh liên quan. Ví dụ, câu hỏi “So sánh hai cái này” nên đứng trước hai khối hình ảnh.

Tài liệu của Z.ai cũng hỗ trợ video và tệp theo cơ chế content block. Hãy xác thực bằng dữ liệu thực tế trước khi xây dựng tính năng phụ thuộc vào đầu vào video.

Để xem quy trình từ ảnh chụp màn hình sang mã và cách kết hợp ảnh với tài liệu dài trong cửa sổ 1 triệu token, hãy đọc hướng dẫn vision API GLM-5.3-Flash.

Điều chỉnh mức suy luận

GLM-5.3-Flash hỗ trợ ba mức reasoning_effort: low, high và max.

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"},
)

Mặc định là max, cũng là chế độ tốn kém nhất. Với phân loại hoặc trích xuất số lượng lớn, đặt rõ low để giảm đáng kể token đầu ra.

low là cấp độ mới so với GLM-5.2, vốn chỉ có high và max.

Trong OpenAI Python SDK, reasoning_effort phải nằm trong extra_body vì đây không phải trường của schema OpenAI chuẩn. Khi gọi cURL, đây là trường cấp cao nhất trong JSON.

Tham số lấy mẫu đề xuất

Z.ai đề xuất các giá trị sau:

Trường hợp sử dụng	`temperature`	`top_p`
Chung	1.0	0.95
Mã hóa	0.95	1.0

Khác biệt nhỏ, nhưng cấu hình mã hóa đáng thử nếu đầu ra mã không ổn định.

Streaming

Dùng ngữ nghĩa streaming tiêu chuẩn của OpenAI:

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)

Theo Artificial Analysis, GLM-5.3-Flash tạo khoảng 49 token/giây, chậm hơn GLM-5.3 ở khoảng 86 token/giây. Token đầu tiên xuất hiện sau khoảng 1,52 giây: phù hợp cho giao diện hội thoại, nhưng cần tính đến khi tạo tài liệu dài theo lô.

Gọi công cụ

GLM-5.3-Flash dùng schema tool chuẩn của OpenAI:

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 benchmark tác nhân do Z.ai công bố cho thấy AutomationBench đạt 48.8, so với 26.2 ở GLM-5.2. Đây là số liệu của nhà cung cấp, nhưng phù hợp với định hướng tối ưu cho các vòng lặp gọi công cụ hơn là hội thoại một lượt.

Nếu muốn tạo tool definition từ API hiện có, hãy xem cách chuyển OpenAPI specification thành công cụ tác nhân.

Xử lý lỗi cần có trong production

1. Giới hạn tốc độ

Dùng exponential backoff kèm jitter. Tránh khoảng thời gian retry cố định vì nhiều worker có thể retry đồng thờ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())

2. Tràn ngữ cảnh

Cửa sổ 1 triệu token rất lớn, nhưng tài liệu dài kết hợp với nhiều hình ảnh độ phân giải cao vẫn có thể vượt giới hạn. Hình ảnh cũng tiêu tốn ngữ cảnh, nên hãy theo dõi token đầu vào trước khi gửi yêu cầu.

3. Đầu ra bị cắt cụt

Nếu phản hồi dừng giữa câu, hãy kiểm tra finish_reason. Giá trị length nghĩa là yêu cầu đã chạm giới hạn đầu ra, không phải mô hình tự dừng.

Đọc mức sử dụng token

Mỗi phản hồi chứa usage:

print(response.usage.prompt_tokens, response.usage.completion_tokens)

Đặc biệt theo dõi completion_tokens. Với reasoning_effort="max", token suy luận được tính như token đầu ra, nên phản hồi ngắn vẫn có thể tốn nhiều token hoàn thành.

Cách nhanh nhất để chọn cấu hình phù hợp là chạy cùng prompt ở các mức low, high và max, sau đó so sánh completion_tokens.

Chi phí

Giá niêm yết:

Đầu vào: 0,15 USD / một triệu token
Đầu ra: 0,50 USD / một triệu token
Đầu vào cache: 0,03 USD / một triệu token

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, đưa giá xuống lần lượt còn 0,075 USD, 0,25 USD và 0,015 USD.

Giá có thể khác giữa OpenRouter, Cloudflare Workers AI, Vercel AI Gateway, DeepInfra và các nhà cung cấp khác. Xem phân tích giá GLM-5.3-Flash, đồng thời luôn xác minh giá trực tiếp với nhà cung cấp trước khi lập ngân sách.

Kiểm thử tích hợp

Các payload đa phương thức Base64 thường khó tạo lại bằng cURL, và việc đổi model có thể âm thầm thay đổi cấu trúc phản hồi.

Apidog giúp lưu riêng các request văn bản, hình ảnh và gọi công cụ trong một collection; thêm assertion cho các trường ứng dụng thực sự dùng; và lưu API key trong biến môi trường thay vì shell history.

Khi chương trình khuyến mãi kết thúc, bạn có thể đổi ID model tại một nơi và chạy lại toàn bộ test suite với cả Flash và GLM-5.3. Điều này biến việc chuyển đổi model thành khác biệt có thể quan sát, thay vì một giả định.

FAQ

ID model 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ó hoạt động mà không cần sửa đổi không?

Có, với chat completion, streaming và tool calling. Tham số không chuẩn như reasoning_effort cần extra_body trong Python SDK.

Có thể gửi bao nhiêu hình ảnh trong một request?

Có thể gửi nhiều ảnh, mỗi ảnh là một khối image_url. Giới hạn thực tế là ngân sách ngữ cảnh, không phải số lượng ảnh cố định.

Vì sao phản hồi dài và chậm?

reasoning_effort mặc định là max. Đặt low cho công việc không cần suy luận sâu.

Độ dài đầu ra tối đa là bao nhiêu?

Các nguồn chưa thống nhất: OpenRouter liệt kê 131.072 token, còn thẻ Hugging Face nêu 163.840 token. Hãy xác minh với nhà cung cấp trước khi phụ thuộc vào thế hệ rất dài.

Cách dùng GLM-5.3-Flash trong Claude Code và Cline

Sebastian Petrus — Thu, 27 Aug 2026 03:31:11 +0000

Tích hợp GLM-5.3-Flash với Claude Code và Cline

Nếu bạn đã đăng ký Gói mã hóa GLM, GLM-5.3-Flash đáng chú ý vì được cho là cung cấp dung lượng sử dụng gấp ba lần GLM-5.3 trên cùng một gói. Đổi lại, mô hình đạt 57 điểm trên Chỉ số Thông minh Artificial Analysis, thay vì 60 điểm của GLM-5.3.

Dùng thử Apidog ngay hôm nay

Với công việc mã hóa thông thường, đây thường là đánh đổi hợp lý. Bài viết này hướng dẫn cấu hình GLM-5.3-Flash cho Claude Code và Cline, thời điểm nên dùng GLM-5.3, cùng các lỗi cấu hình phổ biến.

Chuẩn bị

Bạn cần:

Gói đăng ký mã hóa GLM từ z.ai, với giá khởi điểm khoảng 18 USD/tháng.
Khóa API từ bảng điều khiển Z.ai.
Claude Code hoặc Cline đã được cài đặt.

Hãy xác minh hệ số dung lượng và cấp gói trực tiếp trên z.ai trước khi lập kế hoạch sử dụng. Điều khoản gói có thể thay đổi; con số gấp 3 lần đến từ tài liệu của Z.ai.

Claude Code

Z.ai cung cấp endpoint tương thích Anthropic, vì vậy Claude Code có thể gọi GLM bằng hai biến môi trường.

Thiết lập nhanh

Chạy công cụ hỗ trợ của Z.ai:

npx @z_ai/coding-helper

Công cụ sẽ yêu cầu khóa API và tạo cấu hình. Nếu hoàn tất, chuyển sang phần chọn mô hình.

Thiết lập thủ công

Thêm URL cơ sở và mã thông báo vào hồ sơ shell:

export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic"
export ANTHROPIC_AUTH_TOKEN="your-z-ai-key"

Khởi động Claude Code như bình thường. Các yêu cầu sẽ được gửi đến Z.ai thay vì Anthropic.

Lưu ý hai lỗi phổ biến:

ANTHROPIC_API_KEY khác ANTHROPIC_AUTH_TOKEN. Nếu bạn còn khóa Anthropic cũ, hãy hủy đặt biến ANTHROPIC_API_KEY. Đặt cả hai có thể tạo lỗi xác thực giống như dùng sai khóa.
Biến môi trường phải đến được tiến trình Claude Code. Nếu bạn đặt biến trong .zshrc nhưng mở Claude Code từ trình chỉnh sửa hoặc launcher không tải cấu hình shell, các biến sẽ không tồn tại. Kiểm tra bằng lệnh sau trong cùng ngữ cảnh khởi chạy:

echo $ANTHROPIC_BASE_URL

Chọn mô hình

Chọn glm-5.3-flash. Nếu công cụ dùng tệp cài đặt, cấu hình là:

{
  "model": "glm-5.3-flash"
}

Với tác vụ có ngữ cảnh dài, tăng thời gian chờ:

export API_TIMEOUT_MS=3000000

Giá trị này được kế thừa từ thiết lập GLM-5.2; hãy điều chỉnh theo trải nghiệm thực tế. Xem thêm hướng dẫn thiết lập GLM-5.2 nếu bạn đang di chuyển cấu hình cũ.

Cline

Cline kết nối qua nhà cung cấp tương thích OpenAI, không phải endpoint có định dạng Anthropic.

Mở Cline Settings và chọn OpenAI Compatible làm nhà cung cấp API.
Đặt Base URL thành https://api.z.ai/api/coding/paas/v4.
Dán khóa API Z.ai.
Chọn Custom Model và nhập glm-5.3-flash.

Endpoint Gói mã hóa là /api/coding/paas/v4, khác với endpoint API chuẩn /api/paas/v4 dùng cho gọi API trực tiếp trong hướng dẫn API. Dùng endpoint API chuẩn với khóa Gói mã hóa là nguyên nhân phổ biến gây lỗi ủy quyền. Hãy kiểm tra tài liệu Z.ai mới nhất vì các đường dẫn này đã từng thay đổi.

Cài đặt cửa sổ ngữ cảnh

Cline không phải lúc nào cũng suy luận đúng cửa sổ ngữ cảnh cho mô hình tùy chỉnh. Nếu làm việc với codebase lớn hoặc thấy ngữ cảnh bị cắt sớm, hãy đặt thủ công cửa sổ ngữ cảnh thành 1.000.000.

Điều này cũng áp dụng cho GLM-5.2: Cline có thể bỏ qua ngữ cảnh tệp sớm dù mô hình vẫn có khả năng giữ lại.

Vì sao Flash phù hợp với mã hóa tác nhân

Theo số liệu ra mắt của Z.ai:

Điểm chuẩn	GLM-5.3-Flash	GLM-5.2
Terminal-Bench 2.1	84.3	Không so sánh trực tiếp được
DeepSWE	63.4	46.2
AutomationBench	48.8	26.2

Terminal-Bench được đánh giá trên Claude Code 2.1.207, nên có liên quan trực tiếp đến thiết lập của nhiều người dùng. Tuy nhiên, hãy xem đây là tuyên bố từ nhà cung cấp cho đến khi có kết quả sao chép độc lập.

Theo Artificial Analysis, GLM-5.3-Flash có Chỉ số Thông minh là 57, so với 60 của GLM-5.3.

Một khả năng mới hữu ích cho công cụ mã hóa là đầu vào hình ảnh gốc. Flash có thể nhận ảnh chụp màn hình cùng với mã trong một yêu cầu. Với công việc front-end, bạn có thể gửi ảnh bố cục bị lỗi để mô hình suy luận trực tiếp từ kết quả hiển thị thay vì chỉ dựa vào mô tả. Hướng dẫn tính năng thị giác trình bày chi tiết khả năng này.

Đánh đổi về tốc độ

GLM-5.3-Flash tạo khoảng 49 token/giây, trong khi GLM-5.3 đạt khoảng 86 token/giây. Với các yêu cầu cần tạo đầu ra dài, sự khác biệt này sẽ rõ rệt.

Thời gian đến token đầu tiên gần như tương đương: 1,52 giây so với 1,57 giây. Flash bắt đầu phản hồi nhanh, nhưng chậm hơn khi phải tạo nhiều nội dung.

Tóm lại:

Chỉnh sửa nhỏ, gọi công cụ, đọc mã, tác vụ lặp lại: Flash thường có lợi hơn nhờ dung lượng gấp 3 lần.
Tái cấu trúc lớn hoặc viết lại tệp dài: GLM-5.3 có thể đáng dùng hơn nhờ tốc độ tạo đầu ra cao hơn.

Chiến lược định tuyến thực tế

Không cần chỉ chọn một mô hình:

Dùng Flash mặc định cho khám phá, đọc mã, chạy lệnh, chỉnh sửa nhỏ và tác vụ liên quan đến hình ảnh.
Dùng GLM-5.3 cho vấn đề kiến trúc khó, tái cấu trúc lớn hoặc khi Flash đã thất bại một lần.

Việc chuyển đổi chỉ yêu cầu thay đổi ID mô hình trong cài đặt công cụ. Cách này giữ phần lớn khối lượng công việc trên mô hình có dung lượng gấp 3 lần, đồng thời dành dung lượng GLM-5.3 cho những tác vụ thực sự cần thiết.

Z.ai cũng cho biết các lệnh gọi ngoài giờ cao điểm chỉ tiêu thụ một nửa số điểm tiêu chuẩn. Lập lịch tác vụ tác nhân theo lô hoặc chạy nền ngoài giờ cao điểm có thể giúp kéo dài gói dịch vụ.

Khắc phục sự cố

Lỗi 401 hoặc 403 trên mọi yêu cầu

Nguyên nhân thường là:

Base URL không phù hợp với khóa đang dùng.
ANTHROPIC_API_KEY cũ che khuất ANTHROPIC_AUTH_TOKEN.

Hãy xác nhận bằng lệnh gọi trực tiếp ở phần cuối bài viết trước khi thay đổi cấu hình công cụ.

Không tìm thấy mô hình

Kiểm tra chính xác ID:

glm-5.3-flash

ID này dùng dấu chấm trong phiên bản và dấu gạch nối trước flash. Trên OpenRouter, tên là z-ai/glm-5.3-flash, không thể thay thế trực tiếp cho ID gốc của Z.ai.

Ngữ cảnh bị cắt ngắn sớm

Trong Cline, đặt thủ công cửa sổ ngữ cảnh thành 1.000.000. Cline không luôn suy luận chính xác giá trị này cho mô hình tùy chỉnh.

Hết thời gian chờ với yêu cầu lớn

Tăng API_TIMEOUT_MS. Yêu cầu có ngữ cảnh rất dài có thể vượt quá thời gian chờ mặc định của máy khách.

Dung lượng cạn nhanh hơn dự kiến

reasoning_effort mặc định là max, và token suy luận cũng được tính. Nếu công cụ hỗ trợ cấu hình này, hãy giảm xuống low cho công việc thông thường để kéo dài gói dịch vụ.

Lệnh gọi công cụ lỗi hoặc sai định dạng

Xác nhận công cụ và endpoint sử dụng cùng định dạng gọi công cụ. Đây thường là phần nhạy cảm nhất với phiên bản và dễ hỏng sau khi một bên cập nhật.

Dùng với các công cụ khác

Hai kiểu kết nối này bao phủ phần lớn công cụ:

Công cụ tương thích Anthropic — như Claude Code và một số framework tác nhân — dùng https://api.z.ai/api/anthropic với ANTHROPIC_AUTH_TOKEN.
Công cụ tương thích OpenAI — như Cline, Roo, Kilo, OpenCode, Codex và tùy chọn mô hình tùy chỉnh của Cursor — dùng https://api.z.ai/api/coding/paas/v4, khóa API tiêu chuẩn và ID glm-5.3-flash.

Các hướng dẫn cho phiên bản trước:

Xác minh kết nối

Trước khi tin vào cấu hình công cụ, hãy kiểm tra endpoint độc lập:

curl https://api.z.ai/api/coding/paas/v4/chat/completions \
  -H "[REDACTED CREDENTIAL] $ZAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "messages": [{"role": "user", "content": "reply with OK"}]
  }'

Nếu lệnh trả về phản hồi hoàn chỉnh nhưng công cụ vẫn thất bại, vấn đề nằm ở cấu hình công cụ chứ không phải thông tin đăng nhập.

Với nhiều hơn một lần kiểm tra, Apidog thuận tiện hơn lịch sử shell. Lưu endpoint mã hóa và endpoint chuẩn cạnh nhau, dùng biến môi trường để lưu khóa, rồi kiểm tra nhanh liệu lỗi ủy quyền đến từ endpoint hay công cụ.

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

Tôi có cần Gói mã hóa không, hay API credits cũng hoạt động? Cả hai đều hoạt động. Gói mã hóa thường phù hợp hơn với lập trình viên dùng hằng ngày; API credits phù hợp cho ứng dụng. Xem bài viết về giá.
Flash có thực sự có dung lượng gấp 3 lần GLM-5.3 không? Đây là con số do Z.ai công bố. Hãy xác minh tại z.ai/subscribe trước khi lập kế hoạch.
Vì sao Cline cắt ngắn ngữ cảnh? Đặt thủ công cửa sổ ngữ cảnh thành 1.000.000; Cline không luôn suy luận đúng cho mô hình tùy chỉnh.
Dùng Base URL nào? Dùng https://api.z.ai/api/anthropic cho Claude Code, https://api.z.ai/api/coding/paas/v4 cho công cụ tương thích OpenAI trong Gói mã hóa, và https://api.z.ai/api/paas/v4 cho lệnh gọi API trực tiếp.
Tôi có thể dán ảnh chụp màn hình vào Claude Code với Flash không? Mô hình hỗ trợ đầu vào hình ảnh gốc. Việc phiên bản công cụ của bạn có hiển thị khả năng này hay không là vấn đề riêng, vì vậy hãy kiểm tra trước khi phụ thuộc vào nó.

Cách kiểm tra API GLM-5.3-Flash trong Apidog

Sebastian Petrus — Thu, 27 Aug 2026 03:28:29 +0000

Kiểm tra GLM-5.3-Flash bằng Apidog: văn bản, hình ảnh, gọi công cụ và CI

Thay đổi ID LLM chỉ là một dòng code, nhưng có thể làm đổi độ trễ, chi phí token, định dạng đầu ra, hành vi gọi công cụ và khả năng xử lý ảnh. GLM-5.3-Flash rẻ hơn GLM-5.3 khoảng chín lần, hỗ trợ hình ảnh nguyên bản trong khi GLM-5.3 không hỗ trợ, nhưng tốc độ tạo văn bản chỉ bằng khoảng một nửa. Cách đáng tin cậy để chọn mô hình là chạy cùng các yêu cầu thực tế trên cả hai.

Dùng thử Apidog ngay hôm nay

Hướng dẫn này tạo một bộ sưu tập kiểm thử có thể tái sử dụng trong Apidog cho GLM-5.3-Flash: chat văn bản, thị giác, function calling, xác nhận phản hồi và so sánh mô hình.

Vì sao không chỉ dùng curl?

Bạn có thể bắt đầu bằng curl; hướng dẫn API của chúng tôi có ví dụ đầy đủ. Nhưng khi cần chạy lại nhiều lần, hai vấn đề nhanh chóng xuất hiện:

Ảnh Base64 khó quản lý. URL dữ liệu có thể dài hàng nghìn ký tự, khiến lệnh terminal khó đọc, khó sửa và không phù hợp để tái sử dụng.
Không có xác nhận tự động. Curl chỉ cho biết request thành công; không đảm bảo phản hồi vẫn chứa các trường mà ứng dụng phụ thuộc.

Một collection đã lưu giải quyết cả hai: payload có thể chỉnh sửa và các assertion được chạy ở mỗi lần gửi yêu cầu.

1. Thiết lập môi trường

Tạo environment với các biến sau:

Biến	Giá trị
`base_url`	`https://api.z.ai/api/paas/v4`
`api_key`	khóa Z.ai của bạn
`model`	`glm-5.3-flash`

Giữ model ID dưới dạng biến để bạn có thể chạy lại toàn bộ collection với mô hình khác. Lưu API key trong environment thay vì dán vào header để tránh vô tình xuất hoặc chia sẻ khóa.

2. Kiểm tra hoàn thành văn bản

Tạo request POST tới:

{{base_url}}/chat/completions

Headers:

[REDACTED CREDENTIAL] {{api_key}}
Content-Type: application/json

Body:

{
  "model": "{{model}}",
  "messages": [
    {"role": "user", "content": "Reply with exactly: OK"}
  ],
  "reasoning_effort": "low"
}

Đặt reasoning_effort thành low. Mặc định của mô hình là max, và token lý luận được tính phí như token đầu ra. Với kiểm tra kết nối cơ bản, chi phí đó không cần thiết.

Thêm các assertion:

Status code là 200
choices[0].message.content tồn tại
choices[0].finish_reason là stop
usage.total_tokens tồn tại

Kiểm tra finish_reason rất quan trọng. Giá trị length cho biết đầu ra đã bị cắt ở giới hạn token, không phải hoàn thành bình thường. Đây là cách rõ ràng để phát hiện phản hồi bị truncation.

3. Kiểm tra đầu vào hình ảnh

GLM-5.3-Flash hỗ trợ hình ảnh nguyên bản; GLM-5.3 thì không. Dùng cùng endpoint nhưng thay content bằng mảng block:

{
  "model": "{{model}}",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What color is the dominant shape in this image? Answer with one word."},
        {"type": "image_url", "image_url": {"url": "{{test_image_url}}"}}
      ]
    }
  ],
  "reasoning_effort": "low"
}

Thêm test_image_url vào environment. Hãy dùng ảnh công khai, ổn định và có đáp án rõ ràng để biến request này thành regression test thay vì demo.

Với ảnh cục bộ, lưu URL dữ liệu Base64 vào biến môi trường:

data:image/png;base64,iVBORw0go...

Các assertion nên có:

Status code là 200
choices[0].message.content chứa đáp án mong đợi
usage.prompt_tokens lớn hơn request chỉ có văn bản

Assertion token đặc biệt hữu ích: ảnh tiêu thụ token đầu vào. Nếu prompt_tokens không tăng, ảnh có thể đã bị bỏ qua dù API vẫn trả về 200.

Xem thêm hướng dẫn thị giác GLM-5.3-Flash để biết luồng xử lý ảnh và các chế độ lỗi.

4. Kiểm tra function calling

Nếu ứng dụng dùng function calling, hãy kiểm tra trực tiếp định dạng tool call. Đây là phần dễ bị ảnh hưởng nhất khi nhà cung cấp hoặc phiên bản mô hình thay đổi.

{
  "model": "{{model}}",
  "messages": [
    {"role": "user", "content": "Is the checkout-api service healthy?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_deployment_status",
        "description": "Returns the current status of a named deployment.",
        "parameters": {
          "type": "object",
          "properties": {
            "service": {"type": "string", "description": "The service name."}
          },
          "required": ["service"]
        }
      }
    }
  ]
}

Thêm các assertion:

choices[0].message.tool_calls tồn tại và không rỗng
choices[0].message.tool_calls[0].function.name là get_deployment_status
choices[0].finish_reason là tool_calls

Đừng chỉ kiểm tra sự tồn tại của tool call. Kiểm tra tên hàm giúp phát hiện mô hình gọi sai tool khi bạn có nhiều công cụ.

Nếu đã có API, bạn có thể biến đổi spec OpenAPI thành công cụ tác tử thay vì viết schema thủ công.

5. So sánh với GLM-5.3

Nhân đôi environment, rồi đổi:

model = glm-5.3

Chạy lại cùng collection và so sánh ba điểm:

Tính đúng đắn: Các assertion có còn qua không? Request hình ảnh sẽ không qua vì GLM-5.3 không hỗ trợ ảnh nguyên bản. Đây là một phát hiện hợp lệ, không phải lỗi test.
Độ trễ: Apidog hiển thị response time cho từng request. Với đầu ra dài, GLM-5.3 có thể nhanh hơn: khoảng 86 token/giây so với 49 token/giây của Flash.
Chi phí: Dùng usage.prompt_tokens và usage.completion_tokens, sau đó nhân với đơn giá của từng model. Bạn sẽ có chi phí thực tế theo request thay vì con số marketing tổng quát.

Xem phân tích giá GLM-5.3-Flash và so sánh GLM-5.3-Flash với GLM-5.3.

Theo dõi kỹ completion_tokens ở các mức reasoning_effort. Chạy cùng prompt với low, high và max để xác định mức suy luận mà workload thực sự cần.

6. Kiểm tra triển khai cục bộ

Nếu tự host trọng số, vLLM và SGLang đều có endpoint tương thích OpenAI. Chỉ cần thay base_url bằng URL máy chủ của bạn rồi chạy lại collection.

Đây là cách phát hiện các lỗi mà smoke test không thấy: bản lượng tử hóa có thể trả lời chat cơ bản bình thường nhưng xử lý sai tool schema hoặc giảm chất lượng đầu vào hình ảnh. Hướng dẫn chạy GLM-5.3-Flash cục bộ bao gồm phần triển khai.

7. Đưa collection vào CI

Khi collection ổn định, chạy nó trong CI hoặc theo lịch:

Trước khi chuyển model, làm tín hiệu chấp thuận hoặc từ chối.
Theo lịch, để phát hiện thay đổi phía nhà cung cấp.
Sau khi cập nhật SDK hoặc dependency, để phát hiện thay đổi trong serialization request.

Nhà cung cấp có thể cập nhật mô hình phía sau một model ID ổn định. Kiểm tra định kỳ giúp bạn biết hành vi đã thay đổi trước khi người dùng phát hiện.

8. Kiểm tra ngoài happy path

Sau khi các request cơ bản hoạt động, bổ sung:

Context dài bằng đúng độ dài ứng dụng thực tế sử dụng; hành vi ở 500K token không thể suy ra từ 5K token.
Đầu vào lỗi để xác nhận xử lý lỗi.
Phản hồi rate limit để kiểm tra retry logic.
Nhiều ảnh trong một request; mỗi ảnh cần block image_url riêng.
Streaming nếu ứng dụng dùng stream, vì cấu trúc phản hồi khác completion thông thường.

Kết luận

Giá trị của collection không nằm ở từng request mà ở khả năng lặp lại. Khi giá thay đổi, Z.ai phát hành bản sửa đổi mới, hoặc đội ngũ cân nhắc đổi nhà cung cấp, bạn có thể đánh giá lại quyết định model trong khoảng ba mươi giây.

Apidog miễn phí để bắt đầu. Nhập schema tương thích OpenAI để thiết lập nhanh phần lớn request, sau đó giữ collection như một regression suite cho mọi lần thay đổi mô hình.

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

Tôi có cần gói Apidog trả phí không?

Không. Collection có environment variables và assertion hoạt động trên gói miễn phí.

Làm cách nào để kiểm tra ảnh Base64 mà không làm body khó đọc?

Lưu data URL trong environment và dùng {{test_image_url}} trong request body.

Tôi có thể kiểm tra endpoint coding-plan tương tự không?

Có. Đổi base_url thành:

https://api.z.ai/api/coding/paas/v4

Endpoint này khác API tiêu chuẩn; xem hướng dẫn Claude Code và Cline.

Các test này có dùng được với nhà cung cấp khác không?

Phần lớn có. OpenRouter, Cloudflare Workers AI và Vercel AI Gateway đều có giao diện tương thích OpenAI. Thay base_url và model ID namespace phù hợp.

Làm sao xác nhận phản hồi không xác định trước?

Xác nhận cấu trúc và ràng buộc thay vì toàn bộ văn bản: sự tồn tại trường, kiểu dữ liệu, số token, finish_reason và chuỗi con cho câu hỏi có đáp án đã biết.

Cách chạy GLM-5.3-Flash trên máy tính

Sebastian Petrus — Thu, 27 Aug 2026 03:27:04 +0000

GLM-5.3-Flash là một mô hình 320 tỷ tham số được phát hành theo giấy phép MIT. Hai sự thật này có vẻ mâu thuẫn: giấy phép cho phép bạn chạy nó theo bất kỳ cách nào bạn muốn, nhưng số lượng tham số lại đòi hỏi phần cứng nghiêm túc để làm được điều đó.

Hãy dùng thử Apidog ngay hôm nay

Điểm quan trọng là chỉ 18 tỷ trong 320 tỷ tham số hoạt động trên mỗi token. Cùng với các bản dựng lượng tử hóa đã có, điều này đưa mô hình vào tầm với của những thiết lập nhỏ hơn đáng kể so với nút 8× H200 thường được giả định.

Bài viết này giúp bạn chọn cấu hình phù hợp: từ nút sản xuất độ chính xác đầy đủ đến bản dựng lượng tử hóa trên máy trạm.

Bạn thực sự đang tải gì?

Thuộc tính	Giá trị
Tổng tham số	320B
Hoạt động trên mỗi token	18B
Kiến trúc	MoE, hybrid linear và sparse attention
Ngữ cảnh	1.048.576 token
Giấy phép	MIT
Trọng số	`zai-org/GLM-5.3-Flash`
Lượng tử hóa GGUF	`unsloth/GLM-5.3-Flash-GGUF`

Kiến trúc mixture-of-experts (MoE) khiến mô hình khả thi: toàn bộ 320B tham số phải nằm trong bộ nhớ, nhưng chỉ 18B tham gia khi tạo mỗi token. Vì vậy, giới hạn chính là bộ nhớ, không phải FLOPs.

Z.ai cũng báo cáo KV cache nhỏ hơn khoảng 4,4 lần so với GLM-5.3. Điều này đặc biệt quan trọng cho ngữ cảnh dài, vì KV cache tăng theo số token và thường là nguyên nhân gây hết bộ nhớ.

Cấp 1: Độ chính xác đầy đủ cho môi trường sản xuất

Để phục vụ đầy đủ chất lượng và đồng thời thực sự, cấu hình tham chiếu là 8× H200:

141 GB mỗi GPU
Khoảng 1.128 GB VRAM tổng cộng
8× H20 cũng hoạt động tốt

Chỉ riêng trọng số cần khoảng 700–800 GB tùy độ chính xác; bạn vẫn cần bộ nhớ cho KV cache và overhead runtime. Giá thuê đám mây cho cấu hình này vào khoảng 24–48 USD/ngày.

Chạy bằng vLLM

vLLM có hệ sinh thái rộng và là lựa chọn mặc định phổ biến. Dùng tensor parallel với kích thước là lũy thừa của hai:

vllm serve zai-org/GLM-5.3-Flash \
  --tensor-parallel-size 8 \
  --max-model-len 1048576 \
  --trust-remote-code

Đừng bắt đầu ngay với cửa sổ ngữ cảnh 1 triệu token. Hãy xác thực thiết lập với --max-model-len nhỏ hơn trước, vì yêu cầu ngữ cảnh tối đa sẽ buộc runtime cấp phát KV cache tương ứng và dễ dẫn đến lỗi hết bộ nhớ.

Chạy bằng SGLang

SGLang hỗ trợ mô hình này ngay từ ngày đầu, với công thức triển khai cho H100, H200, B200, B300, GB200 và GB300, bao gồm cả phục vụ đa phương thức. Z.ai đã dùng một stack dựa trên SGLang trước khi ra mắt.

python -m sglang.launch_server \
  --model-path zai-org/GLM-5.3-Flash \
  --tp 8 \
  --context-length 1048576

SGLang thường mạnh về đầu ra có cấu trúc và các tác vụ agentic đồng thời cao. Nếu bạn phục vụ coding agent thay vì giao diện trò chuyện, hãy benchmark cả SGLang và vLLM trên tải thực tế.

Cả hai runtime cần cấu hình tool-call parser nếu bạn dùng function calling. Kiểm tra tài liệu phiên bản hiện tại, vì tên parser có thể thay đổi giữa các bản phát hành.

Cấp 2: Lượng tử hóa trên phần cứng nhỏ hơn

Các bản dựng GGUF lượng tử hóa có tại unsloth/GLM-5.3-Flash-GGUF, gồm các định dạng mạnh như IQ1_S và IQ2_XXS.

Lượng tử hóa 2-bit có thể giảm dung lượng trọng số của mô hình 320B xuống mức phù hợp với:

Máy trạm có RAM lớn
Hệ thống nhiều GPU tiêu dùng
Thiết lập dùng CPU offload

Tuy nhiên, cần lưu ý hai điều.

1. Lượng tử hóa mạnh làm giảm chất lượng

IQ1_S vẫn cách xa chất lượng độ chính xác đầy đủ. Với MoE 320B, mức suy giảm có thể ít nghiêm trọng hơn mô hình dense tương đương vì có nhiều dư thừa hơn, nhưng “chạy được” không đồng nghĩa với “chạy tốt”.

Hãy kiểm tra bằng workload, prompt, tool schema và dữ liệu thực tế của bạn trước khi triển khai.

2. Bản hướng dẫn của Unsloth vẫn đang phát triển

Các định dạng lượng tử hóa và cấu hình khuyến nghị có thể thay đổi. Hãy kiểm tra những bản dựng thực sự đã được phát hành trước khi lên kế hoạch phần cứng quanh một định dạng cụ thể.

Với hệ thống CPU-heavy hoặc hybrid, KTransformers phù hợp với kiến trúc MoE: giữ các expert trong RAM hệ thống và chỉ chuyển phần cần thiết lên GPU. TokenSpeed cũng nằm trong danh sách runtime được hỗ trợ.

Bạn có thể tham khảo thêm:

Tính ngân sách bộ nhớ

Hai yếu tố quyết định cấu hình có khả thi hay không.

Trọng số

Định dạng	Ước tính dung lượng trọng số
BF16	Khoảng 640 GB trước overhead
FP8	Khoảng một nửa BF16
4-bit	Gần 160 GB
2-bit mạnh	Thấp hơn nữa, đổi lại chất lượng giảm

KV cache

KV cache tăng theo:

Độ dài ngữ cảnh
Số lượng yêu cầu đồng thời

Một cấu hình chạy tốt ở 8K token vẫn có thể thất bại ở 128K token do KV cache, không phải do trọng số. Việc Z.ai giảm KV cache khoảng 4,4 lần so với GLM-5.3 là rất hữu ích, nhưng mức sử dụng vẫn tăng tuyến tính theo token.

Cách làm thực tế: đặt giới hạn ngữ cảnh theo nhu cầu thật. Rất ít ứng dụng cần một triệu token; cấp phát bộ nhớ cho cửa sổ không dùng đến là cách nhanh nhất khiến mô hình trông quá đắt đỏ.

Nếu bạn từng theo dõi hướng dẫn trước khi trọng số được phát hành, hãy lưu ý rằng bài viết tự host GLM-5.3 được viết trước thời điểm đó. Trọng số Flash hiện đã được phát hành theo giấy phép MIT, nên hướng dẫn này thay thế bối cảnh cũ.

Tinh chỉnh

Giấy phép MIT cho phép tinh chỉnh và phân phối lại, một lợi thế hiếm có ở mức năng lực này.

Tuy nhiên, tinh chỉnh đầy đủ mô hình 320B nằm ngoài khả năng của hầu hết đội ngũ. Con đường thực tế là các phương pháp hiệu quả tham số như LoRA.

Với MoE, bạn còn phải quyết định điều chỉnh:

Router
Các expert
Các lớp attention

Đây vẫn là một lĩnh vực đang phát triển, với ít hướng dẫn rõ ràng hơn so với mô hình dense.

Nếu mục tiêu là thích nghi miền thay vì bổ sung năng lực mới, hãy thử prompting và retrieval trước. Với cửa sổ ngữ cảnh 1 triệu token, đưa tri thức miền vào prompt thường rẻ hơn và hiệu quả hơn việc huấn luyện nó vào mô hình.

Cài đặt lấy mẫu

Z.ai khuyến nghị các cấu hình sau:

Trường hợp sử dụng	`temperature`	`top_p`
Chung	1.0	0.95
Lập trình	0.95	1.0

Mô hình cũng hỗ trợ reasoning_effort với ba mức:

low
high
max

max là mặc định. Trên phần cứng cục bộ, điều này ảnh hưởng trực tiếp đến thời gian tạo phản hồi. Nếu tốc độ token thấp, low có thể là khác biệt giữa một trải nghiệm khả dụng và không khả dụng.

Tự host có hợp lý về chi phí không?

Thường là không, chủ yếu vì giá API.

GLM-5.3-Flash có giá niêm yết 0,15 USD cho mỗi triệu token đầu vào. Một nút 8× H200 giá khoảng 1.000 USD/tháng tương đương với khoảng 6,7 tỷ token đầu vào qua API.

Nút tự host có chi phí cố định dù nhàn rỗi, trong khi API chỉ tính theo mức sử dụng. Trừ khi tải của bạn rất cao và liên tục, API thường rẻ hơn.

Lý do tự host thường không phải là giá:

Dữ liệu và quyền riêng tư: dữ liệu không rời hạ tầng của bạn.
Không giới hạn tốc độ: năng lực phụ thuộc vào phần cứng của bạn.
Khả dụng: không phụ thuộc uptime hay quyết định giá của nhà cung cấp.
Giấy phép MIT: có thể sửa đổi, tinh chỉnh và phân phối lại.
Phần cứng sẵn có: nếu GPU đã mua và đang nhàn rỗi, chi phí biên chủ yếu là điện.

Xem thêm phân tích giá GLM-5.3-Flash để so sánh chi tiết hơn với API.

Xác minh triển khai

vLLM và SGLang đều cung cấp endpoint tương thích OpenAI. Bạn có thể kiểm tra nhanh máy chủ cục bộ như sau:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org/GLM-5.3-Flash",
    "messages": [{"role": "user", "content": "reply with OK"}]
  }'

Ngoài smoke test, hãy kiểm tra:

Ngữ cảnh dài ở độ dài bạn thực sự cần
Đầu vào ảnh nếu dùng đa phương thức
Tool calling với schema thực tế
Throughput dưới tải đồng thời, không chỉ độ trễ một yêu cầu

Dùng Apidog để lưu bộ kiểm thử, chuyển URL cơ sở thành biến môi trường, rồi chạy cùng một collection với máy chủ cục bộ và endpoint Z.ai. Cách này giúp bạn sớm phát hiện liệu bản dựng lượng tử hóa có còn xử lý đúng các schema công cụ mà ứng dụng phụ thuộc hay không.

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

Phần cứng tối thiểu là gì?

Độ chính xác đầy đủ cần nút 8× H200. Bản GGUF lượng tử hóa cần ít hơn đáng kể, nhưng chất lượng giảm theo mức độ lượng tử hóa.

Tôi có cần giữ đủ 320B tham số trong bộ nhớ không?

Có. Chỉ 18B tham số hoạt động trên mỗi token, nhưng toàn bộ trọng số vẫn phải nằm trong bộ nhớ.

Nên chọn vLLM hay SGLang?

SGLang hỗ trợ sớm, có công thức đa phương thức và thường mạnh về đồng thời cũng như đầu ra có cấu trúc. vLLM có hệ sinh thái rộng hơn. Hãy benchmark cả hai với workload của bạn.

Tôi có thể chạy trên một GPU không?

Không ở độ chính xác đầy đủ. Với lượng tử hóa mạnh và CPU offload qua KTransformers, một GPU có VRAM cao cùng nhiều RAM hệ thống là khả thi, nhưng tốc độ tạo sẽ chậm.

Giấy phép có thực sự là MIT không?

Có. Trọng số được phát hành theo MIT, cho phép sử dụng thương mại, sửa đổi và phân phối lại.

GLM-5.3-Flash là gì? Mô hình đa phương thức tự nhiên trọng số mở đầu tiên của Z.ai

Sebastian Petrus — Thu, 27 Aug 2026 03:26:29 +0000

GLM-5.3-Flash: mô hình đa phương thức 320B với chi phí thấp

Z.ai phát hành GLM-5.3-Flash vào ngày 26 tháng 8 năm 2026. Đây là mô hình mixture-of-experts 320 tỷ tham số, trong đó 18 tỷ tham số được kích hoạt, phát hành theo giấy phép MIT. Đây cũng là mô hình đầu tiên trong dòng GLM-5 xử lý hình ảnh tự nhiên thay vì dùng bộ chuyển đổi thị giác gắn thêm.

Thử Apidog ngay hôm nay

Nhiều nhà phát triển đã sử dụng mô hình này trong một tuần mà không biết danh tính thật của nó. Tuy nhiên, “Flash” trong tên gọi không có nghĩa là mô hình tạo token nhanh.

Tóm tắt nhanh

Mô hình: mixture-of-experts 320B-A18B, trọng số mở, giấy phép MIT.
Nhà phát hành: Z.ai, ngày 26 tháng 8 năm 2026.
Đa phương thức: nhận văn bản, hình ảnh, video và tệp trong cùng một yêu cầu.
Ngữ cảnh: 1.048.576 token, tương đương GLM-5.3.
Giá niêm yết: 0,15 USD cho mỗi triệu token đầu vào và 0,50 USD cho mỗi triệu token đầu ra, xấp xỉ một phần mười GLM-5.2.
Tốc độ: 48,7 token đầu ra mỗi giây; không nhanh so với kích thước mô hình.
Thời gian tạo token đầu tiên: 1,52 giây, tốt hơn mức trung bình 2,14 giây của các mô hình mã nguồn mở.
API: glm-5.3-flash.
Nhà cung cấp: Z.ai, OpenRouter, Cloudflare Workers AI, Vercel AI Gateway và các nền tảng khác.
Tự lưu trữ: trọng số có trên Hugging Face.

Thông số kỹ thuật

Thuộc tính	Giá trị
Tổng tham số	320B
Tham số hoạt động	18B
Kiến trúc	Mixture of experts, chú ý tuyến tính và chú ý thưa lai
Giấy phép	MIT
Cửa sổ ngữ cảnh	1.048.576 token
Đầu vào	Văn bản, hình ảnh, video, tệp
Đầu ra	Văn bản
Chế độ suy luận	`thấp`, `cao`, `tối đa` (mặc định `tối đa`)
ID mô hình API	`glm-5.3-flash`
Hugging Face	`zai-org/GLM-5.3-Flash`

Giới hạn token đầu ra chưa thống nhất

OpenRouter liệt kê tối đa 131.072 token, trong khi thẻ mô hình Hugging Face chỉ ra 163.840 token. Z.ai chưa công bố con số chính thức để giải quyết khác biệt này.

Nếu ứng dụng cần các lần sinh văn bản rất dài, hãy kiểm tra giới hạn với nhà cung cấp thực tế trước khi triển khai.

Đa phương thức tự nhiên là thay đổi quan trọng nhất

Trước đây, khả năng thị giác trong dòng GLM nằm ở các mô hình hoặc điểm cuối riêng biệt. Z.ai phát hành GLM-5V-Turbo và GLM-4.6V như các mô hình thị giác chuyên dụng. GLM-5.2 chỉ xử lý văn bản, còn GLM-5.3 dùng bộ chuyển đổi riêng cho thị giác.

GLM-5.3-Flash đưa hình ảnh, video và tệp vào cùng một yêu cầu chat với văn bản. Điều này tạo ra:

Một ID mô hình duy nhất.
Một dòng thanh toán duy nhất.
Một cửa sổ ngữ cảnh có thể chứa cả hình ảnh và hàng triệu token văn bản.

Bạn có thể gửi một tài liệu đặc tả dài cùng ảnh chụp màn hình giao diện đã render, sau đó yêu cầu mô hình đối chiếu hai nguồn này trong cùng một prompt. Z.ai mô tả mô hình có thể quan sát “giao diện, kết quả hiển thị và phản hồi tương tác”, phù hợp với tác nhân lập trình hơn là chỉ chú thích ảnh.

Nếu cần mô hình thị giác chuyên dụng, hãy xem hướng dẫn API GLM-5V-Turbo hoặc GLM-OCR cho việc hiểu tài liệu.

Kiến trúc và hiệu quả phục vụ

Z.ai xây dựng GLM-5.3-Flash trên một mô hình cơ sở mới thay vì hậu huấn luyện GLM-5.2. Hai lựa chọn kiến trúc chính là:

Chú ý lai (Hybrid attention). Mô hình kết hợp chú ý tuyến tính và chú ý thưa:

Chú ý tuyến tính xử lý các phụ thuộc cục bộ với chi phí thấp.
Chú ý thưa tập trung vào các token có liên quan trên toàn cục.

Theo công bố, chi phí tính toán cho attention thấp hơn khoảng ba lần so với GLM-5.3, còn bộ nhớ đệm KV nhỏ hơn khoảng 4,4 lần.

Siêu kết nối ràng buộc đa tạp (Manifold-Constrained Hyper-Connections). Đây là thuật ngữ Z.ai dùng cho các kỹ thuật tối ưu hiệu quả mở rộng. Hiện chưa có đủ chi tiết công khai để đánh giá độc lập, vì vậy nên xem đây là đặc điểm kiến trúc do nhà cung cấp mô tả, chưa phải lợi thế đã được chứng minh.

Bộ nhớ đệm KV là một trong những nguyên nhân chính khiến suy luận ngữ cảnh dài tốn nhiều bộ nhớ. Việc giảm kích thước bộ nhớ đệm 4,4 lần giúp giải thích cách mô hình duy trì cửa sổ 1M token với mức giá thấp hơn đáng kể.

Quá trình huấn luyện sử dụng kho ngữ liệu đa phương thức mà Z.ai mô tả là khoảng 30 nghìn tỷ token.

“Flash” không có nghĩa là nhanh hơn

Artificial Analysis đo được GLM-5.3-Flash ở mức 48,7 token đầu ra mỗi giây. GLM-5.3 đạt khoảng 86 token mỗi giây trong cùng phép đo, tức phiên bản Flash chỉ có tốc độ gần bằng một nửa.

Điểm mạnh của Flash là thời gian tạo token đầu tiên:

GLM-5.3-Flash: 1,52 giây.
Trung bình các mô hình mã nguồn mở: 2,14 giây.
GLM-5.3: tốc độ tạo token cao hơn đáng kể.

Vì vậy:

Chọn Flash cho các tác vụ gồm nhiều lượt tương tác ngắn, nơi phản hồi ban đầu quan trọng.
Chọn GLM-5.3 nếu cần sinh tài liệu dài với tốc độ streaming cao.
Đừng chọn Flash chỉ vì tên gọi “Flash”.

Lợi thế thực tế của mô hình nằm ở chi phí và bộ nhớ, không phải thông lượng sinh token. Bộ nhớ đệm KV nhỏ hơn và chi phí attention thấp hơn giúp giảm giá mỗi token cùng dấu chân phục vụ, nhưng không khiến mô hình truyền phát nhanh hơn.

Điểm chuẩn

Các số liệu dưới đây do Z.ai công bố khi ra mắt, nên được xem là tuyên bố của nhà cung cấp cho đến khi có bên thứ ba tái tạo.

Artificial Analysis xếp GLM-5.3-Flash ở mức 57 trên Chỉ số thông minh v4.1.1. GLM-5.3 đạt 60 điểm, còn mức trung bình của các mô hình mã nguồn mở có kích thước tương tự là 27.

Z.ai định vị mô hình này gần Claude Opus 4.8 trong các tác vụ lập trình và tác nhân. Đây là đặc tính hóa dựa trên đánh giá nội bộ của nhà cung cấp, không phải kết quả đo lường độc lập. Khoảng cách ba điểm so với GLM-5.3 cũng cho thấy cần thận trọng khi diễn giải tuyên bố này.

Để xem các tiêu chuẩn GLM thay đổi như thế nào qua từng phiên bản, hãy đọc phân tích điểm chuẩn GLM-5.2.

Tuần lễ Ox Alpha

Ngày 20 tháng 8, mô hình ẩn danh ox-alpha xuất hiện trên các nền tảng suy luận bên thứ ba với cửa sổ ngữ cảnh 1M token và giá bằng không. Trong vài ngày, đây là một trong những mô hình được sử dụng nhiều nhất trên các nền tảng đó.

Cộng đồng xác định mô hình thuộc Zhipu trong khoảng 48 giờ dựa trên đặc điểm đầu ra.

Ngày 26 tháng 8, Z.ai xác nhận Ox Alpha chính là GLM-5.3-Flash, còn tuần lễ miễn phí là một thử nghiệm tải có chủ đích.

Z.ai cũng cho biết toàn bộ lưu lượng trong tuần đó được phục vụ trên các bộ tăng tốc nội địa Trung Quốc sử dụng ngăn xếp dựa trên SGLang. Nhà cung cấp tuyên bố chi phí phục vụ mỗi token có thể so sánh với phần cứng NVIDIA thông thường, nhưng chưa có xác minh độc lập.

Mẫu hình này từng xuất hiện với Pony Alpha, sau đó được xác định là mô hình DeepSeek hoặc GLM. Một mô hình ẩn danh có năng lực đặc biệt, cửa sổ ngữ cảnh “tròn trịa” và giá bất thường thường là phiên bản chưa phát hành đang được dùng để thu thập dữ liệu đánh giá.

Cách sử dụng GLM-5.3-Flash

API tương thích OpenAI

Điểm cuối của Z.ai tương thích với OpenAI. Bạn chỉ cần đổi base URL và model ID trong ứng dụng hiện có:

Base URL: https://api.z.ai/api/paas/v4/
Model: glm-5.3-flash

Để triển khai đầu vào hình ảnh và tham số nỗ lực suy luận, xem hướng dẫn API GLM-5.3-Flash.

Nhà cung cấp bên thứ ba

OpenRouter cung cấp mô hình với tên z-ai/glm-5.3-flash. Mô hình cũng có mặt trên:

Cloudflare Workers AI
Vercel AI Gateway
DeepInfra
Novita
GMICloud
Baseten
io.net

Giá và giới hạn có thể khác nhau đáng kể giữa các nhà phân phối.

Coding agents

GLM-5.3-Flash nằm trong Gói Lập trình GLM và được báo cáo có hạn mức sử dụng gấp ba lần GLM-5.3. Đây có thể là lý do thực tế để người đăng ký chuyển sang Flash.

Tài liệu Z.ai cũng cho biết các cuộc gọi ngoài giờ cao điểm tiêu thụ một nửa số điểm tiêu chuẩn.

Tự lưu trữ

Trọng số được cấp phép MIT và có trên Hugging Face tại zai-org/GLM-5.3-Flash.

Các công cụ hỗ trợ gồm:

vLLM
SGLang
TokenSpeed
KTransformers
Các bản lượng tử hóa GGUF cho hệ thống nhỏ hơn

Có nên sử dụng GLM-5.3-Flash?

Hãy chọn GLM-5.3-Flash nếu bạn:

Cần xử lý hình ảnh hoặc video cùng văn bản trong một yêu cầu.
Tối ưu chi phí trên mỗi token.
Muốn tự lưu trữ trọng số theo giấy phép MIT.
Xây dựng tác nhân lập trình cần phản hồi ban đầu nhanh.

Hãy chọn GLM-5.3 nếu bạn:

Cần chất lượng suy luận cao hơn một chút.
Cần thông lượng sinh token cao hơn.
Không bị giới hạn nghiêm ngặt bởi chi phí.

Xem so sánh trực tiếp GLM-5.3-Flash và GLM-5.3 để phân tích chi tiết hơn. Bài viết GLM-5.3 là gì trình bày riêng về mô hình cơ sở.

Với API tương thích OpenAI, việc thử nghiệm chỉ yêu cầu thay đổi một dòng model ID. Hãy kiểm tra cả hai mô hình trên khối lượng công việc thực tế thay vì chỉ dựa vào bảng điểm chuẩn.

Khi đánh giá thay đổi mô hình, nên gửi các yêu cầu thật và kiểm tra phản hồi thật, bao gồm cả các yêu cầu đa phương thức khó mô phỏng bằng curl. Apidog cho phép lưu các lệnh gọi thành collection có thể tái sử dụng kèm assertion. Nhờ đó, bạn có thể xác nhận cấu trúc phản hồi vẫn tương thích trước khi chuyển từ GLM-5.3 sang Flash trong môi trường production.

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

GLM-5.3-Flash còn miễn phí không?

Không. Tuần lễ Ox Alpha miễn phí đã kết thúc khi mô hình được công bố chính thức. Chương trình giảm giá ra mắt 50% kéo dài đến hết ngày 9 tháng 9 năm 2026; sau đó áp dụng giá niêm yết.

GLM-5.3-Flash có nhanh hơn GLM-5.3 không?

Không. Flash tạo khoảng 49 token mỗi giây, so với 86 token mỗi giây của GLM-5.3. Tuy nhiên, Flash bắt đầu phản hồi nhanh hơn với thời gian tạo token đầu tiên 1,52 giây.

Mô hình có thực sự hỗ trợ một triệu token không?

Cửa sổ được cấu hình là 1.048.576 token, được xác nhận trong cấu hình mô hình và bởi Artificial Analysis. OpenRouter liệt kê 1.310.720 token, nhưng nên xem đây là thông tin từ nhà cung cấp chứ không phải thông số kỹ thuật chuẩn của mô hình.

Mô hình có nhận video không?

Tài liệu Z.ai liệt kê văn bản, hình ảnh, video và tệp là các loại đầu vào. Vì hỗ trợ video mới hơn và ít được sử dụng rộng rãi, hãy kiểm thử với dữ liệu thực tế trước khi phụ thuộc vào tính năng này.

Trọng số sử dụng giấy phép nào?

MIT. Trọng số được công bố trên Hugging Face tại zai-org/GLM-5.3-Flash.

Ox Alpha Chính Là GLM-5.3-Flash: Giải Mã Chiến Lược Ra Mắt Mô Hình Thầm Lặng

Sebastian Petrus — Thu, 27 Aug 2026 03:26:17 +0000

Ox Alpha là ai? Cách một mô hình ẩn danh trở thành GLM-5.3-Flash

Ngày 20/8/2026, một mô hình tên ox-alpha xuất hiện trên các nền tảng suy luận bên thứ ba: không nhà cung cấp, không thông báo, không thẻ mô hình, nhưng có cửa sổ ngữ cảnh 1 triệu token và miễn phí hoàn toàn.

Hãy dùng thử Apidog ngay hôm nay

Chỉ trong vài ngày, nó trở thành một trong các mô hình được dùng nhiều nhất. Khoảng 48 giờ sau, cộng đồng xác định nó có khả năng thuộc Zhipu. Ngày 26/8, Z.ai xác nhận: Ox Alpha chính là GLM-5.3-Flash, còn tuần miễn phí là một thử nghiệm có chủ đích.

Đây là cách nhận diện mô hình ẩn danh, lý do nhà cung cấp thực hiện chiến lược này, và cách sử dụng chúng an toàn trong quy trình đánh giá.

Dòng thời gian

20/8: ox-alpha xuất hiện trên OpenRouter và OpenCode dưới dạng mô hình ẩn danh, với ngữ cảnh 1M token và giá bằng 0.

20–22/8: Lượng sử dụng tăng nhanh. Nhà phát triển bắt đầu định tuyến các tác vụ thực tế qua mô hình và phân tích đầu ra để truy tìm nguồn gốc.

Khoảng 48 giờ sau: Đồng thuận của cộng đồng nghiêng về Zhipu, dựa trên hành vi mô hình thay vì bất kỳ tiết lộ chính thức nào.

26/8: Z.ai công bố GLM-5.3-Flash và xác nhận Ox Alpha là mô hình này.

Cách nhận diện một mô hình ẩn danh

Bạn không cần quyền truy cập nội bộ. Hãy so sánh hành vi của mô hình với các họ mô hình đã biết.

1. Kiểm tra hành vi tokenizer

Mỗi họ mô hình chia văn bản thành token theo cách khác nhau. Hãy thử:

Chuỗi ký tự bất thường
Emoji liên tiếp
Văn bản pha trộn nhiều hệ chữ
Khoảng trắng dài
Mã có thụt lề lạ

Quan sát số token, lỗi xử lý hoặc vị trí mô hình gặp khó khăn. Tokenizer thường được kế thừa giữa các bản phát hành trong cùng một họ và khó che giấu.

2. Đặt câu hỏi gián tiếp về danh tính

Câu hỏi trực tiếp thường bị né tránh hoặc trả lời sai. Thay vào đó, dùng các lời nhắc gián tiếp để tìm:

Cách diễn đạt đặc trưng
Giới hạn kiến thức
Phong cách từ chối
Dấu vết dữ liệu huấn luyện mô tả chính mô hình

3. So sánh phong cách đầu ra

Theo dõi cách mô hình:

Từ chối một yêu cầu
Mở đầu câu trả lời
Cấu trúc danh sách
Dùng tiêu đề và định dạng
Phản hồi bằng nhiều ngôn ngữ

Những đặc điểm này thường phản ánh quá trình hậu huấn luyện của từng phòng thí nghiệm.

4. Kiểm tra hành vi đa ngôn ngữ

Mô hình được huấn luyện mạnh bằng tiếng Trung và tiếng Anh sẽ phản hồi khác với mô hình coi tiếng Trung là ngôn ngữ ít phổ biến. Đây là một tín hiệu đáng chú ý đối với các mô hình của Zhipu.

5. So sánh “hình dạng” benchmark

Chạy một bộ đánh giá ngắn và so sánh điểm mạnh, điểm yếu với các mô hình đã biết. Đừng chỉ nhìn điểm tuyệt đối; hãy quan sát danh mục nào nổi trội hoặc yếu hơn tương đối.

6. Quan sát đặc điểm phục vụ

Độ trễ, thông lượng, giới hạn ngữ cảnh và tham số endpoint hỗ trợ đều có thể tiết lộ thông tin về hạ tầng phía sau.

Quy trình tương tự từng xuất hiện khi Pony Alpha được suy đoán là mô hình DeepSeek hoặc GLM.

Vì sao nhà cung cấp phát hành ẩn danh?

Một đợt ra mắt âm thầm đem lại dữ liệu mà beta kín khó tạo ra.

Lưu lượng thực ở quy mô thực

Người thử nghiệm nội bộ không thể tái hiện tất cả tình huống ngoài đời. Lưu lượng công khai giúp phát hiện:

Prompt kỳ lạ hoặc lạm dụng
Ngữ cảnh cực lớn
Vòng lặp gọi công cụ
Các lỗi hiếm chỉ xuất hiện dưới tải thực

Kiểm tra tải trung thực

Z.ai cho biết tuần Ox Alpha chạy hoàn toàn trên bộ tăng tốc nội địa Trung Quốc, dùng hạ tầng dựa trên SGLang. Họ tuyên bố chi phí phục vụ mỗi token tương đương phần cứng NVIDIA thông thường.

Đây là tuyên bố từ nhà cung cấp, chưa có xác minh độc lập. Tuy nhiên, loại tuyên bố này chỉ đáng tin cậy hơn sau khi hệ thống đã phục vụ lưu lượng thực.

Phản hồi không bị ảnh hưởng bởi thương hiệu

Người dùng đánh giá một “mô hình ẩn danh tốt” khác với một mô hình có logo. Sự ẩn danh giúp loại bỏ cả thiên kiến tích cực lẫn tiêu cực về thương hiệu.

Tiếp thị sau khi tiết lộ

Khi công bố chính thức, nhiều nhà phát triển đã có trải nghiệm thực tế và đánh giá tích cực. Điều này thường thuyết phục hơn một bảng benchmark do nhà cung cấp tự công bố.

Rủi ro là thiện chí người dùng: ai đã xây dựng giải pháp trong tuần miễn phí sẽ phải trả phí sau đó. Với Ox Alpha, ưu đãi giảm giá 50% khi ra mắt kéo dài đến 9/9/2026 để giảm tác động này.

GLM-5.3-Flash thực chất là gì?

GLM-5.3-Flash là mô hình mixture-of-experts (MoE) với:

320B tham số
18B tham số hoạt động trên mỗi token
Cửa sổ ngữ cảnh 1.048.576 token
Cơ chế chú ý tuyến tính và thưa thớt kết hợp
Khả năng đa phương thức bản địa đầu tiên trong dòng GLM-5
Trọng số phát hành trên Hugging Face theo giấy phép MIT

Theo Artificial Analysis, mô hình đạt 57 điểm trên Chỉ số Thông minh, so với 60 của GLM-5.3 lớn hơn và mức trung bình 27 của các mô hình mã nguồn mở cùng kích thước.

Xem thêm phân tích chi tiết về GLM-5.3-Flash.

Một yếu tố quan trọng giải thích tuần miễn phí: Z.ai cho biết GLM-5.3-Flash dùng lượng tính toán attention ít hơn khoảng ba lần và KV cache nhỏ hơn khoảng 4,4 lần so với GLM-5.3. Chi phí suy luận thấp hơn khiến việc tặng quyền truy cập miễn phí ít rủi ro hơn.

Điều này có ý nghĩa gì với bạn?

Mô hình ẩn danh thường là bản phát hành sắp ra mắt

Một mô hình không thương hiệu, có ngữ cảnh lớn bất thường và miễn phí thường không phải dự án thử nghiệm cá nhân. Có nhà cung cấp đang tài trợ chi phí suy luận.

Miễn phí chỉ là tạm thời

Ox Alpha chuyển từ miễn phí sang 0,15 USD cho mỗi triệu token đầu vào trong sáu ngày. Giá rẻ không đồng nghĩa với miễn phí.

Không đưa mô hình ẩn danh vào production

Mô hình ẩn danh không có:

Cam kết phiên bản
Thông báo ngừng hỗ trợ
Thẻ mô hình
Hỗ trợ kỹ thuật
Đảm bảo mô hình không bị thay thế đột ngột

Dùng để đánh giá thì hợp lý. Dùng làm phụ thuộc production thì không.

Lưu kết quả đánh giá thay vì chỉ thử ngẫu nhiên

Một tuần dùng thực tế tạo ra dữ liệu giá trị hơn benchmark của nhà cung cấp — nếu bạn lưu dữ liệu đó.

Hãy lưu prompt đánh giá dưới dạng collection trong Apidog, dùng biến môi trường cho model ID và base URL. Khi có một mô hình ẩn danh mới, bạn có thể chạy lại cùng bộ thử nghiệm và so sánh kết quả thay vì dựa vào cảm giác.

Ba tín hiệu quan trọng từ tuần miễn phí

1. Chi phí phục vụ thấp là lợi thế kiến trúc

Attention ít hơn khoảng ba lần và KV cache nhỏ hơn khoảng 4,4 lần không phải chỉ là quyết định định giá. Đây là lựa chọn kiến trúc, khiến giá niêm yết thấp có khả năng bền vững hơn mức khuyến mãi ngắn hạn.

Xem phân tích giá GLM-5.3-Flash.

2. Trọng số mở không đồng nghĩa chỉ dùng qua API

Mô hình được phát hành trên Hugging Face theo giấy phép MIT. Nếu có đủ phần cứng, bạn có thể chạy mô hình cục bộ vô thời hạn.

Xem hướng dẫn chạy GLM-5.3-Flash cục bộ.

3. Khả năng đa phương thức có thể bị bỏ sót

Trong tuần ẩn danh, phần lớn người dùng chỉ dùng Ox Alpha như mô hình văn bản vì không có thẻ mô hình cho biết nó hỗ trợ hình ảnh. Điều này cho thấy điểm yếu của việc ra mắt không thương hiệu: lưu lượng lớn có thể chỉ tập trung vào những khả năng mà người dùng giả định mô hình sở hữu.

Xem hướng dẫn Vision API của GLM-5.3-Flash.

Kết luận

Ox Alpha không phải trường hợp cuối cùng. Việc triển khai ẩn danh trên router bên thứ ba đang trở thành giai đoạn tiền phát hành, nằm giữa đánh giá nội bộ và ra mắt công khai.

Cách tiếp cận thực tế là:

Thử nghiệm mô hình ẩn danh.
Chạy bộ đánh giá đã lưu.
Ghi lại độ trễ, chi phí và chất lượng đầu ra.
Không xây dựng production trên mô hình chưa có danh tính và cam kết hỗ trợ.

Tuần miễn phí là cơ hội nghiên cứu, không phải chuỗi cung ứng đáng tin cậy.

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

ox-alpha là gì?

Đó là GLM-5.3-Flash, mô hình đa phương thức 320B-A18B với trọng số mở của Z.ai, được triển khai ẩn danh từ 20/8/2026 và tiết lộ ngày 26/8.

Mô hình còn miễn phí không?

Không. Thời gian miễn phí đã kết thúc khi có thông báo. Ưu đãi giảm giá 50% kéo dài đến 9/9/2026, sau đó giá niêm yết là 0,15 USD cho đầu vào và 0,50 USD cho đầu ra trên mỗi triệu token.

Mọi người xác định đó là mô hình của Zhipu như thế nào?

Bằng cách so sánh tokenizer, phong cách đầu ra, hành vi đa ngôn ngữ, mẫu từ chối và hình dạng benchmark với các bản phát hành GLM đã biết.

Tại sao nhà cung cấp tặng mô hình miễn phí?

Để thu thập lưu lượng thực, kiểm tra tải, nhận phản hồi không bị ảnh hưởng bởi thương hiệu và tạo cộng đồng người dùng trước ngày ra mắt.

Có nên dùng mô hình ẩn danh trên OpenRouter trong production không?

Không. Hãy dùng chúng để đánh giá, không phải làm phụ thuộc production.

Truy vết Cuộc gọi Công cụ AI Agent: Nên ghi gì trên mỗi Yêu cầu

Sebastian Petrus — Wed, 26 Aug 2026 10:58:10 +0000

Khả năng quan sát cho tác nhân AI: Ghi lại quyết định, không chỉ mã HTTP 200

Một người dùng báo cáo rằng tác nhân (agent) “đã làm điều gì đó lạ” vào chiều hôm qua. Bạn mở nhật ký và thấy:

INFO  agent run started
INFO  calling tool: updateOrder
INFO  tool returned 200
INFO  agent run completed

Tác nhân đã gọi updateOrder, nhưng bạn không biết với đối số nào, dựa trên lệnh nào, vì sao chọn công cụ đó hay API đã trả về dữ liệu gì. Lần chạy được xem là thành công theo mọi chỉ số hiện có, nhưng bạn không thể tái tạo bất kỳ quyết định nào.

Dùng thử Apidog hôm nay

Các hệ thống tác nhân thường thất bại theo những cách chỉ trở nên rõ ràng khi nhìn lại. Vì vậy, nhật ký không phải phần phụ; nó là một sản phẩm của hệ thống.

Bài viết về khả năng quan sát API tập trung vào phía dịch vụ. Bài này tập trung vào lớp tác nhân nằm trên dịch vụ đó: cần ghi gì trong mỗi lần gọi công cụ, cách liên kết quyết định của mô hình với yêu cầu HTTP, dữ liệu nào phải biên tập và cách biến dấu vết thành bài kiểm thử.

Apidog đặc biệt hữu ích khi bạn đã có một dấu vết: cách nhanh nhất để hiểu một cuộc gọi sai thường là phát lại nó với cùng điểm cuối và quan sát kết quả.

Ba lớp cần có trong một dấu vết

Một tác nhân tạo ra sự kiện ở ba cấp độ. Hầu hết nhóm chỉ ghi lại lớp ở giữa.

1. Lớp suy luận

Đây là nơi mô hình đưa ra quyết định:

Nó nhìn thấy gì trong ngữ cảnh?
Những công cụ nào được cung cấp?
Nó chọn công cụ nào?
Các đối số được tạo ra là gì?

2. Lớp công cụ

Đây là trình thực thi của ứng dụng:

Xác thực đối số.
Áp dụng chính sách.
Ánh xạ lời gọi công cụ thành yêu cầu HTTP.
Xử lý kết quả và lỗi.

3. Lớp HTTP

Đây là đường truyền thực tế:

Phương thức và URL.
Tiêu đề và nội dung.
Mã trạng thái.
Độ trễ, số lần thử lại và khóa idempotency.

Gỡ lỗi gần như luôn liên quan đến nhiều lớp.

“Tác nhân gửi sai ID khách hàng” là lỗi suy luận, nhưng chỉ hiển thị ở lớp HTTP.

“API trả về mã 200 với nội dung trống” là lỗi HTTP, sau đó có thể xuất hiện dưới dạng một chuỗi suy luận kỳ lạ.

Nếu ba lớp không được liên kết bằng định danh chung, bạn sẽ phải tương quan theo thời gian. Cách này nhanh chóng thất bại khi hai lần chạy chồng lấn.

Quy tắc nền tảng:

Một trace_id cho mỗi lần chạy tác nhân.
Một span_id cho mỗi lần gọi công cụ.
Cả hai xuất hiện trong mọi bản ghi ở cả ba lớp.

Dấu vết OpenTelemetry đã mô hình hóa chính xác cấu trúc này. Các quy ước ngữ nghĩa GenAI cũng đang bổ sung cách đặt tên thuộc tính để dữ liệu có thể di chuyển giữa các công cụ.

Ghi lại gì trong mỗi lần gọi công cụ?

Một bản ghi hữu ích có thể trông như sau:

{
  "trace_id": "run_01J8ZK3M2Q",
  "span_id": "call_004",
  "parent_span_id": "call_003",
  "timestamp": "2026-08-26T14:03:11.482Z",
  "agent": "billing",
  "step": 4,

  "tool_name": "refundOrder",
  "tool_args": { "orderId": "ord_92", "amount": 1200, "reason": "duplicate" },
  "tools_available": ["getOrder", "listOrders", "refundOrder", "voidInvoice"],

  "http": {
    "method": "POST",
    "url": "/v1/orders/ord_92/refund",
    "request_body_hash": "sha256:1f4c...",
    "status": 200,
    "duration_ms": 412,
    "retry_count": 1,
    "idempotency_key": "9f2b7c14-6d3a-4b18"
  },

  "outcome": "success",
  "tokens": { "prompt": 8420, "completion": 96 },
  "policy": { "approval_required": true, "approved_by": "user_31", "dry_run": false }
}

Năm trường sau thường quyết định việc điều tra có thành công hay không.

`tool_args`

Đây là trường bị thiếu nhiều nhất và cũng là trường cần có nhất.

Ghi lại đối số do mô hình tạo ra trước khi trình thực thi chuẩn hóa hoặc biến đổi chúng. Nếu tác nhân gửi sai ID, lỗi sẽ xuất hiện ở đây.

`tools_available`

Trường này giải thích lựa chọn của mô hình. Nếu mô hình chọn một công cụ bất thường, câu hỏi đầu tiên là: nó còn những lựa chọn nào khác?

Chi phí lưu trữ rất nhỏ nhưng giá trị chẩn đoán lớn.

`retry_count`

Trường này phân biệt:

API chậm nhưng thành công ngay lần đầu.
API thất bại hai lần rồi mới thành công.
Trình thực thi đã gửi cùng một yêu cầu nhiều lần.

Nếu không ghi lại, ba lần thử có thể trông giống như một cuộc gọi duy nhất.

`outcome`

Dùng một enum rõ ràng thay vì suy ra kết quả từ mã trạng thái:

success
failed
timed_out
blocked_by_policy
rejected_by_human

Hai trạng thái cuối rất quan trọng. Một cuộc gọi bị chính sách chặn là hàng rào bảo vệ đang hoạt động, không nhất thiết là lỗi. Trộn chúng với lỗi kỹ thuật sẽ làm sai tỷ lệ thất bại.

`policy`

Đây là dấu vết kiểm toán. Khi có người hỏi một hành động mang tính phá hủy có được phê duyệt hay không, trường này phải trả lời được:

Có cần phê duyệt không?
Ai đã phê duyệt?
Phê duyệt lúc nào?
Có đang chạy ở chế độ dry_run không?

policy nên được kết hợp với cơ chế thực thi trong bài viết về hàng rào bảo vệ tác nhân AI.

Ghi lại quyết định, không chỉ hành động

Các lỗi khó nhất của tác nhân thường là lỗi lựa chọn. Để tái tạo chúng, hãy ghi lại đủ ngữ cảnh quyết định.

Lưu định nghĩa công cụ hoặc mã băm

Lưu phiên bản định nghĩa công cụ được sử dụng trong lần chạy, hoặc ít nhất là mã băm của chúng.

Khi độ chính xác lựa chọn thay đổi, nghi phạm đầu tiên thường là phần mô tả công cụ. Một mã băm cho biết ngay liệu bộ công cụ có thay đổi giữa lần chạy tốt và lần chạy lỗi hay không.

Văn bản trong schema có thể ảnh hưởng đáng kể đến hành vi mô hình. Xem thêm về thiết kế lược đồ công cụ cho tác nhân.

Ghi lại mô hình và cấu hình

Bản ghi lần chạy nên chứa:

ID mô hình.
Nhiệt độ (temperature).
Phiên bản lời nhắc (prompt_version).
Phiên bản ứng dụng hoặc agent runtime.

Hành vi có thể thay đổi giữa các phiên bản mô hình. Nếu thiếu những trường này, bạn có thể mất nhiều thời gian điều tra code trong khi nguyên nhân nằm ở cấu hình.

Ghi lại những gì mô hình đã thấy

Không phải lúc nào cũng nên lưu toàn bộ prompt vì chi phí và dữ liệu nhạy cảm. Một phương án cân bằng là lưu:

Số lượng token.
Kích thước prompt.
Mã băm prompt.
Phiên bản prompt.

Một lần chạy có prompt lớn gấp đôi bình thường là tín hiệu cho thấy dữ liệu ngoài dự kiến đã được thêm vào ngữ cảnh.

Lưu kết quả công cụ thô

Nếu trình thực thi cắt gọn phản hồi trước khi gửi cho mô hình, hãy lưu toàn bộ payload trong dấu vết.

Bài viết về giữ phản hồi công cụ khỏi cửa sổ ngữ cảnh đề cập cách kiểm soát dữ liệu đưa vào prompt. Tuy nhiên, bản ghi quan sát vẫn nên giữ phiên bản thô, nếu chính sách dữ liệu cho phép. Nếu không, bạn sẽ không biết dữ liệu bị thiếu từ API hay bị cắt trong runtime.

Biên tập dữ liệu trước khi lưu trữ

Dấu vết tác nhân đặc biệt nhạy cảm vì nó chứa cả yêu cầu lẫn lý do xung quanh yêu cầu đó. Prompt cũng thường thu thập dữ liệu cá nhân ngoài dự kiến.

Bốn quy tắc sau giúp giảm rủi ro.

Không lưu thông tin xác thực

Loại bỏ:

Authorization.
API key.
Cookie.
URL đã ký.
Token trong query string hoặc request body.

Thay vì lưu giá trị, hãy lưu định danh của credential, chẳng hạn credential_id hoặc key_id. Bài viết về API key đặc quyền tối thiểu cho tác nhân giải thích vì sao việc định danh credential vẫn hữu ích: bạn biết tác nhân nào đã thực hiện hành động mà không làm lộ bí mật.

Biên tập tại ranh giới ghi nhật ký

Không nên đợi đến lúc truy vấn dữ liệu mới lọc bí mật. Khi đó bí mật đã có thể được ghi vào đĩa, sao chép hoặc đưa vào bản sao lưu.

Hãy biên tập trong middleware ghi nhật ký, trước khi bản ghi rời khỏi tiến trình.

Băm payload không thể lưu

Mã băm nội dung yêu cầu cho phép chứng minh hai cuộc gọi giống hệt nhau, phục vụ phần lớn điều tra về trùng lặp mà không cần giữ payload.

Ví dụ:

{
  "request_body_hash": "sha256:1f4c...",
  "payload_stored": false
}

Phân cấp thời gian lưu trữ

Một chính sách thực tế có thể là:

Dấu vết đầy đủ: giữ trong một tuần.
Dấu vết đã biên tập, không có payload: giữ trong một năm.
Chỉ số tổng hợp: giữ lâu hơn nếu cần.

Phần lớn việc gỡ lỗi diễn ra trong vài ngày, còn câu hỏi kiểm toán thường xuất hiện trong vài tháng.

Biến dấu vết thành bài kiểm thử

Theo dõi tốt không chỉ giúp gỡ lỗi nhanh hơn. Nó còn tạo ra các trường hợp kiểm thử thực tế.

Phát lại mọi lần chạy thất bại

Mỗi lần chạy thất bại là một kịch bản:

Lấy các lệnh gọi công cụ từ dấu vết.
Phát lại chúng với API.
Xác nhận lỗi.
Sửa nguyên nhân.
Giữ bản phát lại làm bài kiểm thử hồi quy.

Trong Apidog, bạn có thể dựng lại yêu cầu lỗi dưới dạng một trường hợp đã lưu, xác nhận hành vi sau khi sửa và chạy nó trong CI. Một sự cố đơn lẻ từ đó trở thành phạm vi kiểm thử lâu dài.

Dùng dấu vết để chọn mock

Dấu vết cho biết trực tiếp:

Điểm cuối nào được gọi nhiều nhất.
Trạng thái lỗi nào thực sự xảy ra.
Dữ liệu nào thường xuất hiện trong phản hồi.
Công cụ nào có ảnh hưởng lớn nhất đến luồng chạy.

Hãy xây dựng mock quanh các trường hợp này thay vì đoán. Xem thêm bài viết về chạy tác nhân với API mock thay vì production.

Phát hiện thay đổi chậm

Theo dõi hàng tuần:

Phân phối lựa chọn công cụ.
Tỷ lệ thử lại theo điểm cuối.
Số lần gọi trên mỗi tác vụ hoàn thành.
Tỷ lệ lần chạy bị chính sách chặn.

Một thay đổi nhỏ trong các chỉ số này có thể là tín hiệu sớm trước khi trở thành sự cố. Các kiểm thử cấp hợp đồng, như trong hướng dẫn kiểm thử hợp đồng API, có thể phát hiện thay đổi ở thượng nguồn.

Ba câu hỏi mà dấu vết phải trả lời được

“Tác nhân đã tính phí sai khách hàng như thế nào?”

Bạn cần:

Đối số mô hình tạo ra.
URL cuối cùng sau khi resolve.
Bước ngay trước đó.
Kết quả của các công cụ trước đó.

Trong nhiều trường hợp, ID bắt nguồn từ một kết quả công cụ có nhiều bản ghi khớp, rồi mô hình chọn bản ghi đầu tiên. Dấu vết phải cho thấy kết quả, sự mơ hồ và lựa chọn cuối cùng.

Nếu không có tool_args, bạn chỉ còn mã HTTP 200 và một khách hàng không hài lòng.

“Tác nhân ngừng hoạt động từ thứ Ba vì sao?”

So sánh lần chạy tốt và lần chạy lỗi theo từng trường:

ID mô hình.
Mã băm bộ công cụ.
Phiên bản prompt.
Kích thước phản hồi trung bình.
Số token.
Số lần thử lại.

Một trong các trường này thường cho biết điều gì đã thay đổi. Đây là lý do bản ghi lần chạy phải chứa cấu hình, không chỉ danh sách sự kiện.

“Có ai phê duyệt hành động này không?”

Khối policy phải trả lời trực tiếp:

approval_required.
approved_by.
Thời điểm phê duyệt.
Trạng thái thực thi.

Hãy ghi lại tại thời điểm quyết định được đưa ra, không cố tái tạo sau này.

Điểm chung của cả ba câu hỏi: không câu nào được trả lời bằng “công cụ trả về 200”. Chúng cần các trường nhỏ, rẻ để lưu nhưng không thể khôi phục sau khi sự việc xảy ra.

Lấy mẫu có chọn lọc

Theo dõi đầy đủ mọi lần chạy có thể tốn kém khi khối lượng lớn. Tuy nhiên, lưu lượng tác nhân không đồng nhất nên không nên lấy mẫu ngẫu nhiên theo tỷ lệ cố định.

Luôn giữ lại

Mọi lần chạy thất bại.
Mọi lần chạy bị chính sách chặn.
Mọi lần chạy chứa thao tác ghi.
Mọi lần chạy vượt ngưỡng độ trễ.
Mọi lần chạy có retry hoặc timeout.

Đây là những lần chạy người dùng và đội vận hành có khả năng cần điều tra nhất.

Có thể lấy mẫu

Các lần chạy chỉ đọc thành công thường chiếm phần lớn khối lượng và ít thú vị khi xem riêng lẻ. Bạn vẫn cần giữ đủ mẫu để tính đường cơ sở.

Chương về giám sát hệ thống phân tán trong SRE của Google giải thích rõ vì sao nên lấy mẫu theo tín hiệu thay vì theo khối lượng. Nguyên tắc này áp dụng trực tiếp cho tác nhân.

Ngay cả khi loại bỏ payload, hãy giữ bản ghi khung gồm:

Tên công cụ.
Kết quả.
Thời lượng.
Trạng thái.
Retry count.

Bản ghi khung rất nhỏ nhưng vẫn hỗ trợ các chỉ số quan trọng. Payload và prompt là phần tốn kém nhất, nên loại bỏ chúng trước.

Cẩn thận với tail sampling

Nếu quyết định giữ hay bỏ dấu vết sau khi lần chạy kết thúc, quyết định đó phải xảy ra sau khi biết kết quả cuối cùng.

Một lần chạy có thể trông bình thường ở bước 3 nhưng thất bại ở bước 9. Vì vậy, cần đệm dữ liệu trong khi chạy thay vì loại bỏ ngay từng span.

Nên lưu dấu vết ở đâu?

Các nguyên tắc trên giả định bạn sở hữu hệ thống lưu trữ. Điều này phù hợp khi tác nhân là dịch vụ của bạn gọi API của bạn, nhưng không phù hợp khi tác nhân chạy trên máy của nhà phát triển hoặc khách hàng.

Khi đó, dấu vết có thể nằm ở bất kỳ thiết bị đầu cuối nào đã chạy tác nhân.

Sharkly áp dụng cách tiếp cận khác: gắn dấu vết thực thi vào nhiệm vụ mà tác nhân được giao. Lịch sử chạy, nhật ký thực thi và kết quả nằm cạnh mục tiêu, trạng thái và chuỗi bình luận nơi con người xem xét công việc.

Lợi ích thực tế nằm ở khả năng truy xuất. Câu hỏi “Tại sao tác nhân làm điều đó?” trở thành việc mở nhiệm vụ thay vì tìm đúng máy, phiên làm việc và lịch sử terminal.

Cách này không thay thế OpenTelemetry, hệ thống quan sát hay môi trường runtime. Claude Code và Codex vẫn thực hiện công việc. Nó chỉ thay đổi nơi bản ghi kết thúc khi tác nhân không phải là một dịch vụ do bạn triển khai.

Theo dõi bốn chỉ số quan trọng

Dấu vết chỉ có giá trị khi được sử dụng. Bốn chỉ số sau nên có trên dashboard.

1. Số lần gọi trên mỗi tác vụ hoàn thành

Đây là thước đo hiệu quả trực tiếp nhất.

Nếu chỉ số tăng, tác nhân có thể đang khám phá quá nhiều, thường do:

Mô tả công cụ kém.
Prompt phình to.
Một điểm cuối bắt đầu lỗi.
Kết quả API không đủ rõ ràng.

2. Tỷ lệ retry theo điểm cuối

Chỉ số này xếp hạng các phụ thuộc kém tin cậy nhất và cho thấy khi nào một điểm cuối suy giảm.

Bài viết về phục hồi lỗi tác nhân trình bày cách xử lý các điểm cuối đứng đầu danh sách.

3. Tỷ lệ bị chính sách chặn

Chỉ số này nên thấp và ổn định.

Một mức tăng đột biến có thể cho thấy:

Tác nhân đang cố thực hiện hành động không được phép.
Chính sách quá chặt và trở thành nút cổ chai.
Prompt hoặc mô tả công cụ đã thay đổi.

4. Thời gian đến lần gọi công cụ đầu tiên

Khởi đầu chậm thường liên quan đến prompt quá lớn. Kích thước prompt là một dạng “phình to âm thầm”: nó có thể tăng dần mà không ai chủ động quyết định tăng.

Checklist triển khai

[ ] Một trace_id cho mỗi lần chạy và một span_id cho mỗi lần gọi công cụ.
[ ] ID được ghi ở cả lớp suy luận, lớp công cụ và lớp HTTP.
[ ] Đối số mô hình được ghi trước khi chuẩn hóa.
[ ] Danh sách công cụ có sẵn được lưu trong mỗi lần gọi.
[ ] Kết quả dùng enum rõ ràng, bao gồm cả trạng thái bị chính sách chặn.
[ ] Số lần retry được tách khỏi số lần gọi.
[ ] Model, temperature, phiên bản prompt và mã băm bộ công cụ nằm trong bản ghi lần chạy.
[ ] Kết quả công cụ thô được lưu, không chỉ phiên bản đã cắt gọn gửi cho mô hình.
[ ] Credential được loại bỏ trong middleware.
[ ] Payload không thể lưu được thay bằng mã băm.
[ ] Thời gian lưu trữ được phân cấp theo độ nhạy cảm.
[ ] Dấu vết lỗi có thể chuyển thành trường hợp kiểm thử và phát lại.
[ ] Tail sampling chỉ quyết định sau khi biết kết quả cuối cùng.

Mục tiêu rất đơn giản: khi có người hỏi vì sao tác nhân làm điều gì đó, bạn trả lời được từ bản ghi thay vì phỏng đoán.

Bạn có thể tải Apidog để phát lại các cuộc gọi trong dấu vết và lưu các bản tái tạo thành bài kiểm thử.

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

Nên dùng OpenTelemetry hay công cụ quan sát tác nhân chuyên dụng?

Dùng OpenTelemetry cho việc vận chuyển và mô hình hóa dấu vết. Nó đã xử lý tương quan, đồng thời hạ tầng hiện có của bạn có thể hiểu dữ liệu này.

Công cụ chuyên dụng cho tác nhân có thể bổ sung các chế độ xem hữu ích, nhưng dữ liệu nền vẫn nên có thể di chuyển được.

Chi phí lưu trữ đầy đủ dấu vết là bao nhiêu?

Thường thấp hơn dự kiến nếu áp dụng lưu trữ phân cấp:

Payload đầy đủ trong vài ngày.
Bản ghi có cấu trúc, không chứa nội dung, trong thời gian dài hơn.
Mã băm và kích thước prompt thay vì lưu prompt mặc định.

Prompt thường là phần tốn kém nhất.

Có cần ghi lại văn bản suy luận của mô hình không?

Thông thường là không.

Công cụ được chọn, các đối số được tạo ra và những lựa chọn có sẵn đã giải thích phần lớn quyết định. Nếu nhà cung cấp cho phép truy cập nội dung suy luận, chỉ nên lưu cho các lần chạy thất bại và xem đó là dữ liệu nhạy cảm.

Làm sao theo dõi nhiều tác nhân?

Giữ một trace_id cho toàn bộ tác vụ và cấp một span riêng cho mỗi tác nhân. Ghi việc chuyển giao giữa các tác nhân thành một sự kiện.

Xem thêm về chuyển giao đa tác nhân và truyền ngữ cảnh.

Nếu tác nhân chạy trên máy khách hàng thì sao?

Ghi nhật ký cục bộ, biên tập tích cực và chỉ gửi số liệu tổng hợp, trừ khi người dùng đồng ý chia sẻ thêm.

Tên công cụ, kết quả và thời lượng thường đủ cho giám sát cấp đội ngũ mà không cần payload rời khỏi thiết bị.

Mã băm nội dung yêu cầu có thực sự hữu ích không?

Có, đối với phần lớn câu hỏi phổ biến.

Mã băm chứng minh hai cuộc gọi giống hệt nhau, hỗ trợ điều tra các lần ghi trùng lặp mà không cần lưu payload. Kết hợp mã băm với idempotency key còn giúp ngăn chặn nhiều trường hợp trùng lặp ngay từ đầu.

Tài liệu tham khảo

Cửa sổ ngữ cảnh Agent AI: Tối ưu hóa phản hồi API cồng kềnh

Sebastian Petrus — Wed, 26 Aug 2026 10:57:25 +0000

Thiết kế phản hồi API gọn nhẹ cho tác nhân AI

Tác nhân yêu cầu hồ sơ khách hàng. API trả về thông tin khách hàng, 200 đơn hàng gần nhất, từng mặt hàng, dấu thời gian ở ba định dạng và _links cho mỗi mục. Bốn mươi nghìn token rơi vào cửa sổ ngữ cảnh, trong khi tác nhân chỉ cần địa chỉ email.

Dùng thử Apidog ngay hôm nay

Lặp lại điều đó bốn lần trong một lượt chạy, tác nhân sẽ dùng gần hết ngân sách chỉ để đọc JSON không cần thiết. Sau đó nó quên hướng dẫn ban đầu, tóm tắt thay vì hoàn thành nhiệm vụ, và chi phí tăng trong khi chất lượng giảm.

Đây là vấn đề thiết kế API, không phải vấn đề prompt. Mọi trường trong phản hồi đều cạnh tranh với hướng dẫn, lịch sử hội thoại và kế hoạch của tác nhân trong một cửa sổ ngữ cảnh cố định. Việc cạn kiệt ngữ cảnh là một nguyên nhân khiến tác nhân AI thất bại trong môi trường sản xuất.

Apidog giúp bạn đo kích thước phản hồi thực tế của từng endpoint và mô phỏng phản hồi đã được cắt giảm trước khi API được triển khai.

Token đi đâu?

Các phản hồi dành cho trình duyệt và dashboard thường chứa dữ liệu không cần thiết cho tác nhân:

Envelope rườm rà: data, meta, links, included có thể làm tăng gấp đôi tải trọng. Hypermedia hữu ích cho client theo liên kết, nhưng URL là token mà tác nhân hiếm khi cần.
Khóa lặp lại: Danh sách 200 mục, mỗi mục 15 trường, phải lặp lại khoảng 3.000 chuỗi khóa JSON.
Mở rộng lồng nhau mặc định: Khách hàng → đơn hàng → mặt hàng là một cây dữ liệu tăng kích thước rất nhanh.
Định dạng dư thừa: created_at, created_at_unix và created_at_human trả ba lần cùng một thông tin.
Giá trị null hoặc rỗng: Phát mọi trường chưa được đặt là lãng phí hoàn toàn.

Chi phí token phụ thuộc vào kích thước văn bản đã tuần tự hóa, không phải số bản ghi. Hai trăm bản ghi phẳng với năm trường có thể rẻ hơn một đối tượng lồng nhau sâu.

Quy tắc 1: Trả về trường, không phải toàn bộ tài nguyên

Cho phép người gọi chọn đúng trường cần dùng:

GET /v1/customers/8812?fields=id,email,plan,status

{ "id": "8812", "email": "dana@example.com", "plan": "pro", "status": "active" }

Thay đổi này thường giảm khoảng 90% kích thước của một bản ghi đầy đủ. Hướng dẫn thiết kế API của Google mô tả mẫu field mask; GraphQL cũng giải quyết vấn đề này bằng cách bắt buộc chọn trường.

Khi triển khai:

Xác thực danh sách trường bằng schema và từ chối tên không tồn tại. Đừng âm thầm bỏ qua một trường bị mô hình “ảo giác”.
Dùng một tập trường mặc định nhỏ cho client không gửi fields; đừng mặc định trả về mọi thứ.
Đặt fields là bắt buộc trong schema công cụ:

{
  "name": "getCustomer",
  "description": "Lấy thông tin khách hàng bằng ID. Luôn truyền `fields` với chỉ những gì bạn cần. Các trường có sẵn: id, email, name, plan, status, created_at, billing_address, order_count.",
  "input_schema": {
    "type": "object",
    "required": ["customerId", "fields"],
    "properties": {
      "customerId": { "type": "string" },
      "fields": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Tên các trường cần trả về. Giữ danh sách này ở mức tối thiểu."
      }
    }
  }
}

Mô tả công cụ là nơi mô hình học các quy tắc gọi API. Cả hướng dẫn gọi hàm của OpenAI và tài liệu sử dụng công cụ của Anthropic đều nhấn mạnh điều này. Một tham số tùy chọn dễ bị bỏ qua; tham số bắt buộc khiến mô hình phải chọn dữ liệu cần thiết.

Quy tắc 2: Luôn giới hạn danh sách

Endpoint danh sách không giới hạn là nguồn phổ biến gây tràn ngữ cảnh. Một yêu cầu “các đơn hàng gần đây” không nên trả về mọi đơn hàng từ năm 2019.

Đặt giới hạn cứng ở phía máy chủ. Nếu tác nhân gửi limit=5000, hãy trả tối đa 100 mục và cho biết phản hồi đã bị giới hạn.

Kết hợp các nguyên tắc trong bài viết về phân trang REST API và thiết kế phân trang cho hàng triệu bản ghi:

Giới hạn mỗi trang khoảng 20–50 mục với bản ghi thông thường.
Trả total để tác nhân biết có bao nhiêu dữ liệu mà không phải phân trang chỉ để đếm.
Dùng cursor pagination thay vì offset, vì offset lệch khi dữ liệu thay đổi giữa các lần gọi.
Trả tín hiệu rõ ràng như "truncated": true để mô hình biết còn dữ liệu chưa xem.

Ngoài ra, hãy cung cấp cách tránh phân trang hoàn toàn: endpoint count, tìm kiếm có bộ lọc hẹp, hoặc endpoint tóm tắt. Phản hồi rẻ nhất là phản hồi không trả dữ liệu thừa.

Quy tắc 3: Cắt giảm ở lớp công cụ khi không sở hữu API

API bên thứ ba có thể không hỗ trợ chọn trường. Khi đó, cắt giảm phản hồi giữa HTTP client và mô hình:

KEEP = {
    "getCustomer": ["id", "email", "plan", "status"],
    "listOrders": ["id", "total", "status", "created_at"],
}

def project(tool_name, payload):
    keep = KEEP.get(tool_name)
    if keep is None:
        return payload
    if isinstance(payload, list):
        return [{k: item.get(k) for k in keep if k in item} for item in payload]
    return {k: payload.get(k) for k in keep if k in payload}

Để cách này vận hành tốt:

Lưu toàn bộ phản hồi trong nhật ký chạy, nhưng chỉ gửi phần đã chiếu cho mô hình. Xem thêm cách truy vết các lệnh gọi công cụ của tác nhân.
Báo rõ trường đã bỏ qua, ví dụ: "_omitted": ["billing_address", "notes", "metadata"].
Với dữ liệu dạng bảng, chuyển JSON sang CSV hoặc bảng Markdown để tên cột chỉ xuất hiện một lần.

id,total,status,created_at
ord_91,4900,paid,2026-08-21
ord_92,1200,refunded,2026-08-22

Quy tắc 4: Tóm tắt trên máy chủ cho trường hợp nặng

Nhiều câu hỏi không cần bản ghi chi tiết. Ví dụ: “Khách hàng này có khoản thanh toán thất bại nào trong tháng này không?” là câu hỏi boolean. Trả 40 đối tượng thanh toán để mô hình tự suy luận là tốn kém.

Với câu hỏi lặp lại, hãy thêm endpoint trả lời trực tiếp: tóm tắt trạng thái tài khoản, tổng hợp theo trạng thái hoặc một tập dữ liệu nhỏ. Đây là cải tiến giá trị nhất: thay vì cắt giảm phản hồi lớn, bạn tránh tạo nó.

Giữ các phản hồi tóm tắt ổn định về hình dạng và có version. Prompt của tác nhân phụ thuộc vào shape phản hồi; thay đổi âm thầm có thể làm nó hỏng. Tham khảo điều gì xảy ra khi API thay đổi bên dưới tác nhân và chiến lược tạo phiên bản API.

Đo lường trước và sau

Đừng tối ưu mù quáng. Đo ba chỉ số:

Byte mỗi phản hồi, theo endpoint: Gửi yêu cầu thực tế đến mọi công cụ tác nhân có thể gọi. Endpoint vượt vài kilobyte là ứng viên cần tối ưu. Trong Apidog, bạn có thể chạy endpoint, xem trực tiếp kích thước phản hồi và lưu request để kiểm tra lại sau này.
Token mỗi lần gọi công cụ: Byte chỉ là đại diện; token mới là hóa đơn. Đưa tải trọng qua tokenizer của nhà cung cấp, chẳng hạn tiktoken, rồi xếp hạng endpoint theo chi phí.
Ngữ cảnh dùng cho mỗi lượt chạy: Theo dõi tổng token trong toàn bộ tác vụ. Nếu lượt chạy chạm giới hạn ngữ cảnh, cắt giảm sẽ giúp tác vụ hoàn thành thay vì chỉ rẻ hơn.

Sau đó, mô phỏng phản hồi mục tiêu bằng mock server trước khi đội API triển khai. Điều quan trọng là xác minh tác nhân vẫn thành công với ít dữ liệu hơn. Xem quy trình chạy tác nhân với API giả lập thay vì môi trường production.

Một phản hồi tốt trông như thế nào?

Phản hồi thân thiện với tác nhân nên nhỏ gọn, phẳng và trung thực về dữ liệu bị bỏ qua:

{
  "customer": { "id": "8812", "email": "dana@example.com", "plan": "pro" },
  "recent_orders": [
    { "id": "ord_91", "total_cents": 4900, "status": "paid" },
    { "id": "ord_92", "total_cents": 1200, "status": "refunded" }
  ],
  "recent_orders_total": 47,
  "truncated": true,
  "_omitted": ["billing_address", "metadata", "order_line_items"]
}

Phản hồi này dưới 200 token, trả lời câu hỏi phổ biến, cho biết có 47 đơn hàng thay vì ngụ ý chỉ có hai, và giúp mô hình biết dữ liệu nào có thể yêu cầu tiếp theo.

Bắt đầu với endpoint đắt nhất: đo lường, thêm chọn trường, giới hạn danh sách, rồi chạy lại tác nhân. Chênh lệch thường đủ lớn để biện minh cho phần còn lại của công việc. Tải xuống Apidog để đo lường và mô phỏng trong cùng một dự án.

Ba tình huống thực tế

1. Phân loại hỗ trợ

Một tác nhân đọc ticket, lấy thông tin khách hàng và quyết định có cần leo thang không. Phiên bản ngây thơ lấy toàn bộ hồ sơ khách hàng cùng 50 ticket gần nhất, tiêu tốn 30.000 token trước khi đọc được khiếu nại hiện tại.

Phiên bản tốt hơn gọi endpoint tóm tắt trả về gói dịch vụ, trạng thái, số ticket đang mở và ngày liên hệ gần nhất. Khoảng 80 token, nhưng quyết định tốt hơn vì tín hiệu liên quan không bị chôn vùi.

2. Tác nhân vận hành nội bộ

Một tác nhân triển khai kiểm tra tình trạng của 40 dịch vụ. Đối tượng trạng thái đầy đủ có thể làm tràn cửa sổ ở dịch vụ thứ 12.

Hãy trả một dòng cho mỗi dịch vụ: tên, trạng thái và tỷ lệ lỗi. Toàn bộ 40 dịch vụ sẽ vừa trong vài trăm token, cho phép tác nhân suy luận trên cả hệ thống thay vì quên nửa đầu danh sách.

3. Nhập liệu và đối chiếu dữ liệu

Một tác nhân đối chiếu hóa đơn với thanh toán. Trả toàn bộ tài liệu hóa đơn khiến nó thất bại sau vài chục bản ghi.

Trả id, amount_cents, date và reference dưới dạng CSV cho phép nó xử lý vài trăm bản ghi trong một lần gọi, vì phép so sánh chỉ dùng bốn trường này.

Mẫu chung: tác nhân cần bề mặt ra quyết định, nhưng API thường trả về một tài liệu đầy đủ.

Bạn cần lịch sử chạy để thấy mô hình

Một lượt chạy chỉ cho biết có một phản hồi lớn. Xu hướng thực sự—endpoint nào vượt ngân sách và tần suất ra sao—chỉ xuất hiện sau nhiều lượt chạy.

Với dịch vụ tự triển khai, đó là telemetry của bạn. Với tác nhân lập trình thực hiện công việc được giao, nền tảng chạy tác nhân cần lưu dấu vết và kết quả. Sharkly lưu lịch sử thực thi theo Task, giúp so sánh giữa các lần chạy mà không cần tái tạo phiên terminal.

Thực thi ngân sách mà không có lịch sử chỉ cho bạn biết “có thứ gì đó quá lớn”, chứ không cho biết nên sửa endpoint nào trước.

Đặt ngân sách cho từng công cụ

Đừng chỉ giới hạn tổng ngữ cảnh của toàn bộ lượt chạy. Hãy đặt ngân sách cho mỗi công cụ, ví dụ 1.500 token.

Khi phản hồi vượt giới hạn:

Cắt giảm theo phần trường đã chọn.
Thêm dấu chỉ trường bị bỏ qua.
Ghi nhận sự kiện vượt ngân sách.

Bạn sẽ có danh sách endpoint thường xuyên vượt ngưỡng, được xếp hạng theo tần suất gọi—đó chính là hàng đợi tối ưu hóa.

Ngân sách theo công cụ cũng bảo vệ khỏi các trường hợp đuôi dài: endpoint nhỏ trong môi trường thử nghiệm có thể trở nên khổng lồ với khách hàng có 4.000 đơn hàng. Giới hạn cứng biến tình huống đó thành phản hồi đã cắt giảm thay vì một tác vụ thất bại lúc 2 giờ sáng.

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

Cắt bớt phản hồi có rủi ro nếu tác nhân cần dữ liệu bị thiếu?

Chỉ rủi ro khi bạn che giấu việc cắt bớt. Hãy trả tín hiệu rõ ràng và danh sách trường bị bỏ qua để mô hình có thể yêu cầu thêm. Cắt giảm âm thầm mới là nguyên nhân gây câu trả lời sai.

Có nên dùng GraphQL thay REST cho tác nhân?

GraphQL buộc chọn trường, nên giải quyết vấn đề này gọn gàng. Tuy nhiên, nó chuyển độ phức tạp sang việc tạo truy vấn, và mô hình thường viết truy vấn không hợp lệ. Thêm fields vào REST thường là thay đổi nhỏ hơn.

Phản hồi công cụ nên nhỏ đến mức nào?

Mục tiêu thực tế:

Dưới 1.000 token cho một lần đọc bản ghi.
Dưới 2.000 token cho một danh sách.

Vượt các mức này, hãy hỏi liệu tác nhân cần bản ghi hay chỉ cần câu trả lời.

Prompt caching có giải quyết vấn đề không?

Không hoàn toàn. Caching giảm chi phí của ngữ cảnh lặp lại, nhưng không giải phóng không gian cửa sổ ngữ cảnh. Phản hồi 40.000 token được cache vẫn chiếm 40.000 token.

Còn phản hồi nhị phân và tệp?

Không đưa trực tiếp vào ngữ cảnh. Lưu trữ tệp, cung cấp tham chiếu cùng mô tả ngắn, và cho tác nhân một công cụ riêng để trích xuất đúng phần cần thiết.

Nên cắt giảm trong API hay wrapper công cụ?

Cắt trong API khi bạn sở hữu nó, vì mọi client đều hưởng lợi và dữ liệu thừa không phải truyền qua mạng. Cắt trong wrapper khi đó là API bên thứ ba. Làm cả hai là tốt nhất.

Tính Lũy Đẳng Tác nhân AI: Ngăn Chặn Tính Phí Kép Khi Thử Lại

Sebastian Petrus — Wed, 26 Aug 2026 10:57:19 +0000

Tính bất biến cho tác nhân AI: ngăn thử lại tạo giao dịch trùng lặp

Tác nhân của bạn gọi endpoint thanh toán, máy chủ đã ghi nhận giao dịch nhưng phản hồi bị timeout trên đường về. Không thấy mã 200, tác nhân thử lại — và khách hàng bị tính phí hai lần dù log không báo lỗi rõ ràng.

Dùng thử Apidog ngay hôm nay

Đây là khác biệt quan trọng giữa tác nhân và API client thông thường: người dùng thường chờ hoặc kiểm tra trước khi bấm lại; tác nhân có thể thử lại 3–4 lần trong vài giây. Chính sách retry giúp tác nhân bền bỉ hơn, nhưng cũng làm tăng nguy cơ ghi dữ liệu trùng lặp.

Giải pháp là tính bất biến (idempotency): một yêu cầu lặp lại phải tạo ra cùng kết quả với một yêu cầu duy nhất.

Bài viết này tập trung vào cách:

Tạo khóa bất biến mà tác nhân có thể tái sử dụng khi retry.
Lưu và xử lý khóa đúng ở phía máy chủ.
Kiểm thử để chứng minh lần gọi thứ hai không tạo hiệu ứng mới.
Theo dõi lần chạy đã thực hiện thao tác nào.

Để hiểu rộng hơn về các lỗi tác nhân trong môi trường thực tế, xem bài viết về độ tin cậy của tác nhân AI trong production.

Apidog hữu ích ở giai đoạn kiểm thử: bạn có thể gửi cùng một request nhiều lần, lưu kịch bản và chạy nó trong CI để phát hiện hồi quy.

Vì sao tác nhân dễ tạo bản sao hơn con người?

Ba đặc điểm khiến lưu lượng từ tác nhân dễ sinh thao tác trùng lặp:

Retry mạnh mẽ

Framework tác nhân thường retry khi gặp lỗi mạng tạm thời. Backoff và circuit breaker là cần thiết, nhưng chúng cũng làm tăng số lần một request đến máy chủ. Xem thêm hướng dẫn về khôi phục lỗi cho tác nhân.
Timeout mang tính mơ hồ

Một 504 từ proxy có thể nghĩa là máy chủ chưa xử lý request, hoặc đã xử lý xong nhưng phản hồi bị mất. Tác nhân thường retry thay vì gọi API để kiểm tra trạng thái trước.
Retry toàn bộ workflow

Nếu bước 1 tạo đơn hàng và bước 4 thất bại, việc khởi động lại workflow có thể tạo đơn hàng thứ hai. Với tác nhân đa bước, ranh giới retry không luôn rõ ràng vì mô hình có thể quyết định bắt đầu lại từ đâu.

Vấn đề không phải tác nhân gửi request sai. Chúng gửi request đúng — nhiều hơn một lần.

Tính bất biến thực sự đảm bảo điều gì?

Một thao tác là bất biến khi gọi nhiều lần có cùng tác động với gọi một lần.

Theo RFC 9110, GET, PUT và DELETE là các phương thức bất biến. POST không bất biến, nên thường được dùng cho các thao tác rủi ro như tạo đơn hàng, gửi email hoặc bắt đầu chuyển khoản.

Phân biệt hai khái niệm:

Bất biến không đồng nghĩa với an toàn. DELETE là bất biến: gọi năm lần vẫn chỉ xóa một tài nguyên. Nhưng nó vẫn là thao tác phá hủy. Với tác nhân, quyền đọc và quyền ghi cần được tách riêng bằng API key có đặc quyền tối thiểu.
Bất biến không yêu cầu phản hồi giống byte-for-byte. Lần gọi lại có thể trả về phản hồi đã lưu hoặc mã trạng thái khác. Điều quan trọng là trạng thái máy chủ không đổi: một giao dịch, một đơn hàng, một email.

Dùng `Idempotency-Key` cho các thao tác `POST`

Mô hình phổ biến là client tạo khóa và gửi kèm request. Máy chủ lưu khóa cùng kết quả xử lý; request sau dùng cùng khóa sẽ nhận lại kết quả đó thay vì thực hiện công việc lần nữa.

Stripe đã phổ biến cách tiếp cận này trong tài liệu về idempotent request. IETF cũng đang chuẩn hóa header Idempotency-Key.

POST /v1/payments HTTP/1.1
Host: api.yourservice.com
[REDACTED CREDENTIAL] [REDACTED]...
Idempotency-Key: 9f2b7c14-6d3a-4b18-9d55-1e2a7c0b4f31
Content-Type: application/json

{
  "amount": 4900,
  "currency": "usd",
  "customer_id": "cus_8812",
  "description": "Pro plan, August"
}

Khóa thường là UUID. Máy chủ cần lưu:

Khóa.
Dấu vân tay của payload.
Trạng thái xử lý.
Mã trạng thái và response body.
Thời điểm hết hạn.

Tạo khóa mà tác nhân thực sự tái sử dụng

Sai lầm phổ biến là để tool wrapper tạo UUID mới cho từng HTTP attempt. Khi đó retry dùng khóa khác và hoàn toàn mất tác dụng.

Quy tắc: tạo khóa khi tác nhân quyết định thực hiện một thao tác logic, rồi tái sử dụng khóa đó cho mọi lần thử lại của thao tác ấy.

import uuid

class PaymentTool:
    def __init__(self, client):
        self.client = client
        self._keys = {}

    def charge(self, task_id, step_id, amount, customer_id):
        # One key per (task, step). Retries of the same step reuse it.
        op = f"{task_id}:{step_id}"
        if op not in self._keys:
            self._keys[op] = str(uuid.uuid4())

        return self.client.post(
            "/v1/payments",
            headers={"Idempotency-Key": self._keys[op]},
            json={"amount": amount, "customer_id": customer_id},
        )

Để khóa tồn tại qua lần khởi động lại tiến trình, dùng khóa xác định từ ID tác vụ, ID bước và payload:

import hashlib

def idempotency_key(task_id: str, step_id: str, payload: dict) -> str:
    raw = f"{task_id}|{step_id}|{sorted(payload.items())}"
    return hashlib.sha256(raw.encode()).hexdigest()[:32]

Không tạo khóa từ timestamp hoặc giá trị ngẫu nhiên được sinh lại khi retry. Nếu tác nhân khởi động một tác vụ mới thực sự, task_id mới sẽ tạo ra khóa mới — đúng với ý nghĩa nghiệp vụ.

Máy chủ cần làm gì?

Máy chủ không chỉ tra cứu khóa; nó phải xử lý cả tính nhất quán và cạnh tranh đồng thời.

Claim khóa trước khi làm việc

Chèn khóa vào bảng có unique constraint trước khi thực hiện thao tác ghi.
Từ chối cùng khóa nhưng payload khác

Nếu request hash khác, trả về 422. Không âm thầm trả response cũ vì điều đó che giấu lỗi client.
Xử lý request đang chạy

Nếu request đầu tiên với cùng khóa chưa hoàn thành, trả 409 để client back off thay vì cạnh tranh.
Lưu kết quả hoàn tất

Lưu status code và response body, sau đó trả lại đúng kết quả đã lưu cho các request sau.

CREATE TABLE idempotency_records (
  key             TEXT PRIMARY KEY,
  request_hash    TEXT NOT NULL,
  state           TEXT NOT NULL,      -- in_progress | completed
  response_status INT,
  response_body   JSONB,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
  expires_at      TIMESTAMPTZ NOT NULL
);

Đặt TTL cho khóa. 24 giờ thường đủ cho hầu hết retry window thực tế và cũng là mặc định Stripe sử dụng. Giữ khóa vĩnh viễn chỉ làm bảng dữ liệu phình to.

Kiểm thử: lần gọi thứ hai không được thay đổi gì

Happy path không đủ để chứng minh idempotency hoạt động, vì hai giao dịch thành công đều có thể trả 200.

Thay vào đó, hãy kiểm thử dựa trên trạng thái:

Response body lần hai phải chứa cùng ID tài nguyên như lần đầu.
GET danh sách tài nguyên sau đó chỉ trả về một bản ghi.
Số dư, bộ đếm hoặc side effect chỉ thay đổi một lần.

Trong Apidog, tạo một kịch bản gồm:

Gửi POST với Idempotency-Key cố định.
Gửi lại request hoàn toàn giống hệt.
Lưu ID từ response đầu tiên và xác minh response thứ hai trả lại cùng ID.
Gọi endpoint liệt kê tài nguyên và xác minh chỉ có một bản ghi.

Lưu kịch bản này và chạy trong CI khi thay đổi payment flow. Cách làm này cũng phù hợp với kiểm thử hợp đồng API.

Đừng bỏ qua hai trường hợp sau:

Cùng khóa, payload khác: phải nhận 422, không phải success âm thầm.
Request trùng lặp đồng thời: gửi hai request cùng lúc và xác minh chỉ một request thực hiện thao tác. Kiểm thử tuần tự sẽ không phát hiện unique constraint bị thiếu.

Nếu payment API chưa tồn tại, hãy tạo mock có ngữ nghĩa idempotency ngay từ đầu, bao gồm 422 khi payload không khớp. Điều này cho phép bạn luyện retry logic của tác nhân trước khi chạm vào production. Xem thêm lý do tác nhân nên dùng mock API thay vì môi trường production.

Khi không thể thêm khóa bất biến

Nếu API bên thứ ba không hỗ trợ idempotency, ưu tiên các phương án sau:

Thiết kế thao tác vốn đã bất biến

Dùng PUT /orders/{client_order_id} thay vì POST /orders nếu bạn kiểm soát API. Client chọn resource ID, nên retry cùng request không tạo đơn hàng mới.
Kiểm tra trước khi ghi

Cho tác nhân tìm bản ghi có natural key tương ứng trước khi tạo. Cách này yếu hơn do vẫn có race condition, nhưng giảm rủi ro timeout-retry phổ biến.
Khử trùng lặp ở downstream

Với event hoặc message, gắn message ID ổn định và yêu cầu consumer bỏ qua bản sao. Đây là thực hành chuẩn trong event-driven system; xem hướng dẫn thiết kế webhook đáng tin cậy.
Yêu cầu phê duyệt của con người

Với thao tác không thể đảo ngược và không thể làm bất biến, dùng approval gate. Đây là mô hình phù hợp khi chi phí của thao tác trùng lặp quá cao; xem thêm về hàng rào bảo vệ cho tác nhân AI.

Theo dõi lần chạy nào đã tạo dữ liệu

Idempotency ngăn bản sao nhưng không cho biết attempt nào đã tạo bản ghi. Vì vậy, hãy log task_id, step_id, idempotency key và kết quả của từng attempt.

Nếu tác nhân chạy trong coding runtime, nền tảng cũng nên liên kết thao tác ghi với task và execution run tương ứng. Ví dụ, Sharkly gắn từng lần chạy với Tác vụ nguồn, trạng thái thực thi và kết quả, giúp truy ngược thao tác lặp lại về một run cụ thể thay vì một retry ẩn danh.

Checklist trước khi triển khai

[ ] Mọi tool ghi dữ liệu mà tác nhân gọi đều yêu cầu Idempotency-Key.
[ ] Tool wrapper tạo khóa từ task và step, không phải từ từng retry.
[ ] Máy chủ claim khóa trước khi thực hiện công việc.
[ ] Cùng khóa nhưng payload khác trả về lỗi.
[ ] Request trùng lặp đồng thời được xử lý bằng unique constraint ở database.
[ ] Có kịch bản kiểm thử xác minh request thứ hai không tạo side effect.
[ ] Kịch bản được chạy trong CI.
[ ] Khóa có TTL và dữ liệu hết hạn được dọn dẹp.

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

Có cần khóa bất biến cho tool chỉ đọc không?

Không. GET đã an toàn và bất biến. Retry chỉ làm tăng độ trễ, không tạo side effect. Chỉ dùng khóa cho thao tác tạo, tính phí, gửi hoặc thay đổi trạng thái.

Nên tạo khóa trong tác nhân hay tool wrapper?

Trong tool wrapper, dựa trên ID tác vụ và ID bước. Không để mô hình tự tạo khóa: mô hình có thể tạo giá trị mới khi retry hoặc tạo va chạm giữa các tác vụ.

Request lặp lại nên trả status code nào?

Trả lại status code đã lưu từ request gốc. Nếu request đầu trả 201, request lặp lại cũng nên trả 201 cùng response body. Có thể thêm header Idempotent-Replay: true để hỗ trợ gỡ lỗi.

Nên giữ khóa bao lâu?

24 giờ bao phủ gần như mọi retry window. Giữ lâu hơn hiếm khi hữu ích và làm tăng kích thước bảng không giới hạn. Retry sau TTL nên được coi là thao tác mới.

Idempotency có thay thế transaction không?

Không. Idempotency ngăn request trùng lặp tạo side effect trùng lặp; transaction đảm bảo một request đơn lẻ là atomic. Bạn cần cả hai, và nên claim idempotency key trong cùng transaction với thao tác nghiệp vụ khi có thể.

Kiểm thử mà không có nhà cung cấp thanh toán thật như thế nào?

Trỏ tác nhân tới mock triển khai Idempotency-Key, bao gồm cả 422 khi payload không khớp. Bạn có thể tải Apidog để đặt mock và kịch bản kiểm thử retry trong cùng một dự án.