🚀 RAG API

多租户多模态文档智能检索系统

基于 RAG-Anything 和 LightRAG 构建的企业级 RAG 服务

功能特性 • 快速开始 • 架构设计 • API 文档 • 部署指南

📖 项目简介

RAG API 是一个企业级的检索增强生成（RAG）服务，结合了 RAG-Anything 的强大文档解析能力和 LightRAG 的高效知识图谱检索技术，为您的文档提供智能问答能力。

🎯 核心亮点

🏢 多租户隔离 - 完整的租户数据隔离，支持企业级多租户场景
🎨 多模态解析 - 支持 PDF、Word、图片等多种格式，OCR、表格、公式全覆盖
⚡ 高性能检索 - 基于知识图谱的混合检索，查询响应 6-15 秒
🔄 灵活部署 - 支持生产模式和开发模式，一键切换
📦 开箱即用 - Docker 一键部署，3 分钟启动服务
🎛️ 多解析引擎 - DeepSeek-OCR(远程API) + MinerU（本地/远程API）+ Docling（快速）
🎨 RAG-Anything-VLM增强 - 三种模式（off/selective/full），深度理解图表内容
💾 任务持久化 - Redis 存储支持，容器重启/实例重建后任务可恢复

✨ 功能特性

📄 文档处理

✅ 多格式支持
- PDF、Word、Excel、PPT
- PNG、JPG、WebP 图片
- TXT、Markdown 文本
✅ 智能解析
- 纯文本（.txt, .md）→ 直接插入（极快 ~1秒，跳过解析器）
- OCR 文字识别
- 表格结构化提取
- 数学公式识别
- 版面分析
✅ RAG-Anything-VLM增强 🆕
- off - 仅 Markdown（最快）
- selective - 选择性处理重要图表
- full - 完整上下文增强处理
- 智能过滤：有标题、大尺寸、首页内容
- ⚠️ 仅支持 remote MinerU 模式,本地模式会调用RAG-Anything原生方法
✅ 批量处理
- 单次最多 100 个文件
- 异步任务队列
- 进度实时追踪

🔍 智能检索

✅ 多模式查询
- naive - 向量检索（最快）
- local - 本地图谱
- global - 全局图谱
- hybrid - 混合检索
- mix - 完整检索（最准确）
✅ 知识图谱
- 自动实体提取
- 关系推理
- 语义理解
- 上下文增强
✅ 外部存储
- DragonflyDB（KV 存储 + 任务存储）
- Qdrant（向量存储）
- Memgraph（图数据库）
- 任务持久化（Redis 模式）

🏗️ 架构设计

系统架构图

graph TB
    subgraph "客户端层"
        Client[客户端应用]
        WebUI[Web 界面]
    end
    
    subgraph "API 网关层"
        FastAPI[FastAPI 服务]
        Auth[租户认证]
    end
    
    subgraph "业务逻辑层"
        TenantMgr[租户管理器]
        TaskQueue[任务队列]
        
        subgraph "文档处理"
            DeepSeekOCR[DeepSeek-OCR<br/>快速 OCR 80%场景]
            MinerU[MinerU 解析器<br/>复杂多模态]
            Docling[Docling 解析器<br/>快速轻量]
            FileRouter[智能路由<br/>复杂度评分选择]
        end
        
        subgraph "RAG 引擎"
            LightRAG[LightRAG 实例池<br/>LRU 缓存 50]
            KG[知识图谱引擎]
            Vector[向量检索引擎]
        end
    end
    
    subgraph "存储层"
        DragonflyDB[(DragonflyDB<br/>KV 存储)]
        Qdrant[(Qdrant<br/>向量数据库)]
        Memgraph[(Memgraph<br/>图数据库)]
        Local[(本地文件<br/>临时存储)]
    end
    
    subgraph "外部服务"
        LLM[LLM<br/>实体提取/生成]
        Embedding[Embedding<br/>向量化]
        Rerank[Rerank<br/>重排序]
    end
    
    Client --> FastAPI
    WebUI --> FastAPI
    FastAPI --> Auth
    Auth --> TenantMgr
    TenantMgr --> TaskQueue
    TenantMgr --> LightRAG
    
    TaskQueue --> FileRouter
    FileRouter --> DeepSeekOCR
    FileRouter --> MinerU
    FileRouter --> Docling
    DeepSeekOCR --> LightRAG
    MinerU --> LightRAG
    Docling --> LightRAG
    
    LightRAG --> KG
    LightRAG --> Vector
    
    KG --> DragonflyDB
    KG --> Memgraph
    Vector --> Qdrant
    LightRAG --> Local
    
    LightRAG --> LLM
    LightRAG --> Embedding
    Vector --> Rerank
    
    style FastAPI fill:#00C7B7
    style LightRAG fill:#FF6B6B
    style DeepSeekOCR fill:#5DADE2
    style MinerU fill:#4ECDC4
    style Docling fill:#95E1D3
    style TenantMgr fill:#F38181

