# DocFlow智文通企业级RAG

**Repository Path**: zhang_sinno/docflow

## Basic Information

- **Project Name**: DocFlow智文通企业级RAG
- **Description**: 3级缓存 + Rag增强检索的企业内部知识问答系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-23
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DocFlow 智文通 · 企业级 RAG 智能技术文档问答平台

面向企业级 SaaS 服务商的技术文档问答系统：整合 Confluence / OpenAPI / GitHub / 内部 Wiki / PDF / FAQ
等多源知识，提供带引用的秒级问答，内置意图识别、多策略检索路由、三级缓存、重排与幻觉控制。

内置约 **1000 条模拟问答**（400 条文档问答 + 600 条 FAQ，数据源在 `data/docs`），并提供
一个简洁的对话式前端页面。

![DocFlow 前端预览](docs/ui-preview.png)

## 核心能力

- **多源离线链路**：50 个知识源配置、8 类连接器、按文档类型差异化分块、增量同步与版本失效。
- **在线检索**：意图分类 → Direct / HyDE / SubQuery / Backtrack 四种策略 → 向量 + BM25 混合召回 →
  BGE Reranker 重排 → 上下文预算组装。
- **三级缓存**：Redis（L1）→ MySQL FAQ（L2）→ BM25（L3），按 `doc_id` 建立失效映射。
- **幻觉控制**：Prompt 硬约束、引用编号、事实句支撑校验、编造版本号/API 路径检测、无依据降级。
- **流式输出**：WebSocket `start / delta / citation / end / error` 协议，首 token 与总耗时埋点。
- **内置前端**：原生 HTML/CSS/JS 聊天页，流式回答、引用卡片、缓存/策略徽标、深浅色主题。
- **评估与运维**：本地离线指标 + RAGAS 可选适配、评估基线、索引重建与增量同步脚本。

## 验收目标

| 指标 | 目标 |
| --- | --- |
| 问答准确率 | ≥ 94% |
| RAGAS Faithfulness | ≥ 0.93 |
| RAGAS Context Precision | ≥ 0.91 |
| 三级缓存命中率 | ≥ 45%（L1 15% / L2 20% / L3 10%） |
| 平均解答时间 | ≤ 8 分钟（人工口径）/ 秒级（系统口径） |
| 支撑规模 | 日均 800+ 查询，峰值并发约 150 |

> 当前离线环境的实测基线见 [docs/eval-baseline.md](docs/eval-baseline.md)，生产口径需在
> BGE-M3 + BGE Reranker + LLM 环境复测。

## 系统架构

```text
用户提问 (REST / WebSocket)
        │
        ├─ 三级缓存: Redis L1 → MySQL FAQ L2 → BM25 L3
        │     命中 → 直接返回（含引用/层级/耗时）
        │
        └─ 未命中
             ├─ 意图识别（LLM，规则兜底）
             ├─ 策略路由: Direct / HyDE / SubQuery / Backtrack
             ├─ 混合召回: Milvus 向量 + BM25 全文（加权融合、去重）
             ├─ Rerank: BGE Reranker（失败降级按召回分）
             ├─ 上下文组装: token 预算 + 引用编号
             ├─ LLM 生成（仅基于上下文，流式）
             └─ 引用一致性校验 → 降级/回写缓存
```

离线链路：

```text
sources.yaml → 连接器 → 解析(Markdown/OpenAPI/HTML/PDF/FAQ)
→ 差异化分块 → BGE-M3 向量化 → Milvus + BM25 + MySQL FAQ
→ 版本/增量状态（content_hash）→ 缓存失效
```

## 技术栈

| 层次 | 选型 |
| --- | --- |
| 语言 | Python 3.12 |
| 文档解析 | pypdf / BeautifulSoup / OpenAPI（MinerU 的轻量平替） |
| RAG 框架 | LangChain 1.x |
| 向量库 | Milvus 2.4.4（pymilvus 3.x） |
| Embedding | BGE-M3（sentence-transformers，维度 1024） |
| LLM | DeepSeek / Qwen（OpenAI 兼容协议，统一封装层） |
| Web 服务 | FastAPI + Uvicorn + WebSocket |
| 缓存/存储 | Redis / MySQL 8.4 / BM25（rank-bm25 + jieba） |
| 评估 | 本地指标 + RAGAS 可选适配 |
| 部署 | Docker Compose（Milvus + Redis + MySQL + App） |

