SpringAI基础使用

一、环境准备

1. 安装依赖工具

   • JDK 17+（必须，Spring Boot 3.3+ 和 SpringAI 依赖此版本）。
   • IDE（如 IntelliJ IDEA）。
   • Maven/Gradle（项目管理工具，推荐 Maven）。

2. 获取 AI 服务密钥

   • 申请 OpenAI API Key（或其他兼容大模型的 API Key），可通过以下途径：
     • GPT-API-free（免费版支持 GPT-3.5/4）。
     • AiCore（需注册，部分功能付费）。
     • 直接购买（如淘宝搜索 “OpenAI Key”）。

二、创建 Spring Boot 项目

1. 初始化项目

   • 通过 Spring Initializr 创建项目，选择以下依赖：
     • Spring Web（Web 服务支持）。
     • Spring AI OpenAI Starter（集成 OpenAI 大模型）。
     • Lombok（可选，简化代码）。

2. 配置 pom.xml

   <dependencies>
       <dependency>
           <groupId>org.springframework.boot</groupId>
           <artifactId>spring-boot-starter-web</artifactId>
       </dependency>
       <dependency>
           <groupId>org.springframework.ai</groupId>
           <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
       </dependency>
       <dependency>
           <groupId>org.projectlombok</groupId>
           <artifactId>lombok</artifactId>
           <optional>true</optional>
       </dependency>
   </dependencies>
   <dependencyManagement>
       <dependencies>
           <dependency>
               <groupId>org.springframework.ai</groupId>
               <artifactId>spring-ai-bom</artifactId>
               <version>1.0.0-M1</version>
               <type>pom</type>
               <scope>import</scope>
           </dependency>
       </dependencies>
   </dependencyManagement>
   

三、配置 AI 服务信息

1. 修改 application.properties

   spring:
     ai:
       openai:
         api-key: sk-xxxxxxxxxxx  # OpenAI API Key
         base-url: https://api.chatanywhere.tech  # 代理地址（国内推荐）
   

    
   • 若直接访问 OpenAI，需配置代理（在启动类中添加系统属性）：

     @SpringBootApplication
     public class Application {
         public static void main(String[] args) {
             System.setProperty("proxyHost", "127.0.0.1"); // 代理地址
             System.setProperty("proxyPort", "7890");      // 代理端口
             SpringApplication.run(Application.class, args);
         }
     }
     

四、实现基础对话功能

1. 创建控制器 AIController

   @RestController
   @RequestMapping("/ai")
   public class AIController {
       private final ChatClient chatClient;
   
       public AIController(ChatClient.Builder chatClientBuilder) {
           this.chatClient = chatClientBuilder.build();
       }
   
       @GetMapping("/chat")
       public String chat(@RequestParam String msg) {
           return chatClient.prompt()
                   .user(msg)        // 用户输入
                   .call()           // 调用大模型
                   .content();       // 获取响应内容
       }
   }
   

五、高级功能扩展

1. 角色预设与流式响应

• 角色预设（配置默认系统提示）

  @Configuration
  public class AIConfig {
      @Bean
      public ChatClient chatClient(ChatClient.Builder builder) {
          return builder.defaultSystem("你是Java老师，名字叫考拉AI") // 预设角色
                        .build();
      }
  }
  

• 流式响应（逐字符输出）

  @GetMapping(value = "/chat/stream", produces = "text/html;charset=UTF-8")
  public Flux<String> chatStream(@RequestParam String msg) {
      return chatClient.prompt().user(msg).stream().content(); // 流式返回
  }
  

2. 函数调用（集成自定义工具）

1. 定义工具函数

   public class WeatherFunction implements Function<WeatherFunction.Request, WeatherFunction.Response> {
       public record Request(String location) {}
       public record Response(String weather) {}
   
       @Override
       public Response apply(Request request) {
           return new Response("济南天气：晴转多云"); // 模拟工具返回结果
       }
   }
   