多租户架构

graph TB
    subgraph "租户 A"
        A_Config[租户 A 配置<br/>独立 API Key]
        A_Instance[LightRAG 实例 A<br/>专属 LLM/Embedding]
        A_Data[(租户 A 数据<br/>完全隔离)]
        A_Config --> A_Instance
        A_Instance --> A_Data
    end

    subgraph "租户 B"
        B_Config[租户 B 配置<br/>独立 API Key]
        B_Instance[LightRAG 实例 B<br/>专属 LLM/Embedding]
        B_Data[(租户 B 数据<br/>完全隔离)]
        B_Config --> B_Instance
        B_Instance --> B_Data
    end

    subgraph "租户 C"
        C_Config[使用全局配置]
        C_Instance[LightRAG 实例 C<br/>共享 LLM/Embedding]
        C_Data[(租户 C 数据<br/>完全隔离)]
        C_Config --> C_Instance
        C_Instance --> C_Data
    end

    Pool[实例池管理器<br/>LRU Cache + 配置隔离]
    Global[全局配置<br/>默认 API Key]

    Pool --> A_Instance
    Pool --> B_Instance
    Pool --> C_Instance

    C_Config -.降级.-> Global

    style Pool fill:#F38181
    style Global fill:#95E1D3
    style A_Config fill:#FFD93D
    style B_Config fill:#FFD93D
    style C_Config fill:#E8E8E8

核心技术栈

🔧 框架 & 运行时

FastAPI 0.115+
Python 3.11+
Uvicorn
Docker & Docker Compose

🧠 AI & RAG

LightRAG 1.4.9.4
RAG-Anything
MinerU (PDF-Extract-Kit)
Docling

💾 存储 & 数据库

DragonflyDB（Redis 协议兼容）
Qdrant（向量数据库）
Memgraph（图数据库）
本地文件系统

🚀 快速开始

方式一：一键部署（推荐）

适合生产环境和测试环境：

# 1. 克隆项目
git clone https://github.com/BukeLy/rag-api.git
cd rag-api

# 2. 配置环境变量
cp env.example .env
nano .env  # 填入你的 API 密钥

# 3. 运行部署脚本
chmod +x deploy.sh
./deploy.sh

# 选择部署模式：
# 1) 生产模式 (Production) - 标准容器部署
# 2) 开发模式 (Development) - 代码热重载

# 4. 验证服务
curl http://localhost:8000/

访问 Swagger 文档： http://localhost:8000/docs

方式二：Docker Compose

生产模式

# 配置环境变量
cp env.example .env
nano .env

# 启动服务
docker compose -f docker-compose.yml up -d

# 查看日志
docker compose -f docker-compose.yml logs -f

开发模式（代码热重载）

# 启动开发环境
docker compose -f docker-compose.dev.yml up -d

# 或使用快捷脚本
./scripts/dev.sh

# 修改代码会自动重载，无需重启

方式三：本地开发

# 安装 uv (Python 包管理器)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装依赖
uv sync

# 配置环境变量
cp env.example .env
nano .env

# 启动服务
uv run uvicorn main:app --host 0.0.0.0 --port 8000 --reload

环境变量配置

最小配置（必填）：

# LLM 配置（功能导向命名）
LLM_API_KEY=your_llm_api_key
LLM_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
LLM_MODEL=ep-xxx-xxx
# LLM_REQUESTS_PER_MINUTE=800        # 速率限制（可选）
# LLM_TOKENS_PER_MINUTE=40000        # 速率限制（可选）
# LLM_MAX_ASYNC=8                    # 【可选,专家模式】手动指定并发数
#                                    # 未设置时自动计算: min(RPM, TPM/3500) = 11