## 目录结构

```text
docflow/
├── app/
│   ├── api/              # chat / admin / health / deps / 异常与中间件
│   ├── ws/               # WebSocket 流式协议
│   ├── core/             # 配置、日志、trace、异常、DI、客户端、指标
│   ├── ingestion/        # 连接器 / 解析器 / 分块器 / 索引与同步
│   ├── retrieval/        # 三级缓存 / 意图路由 / 策略 / 重排 / 上下文
│   ├── generation/       # Prompt / 生成 / 引用校验 / 答案服务
│   ├── evaluation/       # 评估数据集、指标、Runner、RAGAS 适配
│   ├── models/           # Pydantic schema
│   └── main.py
├── config/               # settings.yaml / sources.yaml
├── models/               # 本地模型权重（BGE-M3 / Reranker，已 gitignore）
├── scripts/              # 同步、重建、评估、语料生成 CLI
├── data/
│   ├── docs/             # 1000 条模拟问答数据源（API/故障/实践/发布/FAQ）
│   └── ...               # 样例文档、同步状态、BM25 索引、评估结果
├── docs/                 # 评估基线、前端预览图
├── web/                  # 前端页面（index.html / styles.css / app.js）
├── tests/                # 203 个单元/集成测试
├── Dockerfile
└── docker-compose.yml
```

## 快速开始

### 方式一：Docker Compose（推荐）

```bash
cp .env.example .env
# 编辑 .env：填写 MYSQL_ROOT_PASSWORD / MYSQL_PASSWORD / REDIS_PASSWORD /
# DOCFLOW_ADMIN_TOKEN；DEEPSEEK_API_KEY 可选（不填则走检索摘要降级）
docker compose up -d --build
docker compose ps
curl http://127.0.0.1:8000/api/v1/health/ready
```

> `.env` 已被 `.gitignore` 忽略，数据库/Redis 密码与管理令牌只保存在本地，不会提交到 Git。
> 如果本机已有 `volumes/mysql` 数据卷，`MYSQL_ROOT_PASSWORD` 必须与卷初始化时的密码一致；
> 否则需要重建该卷或手动修改 MySQL 用户密码。

- Swagger：<http://127.0.0.1:8000/api/v1/docs>
- 前端页面：<http://127.0.0.1:8000/>（支持 `?theme=light|dark` 与 `?q=问题` 深链）
- Attu（Milvus 控制台）：<http://127.0.0.1:3000>
- 首次启动后同步样例数据：

```bash
docker compose exec app python scripts/sync_documents.py
```

> 镜像包含 torch / sentence-transformers，构建体积较大；模型权重使用项目内
> `models/BAAI`，compose 以只读方式挂载到容器 `/app/models`。Linux 主机如遇挂载目录权限问题，执行
> `sudo chown -R 10001:10001 data models`。

### 方式二：本地开发

```bash
# 1. 启动基础设施（只启动依赖）
docker compose up -d etcd minio milvus redis mysql

# 2. 安装依赖（Python 3.12）
pip install -r requirements-dev.txt

# 3. 配置环境变量（应用会自动加载项目根目录的 .env）
cp .env.example .env
# 填写 MYSQL_ROOT_PASSWORD / MYSQL_PASSWORD / REDIS_PASSWORD / DOCFLOW_ADMIN_TOKEN

# 4. 启动服务
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 5. 同步知识源 / 评估 / 重建
python scripts/sync_documents.py
python scripts/evaluate.py
python scripts/rebuild_index.py --kb api_docs
```

无 GPU / 无 BGE 权重的离线演示可设置：

```bash
export DOCFLOW_EMBEDDING_PROVIDER=hashing
export DOCFLOW_RERANK_ENABLED=false
```

> 哈希向量只用于联调与离线演示，不具备语义检索能力，生产必须使用 BGE-M3。

## 模型权重

项目使用本地权重，默认路径：

```text
models/BAAI/bge-m3/                 # Embedding，1024 维（约 4.3 GB）
models/BAAI/bge-reranker-v2-m3/     # Reranker（约 2.1 GB）
```

可通过环境变量覆盖：

```bash
EMBEDDING_MODEL_NAME=model/BAAI/bge-m3
RERANK_MODEL_NAME=model/BAAI/bge-reranker-v2-m3
DOCFLOW_EMBEDDING_PROVIDER=sentence-transformers
DOCFLOW_RERANK_ENABLED=true
```

