# modular-multi-agent-rag-python

**Repository Path**: laityy/modular-multi-agent-rag-python

## Basic Information

- **Project Name**: modular-multi-agent-rag-python
- **Description**: 多agent模块化rag项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Modular Multi-Agent RAG（Python）

这是 `modular-multi-agent-rag` 的独立 Python 重构版。后端使用 Python 3.12、
FastAPI、LangGraph、SQLAlchemy Core 与 Alembic；前端保留 React + Vite。
旧 TypeScript 项目不会被本项目修改，两套项目与数据库可独立运行。

## 当前能力

- DeepSeek / OpenAI 兼容 LLM，可在配置中切换。
- 本地 Feature Hash 或 Voyage Embedding。
- SQLite 或 Qdrant 向量存储。
- SQLite FTS5 BM25 + Dense + RRF + 可选 Voyage Reranker。
- Planner、Researcher、Analyst、Critic、Follow-up、Synthesizer 多 Agent 工作流。
- 本地文档与 Tavily 网页搜索/网页摄取。
- 对话、消息、文档和向量持久化；可改标题、删除对话与单条消息。
- 与原 React 前端兼容的 camelCase HTTP API。
- 旧 SQLite 数据一次性只读复制与索引重建。
- 本地终端和 Docker 两种启动方式。

## 快速开始

环境要求：Node.js 20+、npm、Python 3.12、uv。首次安装：

```powershell
cd D:\agents\modular-multi-agent-rag-python
python -m pip install --user uv
uv python install 3.12
uv sync --project backend --python 3.12 --extra dev
npm install
```

Windows 如果刚安装后提示找不到 `uv`，请把 uv 所在的 Scripts 目录加入用户 PATH，
然后完整退出并重新打开 VS Code。当前开发机使用的是
`%APPDATA%\Python\Python313\Scripts`，可用 `uv --version` 确认。

项目只提供 `.env.example`，不会创建或复制 `.env`。你需要手动执行：

```powershell
Copy-Item .env.example .env
```

至少填写 `DEEPSEEK_API_KEY`。默认 `EMBEDDING_PROVIDER=local` 不需要 Voyage Key；
需要真正的语义向量与神经网络重排时，再配置 Voyage。

项目统一使用独立的 `uv` 命令创建环境和启动 Python。即使 VS Code 已自动激活
`backend/.venv`，`uv run --project backend` 仍会解析并使用同一个项目环境。
不要在激活后的虚拟环境中使用 `python -m uv`，因为那会尝试从虚拟环境导入 uv。

### 开发模式

```powershell
npm run dev
```

- React Vite：http://127.0.0.1:5174
- FastAPI：http://127.0.0.1:3100
- API 文档：http://127.0.0.1:3100/docs

Vite 将 `/api`、`/health`、`/ready` 代理到 3100。两个地址都能看到前端，
但开发时应优先访问 5174，它支持热更新。

### 本地生产模式

```powershell
npm run start
```

该命令先构建 React，再由 FastAPI 在 http://127.0.0.1:3100 同时提供页面和 API。
只需要访问一个端口。

也可分开执行：

```powershell
npm run build:web
npm run start:api
```

### Docker

Docker 不要求修改代码。先手动准备 `.env`，然后：

```powershell
docker compose up --build
```

访问 http://127.0.0.1:3100。默认使用 SQLite 向量存储。

启用 Qdrant 时，把 `.env` 中的 `VECTOR_STORE_MODE` 改成 `qdrant`，再运行：

```powershell
docker compose --profile qdrant up --build
```

本地终端与 Docker 可以共存，但端口和数据库文件不能冲突。建议二选一：

- 更换一方映射端口，例如 `3110:3100`。
- 为 Docker 使用独立数据卷，避免两个进程同时写同一个 SQLite 文件。

## 旧数据迁移

默认命令从旧项目只读复制数据库：

```powershell
npm run migrate:data
```

等价于：

```powershell
backend\.venv\Scripts\python.exe -m modular_rag.cli migrate-from-ts `
  --source D:\agents\modular-multi-agent-rag\data\app.db `
  --target D:\agents\modular-multi-agent-rag-python\data\app.db
```

迁移保留文档、分块、对话和消息，使用 Python 分词规则重建 FTS5 与本地
Feature Hash 向量，并创建 `app.db.pre-python.bak`。它不会修改源数据库。
目标已存在时命令会拒绝覆盖；确认覆盖才使用 `--force`。

本次真实迁移验证结果：

| 数据 | 数量 |
| --- | ---: |
| documents | 145 |
| chunks | 2773 |
| conversations | 2 |
| chat_messages | 6 |
| 重建 FTS | 2773 |
| 重建向量 | 2773 × 1024 维 |

## 架构

```mermaid
flowchart LR
    UI["React + Vite"] --> API["FastAPI 兼容 API"]
    API --> CS["会话存储"]
    API --> MODE{"RAG 开关"}
    MODE -->|关| DIRECT["直接调用 LLM"]
    MODE -->|开| GRAPH["LangGraph"]
    GRAPH --> PLAN["Planner"]
    PLAN --> RESEARCH["并发 Researchers"]
    RESEARCH --> LOCAL["本地 Hybrid RAG"]
    RESEARCH --> WEB["Tavily Web"]
    LOCAL --> ANALYST["Analyst"]
    WEB --> ANALYST
    ANALYST --> CRITIC["Critic"]
    CRITIC -->|证据不足，最多一次| FOLLOW["Follow-up"]
    FOLLOW --> ANALYST
    CRITIC -->|通过或达到上限| SYN["Synthesizer"]
    SYN --> API

    LOCAL --> BM25["SQLite FTS5"]
    LOCAL --> DENSE["SQLite / Qdrant"]
    BM25 --> RRF["RRF 融合"]
    DENSE --> RRF
    RRF --> RERANK["Voyage 或 RRF fallback"]
```