# Embedding 配置（功能导向命名）
EMBEDDING_API_KEY=your_embedding_api_key
EMBEDDING_BASE_URL=https://api.siliconflow.cn/v1
EMBEDDING_MODEL=Qwen/Qwen3-Embedding-0.6B
EMBEDDING_DIM=1024
# EMBEDDING_MAX_ASYNC=32             # 【可选,专家模式】未设置时自动计算: 800

# MinerU 模式（推荐远程模式）
MINERU_MODE=remote
MINERU_API_TOKEN=your_token
MINERU_HTTP_TIMEOUT=60              # MinerU 下载超时（秒，默认 60）
FILE_SERVICE_BASE_URL=http://your-ip:8000

# VLM 图表增强配置 🆕
# ⚠️ 注意：仅在 MINERU_MODE=remote 时生效
RAG_VLM_MODE=off                    # off / selective / full
RAG_IMPORTANCE_THRESHOLD=0.5        # 重要性阈值（selective 模式）
RAG_CONTEXT_WINDOW=2                # 上下文窗口（full 模式）
RAG_CONTEXT_MODE=page               # page / chunk
RAG_MAX_CONTEXT_TOKENS=3000         # 最大上下文 tokens

# 任务存储配置 🆕
TASK_STORE_STORAGE=redis            # memory / redis（生产推荐 redis）

# 文档插入验证配置 🆕
DOC_INSERT_VERIFICATION_TIMEOUT=300        # 验证超时时间（秒，默认 5 分钟）
DOC_INSERT_VERIFICATION_POLL_INTERVAL=0.5  # 轮询间隔（秒，默认 500ms）

# 模型调用超时配置 🆕
MODEL_CALL_TIMEOUT=90               # 模型调用最大超时（秒，默认 90）

⚡ 自动并发数计算：

LLM: 未设置 LLM_MAX_ASYNC 时，自动计算为 min(RPM, TPM/3500) ≈ 11
Embedding: 未设置 EMBEDDING_MAX_ASYNC 时，自动计算为 min(RPM, TPM/500) ≈ 800
Rerank: 未设置 RERANK_MAX_ASYNC 时，自动计算为 min(RPM, TPM/500) ≈ 800

✅ 推荐: 不设置 *_MAX_ASYNC，让系统自动计算，彻底避免 429 错误

完整配置参考 env.example。

📚 API 文档

核心接口

1️⃣ 上传文档

# 单文件上传（默认模式）
curl -X POST "http://localhost:8000/insert?tenant_id=your_tenant&doc_id=doc1" \
  -F "file=@document.pdf" \
  -F "parser=auto"

# VLM 图表增强模式 🆕
# off: 仅 Markdown（最快，默认）
curl -X POST "http://localhost:8000/insert?tenant_id=your_tenant&doc_id=doc2&vlm_mode=off" \
  -F "file=@document.pdf"

# selective: 选择性处理重要图表（平衡性能和质量）
curl -X POST "http://localhost:8000/insert?tenant_id=your_tenant&doc_id=doc3&vlm_mode=selective" \
  -F "file=@document.pdf"

# full: 完整 RAG-Anything 处理（最高质量，启用上下文增强）
curl -X POST "http://localhost:8000/insert?tenant_id=your_tenant&doc_id=doc4&vlm_mode=full" \
  -F "file=@document.pdf"

# 返回
{
  "task_id": "task-xxx-xxx",
  "doc_id": "doc1",
  "filename": "document.pdf",
  "vlm_mode": "off",
  "status": "pending"
}

2️⃣ 批量上传

curl -X POST "http://localhost:8000/batch?tenant_id=your_tenant" \
  -F "files=@doc1.pdf" \
  -F "files=@doc2.docx" \
  -F "files=@image.png"

# 返回
{
  "batch_id": "batch-xxx-xxx",
  "total_files": 3,
  "accepted_files": 3,
  "tasks": [...]
}

3️⃣ 智能查询（Query API v2.0）

新增高级功能：

✨ 对话历史：支持多轮对话上下文
✨ 自定义提示词：定制回答风格
✨ 响应格式控制：paragraph/list/json
✨ 关键词精准检索：hl_keywords/ll_keywords
✨ 流式输出：实时查看生成过程

# 基础查询
curl -X POST "http://localhost:8000/query?tenant_id=your_tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "文档中的核心观点是什么？",
    "mode": "hybrid"
  }'

