1. 从一堆散落的 PDF 和 Markdown 说起我为什么要自己搭知识工作台手里攒了几百个 PDF、上千个 Markdown 笔记还有各种项目文档、会议纪要、技术方案这大概是很多技术从业者的常态。问题不在于存而在于找和用。我试过用文件夹分类、用标签管理、用全文搜索工具但每次想查一个具体问题的答案还是要打开好几个文件来回翻效率极低。更别说那些扫描版 PDF 里的图表和公式传统搜索根本无能为力。真正让我下决心动手的是一次项目复盘。我需要从过去半年的技术方案、踩坑记录和第三方文档里快速整理出一份某类问题的最佳实践。结果花了整整一个下午翻了二十多个文件最后整理出来的东西还不完整。那一刻我意识到文件管理不等于知识管理存储不等于可检索可检索不等于可追问。我需要的是一个能理解内容、能持续追问、能把碎片信息串联起来的系统。这就是我搭建这套可持续追问的知识工作台的起点。它的核心目标很明确把 PDF、Markdown 和项目资料统一沉淀到一个可检索、可追问、可扩展的知识库里用 RAG检索增强生成技术让 AI 基于我的私有资料回答问题而不是泛泛而谈。适合谁参考任何有大量文档需要管理、希望用 AI 提升信息利用效率的人——不管你是开发者、产品经理、研究人员还是运维工程师只要你有资料很多但用不起来的困扰这套思路都能直接借鉴。关键词里提到的 PDF、Markdown、AI、知识库、RAG正好对应了这套系统的五个核心环节文档解析、格式统一、智能问答、知识沉淀和检索增强。接下来我会把这套系统从选型到落地、从踩坑到优化的完整过程拆开讲包括我实际用到的工具、配置参数、代码片段和那些文档里不会写的经验教训。2. 拆解需求知识工作台到底要解决哪几个真问题2.1 不是存进去就完了检索质量才是命门很多人搭知识库的第一步是找个工具把文件传上去然后发现搜出来的东西驴唇不对马嘴。问题出在检索环节。传统关键词搜索依赖字面匹配你搜接口超时怎么排查它只能找到包含这几个字的文档但真正有用的可能是某篇写着服务响应延迟根因分析的笔记。RAG 的核心价值就在于用语义检索替代字面匹配把意思相近的内容也捞出来。但语义检索不是万能的。我实测下来检索质量取决于三个因素文档切分粒度、嵌入模型选择和检索策略。切分太粗一个 chunk 里混了好几个主题检索时噪声大切分太细上下文丢失AI 回答时缺乏依据。嵌入模型的选择直接决定语义理解的准确度不同模型对中文技术文档的表现差异明显。检索策略则决定了是只做向量检索还是结合关键词检索做混合召回。2.2 PDF 解析是最大的坑没有之一Markdown 文件天然结构化解析起来相对简单。PDF 才是真正的噩梦。我统计过自己手头的 PDF大致分三类原生电子版文字可选中、扫描版纯图片、混合版部分文字部分图片。原生电子版用常规解析库就能提取文字但表格、公式、代码块经常乱掉扫描版必须走 OCR识别准确率受字体、清晰度、排版影响很大混合版最麻烦需要判断哪些页面走文字提取、哪些走 OCR。更隐蔽的问题是阅读顺序。很多 PDF 是双栏排版解析库如果按坐标顺序提取会把左右栏的文字交错在一起读起来完全不通。我踩过这个坑一篇技术论文解析出来前言不搭后语后来才发现是分栏问题。解决办法是启用版面分析功能先识别区块再按逻辑顺序提取。2.3 可持续追问意味着什么普通问答是一问一答问完就结束了。可持续追问要求系统能记住上下文、能基于之前的回答继续深入、能在多轮对话中保持一致性。这对知识库提出了更高要求不仅要有好的检索还要有对话历史管理、上下文窗口控制和追问引导机制。我设计时的思路是每次追问都重新检索但把历史对话作为上下文一起送给模型。这样既能利用新检索到的内容又能保持对话连贯性。代价是 token 消耗增加需要控制历史对话的长度只保留最近几轮或做摘要压缩。2.4 需求优先级排序需求优先级原因PDF 高质量解析高解析质量差后面全白搭语义检索准确高检索不准AI 回答就是胡编多轮追问支持中高单轮问答价值有限追问才能深挖多格式统一中Markdown 和 PDF 是主力其他格式可后续扩展增量更新中新资料能方便加入不用全量重建权限管理低个人使用场景暂时不需要这个优先级排序很关键。我见过不少人一上来就追求支持所有格式界面要好看结果核心的解析和检索没做好系统根本用不起来。先把 PDF 解析和语义检索这两个核心环节做扎实其他都是锦上添花。3. 技术选型为什么我最终选了这套组合3.1 文档解析层PyMuPDF PaddleOCR UnstructuredPDF 解析我试过至少五种方案最后定下来的是组合拳。PyMuPDF也叫 fitz负责原生电子版 PDF 的文字和版面提取速度快、对表格和坐标支持好。扫描版走 PaddleOCR中文识别准确率在我实测的几款开源 OCR 里是最稳的而且对表格结构有一定还原能力。Unstructured 作为补充处理那些格式特别复杂的文档它的分区识别能力比较强。为什么不用商业 API一是成本我手头文档量大按页计费不划算二是隐私很多项目资料不适合上传到第三方三是可控性本地部署可以针对自己的文档类型调优。PaddleOCR 的安装稍微麻烦点需要配好 Python 环境和依赖但跑通之后很稳定。Markdown 解析就简单多了直接用 Python 的 markdown 库或者自己写正则提取标题、段落、代码块。关键是要保留结构信息比如标题层级、代码块语言标记这些对后续检索很有帮助。3.2 向量化与存储BGE-M3 ChromaDB嵌入模型我选的是 BGE-M3。理由有三第一它对中文支持好在中文技术文档上的语义相似度表现明显优于一些通用模型第二它支持多语言我有些英文资料也能一起处理第三它输出的向量维度适中1024 维存储和检索效率平衡得不错。向量数据库用的 ChromaDB。轻量、易部署、Python 原生支持适合个人和小团队场景。它支持持久化存储重启不丢数据也支持元数据过滤可以按文档类型、时间等条件筛选。如果数据量特别大百万级以上可能需要考虑 Milvus 或 Qdrant但个人知识库通常到不了这个量级。3.3 检索策略混合检索 重排序单纯向量检索有个问题对专有名词、代码标识符、版本号这类精确匹配需求表现不好。比如你搜v2.3.1 的配置项向量检索可能返回一堆语义相近但版本不对的内容。所以我加了 BM25 关键词检索做混合召回两路结果合并后再用重排序模型精排。重排序模型用的是 BGE-Reranker它会对召回的候选文档重新打分把最相关的排到前面。实测下来加了重排序之后Top-3 的命中率提升很明显。代价是增加了一次模型推理延迟会高一些但个人使用场景完全能接受。3.4 生成层本地模型 vs 云端 API生成层我做了双轨设计敏感资料走本地模型普通资料走云端 API。本地模型用的是 Qwen2.5-7B 的量化版本跑在一张消费级显卡上速度够用质量对技术问答来说也还行。云端 API 则用于那些不敏感但需要更强推理能力的场景。为什么不全用云端因为有些项目文档涉及内部方案不适合外传。为什么不全用本地因为本地小模型在复杂推理和多轮对话上确实不如大模型。双轨设计是在隐私、成本和质量之间找平衡你可以根据自己的资料敏感度调整比例。3.5 编排框架为什么没用 LangChainLangChain 功能很全但对我来说太重了。它的抽象层多调试起来不直观而且版本迭代快经常出现 breaking change。我最后选择自己写编排逻辑核心流程就几百行代码清晰可控。用到的库也很基础sentence-transformers 做嵌入chromadb 做存储rank_bm25 做关键词检索transformers 做重排序和生成。这不是说 LangChain 不好而是个人项目优先考虑可维护性和可调试性。如果你要快速搭原型LangChain 能省不少事但如果想长期维护、深度定制自己写核心逻辑反而更省心。4. 从零搭建完整流程与关键配置4.1 环境准备与依赖安装先说我用的环境Python 3.10Ubuntu 22.04一张 12GB 显存的显卡。Python 版本建议 3.9 到 3.11太新或太旧都可能遇到依赖兼容问题。核心依赖清单pip install pymupdf paddlepaddle paddleocr pip install unstructured markdown pip install sentence-transformers chromadb rank_bm25 pip install transformers torch acceleratePaddleOCR 的安装要注意它依赖 paddlepaddle需要根据你的 CUDA 版本选择对应的安装包。如果只用 CPU 推理装 CPU 版就行速度慢一些但能用。我一开始装了 GPU 版但 CUDA 版本不匹配折腾了半天才搞定建议先确认显卡驱动和 CUDA 版本再装。ChromaDB 默认是内存模式要持久化需要指定 persist_directory。这个目录会存向量和元数据建议放在 SSD 上检索速度会快很多。4.2 PDF 解析的完整处理链路我的 PDF 处理流程分四步类型判断、文字提取、OCR 补充、结构重建。类型判断很简单用 PyMuPDF 打开后检查每页的文字块数量。如果某页文字块极少但图片很多基本可以判定是扫描页走 OCR 流程。import fitz def classify_page(page): text page.get_text() images page.get_images() if len(text.strip()) 50 and len(images) 0: return scanned return native文字提取用page.get_text(dict)能拿到带坐标的文本块方便后续做版面分析。对于双栏文档我按 x 坐标把文本块分成左右两组分别按 y 坐标排序再合并这样能还原正确的阅读顺序。OCR 部分用 PaddleOCR关键参数是use_angle_clsTrue自动纠正文字方向和langch中文识别。识别结果按坐标排序后拼接尽量还原原始阅读顺序。表格识别用 PaddleOCR 的表格结构识别功能能输出 HTML 格式的表格比纯文本好很多。结构重建是把提取的文字按标题、段落、列表、代码块分类。PDF 里没有显式的结构标记只能靠字体大小、加粗、缩进等特征推断。我的做法是字体明显大于正文的判为标题等宽字体的判为代码带项目符号的判为列表。这个规则不完美但覆盖了大部分技术文档。4.3 文档切分粒度、重叠与元数据切分是 RAG 里最容易被忽视但影响最大的环节。我的经验是技术文档按语义切分不要按固定字数切。具体做法是先用标题做一级切分把文档分成若干章节。如果某章节太长超过 1000 字再按段落切分。每个 chunk 控制在 300 到 800 字之间太短上下文不足太长检索噪声大。chunk 之间保留 50 到 100 字的重叠避免边界处的信息丢失。元数据要保留来源文件名、章节标题、页码、文档类型、创建时间。这些在检索时可以用来过滤也能在回答时标注出处方便追溯。def split_document(text, metadata, max_len800, overlap100): chunks [] paragraphs text.split(\n\n) current for para in paragraphs: if len(current) len(para) max_len: chunks.append({text: current, meta: metadata}) current current[-overlap:] para else: current \n\n para if current: chunks.append({text: current, meta: metadata}) return chunks这个切分逻辑简单但实用。实际用的时候可以根据文档类型调整 max_len代码多的文档可以短一些叙述性文档可以长一些。4.4 向量化与入库的实操细节嵌入模型加载用 sentence-transformersBGE-M3 的模型名是BAAI/bge-m3。第一次加载会下载模型大概 2GB 左右建议提前下好放到本地。from sentence_transformers import SentenceTransformer import chromadb model SentenceTransformer(BAAI/bge-m3) client chromadb.PersistentClient(path./kb_data) collection client.get_or_create_collection(knowledge_base) def add_chunks(chunks): texts [c[text] for c in chunks] embeddings model.encode(texts, normalize_embeddingsTrue) collection.add( embeddingsembeddings.tolist(), documentstexts, metadatas[c[meta] for c in chunks], ids[fdoc_{i} for i in range(len(texts))] )注意normalize_embeddingsTrueBGE 系列模型建议归一化后再算相似度效果更稳定。批量 encode 的时候控制 batch_size太大容易爆显存我一般设 32。入库时 ids 要唯一我用的是文档哈希加序号避免重复导入时冲突。如果同一文档更新了先按来源文件名删除旧记录再插入新的。4.5 检索与重排序的代码实现检索分两路向量检索和关键词检索。向量检索用 ChromaDB 的 query 接口关键词检索用 rank_bm25。from rank_bm25 import BM25Okapi def hybrid_search(query, top_k10): # 向量检索 q_emb model.encode([query], normalize_embeddingsTrue) vec_results collection.query(query_embeddingsq_emb.tolist(), n_resultstop_k) # 关键词检索 tokenized [doc.split() for doc in all_docs] bm25 BM25Okapi(tokenized) bm25_scores bm25.get_scores(query.split()) bm25_top sorted(range(len(bm25_scores)), keylambda i: -bm25_scores[i])[:top_k] # 合并去重 candidates set(vec_results[ids][0]) for i in bm25_top: candidates.add(all_ids[i]) return list(candidates)合并后的候选再用 BGE-Reranker 精排from transformers import AutoModelForSequenceClassification, AutoTokenizer reranker AutoModelForSequenceClassification.from_pretrained(BAAI/bge-reranker-base) rerank_tokenizer AutoTokenizer.from_pretrained(BAAI/bge-reranker-base) def rerank(query, candidates, top_n5): pairs [(query, doc) for doc in candidates] inputs rerank_tokenizer(pairs, paddingTrue, truncationTrue, return_tensorspt) scores reranker(**inputs).logits.squeeze(-1) ranked sorted(zip(candidates, scores.tolist()), keylambda x: -x[1]) return [doc for doc, _ in ranked[:top_n]]重排序的 batch 也要控制我一般设 16。如果候选多可以分批处理。4.6 生成与追问的编排逻辑生成部分把检索到的 Top-N 文档拼成上下文加上系统提示词和用户问题送给模型。系统提示词要明确要求基于提供的资料回答资料中没有的信息不要编造。def generate_answer(query, context_docs, history): context \n\n.join(context_docs) prompt f基于以下资料回答问题。如果资料中没有相关信息请明确说明。 资料 {context} 对话历史 {history} 问题{query} # 调用模型生成 return model.generate(prompt)追问的处理是每次追问都重新检索但把历史对话拼进 prompt。历史对话只保留最近 3 轮更早的做摘要压缩避免 token 超限。5. 实测中的意外与踩坑记录5.1 扫描版 PDF 的 OCR 准确率问题我手头有一批老技术手册扫描质量参差不齐。PaddleOCR 在清晰文档上准确率能到 95% 以上但遇到模糊、倾斜、有印章的页面错误率明显上升。最典型的问题是数字和字母混淆比如 0 和 O、1 和 l在代码和版本号里特别致命。我的应对策略是对 OCR 结果做后处理用正则修正常见的混淆模式。比如版本号格式v\d\.\d\.\d如果识别出vO.1.l就自动纠正。另外对关键文档我会人工校对一遍虽然费时间但比让错误信息污染知识库强。还有个坑是多栏扫描件。OCR 默认按行识别双栏文档会把左右栏的文字混在一起。解决办法是先用版面分析把页面分成左右两个区域分别 OCR 再合并。PaddleOCR 有版面分析功能但需要额外配置。5.2 向量检索的语义漂移现象用了一段时间后发现一个诡异现象搜某些技术术语时返回的结果语义上相关但实际不匹配。比如搜连接池配置返回了一堆线程池内存池的内容。这就是语义漂移——嵌入模型把池这个概念泛化了忽略了具体类型。根因是嵌入模型在训练时见到的池相关文本比较杂没有区分不同技术语境。解决办法有两个一是用领域数据微调嵌入模型成本高但效果最好二是加关键词检索做兜底BM25 对精确术语的匹配很准能弥补向量检索的不足。我选了后者混合检索之后这个问题基本解决了。5.3 长文档切分的边界丢失有次问一个跨章节的问题AI 回答得支离破碎。排查发现是切分时把相关内容切到了不同 chunk检索只召回了其中一部分。比如一个问题的答案分散在背景和解决方案两个章节切分后成了两个独立 chunk检索时只命中了一个。改进方法是增加 chunk 重叠并且在元数据里记录章节关系。检索时如果命中某个 chunk把它的前后相邻 chunk 也一起召回。这样虽然增加了上下文长度但保证了信息完整性。另外对于明确跨章节的问题可以在检索时扩大 top_k让更多相关 chunk 进入候选。5.4 多轮追问的上下文污染追问几轮之后AI 开始跑偏回答越来越偏离原始问题。原因是历史对话里的错误信息被反复引用形成了累积误差。比如第一轮回答有个小错误第二轮基于这个错误继续推理越错越远。我的解法是每轮追问都重新检索历史对话只作为参考不作为事实依据。在 prompt 里明确告诉模型以检索资料为准历史对话仅供参考。另外如果检测到连续几轮回答质量下降就主动重置对话历史从当前问题重新开始。5.5 增量更新的索引一致性问题新文档加入后有时候检索不到有时候又检索到旧版本。排查发现是 ChromaDB 的持久化和内存索引没同步。写入后需要显式调用 persist否则重启后数据可能丢失。另外删除旧文档时要确保向量和元数据一起删只删一个会导致检索时找不到对应内容。现在的做法是每次批量导入后调用client.persist()并且用文档哈希做去重同一文档更新时先删后插。定期做一次全量校验对比文件系统和数据库的记录清理孤儿数据。6. 让知识库真正活起来的几个优化方向6.1 查询改写让检索更懂你的意图用户的问题往往口语化、模糊直接拿去检索效果不好。查询改写是把口语化问题转成更适合检索的形式。比如那个接口超时的问题怎么解决的改写成接口超时 排查 解决方案。实现方式有两种一是用规则做同义词替换和关键词提取二是用一个小模型做 query rewriting。我用的是后者用 Qwen2.5-1.5B 做轻量改写速度快效果也够用。改写后的查询同时用于向量检索和关键词检索召回率提升明显。6.2 多路召回与结果融合除了向量和 BM25还可以加其他召回路径。比如按元数据过滤限定某个项目或时间段、按文档类型过滤只要技术方案不要会议纪要。多路结果用 RRFReciprocal Rank Fusion融合比简单加权更稳定。RRF 的公式很简单每个文档的得分是1/(k rank)的累加k 一般取 60。这个方法不需要调权重对不同召回路径的尺度差异不敏感实测效果不错。6.3 回答溯源与置信度标注AI 回答最怕胡编。我的做法是要求模型在回答时标注信息来源比如根据《XX方案》第 3 节。如果检索到的资料不足以回答问题模型要明确说资料中没有相关信息而不是硬编一个答案。置信度标注是给每个回答打个分基于检索相似度和重排序分数综合计算。分数低的回答会提示用户此回答依据不足建议核实。这个机制能有效减少误导。6.4 定期重建与知识库健康度检查知识库不是建完就不管了。文档会更新模型会升级检索策略会调整定期重建索引能保证一致性。我一般一个月做一次全量重建平时增量更新。健康度检查包括文档覆盖率有多少文档成功入库、检索命中率随机抽样问题看能否召回相关文档、回答准确率人工抽检。发现异常及时排查避免问题累积。7. 一些实际使用中的体会这套系统跑了大半年最大的感受是知识库的价值不在于技术多先进而在于能不能真正融入日常工作流。我现在的习惯是遇到问题先问知识库能解决就解决解决不了再把新发现补充进去。这样知识库越用越厚检索越用越准。另一个体会是不要追求一步到位。我一开始想支持所有格式、所有功能结果拖了很久没上线。后来砍掉非核心需求先把 PDF 和 Markdown 跑通两周就出了可用版本。后续再逐步加功能反而推进得更快。最后分享一个小技巧给知识库加一个最近更新视图能看到最近加入的文档和最近的问答记录。这不仅能帮你回顾还能发现知识盲区——哪些问题反复被问但资料不足就是需要补充的方向。