1. 快速开始
1.1 概述
Spring AI 是 Spring 生态系统的 AI 应用开发框架，提供统一的 API 抽象，支持 20+ AI 模型提供商和 19+ 向量数据库。
1.2 最小可运行示例
@SpringBootApplication public class MyAiApplication { public static void main(String[] args) { SpringApplication.run(MyAiApplication.class, args); } @Bean CommandLineRunner demo(ChatClient chatClient) { return args -> { String response = chatClient.prompt() .user("Hello, Spring AI!") .call() .content(); System.out.println(response); }; } }2. 环境搭建与依赖配置
2.1 系统要求
| 组件 | 最低版本 | 推荐版本 |
|---|---|---|
| Java | 17 | 21 |
| Spring Boot | 3.2.x | 3.5.x |
| Maven | 3.6+ | 3.9+ |
2.2 BOM 依赖管理
在pom.xml中添加 Spring AI BOM：
<properties> <spring-ai.version>1.1.4</spring-ai.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>${spring-ai.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>2.3 模型提供商依赖
OpenAI
<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-openai</artifactId> </dependency>application.yml 配置:
spring: ai: openai: api-key: ${OPENAI_API_KEY} base-url: https://api.openai.com # 可选，用于代理 chat: options: model: gpt-4 temperature: 0.7 max-tokens: 2000智谱 AI (ZhiPuAI)
<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-zhipuai</artifactId> </dependency>application.yml 配置:
spring: ai: zhipuai: api-key: ${ZHIPUAI_API_KEY} chat: options: model: glm-4 temperature: 0.7 max-tokens: 2000Ollama（本地模型）
<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-ollama</artifactId> </dependency>application.yml 配置:
spring: ai: ollama: base-url: http://localhost:11434 chat: options: model: llama3 temperature: 0.72.4 环境变量管理
开发环境-.env文件（配合spring-dotenv）：
# .env OPENAI_API_KEY=sk-xxx ZHIPUAI_API_KEY=xxx.xxx PGVECTOR_HOST=localhost PGVECTOR_PORT=5432 PGVECTOR_DATABASE=vectordb PGVECTOR_USER=postgres PGVECTOR_PASSWORD=secret生产环境- Kubernetes Secret：
apiVersion: v1 kind: Secret metadata: name: ai-config type: Opaque stringData: OPENAI_API_KEY: "sk-xxx" ZHIPUAI_API_KEY: "xxx"3. ChatModel 集成指南
3.1 基础对话实现
方式一：使用 ChatClient（推荐）
@Service public class ChatService { private final ChatClient chatClient; public ChatService(ChatClient.Builder chatClientBuilder) { this.chatClient = chatClientBuilder .defaultSystem("你是一个专业的技术助手") .defaultOptions(ChatOptions.builder() .temperature(0.7) .maxTokens(2000) .build()) .build(); } public String chat(String message) { return chatClient.prompt() .user(message) .call() .content(); } }方式二：直接使用 ChatModel
@Service public class AdvancedChatService { @Autowired private ChatModel chatModel; public String chatWithHistory(String message, List<Message> history) { List<Message> messages = new ArrayList<>(history); messages.add(new UserMessage(message)); Prompt prompt = new Prompt(messages); ChatResponse response = chatModel.call(prompt); return response.getResult().getOutput().getText(); } }3.2 系统提示与用户提示
public String chatWithContext(String userMessage) { return chatClient.prompt() .system(""" 你是一个专业的 Java 开发助手。 请遵循以下原则： 1. 提供清晰的代码示例 2. 解释关键概念 3. 指出最佳实践 """) .user(userMessage) .call() .content(); }3.3 参数配置详解
| 参数 | 类型 | 说明 | 推荐值 |
|---|---|---|---|
temperature | Double | 创造性程度（0-2） | 0.3-0.7 |
maxTokens | Integer | 最大生成 token 数 | 500-4000 |
topP | Double | 核采样概率 | 0.9-1.0 |
frequencyPenalty | Double | 频率惩罚（-2~2） | 0.0 |
presencePenalty | Double | 存在惩罚（-2~2） | 0.0 |
运行时动态配置：
public String chatWithOptions(String message, double temperature) { return chatClient.prompt() .user(message) .options(ChatOptions.builder() .temperature(temperature) .maxTokens(1000) .build()) .call() .content(); }3.4 结构化输出
POJO 定义
public record ActorFilms( String actor, List<String> movies ) {} public record WeatherResponse( String city, double temperature, String condition, @JsonProperty("humidity_percent") int humidity ) {}实体映射
public ActorFilms getActorFilms(String actorName) { return chatClient.prompt() .user("列出 " + actorName + " 主演的5部电影") .call() .entity(ActorFilms.class); }列表输出
public List<String> getMovieRecommendations(String genre) { return chatClient.prompt() .user("推荐5部" + genre + "类型的电影") .call() .entity(new ParameterizedTypeReference<List<String>>() {}); }3.5 多轮对话管理
@Service public class ConversationService { private final ChatClient chatClient; private final ChatMemory chatMemory; public String chat(String conversationId, String message) { return chatClient.prompt() .advisors(new MessageChatMemoryAdvisor(chatMemory, conversationId, 10)) .user(message) .call() .content(); } } // ChatMemory 配置 @Bean public ChatMemory chatMemory() { // 内存存储（开发/测试） return new InMemoryChatMemory(); // 或 Redis 存储（生产） // return new RedisChatMemory(redisTemplate, Duration.ofHours(24)); }4. StreamingChatModel 流式响应
4.1 基础流式实现
@RestController @RequestMapping("/api/chat") public class ChatStreamController { @Autowired private ChatClient chatClient; @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<String> streamChat(@RequestParam String message) { return chatClient.prompt() .user(message) .stream() .content(); } }4.2 带上下文的流式响应
@GetMapping(value = "/stream-with-context", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<ServerSentEvent<String>> streamWithContext(@RequestParam String message) { return chatClient.prompt() 