# 高级查询（多轮对话 + 自定义提示词）
curl -X POST "http://localhost:8000/query?tenant_id=your_tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "能详细展开第二点吗？",
    "mode": "hybrid",
    "conversation_history": [
      {"role": "user", "content": "有哪些要点？"},
      {"role": "assistant", "content": "主要有三点..."}
    ],
    "user_prompt": "请用专业的学术语言回答",
    "response_type": "list"
  }'

# 流式查询（SSE）
curl -N -X POST "http://localhost:8000/query/stream?tenant_id=your_tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "文档中的核心观点是什么？",
    "mode": "hybrid"
  }'

# 返回（实时流式输出）
data: {"chunk": "根据", "done": false}
data: {"chunk": "文档内容", "done": false}
data: {"done": true}

4️⃣ 任务状态查询

curl "http://localhost:8000/task/task-xxx-xxx?tenant_id=your_tenant"

# 返回
{
  "task_id": "task-xxx-xxx",
  "status": "completed",
  "progress": 100,
  "result": {...}
}

5️⃣ 租户管理

# 获取租户统计
curl "http://localhost:8000/tenants/stats?tenant_id=your_tenant"

# 清除租户缓存
curl -X DELETE "http://localhost:8000/tenants/cache?tenant_id=your_tenant"

# 查看实例池状态（管理员）
curl "http://localhost:8000/tenants/pool/stats"

VLM 模式对比 🆕

模式	速度	质量	资源消耗	适用场景
`off`	⚡⚡⚡⚡⚡	⭐⭐⭐	极低	纯文本文档、快速批量处理
`selective`	⚡⚡⚡⚡	⭐⭐⭐⭐	低	包含关键图表的文档（推荐）
`full`	⚡⚡	⭐⭐⭐⭐⭐	高	图表密集的研究报告、论文

处理时间估算（以 20 页 PDF 为例）：

off: ~10 秒（仅 Markdown）
selective: ~30 秒（5-10 个重要图表）
full: ~120 秒（完整上下文处理）

查询模式对比

模式	速度	准确度	适用场景
`naive`	⚡⚡⚡⚡⚡	⭐⭐⭐	简单问答，快速检索
`local`	⚡⚡⚡⚡	⭐⭐⭐⭐	局部实体关系查询
`global`	⚡⚡⚡	⭐⭐⭐⭐	全局知识图谱推理
`hybrid`	⚡⚡⚡	⭐⭐⭐⭐⭐	混合检索（推荐）
`mix`	⚡⚡	⭐⭐⭐⭐⭐	复杂问题，深度分析

Query API v2.0 高级参数

参数	类型	说明	示例
`conversation_history`	List[Dict]	多轮对话上下文	`[{"role": "user", "content": "..."}]`
`user_prompt`	str	自定义提示词	"请用专业的学术语言回答"
`response_type`	str	响应格式	"paragraph", "list", "json"
`hl_keywords`	List[str]	高优先级关键词	`["人工智能", "机器学习"]`
`ll_keywords`	List[str]	低优先级关键词	`["应用", "案例"]`
`only_need_context`	bool	仅返回上下文（调试）	`true`
`max_entity_tokens`	int	实体 Token 限制	`6000`

完整 API 文档访问：http://localhost:8000/docs

🎯 使用示例

Python SDK

import requests

# 配置
BASE_URL = "http://localhost:8000"
TENANT_ID = "your_tenant"

# 上传文档
with open("document.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/insert",
        params={"tenant_id": TENANT_ID, "doc_id": "doc1"},
        files={"file": f}
    )
    task_id = response.json()["task_id"]
    print(f"Task ID: {task_id}")

# 查询
response = requests.post(
    f"{BASE_URL}/query",
    params={"tenant_id": TENANT_ID},
    json={
        "query": "文档的主要内容是什么？",
        "mode": "hybrid",
        "top_k": 10
    }
)
result = response.json()
print(f"Answer: {result['answer']}")

cURL 完整示例

# 1. 上传 PDF 文档
TASK_ID=$(curl -X POST "http://localhost:8000/insert?tenant_id=demo&doc_id=report" \
  -F "file=@report.pdf" | jq -r '.task_id')

echo "Task ID: $TASK_ID"

