ZhiPuAI Image Generation

Spring AI 支持智谱AI的图像生成模型 CogView。

Spring AI supports CogView, the Image generation model from ZhiPuAI.

Prerequisites

你需要使用智谱AI创建一个API来访问智谱AI语言模型。

You will need to create an API with ZhiPuAI to access ZhiPu AI language models.

在` ZhiPu AI registration page 创建一个账户并在 API Keys page `生成令牌。

Create an account at ZhiPu AI registration page and generate the token on the API Keys page.

Spring AI 项目定义了一个名为 spring.ai.zhipuai.chat.api-key 的配置属性，您应该将其设置为从 API 密钥页面获取的 API 密钥值。

The Spring AI project defines a configuration property named spring.ai.zhipuai.api-key that you should set to the value of the API Key obtained from the API Keys page.

你可以在` application.properties `文件中设置此配置属性：

You can set this configuration property in your application.properties file:

spring.ai.zhipuai.api-key=<your-zhipuai-api-key>

为了在处理 API 密钥等敏感信息时增强安全性，您可以使用 Spring 表达式语言 (SpEL) 引用自定义环境变量：

For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference a custom environment variable:

# In application.yml
spring:
  ai:
    zhipuai:
      api-key: ${ZHIPUAI_API_KEY}

# In your environment or .env file
export ZHIPUAI_API_KEY=<your-zhipuai-api-key>

你也可以在应用程序代码中以编程方式设置此配置：

You can also set this configuration programmatically in your application code:

// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("ZHIPUAI_API_KEY");

Add Repositories and BOM

Spring AI 工件发布在 Maven Central 和 Spring Snapshot 存储库中。请参阅“添加 Spring AI 仓库”部分，将这些仓库添加到您的构建系统。

Spring AI artifacts are published in Maven Central and Spring Snapshot repositories. Refer to the Artifact Repositories section to add these repositories to your build system.

为了帮助进行依赖项管理，Spring AI 提供了一个 BOM（物料清单）以确保在整个项目中使用一致版本的 Spring AI。有关将 Spring AI BOM 添加到你的构建系统的说明，请参阅 Dependency Management 部分。

To help with dependency management, Spring AI provides a BOM (bill of materials) to ensure that a consistent version of Spring AI is used throughout the entire project. Refer to the Dependency Management section to add the Spring AI BOM to your build system.

Auto-configuration

Spring AI 自动配置、启动器模块的工件名称发生了重大变化。请参阅 upgrade notes 以获取更多信息。

There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the upgrade notes for more information.

Spring AI 为智谱 AI 聊天客户端提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到您项目的 Maven pom.xml 文件中：

Spring AI provides Spring Boot auto-configuration for the ZhiPuAI Chat Client. To enable it add the following dependency to your project’s Maven pom.xml file:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-zhipuai</artifactId>
</dependency>

或添加到 Gradle build.gradle 构建文件中。

or to your Gradle build.gradle build file.

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-zhipuai'
}

参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

Refer to the Dependency Management section to add the Spring AI BOM to your build file.

Image Generation Properties

图像自动配置的启用和禁用现在通过带有前缀 spring.ai.model.image 的顶级属性进行配置。

Enabling and disabling of the image auto-configurations are now configured via top level properties with the prefix spring.ai.model.image.

要启用，spring.ai.model.image=stabilityai（默认启用）

To enable, spring.ai.model.image=stabilityai (It is enabled by default)

要禁用，spring.ai.model.image=none（或任何不匹配 stabilityai 的值）

To disable, spring.ai.model.image=none (or any value which doesn’t match stabilityai)

此更改旨在允许配置多个模型。

This change is done to allow configuration of multiple models.

前缀 spring.ai.zhipuai.image 是属性前缀，允许您为智谱AI配置 ImageModel 的实现。

The prefix spring.ai.zhipuai.image is the property prefix that lets you configure the ImageModel implementation for ZhiPuAI.

Property

Description

Default

spring.ai.zhipuai.image.enabled (Removed and no longer valid)

Enable ZhiPuAI image model.

true

spring.ai.model.image

Enable ZhiPuAI image model.

zhipuai

spring.ai.zhipuai.image.base-url

Optional overrides the spring.ai.zhipuai.base-url to provide chat specific url

spring.ai.zhipuai.image.api-key

