GLM-5.3 实用指南：始终在线思维、三个努力级别和 API 支持矩阵

标题：GLM-5.3 实用指南：始终在线思维、三个努力级别和 API 支持矩阵

描述：2026 年 8 月的 GLM-5.3 指南：始终在线思维，三个推理努力级别，推理摘要，平行工具调用，结构化输出和自动缓存——包含经过验证的 AIHubMix 聊天 / 响应 / 消息示例。

本文涵盖了 GLM-5.3 的关键 API 更改和使用说明。GLM-5.3 是 Z.ai 于 2026 年 8 月 14 日发布的旗舰模型——它使用与 GLM-5.2 完全相同的基础模型，所有的提升均来自后期训练。在 AIHubMix 上，模型 ID 为 coding-glm-5.3（目前为限时预览路线），可通过聊天完成、响应和 Claude 兼容的消息 API 获得。另请参见：Z.ai 官方发布博客。

每个部分中的“验证”结论和示例响应来自于 2026 年 8 月 14 日通过 AIHubMix API（聊天完成 / 响应 / 消息）进行的实际调用。

1. 模型规格一览

验证：max_tokens: 999999 返回 400，错误正文中明确列出了有效范围——上限确实经过验证，而不是静默截断。

# max_tokens=999999 -> HTTP 400
"max_tokens 参数无效：值必须在 [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 按照正常方式返回）——该值根据官方通道语义自动转换，而不是被拒绝。如果您的客户端依赖于“关闭思维以节省令牌”，请切换到 reasoning_effort: "low"。

验证：reasoning_effort 的超出枚举值也返回 200，没有错误（根据官方文档回退到默认 max）；low 与 max 显示预期的轻思维趋势（在同一算术问题上，27 与 39 个推理令牌）。

聊天完成

思维内容在 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, 默认 max
    extra_body={"thinking": {"type": "enabled"}},
    messages=[
        {"role": "user", "content": "计算 (17*23-19*11) 的平方根，向下取整。仅限数字。"}
    ],
)

print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)   # 观察到：“13”

验证：usage.completion_tokens_details.reasoning_tokens 报告思维使用情况——在同一问题上，reasoning_effort="low" 为 27，"max" 为 39。

响应

思维内容作为 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="法国的首都是什么？仅限城市名称。",
)

# 观察到的 response.output 项类型：["reasoning", "message"]
# reasoning 项：{"type": "reasoning", "summary": [{"type": "summary_text", "text": "用户在询问..."}]}
# usage.output_tokens_details.reasoning_tokens: 80

验证：默认请求（根本没有 reasoning 参数）已经包含 reasoning 项和 summary_text —— 无需显式选择加入。

消息

思维内容作为原生 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": "法国的首都是什么？仅限城市名称。"}
    ],
)

# 观察到的 response.content 块类型：["thinking", "text"]

验证：思维块默认返回；在此 API 上 thinking: {"type": "disabled"} 同样返回 200，思维仍然发生（与官方“禁用转换为低，请求继续”的通道语义一致）。

3. 工具调用和并行工具

功能调用在所有三个 API 上均已验证工作；在响应 API 上，我们还观察到在单个回合内的并行工具调用（Z.ai 明确声明 supports_parallel_tool_calls: true 适用于 GLM-5.3）。上游限制：在 tools 中最多 128 个功能；tool_choice 原生仅支持 auto。

聊天完成

completion = client.chat.completions.create(
    model="coding-glm-5.3",
    messages=[{"role": "user", "content": "今天北京的天气怎么样？"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取城市天气",
            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        },
    }],
)

# 观察到：finish_reason "tool_calls"，在 tool_calls 中有一个 get_weather 调用

验证：tool_choice: "none" 可用——同样的天气问题返回纯文本，没有工具调用。

响应

response = client.responses.create(
    model="coding-glm-5.3",
    input="检查今天上海和北京的天气",
    parallel_tool_calls=True,
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "获取城市天气",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
)

# 观察到：单个回合返回 2 个并行 function_call 输出项（每个城市一个）

验证：在一个回合中进行 2 次并行工具调用，符合官方 supports_parallel_tool_calls: true 的声明。

消息

response = client.messages.create(
    model="coding-glm-5.3",
    max_tokens=4096,
    tools=[{
        "name": "get_weather",
        "description": "获取城市天气",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    messages=[{"role": "user", "content": "今天北京的天气怎么样？"}],
)

# 观察到：stop_reason "tool_use"；内容包含一个 tool_use 块

❗ 验证：在此 API 上，模型 仍然生成工具调用，即使在 tool_choice: {"type": "none"} 之后——要禁用工具，请完全删除 tools 参数，或在聊天完成 API 上使用 tool_choice: "none"。

4. 结构化输出

response_format 支持 text 和 json_object；上游未列出 json_schema 模式。当您需要严格的模式一致性时，请在提示中嵌入 JSON Schema 并进行客户端验证。

聊天完成

completion = client.chat.completions.create(
    model="coding-glm-5.3",
    messages=[
        {"role": "user", "content": "法国的首都是什么？以 JSON 格式回答，键为 \"answer\"。"}
    ],
    response_format={"type": "json_object"},
)

# 观察到的响应内容：{"answer": "巴黎"}

验证：输出是有效的 JSON，包含请求的键。

响应

response = client.responses.create(
    model="coding-glm-5.3",
    input="法国的首都是什么？以 JSON 格式回答，键为 \"answer\"。",
    text={"format": {"type": "json_object"}},
)

# 观察到的输出文本：{"answer": "巴黎"}

消息

# 在提示中指定 JSON 结构；观察到的输出是有效的 JSON
response = client.messages.create(
    model="coding-glm-5.3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "法国的首都是什么？以 JSON 格式回答，键为 \"answer\"。"}
    ],
)

# 观察到的响应文本：{"answer": "巴黎"}

5. 上下文缓存是自动的

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

聊天完成

# 使用相同长前缀的第二次调用
"prompt_tokens_details": {"cached_tokens": 960}

验证：两次连续调用中的第二次命中 960 个缓存令牌。

响应

# 使用相同长前缀的第二次调用
"input_tokens_details": {"cached_tokens": 960}

消息

# 命中通过 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 之间有所不同——消息 API 拒绝超出范围的 temperature: 3，返回 400 并明确列出有效范围 [0,1]，而聊天完成 / 响应则静默接受相同的超出范围值并返回 200。在跨 API 迁移时，请不要依赖网关捕获超出范围的采样值。

# 消息 API 使用 temperature=3 -> HTTP 400
"temperature 参数无效：值必须在 [0,1] 之间"

7. 能力 × API 支持矩阵

以下每个单元均通过 2026 年 8 月 14 日通过 AIHubMix 实时 API 的实际调用进行了验证；单元显示每个 API 的参数/字段拼写。

常见问题

GLM-5.3 在 AIHubMix 上的模型 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 级别）。要节省思维令牌，请发送 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；对于严格的模式，请在提示中嵌入 JSON Schema 并进行客户端验证。

coding-glm-5.3 是生产版本吗？
目前是限时预览路线（Z.ai 的模型 API 文档将官方 API 标记为“即将推出”）；AIHubMix 将在商业 API 发布后及时跟进。有关当前定价和状态，请参见模型页面。

有关定价和实时状态，请参见 GLM-5.3 模型页面；有关更多模型，请访问 模型画廊。