AgentCPM深度研报助手Java集成实战：SpringBoot微服务构建指南-平芜编程栈

AgentCPM深度研报助手Java集成实战：SpringBoot微服务构建指南

如果你是一名Java开发者，正在寻找一个能帮你自动生成行业分析、市场研究报告的智能工具，并且希望把它无缝集成到自己的SpringBoot项目里，那你来对地方了。AgentCPM深度研报助手就是这样一个能理解复杂指令、自动搜集信息并生成结构化研报的AI模型。今天，我们不谈复杂的算法原理，就手把手地带你走一遍从零开始，在SpringBoot微服务里集成它的全过程。

整个过程其实比你想象的要简单。核心就是三步：准备好你的开发环境，学会怎么调用模型的API，然后把生成的结果处理好、存起来。我会提供完整的项目结构、清晰的代码示例，以及我在集成过程中踩过的一些“坑”和解决方案。目标是让你跟着做一遍，就能在自己的项目里跑起来。

1. 环境准备与项目初始化

在开始写代码之前，我们得先把“舞台”搭好。这里不需要什么特殊的硬件，只要你的开发机满足基本要求就行。

1.1 基础环境检查

首先，确保你的电脑上已经安装了以下软件，版本不要太老：

JDK 8 或以上：推荐使用JDK 11或17，长期支持版本更稳定。打开终端，输入java -version检查一下。
Maven 3.6+：这是我们管理项目依赖和构建的工具。同样，在终端输入mvn -v确认版本。
一个你喜欢的IDE：IntelliJ IDEA、Eclipse 或者 VS Code 都可以，能写Java代码就行。
网络连接：需要能够访问AgentCPM模型提供的API服务。通常你需要从模型提供方获取一个可用的API端点（Endpoint）和访问密钥（API Key）。

1.2 创建SpringBoot项目

最快的方式是使用 Spring Initializr。打开这个网站，按下面这样选：

Project: Maven
Language: Java
Spring Boot: 选择一个稳定的版本，比如 3.1.x 或 3.2.x。
Group & Artifact: 按你的习惯来，例如com.yourcompany和report-agent-demo。
Dependencies: 这里我们勾选几个必需的：
- Spring Web: 用于构建RESTful API。
- Spring Data JPA: 为了后面方便地把研报数据存到数据库。
- Lombok: 减少Java Bean的模板代码，让代码更简洁。
- H2 Database或MySQL Driver: 选一个你熟悉的数据库。为了演示方便，我们可以先用内嵌的H2。

点击“Generate”下载项目压缩包，解压后用IDE打开。

1.3 配置项目依赖与连接信息

打开项目里的pom.xml文件，除了Initializr帮我们生成的依赖，我们还需要添加两个关键的库：

HTTP客户端：用于调用AgentCPM的API。这里推荐使用OkHttp，它简单高效。
JSON处理库：我们使用Spring Boot默认集成的Jackson就够了，不需要额外添加。

在pom.xml的<dependencies>部分加入OkHttp：

<dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>okhttp</artifactId> <version>4.12.0</version> <!-- 请使用当时的最新稳定版 --> </dependency>

接下来，配置应用参数。打开src/main/resources/application.properties文件，添加AgentCPM API的连接信息和你选择的数据库配置：

# AgentCPM API 配置 agentcpm.api.url=https://your-agentcpm-api-endpoint.com/v1/generate agentcpm.api.key=your-secret-api-key-here agentcpm.api.timeout=30000 # 超时时间设为30秒，生成研报可能需要较长时间 # 数据库配置 (以H2内存数据库为例，方便演示) spring.datasource.url=jdbc:h2:mem:testdb spring.datasource.driverClassName=org.h2.Driver spring.datasource.username=sa spring.datasource.password= spring.jpa.database-platform=org.hibernate.dialect.H2Dialect # 启动时在控制台打开H2 Web Console (访问 http://localhost:8080/h2-console) spring.h2.console.enabled=true

