# myACTRAG

**Repository Path**: openminds/myACTRAG

## Basic Information

- **Project Name**: myACTRAG
- **Description**: 基于 检索增强生成（RAG） 的 ACT（接纳承诺疗法） 心理学知识问答系统。提供 RESTful API 和 MCP 协议端点，支持混合检索与多模式查询。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-10
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: RAG, LlamaIndex, FastAPI, ACT

## README

# ACTRAG

基于 **检索增强生成（RAG）** 的 **ACT（接纳承诺疗法）** 心理学知识问答系统。提供 RESTful API 和 MCP 协议端点，支持混合检索与多模式查询。

## 项目简介

ACTRAG 是一个端到端的 RAG 系统，从 EPUB 电子书中解析 ACT 疗法的专业知识，构建向量索引和关键词索引，通过混合检索 + 大语言模型生成精准回答。提供 RESTful API 微服务，支持流式响应和多种检索模式。

### 功能特性

- **混合检索** — 支持 4 种检索模式：纯向量、纯关键词、混合加权、融合平均
- **多语言支持** — 使用 `paraphrase-multilingual-MiniLM-L12-v2` 嵌入模型，支持中/英/法/西等语言
- **流式响应** — 支持 SSE 风格的流式查询输出
- **RESTful API** — 基于 FastAPI 构建，提供完整的 Swagger 文档
- **后台索引管理** — 启动时自动加载或构建索引，无需手动操作
- **配置驱动** — 所有配置通过环境变量 / `.env` 文件管理
- **MCP 协议支持** — 基于 FastMCP 提供 act-rag-mcp 端点，剥离 LLM 调用，返回原始检索结果
- **资源安全** — 线程锁防止并发索引构建，资源清理机制

## 快速开始

### 前置要求

