> ## Documentation Index > Fetch the complete documentation index at: https://javaai.pig4cloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Azure OpenAI 向量模型 Azure OpenAI 扩展了 OpenAI 的功能，为各种任务提供安全的文本生成和 Embeddings 计算模型： * 相似性嵌入擅长捕捉两个或多个文本片段之间的语义相似性。 * 文本搜索嵌入有助于衡量长文档是否与短查询相关。 * 代码搜索嵌入可用于嵌入代码片段和嵌入自然语言搜索查询。 Azure OpenAI 嵌入依赖于`余弦相似度`来计算文档和查询之间的相似度。 ## 先决条件 Azure OpenAI 客户端提供三种连接选项：使用 Azure API 密钥、使用 OpenAI API 密钥或使用 Microsoft Entra ID。 ### Azure API 密钥和终结点 从 [Azure 门户](https://portal.azure.com)上的 Azure OpenAI 服务部分获取您的 Azure OpenAI `endpoint` 和 `api-key`。 Spring AI 定义了两个配置属性： 1. `spring.ai.azure.openai.api-key`：将其设置为从 Azure 获取的 `API Key` 的值。 2. `spring.ai.azure.openai.endpoint`：将其设置为在 Azure 中预配模型时获取的终结点 URL。 您可以在 `application.properties` 或 `application.yml` 文件中设置这些配置属性： ```properties theme={"system"} spring.ai.azure.openai.api-key=<您的 Azure API 密钥> spring.ai.azure.openai.endpoint=<您的 Azure 终结点 URL> ``` 如果您希望对 API 密钥等敏感信息使用环境变量，可以在配置中使用 Spring 表达式语言 (SpEL)： ```yaml theme={"system"} # 在 application.yml 中 spring: ai: azure: openai: api-key: ${AZURE_OPENAI_API_KEY} endpoint: ${AZURE_OPENAI_ENDPOINT} ``` ```bash theme={"system"} # 在您的环境或 .env 文件中 export AZURE_OPENAI_API_KEY=<您的 Azure OpenAI API 密钥> export AZURE_OPENAI_ENDPOINT=<您的 Azure 终结点 URL> ``` ### OpenAI 密钥 要使用 OpenAI 服务（而非 Azure）进行身份验证，请提供 OpenAI API 密钥。 ## 自动配置 > **注意**：Spring AI 自动配置和启动器模块的工件名称已发生重大更改。 > 有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。 Spring AI 为 Azure OpenAI Embedding 模型提供 Spring Boot 自动配置。 要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 文件中： ```xml theme={"system"} org.springframework.ai spring-ai-starter-model-azure-openai ``` 或添加到您的 Gradle `build.gradle` 构建文件中。 ```groovy theme={"system"} dependencies { implementation 'org.springframework.ai:spring-ai-starter-model-azure-openai' } ``` > **提示**：请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。 ### Embedding 属性 前缀 `spring.ai.azure.openai` 是用于配置与 Azure OpenAI 连接的属性前缀。 | 属性 | 描述 | 默认值 | | :------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-- | | spring.ai.azure.openai.api-key | Azure AI OpenAI `资源管理`下`密钥和终结点`部分的密钥。 | - | | spring.ai.azure.openai.endpoint | Azure AI OpenAI `资源管理`下`密钥和终结点`部分的终结点。 | - | | spring.ai.azure.openai.openai-api-key | (非 Azure) OpenAI API 密钥。用于向 OpenAI 服务（而非 Azure OpenAI）进行身份验证。这会自动将终结点设置为 [https://api.openai.com/v1。使用](https://api.openai.com/v1。使用) `api-key` 或 `openai-api-key` 属性。使用此配置时，`spring.ai.azure.openai.embedding.options.deployment-name` 将被视为 [OpenAI 模型](https://platform.openai.com/docs/models)名称。 | - | > **注意**：嵌入自动配置的启用和禁用现在通过前缀为 `spring.ai.model.embedding` 的顶级属性进行配置。 > > 要启用，请设置 spring.ai.model.embedding=azure-openai (默认情况下启用) > > 要禁用，请设置 spring.ai.model.embedding=none (或任何与 azure-openai 不匹配的值) > > 此更改是为了允许配置多个模型。 前缀 `spring.ai.azure.openai.embedding` 是配置 Azure OpenAI 的 `EmbeddingModel` 实现的属性前缀。 | 属性 | 描述 | 默认值 | | :------------------------------------------------------- | :----------------------------- | :--------------------- | | spring.ai.azure.openai.embedding.enabled (已删除且不再有效) | 启用 Azure OpenAI 嵌入模型。 | true | | spring.ai.model.embedding | 启用 Azure OpenAI 嵌入模型。 | azure-openai | | spring.ai.azure.openai.embedding.metadata-mode | 文档内容提取模式。 | EMBED | | 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` 调用添加特定于请求的[嵌入选项](#embedding-options)来覆盖。 ## 运行时选项 `AzureOpenAiEmbeddingOptions` 提供嵌入请求的配置信息。 `AzureOpenAiEmbeddingOptions` 提供了一个构建器来创建选项。 在启动时，使用 `AzureOpenAiEmbeddingModel` 构造函数设置用于所有嵌入请求的默认选项。 在运行时，您可以通过将 `AzureOpenAiEmbeddingOptions` 实例传递给 `EmbeddingRequest` 请求来覆盖默认选项。 例如，要覆盖特定请求的默认模型名称： ```java theme={"system"} 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` 实现，您可以将其注入到您的类中。 这是一个简单的 `@Controller` 类示例，它使用 `EmbeddingModel` 实现。 ```properties theme={"system"} spring.ai.azure.openai.api-key=您的 API 密钥 spring.ai.azure.openai.endpoint=您的终结点 spring.ai.azure.openai.embedding.options.model=text-embedding-ada-002 ``` ```java theme={"system"} @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` 文件中： ```xml theme={"system"} org.springframework.ai spring-ai-azure-openai ``` 或添加到您的 Gradle `build.gradle` 构建文件中。 ```groovy theme={"system"} dependencies { implementation 'org.springframework.ai:spring-ai-azure-openai' } ``` > **提示**：请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。 > **注意**：`spring-ai-azure-openai` 依赖项还提供对 `AzureOpenAiEmbeddingModel` 的访问。有关 `AzureOpenAiChatModel` 的更多信息，请参阅 [Azure OpenAI Embeddings](/spring4ai/api/embeddings/azure-openai-embeddings) 部分。 接下来，创建一个 `AzureOpenAiEmbeddingModel` 实例，并用它来计算两个输入文本之间的相似度： ```java theme={"system"} 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")); ``` > **注意**：`text-embedding-ada-002` 实际上是 Azure AI 门户中显示的`部署名称`。 发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！