项目背景与目标
公司制度、财务规则、产品资料和客服说明分散在多份 PDF 中,员工查询年假、报销流程、试用期、产品接口等内容时需要跨文档查找。普通 RAG 往往只做一次检索,容易出现答案缺少依据、坏文件导致整轮失败、资料不足仍然编造等问题。为此,我参与建设了“企业文档 Agent”,目标是让模型根据问题自主选择检索、读取原文、计算或时间工具,经过多轮“决策—执行—观察”后给出带来源页码的回答,并在证据或权限不足时明确拒答。
核心功能
系统支持单轮问答、多轮对话、流式输出和命令行交互,提供 10 个工具,包括知识库混合检索、文档列表、原文读取、文档预览、旧索引补充召回、关键词提取、索引重建、状态检查、数学计算和当前时间查询。知识检索采用 BM25、向量召回、RRF 排名融合和本地重排;工具调用具备参数校验、重复调用复用、单轮调用上限、结果截断和运行轨迹记录。此外,系统还提供 12 个黑盒验收场景,用于检查事实正确性、引用来源、缺失证据和机密文档权限。
业务流程
用户输入问题后,Agent 将问题写入会话上下文并交给模型。模型判断是否需要工具:需要检索时调用 search_knowledge_base,需要细节时调用 read_chunk,需要计算或时间时调用对应工具。执行结果以 tool 消息回填上下文,模型继续推理,直到给出最终回答或达到 6 步上限。系统在回答中要求使用 [n] 标注来源;没有相关资料时说明证据不足,遇到机密、薪酬或他人隐私时拒绝披露。评测模块则按“测试用例—启动候选程序—收集回答—校验引用与权限—输出报告”的路径独立运行。
整体架构与设计思路
项目分为运行层和评测层。运行层包含 CLI/对话入口、ChatAgent 主循环、上下文管理、ToolExecutor、TOOL_REGISTRY、混合检索、PDF 语料处理和配置模块;评测层独立读取知识索引,向候选 Agent 发送标准 JSON 请求并检查回答。这样拆分后,Agent 负责完成任务,评测器负责判断结果,避免把出题逻辑和运行逻辑耦合在一起。
技术栈方面,项目使用 Python 3.10,模型通过 OpenAI 兼容接口接入 DeepSeek;PDF 处理使用 pypdf,关键词检索使用 jieba 和 rank_bm25,向量索引使用 Chroma,融合采用 RRF,重排使用本地 CrossEncoder。工具参数由函数签名自动生成 JSON Schema。当前知识库包含 5 份可检索文档、56 个片段和 25 个唯一来源页面,工具总数为 10 个。
我负责的工作
我主要负责 Agent 主循环与工具执行链路:补充工具注册表和 schema 生成,实现工具结果回填、历史裁剪、最大步数收口、重复调用复用和结果截断;完善 PDF 逐文件容错、中文分词、BM25 与向量混合检索、RRF 融合和重排;同时搭建了 12 个黑盒验收场景和 8 项验收器自测。最终项目通过 24/24 项运行时测试,重排后 Hit@1 为 6/7、Hit@3 为 7/7、MRR 为 0.929。
难点与解决
一是加密、扫描和损坏 PDF 会中断整轮加载,我改为逐文件容错,并记录跳过原因;二是中文短查询容易被分词切碎,我加入汉字二元组和子串兜底;三是 BM25 与向量分数尺度不同,我使用只依赖排名的 RRF,再加入本地重排;四是工具结果会快速占满上下文,我加入调用上限、结果截断、去重和最近 8 条历史裁剪;五是模型可能答得流畅但缺少依据,我把引用页码、证据不足拒答和权限控制加入系统提示及独立评测,确保回答可以被核对。