RAG
RAG（Retrieval-Augmented Generation）让模型在回答前先检索外部资料，例如文档、知识库或网页内容。当效果不对时，问题往往不是模型“太笨”，而是上下文没有被正确提取、索引或注入。
本页整理最常见的 RAG 问题与处理方式。
按场景推荐的基础设置
RAG 的效果高度依赖模型能力与上下文预算。默认值偏保守，适合“到处都能跑”，但未必适合你的生产环境。
本地小上下文模型（≤ 8K）
适合 Ollama 等本地模型：
| 设置 | 建议值 | 原因 |
|---|---|---|
| Text Splitter | token | 用 token 控制 chunk 更稳定 |
| Markdown Header Splitting | 开 | 尽量保留结构 |
| Chunk Size | 1000 | 更适合小上下文窗口 |
| Chunk Overlap | 100 | 常规重叠 |
| Top K | 3–5 | 避免一次塞太多内容 |
| Full Context Mode | 关 | 通常塞不下整篇 |
云模型 / 大上下文模型（32K+）
| 设置 | 建议值 | 原因 |
|---|---|---|
| Text Splitter | token | 一致的 chunk 控制 |
| Markdown Header Splitting | 开 | 保留结构 |
| Chunk Size | 2000 | 每次检索保留更多上下文 |
| Chunk Overlap | 200 | 降低截断句子风险 |
| Top K | 15–25 | 大上下文可以承受更多命中 |
| Full Context Mode | 小文档可考虑 | 对中小文档常常更直接有效 |
混合环境（本地 + 云 ）
如果你同时使用本地和云模型，建议先采用折中设置，再按模型覆盖：
| 设置 | 建议值 |
|---|---|
| Chunk Size | 1500 |
| Chunk Overlap | 200 |
| Top K | 10 |
Embedding 模型建议
| 场景 | 建议 | 原因 |
|---|---|---|
| 单用户 / 快速上手 | all-MiniLM-L6-v2 | 默认可本地运行 |
| 多用户且有 Ollama | nomic-embed-text | 可把 embedding 压力转给 Ollama |
| 生产环境且有预算 | text-embedding-3-small | 性价比较高 |
| 自托管 / 无外网 | nomic-embed-text 或 mxbai-embed-large | 不依赖外部 API |
更换 embedding 模型后，记 得重建已有文档索引。
常见问题
0. 组织迁移后检索结果错乱或缺文档
如果启用了组织，检索问题有时其实是资源归属同步问题，而不是 embedding 质量问题。
处理方式：
- 检查当前组织的文件和文档状态
- 修复 pending 的 file / vector ownership repair
- 如果用了 Qdrant 等外部向量库，先完成 tenant metadata 迁移
- 遇到组织拆分、迁移或大规模 rollout 后，优先参照 组织维护
1. 模型“看不到”你的内容
最常见根因是内容提取阶段就出了问题。
处理方式：
- 打开 Admin Settings > Documents
- 检查当前 content extraction engine
- 尝试预览抽取后的文本，看是否为空或明显缺段
- 必要时改用 Apache Tika、Docling 或更适合你文档类型的提取器
2. 只用到了文档的一小部分
默认配置会尽量兼容小上下文模型，因此会很积极地裁剪检索结果。
处理方式：
- 在 Admin Settings > Documents 中：
- 启用 Bypass Embedding and Retrieval
- 或启用 Full Context Mode
如果模型本身上下文不够大，即使启用了 Full Context，也仍然可能被上游模型端截断。
3. Token 上限太小
很多本地模型默认只有 2048 token，上网页或长文档时很快就不够。
处理方式：
- 对 Ollama / 本地模型，提高模型上下文长度
- 对云模型，确认你用的是上下文更大的型号
- 做 web search / 长文档时，尽量使用 8K 以上、最好 16K 以上的上下文窗口
4. Embedding 模型质量差或不匹配
embedding 质量差，RAG 就会在“检错内容”这一步直接失败。
处理方式：
- 切换到质量更好的 embedding 模型
- 然后重建索引
5. NoneType has no attribute encode
这通常表示 embedding 模型未正确配置或不可达。
处理方式：
- 到 Admin Settings > Documents > Embedding Model
- 重新保存一次 embedding 配置
- 如果是远程 embedding 服务，确认服务真的在线且 OPL 数据空间能访问到
5. 400: NoneType object has no attribute encode
这类报错通常就是上一节提到的 embedding 配置缺失或失效。排查时优先重新保存 embedding model，并确认远端服务可达。
6. 上传限制与限制差异
需要注意聊天上传、Folder 上传和 Knowledge Base 上传的限制并不完全一样：
- 聊天上传受
RAG_FILE_MAX_SIZE/RAG_FILE_MAX_COUNT/RAG_ALLOWED_FILE_EXTENSIONS控制 - Folder 上传受
FOLDER_MAX_FILE_COUNT控制 - Knowledge Base 上传通常不受
RAG_FILE_MAX_COUNT限制
7. Chunk 过碎
Markdown Header Splitter 有时会把文档切得过细，导致语义不足。
处理方式：
- 增大 Chunk Min Size Target
- 常见做法是设成
1000或CHUNK_SIZE的 50% 到 60%
8. 后续追问越来越慢
这通常是 KV cache 被频繁打失效了。
处理方式：
RAG_SYSTEM_CONTEXT=True这样 RAG 上下文会进入 system message，而不是不断插到 user message 中，更利于模型或云服务做 prefix cache / prompt cache。
10. CUDA 内存不足
如果 embedding 或 reranking 过程中出现 CUDA OOM，优先考虑：
- 改用更小的 embedding 模型
- 把 embedding 挪到 CPU 或外部服务
- 降低并发与批量处理规模
12. 文档上传时 worker 崩溃
如果上传文档时 worker 直接退出，通常要优先检查：
- 是否在多 worker / 多副本下仍使用本地 SQLite-backed Chroma
- 是否应切到外部向量库或 Chroma HTTP 模式
这类问题通常和 多副本排障 中的向量库限制一起出现。
13. 模型绑定的知识库不生效
如果你把知识库绑定到模型后仍然检索不到内容，优先检查：
- 文档是否完成索引
- 当前组织 / 当前用户是否对该知识库有可见权限
- embedding 模型是否变更后却没有重建索引
| 问题 | 处理方式 |
|---|---|
| 模型看不到内容 | 检查抽取器和抽取结果 |
| 只用了部分内容 | 开 Full Context 或 Bypass Embedding |
| 上下文不够 | 增大模型上下文或换大上下文模型 |
| 检索不准 | 换更好的 embedding 并重建索引 |
| 文件太多太碎 | 调整上传限制和 Chunk Min Size |