李眉（运维）端着茶杯飘过来："小崔，Ollama 我给你装好了，llama3 也拉下来了。你那 API Key 别写死在代码里啊，进环境变量。"

环境准备与配置

定义与作用

在编写 Spring AI 代码之前，需要完成三项环境准备：获取 API Key（或安装本地模型）、添加 Maven 依赖、配置 application.yml。Spring AI 的自动配置机制会根据 classpath 中的 Starter 和 YAML 属性自动创建 ChatModel 和 ChatClient.Builder Bean。

核心原理：配置加载流程

图释：Spring Boot 启动时，OpenAiAutoConfiguration 检查 spring.ai.openai.api-key 是否有值。如果有，创建 OpenAiChatModel Bean；如果没有，检查 Ollama 配置。两者都没有则启动失败。

API Key 获取

OpenAI

  1. 访问 https://platform.openai.com/api-keys
  2. 登录后点击「Create new secret key」
  3. 复制 Key（只显示一次），设置为环境变量：
# Windows PowerShell
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-xxx...", "User")

Ollama 本地模型（免费，推荐开发环境）

# 1. 下载安装 Ollama：https://ollama.com/download
# 2. 拉取模型
ollama pull llama3
# 3. 验证模型可用
ollama run llama3 "Hello"

Ollama 默认监听 http://localhost:11434，无需 API Key。

application.yml 配置详解

OpenAI 配置

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com  # 可改为代理地址
      chat:
        enabled: true
        options:
          model: gpt-4o         # 模型名称
          temperature: 0.7       # 0.0~1.0，越高越随机
          max-tokens: 2000       # 最大返回 Token 数

Ollama 配置

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        enabled: true
        options:
          model: llama3
          temperature: 0.7

多环境切换（推荐）

# application-dev.yml（开发环境，免费）
spring:
  ai:
    openai:
      api-key: unused       # Ollama 不需要 API Key
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: llama3

# application-prod.yml（生产环境）
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o
    ollama:
      chat:
        enabled: false       # 生产环境关闭 Ollama

配置属性速查表

属性说明示例值
spring.ai.openai.api-keyOpenAI API 密钥${OPENAI_API_KEY}
spring.ai.openai.base-urlAPI 地址（可改为代理）https://api.openai.com
spring.ai.openai.chat.options.model对话模型gpt-4o / gpt-3.5-turbo
spring.ai.openai.chat.options.temperature生成随机度0.7
spring.ai.ollama.base-urlOllama 服务地址http://localhost:11434
spring.ai.ollama.chat.options.model本地模型名llama3 / mistral
spring.ai.retry.max-attemptsAPI 调用最大重试次数3
spring.ai.retry.backoff.initial-interval重试初始间隔1000（毫秒）

易错场景与面试考点

易错场景一：API Key 未设置导致启动失败

# ❌ 错误：spring.ai.openai.api-key 为空
spring:
  ai:
    openai:
      chat:
        options:
          model: gpt-4o

问题分析

Spring AI 的 OpenAiAutoConfiguration 使用 @ConditionalOnProperty 检查 spring.ai.openai.api-key。如果该属性为空，自动配置跳过，不会创建 ChatModel Bean，运行时 @Autowired ChatClient 注入失败。

# ✅ 正确做法：通过环境变量设置
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}  # 从环境变量读取

或者在 IDE 的 Run Configuration 中添加环境变量 OPENAI_API_KEY=sk-xxx。

易错场景二：Ollama 未启动就运行应用

# ❌ 错误：Ollama 服务未运行
# 应用启动后调用 ChatClient 时报错：
# Connection refused: localhost/127.0.0.1:11434

问题分析

Ollama 需要先启动服务才能接受 API 请求。启动方式：

# ✅ 正确：先启动 Ollama 服务（通常安装后自动启动）
ollama serve
# 或直接用 ollama run 启动模型交互（也会启动服务）
ollama run llama3

本章小结

  • 环境准备三步走：API Key / Ollama → Maven 依赖 → application.yml
  • spring.ai.openai.api-key 非空时自动创建 OpenAiChatModel Bean
  • 开发环境推荐 Ollama（免费），生产环境推荐 OpenAI（效果更好）
  • API Key 通过环境变量 ${OPENAI_API_KEY} 传入，不要硬编码
  • 多环境用 application-{profile}.yml 切换配置