简介面向有一定技术基础的企业用户与个人开发者这份 DOCX 文档聚焦 Deepseek 与本地知识库的私有化部署讨论数据隐私敏感场景下的工具选择与知识管理落地。内容对比 Cherry Studio 和 AnythingLLM 两条路线涉及嵌入模型、本地服务、模型配置、文档向量化、搜索验证与大模型问答等环节并延伸到企业培训、科研检索、个性化推荐及内容运营等场景。资源包共 1 个 DOCX 文件约 1.47MB内容集中、便于查阅。已有 2902 人学习读者可了解两类工具的适用边界获得隐私数据离线使用提醒并建立从文档入库到检索问答的整体框架文档还讨论了本地大模型在资料查找、关联发现和代码辅助方面的优势适合兼顾隐私与检索效率的读者参考便于读者对照自身需求选择方案。1. 把 DeepSeek 接进本地知识库先算清“检索省下的上下文”这笔账某公司内部有几百份制度文档一开始把全文塞进 DeepSeek 对话框问“报销节点”时模型答得挺顺但问到跨文档的审批链就开始漏条款。原因不玄学上下文窗口再大也不会自动帮你做段落级定位。DeepSeek本地知识库的部署方法核心不是把模型跑起来而是把“文档切分—向量召回—拼 Prompt—生成引用”这条链路固定下来应用场景也从内部问答延伸到工单辅助、代码库检索和售后话术查询。适合手里有私有文档、又不想把原文交给外部接口的团队。下面按可复现的步骤拆。2. 文档切分与向量召回本地知识库的四个参数怎么定2.1 先做文档清洗把 PDF、Word、Markdown 统一成可切分的文本本地知识库最先翻车的地方通常不是模型而是输入文本。PDF 里的页眉页脚、双栏排版、表格线Word 里的自动编号和批注Markdown 里的代码块直接丢进切分器会切出一堆无意义片段。常见做法是先做一层文档清洗把不同格式统一成带source、title、section元数据的纯文本块后面召回时才能把引用定位到章节。我一般会把清洗拆成三个动作按文件类型解析、去掉高频重复行、保留标题层级。PDF 用pymupdf或pdfplumber逐页取文本Word 用python-docx读段落Markdown 直接按行读。页眉页脚的处理不用太复杂统计整份文档里重复出现的短行出现次数超过总页数一半就删掉。表格尽量转成 Markdown 表格文本不要只留单元格里的数字否则模型不知道数字属于哪一列。import re from pathlib import Path import fitz # pymupdf from docx import Document def clean_lines(lines, page_count): # 去掉页眉页脚短行且重复率过高 freq {} for line in lines: s line.strip() if 0 len(s) 40: freq[s] freq.get(s, 0) 1 drop {s for s, c in freq.items() if c max(2, page_count // 2)} out [] for line in lines: s line.strip() if not s or s in drop: continue s re.sub(r\s, , s) out.append(s) return out def load_pdf(path): doc fitz.open(path) lines [] for page in doc: lines.extend(page.get_text(text).splitlines()) return clean_lines(lines, len(doc)) def load_docx(path): doc Document(path) lines [p.text for p in doc.paragraphs] return clean_lines(lines, max(1, len(lines) // 30)) def load_text(path): text Path(path).read_text(encodingutf-8, errorsignore) return clean_lines(text.splitlines(), max(1, len(text.splitlines()) // 30))这段代码做的是格式归一化clean_lines负责去空行、合并空白、按重复频率删页眉页脚load_pdf用页数作为重复行判断的基数load_docx和load_text用行数估算一个页面规模。参数上len(s) 40是页眉页脚的典型长度太长容易误删正文c max(2, page_count // 2)是重复阈值文档页数少的时候至少出现两次才删。清洗完不要把全文拼成一个巨大字符串保留行列表下一步按标题和句子切分更稳。2.2 切分长度与重叠512 token 和 1024 token 怎么选切分参数直接决定召回质量。切得太碎单块缺少上下文模型回答“年假天数”时只看到“申请流程”切得太大一个块里混进三四个主题向量相似度被稀释召回结果看起来相关但答非所问。常见起点是chunk_size512、chunk_overlap64中文制度文档、产品手册、工单记录都适用。技术文档和代码库可以放到 768 到 1024但要把标题和函数签名保留在块开头。我不建议只按固定字符数硬切。更稳的做法是先按 Markdown 标题、Word 标题样式、PDF 里识别出的章节号切一级再在章节内部按句子切。句子切分用中文标点加换行不要用空格。每个块前面拼上“文档标题 章节标题”这样即使块内没出现关键词向量也能带上层级语义。重叠不是越大越好64 到 128 足够覆盖跨句指代重叠到 256 会让索引里充满重复片段召回时 top_k 里一半是近重复内容。参数建议起点适用场景调大后的副作用chunk_size512 token制度、手册、工单主题混杂召回精度下降chunk_overlap64 token跨句指代多的文档索引膨胀近重复变多标题前缀开多章节文档块首 token 被标题占用最小块长度80 字过滤残片太大会丢掉短条款import re def split_by_heading(text, max_chars900, overlap120): # 先按标题切大段再按句子补切 parts re.split(r(?m)^(#{1,4}\s.)$, text) sections [] current_title buffer [] for part in parts: if re.match(r^#{1,4}\s, part.strip()): if buffer: sections.append((current_title, \n.join(buffer).strip())) current_title part.strip() buffer [] else: buffer.append(part) if buffer: sections.append((current_title, \n.join(buffer).strip())) chunks [] for title, body in sections: sentences re.split(r(?[。]), body) cur for sent in sentences: if len(cur) len(sent) max_chars: cur sent else: if cur.strip(): chunks.append(f{title}\n{cur.strip()}) cur sent if cur.strip(): chunks.append(f{title}\n{cur.strip()}) # 加一点重叠避免跨块指代断掉 overlapped [] for i, c in enumerate(chunks): if i 0: overlapped.append(c) else: prev_tail chunks[i - 1][-overlap:] overlapped.append(prev_tail \n c) return overlapped这段代码先按 Markdown 标题拆章节再按中文句子累积到max_chars最后给相邻块加尾部重叠。max_chars900是字符数近似不是严格 token 数中文大约 1 字 1 token 上下落地时按你的分词器再校正。overlap120控制重叠字符数制度文档用 120 足够如果文档里跨段指代特别多可以到 160但不要超过块长的三分之一。标题前缀会进入向量检索“年假”时能命中“员工福利 年假”章节而不是只命中正文里偶然出现“年假”二字的流程页。2.3 向量模型与索引FAISS、Chroma、Milvus 的落地边界向量模型选型看语言和部署成本。中文文档为主优先选中文或多语言 embedding 模型别拿英文模型硬扛查询和文档必须用同一个模型编码混用会出现“相似度很高但语义不对”的黑匣子现象。编码后做 L2 归一化再用内积或余弦相似度检索。小规模本地知识库几千到几万块FAISS 够用单机文件索引启动快需要增删改和元数据过滤Chroma 更顺手多租户、百万级块、要独立扩容才上 Milvus 这类服务化索引。索引方案适用规模优点注意点FAISS几千到几万块单机、依赖少、检索快增删改要重建或自己维护 IDChroma几万到几十万块自带元数据和持久化大规模并发要调服务参数Milvus百万级以上分布式、过滤能力强运维成本高小团队容易过度设计import faiss import numpy as np from sentence_transformers import SentenceTransformer # 换成你本地实际使用的中文 embedding 模型目录 encoder SentenceTransformer(/models/embedding-zh) texts [员工福利 年假\n年假天数按工龄计算。, 财务报销 审批\n报销单需直属主管审批。] vecs encoder.encode(texts, normalize_embeddingsTrue, batch_size32) vecs np.asarray(vecs, dtypefloat32) dim vecs.shape[1] index faiss.IndexHNSWFlat(dim, 32) index.hnsw.efConstruction 200 index.add(vecs) query encoder.encode([年假有几天], normalize_embeddingsTrue) query np.asarray(query, dtypefloat32) index.hnsw.efSearch 64 scores, ids index.search(query, k5) print(scores, ids)这段代码用 FAISS 的 HNSW 索引建本地向量库。normalize_embeddingsTrue保证向量归一化后面用内积等价于余弦相似度IndexHNSWFlat(dim, 32)里的 32 是每个节点的连接数越大召回越稳但内存和构建时间上升efConstruction200影响建索引质量efSearch64影响查询时的候选范围线上可以先 64 再压到 32 看召回损失。k5是召回条数后面接重排时可以放到 10 再筛到 5。索引文件要跟 embedding 模型绑定换模型必须重建否则向量空间对不上召回结果会变得很随机。3. DeepSeek 本地推理服务用 vLLM 拉起兼容 Chat Completions 的接口的最小命令3.1 模型目录、显存预算与启动参数本地跑 DeepSeek 权重先把目录理清楚。常见做法是把权重放在/models/deepseek目录里包含配置文件、分词器文件和权重分片启动时只传目录不要传单个权重文件。vLLM 适合做本地推理服务原因是它直接暴露/v1/chat/completions这类接口后面的 RAG 服务不用关心底层推理框架。启动前先算显存7B 级模型在 FP16 下权重大约十几 GB加上 KV cache 和框架开销单卡 24GB 能跑但上下文不能开太大14B 级建议 48GB 以上32B 级要么多卡张量并行要么量化。下面表格是粗略预算实际按你的权重精度和并发量校正。模型规格权重精度显存建议max-model-len起点备注7B 级FP1624GB 单卡4096并发低时可用14B 级FP1648GB 单卡或双卡4096注意 KV cache32B 级FP16多卡张量并行4096先压上下文再扩并发7B 级4bit 量化12GB 到 16GB4096精度有损失先验收# 模型目录按你本地实际权重替换不要写死具体版本 MODEL_PATH/models/deepseek python -m vllm.entrypoints.openai.api_server \ --model $MODEL_PATH \ --served-model-name deepseek-local \ --host 0.0.0.0 \ --port 8000 \ --tensor-parallel-size 1 \ --max-model-len 4096 \ --gpu-memory-utilization 0.90 \ --dtype auto \ --api-key local-key这段命令把 DeepSeek 权重拉成一个本地 HTTP 服务。--served-model-name deepseek-local是后面 RAG 服务调用的模型名不用跟目录名一致--tensor-parallel-size 1表示单卡双卡改成 2--max-model-len 4096是上下文上限直接影响 KV cache 占用本地知识库的 Prompt 如果经常超过 3000 token就要往上调但先确认显存--gpu-memory-utilization 0.90控制显存占用比例留一点给系统--api-key local-key是本地接口的简单鉴权不要裸奔到公网。启动后看日志里有没有Uvicorn running和模型加载完成的信息再进下一步验证。注意max-model-len不是越大越好。它会把 KV cache 的预留空间拉高显存不够时启动直接失败或者运行中并发一上来就排队。3.2 用 curl 验证流式输出和上下文长度服务起来后不要直接接 RAG先用 curl 验证三件事接口通不通、流式输出是否正常、长上下文会不会报错。非流式请求适合脚本验收流式请求适合前端逐字显示。请求体里model填启动时的served-model-namemessages用标准的角色结构temperature先设 0.1 到 0.3知识库问答不需要太发散。max_tokens先设 512避免一次生成太长把超时拖爆。curl -s http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer local-key \ -d { model: deepseek-local, messages: [ {role: system, content: 你是一个严谨的文档问答助手。}, {role: user, content: 用一句话说明本地知识库为什么要做切分。} ], temperature: 0.2, max_tokens: 128, stream: false }这段 curl 验证非流式链路。Authorization对应启动命令里的--api-keystream: false表示一次性返回方便看完整 JSONtemperature: 0.2降低随机性max_tokens: 128只验证返回结构不验证长文生成。返回里重点看choices[0].message.content是否为空、usage里的 token 数是否合理。如果返回 401先查请求头如果返回 404查路径是不是/v1/chat/completions如果卡住不返回查模型是否加载完、显存是否打满。curl -N http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer local-key \ -d { model: deepseek-local, messages: [{role: user, content: 分三点说明 RAG 的检索链路。}], temperature: 0.2, max_tokens: 256, stream: true }-N关闭 curl 缓冲stream: true让服务按 SSE 分块返回。前端接流式时不要按行拼 JSON要按data:前缀取内容遇到[DONE]结束。流式验证通过后再发一条接近真实长度的 Prompt把检索片段拼到 2500 到 3000 token 左右看服务是否稳定返回如果报上下文超限回到启动参数调max-model-len或者在前置检索层压缩片段。这个顺序能避免把推理服务的问题误判成 RAG 逻辑问题。4. 串起 RAG 链路检索、拼 Prompt、生成回答的三个接口4.1 检索接口top_k、score_threshold 与重排怎么配检索接口不要只返回一个向量距离要把块文本、来源、章节、分数一起返回。top_k先设 8 到 12给重排留候选score_threshold用来过滤明显不相关的块但阈值跟 embedding 模型强相关不能照搬别人的 0.7。更稳的做法是先不做硬阈值用重排模型对候选打分取前 3 到 5 个进入 Prompt。重排模型可以用中文 cross-encoder输入查询和块文本输出相关性分数比单纯向量内积更能区分“年假天数”和“年假申请流程”。参数建议起点作用调错后的表现top_k8 到 12向量召回候选数太小漏召回太大稀释 Promptscore_threshold先不设或 0.3 起过滤低相关块设太高召回为空重排保留数3 到 5控制 Prompt 长度太多引入噪声单块最大 token350 到 500防止单块占满上下文太大挤掉其他证据def retrieve(query, encoder, index, chunks, top_k10, keep4): q encoder.encode([query], normalize_embeddingsTrue) scores, ids index.search(q, ktop_k) candidates [] for score, idx in zip(scores[0], ids[0]): if idx -1: continue candidates.append({ score: float(score), text: chunks[idx][text], source: chunks[idx][source], section: chunks[idx][section], }) # 这里可接重排模型没有重排时先按向量分数截断 candidates.sort(keylambda x: x[score], reverseTrue) return candidates[:keep]这段检索函数把 FAISS 的 ID 映射回原始块保留来源和章节。top_k10是候选池keep4是最终进入 Prompt 的条数如果接了重排keep可以保持 4但排序要用重排分数不要再用向量分数。source和section不是装饰字段后面生成引用时要靠它们拼出处。检索结果为空时不要硬塞一个空字符串给模型直接返回“未检索到相关片段”让上层决定是提示用户换问法还是走兜底回答。4.2 生成接口把引用片段塞进 DeepSeek 的 prompt 模板Prompt 模板要把三件事写死只依据片段回答、片段编号必须对应、找不到就说不知道。常见错误是把检索片段直接拼在用户问题后面没有边界标记模型会把片段当普通上下文开始自由发挥。我一般会用固定分隔符和编号例如[1]、[2]并在系统提示里要求“引用编号只能来自给定片段”。片段总长度控制在max-model-len的三分之一到二分之一给生成留空间如果片段太长先做摘要或截断不要硬塞。PROMPT_TEMPLATE 你是内部文档问答助手。只能依据下面的片段回答。 如果片段中没有答案直接说“根据现有资料无法确定”不要编造。 回答末尾用 [编号] 标注引用编号只能来自片段列表。 片段列表 {context} 用户问题{question} def build_prompt(question, candidates): lines [] for i, c in enumerate(candidates, 1): lines.append(f[{i}] 来源{c[source]} / {c[section]}\n{c[text]}) context \n\n.join(lines) return PROMPT_TEMPLATE.format(contextcontext, questionquestion)这个模板把检索结果编号后放进context系统提示明确“只能依据片段”和“无法确定”的兜底话术。来源和章节放在片段开头模型引用时更容易带出处。实际落地时可以把系统提示和用户内容分开系统提示走system角色片段和问题走user角色避免长片段把系统约束冲淡。temperature设在 0.1 到 0.3top_p保持默认或 0.9知识库问答不需要创意。4.3 用 FastAPI 写一个最小可用的 /ask 接口把检索、拼 Prompt、调用 DeepSeek 串成一个/ask接口前端只需要传问题。接口内部先检索检索为空直接返回兜底有候选就拼 Prompt再调本地/v1/chat/completions。请求超时要设生成参数要限制返回体里带答案和引用列表。下面代码用httpx调本地服务避免引入额外 SDKtimeout设 60 秒流式场景另做。from fastapi import FastAPI from pydantic import BaseModel import httpx app FastAPI() LLM_URL http://127.0.0.1:8000/v1/chat/completions LLM_KEY local-key class AskRequest(BaseModel): question: str app.post(/ask) async def ask(req: AskRequest): candidates retrieve(req.question, encoder, index, chunks, top_k10, keep4) if not candidates: return {answer: 根据现有资料无法确定。, references: []} prompt build_prompt(req.question, candidates) payload { model: deepseek-local, messages: [ {role: system, content: 你只依据用户提供的片段回答并标注引用编号。}, {role: user, content: prompt}, ], temperature: 0.2, max_tokens: 512, stream: False, } async with httpx.AsyncClient(timeout60) as client: resp await client.post( LLM_URL, headers{Authorization: fBearer {LLM_KEY}}, jsonpayload, ) resp.raise_for_status() data resp.json() answer data[choices][0][message][content] refs [{source: c[source], section: c[section]} for c in candidates] return {answer: answer, references: refs}这个接口把 RAG 的三段固定下来retrieve负责召回build_prompt负责约束httpx负责调本地 DeepSeek。timeout60是同步生成的保守值前端如果要求更快改成流式并缩短max_tokensmax_tokens512控制回答长度制度问答通常够用references返回的是候选片段来源不是模型自己编的编号后面可以做一次引用校验。接口层不要直接把 FAISS 索引和模型对象放在全局裸奔生产环境要加并发限制和请求日志至少能定位是检索慢还是生成慢。5. 部署与调优避坑六个翻车现场5.1 检索链路的三个坑切分、embedding、索引坑一召回结果全是页眉页脚。现象是问“报销标准”返回的前几条都是公司名、页码、文档标题重复行原因是 PDF 清洗只去了空行没有处理重复短行解决是把出现频率超过页数一半的短行删掉并在切分前过滤长度小于 10 个字的残片。这个坑很常见尤其是从办公软件导出的 PDF页眉页脚会跟着每一页进入索引向量模型会把它们当成正文。坑二问“年假天数”召回“年假申请流程”。现象是向量分数不低但块里没有天数原因是按页切分把“天数表”和“申请流程”切成了两个块而查询词同时出现在两个块里解决是按标题切分把“年假”章节下的天数表和流程放在同一个父章节下块前面拼章节标题chunk_size从 1024 降到 512overlap留 64。切分不是越细越好关键是把同一主题的表格和说明放在一起。坑三换了 embedding 模型后没有重建索引。现象是服务能启动检索也能返回结果但答非所问的比例明显上升原因是查询用了新模型编码索引里还是旧模型的向量两个向量空间不对齐解决是 embedding 模型和索引版本绑定换模型必须全量重建并在索引元数据里记录模型标识。这个坑隐蔽因为接口不报错只是效果变差排查时先看索引构建时间和模型加载时间是否对得上。5.2 生成与部署的三个坑显存、超时、引用幻觉坑四vLLM 启动直接 OOM。现象是日志里出现显存分配失败服务没起来原因是max-model-len设得太大KV cache 预留超过可用显存或者gpu-memory-utilization设到 0.98 没给系统留空间解决是把max-model-len从 8192 降到 4096gpu-memory-utilization降到 0.85 到 0.90再按实际 Prompt 长度逐步往上试。不要一次性把上下文拉满先让服务跑起来再用长 Prompt 压测。坑五前端等 60 秒超时后端其实还在生成。现象是浏览器报超时服务日志显示请求还在跑原因是同步生成且max_tokens太大检索片段又长首 token 时间被拖长解决是改成流式输出限制max_tokens接口层设 30 到 60 秒超时超时后主动断开。流式不是前端体验问题它能让用户更早看到内容也能让后端更早释放连接。坑六回答里出现不存在的引用编号。现象是答案末尾写[5]但这次只给了 3 个片段原因是 Prompt 没有限制编号范围模型把历史对话或训练语料里的编号习惯带出来解决是固定片段编号系统提示写明“只能引用 [1] 到 [N]”返回前做一次正则校验把越界编号删掉或改成“未标注”。下面这个校验函数可以直接放在/ask返回前。import re def check_refs(answer, max_ref): # 找出所有 [数字]越界的替换为“未标注” def repl(m): n int(m.group(1)) return m.group(0) if 1 n max_ref else [未标注] return re.sub(r\[(\d)\], repl, answer)这个函数做的是引用编号兜底max_ref是本次传入的片段数正则只匹配方括号里的数字越界就替换。它不能保证模型引用的内容一定正确但能拦住最明显的编号幻觉。更严的做法是把每个片段的编号和来源映射传给前端前端点击引用时反查原文发现对不上就提示“引用待核对”。本地知识库问答不怕说不知道怕的是一本正经地编出处。6. 用 30 条问题验收DeepSeek 本地知识库上线前该盯哪两个指标上线前不要只看“回答像不像人话”要拿 30 条问题做一次小回归。问题集覆盖四类事实型年假几天、跨文档型报销和采购审批谁先、否定型文档里没写的制度、时效型新旧版本冲突。每条问题人工标好标准答案和应该命中的片段跑完记录两个指标召回命中率和回答忠实度。召回命中率看前 5 个片段里有没有标准片段回答忠实度看答案里的关键结论是否都能在片段里找到依据。两个指标分开看才能判断是检索问题还是生成问题。指标计算方式建议通过线不达标先查召回命中率命中标准片段的问题数 / 3080% 以上切分、embedding、索引版本回答忠实度无编造结论的问题数 / 3090% 以上Prompt 约束、引用校验平均首 token 时间从请求到首个字符3 秒以内显存、并发、max_tokens平均总耗时完整回答返回15 秒以内检索条数、生成长度我一般会先把 30 条问题跑三遍再把没命中的问题反查到 chunk别急着换模型。十次里有八次是切分把答案切没了或者索引还是旧 embedding 建的。这个方案值不值得做看的是你能不能接受“先检索再回答”的工程复杂度如果文档量少、更新慢直接做全文摘要也能凑合但只要涉及权限、引用和更新本地知识库这条链路就绕不开。希望帮到你。本文还有配套的精品资源点击获取