Optional overrides the spring.ai.zhipuai.api-key to provide chat specific api-key

spring.ai.zhipuai.image.options.model

The model to use for image generation.

cogview-3

spring.ai.zhipuai.image.options.user

A unique identifier representing your end-user, which can help ZhiPuAI to monitor and detect abuse.

Connection Properties

前缀` spring.ai.zhipuai `用作属性前缀，允许你连接到智谱AI。

The prefix spring.ai.zhipuai is used as the property prefix that lets you connect to ZhiPuAI.

Property

Description

Default

spring.ai.zhipuai.base-url

The URL to connect to

[role="bare"]https://open.bigmodel.cn/api/paas

spring.ai.zhipuai.api-key

The API Key

Configuration Properties

Retry Properties

前缀 spring.ai.retry 用作属性前缀，允许您为智谱AI图像客户端配置重试机制。

The prefix spring.ai.retry is used as the property prefix that lets you configure the retry mechanism for the ZhiPuAI Image client.

Property Description Default

Property	Description	Default
spring.ai.retry.max-attempts	Maximum number of retry attempts.	10
spring.ai.retry.backoff.initial-interval	Initial sleep duration for the exponential backoff policy.	2 sec.
spring.ai.retry.backoff.multiplier	Backoff interval multiplier.	5
spring.ai.retry.backoff.max-interval	Maximum backoff duration.	3 min.
spring.ai.retry.on-client-errors	If false, throw a NonTransientAiException, and do not attempt retry for `4xx` client error codes	false
spring.ai.retry.exclude-on-http-codes	List of HTTP status codes that should not trigger a retry (e.g. to throw NonTransientAiException).	empty
spring.ai.retry.on-http-codes	List of HTTP status codes that should trigger a retry (e.g. to throw TransientAiException).	empty

spring.ai.retry.max-attempts

Maximum number of retry attempts.

spring.ai.retry.backoff.initial-interval

Initial sleep duration for the exponential backoff policy.

2 sec.

spring.ai.retry.backoff.multiplier

Backoff interval multiplier.

spring.ai.retry.backoff.max-interval

Maximum backoff duration.

3 min.

spring.ai.retry.on-client-errors

If false, throw a NonTransientAiException, and do not attempt retry for 4xx client error codes

false

spring.ai.retry.exclude-on-http-codes

List of HTTP status codes that should not trigger a retry (e.g. to throw NonTransientAiException).

empty

spring.ai.retry.on-http-codes

List of HTTP status codes that should trigger a retry (e.g. to throw TransientAiException).

empty

Runtime Options

ZhiPuAiImageOptions.java 提供模型配置，例如要使用的模型、质量、大小等。

The ZhiPuAiImageOptions.java provides model configurations, such as the model to use, the quality, the size, etc.

在启动时，可以使用 ZhiPuAiImageModel(ZhiPuAiImageApi zhiPuAiImageApi) 构造函数和 withDefaultOptions(ZhiPuAiImageOptions defaultOptions) 方法配置默认选项。或者，使用前面描述的 spring.ai.zhipuai.image.options.* 属性。

On start-up, the default options can be configured with the ZhiPuAiImageModel(ZhiPuAiImageApi zhiPuAiImageApi) constructor and the withDefaultOptions(ZhiPuAiImageOptions defaultOptions) method. Alternatively, use the spring.ai.zhipuai.image.options.* properties described previously.

在运行时，您可以通过向 ImagePrompt 调用添加新的、特定于请求的选项来覆盖默认选项。例如，要覆盖智谱AI特有的选项，例如质量和要创建的图像数量，请使用以下代码示例：

At runtime you can override the default options by adding new, request specific, options to the ImagePrompt call. For example to override the ZhiPuAI specific options such as quality and the number of images to create, use the following code example:

ImageResponse response = zhiPuAiImageModel.call(
        new ImagePrompt("A light cream colored mini golden doodle",
        ZhiPuAiImageOptions.builder()
                .quality("hd")
                .N(4)
                .height(1024)
                .width(1024).build())

);

除了模型特定的 ZhiPuAiImageOptions 之外，您还可以使用通过 ImageOptions 创建的可移植 ImageOptionsBuilder#builder() 实例。

In addition to the model specific ZhiPuAiImageOptions you can use a portable ImageOptions instance, created with the ImageOptionsBuilder#builder().