# 2. 等待处理完成
while true; do
  STATUS=$(curl -s "http://localhost:8000/task/$TASK_ID?tenant_id=demo" | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    break
  fi
  sleep 2
done

# 3. 查询文档内容
curl -X POST "http://localhost:8000/query?tenant_id=demo" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "这份报告的主要结论是什么？",
    "mode": "hybrid"
  }' | jq '.answer'

🛠️ 部署指南

系统要求

最小配置：

CPU: 2 核
内存: 4GB
磁盘: 40GB SSD
系统: Ubuntu 20.04+ / Debian 11+ / CentOS 8+

推荐配置（生产环境）：

CPU: 4 核
内存: 8GB
磁盘: 100GB SSD
系统: Ubuntu 22.04 LTS

服务器部署

阿里云/腾讯云快速部署

# SSH 登录服务器
ssh root@your-server-ip

# 克隆项目
git clone https://github.com/BukeLy/rag-api.git
cd rag-api

# 运行一键部署脚本
chmod +x deploy.sh
./deploy.sh

# 脚本会自动：
# 1. 安装 Docker 和 Docker Compose
# 2. 配置环境变量
# 3. 优化系统参数
# 4. 启动服务
# 5. 验证健康状态

外部存储配置

支持 DragonflyDB + Qdrant + Memgraph 外部存储（默认已启用）：

# 在 .env 中配置
USE_EXTERNAL_STORAGE=true

# DragonflyDB 配置（KV 存储）
KV_STORAGE=RedisKVStorage
REDIS_URI=redis://dragonflydb:6379/0

# Qdrant 配置（向量存储）
VECTOR_STORAGE=QdrantVectorDBStorage
QDRANT_URL=http://qdrant:6333

# Memgraph 配置（图存储）
GRAPH_STORAGE=MemgraphStorage
MEMGRAPH_URI=bolt://memgraph:7687
MEMGRAPH_USERNAME=
MEMGRAPH_PASSWORD=

详细配置参考外部存储部署文档。

Docker Compose 配置

项目提供两个配置文件：

文件	用途	特点
`docker-compose.yml`	生产模式	代码打包到镜像，性能最优
`docker-compose.dev.yml`	开发模式	代码外挂，支持热重载

选择配置文件：

# 生产模式
docker compose -f docker-compose.yml up -d

# 开发模式
docker compose -f docker-compose.dev.yml up -d

性能优化

调优参数

在 .env 中配置：

# ⚡ 并发控制（推荐：使用自动计算）
# LLM_MAX_ASYNC=8                    # 【专家模式】手动指定 LLM 并发数
#                                    # 未设置时自动计算: min(RPM, TPM/3500) ≈ 11
# EMBEDDING_MAX_ASYNC=32             # 【专家模式】手动指定 Embedding 并发数
#                                    # 未设置时自动计算: min(RPM, TPM/500) ≈ 800
# RERANK_MAX_ASYNC=16                # 【专家模式】手动指定 Rerank 并发数
#                                    # 未设置时自动计算: min(RPM, TPM/500) ≈ 800

# 检索数量（影响查询质量和速度）
TOP_K=20  # 实体/关系检索数量
CHUNK_TOP_K=10  # 文本块检索数量

# 文档处理并发
DOCUMENT_PROCESSING_CONCURRENCY=10  # 远程模式可设高，本地模式设为 1

🎯 并发数配置建议：

推荐方式：不设置 *_MAX_ASYNC，让系统根据 TPM/RPM 自动计算
专家模式：如果需要手动控制，可设置 LLM_MAX_ASYNC 等参数
优势：自动计算可彻底避免 429 错误（TPM limit reached）

模式选择

MinerU 远程模式（推荐）：高并发，节省资源
MinerU 本地模式：需要 GPU，内存占用高
Docling 模式：快速轻量，适合简单文档

🏢 多租户使用

租户隔离

每个租户拥有：

✅ 独立的 LightRAG 实例
✅ 隔离的数据存储空间
✅ 独立的向量索引
✅ 专属的知识图谱
✅ 独立的服务配置（LLM、Embedding、Rerank、DeepSeek-OCR、MinerU）🆕

租户配置管理 🆕

每个租户可以独立配置 5 个服务，支持配置热重载：

# 1️⃣ 为租户 A 配置独立的 DeepSeek-OCR API key
curl -X PUT "http://localhost:8000/tenants/tenant_a/config" \
  -H "Content-Type: application/json" \
  -d '{
    "ds_ocr_config": {
      "api_key": "sk-tenant-a-ds-ocr-key",
      "base_url": "https://api.siliconflow.cn/v1",
      "model": "deepseek-ai/DeepSeek-OCR",
      "timeout": 90
    }
  }'

