GLM-5.3 实战指南：始终开启的思考、三档推理强度与 API 支持矩阵

标题：GLM-5.3 实战指南：始终开启的思考、三档推理强度与 API 支持矩阵

描述：2026 年 8 月 GLM-5.3 指南：始终开启的思考（三档 reasoning_effort）、推理摘要、并行工具调用、结构化输出和自动缓存，并附经过验证的 AIHubMix Chat / Responses / Messages 示例。

本文介绍 GLM-5.3 的关键 API 变更和使用注意事项。GLM-5.3 是 Z.ai 于 2026-08-14 发布的旗舰模型，它与 GLM-5.2 使用完全相同的基础模型，所有提升都来自后训练。在 AIHubMix 上，模型 ID 为 coding-glm-5.3（目前为限时预览路由），可通过 Chat Completions、Responses 和兼容 Claude 的 Messages API 调用。另请参阅：Z.ai 官方发布博客。

各部分中标注“已验证”的结论和示例响应，均来自 2026-08-14 通过 AIHubMix API（Chat Completions / Responses / Messages）的实际调用。

1. 模型规格速览

已验证：max_tokens: 999999 返回 400，且错误信息中列出了有效范围，说明上限确实经过验证，而不是被静默截断。

# max_tokens=999999 -> HTTP 400
"max_tokens parameter invalid: value must be within [1,131072]"

2. GLM-5.3 与 GLM-5.2 对比：始终开启的思考，通过 reasoning_effort 控制强度

以下是 GLM-5.3 相对 GLM-5.2 最重要的两项 API 变更：

1. thinking.type 不再支持 disabled，思考无法关闭。官方迁移建议：原先发送 {"type": "disabled"} 的应用应改为 {"type": "enabled"}，并将 reasoning_effort 设为 "low"。
2. reasoning_effort 收窄为三档：low（轻度）/ high（增强）/ max（深度，默认）。GLM-5.2 时代的 7 值兼容映射已不再适用；Z.ai 建议编程任务使用 max。

已验证：通过 AIHubMix 发送 thinking: {"type": "disabled"} 返回 200，且思考依然发生（reasoning_content 照常返回），该值会按官方渠道语义自动转换，而不是被拒绝。如果你的客户端依赖“关闭思考以节省 token”，请改用 reasoning_effort: "low"。

已验证：reasoning_effort 的越界值同样返回 200 且不报错（按官方文档回退为默认值 max）；同一算术题上，low 与 max 的推理 token 分别为 27 和 39，思考量确实按预期减少。

Chat Completions

思考内容通过 reasoning_content 字段返回；流式输出中以 delta.reasoning_content 的形式到达。

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

completion = client.chat.completions.create(
    model="coding-glm-5.3",
    reasoning_effort="max",          # low / high / max, default max
    extra_body={"thinking": {"type": "enabled"}},
    messages=[
        {"role": "user", "content": "Compute the square root of (17*23-19*11), rounded down. Digits only."}
    ],
)

print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)   # Observed: "13"

已验证：usage.completion_tokens_details.reasoning_tokens 反映思考用量。同一问题下，reasoning_effort="low" 为 27，"max" 为 39。

Responses

思考内容以 reasoning 输出项返回，其中 summary 数组内的文本类型为 summary_text。

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

response = client.responses.create(
    model="coding-glm-5.3",
    input="What is the capital of France? City name only.",
)

# Observed response.output item types: ["reasoning", "message"]
# reasoning item: {"type": "reasoning", "summary": [{"type": "summary_text", "text": "The user is asking..."}]}
# usage.output_tokens_details.reasoning_tokens: 80

已验证：默认请求（完全不带 reasoning 参数）已经包含带有 summary_text 的 reasoning 项，无需显式开启。

Messages

思考内容以原生 thinking 内容块返回。

from anthropic import Anthropic

client = Anthropic(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com"
)

response = client.messages.create(
    model="coding-glm-5.3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "What is the capital of France? City name only."}
    ],
)

# Observed response.content block types: ["thinking", "text"]

已验证：默认返回 thinking 内容块；在该 API 上发送 thinking: {"type": "disabled"} 同样返回 200，思考依然发生（符合官方“disabled 转换为 low，请求继续”的渠道语义）。

3. 工具调用与并行工具

函数调用已在三个 API 上验证可用。在 Responses API 上，我们还观察到单轮内的并行工具调用（Z.ai 明确为 GLM-5.3 声明了 supports_parallel_tool_calls: true）。上游限制：tools 中最多 128 个函数；tool_choice 原生仅支持 auto。

Chat Completions

completion = client.chat.completions.create(
    model="coding-glm-5.3",
    messages=[{"role": "user", "content": "What's the weather in Beijing today?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather for a city",
            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        },
    }],
)

# Observed: finish_reason "tool_calls", with a get_weather call in tool_calls

已验证：tool_choice: "none" 生效，同一天气问题返回纯文本，不产生工具调用。

Responses

response = client.responses.create(
    model="coding-glm-5.3",
    input="Check today's weather in Shanghai and Beijing",
    parallel_tool_calls=True,
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Get weather for a city",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
)

