Spring AI 使用 OpenAI SDK 嵌入向量（官方版）

Spring AI 通过官方 OpenAI Java SDK 支持 OpenAI 文本嵌入模型，提供与 OpenAI 服务（包括微软云服务和 GitHub 模型）的稳定、官方维护集成。

OpenAI 文本嵌入用于衡量文本字符串的相关性。嵌入向量是一组浮点数，两个向量的距离越小，相关性越高；距离越大，相关性越低。

该模块会根据你提供的基础 URL 自动识别服务提供商：OpenAI、微软 Foundry 或 GitHub Models。

认证方式

通过基础 URL 和 API 密钥完成认证，支持 Spring 配置或环境变量。

使用 OpenAI

spring.ai.openai-sdk.api-key=# 可选，默认 https://api.openai.com/v1
# spring.ai.openai-sdk.base-url=https://api.openai.com/v1

环境变量：

export OPENAI_API_KEY=

使用微软 Foundry

spring.ai.openai-sdk.base-url=https://.openai.azure.com
spring.ai.openai-sdk.api-key=spring.ai.openai-sdk.microsoft-deployment-name=

无密码认证（推荐）

添加依赖：

com.azureazure-identity

无需配置 api-key：

spring.ai.openai-sdk.base-url=https://.openai.azure.com
spring.ai.openai-sdk.microsoft-deployment-name=

使用 GitHub Models

spring.ai.openai-sdk.base-url=https://models.inference.ai.azure.com
spring.ai.openai-sdk.api-key=github_pat_XXXXXXXXXXX

添加依赖

Maven：

org.springframework.aispring-ai-starter-model-openai-sdk

Gradle：

implementation 'org.springframework.ai:spring-ai-starter-model-openai-sdk'

配置属性

连接属性

嵌入模型属性

运行时选项

可在请求时覆盖默认配置：

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World"),
        OpenAiSdkEmbeddingOptions.builder()
            .model("text-embedding-3-large")
            .dimensions(1024)
            .build()));

示例控制器

@RestController
public class EmbeddingController {
    private final EmbeddingModel embeddingModel;

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

    @GetMapping("/ai/embedding")
    public Mapembed(@RequestParam String message) {
        EmbeddingResponse response = embeddingModel.embedForResponse(List.of(message));
        return Map.of("embedding", response);
    }
}

手动配置

var options = OpenAiSdkEmbeddingOptions.builder()
    .model("text-embedding-ada-002")
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();

var model = new OpenAiSdkEmbeddingModel(options);
EmbeddingResponse response = model.embedForResponse(List.of("Hello World"));

微软 Foundry 手动配置

var options = OpenAiSdkEmbeddingOptions.builder()
    .baseUrl("https://your-resource.openai.azure.com")
    .deploymentName("text-embedding-ada-002")
    .azure(true)
    .build();

var model = new OpenAiSdkEmbeddingModel(options);

GitHub Models 手动配置

var options = OpenAiSdkEmbeddingOptions.builder()
    .baseUrl("https://models.inference.ai.azure.com")
    .apiKey(System.getenv("GITHUB_TOKEN"))
    .githubModels(true)
    .build();

可观测性

通过 Micrometer 支持 Spring AI 监控与追踪。