# 2️⃣ 为租户 B 配置独立的 MinerU API token
curl -X PUT "http://localhost:8000/tenants/tenant_b/config" \
  -H "Content-Type: application/json" \
  -d '{
    "mineru_config": {
      "api_token": "tenant-b-mineru-token",
      "base_url": "https://mineru.net",
      "model_version": "vlm"
    }
  }'

# 3️⃣ 同时配置多个服务（LLM + Embedding + DeepSeek-OCR）
curl -X PUT "http://localhost:8000/tenants/tenant_c/config" \
  -H "Content-Type: application/json" \
  -d '{
    "llm_config": {
      "api_key": "sk-tenant-c-llm-key",
      "model": "gpt-4"
    },
    "embedding_config": {
      "api_key": "sk-tenant-c-embedding-key",
      "model": "Qwen/Qwen3-Embedding-0.6B",
      "dim": 1024
    },
    "ds_ocr_config": {
      "api_key": "sk-tenant-c-ds-ocr-key"
    }
  }'

# 4️⃣ 查询租户配置（API key 自动脱敏）
curl "http://localhost:8000/tenants/tenant_a/config"

# 返回示例
{
  "tenant_id": "tenant_a",
  "ds_ocr_config": {
    "api_key": "sk-***-key",  // 自动脱敏
    "timeout": 90
  },
  "merged_config": {
    "llm": {...},        // 使用全局配置
    "embedding": {...},  // 使用全局配置
    "rerank": {...},     // 使用全局配置
    "ds_ocr": {...},     // 使用租户配置
    "mineru": {...}      // 使用全局配置
  }
}

# 5️⃣ 刷新配置缓存（配置热重载）
curl -X POST "http://localhost:8000/tenants/tenant_a/config/refresh"

# 6️⃣ 删除租户配置（恢复使用全局配置）
curl -X DELETE "http://localhost:8000/tenants/tenant_a/config"

支持的配置项：

服务	配置字段	说明
LLM	`llm_config`	模型、API key、base_url 等
Embedding	`embedding_config`	模型、API key、维度等
Rerank	`rerank_config`	模型、API key等
DeepSeek-OCR	`ds_ocr_config`	API key、超时、模式等
MinerU	`mineru_config`	API token、版本、超时等

配置优先级：租户配置 > 全局配置

使用场景：

🔐 多租户 SaaS：每个租户使用自己的 API key
💰 按量计费：通过独立 API key 跟踪租户使用量
🎯 差异化服务：不同租户使用不同的模型（GPT-4 vs GPT-3.5）
🧪 A/B 测试：对比不同模型/参数的效果

使用方式

所有 API 都需要提供 tenant_id 参数：

# 租户 A 上传文档
curl -X POST "http://localhost:8000/insert?tenant_id=tenant_a&doc_id=doc1" \
  -F "file=@doc.pdf"

# 租户 B 上传文档（完全隔离）
curl -X POST "http://localhost:8000/insert?tenant_id=tenant_b&doc_id=doc1" \
  -F "file=@doc.pdf"

# 租户 A 查询（只能查到自己的文档）
curl -X POST "http://localhost:8000/query?tenant_id=tenant_a" \
  -H "Content-Type: application/json" \
  -d '{"query": "文档内容", "mode": "hybrid"}'

实例池管理

容量：最多缓存 50 个租户实例
策略：LRU（最近最少使用）自动清理
配置隔离：每个租户可使用独立的 LLM、Embedding、解析器配置

📊 监控与维护

常用命令

# 查看服务状态
docker compose ps

# 查看实时日志
docker compose logs -f

# 重启服务
docker compose restart

# 停止服务
docker compose down

# 查看资源使用
docker stats

# 清理 Docker 资源
docker system prune -f

维护脚本

# 监控服务健康状态
./scripts/monitor.sh

# 备份数据
./scripts/backup.sh

# 更新服务
./scripts/update.sh

# 性能测试
./scripts/test_concurrent_perf.sh

# 性能监控
./scripts/monitor_performance.sh

健康检查

# 完整健康检查（推荐）
./scripts/health_check.sh
./scripts/health_check.sh --verbose  # 详细输出

# API 健康检查
curl http://localhost:8000/