重要提示：agentcpm.api.key是敏感信息，在实际生产环境中，绝对不要直接写在配置文件里然后提交到代码仓库。应该使用环境变量、配置中心或密钥管理服务来注入。例如，可以改成agentcpm.api.key=${AGENTCPM_API_KEY}，然后在运行环境里设置这个环境变量。

2. 核心服务层：封装API调用

环境搭好了，我们来写最核心的部分——和AgentCPM模型“对话”的服务。好的封装能让后面的业务逻辑变得清晰简单。

2.1 定义请求与响应模型

我们先创建几个Java类，用来描述要发送给API的数据结构，以及解析它返回的数据。这就像给双方定好沟通的“语言”。

创建一个dto包，在里面新建AgentCpmRequest.java：

package com.yourcompany.reportagentdemo.dto; import lombok.Data; import java.util.List; @Data public class AgentCpmRequest { // 模型名称，根据AgentCPM提供的具体模型名填写 private String model; // 给模型的指令，例如“生成一份关于2024年新能源汽车电池技术的行业研报” private String prompt; // 可选参数，控制生成文本的随机性等 private Double temperature; // 可选参数，生成文本的最大长度 private Integer maxTokens; // 可以传递一些上下文信息 private List<Message> messages; @Data public static class Message { private String role; // 如 "user", "assistant" private String content; } }

再创建AgentCpmResponse.java：

package com.yourcompany.reportagentdemo.dto; import lombok.Data; import java.util.List; @Data public class AgentCpmResponse { private String id; private String object; private Long created; private String model; private List<Choice> choices; private Usage usage; @Data public static class Choice { private Message message; private Integer index; private String finishReason; } @Data public static class Message { private String role; private String content; } @Data public static class Usage { private Integer promptTokens; private Integer completionTokens; private Integer totalTokens; } }

这些字段是根据常见的AI模型API响应格式定义的，你可能需要根据AgentCPM API的实际返回格式稍作调整。

2.2 实现HTTP调用服务

现在，我们创建一个服务类，专门负责和AgentCPM API打交道。在service包下创建AgentCpmService.java。

package com.yourcompany.reportagentdemo.service; import com.fasterxml.jackson.databind.ObjectMapper; import com.yourcompany.reportagentdemo.dto.AgentCpmRequest; import com.yourcompany.reportagentdemo.dto.AgentCpmResponse; import lombok.extern.slf4j.Slf4j; import okhttp3.*; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Service; import javax.annotation.PostConstruct; import java.io.IOException; import java.util.concurrent.TimeUnit; @Slf4j @Service public class AgentCpmService { @Value("${agentcpm.api.url}") private String apiUrl; @Value("${agentcpm.api.key}") private String apiKey; @Value("${agentcpm.api.timeout:30000}") private int timeout; private OkHttpClient client; private final ObjectMapper objectMapper = new ObjectMapper(); public static final MediaType JSON = MediaType.get("application/json; charset=utf-8"); @PostConstruct public void init() { // 初始化HTTP客户端，设置连接超时和读取超时 this.client = new OkHttpClient.Builder() .connectTimeout(timeout, TimeUnit.MILLISECONDS) .readTimeout(timeout, TimeUnit.MILLISECONDS) .writeTimeout(timeout, TimeUnit.MILLISECONDS) .build(); } /** * 调用AgentCPM API生成研报内容 * @param request 包含生成指令的请求对象 * @return 模型生成的研报文本内容 * @throws IOException 网络或API错误 */ public String generateReport(AgentCpmRequest request) throws IOException { // 1. 将请求对象转换为JSON字符串 String requestBody = objectMapper.writeValueAsString(request); log.info("调用AgentCPM API，请求内容：{}", request.getPrompt()); // 2. 构建HTTP请求 RequestBody body = RequestBody.create(requestBody, JSON); Request httpRequest = new Request.Builder() .url(apiUrl) .addHeader("Authorization", "Bearer " + apiKey) .addHeader("Content-Type", "application/json") .post(body) .build(); // 3. 发送请求并获取响应 try (Response response = client.newCall(httpRequest).execute()) { if (!response.isSuccessful()) { String errorBody = response.body() != null ? response.body().string() : "null"; log.error("AgentCPM API调用失败，状态码：{}，响应体：{}", response.code(), errorBody); throw new IOException("API请求失败: " + response.code() + " - " + errorBody); } // 4. 解析响应 String responseBody = response.body().string(); AgentCpmResponse apiResponse = objectMapper.readValue(responseBody, AgentCpmResponse.class); if (apiResponse.getChoices() != null && !apiResponse.getChoices().isEmpty()) { String generatedContent = apiResponse.getChoices().get(0).getMessage().getContent(); log.info("研报生成成功，长度：{}字符", generatedContent.length()); return generatedContent; } else { log.warn("API响应中未包含有效内容"); return ""; } } } }

这个服务类做了几件关键事：读取配置、构建HTTP客户端、组装带有认证头的请求、发送请求、处理响应和错误。注意这里的异常处理，在实际项目中你可能需要定义更细致的业务异常。

3. 异步处理与数据持久化

生成一份深度研报可能需要几十秒甚至更长时间。我们不能让用户在前端一直干等着，所以要用异步任务。同时，生成好的研报也得存到数据库里，方便以后查看和管理。

3.1 设计研报数据实体

首先，定义我们要存什么。在entity包下创建ResearchReport.java。

package com.yourcompany.reportagentdemo.entity; import lombok.Data; import javax.persistence.*; import java.time.LocalDateTime; @Data @Entity @Table(name = "research_report") public class ResearchReport { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @Column(nullable = false) private String topic; // 研报主题，如“新能源汽车电池技术” @Column(columnDefinition = "TEXT") private String userPrompt; // 用户原始指令 @Column(columnDefinition = "LONGTEXT") private String generatedContent; // AI生成的完整研报内容 private String status; // 状态：PENDING, PROCESSING, COMPLETED, FAILED private LocalDateTime createdAt; private LocalDateTime completedAt; @PrePersist protected void onCreate() { createdAt = LocalDateTime.now(); status = "PENDING"; } }

3.2 实现异步生成任务

Spring Boot的@Async注解让异步编程变得非常简单。我们创建一个任务服务，在service包下创建ReportGenerationTaskService.java。

package com.yourcompany.reportagentdemo.service; import com.yourcompany.reportagentdemo.dto.AgentCpmRequest; import com.yourcompany.reportagentdemo.entity.ResearchReport; import com.yourcompany.reportagentdemo.repository.ResearchReportRepository; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.scheduling.annotation.Async; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; @Slf4j @Service @RequiredArgsConstructor public class ReportGenerationTaskService { private final AgentCpmService agentCpmService; private final ResearchReportRepository reportRepository; /** * 异步生成研报任务 * @param reportId 研报记录ID * @param prompt 用户输入的指令 */ @Async // 关键注解，使方法异步执行 @Transactional public void generateReportAsync(Long reportId, String prompt) { ResearchReport report = reportRepository.findById(reportId) .orElseThrow(() -> new RuntimeException("未找到研报记录: " + reportId)); try { log.info("开始异步生成研报，ID: {}, 主题: {}", reportId, report.getTopic()); report.setStatus("PROCESSING"); reportRepository.save(report); // 构建请求 AgentCpmRequest request = new AgentCpmRequest(); request.setModel("agentcpm-latest"); // 使用实际的模型名称 request.setPrompt(prompt); request.setTemperature(0.7); request.setMaxTokens(2000); // 调用API String content = agentCpmService.generateReport(request); // 更新数据库 report.setGeneratedContent(content); report.setStatus("COMPLETED"); report.setCompletedAt(java.time.LocalDateTime.now()); reportRepository.save(report); log.info("研报生成任务完成，ID: {}", reportId); } catch (Exception e) { log.error("研报生成任务失败，ID: {}", reportId, e); report.setStatus("FAILED"); reportRepository.save(report); } } }

为了让@Async生效，别忘了在主应用类或配置类上添加@EnableAsync注解。

3.3 创建数据访问层

Spring Data JPA让数据库操作变得极其简单。在repository包下创建接口ResearchReportRepository.java。

package com.yourcompany.reportagentdemo.repository; import com.yourcompany.reportagentdemo.entity.ResearchReport; import org.springframework.data.jpa.repository.JpaRepository; import org.springframework.stereotype.Repository; @Repository public interface ResearchReportRepository extends JpaRepository<ResearchReport, Long> { // 可以在这里定义自定义查询方法，例如按状态查找 // List<ResearchReport> findByStatus(String status); }

4. 构建REST API控制器

最后，我们需要一个入口，接收用户的请求，触发异步任务，并返回任务状态。在controller包下创建ReportController.java。

package com.yourcompany.reportagentdemo.controller; import com.yourcompany.reportagentdemo.entity.ResearchReport; import com.yourcompany.reportagentdemo.repository.ResearchReportRepository; import com.yourcompany.reportagentdemo.service.ReportGenerationTaskService; import lombok.RequiredArgsConstructor; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; import java.util.Map; @RestController @RequestMapping("/api/reports") @RequiredArgsConstructor public class ReportController { private final ResearchReportRepository reportRepository; private final ReportGenerationTaskService taskService; /** * 提交一个新的研报生成请求 * @param requestBody 包含topic和prompt * @return 创建的任务信息 */ @PostMapping public ResponseEntity<Map<String, Object>> createReport(@RequestBody Map<String, String> requestBody) { String topic = requestBody.get("topic"); String prompt = requestBody.get("prompt"); if (topic == null || prompt == null) { return ResponseEntity.badRequest().body(Map.of("error", "topic和prompt不能为空")); } // 1. 创建研报记录 ResearchReport report = new ResearchReport(); report.setTopic(topic); report.setUserPrompt(prompt); ResearchReport savedReport = reportRepository.save(report); // 2. 触发异步生成任务 taskService.generateReportAsync(savedReport.getId(), prompt); // 3. 立即返回，告知用户任务已提交 return ResponseEntity.ok(Map.of( "message", "研报生成任务已提交", "reportId", savedReport.getId(), "status", savedReport.getStatus(), "checkUrl", "/api/reports/" + savedReport.getId() )); } /** * 根据ID查询研报生成状态和结果 * @param id 研报ID * @return 研报详情 */ @GetMapping("/{id}") public ResponseEntity<ResearchReport> getReport(@PathVariable Long id) { return reportRepository.findById(id) .map(ResponseEntity::ok) .orElse(ResponseEntity.notFound().build()); } }

这个控制器提供了两个核心接口：一个是提交任务（POST /api/reports），一个是查询结果（GET /api/reports/{id}）。用户提交后立刻得到响应，然后可以通过轮询查询接口来获取生成进度和最终结果。

5. 运行与测试

代码都写完了，我们来试试看它能不能跑起来。

启动应用：在IDE里找到主启动类（通常叫ReportAgentDemoApplication），运行它。看到Spring Boot的启动日志，没有报错就成功了一半。
测试API：打开Postman或任何你喜欢的API测试工具。
- 提交任务：发送一个POST请求到http://localhost:8080/api/reports，Body用JSON格式：
```
{ "topic": "2024年人工智能芯片行业分析", "prompt": "请生成一份关于2024年人工智能芯片（AI Chip）技术发展趋势、主要厂商竞争格局、以及市场前景的深度行业研报，要求数据详实、观点清晰。" }
```
  你应该会立刻收到一个包含reportId的响应。
- 查询结果：用上一步拿到的reportId，发送GET请求到http://localhost:8080/api/reports/{reportId}。一开始状态是PENDING或PROCESSING，过一会儿（取决于模型生成速度）再查，如果状态变成COMPLETED，就能在响应体里看到generatedContent字段里的完整研报了。
查看数据库：如果你配置的是H2内存数据库，并且开启了控制台（spring.h2.console.enabled=true），可以访问http://localhost:8080/h2-console，JDBC URL填jdbc:h2:mem:testdb，就能看到RESEARCH_REPORT表里的数据了。