- Python >= 3.11
- [uv](https://docs.astral.sh/uv/) 包管理器

### 安装

```bash
# 克隆项目后进入目录
cd myACTRAG

# 复制环境变量配置
cp .example.env .env
# 编辑 .env，填入 DeepSeek API Key
# DEEPSEEK_API_KEY=your-api-key

# 安装依赖
uv sync
```

### 启动服务

```bash
uv run act-rag-api
```

服务默认运行在 `http://localhost:8021`，访问 `http://localhost:8021/docs` 查看 Swagger API 文档。

### 命令行查询

```bash
uv run python -m rag.system
```

## API 文档

| 端点 | 方法 | 说明 |
|------|------|------|
| `/` | GET | 服务信息 |
| `/health` | GET | 健康检查 |
| `/status` | GET | 系统状态 |
| `/index/status` | GET | 索引状态 |
| `/query` | POST | 查询（支持流式） |
| `/search/keyword` | POST | 关键词搜索 |
| `/query/batch` | POST | 批量查询 |
| `/mode/change` | POST | 切换检索模式 |

### 查询示例

```bash
curl -X POST "http://localhost:8021/query" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "什么是接纳承诺疗法？",
    "mode": "HYBRID",
    "similarity_top_k": 3,
    "stream": false
  }'
```

### 流式查询

```bash
curl -X POST "http://localhost:8021/query?format=text" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "什么是接纳承诺疗法？",
    "mode": "HYBRID",
    "stream": true
  }'
```

### 使用 httpx 调用

参考 [examples/httpx_client.py](examples/httpx_client.py) 获取完整的同步/异步调用示例。

```bash
uv run python examples/httpx_client.py
```

## 检索模式

| 模式 | 说明 |
|------|------|
| `HYBRID` | 分别检索向量和关键词，合并去重，关键词节点有 1.1x 加分 |
| `VECTOR_ONLY` | 仅向量检索（语义相似度） |
| `KEYWORD_ONLY` | 仅关键词检索（BM25 风格） |
| `FUSION` | 加权平均融合，`vector_weight` 控制向量与关键词的权重比 |

## MCP 服务器 (act-rag-mcp)

基于 [FastMCP](https://gofastmcp.com) 的 MCP 协议端点，复用底层检索逻辑，剥离外部 LLM 调用。适用于需要原始检索结果的 IDE 集成（Claude Desktop、Cursor 等）或自定义客户端。

### 启动方式

```bash
# stdio 模式（本地 / IDE 集成）
uv run act-rag-mcp

# HTTP 模式（远程访问，端口 8022）
uv run python -c "from rag.mcp_server import main_http; main_http()"
```

### 可用工具

| 工具 | 说明 | 参数 |
|------|------|------|
| `search` | 混合检索，支持 4 种模式 | `question`(必填), `mode`(默认 HYBRID), `top_k`(1-20), `vector_weight`(0-1), `similarity_cutoff`(0-1) |
| `keyword_search` | 纯关键词检索 | `keyword`(必填), `top_k`(1-20) |
| `build_index` | 构建或重建混合检索索引 | `force_rebuild`(布尔, 默认 false) |
| `get_index_status` | 查询索引构建状态 | 无 |

### 可用资源

| URI | 说明 |
|-----|------|
| `actrag://status` | 系统静态配置信息（模型、路径、默认参数） |
| `actrag://index/status` | 索引文件是否存在 |

### 客户端配置

**Claude Desktop / Cursor 等 MCP 客户端（需指定项目目录）：**

```json
{
  "mcpServers": {
    "act-rag-mcp": {
      "command": "uv",
      "args": ["run", "act-rag-mcp"],
      "cwd": "E:\\myWorkspace\\myACTRAG"
    }
  }
}
```

> `cwd` 需指向项目根目录（即包含 `.env` 和 `pyproject.toml` 的目录），确保服务器能正确加载环境变量和持久化索引。

**远程连接：**

```json
{
  "mcpServers": {
    "act-rag-mcp": {
      "url": "http://localhost:8022/mcp",
      "transport": "streamable-http"
    }
  }
}
```

### 使用 MCP Inspector 测试

```bash
uv run fastmcp dev rag/mcp_server.py
```

### 配置说明

所有配置通过 `.env` 文件管理，参考 [.example.env](.example.env)：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `API_HOST` | `localhost` | 服务监听地址 |
| `API_PORT` | `8021` | 服务端口 |
| `DEEPSEEK_API_KEY` | — | DeepSeek API 密钥 |
| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 模型名称 |
| `EMBEDDING_MODEL` | `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` | 嵌入模型 |
| `DEFAULT_MODE` | `HYBRID` | 默认检索模式 |
| `DEFAULT_TOP_K` | `5` | 默认检索数量 |
| `SIMILARITY_CUTOFF` | `0.2` | 相似度过滤阈值 |
| `MAX_SOURCES` | `3` | 返回的最大来源数 |
| `PERSIST_DIR` | `./chroma_act_fastapi_db` | 向量数据库持久化目录 |

## 项目结构

```
myACTRAG/
├── rag/                      # 核心 RAG 包
│   ├── __init__.py           # 包入口，延迟导入机制
│   ├── config.py             # 配置模块 (RagConfig)
│   ├── models.py             # Pydantic 请求/响应模型
│   ├── prompts.py            # 提示模板
│   ├── ingestion.py          # 文档解析和索引构建
│   ├── retriever.py          # 混合检索器 (HybridRetriever)
│   ├── mcp_server.py         # FastMCP 服务器 (act-rag-mcp)
│   └── system.py             # 核心 RAG 系统 (DeepSeekRAGSystem)
├── service.py                # FastAPI 微服务入口
├── tests/                    # 单元测试（93 个测试用例）
│   ├── conftest.py           # 共享 fixtures 和 Mock 注册
│   ├── test_config.py        # 配置测试
│   ├── test_ingestion.py     # 文档解析测试
│   ├── test_mcp_server.py    # MCP 服务器测试
│   ├── test_models.py        # 模型测试
│   ├── test_retriever.py     # 检索器测试
│   ├── test_service.py       # API 端点测试
│   └── test_system.py        # 核心系统测试
├── examples/
│   └── httpx_client.py       # httpx 调用示例
├── epub_books/               # ACT 疗法 EPUB 书籍
├── .env                      # 环境变量（从 .env.example 复制）
├── .env.example              # 示例环境变量配置
└── pyproject.toml            # 项目依赖和元数据
```

## 运行测试

```bash
# 运行全部测试（93 个用例）
uv run pytest

# 带覆盖率
uv run pytest --cov=rag --cov=service.py --cov=rag.mcp_server -v

# 运行特定测试模块
uv run pytest tests/test_system.py -v
uv run pytest tests/test_mcp_server.py -v
```

## 技术栈

| 组件 | 技术 |
|------|------|
| 框架 | [LlamaIndex](https://www.llamaindex.ai/) |
| 微服务 | [FastAPI](https://fastapi.tiangolo.com/) |
| LLM | [DeepSeek API](https://platform.deepseek.com/) |
| 嵌入模型 | Sentence Transformers (多语言) |
| 向量数据库 | [ChromaDB](https://www.trychroma.com/) |
| 文档解析 | ebooklib + BeautifulSoup |
| MCP 协议 | [FastMCP](https://gofastmcp.com) |
| 测试 | pytest + pytest-asyncio |

## 许可证

[MIT](LICENSE)