OpenAI SDK 嵌入（官方）
Spring AI 通过 OpenAI Java SDK 支持 OpenAI 的文本嵌入模型，为包括 Microsoft Foundry 和 GitHub 模型在内的 OpenAI 服务提供了强大且官方维护的集成。
| 此实现使用了来自OpenAI的官方OpenAI Java SDK。有关Spring AI的替代实现，请参见OpenAI嵌入。 |
OpenAI的文本嵌入用于衡量文本字符串之间的相关性。 嵌入是一个浮点数的向量（列表）。两个向量之间的距离度量了它们的相关性。距离小表明高度相关，而距离大则表明相关性低。
该 OpenAI SDK 模块会根据你提供的基地址自动检测服务提供者（OpenAI、Microsoft Foundry 或 GitHub Models）。
身份验证
认证过程使用了一个基数URL和一个API密钥。实现部分通过Spring Boot配置属性或环境变量提供了灵活的配置选项。
使用OpenAI
If you are using OpenAI directly, create an account at OpenAI注册页面 and generate an API key on the API密钥页面.
基URL不需要手动设置，系统会默认为0：
spring.ai.openai-sdk.api-key=<your-openai-api-key>
# base-url is optional, defaults to https://api.openai.com/v1或者，使用环境变量配置应用程序：
export OPENAI_API_KEY=<your-openai-api-key>
# OPENAI_BASE_URL is optional, defaults to https://api.openai.com/v1使用微软Foundry
当使用微软Foundry URL时，微软Foundry会被自动检测出来。你可以通过属性来配置它。
spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.api-key=<your-api-key>
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>或者，使用环境变量配置应用程序：
export OPENAI_BASE_URL=https://<your-deployment-url>.openai.azure.com
export OPENAI_API_KEY=<your-api-key>无密码认证（推荐用于Azure）：
微软Foundry支持无密钥的密码less认证，无需提供API密钥，这在Azure上运行时更加安全。
为了实现无密码认证，添加 零 依赖项：
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
</dependency>然后，无需配置API密钥进行配置：
spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>
# No api-key needed - will use Azure credentials from environment使用 GitHub 模型
GitHub Models会在使用GitHub Models基础URL时自动检测到。您还需要使用0代码范围创建GitHub个人访问Tokens（PAT）。
spring.ai.openai-sdk.base-url=https://models.inference.ai.azure.com
spring.ai.openai-sdk.api-key=github_pat_XXXXXXXXXXX或者，使用环境变量配置应用程序：
export OPENAI_BASE_URL=https://models.inference.ai.azure.com
export OPENAI_API_KEY=github_pat_XXXXXXXXXXX| 为了提高安全性，当处理敏感信息如API密钥时，你可以使用Spring表达式语言（SpEL）在属性中使用： ```java // 示例代码 System.setProperty("myAppspringId", "unique-value-for-my-app"); ``` |
spring.ai.openai-sdk.api-key=${OPENAI_API_KEY}自动配置
Spring AI 为 OpenAI SDK 嵌入模型提供了 Spring Boot 自动配置功能。要启用该功能，请将以下依赖项添加到项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中：
-
Maven
-
Gradle
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai-sdk</artifactId>
</dependency>dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-openai-sdk'
}| 参考以下依赖管理部分，添加Spring AI BOM到你的构建文件中。 |
配置属性
连接属性
The prefix spring.ai.openai-sdk is used as the property prefix that lets you configure the OpenAI SDK client.
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.openai-sdk.base-url |
连接到的URL。如果未设置，则自动从 |
|
spring.ai.openai-sdk.api-key |
API密钥。如果不设置，会从 |
- |
spring.ai.openai-sdk.organization-id |
可选地指定用于API请求的组织。 |
- |
spring.ai.openai-sdk.timeout |
请求超时持续时间。 |
- |
spring.ai.openai-sdk.max-retries |
失败请求的最大重试次数。 |
- |
spring.ai.openai-sdk.proxy |
Proxy设置为OpenAI客户端（Java 0对象）。 |
- |
spring.ai.openai-sdk.custom-headers |
需要将以下英文文本翻译成中文简体： Custom HTTP headers to include in requests. Map of header name to header value. 翻译结果如下： 在请求中包含自定义HTTP头。头名称与头值的映射关系。 |
- |
微软熔炉属性
OpenAI SDK 实现为 Microsoft Foundry 提供了原生支持，包括自动配置功能：
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.openai-sdk.microsoft-foundry |
启用 Microsoft Foundry 模式。如果基体 URL 包含 |
false |
spring.ai.openai-sdk.microsoft-deployment-name |
微软Foundry的部署名称。如果未指定，则使用模型名。此外，还可以通过别名 |
- |
spring.ai.openai-sdk.microsoft-foundry-service-version |
微软Foundry API服务版本 |
- |
spring.ai.openai-sdk.credential |
凭证对象用于无密码认证（需要 |
- |
微软Foundry支持无密钥认证。添加com.azure:azure-identity依赖项，实现将自动尝试从环境变量中使用Azure凭证（而非API密钥）。 |
GitHub 模型属性
GitHub Models的原生支持已推出：
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.openai-sdk.github-models |
启用GitHub模型模式。如果基础URL包含 |
false |
| GitHub Models需要一个个人访问Tokens，具有0的权限范围。通过以下方式设置：1环境变量或2属性。 |
嵌入模型属性
前缀 spring.ai.openai-sdk.embedding 是配置嵌入模型实现的属性前缀:
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.openai-sdk.embedding.metadata-mode |
文档内容提取模式。 |
EMBED |
spring.ai.openai-sdk.embedding.options.model |
要使用的模型。您可以在以下模型中选择： |
|
spring.ai.openai-sdk.embedding.options.user |
代表您终端用户的唯一标识符，有助于OpenAI监控和检测滥用行为。 |
- |
spring.ai.openai-sdk.embedding.options.dimensions |
生成的输出嵌入应具有的维度数量。仅在 |
- |
所有以spring.ai.openai-sdk.embedding.options为前缀的属性都可以通过向EmbeddingRequest调用中添加请求特定的运行时选项在运行时覆盖。 |
运行时选项
OpenAiSdkEmbeddingOptions.java 文件提供了OpenAI的配置选项，例如使用的模型、维度和用户标识符。
默认选项也可以使用spring.ai.openai-sdk.embedding.options属性进行配置。
在启动时，使用OpenAiSdkEmbeddingModel构造函数设置所有嵌入请求使用的默认选项。在运行时，您可以使用OpenAiSdkEmbeddingOptions实例作为EmbeddingRequest的一部分来覆盖默认选项。
例如，要为特定请求覆盖默认的模型名称：
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
OpenAiSdkEmbeddingOptions.builder()
.model("text-embedding-3-large")
.dimensions(1024)
.build()));| 除了特定于模型的OpenAiSdkEmbeddingOptions之外，您还可以使用通过构建器创建的便携式EmbeddingOptions实例。 |
示例控制器
创建一个新的Spring Boot项目，并将spring-boot-starter-web添加到您的pom（或gradle）依赖中。
在src/main/resources目录下添加一个application.properties文件以配置OpenAI SDK嵌入模型:
spring.ai.openai-sdk.api-key=YOUR_API_KEY
spring.ai.openai-sdk.embedding.options.model=text-embedding-ada-002将api-key替换为您的OpenAI凭据。 |
这将创建一个您可以注入到类中的OpenAiSdkEmbeddingModel实现。
下面是一个使用嵌入模型的简单@RestController类的例子。
@RestController
public class EmbeddingController {
private final EmbeddingModel embeddingModel;
@Autowired
public EmbeddingController(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
@GetMapping("/ai/embedding")
public Map<String, Object> embed(
@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
return Map.of("embedding", embeddingResponse);
}
}手动配置
OpenAiSdkEmbeddingModel 类实现了 EmbeddingModel 并使用官方 OpenAI Java SDK 连接到 OpenAI 服务。
如果不使用Spring Boot自动配置，您可以手动配置OpenAI SDK嵌入模型。
为此，请将spring-ai-openai-sdk依赖项添加到项目Mavenpom.xml文件中:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-sdk</artifactId>
</dependency>或者添加到你的 Gradle build.gradle 构建文件中：
dependencies {
implementation 'org.springframework.ai:spring-ai-openai-sdk'
}| 参考以下依赖管理部分，添加Spring AI BOM到你的构建文件中。 |
spring-ai-openai-sdk 依赖项还提供了对 OpenAiSdkChatModel 和 OpenAiSdkImageModel 的访问。
有关 OpenAiSdkChatModel 的更多信息，请参阅 OpenAI SDK 聊天 部分。 |
接下来，创建一个OpenAiSdkEmbeddingModel实例，并使用它来计算两个输入文本之间的相似度：
var embeddingOptions = OpenAiSdkEmbeddingOptions.builder()
.model("text-embedding-ada-002")
.apiKey(System.getenv("OPENAI_API_KEY"))
.build();
var embeddingModel = new OpenAiSdkEmbeddingModel(embeddingOptions);
EmbeddingResponse embeddingResponse = embeddingModel
.embedForResponse(List.of("Hello World", "World is big and salvation is near"));数字OpenAiSdkEmbeddingOptions为嵌入请求提供了配置信息。
选项类提供了一个builder()以简化选项创建过程。
微软foundry配置Microsoft Foundry Configuration
对于 Microsoft Foundry：
var embeddingOptions = OpenAiSdkEmbeddingOptions.builder()
.baseUrl("https://your-resource.openai.azure.com")
.apiKey(System.getenv("OPENAI_API_KEY"))
.deploymentName("text-embedding-ada-002")
.azureOpenAIServiceVersion(AzureOpenAIServiceVersion.V2024_10_01_PREVIEW)
.azure(true) // Enables Microsoft Foundry mode
.build();
var embeddingModel = new OpenAiSdkEmbeddingModel(embeddingOptions);Microsoft Foundry支持无密码认证。在项目中添加com.azure:azure-identity依赖项。如果未提供密钥，则实现将自动尝试从环境中使用Azure凭证。 |
GitHub模型配置
对于GitHub模型来说：
var embeddingOptions = OpenAiSdkEmbeddingOptions.builder()
.baseUrl("https://models.inference.ai.azure.com")
.apiKey(System.getenv("GITHUB_TOKEN"))
.model("text-embedding-3-large")
.githubModels(true)
.build();
var embeddingModel = new OpenAiSdkEmbeddingModel(embeddingOptions);