# Observed: a single turn returns 2 parallel function_call output items (one for each city)

已验证：单轮内产生 2 个并行工具调用，与官方 supports_parallel_tool_calls: true 声明一致。

Messages

response = client.messages.create(
    model="coding-glm-5.3",
    max_tokens=4096,
    tools=[{
        "name": "get_weather",
        "description": "Get weather for a city",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    messages=[{"role": "user", "content": "What's the weather in Beijing today?"}],
)

# Observed: stop_reason "tool_use"; content contains a tool_use block

❗ 已验证：在该 API 上，设置 tool_choice: {"type": "none"} 后，模型仍会产生工具调用。要禁用工具，请完全移除 tools 参数，或改用 Chat Completions API 上的 tool_choice: "none"。

4. 结构化输出

response_format 支持 text 和 json_object；上游未列出 json_schema 模式。需要严格符合 schema 时，请将 JSON Schema 嵌入提示词，并在客户端进行校验。

Chat Completions

completion = client.chat.completions.create(
    model="coding-glm-5.3",
    messages=[
        {"role": "user", "content": "What is the capital of France? Answer in JSON with the key \"answer\"."}
    ],
    response_format={"type": "json_object"},
)

# Observed response content: {"answer": "Paris"}

已验证：输出为合法 JSON，并包含所请求的键。

Responses

response = client.responses.create(
    model="coding-glm-5.3",
    input="What is the capital of France? Answer in JSON with the key \"answer\".",
    text={"format": {"type": "json_object"}},
)

# Observed output text: {"answer": "Paris"}

Messages

# Specify the JSON structure in the prompt; observed output is valid JSON
response = client.messages.create(
    model="coding-glm-5.3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "What is the capital of France? Answer in JSON with the key \"answer\"."}
    ],
)

# Observed response text: {"answer": "Paris"}

5. 上下文缓存自动启用

隐式缓存默认开启，无需传递任何参数；重复的长前缀会在 usage 中报告缓存命中（字段名因 API 而异）。

Chat Completions

# usage of the second call with an identical long prefix
"prompt_tokens_details": {"cached_tokens": 960}

已验证：两次背靠背调用中，第二次命中了 960 个缓存 token。

Responses

# usage of the second call with an identical long prefix
"input_tokens_details": {"cached_tokens": 960}

Messages

# hits are reported via usage.cache_read_input_tokens
"cache_read_input_tokens": 0

已验证：本轮未能在该 API 上复现缓存命中（缓存按渠道预热，负载均衡切换可能导致未命中）。命中计数字段遵循 Anthropic 语义。

6. 采样参数与参数校验

采样遵循 GLM 系列端点的约定：temperature 取值范围为 [0, 1]，默认 1.0（注意，比 OpenAI 协议的 [0, 2] 范围更窄）；top_p 取值范围为 [0.01, 1]，默认 0.95。Z.ai 建议只调整两者之一。

已验证：不同 API 的参数校验存在差异。Messages API 对越界的 temperature: 3 返回 400，并明确给出有效范围 [0,1]；而 Chat Completions / Responses 会静默接受同样的越界值并返回 200。跨 API 迁移时，不要指望网关替你拦截越界的采样参数。

# Messages API with temperature=3 -> HTTP 400
"temperature parameter invalid: value must be within [0,1]"

7. 能力 × API 支持矩阵

以下每个单元格都已于 2026-08-14 通过 AIHubMix 实时 API 实际调用验证；单元格中显示的是各 API 对应的参数或字段写法。

常见问题

AIHubMix 上 GLM-5.3 的模型 ID 是什么？需要 [1m] 后缀吗？
模型 ID 为 coding-glm-5.3，原样使用即可。glm-5.3[1m] 是 Z.ai 为 Claude Code 客户端设计的模型名语法，与 AIHubMix 调用无关；三种 API 都不需要任何后缀。

可以关闭思考吗？
不可以。GLM-5.3 的思考始终开启，thinking.type 仅支持 enabled。在我们的测试中，发送 disabled 返回 200，但思考依然发生（按官方语义转换为 low 档位）。要节省思考 token，请发送 reasoning_effort: "low"。

GLM-5.3 与 GLM-5.2 是什么关系？
基础模型相同，所有提升都来自后训练（官方表述大意为：“它与 GLM-5.2 使用相同的基础模型，所有提升都来自后训练”）。有两项硬性 API 变更：思考不能再被关闭，且 reasoning_effort 收窄为 low/high/max 三档（默认 max）。

如果需要严格的 json_schema 结构化输出怎么办？
上游未列出 response_format: json_schema 模式。在我们的测试中，json_object JSON 模式在三种 API 上都能生成合法 JSON；如需严格的 schema，请将 JSON Schema 嵌入提示词，并在客户端进行校验。

现在 coding-glm-5.3 是正式发布版本吗？
目前它是一个限时预览通道（Z.ai 的模型 API 文档将正式 API 标注为“即将推出”）；商业 API 上线后，AIHubMix 会第一时间跟进。当前定价和状态请查看模型页面。

定价和实时状态请查看 GLM-5.3 模型页面；更多模型请访问模型广场。