# 租户统计
curl "http://localhost:8000/tenants/stats?tenant_id=your_tenant"

# 实例池状态
curl "http://localhost:8000/tenants/pool/stats"

🗂️ 项目结构

rag-api/
├── main.py                 # FastAPI 应用入口
├── api/                    # API 路由模块
│   ├── __init__.py         # 路由聚合
│   ├── insert.py           # 文档上传（单/批量）
│   ├── query.py            # 智能查询
│   ├── task.py             # 任务状态查询
│   ├── tenant.py           # 租户管理
│   ├── files.py            # 文件服务
│   ├── models.py           # Pydantic 模型
│   └── task_store.py       # 任务存储
├── src/                    # 核心业务逻辑
│   ├── rag.py              # LightRAG 生命周期管理
│   ├── multi_tenant.py     # 多租户实例管理器
│   ├── tenant_deps.py      # 租户依赖注入
│   ├── logger.py           # 统一日志
│   ├── metrics.py          # 性能指标
│   ├── file_url_service.py # 临时文件服务
│   ├── mineru_client.py    # MinerU 客户端
│   └── mineru_result_processor.py  # 结果处理
├── docs/                   # 文档
│   ├── ARCHITECTURE.md     # 架构设计文档
│   ├── USAGE.md            # 详细使用指南
│   ├── DEPLOY_MODES.md     # 部署模式说明
│   ├── PR_WORKFLOW.md      # PR 工作流程
│   └── ...
├── scripts/                # 维护脚本
│   ├── dev.sh              # 开发模式快捷启动
│   ├── monitor.sh          # 服务监控
│   ├── backup.sh           # 数据备份
│   ├── update.sh           # 服务更新
│   └── ...
├── deploy.sh               # 一键部署脚本
├── docker-compose.yml      # 生产模式配置
├── docker-compose.dev.yml  # 开发模式配置
├── Dockerfile              # 生产镜像
├── Dockerfile.dev          # 开发镜像
├── pyproject.toml          # 项目依赖
├── uv.lock                 # 依赖锁定
├── env.example             # 环境变量模板
├── CLAUDE.md               # Claude AI 指引
└── README.md               # 本文档

🐛 故障排查

常见问题

Q1: 服务启动失败怎么办？

# 查看详细日志
docker compose logs

# 检查端口占用
netstat -tulpn | grep 8000

# 检查 Docker 状态
docker ps -a

Q2: multimodal_processed 错误？

注意：此问题已在 LightRAG 1.4.9.4+ 版本中修复。如果遇到此错误，说明版本过旧。

解决方案：

# 方案 1：升级到最新版本（推荐）
# 修改 pyproject.toml 中的 LightRAG 版本
# lightrag = "^1.4.9.4"

# 重新构建镜像
docker compose down
docker compose up -d --build

# 方案 2：清理旧数据（临时方案）
rm -rf ./rag_local_storage
docker compose restart

Q3: 上传文件返回 400 错误？

检查：

文件格式是否支持（PDF、DOCX、PNG、JPG等）
文件大小是否超过 100MB
文件是否为空

# 查看支持的格式
curl http://localhost:8000/docs

Q3.5: Embedding 维度错误？

如果遇到维度相关错误，需要清理数据并重建：

# 停止服务
docker compose down

# 删除所有 volume（清空数据库）
docker volume rm rag-api_dragonflydb_data rag-api_qdrant_data rag-api_memgraph_data

# 修改 .env 中的 EMBEDDING_DIM
EMBEDDING_DIM=1024  # 或 4096，必须与模型匹配

# 重新启动
docker compose up -d

Q4: 查询速度很慢（>30秒）？

优化建议：

使用 naive 或 hybrid 模式而不是 mix
增加 MAX_ASYNC 参数（在 .env 中）
减小 TOP_K 和 CHUNK_TOP_K
启用 Reranker

# 修改 .env
MAX_ASYNC=8
TOP_K=20
CHUNK_TOP_K=10

Q5: 内存不足（OOM）？

如果使用本地 MinerU：

# 切换到远程模式
# 在 .env 中修改
MINERU_MODE=remote
MINERU_API_TOKEN=your_token

# 或限制并发
DOCUMENT_PROCESSING_CONCURRENCY=1

Q6: 容器重启后任务丢失？

问题现象：

