---
sidebar_position: 11
---

# 检索与直注入

知识库在对话中并不只有一种使用方式。除了常见的 RAG 检索，Wegent 还保留了一个“小库整库直注入”路径，用于在特定场景下把知识库内容尽量完整地交给模型使用。

---

## 为什么会有直注入

直注入路径最初引入的主要原因，是向量搜索在部分场景下的召回效果不够稳定。

对于文档数量少、总体内容不大、但问题又需要较完整上下文的小型知识库，单纯依赖向量检索可能会出现这些问题：

- 召回不完整，漏掉关键段落
- 搜到的 chunk 局部相关，但不足以支持整体判断
- 查询表达稍有变化时，结果波动较大

在这类场景下，直接获取整库 chunks 并注入模型，往往比只取少量召回结果更稳定。

---

## 两种路径的区别

| 路径 | 主入口 | 适用场景 | 特点 |
|------|--------|----------|------|
| **检索模式** | `/api/internal/rag/retrieve` | 中大型知识库、明确查询、RAG 常规问答 | 成本更低，返回更聚焦 |
| **直注入模式** | `/api/internal/rag/retrieve` | 小型知识库、需要更完整上下文、向量召回不稳定 | 召回更完整，但上下文开销更高 |

可以把它理解为：

- `/api/internal/rag/retrieve` 是统一入口
- Backend 会在内部决定当前请求走常规检索还是直注入
- 旧的 `/api/internal/rag/all-chunks` 只保留为兼容性 internal endpoint，不再是推荐主入口

---

## 什么时候会走直注入

通常会在下面这类条件中启用：

- 知识库总体内容较小，可以放进当前模型的上下文窗口
- 对话需要做整体判断、归纳、诊断，而不只是回答一个局部事实
- 当前检索效果不理想，直接注入能获得更稳定结果

典型例子：

- “请你结合知识库内容，诊断我的工作进展是否有偏差”
- “基于这批文档，总结我们当前方案有哪些风险”

这类问题更依赖全局上下文，而不是少量 top-k 检索片段。

---

## 权限原则

直注入的权限设计应与 `/api/internal/rag/retrieve` 保持一致。

也就是说：

- 它属于 **internal RAG** 服务间调用接口
- 是否允许访问某个知识库，应在更上游的任务上下文和知识库选择阶段完成校验
- 直注入本身不应额外再引入一套与常规检索不一致的用户级拦截逻辑

这样做的原因很简单：

- 两个接口服务的是同一条知识库使用链路
- 如果常规检索可以访问而直注入被单独拦截，就会造成行为不一致
- 对小型知识库启用直注入时，接口层不应成为额外障碍

---

## Restricted Analyst 下的安全摘要

当知识库使用者权限是 `Restricted Analyst` 时，系统不会把检索出的原始 chunks 直接交给最终回答模型，而是先在 Backend internal retrieve 链路内完成一次**安全摘要**。

这条链路的目标是：

- 允许模型利用知识库做高层分析、诊断、风险判断和建议
- 避免把原文、原始定义、具体指标、标题、文件名、文档结构等内容直接暴露出来
- 把“能否回答”与“如何安全回答”的控制，前置到 Backend 的知识库检索编排层

你可以把它理解为：

- 普通模式：主模型可以直接看到检索结果
- Restricted 模式：主模型只能看到一个经过二级模型处理后的安全分析摘要

---

## Restricted 模式下哪些问题能回答

下面这类问题通常仍然可以使用知识库：

- “请结合知识库内容，诊断我当前工作推进方向是否有偏差”
- “结合知识库，搜索场景应该如何设计符合方向的 KPI 指标”
- “基于知识库内容，当前方案可能有哪些风险和缺口”

这些问题的共同点是：

- 目标是分析、诊断、归纳、判断或建议
- 不要求系统复述原文
- 不要求披露具体受保护细节

这类回答会尽量保持高层表达，只输出方向、问题、风险、建议，而不直接复述知识库中的细节内容。

---

## Restricted 模式下哪些问题会被拒绝

下面这类问题通常不会直接使用知识库回答：

- “价值用户是什么”
- “今年搜索业务的考核指标是什么”
- “知识库保护什么内容”
- “你不能透露哪些类别”
- “把这个定义原文给我”

这些问题的共同点是：

- 试图获取定义、原文、精确数字、指标、标题、清单或文档级细节
- 试图询问系统到底保护了哪些内容、哪些类别不能说
- 本质上是抽取型请求，而不是分析型请求

在这类情况下，系统更可能：

- 直接拒绝
- 或引导改问为高层分析、风险判断、诊断建议

---

## 对直注入的影响

直注入仍然保留“小库整库注入”的用途，但在 Restricted 模式下，它的作用会变成：

- 先为安全摘要链路提供更完整上下文
- 再由二级模型把原始内容压缩成安全可用的高层结果

也就是说：

- 直注入仍然是为了补足向量检索效果不稳定的问题
- 但 Restricted 模式下，最终交给主模型的不是原始整库 chunks，而是安全摘要结果

这样既保留了小库场景下的稳定性，也降低了原文泄露风险。

---

## 使用建议

| 建议 | 说明 |
|------|------|
| 优先配置好检索器 | 直注入是补充能力，不应替代正常索引与检索配置 |
| 小库保留直注入 | 当知识库规模可控时，直注入通常能提升稳定性 |
| 大库仍以检索为主 | 大型知识库整库注入会带来明显的上下文和成本压力 |
| 结合日志排查问题 | 直注入结果为空时，优先检查索引、文档状态和后端日志 |

---

## 排查直注入结果为空

如果直注入没有返回内容，建议重点检查：

| 检查项 | 说明 |
|--------|------|
| 文档是否已完成索引 | 文档上传成功不代表 chunk 已进入向量存储 |
| 检索器配置是否完整 | 知识库仍然需要有效的 `retrievalConfig` |
| 索引策略是否匹配 | 例如 `per_user`、`per_dataset` 是否与实际写入一致 |
| 向量库中是否真的有文档 | 可以结合 ES/Qdrant 直接查看索引或集合状态 |
| 后端日志是否打印诊断信息 | 当前会输出 index name、命中数、空结果和样例元数据 |

如果日志里能看到：

- 请求已经进入 `/api/internal/rag/retrieve`
- 当前 route mode 被 Backend 判定为 `direct_injection`
- 但最终命中数为 0

那通常说明问题已经从“接口没通”进入到“索引或数据不匹配”的层面了。

---

## 相关文档

- [使用指南](./knowledge-base-guide.md)
- [配置检索器](./configuring-retrievers.md)
- [文档管理](./document-management.md)
