1. 为什么我要从零搭一个个人知识库问答机器人我自己平时有大量阅读和记录的习惯散落在各种笔记软件、Markdown 文件、网页剪藏里的资料少说也有几千篇。时间一长就出现一个很尴尬的问题东西明明存过但真要用的时候死活找不到。全文搜索只能匹配关键词稍微换个说法就搜不出来更别提让它帮我总结、对比、串联不同笔记里的观点了。这个痛点我想很多人都有所以当我第一次接触 Agent 和 RAG 这两个概念的时候第一反应就是——这不就是给我这种“资料囤积症患者”准备的吗。所谓Agent你可以理解成一个能自己决定“下一步该干什么”的智能体它不只是被动回答而是会调用工具、检索资料、多轮推理。而RAGRetrieval-Augmented Generation检索增强生成解决的是大模型“不知道你私人资料”的问题先把你的文档切块、向量化存进知识库提问时先检索出最相关的片段再交给模型基于这些片段回答。两者结合就得到一个能读懂我个人知识库、还能主动帮我干活的问答机器人。这篇内容我打算把整个搭建过程完整复盘一遍包括技术选型为什么选LangChain、文档怎么切、向量库怎么选、检索效果怎么调、踩了哪些坑。适合有 Python 基础、想入门 Agent 开发但不知道从哪下手的朋友也适合已经用过现成知识库工具、想自己掌控全流程的人。我不会只贴代码更想讲清楚每一步背后的取舍逻辑这样你换一套资料、换一个场景也能自己迁移。2. 整体架构设计与技术选型思路2.1 先想清楚这个机器人到底要解决什么问题动手写代码之前我强迫自己先把需求写清楚因为 RAG 项目最容易犯的错就是一上来就堆技术栈最后做出来的东西又慢又不准。我的核心需求其实就三条第一能对我本地的 Markdown 和 PDF 文档做问答回答必须基于原文不能瞎编第二支持多轮对话能追问“那第二点展开说说”第三最好能主动调用工具比如帮我算个数、查个日期。这三条需求直接决定了架构。第一条要求必须有检索环节也就是 RAG 的标准流程第二条要求有对话记忆管理第三条要求引入 Agent 的工具调用能力。所以最终形态是“RAG 打底 Agent 调度”的组合而不是单纯的问答机器人。2.2 技术栈选型为什么是 LangChain 而不是自己造轮子很多人会问RAG 流程不就是“切块-向量化-检索-拼 prompt”吗自己写也就一两百行为什么要用LangChain我一开始也是这么想的直到我真正开始处理各种边界情况不同格式的文档加载、切块时保留元数据、检索后重排序、对话历史裁剪、工具调用的解析……这些琐碎但关键的环节LangChain 都有现成的抽象。更实际的原因是生态。LangChain 把 LLM、Embedding、向量库、文档加载器都做成了统一接口我换一个模型或者换一个向量库改动量极小。比如我一开始用 OpenAI 的 embedding后来想换成开源的本地 embedding只改了一行配置。这种可替换性在快速试错阶段太重要了。不过我也要泼盆冷水LangChain 抽象层多出问题的时候报错信息经常藏在好几层调用栈里调试起来比较痛苦。所以我的建议是先用 LangChain 快速跑通理解每个环节在干什么等遇到性能或精度瓶颈再针对性地替换掉某一层而不是一上来就全自己写。2.3 组件拆解一个 RAG Agent 由哪几块拼成我把整个系统拆成五个模块这样每块都能单独测试和替换模块职责我的选型替换成本文档加载读取各种格式文件LangChain 的 DirectoryLoader低文本切分把长文档切成小块RecursiveCharacterTextSplitter低向量化文本转向量本地 embedding 模型中向量存储存向量并做相似度检索本地向量库中Agent 调度决定检索还是调工具LangChain Agent 工具集高这个拆法有个好处当回答不准的时候我能快速定位是切分问题、检索问题还是生成问题。比如检索出来的片段明明是对的但回答还是错的那问题就在生成环节的 prompt 上而不是去瞎调向量库参数。3. 核心细节解析与实操要点3.1 文档切分RAG 效果的地基90% 的人在这里翻车我可以很负责任地说RAG 效果不好一大半问题出在切分上。切分就是把长文档切成一段段适合检索的小块chunk切得好检索精准切得烂检索出来的片段要么缺上下文要么混入无关内容。我踩过的第一个坑就是切得太大。一开始我设 chunk_size 为 2000 字符想着信息量大点总没错。结果检索出来的片段里一半是废话模型被干扰得答非所问。后来我把 chunk_size 调到 500 到 800 之间配合 100 到 150 的 overlap重叠效果明显好转。为什么要有 overlap因为切分是硬切的一句话可能被从中间劈开。重叠部分能让被切断的语义在相邻块里补全。这个道理就像你撕一张报纸撕口处的字两边各留一点拼起来才读得通。from langchain.text_splitter import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size600, chunk_overlap120, separators[\n\n, \n, 。, , , , , ], )注意 separators 的顺序它是从大到小尝试的先按段落切段落太长再按句子切最后才按字符硬切。中文文档一定要把中文标点加进去否则它会按空格切中文里空格少就会退化成硬切。提示切分参数没有万能值。技术文档逻辑性强块可以小一点叙事类内容上下文依赖重块要大一点。我的经验是先跑一批测试问题看检索结果再反过来调参数。3.2 向量化与向量库本地跑还是调 API向量化就是把文本变成一串数字向量语义相近的文本向量距离也近。这一步有两个选择调云端 API或者本地跑开源模型。我最终选了本地 embedding 模型原因有三个一是隐私我的笔记里有些私人内容不想上传二是成本几千篇文档反复调试调 API 的钱积少成多三是离线可用断网也能跑。代价是首次要下载模型而且速度比云端慢一些但对个人知识库这种规模完全够用。向量库我选的是本地轻量方案直接把向量存成文件。为什么不上一套专业的向量数据库因为我的数据量就几千个 chunk本地文件检索毫秒级就返回了引入数据库反而增加部署复杂度。选型要匹配规模不要为了技术而技术。等你的知识库涨到几十万 chunk再考虑迁移到专业向量库也不迟。3.3 Agent 的工具设计让它真的“会干活”普通 RAG 只能问答Agent 的价值在于能调用工具。我给机器人配了三个工具知识库检索、计算器、当前时间查询。工具设计有个原则——描述要写得像给新员工交代任务一样清楚因为模型是靠工具描述来决定调不调的。from langchain.tools import tool tool def search_knowledge_base(query: str) - str: 当用户询问个人笔记、文档、资料相关的问题时使用此工具。 输入应该是一个完整的自然语言问题而不是单个关键词。 docs retriever.invoke(query) return \n\n.join(d.page_content for d in docs)注意 docstring 里的说明我特意强调“输入是完整问题而非关键词”因为早期模型老是把“LangChain”这种单词丢进去检索效果很差。工具描述就是给模型的说明书写得越具体它用得越准。3.4 对话记忆多轮追问的关键没有记忆的机器人你问“那第二点呢”它一脸懵。LangChain 提供了几种记忆方案我选的是滑动窗口记忆只保留最近几轮对话。为什么不保留全部因为上下文越长模型越容易分心而且 token 成本飙升。对个人问答场景最近 5 轮基本够用。这里有个细节记忆里存的应该是用户问题和最终回答而不是中间的工具调用过程。否则上下文会被大量检索片段塞满模型反而抓不住重点。4. 完整实操流程与关键环节实现4.1 环境准备与依赖安装先把环境搭起来。我建议用虚拟环境避免污染全局包。python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install langchain langchain-community langchain-text-splitters pip install chromadb sentence-transformers pypdf这里解释下几个包langchain-community放的是各种集成组件sentence-transformers提供本地 embedding 模型pypdf用来读 PDF。如果你只用 Markdownpypdf 可以不装。4.2 加载文档并构建向量库假设你的笔记都放在./knowledge目录下格式是 Markdown 和 PDF 混合。from langchain_community.document_loaders import DirectoryLoader, TextLoader from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma # 1. 加载文档 loader DirectoryLoader( ./knowledge, glob**/*.md, loader_clsTextLoader, loader_kwargs{encoding: utf-8}, ) documents loader.load() print(f共加载 {len(documents)} 个文档) # 2. 切分 chunks splitter.split_documents(documents) print(f切分后得到 {len(chunks)} 个片段) # 3. 向量化并存入向量库 embeddings HuggingFaceEmbeddings( model_nameBAAI/bge-small-zh-v1.5, model_kwargs{device: cpu}, ) vectorstore Chroma.from_documents( documentschunks, embeddingembeddings, persist_directory./vector_db, ) vectorstore.persist()bge-small-zh-v1.5是我实测下来中文效果不错、体积又小的模型几百兆CPU 上跑也不慢。第一次运行会下载模型耐心等几分钟。注意向量库构建是一次性的之后提问直接加载persist_directory即可不用每次重新切分。但如果你更新了笔记记得重新构建否则检索的还是旧内容。4.3 搭建检索器并调优检索器决定了“从知识库里捞哪些片段给模型”。最基础的是相似度检索但我强烈建议加上 MMR最大边际相关性重排。retriever vectorstore.as_retriever( search_typemmr, search_kwargs{k: 4, fetch_k: 20, lambda_mult: 0.5}, )这几个参数什么意思fetch_k20表示先捞出 20 个候选k4表示最终只留 4 个给模型lambda_mult0.5控制多样性——值越小结果越多样值越大越聚焦相似。为什么要多样性因为如果 4 个片段全是同一段话的重复模型就看不到其他角度的信息了。MMR 就是解决“检索结果同质化”这个问题的。我实测下来纯相似度检索经常返回一堆高度重复的片段换成 MMR 后回答的覆盖面明显变广。4.4 组装 Agent 并接入对话最后把检索器包装成工具交给 Agent 调度。from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 你是一个个人知识库助手。回答必须基于检索到的资料 如果资料里没有相关信息就诚实说不知道不要编造。), (placeholder, {chat_history}), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, [search_knowledge_base, calculator], prompt) agent_executor AgentExecutor( agentagent, tools[search_knowledge_base, calculator], memorymemory, verboseTrue, ) result agent_executor.invoke({input: 我之前记的关于 RAG 切分参数的笔记说了什么}) print(result[output])verboseTrue在调试阶段一定要开你能看到 Agent 每一步在想什么、调了什么工具、传了什么参数。这是排查问题最有效的手段。4.5 参数计算chunk 数量与检索成本的估算很多人不关心这个但心里有个数很重要。假设你有 1000 篇笔记平均每篇 2000 字总共 200 万字。按 chunk_size600、overlap120 计算每个 chunk 净增 480 字大约产生 2000000 / 480 ≈ 4167 个 chunk。检索时每次要计算 query 向量和所有 chunk 向量的相似度。4000 多个向量本地计算一次大概几十毫秒完全可接受。但如果你的知识库涨到 40 万个 chunk线性扫描就会变成几百毫秒甚至更久这时候就得上近似最近邻ANN索引了。所以规模决定架构别过早优化也别等到卡死了才想起来优化。5. 常见问题与排查技巧实录5.1 回答不准按这个顺序排查RAG 出问题新手最容易乱调参数。我总结了一套排查顺序从源头往下查现象可能原因排查方法解决方向检索不到相关内容切分太碎或太大打印检索结果看原文调 chunk_size检索到了但答非所问prompt 没约束看模型输入强化 system prompt回答缺上下文overlap 太小检查被切断的句子增大 overlap结果重复啰嗦检索同质化看返回片段相似度换 MMR 检索多轮对话失忆记忆没接上打印 chat_history检查 memory 配置我的习惯是先打印检索到的原始片段这一步能解决 80% 的问题。如果片段本身就是错的那再怎么调 prompt 都没用。5.2 中文检索效果差的三个隐藏原因第一个原因是 embedding 模型选错了。很多英文模型对中文语义的捕捉很弱一定要选中文或中英双语模型。第二个原因是切分时没加中文标点分隔符导致句子被硬切。第三个原因是 query 太短比如只输入“切分”向量信息量太少检索自然不准。解决办法是让 Agent 把用户问题改写成完整句子再检索这也是我在工具描述里强调“输入完整问题”的原因。5.3 踩过的坑向量库更新与增量索引我遇到过一个很坑的问题往知识库加了新笔记但机器人死活检索不到。查了半天才发现向量库是构建时快照新增文档不会自动进去。后来我改成每次启动时检查文档数量有变化就重建索引。对个人知识库这种规模全量重建也就几十秒比维护增量索引的复杂度划算多了。提示如果你追求增量更新可以用文档的哈希值做去重只对新增或修改的文件重新向量化。但这套逻辑要自己写LangChain 没有开箱即用的方案。5.4 性能与并发个人场景别想太多网上很多文章一上来就讲怎么扛高并发但个人知识库问答机器人根本用不上。你一个人用QPS 撑死也就 1。真正影响体验的是首字延迟也就是从提问到看到第一个字的时间。这个时间主要花在检索和模型推理上。我的优化手段很简单把 embedding 模型常驻内存避免每次重新加载检索结果做缓存相同问题直接返回。这两招下来重复问题的响应几乎是瞬时的。5.5 一个容易被忽略的细节元数据过滤我的笔记分好几个主题有时候我只想在“技术”类笔记里搜。这时候元数据就派上用场了。加载文档时给每个 chunk 打上来源、分类标签检索时加过滤条件retriever vectorstore.as_retriever( search_kwargs{k: 4, filter: {category: tech}}, )这个功能在知识库变大之后特别有用能大幅缩小检索范围提升精度。代价是加载文档时要多写点元数据提取逻辑但绝对值得。6. 后续可以怎么扩展跑通基础版本之后我陆续加了一些扩展这里分享几个性价比高的方向。第一个是多模态把图片也纳入知识库。做法是用视觉模型给图片生成文字描述再把描述向量化检索时就能命中图片内容。第二个是重排序在检索之后加一个 rerank 模型对候选片段重新打分精度能再上一个台阶。第三个是定时同步让机器人定期扫描笔记目录自动更新索引省得手动重建。我个人在实际操作中的体会是RAG 这个方向工程细节远比模型选择重要。同一个模型切分和检索调好了效果能差出一大截。所以别急着追新模型先把数据管道打磨扎实收益更明显。最后再分享一个小技巧准备一组 20 到 30 个测试问题每次改完参数都跑一遍用命中率量化效果比凭感觉调参靠谱得多。
