1. 项目概述从“检索增强”到“智能体驱动”的范式跃迁去年年底我们团队启动了一个代号为“探路者”的内部项目核心目标是为公司内部的技术文档和产品手册构建一个智能问答系统。最初的方案毫无悬念地选择了当时最火热的RAG检索增强生成架构。我们花了几个月时间从文档切片、向量化嵌入到多路召回和重排序搭建了一个看起来相当标准的RAG系统。上线初期它确实解决了一些简单的事实性问题比如“产品X的默认端口号是多少”或者“如何配置Y功能的参数”。但很快我们遇到了瓶颈面对稍微复杂一点的查询比如“我想实现一个类似A功能的效果但在B场景下遇到了C问题有什么替代方案或排查思路”系统的回答要么是生硬地拼凑几段不相关的文档片段要么干脆回答“根据现有文档未找到相关信息”。这种“检索-拼接-生成”的机械模式暴露了传统RAG的深层局限它本质上是一个被动的、基于关键词匹配的“文档搬运工”缺乏对问题背后意图的深度理解更不具备主动规划、推理和调用工具的能力。用户得到的是一堆“可能相关”的信息碎片而不是一个经过思考、整合后的“解决方案”。正是这些痛点促使我们在2026年初决定对系统进行一次彻底的架构升级从传统的RAG范式转向结合了智能体Agentic Search与技术图谱Tech Graph的新架构。今天复盘的这个项目就是这次转型的完整记录涵盖了从设计思路、技术选型、核心实现到踩坑经验的全过程。2. 架构演进为什么是Agentic Search Tech Graph2.1 传统RAG的“天花板”与核心痛点在深入新架构之前有必要先厘清我们抛弃旧方案的具体原因。传统的RAG流水线通常包括文档加载与切片、文本向量化、向量数据库存储、查询向量化与相似度检索、检索结果重排序、最后将Top-K片段送入大语言模型生成答案。这套流程在应对明确、具体的事实查询时是高效的但其设计哲学决定了它的能力边界。第一个痛点是“意图理解”的缺失。用户的自然语言查询是模糊和多义的。例如“帮我看看服务启动失败的问题”这个请求传统RAG会将其转换为一个向量然后去向量库中寻找包含“服务”、“启动”、“失败”等词频高或语义相近的片段。它无法理解用户可能身处何种环境K8s还是物理机服务是什么类型Web服务还是数据库日志特征是什么。结果就是召回了一堆泛泛而谈的“系统服务故障排查”文档而非针对性的解决方案。第二个痛点是“静态知识”的局限。向量库里的嵌入是凝固的它只记录了文档成文那一刻的知识。但技术世界是动态的软件版本在迭代API接口在变更最佳实践在演进。一个基于三个月前文档构建的RAG系统很可能给出已经过时甚至错误的建议比如推荐一个已被弃用的配置项。第三个痛点是“推理与规划”能力的匮乏。复杂问题往往需要多步推理和子任务分解。比如“优化数据库查询性能”这可能需要先诊断当前慢查询步骤1再分析表结构和索引步骤2最后提出具体的索引优化或查询重写建议步骤3。传统RAG是一次性召回它没有这种分步执行、步步为营的“思考”过程。2.2 Agentic Search赋予搜索“思考”和“行动”的能力Agentic Search智能体驱动搜索的核心思想是将一次性的“查询-响应”转变为一次有状态的、可规划的“任务求解”过程。我们将其抽象为一个具备感知、规划、执行、反思循环的智能体。在我们的架构中这个智能体接收到用户查询后其工作流如下感知与意图解析利用LLM分析用户查询识别核心意图、实体、约束条件和隐含上下文。这一步的输出是一个结构化的“任务描述”而不仅仅是一个查询向量。任务规划与分解针对复杂任务智能体会制定一个执行计划。例如对于“性能优化”计划可能是[调用“慢查询分析工具”] - [根据分析结果检索“索引设计指南”] - [综合两者生成报告]。工具调用与执行智能体拥有一个“工具箱”。这不仅包括传统的向量检索工具还包括图谱查询工具用于查询技术实体间的关联。API调用工具用于获取实时信息如当前服务器状态、最新版本号。代码执行工具沙盒环境用于验证某个配置片段或执行简单的诊断脚本。计算工具用于进行参数计算、单位换算等。反思与答案合成智能体收集各步骤的执行结果进行批判性验证和整合最终生成一个连贯、准确且可追溯的答案并说明其推理依据。注意引入智能体意味着系统复杂度的指数级上升。最大的挑战从“如何提高召回率”变成了“如何确保智能体规划的可控性和工具调用的安全性”。必须为智能体的行动设定严格的边界和验证机制。2.3 Tech Graph构建结构化的技术知识“地图”如果说Agent赋予了系统“思考”的能力那么Tech Graph技术图谱则提供了“思考”所依赖的结构化知识体系。我们不再仅仅将文档视为一堆文本片段而是从中抽取出实体如技术概念、产品组件、API接口、配置参数、故障代码和关系如A依赖B、C是D的一种配置方式、E会导致F错误构建成一个图数据库。这张“技术地图”带来了几个根本性优势精准关联检索当用户提到“Nginx”时我们可以通过图谱迅速关联到其相关的“负载均衡配置”、“日志格式”、“与上游服务如Tomcat的连接参数”等实现跨文档的精准知识聚合。支持复杂推理图谱能很好地回答“为什么”和“怎么样”的问题。例如“为什么修改了参数max_connections后连接池报错”通过图谱可以追溯max_connections- (限制) - [数据库连接池] - (依赖) - [应用服务器线程池] - (如果大于) - 可能导致资源耗尽。这种链式推理是向量检索难以实现的。知识可视化与探索图谱本身可以作为前端的一个交互式探索界面帮助用户主动发现知识关联而不仅仅是被动问答。Agentic Search与Tech Graph的关系二者是相辅相成的。Tech Graph为Agent提供了结构化的、可推理的知识库是比向量库更“智能”的记忆体。而Agent利用其规划能力可以发起对图谱的多跳查询、路径探索将图谱的价值最大化。例如智能体可以将用户问题“A服务和B服务通信超时”分解为查询A服务的网络配置图谱实体、查询B服务的防火墙规则图谱实体、检索历史上类似案例的解决方案向量检索图谱关联。3. 核心实现构建新一代智能问答引擎3.1 系统整体架构设计我们的新系统架构分为五层自底向上分别是数据源层、知识加工层、知识存储层、智能体引擎层和应用层。数据源层整合了各类非结构化数据产品PDF、Markdown文档、Confluence页面、GitHub Wiki和半结构化/结构化数据API Schema (Swagger/OpenAPI)、数据库表结构说明、系统部署清单。知识加工层这是最核心的预处理环节采用双管道并行处理。向量化管道对非结构化文本进行智能分块不仅按长度更按语义章节然后使用混合嵌入模型我们采用了BGE-M3因其在密集检索、稀疏检索和多向量检索上的均衡表现生成向量。图谱构建管道利用LLM作为信息抽取器。我们设计了一套详细的提示词指导LLM从文档中抽取技术实体和关系。例如从一段“配置Redis缓存”的文档中抽取出实体[Redis, maxmemory-policy, allkeys-lru]以及关系[(Redis, has_configuration, maxmemory-policy), (maxmemory-policy, can_be_set_to, allkeys-lru)]。初始构建后还需要人工进行少量校准确保图谱质量。知识存储层向量数据库选用Qdrant主要看中其过滤查询性能和对多向量、标量数据混合存储的支持方便后续做混合检索。图数据库选用Neo4j。它的Cypher查询语言直观强大能很好地表达技术实体间复杂的关系且社区活跃可视化工具完善。智能体引擎层这是系统的大脑。我们基于LangGraph框架来构建智能体的工作流。LangGraph提供了清晰的状态管理和基于图的流程控制非常适合描述智能体“规划-行动-观察”的循环。智能体的核心“工具集”包括向量检索工具、图谱查询工具封装Cypher查询、计算器、以及一个安全的子进程调用工具用于执行预定义的安全脚本如ping、curl健康检查。应用层提供标准的Web API接口和一个交互式聊天界面。界面会展示智能体的“思考过程”即其规划步骤和工具调用记录增强结果的可解释性。3.2 技术图谱的构建与迭代实战构建高质量的技术图谱是整个项目的难点和重点。我们走了一些弯路总结出以下关键步骤和心得。第一步定义本体Ontology这是图谱的“蓝图”。我们召集了各技术领域的专家共同定义了我们技术栈的核心实体类型和关系类型。例如实体类型技术产品(如Kafka, MySQL)、配置项、API接口、错误码、部署环境、最佳实践。关系类型依赖、配置于、调用、导致、替代方案、隶属于版本。一个清晰的本体能极大提升后续信息抽取的准确性和一致性。第二步基于LLM的信息抽取我们尝试了直接使用预训练NER模型但在技术领域专有名词上效果不佳。最终方案是采用LLM我们使用Qwen2.5-72B-Instruct的API进行零样本或少样本抽取。关键技巧在于设计结构化的提示词你是一个技术文档分析专家。请从以下技术文档片段中提取所有提到的技术实体及其关系。 请严格按照以下JSON格式输出 { entities: [{name: 实体名, type: 实体类型}], relations: [{source: 源实体名, target: 目标实体名, type: 关系类型}] } 文档片段此处插入文档文本为了提高效率我们将文档预处理成较小的语义块如一个配置章节、一个API说明批量提交给LLM处理。然后编写后处理脚本合并重复实体解决共指问题如“该服务”指代前文的“订单服务”。实操心得LLM抽取会有“幻觉”可能创造出不存在的实体或关系。必须设置一个验证环节。我们的做法是将抽取结果特别是关系反向生成一段描述让LLM判断“这段描述是否严格源自原文”。例如如果抽取出(A, 导致, B)我们就问LLM“原文中是否明确说明了A会导致B”这能过滤掉大部分推理过度的情况。第三步图谱存储与查询将抽取后的结构化数据导入Neo4j。这里需要注意索引的建立。我们为所有实体的name属性和type属性创建了索引并对高频查询的关系类型也建立了索引显著提升了查询速度。第四步人工校准与迭代初始图谱构建完成后我们将其可视化并邀请技术专家进行“图漫步”检查核心区域如关键系统的配置链、服务依赖图的正确性和完整性。根据反馈我们调整了本体并补充了提示词示例形成了“构建-评估-修正”的闭环。图谱不是一次性的我们建立了每周定时更新的机制将新的文档变更增量更新到图谱中。3.3 智能体工作流的设计与LangGraph实践我们使用LangGraph将智能体的推理过程建模为一个有状态图。核心状态State包含用户问题、对话历史、已执行的步骤列表、中间结果、最终答案。工作流图的主要节点如下路由节点Router根据当前状态判断下一步行动。这是一个LLM调用节点让其决定是应该“规划任务”、“调用工具”还是“直接回答”。规划节点Planner对于复杂问题将问题分解为子任务序列。我们采用了“思维树”Tree of Thoughts的简化版让LLM生成多个可能的解决路径并快速评估其可行性。工具调用节点Tool Node这是执行单元。根据规划调用相应的工具。例如调用query_tech_graph工具其内部会构建一个Cypher查询如MATCH (c:Config {name:timeout})-[:belongs_to]-(s:Service {name:API-Gateway}) RETURN c.value, c.description然后执行并返回结果。反思节点Reflect在所有工具调用完成后或者当工具返回结果不确定时触发反思。LLM会评估当前收集到的信息是否足以回答问题或者是否存在矛盾。如果不足它会生成一个新的、更具体的问题重新进入规划或工具调用环节。# 一个简化的LangGraph状态定义示例 from typing import TypedDict, List, Annotated from langgraph.graph import StateGraph, END import operator class AgentState(TypedDict): question: str context: List[str] # 存放检索到的信息片段 plan: List[str] # 存放执行计划 observations: List[str] # 存放工具执行结果 answer: str # 定义工具函数 def retrieve_from_vector_db(state: AgentState): # 调用向量检索... return {context: [new_snippet]} def query_tech_graph(state: AgentState): # 构建Cypher查询调用Neo4j... return {observations: [graph_result]} # 构建图 workflow StateGraph(AgentState) workflow.add_node(retrieve, retrieve_from_vector_db) workflow.add_node(query_graph, query_tech_graph) # ... 添加其他节点和边条件边踩坑实录智能体容易陷入“循环思考”或“过度规划”。我们通过两个机制解决一是设置最大迭代次数如5轮二是在状态中维护一个“已尝试路径”的列表避免重复执行完全相同或无效的查询。4. 混合检索策略向量、图谱与关键词的融合单一的检索方式无法应对所有场景。我们的检索层设计为“混合检索网关”根据查询类型动态调配资源。1. 查询分类器首先用一个轻量级文本分类模型或few-shot的LLM对用户查询进行快速分类。我们定义了以下几类事实型“Kafka的默认端口是” - 优先使用向量检索快速、直接。诊断/推理型“为什么增加线程池大小后响应时间反而变长了” - 优先使用图谱查询探索配置、资源和性能指标的因果关系链。探索/方案型“如何设计一个高可用的微服务架构” - 启动智能体规划结合图谱查询架构组件关系和向量检索查找具体实践文档。简单关键词匹配型“SSL证书 过期” - 可并行使用BM25等稀疏检索作为向量检索的补充解决专业术语、缩写词匹配不准的问题。2. 多路召回与融合排序 对于需要混合检索的查询系统会并行发起多路召回路1密集检索查询向量化在Qdrant中进行近似最近邻搜索。路2图谱检索将查询中的实体链接到图谱节点然后进行一跳或多跳查询获取相关联的实体和文本描述。路3稀疏检索在Elasticsearch我们同时维护了一个文本索引中使用BM25进行全文检索。召回的结果文本片段会统一到一个列表中。然后我们使用一个交叉编码器Cross-Encoder重排序模型如bge-reranker对所有候选片段进行精细化的相关性打分。这个模型会同时看查询和每一个候选片段计算出的分数比单纯的向量余弦相似度更准确。最后取Top-N个片段作为生成答案的上下文。3. 反馈与优化我们记录了每次问答的查询类型、使用的检索方式、以及用户对答案的满意度反馈显式的点赞/点踩或隐式的后续追问行为。这些数据用于持续优化查询分类器和各检索通道的权重配比。5. 评估、监控与持续迭代5.1 如何评估新系统的效果告别了单纯看“召回率K”和“BLEU分数”的时代我们建立了一套更贴近用户体验的评估体系。答案准确性对于事实性问题组织专家进行人工评判。对于复杂问题采用“基于准则的评估”制定一系列准则如是否涵盖了所有关键方面推理逻辑是否清晰建议是否可行由LLM如GPT-4或专家根据准则打分。任务完成度对于过程性任务如“指导我完成配置”评估智能体规划的子步骤是否完整且正确最终是否引导用户达成了目标。效率提升统计平均问题解决时间从提问到获得满意答案与旧RAG系统以及直接搜索文档进行对比。可解释性评估系统提供的“思考过程”是否有助于用户理解答案的由来增加信任感。5.2 生产环境监控要点将这样一个复杂系统投入生产监控至关重要。我们重点关注以下指标智能体层面规划深度/工具调用次数监控每个会话的平均工具调用次数。异常增多可能意味着智能体陷入循环或规划低效。工具调用成功率特别是图谱查询和API调用的成功率。响应延迟分布拆解各环节耗时意图识别、规划、检索、生成定位瓶颈。检索层面各检索通道的召回占比观察向量、图谱、关键词检索的使用频率验证查询分类策略是否合理。重排序模型置信度监控重排序模型输出的分数分布及时发现模型漂移。知识层面知识库覆盖率定期抽样用户问题检查有多少问题因知识库缺失而无法回答。图谱健康度监控图谱中的孤立节点数、关系密度等反映知识抽取的质量。5.3 遇到的挑战与解决方案实录挑战一智能体的“幻觉”与可控性即便在工具增强下智能体在合成最终答案时仍可能产生幻觉。我们的解决方案是实施严格的“引用溯源”机制。要求智能体在答案中为每一个关键事实或建议注明来源例如来自哪份文档的哪个章节或图谱中的哪个关系。前端会将这些来源高亮显示用户可以点击查看原文。这既增加了可信度也便于我们事后审计和修正知识库。挑战二图谱构建与维护的成本信息抽取和人工校准确实耗时。我们通过以下方式降低成本优先构建核心领域并非所有文档都值得入图。我们优先处理了故障排查指南、系统架构说明、核心API文档等高价值、高关联性的文档。开发半自动化标注平台构建了一个内部平台将LLM的抽取结果以高亮形式展示在原文旁审核人员只需点击确认或修正大幅提升了校准效率。建立社区贡献机制鼓励工程师在解决实际问题后通过简单表单提交新的实体关系对经过审核后纳入图谱。挑战三系统延迟智能体的多步推理和工具调用必然增加延迟。优化措施包括缓存策略对常见的图谱查询路径结果进行缓存。对高频的、不变的事实性问题答案进行整体缓存。异步执行对于非强依赖的多个工具调用如同时查询向量库和图谱采用异步并行执行。规划剪枝为智能体的规划步骤设置超时和提前终止条件避免在无关路径上浪费资源。从传统RAG到Agentic Search Tech Graph的升级不是一个简单的技术叠加而是一次认知范式的转变。我们不再追求“更准的片段匹配”而是致力于构建一个能“理解问题、规划路径、综合利用结构化与非结构化知识、并给出可解释答案”的智能伙伴。这个过程中最深的体会是技术选型固然重要但比技术更重要的是对业务问题本质的洞察以及设计出与之匹配的、人机协同的解决流程。新架构带来了更高的复杂度和维护成本但在处理复杂技术问题时的表现让所有投入都变得值得。目前系统仍在快速迭代中下一步我们正在探索如何将实时日志流、监控指标也作为“工具”接入智能体让它真正成为一个7x24小时在线的“全能技术专家”。