Spring AI 1.1.4 开发者使用手册

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 系统要求组件最低版本推荐版本Java1721Spring Boot3.2.x3.5.xMaven3.6+3.9+2.2 BOM 依赖管理在pom.xml中添加 Spring AI BOM：properties spring-ai.version1.1.4/spring-ai.version /properties ​ dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement2.3 模型提供商依赖OpenAIdependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependencyapplication.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 groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-zhipuai/artifactId /dependencyapplication.yml 配置:spring: ai: zhipuai: api-key: ${ZHIPUAI_API_KEY} chat: options: model: glm-4 temperature: 0.7 max-tokens: 2000Ollama（本地模型）dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-ollama/artifactId /dependencyapplication.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, ListMessage history) { ListMessage 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 参数配置详解参数类型说明推荐值temperatureDouble创造性程度（0-2）0.3-0.7maxTokensInteger最大生成 token 数500-4000topPDouble核采样概率0.9-1.0frequencyPenaltyDouble频率惩罚（-2~2）0.0presencePenaltyDouble存在惩罚（-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, ListString 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 ListString getMovieRecommendations(String genre) { return chatClient.prompt() .user("推荐5部" + genre + "类型的电影") .call() .entity(new ParameterizedTypeReferenceListString() {}); }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 FluxString 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 FluxServerSentEventString streamWithContext(@RequestParam String message) { return chatClient.prompt()