Azure OpenAI + Spring AI 集成与配置详解

---

概述

在AI应用快速落地的当下，企业级开发者越来越多地选择云端AI服务来提升生产力和创新能力。Azure OpenAI Service 提供了企业级的 GPT-4、GPT-4o 等大模型能力，结合 Spring AI 框架，开发者可以用 Spring Boot 的方式快速集成、扩展和部署智能应用。

本文将系统梳理 Azure OpenAI + Spring AI 的集成方案，涵盖认证方式、依赖管理、常见配置、代码范例、多模态支持、Token 管理及常见问题排查。并通过三种 Mermaid 图表（流程图、状态图、时序图）帮助你建立系统性认知，知其然更知其所以然。

---

名词解释

• Azure OpenAI Service：微软 Azure 提供的 OpenAI 大模型托管服务，支持 GPT-4、GPT-4o、DALL·E 等模型，具备企业级安全、合规和弹性。
• Spring AI：Spring 官方推出的 AI 集成开发框架，旨在简化 AI 服务与 Spring Boot 应用的集成，支持多种主流大模型平台。
• Deployment Name：Azure OpenAI 中模型部署时自定义的唯一标识，调用接口时必须填写。
• Model Name：OpenAI 官方定义的模型标识，如 gpt-4o、gpt-3.5-turbo。
• maxTokens / maxCompletionTokens：控制单次生成内容的最大 token 数量，不同模型使用不同参数。

---

项目背景与发展历史

OpenAI 自 2020 年 GPT-3 发布以来，推动了自然语言处理的革命。微软 Azure 成为 OpenAI 的深度合作伙伴，将 GPT 系列模型引入 Azure 云平台，并提供合规、可控、企业级 SLA 的大模型服务。与此同时，Spring 生态早在 2023 年推出了 Spring AI，为 Java/Spring 开发者提供与 AI 平台的无缝集成能力。

发展里程碑：

• 2021：Azure OpenAI Service 公测，支持 GPT-3。
• 2023：Spring AI 正式发布，支持 Azure OpenAI、OpenAI、Hugging Face、百度文心一言等。
• 2024：Azure OpenAI 支持 GPT-4o 多模态模型，Spring AI 持续更新完善。

相关权威资料

• Azure OpenAI 官方文档
• Spring AI 官方文档
• Spring AI Azure OpenAI 示例

---

结构简化与优化（Mermaid 图）

1. Flowchart：集成流程总览

说明：

• 流程自上而下，涵盖从注册服务到最终应用部署的全流程。
• 每一步均可细化，如 API Key 可选用环境变量，部署可用 Docker/K8s 等。

---

2. StateDiagram-v2：认证方式状态切换

说明：

• 三种认证方式互斥，开发时任选其一。
• 企业推荐 Entra ID，个人和测试推荐 API Key。

---

3. SequenceDiagram：请求处理时序

说明：

• 用户请求到达 Controller，经由 Spring AI 封装后发往 Azure OpenAI。
• 支持同步/流式响应。

---

详细集成与配置

1. 认证方式

1.1 Azure API Key & Endpoint（推荐）

spring:
  ai:
    azure:
      openai:
        api-key: ${AZURE_OPENAI_API_KEY}
        endpoint: ${AZURE_OPENAI_ENDPOINT}

• 安全建议：API Key 通过环境变量管理，避免泄漏。

1.2 OpenAI Key（直连 OpenAI）

spring:
  ai:
    azure:
      openai:
        openai-api-key: ${OPENAI_API_KEY}
        chat:
          options:
            deployment-name: ${OPENAI_MODEL_NAME}

• Endpoint 自动指向 api.openai.com/v1。

1.3 Microsoft Entra ID（原 Azure AD）

• TokenCredential 自动注入，仅需配置 endpoint。

---

2. 依赖引入及管理

Maven 依赖：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-azure-openai</artifactId>
</dependency>

推荐使用 BOM 管理依赖版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>最新版本</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

---

3. 常见配置参数

配置项	说明	示例/默认值
spring.ai.azure.openai.api-key	Azure OpenAI API Key	-
spring.ai.azure.openai.endpoint	Azure OpenAI Endpoint	-
spring.ai.azure.openai.openai-api-key	OpenAI Key	-
spring.ai.azure.openai.chat.options.deployment-name	Azure 部署名	gpt-4o
spring.ai.azure.openai.chat.options.temperature	采样温度	0.7
spring.ai.azure.openai.chat.options.maxTokens	最大 token 数	-
spring.ai.azure.openai.chat.options.maxCompletionTokens	reasoning 模型用	-

注意：
maxTokens 和 maxCompletionTokens 不能同时设置，且取决于模型类型。

---

4. 代码示例

4.1 基础 Controller

@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 = "Tell me a joke") String message) {
        return Map.of("generation", this.chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
    public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        Prompt prompt = new Prompt(new UserMessage(message));
        return this.chatModel.stream(prompt);
    }
}

4.2 多模态（图文混合）

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("Explain what do you see on this picture?")
    .media(MimeTypeUtils.IMAGE_PNG, resource))
    .call()
    .content();

4.3 运行时参数覆盖

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        AzureOpenAiChatOptions.builder()
            .deploymentName("gpt-4o")
            .temperature(0.4)
        .build()
    ));

---

5. Token 限制参数

• 推理模型（如 o1, o3, o4-mini）：用 maxCompletionTokens
• 非推理模型（如 gpt-4o, gpt-3.5-turbo）：用 maxTokens
• 不能同时设置，否则报错。

---

6. 常见问题与速记口诀

问题	速记口诀
API Key 泄漏	环境变量最安全，配置不明别硬写
Deployment Name 配错	Azure Portal 查一遍，名字完全对得上
maxTokens/maxCompletionTokens 报错	只选一个，模型说明先查明

---

总结 & 系统性认知

• Azure OpenAI + Spring AI 为 Java/Spring 开发者提供了企业级、安全、易用的 AI 服务集成方案。
• 认证方式灵活，推荐用环境变量管理密钥。
• 依赖 BOM 管理，配置参数要分清模型类型。
• 多模态能力（如 GPT-4o 图文混合）已支持，开发潜力巨大。
• 参数覆盖、流式输出、Token 管理等高级用法，提升业务体验与安全性。

---

参考文献

1. Spring AI 官方文档
2. Azure OpenAI 官方文档
3. Spring AI Azure OpenAI 示例
4. OpenAI 平台文档
5. 微软 Azure 官方博客

---

如需源码与模板，建议访问官方仓库或联系企业架构师进行最佳实践咨询。