ragflow+deepseek知识库

本地把 RAGFlow 跑起来、把 DeepSeek 的 key 填进去，通常半天就通了；真正卡人的是上线之后那一段——文档一多解析排队、问答一慢就超时、检索回来的段落对不上问题、出了问题日志里什么都查不到。这篇不重复协议兼容和客户端配置，只按工程视角给一份可照着做的落地清单：先定并发与超时口径，再设计降级和兜底，最后把日志和评测补上。

本地把 RAGFlow 跑起来、把 DeepSeek 的 key 填进去，通常半天就能通。真正卡人的是上线之后那一段：文档一多解析就排队，问答一慢就超时，检索回来的段落对不上问题，出了岔子翻日志什么都查不到。这篇不重复协议兼容和客户端配置，只按工程视角给一份能照着做的落地清单。

顺序建议就是四步：先算进料预算，再定并发与超时口径，然后设计降级和兜底，最后把日志和评测补上。每一步都能单独落地，不必等前面全做完才开始下一步。哪一步没做完就上线，后面排查问题的成本会成倍涨。

先算进料预算：解析、切片、向量化各占多少时间

进料这条链路要拆成四段看：解析、切片、嵌入、入库。每段分别记耗时和失败率，才能找出真正拖后腿的那一段。多数人以为慢在嵌入，实际卡在 PDF 解析或扫描件 OCR 上，先量再优化，别凭直觉加机器。

解析

把原始文件转成文本，扫描件和复杂排版最耗时，也最容易失败

切片

按规则把长文切成片段，规则定得越碎，后面的召回越碎

嵌入

调嵌入模型把片段转成向量，外部调用时它常常是并发瓶颈

入库

写向量库与元数据，量大时也要单独观察写入速率

• 大文件与扫描件单独走一条队列，别和普通文本抢同一批并发额度；
• 嵌入模型是外部调用时，单独限制它的并发数，避免入库把整站拖慢；
• 先用小批量样本跑通全链路再放全量文档，观察入库速率随文档量怎么变；
• 给每段设一个失败可重试的标记，失败文件不要静默丢掉，攒成一份待处理清单。

并发与超时：给检索链路定几个明确数字

整条问答链路至少有三步：检索、改写、生成。这三步的耗时量级完全不同，不要共用一个超时值。检索要短，超时就赶紧走降级；改写可以中等；生成本来就慢，得给够时间。先按站内当时的并发限制口径倒推每步能开多少并发，别等接口返 429 了再回头改。

每步的实际耗时都要记下来，形成一份自己的基线。基线会因为文档量、模型负载、网络状况变化，建议固定周期复测一次。如果某天响应突然变慢，有基线在手就能立刻判断是检索变慢还是生成变慢。

降级路径：检索空了、模型挂了、上下文超了怎么办

降级不是可选项，是上线前必须写好的分支。常见的三类异常要分别处理：检索为空、主模型不可用、命中片段过多导致上下文超限。每类都要有明确的触发条件和日志标记，方便事后统计降级比例。降级比例本身就是一个重要指标，突然升高往往意味着上游出问题了。

1. 检索为空直接给出「没找到相关内容」的明确回复，不要让模型自由发挥编答案，同时记录空召回的问题用于后续调切片。
2. 主模型不可用切到备用模型，但切换后回答风格和格式可能变，上线前要专门验证一轮，别等真挂了才发现输出格式对不上。
3. 上下文超限按相关度截断命中片段，而不是全塞进去；被截掉的片段记下来，看是不是切片粒度太粗。

什么情况下这套降级不适用？如果业务对答案准确性要求极高、宁可报错也不接受降级结果，那就把降级开关改成明确的失败提示，而不是切备用模型硬答。判断标准很简单：降级答案错了，用户能不能接受，不能接受就别自动降级。

日志与评测：让「效果变差」这件事可定位

很多人反馈「效果变差了」，但翻日志什么都查不到，因为压根没记够信息。一次问答最少要记这几样：原始问题、命中的片段 ID、送入模型的上下文长度、模型返回内容、各步耗时。有了这些，才能判断是检索没召回到，还是召回了但模型没用上。

• 把用户点踩或明显答错的问题抽成一个固定用例集，改动切片规则或提示词后重跑一遍；
• 检索阶段的命中率和生成阶段的答案质量分开看，才知道该调检索还是调提示词；
• 调整前后各留一份结果对比，别凭感觉判断「好像变好了」；
• 用例集要定期补充新问题，别让它慢慢跟线上实际脱节。

想省事也可以用通用的评测思路，但私有知识库的答案依赖你自己的语料，通用基准参考价值有限。更实际的做法是维护一份几十条的小用例集，每次改动跑一遍，看通过率是涨是跌。这份用例集不需要多完美，关键是稳定、可重复。