architecture
核对日期：2026-05-13。
1. 架构目标
本系统优先保证：
- 基于授权证据回答。
- 文档过期或冲突时可解释。
- 不泄漏未授权内容。
- 每次回答可追踪、可评测、可复盘。
- 后续可以平滑加入企业 IM、SSO 和真实知识库。
1.1 当前最小 demo 边界
本示例目录已包含一个本地可运行 demo：
data/knowledge-base/*.md
-> src/rag-demo.mjs
-> src/eval-runner.mjs
当前 demo 已实现：
- 合成 Markdown 文档和 metadata 加载。
- 用户 scope 权限过滤。
- 关键词/BM25 风格检索。
- 文档版本和冲突的规则处理。
- 安全拒答和写操作拒绝。
- 带引用回答。
- JSONL eval runner。
当前 demo 刻意不包含：
- 真实 embedding、向量数据库和 rerank。
- 真实 LLM 和模型网关。
- 企业 SSO 和真实权限系统。
- 线上 trace、成本和反馈表。
这些能力应按阶段 07/08/10/11/12 的课程要求逐步替换最小实现。
2. 总体架构
3. 模块职责
| 模块 | 职责 | 关键输入 | 关键输出 | 失败处理 |
|---|---|---|---|---|
| UI | 收集问题、展示引用和反馈 | 用户问题 | answer request | 空输入、超长输入提示 |
| Auth | 用户身份和文档权限 | user id、department | permission scope | 无权限拒绝 |
| Guard | 注入和敏感输入检测 | raw query | safe query / reject | 高风险请求拒答 |
| Query Rewrite | 提取意图、改写检索词 | safe query | rewritten query | 保留原问题用于审计 |
| Hybrid Search | 文档召回 | query、scope | candidate chunks | 空召回进入拒答 |
| Filter | 权限、版本、生效日期过滤 | chunks、user scope | authorized chunks | 过滤后为空则拒答 |
| Rerank | 相关性排序 | query、chunks | top evidence | 低置信度进入澄清 |
| Context Builder | 构造证据包和约束 | evidence、policy | model messages | 超长裁剪并记录 |
| Model Gateway | 模型调用和 fallback | messages | raw output | 超时、重试、降级 |
| Parser | 结构化解析 | raw output | answer object | schema 失败重试 |
| Citation Check | 验证引用和证据 | answer、evidence | final answer | 缺引用则拒绝发布 |
| Trace | 记录执行链路 | events | trace id | 脱敏和采样 |
4. 数据模型
文档 metadata
| 字段 | 示例 | 说明 |
|---|---|---|
| doc_id | hr-onboarding-2026 | 文档唯一 ID |
| title | 新员工入职流程 | 文档标题 |
| owner | HR Ops | 文档负责人 |
| department_scope | all / rd | 可见范围 |
| version | v3.2 | 文档版本 |
| effective_from | 2026-01-01 | 生效日期 |
| updated_at | 2026-04-20 | 更新时间 |
| sensitivity | public_internal | 数据敏感等级 |
证据包
{
"query": "如何申请开发环境权限？",
"user_scope": ["all", "rd"],
"evidence": [
{
"doc_id": "rd-env-access-2026",
"title": "研发环境权限申请规范",
"chunk_id": "chunk-003",
"text": "申请开发环境权限需要提交工单...",
"version": "v2.1",
"updated_at": "2026-03-18"
}
]
}
5. 控制流
6. 权限模型
| 资源 | 权限来源 | 进入模型前处理 |
|---|---|---|
| 全员制度 | 默认全员可见 | 可进入上下文 |
| 研发流程 | 部门为研发或授权成员 | 过滤后进入上下文 |
| 财务制度 | 全员可见但敏感字段脱敏 | 隐藏审批人私人联系方式 |
| 管理层文档 | 管理角色 | 无权限时不可检索 |
| 安全事件文档 | 安全团队 | 无权限时不可检索 |
关键原则：先权限过滤，再构造 prompt。模型不能看到用户无权访问的 chunk。
7. 回滚和停用
- 关闭入口：隐藏 Web/IM 问答入口。
- 降级：只返回搜索结果，不生成答案。
- 回滚 Prompt：按
prompts/prompt-version-log.md回退。 - 回滚索引：切换到上一版文档索引。
- 停用高风险文档源：临时下线某部门知识库。