权重目录体积较大，不提交 Git；Docker Compose 会挂载 `./models:/app/models:ro`。首次加载模型约需
30–60 秒（CPU），之后进程内复用。

## 配置说明

### `config/settings.yaml`

唯一阈值来源：模型名、向量维度、缓存 TTL、Top-K、重排阈值、分块参数、意图映射、评估目标等。
支持 `${ENV_VAR:-default}` 插值，密钥不落盘。关键环境变量：

| 变量 | 说明 | 默认 |
| --- | --- | --- |
| `DEEPSEEK_API_KEY` | LLM 密钥 | 空（降级检索摘要） |
| `DEEPSEEK_BASE_URL` | LLM 网关 | `https://api.deepseek.com` |
| `MILVUS_URI` | Milvus 地址 | `http://127.0.0.1:19530` |
| `REDIS_URL` | Redis 地址（含密码） | 需在 `.env` 配置 |
| `REDIS_PASSWORD` | Redis 密码（Compose 使用） | 需在 `.env` 配置 |
| `MYSQL_HOST/PORT/USER/DATABASE` | MySQL 连接 | `127.0.0.1/3306/root/docflow` |
| `MYSQL_PASSWORD` | 应用连接 MySQL 的密码 | 需在 `.env` 配置 |
| `MYSQL_ROOT_PASSWORD` | MySQL 容器 root 密码 | 需在 `.env` 配置 |
| `DOCFLOW_ADMIN_TOKEN` | `/admin/*` 令牌 | 需在 `.env` 配置 |
| `DOCFLOW_EMBEDDING_PROVIDER` | `sentence-transformers` 或 `hashing` | `sentence-transformers` |
| `DOCFLOW_RERANK_ENABLED` | 是否启用 BGE Reranker | `true` |

> 本地 uvicorn 会在启动时自动加载项目根目录的 `.env`（已配置 `python-dotenv`），
> 无需手动 `export`；Docker Compose 也会读取同一个 `.env` 做变量替换。

### `config/sources.yaml`

50 个知识源，覆盖 5 个知识库与 8 类连接器（local_dir / swagger / markdown / pdf / confluence /
github / wiki / faq）。内部系统源默认 `enabled: false`，配置令牌后开启；本地样例源默认开启。

## 前端页面

启动服务后访问 <http://127.0.0.1:8000/>：

- 对话式问答，优先走 WebSocket 流式输出，连接不可用时自动回退 REST；
- 引用来源卡片（文档标题 / 版本 / 章节），缓存层级、检索策略、耗时徽标；
- 深浅色主题切换（记忆到 localStorage），移动端自适应；
- 支持深链：`/?q=如何创建用户` 直接发起提问，`/?theme=dark` 指定主题；
- 原生 HTML / CSS / JS 实现，无外部 CDN 依赖，离线可用。

页面文件位于 `web/`，由 FastAPI 在 `/` 与 `/static/*` 直接提供：
[index.html](web/index.html) · [styles.css](web/styles.css) · [app.js](web/app.js)。

## API 使用

### REST 问答

```bash
curl -X POST http://127.0.0.1:8000/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"question":"分页参数怎么传","use_cache":true}'
```

响应包含 `answer / citations / grounded / cached / cache_layer / strategy / intent / mode /
latency_ms / first_token_ms / trace_id`。

### WebSocket 流式

```python
import asyncio, json, websockets

async def main():
    async with websockets.connect("ws://127.0.0.1:8000/api/v1/ws/chat") as ws:
        await ws.send(json.dumps({"question": "502 错误怎么排查", "session_id": "s-1"}))
        while True:
            event = json.loads(await ws.recv())
            print(event["type"], event.get("data", {}).get("text", ""))
            if event["type"] in {"end", "error"}:
                break

asyncio.run(main())
```

| 消息 | 说明 |
| --- | --- |
| `start` | 开始处理，携带 `session_id` |
| `delta` | 增量文本 |
| `citation` | 单条引用（标题/URL/版本/章节/片段） |
| `end` | 最终答案、grounded、缓存层级、策略、意图、延迟 |
| `error` | 错误码与信息 |

### 管理接口

