|
此版本仍在开发中，尚未被视为稳定版。如需最新的快照版本，请使用 Spring AI 1.1.3！ |
Azure OpenAI 嵌入模型
Azure 的 OpenAI 扩展了 OpenAI 的功能，为各种任务提供安全的文本生成和嵌入计算模型：
-
相似性嵌入擅长捕捉两段或多段文本之间的语义相似性。
-
文本搜索嵌入有助于衡量长文档是否与短查询相关。
-
代码搜索嵌入对于嵌入代码片段和自然语言搜索查询非常有用。
Azure OpenAI 嵌入依赖 cosine similarity 来计算文档与查询之间的相似度。
前置条件
Azure OpenAI客户端提供了三种连接选项：使用Azure API密钥、使用OpenAI API密钥或使用Microsoft Entra ID。
Azure API密钥与端点
从 Azure 门户 的 Azure OpenAI 服务部分获取您的 Azure OpenAI endpoint 和api-key。
Spring AI 定义了两个配置属性：
-
spring.ai.azure.openai.api-key: 将其设置为从Azure获得的API Key的值。 -
spring.ai.azure.openai.endpoint: 将此设置为您在Azure中部署模型时获得的端点URL。
您可以在您的application.properties或application.yml文件中设置这些配置属性：
spring.ai.azure.openai.api-key=<your-azure-api-key>
spring.ai.azure.openai.endpoint=<your-azure-endpoint-url>如果您更喜欢使用环境变量来存储敏感信息（如 API 密钥），您可以在配置中使用 Spring 表达式语言 (SpEL)：
# In application.yml
spring:
ai:
azure:
openai:
api-key: ${AZURE_OPENAI_API_KEY}
endpoint: ${AZURE_OPENAI_ENDPOINT}# In your environment or .env file
export AZURE_OPENAI_API_KEY=<your-azure-openai-api-key>
export AZURE_OPENAI_ENDPOINT=<your-azure-endpoint-url>OpenAI密钥
要使用 OpenAI 服务（非 Azure）进行身份验证，请提供 OpenAI API 密钥。 这将自动将端点设置为 api.openai.com/v1。
使用此方法时，请将spring.ai.azure.openai.chat.options.deployment-name属性设置为您希望使用的OpenAI模型的名称。
在您的应用程序配置中：
spring.ai.azure.openai.openai-api-key=<your-azure-openai-key>
spring.ai.azure.openai.chat.options.deployment-name=<openai-model-name>使用环境变量与SpEL:
# In application.yml
spring:
ai:
azure:
openai:
openai-api-key: ${AZURE_OPENAI_API_KEY}
chat:
options:
deployment-name: ${OPENAI_MODEL_NAME}# In your environment or .env file
export AZURE_OPENAI_API_KEY=<your-openai-key>
export OPENAI_MODEL_NAME=<openai-model-name>Auto-configuration
|
Spring AI自动配置和starter模块的artifact名称有了重大变化。 请参阅升级说明获取更多信息。 |
Spring AI 为 Azure OpenAI 嵌入模型提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven pom.xml 文件中：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-azure-openai</artifactId>
</dependency>请将以下内容添加到您的Gradle build.gradle 构建文件中。
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-azure-openai'
}| 请参阅依赖管理部分，将Spring AI BOM添加到您的构建文件中。 |
嵌入属性
spring.ai.azure.openai 前缀是配置连接到 Azure OpenAI 的属性前缀。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.azure.openai.api-key |
Azure AI OpenAI 的 Key 从 |
- |
spring.ai.azure.openai.endpoint |
来自Azure AI OpenAI |
- |
spring.ai.azure.openai.openai-api-key |
(non Azure) OpenAI API密钥。用于向OpenAI服务进行身份验证，而不是Azure OpenAI。
这会自动将端点设置为 api.openai.com/v1。可以使用属性 |
- |
|
嵌入自动配置的启用和禁用现在通过前缀为 要启用，请设置 spring.ai.model.embedding=azure-openai（默认已启用） 要禁用，请设置 spring.ai.model.embedding=none（或任何不与 azure-openai 匹配的值） 此更改是为了允许配置多个模型。 |
前缀 spring.ai.azure.openai.embedding 是用于配置 Azure OpenAI 的 EmbeddingModel 实现的属性前缀。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.azure.openai.embedding.enabled（已移除且不再生效） |
启用 Azure OpenAI 嵌入模型。 |
true |
spring.ai.model.embedding |
启用 Azure OpenAI 嵌入模型。 |
azure-openai |
spring.ai.azure.openai.embedding.metadata-mode |
文档内容提取模式 |
嵌入 |
spring.ai.azure.openai.embedding.options.deployment-name |
这是 Azure AI 门户中显示的“部署名称”的值 |
text-embedding-ada-002 |
spring.ai.azure.openai.embedding.options.user |
操作的调用者或最终用户的标识符。这可能用于跟踪或速率限制的目的。 |
- |
所有以spring.ai.azure.openai.embedding.options开头的属性可以在运行时通过向EmbeddingRequest调用添加请求特定的运行时选项来覆盖。 |
运行时选项
AzureOpenAiEmbeddingOptions 提供嵌入请求的配置信息。
AzureOpenAiEmbeddingOptions 提供用于创建选项的构建器。
在启动时，使用 AzureOpenAiEmbeddingModel 构造函数来设置所有嵌入请求的默认选项。
在运行时，您可以通过向 EmbeddingRequest 请求传递一个包含您自定义设置的 AzureOpenAiEmbeddingOptions 实例来覆盖默认选项。
例如，要为特定请求覆盖默认模型名称：
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
AzureOpenAiEmbeddingOptions.builder()
.model("Different-Embedding-Model-Deployment-Name")
.build()));示例代码
这将创建一个您可以注入到类中的 EmbeddingModel 实现。
下面是一个使用 EmbeddingModel 实现的简单 @Controller 类示例。
spring.ai.azure.openai.api-key=YOUR_API_KEY
spring.ai.azure.openai.endpoint=YOUR_ENDPOINT
spring.ai.azure.openai.embedding.options.model=text-embedding-ada-002@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 自动配置，可以在应用程序中手动配置AzureOpenAiEmbeddingModel。
为此，请将spring-ai-azure-openai依赖项添加到项目的 Maven pom.xml文件中：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-azure-openai</artifactId>
</dependency>请将以下内容添加到您的Gradle build.gradle 构建文件中。
dependencies {
implementation 'org.springframework.ai:spring-ai-azure-openai'
}| 请参阅依赖管理部分，将Spring AI BOM添加到您的构建文件中。 |
spring-ai-azure-openai 依赖项还提供了对 AzureOpenAiEmbeddingModel 的访问权限。有关 AzureOpenAiChatModel 的更多信息，请参阅 Azure OpenAI 嵌入部分。 |
接下来，创建一个 AzureOpenAiEmbeddingModel 实例，并使用它来计算两个输入文本之间的相似度：
var openAIClient = OpenAIClientBuilder()
.credential(new AzureKeyCredential(System.getenv("AZURE_OPENAI_API_KEY")))
.endpoint(System.getenv("AZURE_OPENAI_ENDPOINT"))
.buildClient();
var embeddingModel = new AzureOpenAiEmbeddingModel(this.openAIClient)
.withDefaultOptions(AzureOpenAiEmbeddingOptions.builder()
.model("text-embedding-ada-002")
.user("user-6")
.build());
EmbeddingResponse embeddingResponse = this.embeddingModel
.embedForResponse(List.of("Hello World", "World is big and salvation is near"));the text-embedding-ada-002 是实际上的 Deployment Name，如在 Azure AI Portal 中所展示。 |