> ## 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 产品由 ChatGPT 提供支持，超越了传统的 OpenAI 功能，提供具有增强功能的 AI 驱动文本生成。Azure 提供额外的 AI 安全和负责任的 AI 功能，如其最近的更新[此处](https://techcommunity.microsoft.com/t5/ai-azure-ai-services-blog/announcing-new-ai-safety-amp-responsible-ai-features-in-azure/ba-p/3983686)所述。 Azure 为 Java 开发人员提供了通过将其与一系列 Azure 服务（包括 Azure 上的向量存储等 AI 相关资源）集成来充分利用 AI 潜力的机会。 ## 前提条件 Azure OpenAI 客户端提供三种连接选项：使用 Azure API 密钥、使用 OpenAI API 密钥或使用 Microsoft Entra ID。 ### Azure API 密钥和终结点 要使用 API 密钥访问模型，请从 [Azure 门户](https://portal.azure.com)上的 Azure OpenAI 服务部分获取你的 Azure OpenAI `endpoint` 和 `api-key`。 Spring AI 定义了两个配置属性： 1. `spring.ai.azure.openai.api-key`：将其设置为从 Azure 获取的 `API 密钥` 的值。 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> ``` ```yaml theme={"system"} spring: ai: azure: openai: api-key: ${AZURE_OPENAI_API_KEY} endpoint: ${AZURE_OPENAI_ENDPOINT} ``` ```bash theme={"system"} export AZURE_OPENAI_API_KEY=<你的-azure-openai-api-密钥> export AZURE_OPENAI_ENDPOINT=<你的-azure-openai-终结点-url> ``` ### OpenAI 密钥 要向 OpenAI 服务（而非 Azure）进行身份验证，请提供 OpenAI API 密钥。这会自动将终结点设置为 [https://api.openai.com/v1。](https://api.openai.com/v1。) 使用此方法时，请将 `spring.ai.azure.openai.chat.options.deployment-name` 属性设置为要使用的 [OpenAI 模型](https://platform.openai.com/docs/models)的名称。 在你的应用程序配置中： ```properties theme={"system"} spring.ai.azure.openai.openai-api-key=<你的-azure-openai-密钥> spring.ai.azure.openai.chat.options.deployment-name= ``` ```yaml theme={"system"} spring: ai: azure: openai: openai-api-key: ${AZURE_OPENAI_API_KEY} chat: options: deployment-name: ${AZURE_OPENAI_MODEL_NAME} ``` ```bash theme={"system"} export AZURE_OPENAI_API_KEY=<你的-openai-密钥> export AZURE_OPENAI_MODEL_NAME= ``` ### Microsoft Entra ID 要使用 Microsoft Entra ID（以前称为 Azure Active Directory）进行无密钥身份验证，请\_仅\_设置 `spring.ai.azure.openai.endpoint` 配置属性，而\_不\_设置上面提到的 api-key 属性。 仅找到终结点属性后，你的应用程序将评估几个不同的凭据检索选项，并使用令牌凭据创建 `OpenAIClient` 实例。 不再需要创建 `TokenCredential` bean；它会自动为你配置。 ### 部署名称 要使用 Azure AI 应用程序，你需要通过 [Azure AI 门户](https://oai.azure.com/portal)创建一个 Azure AI 部署。 在 Azure 中，每个客户端都必须指定一个 `Deployment Name` 才能连接到 Azure OpenAI 服务。 需要注意的是，`Deployment Name` 与你选择部署的模型不同。 例如，名为"MyAiDeployment"的部署可以配置为使用 GPT 3.5 Turbo 模型或 GPT 4.0 模型。 要开始使用，请按照以下步骤使用默认设置创建部署： 部署名称：`gpt-4o` 模型名称：`gpt-4o` 此 Azure 配置与 Spring Boot Azure AI Starter 及其自动配置功能的默认配置一致。 如果你使用不同的部署名称，请确保相应地更新配置属性： ```properties theme={"system"} spring.ai.azure.openai.chat.options.deployment-name=<我的部署名称> ``` Azure OpenAI 和 OpenAI 的不同部署结构导致 Azure OpenAI 客户端库中有一个名为 `deploymentOrModelName` 的属性。 这是因为在 OpenAI 中没有 `Deployment Name`，只有 `Model Name`。 属性 `spring.ai.azure.openai.chat.options.model` 已重命名为 `spring.ai.azure.openai.chat.options.deployment-name`。 如果你决定通过设置 `spring.ai.azure.openai.openai-api-key=<你的 OpenAI 密钥>` 属性来连接到 `OpenAI` 而不是 `Azure OpenAI`， 那么 `spring.ai.azure.openai.chat.options.deployment-name` 将被视为 [OpenAI 模型](https://platform.openai.com/docs/models)名称。 #### 访问 OpenAI 模型 你可以将客户端配置为直接使用 `OpenAI`，而不是 `Azure OpenAI` 部署的模型。 为此，你需要设置 `spring.ai.azure.openai.openai-api-key=<你的 OpenAI 密钥>` 而不是 `spring.ai.azure.openai.api-key=<你的 Azure OpenAi 密钥>`。 ### 添加仓库和 BOM Spring AI 的构件发布在 Maven Central 和 Spring Snapshot 仓库中。 请参阅[构件仓库](/spring4ai/getting-started#artifact-repositories)部分，将这些仓库添加到你的构建系统中。 为了帮助进行依赖管理，Spring AI 提供了一个 BOM (bill of materials)，以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建系统中。 ## 自动配置 Spring AI 自动配置、启动器模块的构件名称发生了重大变化。 有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。 Spring AI 为 Azure OpenAI 聊天客户端提供 Spring Boot 自动配置。 要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 或 Gradle `build.gradle` 构建文件中： ```xml theme={"system"} org.springframework.ai spring-ai-starter-model-azure-openai ``` ```gradle theme={"system"} dependencies { implementation 'org.springframework.ai:spring-ai-starter-model-azure-openai' } ``` 请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。 Azure OpenAI 聊天客户端是使用 Azure SDK 提供的 [OpenAIClientBuilder](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/openai/azure-ai-openai/src/main/java/com/azure/ai/openai/OpenAIClientBuilder.java) 创建的。Spring AI 允许通过提供 [AzureOpenAIClientBuilderCustomizer](https://github.com/spring-projects/spring-ai/blob/main/auto-configurations/models/spring-ai-autoconfigure-model-azure-openai/src/main/java/org/springframework/ai/model/azure/openai/autoconfigure/AzureOpenAIClientBuilderCustomizer.java) bean 来自定义构建器。 例如，可以使用自定义程序来更改默认响应超时： ```java theme={"system"} @Configuration public class AzureOpenAiConfig { @Bean public AzureOpenAIClientBuilderCustomizer responseTimeoutCustomizer() { return openAiClientBuilder -> { HttpClientOptions clientOptions = new HttpClientOptions() .setResponseTimeout(Duration.ofMinutes(5)); openAiClientBuilder.httpClient(HttpClient.createDefault(clientOptions)); }; } } ``` ### 聊天属性 前缀 `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.chat.options.deployment-name` 将被视为 [OpenAi 模型](https://platform.openai.com/docs/models)名称。 | - | | `spring.ai.azure.openai.custom-headers` | 要包含在 API 请求中的自定义标头映射。映射中的每个条目代表一个标头，其中键是标头名称，值是标头值。 | 空映射 | 聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。 要启用，`spring.ai.model.chat=azure-openai` (默认启用) 要禁用，`spring.ai.model.chat=none` (或任何与 azure-openai 不匹配的值) 此更改是为了允许配置多个模型。 前缀 `spring.ai.azure.openai.chat` 是配置 Azure OpenAI 的 `ChatModel` 实现的属性前缀。 | 属性 | 描述 | 默认值 | | :----------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------- | | `spring.ai.azure.openai.chat.enabled` (已移除且不再有效) | 启用 Azure OpenAI 聊天模型。 | true | | `spring.ai.model.chat` | 启用 Azure OpenAI 聊天模型。 | azure-openai | | `spring.ai.azure.openai.chat.options.deployment-name` | 在 Azure 中使用时，这指的是模型的"部署名称"，你可以在 [https://oai.azure.com/portal](https://oai.azure.com/portal) 中找到它。需要注意的是，在 Azure OpenAI 部署中，"部署名称"与模型本身不同。围绕这些术语的混淆源于使 Azure OpenAI 客户端库与原始 OpenAI 终结点兼容的意图。Azure OpenAI 和 Sam Altman 的 OpenAI 提供的部署结构有显著差异。部署模型名称作为此补全请求的一部分提供。 | gpt-4o | | `spring.ai.azure.openai.chat.options.maxTokens` | 要生成的最大标记数。 | - | | `spring.ai.azure.openai.chat.options.temperature` | 用于控制生成补全的明显创造性的采样温度。较高的值会使输出更随机，而较低的值会使结果更集中和确定。不建议为同一补全请求修改温度和 top\_p，因为这两个设置的相互作用很难预测。 | 0.7 | | `spring.ai.azure.openai.chat.options.topP` | 温度采样的替代方法，称为核采样。此值使模型考虑具有所提供概率质量的标记的结果。 | - | | `spring.ai.azure.openai.chat.options.logitBias` | GPT 令牌 ID 和偏差分数之间的映射，影响特定令牌出现在补全响应中的概率。令牌 ID 通过外部令牌化工具计算，而偏差分数在 -100 到 100 的范围内，最小值和最大值分别对应于完全禁止或独占选择令牌。给定偏差分数的具体行为因模型而异。 | - | | `spring.ai.azure.openai.chat.options.user` | 操作的调用方或最终用户的标识符。这可用于跟踪或速率限制目的。 | - | | `spring.ai.azure.openai.chat.options.stream-usage` | （仅限流式传输）设置为添加一个包含整个请求的标记使用情况统计信息的附加块。此块的 `choices` 字段是一个空数组，所有其他块也将包含一个 usage 字段，但其值为 null。 | false | | `spring.ai.azure.openai.chat.options.n` | 应为聊天补全响应生成的聊天补全选项的数量。 | - | | `spring.ai.azure.openai.chat.options.stop` | 将结束补全生成的文本序列集合。 | - | | `spring.ai.azure.openai.chat.options.presencePenalty` | 一个影响生成令牌出现概率的值，基于它们在生成文本中已有的存在。正值会使令牌在已存在时不太可能出现，并增加模型输出新主题的可能性。 | - | | `spring.ai.azure.openai.chat.options.responseFormat` | 指定模型必须输出的格式的对象。使用 `AzureOpenAiResponseFormat.JSON` 启用 JSON 模式，可确保模型生成的消息是有效的 JSON。使用 AzureOpenAiResponseFormat.TEXT 启用 TEXT 模式。 | - | | `spring.ai.azure.openai.chat.options.frequencyPenalty` | 一个影响生成令牌出现概率的值，基于它们在生成文本中的累积频率。正值会使令牌随着频率的增加而不太可能出现，并降低模型逐字重复相同语句的可能性。 | - | | `spring.ai.azure.openai.chat.options.proxy-tool-calls` | 如果为 true，Spring AI 将不会在内部处理函数调用，而是将它们代理到客户端。然后由客户端负责处理函数调用，将它们分派到适当的函数，并返回结果。如果为 false（默认值），Spring AI 将在内部处理函数调用。仅适用于具有函数调用支持的聊天模型 | false | 所有以 `spring.ai.azure.openai.chat.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的[运行时选项](#runtime-options)来覆盖。 ## 运行时选项 [AzureOpenAiChatOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-azure-openai/src/main/java/org/springframework/ai/azure/openai/AzureOpenAiChatOptions.java) 提供模型配置，例如要使用的模型、温度、频率惩罚等。 在启动时，可以使用 `AzureOpenAiChatModel(api, options)` 构造函数或 `spring.ai.azure.openai.chat.options.*` 属性配置默认选项。 在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。 例如，要为特定请求覆盖默认模型和温度： ```java theme={"system"} ChatResponse response = chatModel.call( new Prompt( "生成 5 个著名海盗的名字。", AzureOpenAiChatOptions.builder() .deploymentName("gpt-4o") .temperature(0.4) .build() )); ``` 除了特定于模型的 [AzureOpenAiChatOptions](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-azure-openai/src/main/java/org/springframework/ai/azure/openai/AzureOpenAiChatOptions.java)之外，你还可以使用通过 [ChatOptionsBuilder#builder()](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptionsBuilder.java) 创建的可移植 [ChatOptions](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java) 实例。 ## 函数调用 你可以使用 AzureOpenAiChatModel 注册自定义 Java 函数，并让模型智能地选择输出一个 JSON 对象，其中包含调用一个或多个已注册函数的参数。 这是将 LLM 功能与外部工具和 API 连接起来的强大技术。 阅读有关[工具调用](/spring4ai/api/tools)的更多信息。 ## 多模态 多模态是指模型同时理解和处理来自各种来源的信息的能力，包括文本、图像、音频和其他数据格式。 目前，Azure OpenAI `gpt-4o` 模型提供多模态支持。 Azure OpenAI 可以将 base64 编码的图像或图像 URL 列表与消息合并。 Spring AI 的 [Message](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/messages/Message.java) 接口通过引入 [Media](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/model/Media.java) 类型来促进多模态 AI 模型。 此类型包含有关消息中媒体附件的数据和详细信息，利用 Spring 的 `org.springframework.util.MimeType` 和 `java.lang.Object` 来获取原始媒体数据。 以下是从 [OpenAiChatModelIT.java](https://github.com/spring-projects/spring-ai/blob/c9a3e66f90187ce7eae7eb78c462ec622685de6c/models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/OpenAiChatModelIT.java#L293) 中摘录的代码示例，说明了使用 `GPT_4_O` 模型将用户文本与图像融合。 ```java theme={"system"} URL url = new URL("https://docs.spring.io/spring-ai/reference/_images/multimodal.test.png"); String response = ChatClient.create(chatModel).prompt() .options(AzureOpenAiChatOptions.builder().deploymentName("gpt-4o").build()) .user(u -> u.text("解释一下你在这张图片上看到了什么？").media(MimeTypeUtils.IMAGE_PNG, this.url)) .call() .content(); ``` 你也可以传递多个图像。 它将 `multimodal.test.png` 图像作为输入： 以及文本消息"解释一下你在这张图片上看到了什么？"，并生成如下响应： ``` 这是一张水果盘的图片，设计简单。碗由金属制成，带有弯曲的金属丝边缘， 形成开放式结构，可以从各个角度看到水果。碗里，两根香蕉放在一个看起来像是红苹果的水果上面。 香蕉有点过熟，表皮上有褐色的斑点。碗的顶部有一个金属环，可能是用来提携的。 碗放在一个平坦的表面上，背景颜色中性，可以清楚地看到里面的水果。 ``` 你也可以传入类路径资源而不是 URL，如下例所示： ```java theme={"system"} Resource resource = new ClassPathResource("multimodality/multimodal.test.png"); String response = ChatClient.create(chatModel).prompt() .options(AzureOpenAiChatOptions.builder() .deploymentName("gpt-4o").build()) .user(u -> u.text("解释一下你在这张图片上看到了什么？") .media(MimeTypeUtils.IMAGE_PNG, this.resource)) .call() .content(); ``` ## 示例控制器 [创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-azure-openai` 添加到你的 pom (或 gradle) 依赖项中。 在 `src/main/resources` 目录下添加一个 `application.properties` 文件，以启用和配置 OpenAi 聊天模型： ```properties theme={"system"} spring.ai.azure.openai.api-key=你的API密钥 spring.ai.azure.openai.endpoint=你的终结点 spring.ai.azure.openai.chat.options.deployment-name=gpt-4o spring.ai.azure.openai.chat.options.temperature=0.7 ``` 将 `api-key` 和 `endpoint` 替换为你的 Azure OpenAI 凭据。 这将创建一个 `AzureOpenAiChatModel` 实现，你可以将其注入到你的类中。 以下是一个简单的 `@Controller` 类的示例，该类使用聊天模型进行文本生成： ```java theme={"system"} @RestController public class ChatController { private final AzureOpenAiChatModel chatModel; @Autowired public ChatController(AzureOpenAiChatModel chatModel) { this.chatModel = chatModel; } @GetMapping("/ai/generate") public Map generate(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) { return Map.of("generation", this.chatModel.call(message)); } @GetMapping("/ai/generateStream") public Flux generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) { Prompt prompt = new Prompt(new UserMessage(message)); return this.chatModel.stream(prompt); } } ``` ## 手动配置 [AzureOpenAiChatModel](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-azure-openai/src/main/java/org/springframework/ai/azure/openai/AzureOpenAiChatModel.java) 实现了 `ChatModel` 和 `StreamingChatModel`，并使用 [Azure OpenAI Java 客户端](https://learn.microsoft.com/en-us/java/api/overview/azure/ai-openai-readme?view=azure-java-preview)。 要启用它，请将 `spring-ai-azure-openai` 依赖项添加到项目的 Maven `pom.xml` 文件中： ```xml theme={"system"} org.springframework.ai spring-ai-azure-openai ``` 或添加到你的 Gradle `build.gradle` 构建文件中： ```gradle theme={"system"} dependencies { implementation 'org.springframework.ai:spring-ai-azure-openai' } ``` 请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。 `spring-ai-azure-openai` 依赖项还提供对 `AzureOpenAiChatModel` 的访问。有关 `AzureOpenAiChatModel` 的更多信息，请参阅 [Azure OpenAI 聊天](/spring4ai/api/chat/azure-openai-chat)部分。 接下来，创建一个 `AzureOpenAiChatModel` 实例并将其用于生成文本响应： ```java theme={"system"} var openAIClientBuilder = new OpenAIClientBuilder() .credential(new AzureKeyCredential(System.getenv("AZURE_OPENAI_API_KEY"))) .endpoint(System.getenv("AZURE_OPENAI_ENDPOINT")); var openAIChatOptions = AzureOpenAiChatOptions.builder() .deploymentName("gpt-4o") .temperature(0.4) .maxTokens(200) .build(); var chatModel = AzureOpenAiChatModel.builder() .openAIClientBuilder(openAIClientBuilder) .defaultOptions(openAIChatOptions) .build(); ChatResponse response = chatModel.call( new Prompt("生成 5 个著名海盗的名字。")); // 或使用流式响应 Flux streamingResponses = chatModel.stream( new Prompt("生成 5 个著名海盗的名字。")); ``` `gpt-4o` 实际上是 Azure AI 门户中显示的`部署名称`。 发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！