```bash
TOKEN="$DOCFLOW_ADMIN_TOKEN"   # 与 .env 中保持一致
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8000/api/v1/admin/stats
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8000/api/v1/admin/metrics

curl -X POST http://127.0.0.1:8000/api/v1/admin/cache/invalidate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"doc_ids":["<doc_id>"],"knowledge_bases":["api_docs"]}'

curl -X POST http://127.0.0.1:8000/api/v1/admin/faq \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"question":"如何重置 API 密钥？","answer":"登录控制台重置。","knowledge_bases":["faq"]}'
```

## 知识库数据（模拟）

`data/docs` 内置 1000 条可复现的模拟问答，按知识库分布：

| 数据源 | 内容 | 条数 | 落库 |
| --- | --- | ---: | --- |
| `data/docs/api/*.md` | API 使用问答 | 100 | Milvus + BM25（api_docs） |
| `data/docs/troubleshooting/*.md` | 故障排查问答 | 100 | Milvus + BM25（troubleshooting） |
| `data/docs/best-practices/*.md` | 最佳实践问答 | 100 | Milvus + BM25（best_practices） |
| `data/docs/release/*.md` | 版本发布问答 | 100 | Milvus + BM25（release_notes） |
| `data/docs/faq/*.csv` | FAQ 问答对 | 600 | MySQL `faq_entries`（L2） |

当前库内实际数量（含原有样例）：`api_docs=130 / troubleshooting=105 / best_practices=106 /
release_notes=102` 个分块，FAQ **606** 条。

重新生成与入库：

```bash
python scripts/generate_knowledge.py               # 固定种子，可复现
python scripts/sync_documents.py --full --embedding-provider hashing
```

> 数据为模拟生成，用于联调、检索/缓存验证与前端演示；正式上线请替换为真实知识源。

## 数据同步与索引重建

```bash
# 增量同步所有 enabled 源
python scripts/sync_documents.py

# 同步单个源 / 全量重建（忽略 content_hash）
python scripts/sync_documents.py --source local-api-samples
python scripts/sync_documents.py --full

# 只解析分块、不写索引
python scripts/sync_documents.py --dry-run

# 按知识库重建（可选删除 Milvus collection 与 BM25）
python scripts/rebuild_index.py --kb api_docs
python scripts/rebuild_index.py --all --drop-collection
```

失败文档会落盘到 `data/failed/<source_id>/`，并生成同名 `.error.json` 记录原因。

## 评估

```bash
# 默认使用本地 BGE-M3 + BGE Reranker（15 条基准集）
python scripts/evaluate.py

# 无模型权重的离线环境可用哈希向量 / 关闭重排
python scripts/evaluate.py --no-rerank --embedding-provider hashing

# 严格模式：未达 settings 中的验收阈值时退出码 1
python scripts/evaluate.py --strict

# RAGAS 官方指标（需 pip install 'ragas>=0.2' 且配置 LLM）
python scripts/evaluate.py --engine ragas --strict
```

结果目录 `data/eval/results/`：`local_<timestamp>.json`、`latest.json`、`latest.md`；
RAGAS 结果写入 `ragas_latest.json`。基线说明见 [docs/eval-baseline.md](docs/eval-baseline.md)。

## 质量与测试

```bash
pytest -q                       # 203 个测试
ruff check app tests scripts    # 代码风格
mypy app                        # 类型检查
```

当前结果：`203 passed`、`ruff All checks passed`、`mypy no issues`。

## 已知限制与生产清单

1. **模型权重**：`models/BAAI` 下为本地 BGE-M3 / Reranker 权重，不随仓库提交；部署时需单独同步该目录
   或通过 `EMBEDDING_MODEL_NAME` / `RERANK_MODEL_NAME` 指向可用路径。
2. **RAGAS**：默认本地指标为离线代理口径；RAGAS 引擎需额外安装与 LLM Key。
3. **哈希向量**：仅用于离线演示/单测，不具备语义能力。
4. **FAQ 检索**：FAQ 知识库用于 L2 精确匹配；语义检索覆盖 4 个向量知识库。
5. **安全**：MySQL/Redis 密码与管理令牌只存在于本地 `.env`（已 gitignore）；生产必须使用强密码、
   通过密钥管理系统注入，并启用 HTTPS。
6. **容量**：并发与限流在网关层实现；服务本身可按需水平扩展，缓存与 Milvus 共享。