cb75b9b274
多库检索与存储修复: - RRF 融合去重改用 (collection, chunk_id) 复合键，修复同名文件结果被吞 - DocStore 存储路径加 collection 前缀，修复跨库同名切片数据覆盖 - search_multiple 去重改用复合键 - chunk_id 解析改用 rsplit 兼容下划线文件名 上传与版本管理修复: - 同名文件上传改为覆盖模式，自动清理旧切片 - 修复首次上传不创建版本记录 - 修复覆盖上传版本号回退到 v1 - sync ADDED 分支改用动态版本号生成 - _generate_version_id 改为基于全部版本递增 - 废止/恢复操作同步 SQLite 版本记录 - mark_document_as_superseded 改为仅更新 SQLite 删除清理修复: - 删除文档时同步清理 SQLite 版本记录和变更日志 - 删除向量库时同步清理该库所有版本记录 - cleanup 改为清理 SQLite 记录而非 ChromaDB 测试: - test_version_management.py: 27 条版本管理单元测试 - test_edge_cases.py: 28 条边界用例测试 - test_upload_dedup.py: 5 条上传去重测试 - e2e_risk_test.py: 27 条端到端风险测试 文档: - 新增风险边界问题修复注意事项.md（面向后端的对接文档） - 新增向量库边界风险分析.md - 更新多篇现有文档
71 lines
5.4 KiB
Markdown
71 lines
5.4 KiB
Markdown
# 多向量库实现权限划分详细说明
|
||
|
||
## 1. 架构目标与背景
|
||
本项目早期采用单一Chroma向量库体系，所有文档数据混合存储，并在检索层采用软性过滤。为满足企业级数据权限隔离、部门级知识库自治管理的要求，本项目统筹规划重构为「多向量库体系」，将`public_kb`（公共知识库）与`dept_{department}`（部门私有知识库）在 Chroma 中进行物理分隔，实现在数据存储基座维度的鉴权与隔离。
|
||
|
||
## 2. 权限控制策略与角色模型
|
||
系统主要通过 `auth/gateway.py` 与网关注入的 Header 信息配合，进行请求身份的判定与映射。
|
||
|
||
### 2.1 网关注入的用户信息
|
||
API 服务会在接受请求前，解析来自网关传递的 HTTP Header：
|
||
- `X-User-ID`：用户唯一标识符
|
||
- `X-User-Role`：用户角色（admin / manager / user）
|
||
- `X-User-Department`：用户所属部门标识（如：finance, hr, tech 等）
|
||
|
||
### 2.2 角色与集合访问权限规则
|
||
根据系统预设的 `COLLECTION_PERMISSIONS` 规则表，不同类别的用户具有不同层级的读写能力：
|
||
- **Admin（超级管理员）**
|
||
- **Read（跨库查询）**: `*`（所有向量库均可访问检索）
|
||
- **Write / Delete / Sync**: `*` （可进行全局库维护操作）
|
||
- **Manager（部门管理员）**
|
||
- **Read**: `public_kb`, `dept_{自己所在部门}`
|
||
- **Write / Delete / Sync**: 仅限 `dept_{自己所在部门}`
|
||
- **User（普通员工）**
|
||
- **Read**: `public_kb`, `dept_{自己所在部门}`
|
||
- **Write / Delete / Sync**: 无任何写入/修改/删除权限。
|
||
|
||
## 3. 多库混合检索与结果合并
|
||
|
||
将文档隔离为多个不同的库集合后，依然通过以下机制保障检索质量与执行效率：
|
||
|
||
### 3.1 独立BM25缓存与协程并发查询
|
||
- **完全解耦索引**：每个子向量库均配备对应的独立 `BM25.pkl` 关键词索引结构（如 `bm25_index_public.pkl`，`bm25_index_finance.pkl`）。
|
||
- **协程并行加载**：在使用大维度混合查询（比如跨多部门或公共+个人部门）时，知识库引擎通过 `asyncio.gather` 并行向相应的分离集合及BM25文件发起并发读取，整体耗时比单一库顺序扫描具备极大优势（多线程下总耗时稳定在 50~70ms 内）。
|
||
|
||
### 3.2 智能库路由 (`knowledge/router.py`)
|
||
Agentic RAG在正式下发检索前，加入了一层轻量级意图预判节点（Router）：
|
||
- **意图降噪**：大模型/关键词正则检测若发现用户的查询（如："财务部报销规范"）具有极强的部门属性，则缩小检索范围仅查匹配的库。
|
||
- **动态寻址**：过滤掉权限不匹配库的同时，避免去不相干的知识库进行检索从而拉低相似度分值，极大提高了用户问答查询效率。
|
||
|
||
### 3.3 RRF (Reciprocal Rank Fusion) 多库融合重排
|
||
当请求在数个子向量库查得片段后，返回的多路向量由于采用了“同源 Embedding 模型”（例如BGE），其余弦相似度在不同子库的数据集之间是完全等价和客观可比较的。
|
||
最终数据层依靠融合模块汇聚所有库的 Top-K 记录，经过全局倒排算法（RRF）以及多维分数权重融合重排，保证了隔离存储不影响任何语义搜寻与内容关联。
|
||
|
||
## 4. 相关代码路径总结
|
||
|
||
### 4.1 鉴权与路由
|
||
- **`auth/gateway.py`**：主要负责网关鉴权与鉴权路由逻辑。
|
||
- **`knowledge/router.py`**：LLM 智能知识库请求目标路由。
|
||
|
||
### 4.2 knowledge/ 核心模块（Mixin 架构）
|
||
知识库管理器 `KnowledgeBaseManager` 采用 Mixin 组合模式，各职责拆分到独立模块：
|
||
|
||
| 模块 | Mixin 类 | 职责 |
|
||
|------|----------|------|
|
||
| `knowledge/base.py` | — | 配置常量、数据类定义（`CollectionInfo`, `SearchResult`, `BM25Index`）、辅助函数 |
|
||
| `knowledge/manager.py` | `KnowledgeBaseManager` | 主入口，组合所有 Mixin，提供多库并发管理与工厂方法 |
|
||
| `knowledge/collection.py` | `CollectionMixin` | 向量库（ChromaDB Collection）的创建、删除、查询等集合管理功能 |
|
||
| `knowledge/document.py` | `DocumentMixin` | 文档级别的管理方法，包括文档计数、文档列表、文档元信息查询 |
|
||
| `knowledge/search.py` | `SearchMixin` | 多源融合检索：单向量库检索 + BM25 混合检索 + RRF 融合排序 + 多库并行检索 + 废止版本检测 |
|
||
| `knowledge/permission.py` | `PermissionMixin` | 基于角色和部门的向量库访问控制，权限校验（admin / manager / user） |
|
||
| `knowledge/processing.py` | `ProcessingMixin` | 图片/表格的智能处理：图片过滤、VLM 描述生成、表格摘要生成、原始数据存储 |
|
||
| `knowledge/chunk.py` | `ChunkMixin` | 文档切片（Chunk）的 CRUD 操作：新增、修改、删除、分页查询切片 |
|
||
| `knowledge/index.py` | `IndexMixin` | BM25 关键词检索索引的生命周期管理：懒加载、持久化、从向量库重建 |
|
||
| `knowledge/document_versions.py` | `DocumentVersionQuery` | 文档版本历史查询、获取当前生效版本、版本变更日志记录 |
|
||
|
||
### 4.3 辅助服务
|
||
- **`knowledge/sync.py`**：知识库同步服务 — 使用 watchdog 监控文档目录变更，自动检测文件哈希差异并触发增量向量化。
|
||
- **`knowledge/cleanup.py`**：文档版本自动清理 — 定期清理 superseded 状态的旧版本，控制存储成本。
|
||
|
||
### 4.4 离线迁移脚本
|
||
- **`scripts/rebuild_multi_kb.py`**：从单库直接转换为多库分治物理结构的离线迁移脚本。 |