一、引言与概述
我们基于 SpringAI Alibaba Graph 构建了一套 Java 版本的 DeepResearch 系统，实现了从信息搜集、分析到结构化报告生成的全自动流程。
二、整体架构概览
系统节点图
三、核心功能与节点实现
任务规划
共有11个节点，功能如下：
CoordinatorNode（协调节点）：根据用户提问信息，识别任务类型走接下来的流程，非任务类型直接结束；RewriteAndMultiQueryNode（重写和扩展节点）：优化用户提问信息，并扩展为多个语义；BackgroundInvestigationNode（背景调查节点）：利用搜索引擎查询问题相关资讯，可根据主题类型（学术研究、生活旅游、百科、数据分析、通用研究）定向查找对应内容；PlannerNode（规划节点）：将任务拆解为几个步骤；InformationNode（信息节点）：判断搜寻的内容是否充足；HumanFeedbackNode（人类节点）：支持用户新增反馈内容；ResearchTeamNode（研究组节点）：异步并行执行ReseacherNode、CoderNode，等待返回结果；ReseacherNode（研究者节点）：调用搜索引擎，可根据主题类型查找对应内容；CoderNode（数据处理节点）：调用python处理工具，进行数据分析；RagNode（Rag节点）：针对用户上传的文件，针对提问进行检索出相关内容；ReporterNode（报告节点）：整合上述所有节点整理的内容，生成对应的报告；在上述节点的支撑下，引入了如下技术点：多模型配置、提示词工程、多Agent写协作、LLM反思机制、任务规划、Graph（节点并行、流式输出、人类反馈）工作流搭建、工具及自定义MCP配置、RAG专业知识库、链路可观测、报告内容在线可视化。
RAG
spring-ai-alibaba-deepresearch项目集成的 RAG 功能，并非依赖单一的检索方式，而是通过策略模式，灵活地从多种异构数据源中检索信息，并将检索结果进行智能融合与重排序，最终为语言模型提供最相关的上下文信息。RAG功能总体来说包含两个核心阶段：
deepresearch项目的RAG具体功能点如下：
RAG功能支持灵活设置，主要配置项包括：
spring.ai.alibaba.deepresearch.rag.enabled属性可以控制 RAG 功能的开启与关闭。simple: 使用SimpleVectorStore，数据可以持久化到本地文件，通过storage-path配置存储路径。elasticsearch: 使用
ElasticsearchVectorStore，将向量存储在 Elasticsearch 数据库中，可通过classpath:/data/目录加载文件。cron: "0 */5 * * * *") 定时扫描指定目录 (directory)，并将处理后的文件归档到另一个目录 (archive-directory)。/api/rag/data/upload)，允许用户通过文件上传的方式手动摄取文档数据。query-expansion-enabled: 启用查询扩展功能，为原始问题生成多个相关查询，以提高检索覆盖率。query-translation-enabled: 启用查询翻译功能，将查询翻译成指定语言 (post-processing-select-first-enabled: 启用后处理功能，仅选择检索到的第一个文档作为最终结果。该 RAG 功能的实现基于 Spring AI 框架，主要围绕VectorStore和ingFang SC", system-ui, -apple-system, BlinkMacSystemFont, "Helvetica Neue", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif;letter-spacing: 0.034em;font-style: normal;font-weight: normal;">RetrievalAugmentationAdvisor两个核心接口构建。
VectorStoreDataIngestionService服务负责处理实际的文档摄取工作。它使用TikaDocumentReader来读取多种格式的文档（如 PDF, DOCX, MD），然后利用TokenTextSplitter将文档分割成小块，最后将这些文档块添加到配置好的VectorStore中。RagProperties的配置，StateGraph中，实现了 RAG 功能作为工作流中的一个可执行节点。3、架构和流程图
deepresearch的RAG实现在深度整合了Spring AI的能力之外，还进行了扩展。核心是HybridRagProcessor接口及其默认实现DefaultHybridRagProcessor。
下面是deepresearch模块RAG功能的扩展架构图，使用Mermaid绘制：
代码段
架构解析:
**RagDataController**)：负责处理外部请求，例如用户上传文件进行知识库构建。**HybridRagProcessor**)：这是RAG流程的“大脑”，负责协调整个检索和融合过程。它接收查询请求，然后调用注册的各种检索策略。**RetrievalStrategy**)：ProfessionalKbApiStrategy：通过API接口从专业的知识库（如DashScope的知识库）中检索文档。ProfessionalKbEsStrategy：使用自定义的RrfHybridElasticsearchRetriever从Elasticsearch中进行混合检索。这种检索方式结合了传统关键词搜索和向量相似度搜索的优点。UserFileRetrievalStrategy：从用户上传并存储在向量数据库中的文件里检索相关内容。**FusionStrategy**)：RrfFusionStrategy：实现了RRF算法。它接收来自所有检索策略返回的文档列表，根据每个文档在不同列表中的排名计算一个综合得分，并据此对所有文档进行重新排序。为了更直观地理解其工作流程，下面是RAG功能的处理流程图：
数据摄取流程
RAG 节点查询流程
工作流程：
流程解析:
2.HybridRagProcessor接收到查询后，会并发地调用所有已注册的RetrievalStrategy。RetrievalStrategy根据自身的逻辑从对应的数据源（API、ES、文件）检索文档，并返回一个有序的文档列表。4.HybridRagProcessor将所有策略返回的文档列表集合起来，传递给RrfFusionStrategy。5.RrfFusionStrategy对这些列表进行融合与重排序，生成一个最终的高度相关的文档列表。4、总结
spring-ai-alibaba-deepresearch模块中的RAG功能通过将检索和融合过程抽象为策略接口，实现了高度的灵活性和可定制性。其混合检索的能力，特别是结合了RRF算法的多路召回融合机制，能够有效整合来自不同数据源的信息，显著提升信息检索的全面性和准确性，为构建企业级、高可用的RAG应用提供了坚实的基础。
tools搜索能力+MCP
在背景调查节点（BackgroundInvestigationNode）和研究者节点（ResearcherNode）中，大语言模型（LLM）会根据用户输入的问题自动制定相应的搜索方案，并通过调用外部搜索工具获取相关信息。目前系统支持四种搜索工具：Tavily、Serp、百度搜索以及阿里云AI搜索。用户还可选择启用 JinaCrawler服务，该服务能够对搜索结果中提取的链接进行进一步抓取和处理，通过 Jina 提供的解析能力增强原始搜索返回的内容。
用户需在application.yml配置文件中提前配置相应搜索工具所需的 API Key 或相关环境变量，以便正常调用搜索服务。
搜索功能主要由SearchFilterService（搜索过滤服务）实现。该服务根据用户配置选择合适的SearchService执行搜索，并对返回的结果依据黑白名单规则进行排序与过滤。系统提供了LocalConfigSearchFilterService作为这一服务的实现类，支持从 JSON 配置文件中读取网站黑白名单。该配置文件为一个 JSON 数组，每个数组元素为包含host和weight字段的对象。
其中weight的取值范围为 -1 到 1：数值越高，表示对应网站的可信度越高；而取值为负数则表示该网站不可信——即使搜索工具返回了来自该网站的结果，系统也会将其过滤，确保不会传递给 LLM 模型用于后续生成答案。
DeepResearch 支持用户集成额外的 MCP（Model Context Protocol）服务，以增强研究者节点（ResearcherNode）和代码节点（CoderNode）的处理能力。用户可以通过以下两种方式配置 MCP 服务：
mcp-config.json中预先定义 MCP 服务器信息。/chat/stream接口发送请求时，通过mcp_settings字段实时携带 MCP 服务定义。启用MCP服务需要将配置文件的spring.ai.mcp.client.enabled和spring.ai.alibaba.deepresearch.mcp.enabled字段设置为true。
有效的 MCP 服务配置示例如下：
{"researchAgent":{"mcp-servers":[{"url":"https://mcp.amap.com?key=${AMAP_API_KEY}","sse-endpoint":"/sse","description":"高德地图位置服务","enabled":true}]},"coderAgent":{"mcp-servers":[]}}当用户通过 API 传递自定义的 MCP 配置时，后端会利用McpProviderFactory将配置内容动态组装为AsyncMcpToolCallbackProvider，供ChatClient在会话中调用相应的 MCP 工具和服务。这一机制使用户能够灵活扩展系统功能，并在运行时按需引入外部服务。
结果生成
spring-ai-alibaba-deepresearch项目的核心能力之一是将多智能体协作的最终研究成果，动态生成为一份结构清晰、内容详实的综合报告。为了便于用户查阅、归档和分享，项目提供了一套完整的报告生成、管理与导出功能。
该功能主要包含以下核心特性：
threadId标识）完成后，系统会自动捕获最终结论，并将其作为一份报告持久化存储。该功能的实现主要围绕ReportService（报告管理）和ExportService（报告导出）两个核心服务展开，并通过ReportController暴露为 API 接口。
ReportService: 报告的存储和管理接口，包括saveReport、getReport、existsReport和deleteReport等核心方法。ReportRedisService: 这是ReportService的默认实现，使用 Redis 作为后端存储。每份报告以字符串形式存储，并使用report:{threadId}作为键（Key），保证了高效的读写性能和持久化能力。ReportMemoryService: 这是ReportService的另一个实现，使用内存中的ConcurrentHashMap来存储报告。它主要用于开发、测试或在没有 Redis 环境下的快速启动。当 Redis 未启用时，该服务会自动生效。ReportService获取原始报告内容（Markdown 格式），然后执行相应的转换逻辑。ReportService获取报告字符串，并利用FileOperationUtil工具类将其保存为一个.md文件。ReportService获取原始 Markdown 报告。commonmark-java库将 Markdown 文本解析并渲染为 HTML 字符串。为了更好地支持 GitHub Flavored Markdown (GFM)，还集成了commonmark-ext-gfm-tables扩展来处理表格。openhtmltopdf库接收上一步生成的 HTML，并将其转换为 PDF 文档。该库能够处理复杂的 CSS 样式和布局，为了正确显示中文字符，项目中已预置并加载了兼容 CJK 的字体。POST /api/reports/export: 触发异步导出任务，支持指定format(pdf/md)。GET /api/reports/download/{threadId}：提供已导出文件的下载。GET /api/reports/interactive-html/{threadId}: 基于报告内容，通过大语言模型流式生成交互式 HTML 响应。连续对话能力
在当前的DeepResearch架构中，为了支持用户进行多轮交互并基于上下文进行连续提问，系统实现了会话上下文管理功能。该功能确保在同一个用户会话中，用户之前的问题以及工作流上几次运行输出的报告，能够作为历史上下文信息，被有效地注入到本次工作流的特定节点
（BackgroundInvestigationNode和CoordinatorNode）的模型请求中。
核心机制：
GraphId): 用户的每一次请求都会被分配一个唯一的GraphId对象。该对象包含两个关键属性：sessionId: 用于标识一个长期的用户会话。同一对话窗口的多次请求会共享同一个sessionId，从而关联起连续的对话上下文。threadId: 用于标识单次独立的请求或工作流执行。每次请求通常拥有一个唯一的threadId，用于区分同一会话内的不同交互回合。SessionContextService): 该功能的核心由SessionContextService（会话上下文服务）接口及其实现承担。其主要职责是：sessionId，获取与该会话相关的最近数次请求的完整历史记录（SessionHistory）。BackgroundInvestigationNode（背景调查节点）和CoordinatorNode（协调节点）会调用SessionContextService。服务返回的SessionHistory会被作为历史消息添加到发送给大语言模型（LLM）的请求中。这使得LLM能够“记住”之前的对话和报告内容，从而做出具有连贯性和上下文感知的响应。框架目前提供了一个默认的、基于内存的实现——InMemorySessionContextService。该实现将会话历史临时存储在应用内存中，适用于开发、测试或轻量级部署场景。其特点是速度快，但存在数据易丢失（如应用重启后）和难以横向扩展的限制。根据实际生产环境的需求，可以编写自己的SessionContextService实现类。
下图展示了动态报告生成与导出功能的整体架构和组件间的交互关系：
为了更直观地理解其工作流程，下面是报告导出功能（以 PDF 为例）的处理流程图：
spring-ai-alibaba-deepresearch项目的动态报告生成与导出功能，通过将核心业务逻辑（报告管理、格式转换）与 API 接口解耦，构建了一个清晰、可扩展的模块。它不仅提供了多样的导出选项以满足不同用户的需求，还通过集成开源的第三方库（commonmark和openhtmltopdf）确保了高质量的文档输出。同时，通过提供Redis和内存两种存储实现，并利用 Spring Boot 的条件化配置自动切换，兼顾了生产环境的可靠性和开发测试的便捷性。这套功能极大地提升了用户使用的便利性和交互体验，是整个应用闭环中不可或缺的重要一环。
四、使用方式与部署方式
方式一：Docker部署完整项目
构建说明
docker 部署需在本地安装最版本的 docker 软件，安装方式参考官方文档
（https://www.docker.com/）
docker 部署的方式为 docker 多阶段构建：
pnpm build-only命令构建前端项目mvn clean install构建后端项目/app/app.jar/var/www/html/ui/部署说明
在项目根目录下执行以下命令：
$#第一步：在dockerConfig目录下创建.env配置文件，并且填写具体的环境变量$cdspring-ai-alibaba-deepresearch$dockerbuild-tspring-ai-deepresearch.$dockerrun--env-file./dockerConfig/.env-p8080:80--namedeepresearch-dspring-ai-deepresearch
.env 配置文件内容：
#百炼apiKey，地址：https://bailian.console.aliyun.com/AI_DASHSCOPE_API_KEY=<AI_DASHSCOPE_API_KEY>#报告导出地址，填写本地路径AI_DEEPRESEARCH_EXPORT_PATH=<AI_DEEPRESEARCH_EXPORT_PATH>#tavily搜索，地址：https://www.tavily.com/TAVILY_API_KEY=<TAVILY_API_KEY>#langfuse监控，地址：https://langfuse.com/YOUR_BASE64_ENCODED_CREDENTIALS=<YOUR_BASE64_ENCODED_CREDENTIALS>
当容器正确启动之后访问 ：http://localhost:8081/
方式二：
Idea启动后端服务+Docker启动中间件+前端启动
要求：
启动中间件
cdspring-ai-alibaba-deepresearchdockercompose-fdocker-compose-middleware.ymlup-d
这里中间件只启动了 redis 和 elasticsearch。
启动后端项目
首先，编译项目
cdspring-ai-alibaba-deepresearchmvncleaninstall-DskipTests
接着，配置 IDEA环境变量
Edit Configurations -> 选择 DeepResearch 项目 -> Modify options -> Environment variables -> 配置具体的环境变量
最后，启动后端项目。
启动前端项目
下载依赖，并且启动前端项目
cdspring-ai-alibaba-deepresearch/ui-vue3pnpminstallpnpmrundev
前端项目配置说明：
VITE_BASE_URL配置为请求后端 URLhttp://127.0.0.1:8080；/deep-research，这个时候就需要前端代理转发到后端，在vite.config.ts 文件进行配置代理；'/deep-research':{target:'http://localhost:8080',changeOrigin:true,rewrite
path)=>path.replace(/^\/deep-research/,'')}最后，访问前端项目：http://localhost:5173/ui
| 欢迎光临 链载Ai (https://www.lianzai.com/) | Powered by Discuz! X3.5 |