2. 注册函数为 Bean

   @Configuration
   public class AIConfig {
       @Bean
       @Description("查询某地天气") // 帮助模型理解函数用途
       public WeatherFunction weatherFunction() {
           return new WeatherFunction();
       }
   }
   

3. 在对话中调用工具

   @GetMapping("/function")
   public String callFunction() {
       return chatClient.prompt()
               .user("济南天气如何？")
               .function("weatherFunction", new WeatherFunction.Request("济南")) // 调用工具
               .call()
               .content();
   }
   

3. 向量数据库与 RAG（检索增强生成）

1. 集成向量数据库（如 Chroma）

   @Bean
   public VectorStore vectorStore(EmbeddingModel embeddingModel) {
       return new ChromaVectorStore(embeddingModel, "chroma-db"); // 创建 Chroma 存储
   }
   

2. 向量化文本并写入数据库

   @GetMapping("/rag/index")
   public void indexDocuments() {
       List<Document> documents = Arrays.asList(
           new Document("苏州大学 船舶电气工程技术 本科"),
           new Document("实习经历：算法工程师，负责图像识别项目")
       );
       vectorStore.add(documents); // 向量化并写入
   }
   

3. 基于 RAG 的问答

   @GetMapping("/rag/query")
   public String ragQuery(@RequestParam String question) {
       List<Document> context = vectorStore.similaritySearch(question, 3); // 检索相关文档
       Prompt prompt = new Prompt(
           "根据以下信息回答问题：" + context + "\n问题：" + question
       );
       return chatModel.call(prompt).getContent(); // 结合上下文回答
   }
   

4. 多模态支持（文本 + 图像 / 音频）

• 文生图（OpenAI DALL-E）

  @Autowired
  private OpenAiImageModel imageModel;
  
  @GetMapping("/image")
  public String generateImage(@RequestParam String prompt) {
      ImageResponse response = imageModel.call(
          new ImagePrompt(prompt, OpenAiImageOptions.builder()
              .withModel("dall-e-3")
              .withN(1)
              .build())
      );
      return response.getUrl(); // 返回图片 URL
  }
  

• 语音合成（Text-to-Speech）

  @Autowired
  private OpenAiAudioSpeechModel speechModel;
  
  @GetMapping("/speech")
  public void textToSpeech() throws IOException {
      SpeechResponse response = speechModel.call(
          new SpeechPrompt("你好，这是语音示例", 
              OpenAiAudioSpeechOptions.builder()
                  .withVoice(Voice.ALLOY)
                  .build())
      );
      Files.write(Paths.get("output.mp3"), response.getAudioBytes()); // 保存音频文件
  }
  

六、运行与测试

1. 启动项目

   mvn spring-boot:run
   

2. 测试接口

   • 访问 http://localhost:8080/ai/chat?msg=你好 测试基础对话。
   • 访问流式接口 http://localhost:8080/ai/chat/stream?msg=讲个故事 观察实时输出。
   • 调用工具接口 http://localhost:8080/ai/function 验证函数集成。

七、最佳实践建议

1. 提示词设计

   • 使用结构化提示（如 SystemMessage + UserMessage）明确角色和目标。
   • 添加占位符（如 {user_input}）动态生成提示，参考：

     java

     SystemMessage system = new SystemMessage("你是{role}，需回答{topic}相关问题");
     UserMessage user = new UserMessage("请解释SpringAI的作用");
     

2. 性能优化

   • 对长文本进行分块（TokenTextSplitter），避免超过模型输入限制。
   • 缓存高频查询结果，减少大模型调用次数。

3. 安全与成本控制

   • 限制未认证用户的调用频率，避免 API Key 泄露。
   • 监控大模型调用成本（如 OpenAI 的 Token 消耗），设置预算预警。

通过以上步骤，可快速搭建基于 SpringAI 的 AI 应用，实现对话交互、工具集成、知识检索等功能。根据需求扩展向量数据库、多模态支持或复杂提示词逻辑，即可构建生产级 AI 原生应用。