deepseek+ragflow本地部署+搭建知识库

本地起 RAGFlow 一般不难，难的是接上模型之后知识库答得不对：文档切得太碎、召回空、回答串味。这篇按落地顺序过一遍——部署前先对齐机器与依赖口径，接模型时把接口和密钥填对，入库前先做文档清洗，检索调参有固定排查顺序。适合准备在自有机器上搭私有知识库的开发者。

本地把 RAGFlow 跑起来这件事，大多数人半天就能搞定，真正卡人的是接上模型之后：知识库答得不对，文档切得太碎、召回全是空的、回答开始串味。这篇按落地顺序过一遍，从部署前对齐口径、接模型填接口、入库前做文档清洗，到检索调参的固定排查顺序。适合准备在自有机器上搭私有知识库的开发者，照着往下走就行。

先说一个心法：本地知识库的效果，八成取决于文档怎么切、怎么召回，模型本身反而是最后才需要动的东西。所以别一上来就换模型、调提示词，先从召回往回查。下面每节都给判断标准和可执行动作，数字类的口径一律到站内对应页面按当时的规模测算，别照搬别人的配置。

部署前先对齐三件事：机器、依赖、端口

机器规格差异很大，跟你的模型规模和文档量直接相关。别抄别人博客里的固定档位，去站内页面按自己的实际情况测算一遍再买机器或开容器。磁盘尤其要留够，知识库解析过程会产生中间文件，跑着跑着满了很常见。

• 按官方文档核对当前版本对内存、磁盘和容器引擎的要求，具体档位到 /models/deploy 页面按你的模型规模测算
• 部署方式在 Docker、源码、Windows 与 Linux 之间只选一种，别混着装，各自踩坑点不同
• 提前定好端口与数据挂载目录，容器重建时数据不丢，挂载路径写宿主机绝对路径别写相对路径
• 装完先用自带示例文档跑通一次问答，再换自己的资料；直接上真实文档，出了问题分不清是环境还是数据

选部署方式时，Windows 和 Linux 的坑点不一样，Docker 相对省事但排查问题时层级更深。这块的配置口径先对齐 /ai-nav/category/ai-model-platform 里的平台说明，别自己猜参数含义。

把模型接进来：对话、嵌入、重排分开配

RAGFlow 里对话模型和嵌入模型是两个独立位置，只填一个就以为接好了，是新手最常见的误判。嵌入模型负责把文档和问题变成向量，召回质量基本由它决定；对话模型只负责最后组织语言。两个都配对了，才谈得上效果。

对话模型

负责根据召回片段生成最终回答

嵌入模型

负责把文档和提问转成向量，决定召回质量

重排模型

对召回的候选片段再排序，压掉噪声但解决不了切分问题

Base URL

各家写法不同，拼错通常报 404 而不是明确提示

1. 填接口地址按 OpenAI 兼容格式填 Base URL，注意结尾有没有斜杠、有没有多写版本路径，先按 ragflow-deepseek-integration 的口径核对。
2. 填密钥用最小权限的 key，先在别处单独测一次能通再填进来。
3. 分别配对话和嵌入两个位置都填完，保存后各测一次，确认互不干扰。
4. 量延迟基线用 /tools/speed-test 量一遍延迟，先分清是网络慢还是配置错，再决定要不要换线路。

切换模型或换 key 之后，老知识库的向量维度可能对不上，表现是检索直接报错或召回为空，这时候需要重建索引，不是改改参数能救的。嵌入模型选型可参考站内 embeddings 页面列的可用项。

入库前的文档处理：切分比模型更影响效果

文档清洗这步最容易被跳过，也最影响最终效果。扫描件、纯图 PDF 不做 OCR 直接入库，检索永远召回不到，因为里面根本没有可检索的文字。清洗清单和 OCR 处理流程见 pdf-ocr-doc-cleaning，照着过一遍再入库。

• 切完抽查几段，看有没有把一句话拦腰截断，尤其是列表和条款
• 给每份文档补元信息：来源、分类、时间，后面按条件过滤时用得上
• 纯靠语义相似度容易把过期内容召回上来，元信息过滤能压一层
• 文档更新后要重新解析，只改文件不重跑入库，库里的还是旧内容

切分不是一劳永逸的，文档类型变了就要重新看一遍切片效果。如果你的资料以问答对为主，按对切比按字数切效果好；如果以长说明书为主，就要保留章节层级。

答不准时的排查顺序：从召回往回查

发现答得不对，别第一反应去改提示词。多数情况问题出在召回本身。固定顺序是从召回往回查，每步只动一个变量，这样才分得清是哪一层在拖后腿。

1. 看召回片段本身把命中的片段打出来看。片段就不对，改提示词没用，回去调切分和嵌入模型。
2. 看召回条数与阈值条数太少会漏，太多会稀释。小步调整，每次只动一个参数，改完重跑同一组问题。
3. 再上重排重排能压掉一批噪声片段，但不解决切分本身的问题，做法见 ragflow-deepseek-rag-ops。
4. 检查上下文拼装换流式输出或加缓存时，注意上下文拼装长度，超了丢历史而不是丢检索结果。
5. 最后才动提示词要求回答带片段引用，方便定位是哪一段在带偏。

什么情况下这套顺序不适用？如果你的问题本身就是模型能力不够，比如需要复杂推理而不是检索事实，那召回再准也答不好。这种场景要换思路，别在检索上死磕。

上线前的几件收尾事：日志、评测、成本

上线之前把日志和评测补齐，比多调几个参数更值钱。没有日志，用户反馈答错了你连复现都做不到；没有回归集，改完配置只能凭感觉判断好坏。

• 每次问答把命中的片段 id、耗时、token 用量记下来，出问题能复盘，字段清单参考 api-log-fields-replay
• 固定一组 20 条左右的问题做回归，改完配置重跑一遍看变好还是变差
• 并发高时入库和查询会互相抢资源，把解析任务和查询分开排期
• 成本按实际调用量估，到 /tools/token-price-calculator 按你的文档量和提问频率算一遍
• 密钥和接口地址集中管理，别散落在多个配置文件里，换 key 时容易漏改

日志字段不用多，够复盘就行。关键是能顺着一次答错的记录，看到当时召回了哪些片段、用了哪个模型、耗时多少。这几项齐了，排查效率会差一个量级。