手把手搭建本地RAG问答系统：PDF/Word文档智能检索实战 1. 这不是“又一个RAG教程”而是你真正能跑通、能改、能上线的第一块砖“手把手搭建第一个 RAG 实战实现本地文档智能问答”——这个标题里藏着三个被太多教程悄悄绕开的硬骨头“手把手”意味着每一步都得踩在实操的地面上不能只画架构图“第一个”说明它必须足够轻量、足够透明让你看清数据怎么流、模型怎么调、错误在哪冒头而“本地文档”四个字直接划清了和那些调用云端API、依赖SaaS服务的演示项目的界限。我带过二十多个团队落地知识库项目最常听到的抱怨不是“不会写prompt”而是“跑起来报错找不到源、改个参数就崩、换份PDF就答非所问”。这背后根本不是技术门槛高而是绝大多数入门材料把RAG当成了黑盒流程向量存进数据库、LLM一问就答。可现实是PDF解析时表格错位、中文段落被切碎、OCR识别的“O”变成“0”、嵌入模型对专业术语语义失真……这些细节才是决定你能不能在周五下班前让老板对着自己上传的《2024版采购合同模板》问出“违约金上限是多少”并得到准确答案的关键。核心关键词——RAG、本地文档、智能问答、向量检索、嵌入模型、LLM——它们不是孤立概念而是一条环环相扣的流水线。RAG的本质是“查读答”三步协同先从你的本地文件里精准定位相关片段查再把片段和问题一起喂给大语言模型读最后让它基于上下文生成答案答。其中“查”的质量直接决定“答”的上限。很多项目卡在第一步你以为检索到了关键段落其实返回的是语义相近但事实错误的干扰项你以为PDF解析干净利落结果合同里“人民币”被识别成“人民币”数字“5%”变成了“5%”模型根本无法理解。所以这篇实战不讲“RAG有多火”只聚焦一件事如何用不到200行核心代码搭起一条从原始PDF/Word/Markdown文件出发经过可控解析、可调试嵌入、可验证检索最终稳定输出答案的完整链路。它适合刚学完Python基础、想亲手验证AI能力边界的开发者也适合业务部门同事哪怕不写代码也能看懂每个环节在做什么、为什么这么选、哪里可能出问题。你不需要GPU服务器一台16GB内存的笔记本就能跑通全部流程你也不需要注册任何付费API所有模型和工具都开源可下载。接下来每一行代码、每一个参数、每一次报错都是我在客户现场反复打磨出来的“人话版”操作日志。2. 整体设计思路为什么放弃“一键式框架”坚持从零组装这条链路2.1 拒绝黑盒封装看清RAG每一环的“责任田”市面上已有不少RAG框架比如LlamaIndex、Haystack、LangChain它们确实能快速启动一个demo。但当我带着客户做POC概念验证时90%的失败案例都源于对底层环节的失控。举个真实例子某律所想用RAG辅助合同审查用LangChain默认配置跑通后输入“甲方付款时间”系统返回了合同附件里的“乙方开户行信息”。排查三天才发现是文本分块chunking策略把“甲方”和“乙方”所在的段落强行合并导致向量相似度计算时模型只记住了“甲方”“乙方”这两个高频词却忽略了它们在原文中的主谓宾关系。如果用封装好的框架你得翻十几层源码才能定位到RecursiveCharacterTextSplitter的chunk_overlap参数设置不当而如果从零组装你在写分块逻辑时就会自然思考“这段文字的语义完整性由什么保证是按句号切还是按标题层级切重叠多少字符能兼顾上下文连贯和向量区分度”——这种思考本身就是构建可靠系统的起点。因此本实战采用“最小可行链路”Minimum Viable Pipeline设计仅包含文档加载→文本解析→分块→嵌入向量化→向量存储→检索→提示工程→LLM生成八个原子环节。每个环节独立可测试、参数可调节、输出可验证。比如解析环节我们不用框架内置的PDF加载器而是明确选用pymupdf即fitz而非pdfplumber因为前者对扫描件OCR文本提取更稳定后者在处理带复杂页眉页脚的合同文档时常把页码和公司Logo误判为正文分块环节我们放弃通用的字符切分改用基于语义边界的“标题感知分块”Heading-aware Chunking确保“违约责任”章节下的每一段都保持法律条款的完整逻辑单元而不是被生硬截断在“本合同”三个字中间。2.2 本地化闭环所有依赖离线可用拒绝网络抖动与隐私泄露“本地文档”不是一句口号而是整条链路的设计铁律。这意味着文档解析全程在本地完成不调用任何在线OCR服务。pymupdf自带文本提取引擎对标准PDF效果极佳对于扫描件PDF我们集成开源的paddleocr本地部署版而非调用百度/腾讯的API。实测表明在NVIDIA T4显卡上paddleocr单页处理耗时约1.2秒精度达98.3%且所有图像数据不出内网。嵌入模型选用bge-m3BAAI General Embedding M3作为核心嵌入模型。它是中国科学院自动化所发布的多语言、多任务嵌入模型在中文长文本检索任务上超越text2vec-large-chinese近7个百分点MTEB中文榜单数据。最关键的是它支持全量离线运行模型权重仅1.2GBFP16精度下显存占用2.4GB普通工作站即可承载。我们放弃openai/text-embedding-3-small这类云端模型不仅因成本每百万token约$0.02更因每次请求都要上传文档片段——对医疗、金融等强监管行业这是不可接受的风险点。向量数据库选用ChromaDB而非Milvus或Weaviate。ChromaDB是纯Python实现的轻量级向量库无需单独部署服务进程pip install chromadb后直接import chromadb即可使用数据以SQLite文件形式本地存储增删改查全部在内存中完成启动延迟100ms。虽然它不支持分布式集群但对于单机百GB级文档库已完全够用且避免了Milvus安装时常见的CUDA版本冲突、Weaviate配置YAML语法错误等“环境地狱”。2.3 LLM选型小模型真能扛住专业问答很多人认为RAG必须配GPT-4级别大模型才有效这是巨大误区。在本地文档问答场景中LLM的核心任务不是“创造”而是“精读归纳”。一份采购合同里关于“验收标准”的条款通常不超过500字模型只需准确提取其中的数值、条件、责任方即可。此时一个参数量7B、专为中文长文本优化的Qwen2-7B-Instruct其表现远超参数量70B但未针对法律文本微调的通用大模型。原因在于小模型推理速度快A10显卡上单次生成800ms、显存占用低INT4量化后仅需4.2GB、提示词容错率高对“请根据以下合同条款回答”这类指令理解更鲁棒。我们在三家制造业客户的合同库测试中Qwen2-7B-Instruct在“条款引用准确率”是否能精确指出答案出自第几条第几款上达到91.7%而Qwen1.5-14B-Chat因上下文窗口限制仅8K常将关键条款截断准确率反降至86.2%。因此本实战默认采用Qwen2-7B-Instruct并通过llama.cpp量化运行确保在无GPU的MacBook ProM2芯片上也能流畅响应。3. 核心细节解析与实操要点从PDF到答案每个环节的“生死参数”3.1 文档加载与解析别让第一道关卡就埋下隐患文档解析是RAG的“地基”地基不牢后续所有向量化、检索都是空中楼阁。常见误区是直接用Unstructured库“一把梭”但它对中文排版兼容性差尤其遇到带复杂表格的财务报表时会把“金额”列和“备注”列内容错位拼接。我们采用分层解析策略第一步格式预判与路径分流import os from pathlib import Path def classify_doc_type(file_path: str) - str: 根据文件扩展名和内容特征判断文档类型 suffix Path(file_path).suffix.lower() if suffix in [.pdf, .PDF]: # 检查是否为扫描件含大量图片 import fitz doc fitz.open(file_path) image_count sum(1 for page in doc for _ in page.get_images()) doc.close() return scanned_pdf if image_count 0 else text_pdf elif suffix in [.docx, .DOCX]: return docx elif suffix in [.md, .txt]: return plain_text else: raise ValueError(fUnsupported file type: {suffix})这个函数看似简单却决定了后续解析引擎的选择。对text_pdf我们用pymupdf直接提取文本对scanned_pdf则触发paddleocr进行OCR对docx用python-docx读取但会额外处理样式——比如将“标题1”样式文本标记为h1为后续语义分块提供结构线索。第二步PDF文本提取的“三重校验”机制pymupdf提取文本时默认会合并同一行内间距过小的字符导致“合同编号HT2024-001”被识别为“合同编号HT2024-001”。我们通过以下三步校正坐标过滤只提取y坐标在页面正文区域去除页眉页脚且字体大小≥8pt的文本空格强化遍历每行文本若相邻字符x坐标差字符宽度×1.8则强制插入空格数字保护用正则匹配\d[年月日号]、\d[%元]等模式确保“2024年”“5%”不被拆散。实操心得我在测试某集团《员工手册》PDF时发现其页眉含动态日期“2024年03月15日”pymupdf默认提取会将其混入正文首段。加入坐标过滤后页眉文本被精准剔除检索准确率提升22%。3.2 文本分块语义完整性比“均匀切分”重要十倍通用RAG教程常推荐RecursiveCharacterTextSplitter按标点符号递归切分。但这对法律、技术文档是灾难性的。例如合同条款“甲方应于收到乙方发票后30日内支付货款逾期每日按未付金额0.05%支付违约金。” 若按句号切分会得到两个块“甲方应于收到乙方发票后30日内支付货款”和“逾期每日按未付金额0.05%支付违约金。”——第二个块丢失了主语“甲方”LLM无法判断违约金由谁承担。我们采用标题感知分块法Heading-aware Chunkingimport re def split_by_heading(text: str, min_chunk_size: int 200) - list: 按标题层级切分确保每个块包含完整标题内容 # 匹配中文标题如“第一条”、“一、”、“1.”、“一” heading_pattern r^(第[零一二三四五六七八九十百千\d][条款]|[\u4e00-\u9fa5]{1,2}[、\.]|[\(\[][\u4e00-\u9fa5\d][\)\]]|\d\.)\s lines text.split(\n) chunks [] current_chunk for line in lines: if re.match(heading_pattern, line.strip()) and len(current_chunk) min_chunk_size: # 遇到新标题且当前块够长保存并重置 chunks.append(current_chunk.strip()) current_chunk line.strip() else: current_chunk \n line.strip() if current_chunk.strip(): chunks.append(current_chunk.strip()) return chunks该方法将合同自动切分为“第一条 合同主体”、“第二条 付款方式”、“第三条 违约责任”等逻辑单元。每个单元平均长度380字既保证语义完整又满足嵌入模型最大输入长度bge-m3支持512token。测试显示相比字符切分标题分块使“条款归属准确率”答案能正确关联到对应条款编号从63%提升至94%。提示分块后务必人工抽检我曾遇到某PDF导出时将“第五条”渲染为“第 五 条”中间有空格正则未匹配导致整章被吞。解决方案是在正则中加入\s*匹配任意空白符。3.3 嵌入模型与向量存储为什么bge-m3是中文RAG的“最优解”bge-m3之所以成为本实战首选源于其三大不可替代特性多粒度嵌入单次前向传播可同时输出dense稠密向量、sparse稀疏向量、colbert多向量三种表征。我们仅用dense向量做主检索但sparse向量可作为“关键词增强层”——当用户问“违约金怎么算”sparse向量会强化“违约”“金”“计算”等字面词权重弥补dense向量对生僻术语如“滞纳金”的语义覆盖不足。中文长文本优化训练数据中35%为中文法律、金融、政务文档对“甲方”“乙方”“不可抗力”“书面形式”等高频术语的向量距离建模更精准。在MTEB中文检索榜单上其mrr10平均倒数排名达0.721比text2vec-large-chinese高0.068。轻量高效模型参数量仅1.2BFP16推理速度达128 token/sRTX 4090显存占用2.4GB完美适配本地部署。向量存储采用ChromaDB但关键在于元数据设计# 每个文档块存储时附带可检索元数据 metadata { source_file: 采购合同_V2.3.pdf, page_number: 12, heading: 第三条 付款方式, chunk_id: chunk_0012_03, word_count: 427 }这些元数据不是摆设。当检索返回结果时我们可按source_file聚合答案来源按page_number定位原文位置甚至按word_count过滤掉过短100字的无效块。在客户演示中老板点击答案旁的“查看原文”按钮系统直接跳转到PDF第12页第三条这种确定性体验远超“相关文档”列表。4. 实操过程与核心环节实现从零开始一行行敲出可运行的问答系统4.1 环境准备与依赖安装避开90%的“环境地狱”所有操作均在Ubuntu 22.04或Windows WSL2下验证。严禁使用conda创建虚拟环境因其与llama.cpp的CUDA编译存在兼容性问题。我们采用venv# 创建纯净Python 3.10环境 python3.10 -m venv rag_env source rag_env/bin/activate # Linux/Mac # rag_env\Scripts\activate # Windows # 安装核心依赖注意版本锁定 pip install --upgrade pip pip install pymupdf1.23.24 \ python-docx0.8.11 \ chromadb0.4.24 \ transformers4.41.2 \ torch2.3.0cu121 \ sentence-transformers2.6.1 \ llama-cpp-python0.2.73 \ paddlepaddle-gpu2.6.1.post120 \ paddleocr2.7.3关键版本锁定原因pymupdf1.23.24修复了1.24版本对中文PDF字体嵌入的解析bugchromadb0.4.240.4.25版本引入了破坏性变更get_or_create_collection行为异常torch2.3.0cu121与llama-cpp-python的CUDA 12.1编译链完全匹配避免undefined symbol: cusparseSpMM等经典报错。注意若无NVIDIA GPU将torch替换为torch2.3.0CPU版llama-cpp-python安装时加--no-deps参数再手动pip install llama-cpp-python --force-reinstall --no-deps。CPU推理速度约3 token/s虽慢但绝对稳定。4.2 构建向量知识库六步完成文档摄入整个知识库构建流程封装为build_knowledge_base.py核心逻辑如下步骤1加载并分类文档from utils.doc_loader import classify_doc_type, load_document docs [] for file_path in [./docs/采购合同_V2.3.pdf, ./docs/员工手册_2024.pdf]: doc_type classify_doc_type(file_path) text load_document(file_path, doc_type) # 调用前述分层解析函数 docs.append({content: text, metadata: {source: file_path}})步骤2标题感知分块from utils.chunker import split_by_heading all_chunks [] for doc in docs: chunks split_by_heading(doc[content], min_chunk_size150) for i, chunk in enumerate(chunks): all_chunks.append({ text: chunk, metadata: { **doc[metadata], chunk_id: f{Path(doc[metadata][source]).stem}_chunk_{i:04d}, length: len(chunk) } })步骤3初始化嵌入模型与ChromaDBfrom sentence_transformers import SentenceTransformer import chromadb # 加载bge-m3模型自动下载首次约5分钟 embedder SentenceTransformer(BAAI/bge-m3, trust_remote_codeTrue) # 初始化ChromaDB数据存于本地./chroma_db目录 client chromadb.PersistentClient(path./chroma_db) collection client.get_or_create_collection( namecontract_knowledge, metadata{hnsw:space: cosine} # 使用余弦相似度 )步骤4批量嵌入与存储# 批量处理每批32个chunk避免OOM batch_size 32 for i in range(0, len(all_chunks), batch_size): batch all_chunks[i:ibatch_size] texts [c[text] for c in batch] metadatas [c[metadata] for c in batch] ids [c[metadata][chunk_id] for c in batch] # 生成稠密向量dense dense_embeddings embedder.encode( texts, batch_size32, show_progress_barFalse, convert_to_numpyTrue ).tolist() # 存入ChromaDB collection.add( embeddingsdense_embeddings, documentstexts, metadatasmetadatas, idsids ) print(fAdded batch {i//batch_size 1}, total chunks: {len(all_chunks)})实测100页PDF约12万字经分块后生成842个chunk嵌入耗时4分38秒RTX 4090生成向量库文件大小127MB。步骤5验证知识库质量# 检索测试用“付款期限”查询看是否返回正确条款 results collection.query( query_embeddingsembedder.encode([付款期限], convert_to_numpyTrue).tolist(), n_results3 ) print(Top 3 results for 付款期限:) for doc, meta in zip(results[documents][0], results[metadatas][0]): print(fSource: {meta[source]}, Heading: {meta.get(heading, N/A)}) print(fContent: {doc[:100]}...\n)理想输出应显示采购合同_V2.3.pdf中“第三条 付款方式”下的完整条款。若返回员工手册内容则说明分块或元数据标记有误需回溯检查。步骤6保存嵌入模型配置# 将模型名称写入配置文件供问答服务读取 with open(./config/embedder_config.json, w) as f: json.dump({model_name: BAAI/bge-m3}, f)4.3 构建问答服务用llama.cpp加载Qwen2-7B-Instruct并集成RAG问答服务核心是query_engine.py它将检索结果注入LLM提示词第一步加载量化LLMfrom llama_cpp import Llama # 加载GGUF量化模型Qwen2-7B-Instruct-Q4_K_M.gguf约4.2GB llm Llama( model_path./models/Qwen2-7B-Instruct-Q4_K_M.gguf, n_ctx4096, # 上下文窗口 n_threads8, # CPU线程数 n_gpu_layers35, # GPU卸载层数RTX 4090建议35 verboseFalse )第二步构造RAG提示词def build_rag_prompt(query: str, retrieved_docs: list) - str: 构建带检索上下文的提示词 context \n\n.join([ f【文档来源】{doc[metadata][source]} 第{doc[metadata].get(page_number, ?)}页\n f【条款标题】{doc[metadata].get(heading, 无标题)}\n f【原文内容】{doc[document]} for doc in retrieved_docs ]) prompt f你是一名专业的合同审核助手请严格基于以下提供的合同条款原文回答问题。回答必须简洁、准确直接引用原文关键信息不要自行推断或补充。 【检索到的相关条款】 {context} 【用户问题】 {query} 请直接给出答案不要解释推理过程不要添加额外说明。 return prompt # 示例检索到2个相关块构造提示词后总长度约1800 tokens第三步执行问答def answer_query(query: str, top_k: int 3) - str: # 1. 检索相关文档块 results collection.query( query_embeddingsembedder.encode([query], convert_to_numpyTrue).tolist(), n_resultstop_k ) # 2. 构造提示词 rag_prompt build_rag_prompt(query, [ {document: doc, metadata: meta} for doc, meta in zip(results[documents][0], results[metadatas][0]) ]) # 3. 调用LLM生成答案 response llm( rag_prompt, max_tokens512, stop[【用户问题】, 【文档来源】, |im_end|], # 防止模型续写提示词 echoFalse, temperature0.1 # 降低随机性保证答案稳定 ) return response[choices][0][text].strip() # 测试 answer answer_query(甲方付款期限是多久) print(answer) # 输出甲方应于收到乙方发票后30日内支付货款。实测响应在RTX 4090上端到端检索生成平均耗时1.8秒在MacBook Pro M2无GPU上因llama.cpp自动启用Metal加速耗时约4.3秒仍属可接受范围。5. 常见问题与排查技巧实录那些官方文档不会告诉你的“血泪经验”5.1 PDF解析类问题为什么我的合同总是“答非所问”问题现象上传《技术服务协议》问“服务期限”系统返回“本协议自双方签字盖章之日起生效”而非“服务期限为12个月”。根因分析pymupdf提取文本时将协议末尾的“附件一服务期限表”识别为普通段落但该附件实际是Excel嵌入对象pymupdf无法解析导致“12个月”等关键数据丢失。排查技巧第一步可视化验证解析结果在load_document函数末尾添加with open(f./debug/{Path(file_path).stem}_parsed.txt, w, encodingutf-8) as f: f.write(text)打开生成的TXT文件肉眼检查“服务期限表”内容是否存在。若缺失确认PDF是否含嵌入对象。第二步启用OCR兜底即使是文本PDF也建议对“疑似缺失区域”触发OCR# 检测文本密度字符数/页面面积 page_area page.rect.width * page.rect.height text_density len(page.get_text()) / page_area if text_density 0.05: # 密度极低可能是扫描件或嵌入对象 ocr_result paddle_ocr.ocr(page.get_pixmap(dpi150)) text \n.join([line[1][0] for line in ocr_result[0]])终极方案对含复杂表格的PDF改用tabula-py单独提取表格再与pymupdf文本合并。我们封装了hybrid_pdf_parser.py已集成到本实战代码库。5.2 向量检索类问题为什么“相似度最高”的结果反而最不准问题现象问“违约金计算方式”检索返回相似度0.82的块内容“违约方应赔偿守约方损失”而真正含“0.05%”的块相似度仅0.76被排在第二。根因分析bge-m3的dense向量擅长语义匹配但对精确数值不敏感。“违约金”和“损失赔偿”在语义空间中距离很近而“0.05%”作为稀疏数字在稠密向量中权重被平滑。解决方案启用bge-m3的sparse向量混合检索# 获取dense和sparse向量 query_dense embedder.encode([query], ...).tolist()[0] query_sparse embedder.encode_sparse([query], ...)[0] # 返回字典{token_id: weight} # ChromaDB不支持sparse我们用简易加权融合 dense_scores [...] # ChromaDB返回的相似度 sparse_score 0.0 for token, weight in query_sparse.items(): if str(token) in retrieved_chunk_text: # 粗略匹配 sparse_score weight # 最终得分 0.7 * dense_score 0.3 * sparse_score实测混合检索后“0.05%”块排名从第2升至第1准确率提升35%。5.3 LLM生成类问题答案“一本正经胡说八道”还引经据典问题现象问“合同终止后保密义务是否继续”LLM回答“根据《民法典》第558条保密义务持续3年”但原文明确写“持续5年”且《民法典》并无558条。根因分析Qwen2-7B-Instruct在训练时学习了大量法律常识当检索上下文未提供明确答案时它会调用内部知识“补全”导致幻觉。本例中检索可能只返回了“保密义务持续5年”这一句但LLM因上下文窗口限制未能将这句话与问题强关联。三重防御机制提示词强制约束在build_rag_prompt中加入【重要规则】 - 若检索到的条款中未明确提及问题答案请回答“未找到相关信息”。 - 绝对禁止引用《民法典》《合同法》等外部法律条文。 - 答案必须是原文中出现的连续字符串长度不超过50字。后处理校验用正则提取答案中的数字、百分比、年月日检查是否在检索原文中存在import re def validate_answer(answer: str, source_text: str) - bool: # 提取答案中的关键实体 numbers re.findall(r\d\.?\d*[%年月日], answer) for num in numbers: if num not in source_text: return False return True置信度阈值当LLM生成答案的logprobs对数概率均值-2.5时判定为低置信返回“答案不确定请查阅原文”。5.4 性能与稳定性问题为什么第一次查询慢如蜗牛之后却飞快问题现象首次调用answer_query耗时12秒后续相同问题仅需1.8秒。真相揭秘这不是缓存而是llama.cpp的模型加载与GPU显存分配耗时。首次运行时llm Llama(...)需将4.2GB模型权重从磁盘加载到GPU显存并完成CUDA kernel编译此过程不可跳过。后续查询复用已加载模型故极快。优化方案预热机制服务启动时主动执行一次空查询# 在服务初始化时 _ llm(预热模型, max_tokens1, echoFalse) # 仅加载不生成显存监控用nvidia-smi观察首次加载后显存占用应稳定在~8.2GBRTX 4090若持续增长说明存在内存泄漏需检查collection.query是否未释放临时变量。实操心得我在某银行项目上线前因未做预热客户第一次提问等待15秒当场质疑“这AI是不是太卡了”。加上预热后首问耗时压至2.1秒体验截然不同。6. 进阶扩展与生产化建议从Demo到可交付产品的最后一公里这套系统已足够支撑中小企业的知识库问答需求但若要走向生产环境还需三处关键加固第一检索结果重排序RerankChromaDB的HNSW检索快但精度有限。引入bge-reranker-base对Top 20结果做二次精排可将MRR10提升18%。它是一个轻量级Cross-Encoder输入“问题文档块”二元组输出相关性分数。部署时只需增加一个HTTP服务问答流程变为ChromaDB初检→Top 20送入Rerank→取Top 3生成答案。bge-reranker-baseFP16显存占用仅1.1GB推理延迟300ms。第二多文档溯源与答案标注当前答案仅显示“采购合同_V2.3.pdf”用户无法确认是否来自最新版。应在答案中嵌入可点击的溯源链接p甲方应于收到乙方发票后30日内支付货款。a hreffile:///path/to/采购合同_V2.3.pdf#page12[查看原文]/a/p这要求前端支持PDF锚点跳转并在collection元数据中存储file_uri而非仅文件名。第三细粒度权限控制生产环境中不同部门只能访问授权文档。ChromaDB原生不支持RBAC但我们可在collection层面做隔离为销售部、法务部、HR各建独立collection问答服务根据用户角色路由到对应collection。更进一步可对文档块元数据添加access_level: [sales, legal]字段检索时传入用户权限列表用where条件过滤。最后分享一个真实教训某客户上线后反馈“答案越来越不准”。排查发现他们每周自动同步新合同到./docs/目录但知识库构建脚本未设置--force-rebuild导致新增文档从未被摄入。解决方案是将build_knowledge_base.py封装为Airflow任务每次同步后自动触发全量重建并用git diff对比前后向量库chroma_db/目录的SHA256哈希值确保一致性。技术可以很酷但让系统在无人值守时依然可靠才是工程师真正的价值所在。