检索增强生成（RAG）
如果你在使用 Ollama，请注意它默认只有 2048 token context length。这会明显限制 RAG 的效果，尤其是网页搜索场景，因为检索到的数据可能根本没被模型用到，或者只处理了很小一部分。
检索增强生成（RAG）是一种通过接入外部上下文来提升聊天能力的技术。 OPL 数据空间可以从本地与远程文档、网页，甚至 YouTube 等多媒体来源中提取内容，并将检索到的文本与预定义 RAG 模板组合后注入到用户提示词前面，让模型基于更具体的上下文回答问题。
本地与远程 RAG
本地文档通常需要先上传到 Workspace 的文档区域，然后你可以在提示词前使用 # 引用它们。选中后，聊天框上方会出现格式化 URL，发送按钮上方也会出现文档图标，表示引用成功。
如果你需要清理大量上传文件或审计存储，可以使用 设置 > Data Controls > Manage Files 下的集中式 File Manager。在那里删除文件时，对应的 RAG embedding 也会一起清理。
你也可以在提示词开头使用 # 加 URL 的方式，把网页内容直接引入会话。
为 RAG 使用网页搜索
Ollama 用户的上下文长度提醒： 普通网页在抽取正文后仍常有 4000 到 8000+ token，如果你的模型只有 2048 token 上下文，往往连半页内容都塞 不下。即使 4096 token，对复杂网页也经常不够。
解决方法： 打开 管理员面板 > Models > 设置（针对你的 Ollama 模型）→ Advanced Parameters，把上下文长度提高到 8192+，最好超过 16000。对于 OpenAI 等其他 provider，则请直接选择上下文足够大的模型。
要把网页内容纳入 RAG，可在聊天中用 # 加目标 URL。 OPL 数据空间会抓取并解析可访问的页面内容。
普通网页经常包含导航、页脚、广告等杂质。若要更好效果，优先引用 raw 页面或阅读模式更友好的页面。
RAG 模板自定义
你可以在 管理员面板 > 设置 > Documents 中自定义 RAG 模板。
Markdown 标题切分
启用后，文档会先按 Markdown 标题（H1-H6）分段，再继续走普通字符或 token 切分逻辑。这样更有利于保留结构语义。
在 管理员面板 > 设置 > Documents 中配合 Chunk Min Size Target 使用，可以在标题切分后智能合并太小的段落，改善检索一致性，同时减少向量数量。
Chunk 配置
OPL 数据空间允许你精细控制文档如何被切成 embedding chunk：
- Chunk Size：每个 chunk 的最大字符数或 token 数
- Chunk Overlap：相邻 chunk 间共享的内容量
- Chunk Min Size Target：用于把过小片段与相邻片段智能合并
为什么要设置 Chunk Min Size Target？
合理合并小段落有几个好处：
- 提升 RAG 质量：避免出现没有语义信息的小碎片
- 降低向量库体积：更少 chunk 意味着更少向量
- 加速检索与 embedding：更小索引意味着更快搜索、更少 embedding 调用
- 整体效率更高：在一些测试里，配置得当时可以显著减少 chunk 数，同时提高检索准确率
RAG Embedding 支持
可以在 管理员面板 > 设置 > Documents 中切换 RAG embedding 模型。当前常见支持包括 Ollama 和 OpenAI 类模型。
修改 RAG 设置后的影响
如果你已经建立过索引，再去修改 chunk 配置或 embedding 模型，需要注意影响范围。
修改 Chunk Size / Overlap
- 新上传文档 会自动使用新配置
- 已有知识库文档 仍保留原来的切分方式，直到你手动 re-index
- 不 re-index 也能继续检索，但不同批次文档的检索质量可能不一致
如果你只是调整 chunk 配置，而没有更换 embedding 模型，技术上可以不立刻 re-index；不过若希望所有文档检索表现一致，仍建议重建索引。
修改 Embedding 模型
更换 embedding 模型后，必须 re-index 所有知识库文档。不同模型生成的 embedding 位于不同向量空间，不兼容。
在 管理员面板 > 设置 > Documents 中修改 embedding 模型后，点击 Reindex 即可用新模型重新嵌入知识库内容。
Re-index 会做什么？
对每个知识库，re-index 会：
- 删除 现有向量集合
- 按当前 chunk 设置重新切分文件
- 按当前 embedding 模型重新嵌入全部 chunk
Re-index 只处理知识库文件。那些直接上传到聊天中的文件，有自己独立的向量集合，不会被 re-index 触及。
如果你更换 embedding 模型，这些聊天附件只能通过重新上传来更新 embedding。
总结
| 变更 | 新文档 | 知识库文档（不 re-index） | 知识库文档（re-index 后） | 独立聊天文件 |
|---|---|---|---|---|
| Chunk Size / Overlap | ✅ 使用新配置 | ⚠️ 旧 chunk 继续可用，但质量可能不一致 | ✅ 重新切分 | ⚠️ 需要重新上传才更新 |
| Embedding Model | ✅ 使用新模型 | ❌ 旧 embedding 不兼容 | ✅ 重新嵌入 | ❌ 需重新上传 |
RAG 引用（Citations）
RAG 功能支持为注入到模型中的文档上下文附加引用信息，便于追踪答案来源，提高透明度和可验证性。
File Context 与 Builtin Tools 的区别
OPL 数据空间通过两组独立能力控制文件如何参与模型推理：
File Context Capability
File Context 决定 OPL 数据空间是否对附件执行传统 RAG。
| File Context | 行为 |
|---|---|
| ✅ 启用 | 附件会被处理、检索并注入上下文 |
| ❌ 禁用 | 不做内容提取，不做注入，模型收不到文件内容 |
适合关闭 File Context 的情况：
- 你想彻底绕开 RAG
- 你想只靠内建工具按需检索
- 你在排查 RAG 处理链路问题
当 File Context 被关闭时， OPL 数据空间不会自动把文件内容提取后塞给模型。此时模型若想访问文件内容，只能依赖内建工具按需查询知识库或文件。
单个文件或知识库也可以通过 Using Entire Document 开关绕过 RAG，直接把整篇文档注入到每次消息中。详见 Full Context vs Focused Retrieval。
Builtin Tools Capability
Builtin Tools 决定模型是否会收到原生函数调用工具，例如 query_knowledge_bases、view_knowledge_file、search_chats 等。
| Builtin Tools | 行为 |
|---|---|
| ✅ 启用 | Native Mode 下模型可自主调用知识库和搜索类工具 |
| ❌ 禁用 | 不注入这些工具，模型只能依赖预先注入的上下文 |
两者如何组合
| File Context | Builtin Tools | 结果 |
|---|---|---|
| ✅ | ✅ | 完整 Agentic 模式：自动注入 RAG 内容，同时模型还能主动检索 |
| ✅ | ❌ | 传统 RAG：内容预先注入，没有自主工具 |
| ❌ | ✅ | 仅工具模式：不预注入内容，模型按需查询 |
| ❌ | ❌ | 完全无文件处理：附件会被忽略 |
增强版 RAG Pipeline
OPL 数据空间的增强 RAG 支持可切换 hybrid search，可结合 BM25、CrossEncoder rerank 和相关性阈值，为你的场景提供更精细的检索效果。
KV Cache 优化 🚀
如果你经常在长文档上连续追问，可以启用 KV Cache Optimization 来显著改善响应速度。
问题：缓存失效
默认情况下， OPL 数据空间会 把检索到的 RAG 内容注入到用户消息里。随着对话变长，这段内容在上下文中的位置会不断变化，许多推理引擎因此无法稳定命中 KV cache / Prompt cache，导致每轮都要重新处理大段上下文。
解决方案：RAG_SYSTEM_CONTEXT
设置 RAG_SYSTEM_CONTEXT=True 后，RAG 内容会被注入到system message 中，而不是用户消息里。因为 system message 始终位于提示词最前面，它的位置不会变化，更利于 provider 或本地引擎稳定复用缓存。
如果你经常在 Ollama、llama.cpp、OpenAI 或 Vertex AI 上“与文档持续对话”，建议启用 RAG_SYSTEM_CONTEXT=True，后续追问的速度提升通常会非常明显。
YouTube RAG
OPL 数据空间支持通过 YouTube 视频 URL 走专门的 RAG 管道，对视频字幕或转录内容做总结和检索，让视频也能作为聊天上下文的一部分。
文档解析
本地和远程文档会通过多种 parser 被解析。更底层的加载逻辑可参阅 get_loader。
在 Temporary Chat 中，为了保证数据不落到服务端，文档处理会尽量限制在前端完成。因此某些依赖后端高级解析器的格式（如复杂 DOCX）可能只能显示原始内容，而不是完整解析结果。要获得完整文档支持，请使用普通聊天。
Google Drive 集成
如果你已经在 Google Cloud 项目中启用了 Google Picker API 和 Google Drive API， OPL 数据空间可以让用户直接在聊天界面访问自己的 Drive 文件，并把文档、Slides、Sheets 等内容作为上下文上传到聊天中。它可在 管理员面板 > 设置 > Documents 中启用，并需要配置 GOOGLE_DRIVE_API_KEY 与 GOOGLE_DRIVE_CLIENT_ID。