rag-platform

KO | EN

gitlite — search

#javascript #typescript #golang #go #linux #docker #nodejs #macos #java #kubernetes #awesome-list #pytorch #ios #open-source

(★ 12)

Enterprise multi-source RAG platform with multimodal embedding, hybrid vector/BM25 retrieval, MCP & RBAC support

rag-platform Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# rag-platform

> 企业知识库 RAG 平台：多源接入 → 清洗 → 多模态向量化 → 混合检索（向量 + BM25 + RRF），支持 MCP 与基于角色的权限过滤。
>
> 本项目由 [`dgr_yuque_qrant`](https://github.com/Today-Hbw/dgr_yuque_qrant) 重构演进而来。

`rag-platform` 把「数据源接入 → 内容清洗 → 多模态向量化入库 → 在线混合检索」拆成边界清晰的模块：数据源通过可插拔的 connector 接入（首个实现为语雀，可扩展 Confluence / Notion / 本地文件等），检索侧提供向量 + BM25 + 标题的 RRF 混合排序、Redis 缓存、基于角色的权限过滤（RBAC），并以 FastAPI 服务和 MCP 客户端两种方式对外提供能力。

## 架构

monorepo + [uv](https://docs.astral.sh/uv/) workspace，按**部署单元**拆分为 4 个包：

| 包 | 职责 | 独立部署 |
|----|------|:---:|
| [`rag-core`](packages/rag-core) | 共享底座：配置、DB、embedding、向量库、清洗/分块、契约、RBAC 数据层 | 否 |
| [`rag-pipeline`](packages/rag-pipeline) | 离线批处理：connector + 下载 / 清洗 / 向量化 | 是（离线面） |
| [`rag-search`](packages/rag-search) | 在线检索服务：FastAPI + 混合检索 + 缓存 + RBAC 过滤 | 是（在线面） |
| [`rag-mcp`](packages/rag-mcp) | MCP 客户端（HTTP 调 rag-search，零 core 依赖） | 是 |

`pipeline`（离线）与 `search`（在线）可部署在不同服务器：仓库合一是为共享 embedding client 与向量 payload 契约（入库端与查询端必须一致，否则检索静默失效），部署分离靠分包镜像。

```
数据源 ──connector──▶ rag-pipeline (下载/清洗/向量化) ──▶ MySQL(元数据) + Qdrant(向量)
                                                              │
用户 ──▶ rag-mcp / web 后端 ──▶ rag-search (混合检索 + RBAC 过滤) ─┘
```

## 状态

**阶段 0–7 的代码 / CI / 镜像全部落地**：全量 291 单测绿，CI 与 Docker 工作流均通过，三镜像自动构建并推送到 GHCR。剩余为需真实环境 / 后端配合 / 人工执行的事项，见下「[上线前待办](#上线前待办)」。

| 阶段 | 内容 | 状态 |
|------|------|------|
| 0 | 密钥止血（gitignore / gitleaks / 轮换清单） | ✅ 配置就绪（凭据轮换待执行） |
| 1 | monorepo 骨架 + uv workspace + 4 包 | ✅ |
| 2 | 抽 rag-core（settings/db/repository/embedding/vectorstore/cleaning…） | ✅（等价对拍待内网） |
| 3 | 测试 + CI（paths-filter + 4 包 matrix + ruff/mypy/coverage + gitleaks） | ✅ CI 绿（291 单测） |
| 4 | connector 多源抽象（yuque + local stub + `rag-pipeline sync`） | ✅（等价对拍待内网） |
| 5 | RBAC 权限过滤（P1 两跳 + introspection + 公共库 + rag-mcp login） | ✅ 代码（业务侧接口 / 灰度待接） |
| 6 | 检索评估 eval（metrics/runner/compare/harvest，`python -m eval`） | ✅ 框架（真实 run / golden 待内网 / 人工） |
| 7 | Docker 分包 + 定时调度（Dockerfile×3 + docker.yml + lock + systemd/compose） | ✅ 镜像已推 GHCR（定时上机 / 告警待部署环境） |

## 快速开始

```bash
uv sync --all-extras --dev          # 安装 workspace 全部依赖
cp .env.example .env                # 填入真实配置（密钥不入库）
```

### 离线：同步数据 → 向量入库（rag-pipeline）

```bash
rag-pipeline sync --source yuque [--scope <库>] [--full] [--date YYYYMMDD] [--dry-run]
rag-pipeline clean                  # downloaded → cleaned
rag-pipeline vectorize [--recreate] # cleaned → imported（--recreate 重建 collection，慎用）
```

`--dry-run` 只报告将抓 / 将删，不写盘不改 DB；新增数据源只需实现一个 connector，下游编排零改动。

### 在线：启动检索服务（rag-search）

```bash
rag-search serve [--host 0.0.0.0] [--port 8090]
```

端点：`POST /search`、`POST /image`、`POST /multimodal`、`GET /health`。

### MCP 客户端（rag-mcp）

```bash
rag-mcp login --login-url <业务登录接口>   # 带外换 token，存本地（不经模型）
rag-mcp -s http://<search-host>:8090        # 启动 MCP stdio server
```

### 检索评估（eval）

顶层 `eval/` 工具包，锚定 `doc_id` 做 @k 指标评估（hit_rate/recall/precision/mrr/ndcg）。

```bash
python -m eval harvest --logs-dir <data_root>/logs --out eval/datasets/candidates.jsonl  # 从日志 pooling 候选
python -m eval run     --dataset eval/datasets/smoke.jsonl --out runs/baseline.json        # 跑评估（需内网）
python -m eval compare --before runs/baseline.json --after runs/tuned.json --fail-on-regress
```

数据集标注与快照约定见 [`eval/datasets/README.md`](eval/datasets/README.md)。

### 部署（Docker + 定时调度）

- 每个可部署包一个 Dockerfile（[pipeline](packages/rag-pipeline/Dockerfile) / [search](packages/rag-search/Dockerfile) / [mcp](packages/rag-mcp/Dockerfile)），多阶段 uv 构建、`--no-editable` 使镜像只含自己 + 依赖闭包。
- [`deploy/docker-compose.yml`](deploy/docker-compose.yml)：search 常驻 + qdrant/redis 内置 + pipeline 按 profile 触发；密钥走 `--env-file`。
- 定时增量同步：[`deploy/systemd/`](deploy/systemd)（timer `Persistent=true` 补跑 + `OnFailure` 告警）或 [`deploy/cron/`](deploy/cron)；入口 [`deploy/scripts/rag-sync.sh`](deploy/scripts/rag-sync.sh)。
- 并发锁 `RAG_PIPELINE__LOCK_BACKEND`：`file`（单主机，默认）/ `redis` / `mysql`（多主机）/ `none`——**改配置即可，不改代码**。
- CI 镜像构建/推送见 [`.github/workflows/docker.yml`](.github/workflows/docker.yml)：push 到 main 时自动构建并推送到 **GHCR**（`ghcr.io/today-hbw/rag-{pipeline,search,mcp}`），用内置 `GITHUB_TOKEN`，无需额外配置。服务器 `docker login ghcr.io`（PAT 带 `read:packages`）后 `docker compose pull` 即可。

## 权限过滤（RBAC，P1）

默认**全关**（`RAG_RBAC__ENABLED=false` = 旧行为，全量可见）；开启后按角色过滤检索结果。

**颗粒度**：知识库（collection）级 + 文档（doc）级例外 + 公共库人人可见；超管（`allow_all`）不过滤。

**两跳解析（均带缓存）**：

```
调用方带 Authorization: Bearer <user token>
  ① token → role_ids   : rag-search 调业务 introspection 接口（可配 URL）      [业务侧]
  ② role_ids → 资源     : 查本地 system_role_permission → collection/doc 集     [RAG 侧]
  ③ 可见集 = 资源 ∪ 公共库(rag_collection.is_public)；allow_all → 不过滤
  ④ Qdrant filter: should=[collection_id MatchAny, doc_id MatchAny]
```

**introspection 接口契约**（业务侧按此实现）：

```
POST <RAG_RBAC__INTROSPECT_URL>   头 Authorization: Bearer <token>（+ 可选 X-Service-Token）
→ 200 {"valid": true, "role_ids": [12,34], "allow_all": false}
  无效 token → HTTP 401 或 {"valid": false}
```

- **离线 / 调试模式**：`INTROSPECT_URL` 为空（默认）→ 不调远程，直接信 `X-Role-Ids` 头（逗号分隔）；`RAG_RBAC__DEFAULT_ROLE_IDS` 可给静态默认角色。**生产配 URL，离线留空，切换只改配置。**
- **服务令牌**（可选第二道）：`RAG_RBAC__SERVICE_TOKEN` 常量时间比对，挡内网直连；调用方置于 `X-Service-Token` 头（与用户 token 的 `Authorization` 头分开）。
- **身份铁律**：token 走传输层，**绝不做成 MCP 工具参数**；登录换 token 走带外（`rag-mcp login`，验证码用 `getpass` 收），不经模型。缓存 key 叠加权限签名，杜绝不同权限用户串缓存。

数据表：`system_role_permission`（角色→资源，`resource_id = book:<collection_id> / doc:<doc_id> / *`）、`rag_collection`（库属性，`is_public=1` 人人可见）。schema 见 [`deploy/migrations/`](deploy/migrations)。

## 上线前待办

代码已就绪，以下为真实环境 / 后端 / 人工事项：

- **凭据轮换（最高优先）**：旧仓明文密钥已泄漏，须全部轮换后填入本地 `.env`（清单见 [`deploy/CREDENTIAL_ROTATION.md`](deploy/CREDENTIAL_ROTATION.md)），并建最小权限 MySQL 应用账号替代 root。
- **业务侧 RBAC 接口**：实现 introspection 接口（契约见上）+ nginx 服务令牌校验 + `system_role_permission`（角色→资源）的维护入口。**未实现前 RBAC 只能停在离线模式（直接信 `X-Role-Ids` 头），不可用于生产。**
- **旧库→新库数据迁移**：[`deploy/migrations/0002_migrate_from_legacy.sql`](deploy/migrations) 为草案，涉线上数据 + `team_code` 历史错值，**须先备份 DB 再人工执行**。
- **内网验证**：新 `sync` 与旧 pipeline 的等价对拍、RBAC 灰度、eval 首个真实 run + golden 标注。
- **部署**：定时任务上机（systemd/cron）、失败告警接真实 webhook、GHCR 镜像拉取（`docker login` 或改 public）。

> ⚠️ 数据一致性铁律：**入库端与查询端必须用同一 embedding 模型 / 维度 / payload 字段**，否则检索静默失效（不报错，结果错）。eval 须打在**冻结的快照 collection** 上。

## 配置

全部走环境变量（`RAG_` 前缀 + `__` 分隔嵌套，密钥用 `SecretStr`），见 [`.env.example`](.env.example)。**密钥不入库**（`.gitignore` + gitleaks 双保险）。rag-mcp 为独立客户端，用自己的 `RAG_MCP_*` 进程环境变量（不读本 `.env`）。

## 开发

```bash
uv run ruff check .           # lint
uv run pytest                 # 全量单测（离线，:memory: Qdrant / respx / fakeredis / mock MySQL）
```

rag-platform

rag-platform Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

rag-platform

rag-platform Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README