最近几个月总有人问我同一个问题公司内部那几百份文档能不能丢给大模型自己问我的回答通常是能但关键要想清楚你是想用云上大模型临时问几次还是想搭一套数据不出本机的本地化 RAG 智能体。前者一个申请工单就能跑通后者才值得你花时间看我这篇记录。这篇东西写给想在自己电脑或内网服务器上做一套完整文档问答系统的开发者。我会把为什么做、怎么选组件、怎么搭管线、实测里踩过哪些坑全部讲一遍。所谓 RAG翻译成大白话就是先检索再生成用户问一个问题系统先去本地知识库里把最相关的几段内容捞出来然后把这些内容和问题一起交给大模型组织答案。而智能体意味着它不是一次性的问答接口而是能结合对话历史、判断要不要查资料、引用出处、多轮追问的系统化流程。把这三件事全部跑在本机就叫本地化 RAG 智能体。我试过不下三种架构也帮别人调过类似系统。最终沉淀下来的这套打法不依赖外部网络、不需要按次付费而且效果可调可控。下面按我的实践顺序展开先讲动机再讲选型然后是核心实现和调优记录。1. 为什么要做本地化而不是继续调云端接口1.1 数据隐私问题有些文档根本不该离开内网有些内容比源代码敏感得多。比如薪酬结构、未公开的架构评审、合作协议、病历数据、监管材料。这些文档一旦通过外部接口去做问答意味着文档内容、检索片段、用户问题、生成答案全部要在外部服务上过一遍。服务方可能说不留存但合规同学不会接受一句保证就不怕。本地化的最大优势是所有数据只存在于本机内存和本地索引文件里断网也能跑没有第三个环境接触原始内容。这一条基本决定了百分之八十的团队要不要走本地化。我见过不止一个团队最初用云端接口做内部知识库后来因为数据出境审查的问题整套方案推翻重来。与其那时候再折腾不如一开始就把数据不出本机定为硬性需求。1.2 成本结构变了本地化是拿算力换灵活Token 计费在频繁多轮对话场景下费用增长非常快。一个人一天问几百次长期下来是一笔不小的开销。而本地化是一次性硬件投入加电费消费级显卡加一个 7B 量级量化模型16G 显存就能流畅跑没有独立显卡CPU 硬扛也能出结果只是慢一些。如果你的场景是批量处理长文档本地部署的成本优势尤其明显。这并不是说本地永远便宜。等你要服务几十个人、并发一上来单机不够用就得投入多卡甚至小型算力集群运维成本会陡增。所以我的建议很简单小团队、单机、知识库规模在几十万条以内本地化很划算如果明确要做上千人规模的企业级服务再考虑分布式方案。1.3 智能体三个字在本地化场景里意味着什么把 RAG 封装成智能体不是简单给大模型接一个检索工具。我的理解是这套系统必须能自己判断这个问题需不需要查资料能把它这个功能这类指代还原成完整描述能在多轮对话里保持上下文还能在回答末尾给出参考片段。本地化让这些环节全部可以改、可以调、可以加日志这是工程上的巨大便利也是我最喜欢本地化的原因。调试智能体是一件很依赖看见中间过程的事情。云端接口往往只给你最终答案中间检索到了什么、prompt 最终拼成了什么样都要靠猜。本地化则不同每个环节都能打印出中间结果问题出在哪里一眼就能定位。2. 选型决策我把整套方案拆成四层逐一取舍很多人一上来就纠结用哪个大模型其实顺序反了。一个 RAG 系统至少要拆成四层嵌入层、存储检索层、生成层、编排层。只有把四层分开考虑后面调优才有抓手。层级核心职责选型要点嵌入层把文本转换成向量中英文混合能力、参数量、维度存储检索层存向量并召回相关片段持久化能力、单机规模、检索速度生成层组织语言回答问题显存占用量、上下文长度、遵循指令的能力编排层串起检索和生成的流程可控性、调试成本、是否易于替换组件2.1 嵌入模型决定能不能找到的关键嵌入模型的作用是把文字变成向量向量之间的远近代表语义上的相似程度。它决定了检索阶段能不能找到相关文档是整个系统召回率的上限。如果这一层没选好后面生成模型再强也无济于事因为根本捞不到有效内容。中文场景下我优先选择支持中英文混合的通用嵌入模型参数规模在 0.3B 到 1B 之间就够用。这类模型在长文档处理上表现稳定维度和计算开销也在可接受范围。判断嵌入模型好坏不建议只看榜单分数直接拿你的文档做测试从文档里摘出 20 个问题对比不同嵌入模型召回的片段是否准确。只有真实数据能告诉你答案。2.2 向量库轻量持久化与超大规模的权衡个人开发者和中小团队我建议先用进程内嵌入式向量库也就是直接在应用进程里读写数据落盘后可以恢复。它的好处是零运维、接口简单常见实现都支持向量检索和元数据过滤足够支撑几十万条规模的本地知识库。什么时候需要换独立部署的服务型向量库当数据量到百万条以上或者多个业务模块需要并发访问同一个向量库时再考虑也不迟。否则你会把大量精力花在部署、监控和升级上而不是花在调检索效果上。一个大原则先让单机跑通跑稳再想分布式。2.3 本地大模型显存定档别盲目上大参数生成层需要的是对话模型它决定回答的流畅度、准确度和可读性。选择逻辑只有一个核心约束你的显卡能装下多大参数。7B 量化模型大约需要 6-8G 显存速度和效果比较均衡适合大多数场景13B 级大约 10-12G更聪明但也更吃资源再往上的参数需要多卡或者大显存单机成本明显上升。没有独立显卡也没关系CPU 可以跑只是延迟会到几十秒级别适合离线批量问答。除了显存还要看模型上下文长度。RAG 会把多个文档片段拼进提示词如果模型上下文只有 4K往往塞进两个片段就截断了。建议生成模型上下文至少 8K 起步越多越好这直接影响你能给模型喂多少参考资料。2.4 编排层全家桶还是手写胶水编排层是连接各组件的中枢很容易被忽略也很容易被过度设计。主流框架能帮你省掉文档加载、切块、拼接提示词等样板代码同时保留各层替换的余地。但框架抽象层级多出问题时链路拉得很长。我自己的做法是核心检索和生成逻辑手写外围的文档解析、格式清洗可以借助现成库。不要为了用框架而用框架。如果只是把文档切成块存进向量库、再捞出来拼到提示词里这一步总共也就几十行代码。手写的好处是每一条数据流都在你眼皮底下任何环节出了问题你都能立刻找到位置。3. 三条数据管线拆解从原始文档到可追溯的回答3.1 文档摄入与切块chunk 大小直接影响检索命中率本地 RAG 的第一步是把 PDF、Word、Markdown、HTML 等格式统一转成纯文本。PDF 要注意栏位和标题顺序Word 要看表格结构Markdown 和 HTML 要剥离掉标记符号。格式洗得越干净后面切块质量越高。切块是整条链路里最容易被低估的环节。切小了一个完整知识点会被截断导致检索只能命中碎片切大了单个片段包含太多无关内容和用户问题的匹配度会被稀释。我的默认起点是 500 字符一块、100 字符重叠。重叠窗口是为了让跨块的内容不至于在边界处丢失比如一个结论放在上一块的最后下一块又能从重叠位置读到。代码类文档建议更小300 字符左右因为代码块上下文依赖强叙事性文档可以适当放宽到 800 字符。重点是不要机械照搬参数要拿你的真实文档测试。3.2 检索与重排为什么只靠向量检索不够向量检索擅长找意思相近的内容但遇到精确匹配场景经常翻车。比如文档里写的是英文缩写RAG用户问检索增强生成向量匹配没问题但如果用户查的是某个具体编号、变量名、设备型号语义向量往往拉不近。这时候就需要关键词检索来兜底用 BM25 这类词频算法做精确匹配再和向量检索结果合并。合并之后还要考虑一个排序问题。向量检索返回的 top 候选片段未必每条都真的相关。我的习惯是加一个轻量重排阶段把候选片段和一个小的排序模型按相关性重新打分。重排会增加延迟但效果提升非常明显尤其适合知识库质量参差不齐的本地场景。如果机器性能有限也可以先用向量检索关键词检索的混合结果直接上把重排作为后续优化项。3.3 生成端的智能体行为查询改写、多轮记忆与引用溯源到了生成端才是智能体和普通问答接口的分水岭。本地模型指令遵循能力比云端顶级模型弱所以流程设计要尽量显式化。我设计了一个简单的三步流程第一步改写用户问题。多轮对话里经常出现它怎么配置这个能不能实现这类省略句如果不做指代消解直接拿去检索往往搜不到。我用一个轻量改写提示把它还原成完整描述第二步判断是否需要检索。有些问题只是闲聊或者追问上文的解释不一定要重新查库第三步检索后把上下文注入提示词要求模型只依据片段内容回答片段不足就直接说不知道并且句末标注引用了第几个片段。这三个流程并不复杂但对回答质量的影响是决定性的。本地小模型如果不在 prompt 里反复强调不要编造它就会理直气壮地输出幻觉内容一旦明确约束再配合引用编号回答的可信度会大幅提升。4. 本地 RAG 智能体实现骨架可运行的代码与步骤下面给一套可以复现的最小实现骨架。为了便于理解我用 HTTP 请求调用本地模型服务的方式串联流程不依赖某个特定框架。核心思路是模型层通过 HTTP 暴露接口业务层负责切块、存取、检索和 prompt 拼接。4.1 环境准备先把模型服务跑起来第一步你需要一个本地模型运行服务把对话模型和嵌入模型都暴露成 HTTP 接口。以本地一台 16G 显存的机器为例直接下载一个 7B 量级开源中文对话模型和一个嵌入模型按文档启动即可。启动顺序是先确认服务可用再写业务代码。可以用一个简单的请求验证服务是否就绪curl http://127.0.0.1:8899/v1/chat/completions \ -H Content-Type: application/json \ -d { model: local-chat-7b, messages: [{role: user, content: 你好}] }如果返回里包含正常的回答文本说明生成服务已经可以调用。嵌入模型的验证类似请求 embeddings 接口传一句文本看看能否返回一串浮点向量。4.2 建立索引从文件到向量库接下来把文档切成块并写入向量库。下面的代码用伪客户端包vector_store表示你选用的向量库实际使用时替换成你选择的库的 API 即可。需要说明的是load_and_clean函数我故意留白因为不同文档格式的解析差异太大。核心逻辑是读文件、清洗格式、返回纯文本。import requests EMBED_URL http://127.0.0.1:8899/v1/embeddings CHAT_URL http://127.0.0.1:8899/v1/chat/completions MODEL_CHAT local-chat-7b MODEL_EMBED local-embed def get_embeddings(texts): resp requests.post(EMBED_URL, json{ model: MODEL_EMBED, input: texts }) resp.raise_for_status() return [item[embedding] for item in resp.json()[data]] def load_and_clean(path): # 这里需要根据文件格式实现PDF 按顺序抽取文本 # Markdown 剥离标记Word 提取段落和表格。 # 返回一个干净的纯文本字符串。 return def chunk_text(text, chunk_size500, overlap100): chunks [] start 0 n len(text) while start n: end min(start chunk_size, n) chunk text[start:end].strip() if chunk: chunks.append(chunk) if end n: break start end - overlap return chunks def build_index(paths, store): all_chunks, all_metas [], [] for path in paths: raw_text load_and_clean(path) chunks chunk_text(raw_text) for idx, chunk in enumerate(chunks): all_chunks.append(chunk) all_metas.append({source: f{path}#{idx}}) embeddings get_embeddings(all_chunks) store.upsert( ids[str(i) for i in range(len(all_chunks))], documentsall_chunks, embeddingsembeddings, metadatasall_metas, )向量库的upsert是把数据写进去ids用于唯一标识documents是原始片段embeddings是对应的向量metadatas里我存了来源路径和块序号这是后面对答案做溯源的基础。4.3 检索问答封装把整个流程串成智能体索引建好之后就到了问答环节。这里我封装了retrieve和build_prompt两个函数核心思路是每次提问都先检索、再拼 prompt、最后调用本地模型生成回答。def retrieve(query, store, top_k5): emb get_embeddings([query])[0] res store.query( query_embeddings[emb], n_resultstop_k, include[documents, metadatas] ) return list(zip(res[documents][0], res[metadatas][0])) def build_prompt(question, docs, history): contexts \n\n.join( [f[片段{i1}]\n{doc} for i, (doc, _) in enumerate(docs)] ) history_text \n.join(history[-4:]) if history else 无 return ( 你是本地知识库问答助手。请只依据下面给出的文档片段回答用户问题。\n f对话历史\n{history_text}\n\n f文档片段\n{contexts}\n\n f用户问题{question}\n 回答要求\n 1. 如果片段足够请给出完整答案并在句末标注参考片段如[1]。\n 2. 如果片段信息不足直接回答资料中暂未找到相关信息。\n 3. 不要编造不要使用片段之外的知识。 ) def ask(question, history, store): docs retrieve(question, store, top_k5) prompt build_prompt(question, docs, history) resp requests.post(CHAT_URL, json{ model: MODEL_CHAT, messages: [{role: user, content: prompt}], temperature: 0.2, max_tokens: 512, }) content resp.json()[choices][0][message][content] return content, docs这样整个骨架就串起来了。之后可以按需加日志模块、历史记录存储、引用解析——只要把检索到的原始片段和最终回答同时打印出来排查效率立马上一个台阶。5. 实测调优记录答得好不好是可以被衡量的5.1 不迷信测试集我用 20 个问题做效果基线调优之前先定一个可以重复验证的基线问题集。我从真实文档场景里整理了 20 个问题四类各 5 个文档内明确能直接找到答案的需要跨多个段落才能推断的文档内根本找不到也应该明确说不知道的多轮追问中依赖历史信息的。每跑完一次改动我固定用这 20 个问题回归一遍人工记录三档结果答对且引用准确、答对但无引用、答错或直接说不知道。这个基线问题集一定要贴近你的真实使用场景别拿公共榜单题来测本地知识库。公共数据集和你的文档格式、语言风格差异太大测出来的分数指导不了实际调参。5.2 调参记录chunk_size、top_k、温度、上下文拼接反复测试之后我记录下几个关键参数对效果的影响参数设置观察到的现象chunk_size300长段落被切断跨段信息检索不到chunk_size800单个片段噪音太多答案容易跑偏chunk_size500 重叠 100综合平衡最好适合大多数文档top_k3覆盖不够重要信息经常漏掉top_k10噪音明显变大回答冗长且不聚焦top_k5当前场景最优temperature0.7表述飘忽输出风格不稳定temperature0.2稳定很多事实性问答更可靠这里面的规律并不复杂检索类问题优先保证精度宁可少召回不可多污染所以 top_k 不宜给太大chunk_size 和文档结构强相关结构化强的技术文档可以适当缩小叙述性文档可以放大temperature 不要一上来就追随机性和创造力本地 RAG 的核心是忠实于资料稳定比发挥更重要。最后是我反复提到的 prompt 模板给本地模型写清边界规则是投入产出比最高的一项调优。5.3 高频翻车场景与排查链路我再整理几个实际踩过的坑每一类都附上排查路径遇到问题可以直接照着走。第一类资料明明在里面就是查不到。排查链路很固定先看索引里有没有这个片段用文档标题或某个关键词去向量库里直接搜如果搜不到就看切块是不是把关键词拆烂了或者嵌入模型对领域术语不敏感。前者调整 chunk 重叠和大小后者增加关键词检索做候补。第二类答得头头是道但完全是编的。这类问题九成出在 prompt 约束不够或者 top_k 太大导致不相关片段混进来。先打印出检索结果看模型真正的依据是什么基本一眼就能定位。我建议在 prompt 里写明宁可说不知道也不要根据片段之外的信息作答并且不要用默认的对话风格模板覆盖掉这个约束。第三类上下文过长被截断。把模型上下文调大或者减少片段数。片段多不等于效果好取最相关的 4 到 5 个片段往往比 10 个片段的综合效果更稳。还可以让模型先生成一个简短的这些片段是否足够回答的判断再决定是否扩大检索范围但初期不建议搞太复杂。第四类多轮对话之后突然答偏。常见原因是历史记录太长把最新的上下文冲淡了。我在build_prompt里只保留最近四轮历史并在每次检索前对用户最新问题做一次去指代改写效果立竿见影。最后说一个我自己调了一下午才想明白的点本地 RAG 调优百分之九十的问题出在检索和切块而不是生成模型。模型只是那个最后开口说话的人它能不能说好取决于你喂养给它的上下文是否精准、约束是否清楚。回到开头的问题到底要不要搭一套本地化的 RAG 智能体——如果目标是给几百份内部文档做一个数据不出内网的知识助手这条路径成本可控、效果可见、迭代方便值得动手如果只是偶尔拿几十页文档试验一下那直接用现成的问答工具处理一次就够了。