容器重启后无法查询之前的任务状态
租户实例被 LRU 驱逐后任务消失

解决方案：启用 Redis 任务存储

# 修改 .env
TASK_STORE_STORAGE=redis

# 重启服务
docker compose restart

# 验证
docker compose logs api | grep TaskStore
# 应该看到: ✅ TaskStore: Redis connection successful

配置说明：

memory 模式：内存存储，重启后数据丢失（默认，适合开发）
redis 模式：持久化存储，支持容器重启和实例重建（生产推荐）

TTL 策略（Redis 模式自动清理）：

completed 任务：24 小时
failed 任务：24 小时
pending/processing 任务：6 小时

Q7: VLM 模式处理失败？

检查项：

vision_model_func 未配置
- 检查日志：vision_model_func not found, fallback to off mode
- 确保 .env 中配置了 LLM API（豆包）
图片文件不存在
- 检查日志：Image file not found: xxx
- 可能是 MinerU ZIP 损坏或解压失败
超时错误
- full 模式处理大文件可能超时
- 建议：先用 selective 模式，或增加 VLM_TIMEOUT

# 修改 .env
VLM_TIMEOUT=300  # 增加到 5 分钟
RAG_VLM_MODE=selective  # 降级到 selective

调试技巧：

# 查看详细日志
docker compose logs -f | grep VLM

# 测试单个文件
curl -X POST 'http://localhost:8000/insert?tenant_id=test&doc_id=test&vlm_mode=off' \
  -F 'file=@test.pdf'

性能调优建议

场景	MAX_ASYNC	TOP_K	CHUNK_TOP_K	MINERU_MODE
快速响应	8	10	5	remote
平衡模式	8	20	10	remote
高准确度	4	60	20	remote
资源受限	4	20	10	remote

📖 文档

📘 架构设计文档 - 详细的系统架构和设计思路
📗 使用指南 - 完整的 API 使用文档和示例
📙 部署模式说明 - 生产模式 vs 开发模式
📕 PR 工作流程 - 贡献代码的流程指南
📔 外部存储部署 - Redis/PostgreSQL/Neo4j 配置
📊 API 对比分析 - rag-api vs LightRAG 官方 API 对比
🌐 WebUI 集成指南 - 知识图谱可视化集成

🤝 贡献指南

我们欢迎所有形式的贡献！

如何贡献

Fork 项目

git clone https://github.com/BukeLy/rag-api.git
cd rag-api

创建功能分支

git checkout -b feature/your-feature-name

开发和测试

# 安装依赖
uv sync

# 运行测试
uv run pytest

# 代码格式化
uv run black .
uv run isort .

提交代码

git add .
git commit -m "feat: 添加新功能"
git push origin feature/your-feature-name

创建 Pull Request

在 GitHub 上创建 PR，详细描述你的更改。

Commit 规范

使用语义化提交信息：

feat: 新功能
fix: Bug 修复
docs: 文档更新
style: 代码格式
refactor: 代码重构
perf: 性能优化
test: 测试相关
chore: 构建/工具

详见 PR 工作流程文档。

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🙏 致谢

本项目基于以下优秀的开源项目构建：

LightRAG - 高效的知识图谱 RAG 框架
RAG-Anything - 多模态文档解析
MinerU - 强大的 PDF 解析工具
Docling - 轻量级文档解析
FastAPI - 现代化的 Python Web 框架

特别感谢所有贡献者和用户的支持！ 🎉

📬 联系我们

GitHub: @BukeLy
Email: buledream233@gmail.com
Issues: 提交问题
Discussions: 参与讨论

⭐ 如果这个项目对你有帮助，请给个 Star！

Made with ❤️ by BukeLy

Name		Name	Last commit message	Last commit date
Latest commit History 172 Commits
.cursor/rules		.cursor/rules
.github/workflows		.github/workflows
api		api
deploy		deploy
docs		docs
scripts		scripts
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
.python-version		.python-version
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
Dockerfile.dev		Dockerfile.dev
Dockerfile.qdrant		Dockerfile.qdrant
README.md		README.md
deploy.sh		deploy.sh
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
env.example		env.example
main.py		main.py
pyproject.toml		pyproject.toml
ruff.toml		ruff.toml
test_lightrag_doc_status_api.py		test_lightrag_doc_status_api.py
uv.lock		uv.lock

BukeLy/rag-api

Folders and files

Latest commit

History

Repository files navigation