MiniMax 嵌入模型

本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。 商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

Spring AI 支持来自 MiniMax 的各种 AI 语言模型。你可以通过 MiniMax 语言模型构建多语言对话助手。

先决条件

你需要创建 MiniMax API 以访问其语言模型。

请前往 MiniMax 注册页面 创建账户，并在 API Key 页面 生成访问令牌（Token）。

Spring AI 项目定义了名为 spring.ai.minimax.api-key 的配置属性，需设置为从 API Key 页面获取的密钥值。

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

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

为提升 API Key 等敏感信息的安全性，可使用 Spring表达式语（SpEL）引用环境变量：

# In application.yml
spring:
  ai:
    minimax:
      api-key: ${MINIMAX_API_KEY}
# In your environment or .env file
export MINIMAX_API_KEY=<your-minimax-api-key>

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

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

添加仓库和 BOM

Spring AI 构件已发布至 Maven 中央仓库和 Spring 快照仓库。请参阅 构件仓库 章节将这些仓库添加到你的构建系统中。

为简化依赖管理，Spring AI 提供 BOM 以确保项目统一使用相同版本的 Spring AI。请参考 依赖管理 章节将 Spring AI BOM 添加到你的构建系统中。

自动配置

Spring AI 自动配置及 starter 模块的构件命名已发生重大变更，详情请参阅 升级说明 文档。

Spring AI 为 Azure MiniMax 嵌入模型提供 Spring Boot 自动配置。启用该功能需在项目的 Maven pom.xml 文件中添加以下依赖：

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

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

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-minimax'
}
请参考 “依赖管理” 章节将 Spring AI BOM 添加到你的构建文件。

嵌入配置

重试配置

前缀 spring.ai.retry 是用于配置 MiniMax 嵌入模型重试机制的属性前缀。

属性 说明 默认值

spring.ai.retry.max-attempts

最大重试尝试次数。

10

spring.ai.retry.backoff.initial-interval

指数退避策略的初始休眠时长。

2 sec.

spring.ai.retry.backoff.multiplier

退避间隔乘数。

5

spring.ai.retry.backoff.max-interval

最大退避时长。

3 min.

spring.ai.retry.on-client-errors

如果为 false，则抛出 NonTransientAiException，并且不会针对 4xx 客户端错误代码尝试重试

false

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

不应触发重试的 HTTP 状态代码列表（例如抛出 NonTransientAiException 的情况）。

empty

spring.ai.retry.on-http-codes

应触发重试的 HTTP 状态代码列表（例如抛出 TransientAiException 的情况）。

empty

连接配置

前缀 spring.ai.minimax 是用于连接 MiniMax 的属性前缀。

属性 说明 默认值

spring.ai.minimax.base-url

要连接到的 URL

api.minimax.chat

spring.ai.minimax.api-key

API Key

-

配置属性

嵌入自动配置的启用与禁用现在通过顶级属性配置，前缀为 spring.ai.model.embedding。

  • 启用：spring.ai.model.embedding=minimax（默认启用）

  • 禁用：spring.ai.model.embedding=none（或任何不匹配 minimax 的值）

此变更是为了支持多模型配置。

前缀 spring.ai.minimax.embedding 是用于配置 MiniMax 嵌入模型 （EmbeddingModel）实现的属性前缀。

属性 说明 默认值

spring.ai.minimax.embedding.enabled （已移除且不再有效）

启用 MiniMax 嵌入模型。

true

spring.ai.model.embedding

启用 MiniMax 嵌入模型。

minimax

spring.ai.minimax.embedding.base-url

可选参数，用于覆盖 spring.ai.minimax.base-url 以指定嵌入专用 URL。

-

spring.ai.minimax.embedding.api-key

可选参数，用于覆盖 `spring.ai.minimax.api-key `以指定嵌入专用 API Key。

-

spring.ai.minimax.embedding.options.model

使用的模型

embo-01
你可以为 ChatModel 和 EmbeddingModel 实现覆盖通用的 spring.ai.minimax.base-url 和 spring.ai.minimax.api-key 配置。若设置了以下属性，它们将优先于通用配置生效：

  • 嵌入模型专用：spring.ai.minimax.embedding.base-url 和 spring.ai.minimax.embedding.api-key

  • 聊天模型专用：spring.ai.minimax.chat.base-url 和 `spring.ai.minimax.chat.api-key `

此功能适用于需要为不同模型和不同端节点使用不同 MiniMax 账户的场景。

所有以 spring.ai.minimax.embedding.options 为前缀的属性，均可通过在 EmbeddingRequest 调用中添加请求特定的 运行时选项 进行覆盖。

运行时选项

MiniMaxEmbeddingOptions.java 提供 MiniMax 配置参数，包括使用的模型等。

默认选项也可通过 spring.ai.minimax.embedding.options 属性进行配置。

初始化时通过 MiniMaxEmbeddingModel 构造函数设置所有嵌入请求的默认选项。运行时可通过在 EmbeddingRequest 中添加 MiniMaxEmbeddingOptions 实例来覆盖默认配置。

例如，针对特定请求覆盖默认模型名称：

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        MiniMaxEmbeddingOptions.builder()
            .model("Different-Embedding-Model-Deployment-Name")
        .build()));

示例 Controller

这将创建一个可注入到你类中的 EmbeddingModel 实现。以下是一个简单的 @Controller 类示例，该类使用 Embedding 实现。

spring.ai.minimax.api-key=YOUR_API_KEY
spring.ai.minimax.embedding.options.model=embo-01
@RestController
public class EmbeddingController {

    private final EmbeddingModel embeddingModel;

    @Autowired
    public EmbeddingController(EmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }

    @GetMapping("/ai/embedding")
    public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
        return Map.of("embedding", embeddingResponse);
    }
}

手动配置

若不使用 Spring Boot，你可以手动配置 MiniMax 嵌入模型。为此，需在项目的 Maven pom.xml 文件中添加 spring-ai-minimax 依赖：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-minimax</artifactId>
</dependency>

或添加到你的 Gradle 构建文件 build.gradle 中：

dependencies {
    implementation 'org.springframework.ai:spring-ai-minimax'
}
请参考 Dependency Management 章节将 Spring AI BOM 添加到你的构建文件。
spring-ai-minimax 依赖同时提供对 MiniMaxChatModel 的访问。有关 MiniMaxChatModel 的更多信息，请参阅 “MiniMax 聊天客户端” 章节。

接下来，创建 MiniMaxEmbeddingModel 实例并使用它计算两个输入文本之间的相似度：

var miniMaxApi = new MiniMaxApi(System.getenv("MINIMAX_API_KEY"));

var embeddingModel = new MiniMaxEmbeddingModel(minimaxApi, MetadataMode.EMBED,
MiniMaxEmbeddingOptions.builder().model("embo-01").build());

EmbeddingResponse embeddingResponse = this.embeddingModel
	.embedForResponse(List.of("Hello World", "World is big and salvation is near"));

MiniMaxEmbeddingOptions 为嵌入请求提供配置信息，其内置的 builder() 方法可便捷创建配置选项。