Z.ai Integration

Z.ai (Zhipu AI) is a Chinese AI company offering the GLM family of high-performance LLMs. Embabel integrates Z.ai as a first-class provider using the native Spring AI ZhiPuAI client (spring-ai-zhipuai) — pointed at Z.ai’s international "PaaS v4" endpoint — following the same pattern as the Google GenAI and Mistral AI providers. This native integration unlocks GLM-specific features such as reasoning ("thinking"), rather than relying on the OpenAI-compatible wire protocol.

Model definitions (ids, pricing, knowledge cutoff, reasoning support) are loaded from classpath:models/zai-models.yml and each is registered as an LlmService bean.

Add the Dependency

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

API Key Configuration

Set your Z.ai API key via environment variable (recommended) or Spring property:

export ZAI_API_KEY=your-api-key

Or in application.yml:

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

Use the property for local development and the environment variable in production deployments.

Available Models

glm-5.2 is the latest flagship model, supporting up to a 1M token context window — the best default choice for demanding reasoning and coding tasks. glm-4.7 and glm-4.6 are strong, cost-effective general-purpose models. glm-4.5-air trades some quality for significantly lower latency and cost — a good choice for intermediate steps in a multi-action agent flow. glm-4.7-flash is free, well-suited to high-volume extraction and classification steps.

Using Z.ai Models

Reference models by name in @LlmCall or programmatically via ai.withLlm():

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

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

Or map Z.ai models to roles in your configuration:

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

Then reference by role with the # prefix:

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

Temperature Clamping

GLM models require temperature in the range (0.0, 1.0] — a value of exactly 0.0 is not permitted. Embabel’s ZaiOptionsConverter clamps temperature automatically:

• Values <= 0.0 are raised to 0.01
• Values > 1.0 are lowered to 1.0

A DEBUG log message is emitted whenever clamping occurs. No action is required on your part — this is handled transparently.

Reasoning (Thinking)

GLM models support native reasoning. Because Embabel uses the native ZhiPuAI client, enabling Thinking on an LlmOptions turns on GLM’s native reasoning mode rather than relying on prompt conventions:

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                   # Alternative to ZAI_API_KEY env var
          base-url: https://api.z.ai/api/paas       # Default; host + /api/paas prefix (no /v4)
          max-attempts: 4                          # Retry attempts (default: 4)
          backoff-millis: 1500                     # Initial backoff ms (default: 1500)
          backoff-multiplier: 2.0                  # Backoff multiplier (default: 2.0)
          backoff-max-interval: 60000              # Max backoff ms (default: 60000)

See Also

• Working with LLMs
• Configuration Reference
• Z.ai