关键入口：

- [FastAPI 路由](backend/src/modular_rag/api.py)
- [依赖装配](backend/src/modular_rag/container.py)
- [LangGraph 工作流](backend/src/modular_rag/agents/workflow.py)
- [Hybrid RAG](backend/src/modular_rag/rag/hybrid.py)
- [摄取流水线](backend/src/modular_rag/ingestion/pipeline.py)
- [SQLAlchemy Core 存储](backend/src/modular_rag/storage/sqlite.py)
- [React 入口](web/src/App.tsx)

## 目录结构

```text
modular-multi-agent-rag-python/
├─ backend/
│  ├─ migrations/                 # Alembic 版本
│  ├─ src/modular_rag/
│  │  ├─ agents/                  # LangGraph 与各 Agent
│  │  ├─ ingestion/               # 扫描、解析、分块、索引
│  │  ├─ providers/               # LLM、Embedding、Reranker、Web
│  │  ├─ rag/                     # 混合检索
│  │  ├─ sources/                 # 来源安全与数据库扩展点
│  │  ├─ storage/                 # SQLite、Qdrant、会话
│  │  ├─ api.py                   # HTTP 入口
│  │  ├─ container.py             # 依赖装配
│  │  ├─ config.py                # 环境配置
│  │  └─ cli.py                   # 数据库命令
│  ├─ tests/
│  ├─ pyproject.toml
│  └─ uv.lock
├─ web/                           # React 前端
├─ docs/                          # 阅读与架构文档
├─ data/                          # 独立 SQLite 数据
├─ Dockerfile
├─ docker-compose.yml
├─ package.json
└─ .env.example
```

## API

保留原前端使用的接口：

- `GET /health`、`GET /ready`
- `POST /api/v1/chat`
- `GET|POST /api/v1/conversations`
- `GET|PATCH|DELETE /api/v1/conversations/{id}`
- `DELETE /api/v1/conversations/{id}/messages/{messageId}`
- `POST /api/v1/search`
- `POST /api/v1/ingestion/local`
- `POST /api/v1/ingestion/url`
- `GET /api/v1/ingestion/jobs/{jobId}`
- `GET /api/v1/documents`
- `DELETE /api/v1/documents/{id}`
- `GET /api/v1/traces/{traceId}`

完整交互定义可在服务启动后访问 `/docs`。

## 配置选择

- 默认推荐 DeepSeek：中文与性价比较适合本机单用户系统。
- `local` Embedding 是 Feature Hash 检索基线，不是远程模型的本地化部署。
- 对语义召回质量要求更高时，推荐 Voyage Embedding + Voyage Reranker。
- Tavily 同时承担 Agent 网页搜索与指定 URL 正文提取。
- SQLite 适合当前单机规模；向量达到几十万级或需要多实例时切换 Qdrant。

## 验证命令

```powershell
npm run typecheck
npm run build:web
npm test
npm run lint:python
docker compose config
```

## 企业级对齐待优化清单

- [ ] 使用真实神经 Embedding 替换默认 Feature Hash，并建立离线评测基线。
- [ ] 构建黄金问答集，度量 Recall@K、MRR、nDCG、Faithfulness 和延迟。
- [ ] 引入 LangGraph 持久化 Checkpointer，支持工作流恢复和人工介入。
- [ ] 将内存摄取任务迁移到 Redis/Celery、Dramatiq 或消息队列。
- [ ] Trace 落库并接入 OpenTelemetry、Prometheus、Grafana。
- [ ] 增加租户、身份认证、RBAC、配额、审计与密钥托管。
- [ ] 完善文档级、字段级 ACL，在检索前强制过滤。
- [ ] 增加 Prompt 注入检测、内容净化、来源白名单和输出策略。
- [ ] 为网页摄取增加重定向逐跳 SSRF 校验、robots 与速率限制。
- [ ] 使用对象存储保存原文，元数据数据库保存版本与血缘。
- [ ] 数据库知识源实现 CDC、增量游标、字段映射和权限裁剪。
- [ ] Qdrant 建立 payload 索引、分片、备份、恢复与容量压测。
- [ ] Provider 增加熔断、预算、限流、fallback、模型路由和成本统计。
- [ ] API 增加流式输出、取消传播、幂等键与分布式超时。
- [ ] 增加端到端契约测试、真实供应商冒烟测试和故障注入。
- [ ] 建立 CI/CD、镜像签名、SBOM、依赖扫描和灰度发布。

## 阅读文档

从 [00-项目阅读导航](docs/00-项目阅读导航.md) 开始。各模块目录内也有说明文档：

- [Agent 模块](backend/src/modular_rag/agents/README.md)
- [RAG 模块](backend/src/modular_rag/rag/README.md)
- [Provider 模块](backend/src/modular_rag/providers/README.md)
- [Storage 模块](backend/src/modular_rag/storage/README.md)
- [Ingestion 模块](backend/src/modular_rag/ingestion/README.md)
- [Sources 模块](backend/src/modular_rag/sources/README.md)
- [VS Code 终端自动激活与 uv 排障](docs/04-VSCode终端环境与uv.md)
- [uv 介绍、使用及与 venv、Conda 的区别](docs/05-uv介绍使用与venv-conda对比.md)