28 · Z.ai

Z.ai（智谱 AI）是一家中国 AI 公司，提供 GLM 系列高性能 LLM。 Embabel 把 Z.ai 作为一等提供方集成，使用原生 Spring AI ZhiPuAI 客户端（spring-ai-zhipuai）—— 指向 Z.ai 的国际版 "PaaS v4" 端点 —— 与 Google GenAI、Mistral AI 提供方遵循相同的模式。 这种原生集成解锁了 GLM 专属特性（例如推理/"thinking"），而不是依赖 OpenAI 兼容协议。

模型定义（id、定价、知识截止、推理支持）从 classpath:models/zai-models.yml 加载，每个都被注册为一个 LlmService bean。

添加依赖（Add the Dependency）

<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-starter-zai</artifactId>
</dependency>

API Key 配置

通过**环境变量（推荐）**或 Spring 属性设置你的 Z.ai API key：

export ZAI_API_KEY=your-api-key

或在 application.yml 中：

embabel:
  agent:
    platform:
      models:
        zai:
          api-key: your-api-key

环境变量 ZAI_API_KEY 优先于属性值。 本地开发用属性，生产部署用环境变量。

可用模型（Available Models）

模型名	模型 ID	输入（每 100 万 token）	输出（每 100 万 token）
GLM-5.2	glm-5.2	$1.40	$4.40
GLM-4.7	glm-4.7	$0.60	$2.20
GLM-4.6	glm-4.6	$0.60	$2.20
GLM-4.5-Air	glm-4.5-air	$0.20	$1.10
GLM-4.7-Flash	glm-4.7-flash	免费	免费

• glm-5.2 是最新旗舰，支持最多 100 万 token 的上下文窗口 —— 应对高难度推理与编码任务的最佳默认选择。
• glm-4.7 与 glm-4.6 是强力且高性价比的通用模型。
• glm-4.5-air 以一些质量换取显著更低的延迟与成本 —— 适合多动作 Agent 流程中的中间步骤。
• glm-4.7-flash 免费，很适合大批量的抽取与分类步骤。

Embabel 的按步骤选择 LLM 能力，让 Z.ai 模型特别适合混合策略： 用 glm-4.7-flash 或 glm-4.5-air 做抽取与分类步骤，把 glm-5.2（或某个更贵的模型）只留给最后的推理步骤。

使用 Z.ai 模型

在 @LlmCall 里按名称引用，或通过 ai.withLlm() 以编程方式引用：

// 声明式
@LlmCall(llm = "glm-5.2")
fun summarize(article: Article): Summary

// 编程式
ai.withLlm("glm-4.5-air")
    .create<Classification>("Classify this input")

或者把 Z.ai 模型映射到配置里的角色：

embabel:
  models:
    llms:
      cheapest: glm-4.7-flash
      best: glm-5.2

然后用 # 前缀按角色引用：

@LlmCall(llm = "#cheapest")
fun extractEntities(text: String): EntityList

温度钳制（Temperature Clamping）

GLM 模型要求 temperature 落在 (0.0, 1.0] 区间内 —— 恰好为 0.0 是不允许的。 Embabel 的 ZaiOptionsConverter 会自动钳制 temperature（把 0.0 抬到允许的下界、1.0 保持 1.0）。 发生钳制时会输出一条 DEBUG 日志。你不需要做任何事 —— 这是透明处理的。

推理（Thinking）

GLM 模型支持原生推理。由于 Embabel 使用的是原生 ZhiPuAI 客户端， 在 LlmOptions 上启用 thinking 会打开 GLM 的原生推理模式，而不是依赖提示词约定：

ai.withLlm(
    LlmOptions.withModel("glm-4.7").withThinking(Thinking.withTokenBudget(2048))
).create<Answer>("Solve this step by step")

配置参考（Configuration Reference）

embabel:
  agent:
    platform:
      models:
        zai:
          api-key: your-api-key                      # 也可以用 ZAI_API_KEY 环境变量
          base-url: https://api.z.ai/api/paas        # 默认值；host + /api/paas 前缀（注意没有 /v4）
          max-attempts: 4                            # 重试次数（默认 4）
          backoff-millis: 1500                       # 初始退避毫秒（默认 1500）
          backoff-multiplier: 2.0                    # 退避倍数（默认 2.0）
          backoff-max-interval: 60000                # 最大退避毫秒（默认 60000）

另见

• 使用 LLM（Working with LLMs）
• 配置参考（Configuration Reference）
• Z.ai