aigc-apps/PAI-RAG · 上手攻略

仓库：aigc-apps/PAI-RAG
链接：https://github.com/aigc-apps/PAI-RAG
分类：RAG · Agentic-RAG · enterprise
作者：Tom
更新：2026-08-13

它是什么

PAI-RAG 是基于阿里云 PAI 平台的开源 Agentic RAG 框架，定位"5 分钟构建企业级 Agentic RAG 应用"。它不只是一个检索增强生成系统，而是一站式平台：知识库管理 + 多模态理解（图片/视频） + ReAct 智能体 + MCP 工具生态 + 任务规划 + 联网搜索 + Text-to-SQL。

核心架构：FastAPI 后端 + Next.js Web UI + ReAct Agent Engine（内置 KB检索 / 联网搜索 / 代码沙箱 / T2SQL / MCP 客户端 / 附件解析工具）。

⚠️ 注意：后端默认监听 localhost:8680（Web UI）和 localhost:8682（API），生产部署推荐 EAS 一键部署。默认使用 sqlite 元数据库，生产环境建议切换 PostgreSQL。

解决什么问题

传统 RAG 的局限：单文件上传 + 固定切片 + 纯向量检索 + 简单问答。PAI-RAG 解决了五个维度：

多模态：20+ 文档格式（PDF/Office/图片/视频），图片问答 + 视频关键帧提取
复杂任务：ReAct 框架 + 任务规划，自动拆解"对比 2023 年财报与行业趋势"这类多步骤查询
检索质量：向量 + 全文 + 混合检索（BM25） + Reranker 精排
工具生态：MCP 客户端（接入任意 MCP 服务器）+ MCP 服务端（将知识库暴露为 MCP 工具）
企业能力：多租户隔离 + RBAC 权限 + OpenTelemetry 全链路追踪

快速安装

Docker 一键启动（推荐新手）

git clone https://github.com/aigc-apps/PAI-RAG.git
cd PAI-RAG/docker
cp .env.example .env
# 编辑 .env 配置 API key 和数据库
docker compose up -d
# 访问 http://localhost:8680

本地 Poetry 安装

# Python 3.11 环境
conda create -n pai-rag python=3.11 && conda activate pai-rag
pip install poetry && poetry install
cp .env.example .env
# 编辑 .env 后
./scripts/start.sh --dev

⚠️ 前置依赖：Redis（docker compose 已含；本地安装需单独启动）。环境变量必填项：DASHSCOPE_API_KEY（通义千问）或 OPENAI_API_KEY。

核心用法

Docker 环境变量（必填）

# 向量库选型
VECTOR_DB_TYPE=local          # local / milvus / elasticsearch / postgresql / hologres / opensearch / tablestore

# 模型（通义千问）
DASHSCOPE_API_KEY=sk-xxxxxxxx

# 或 OpenAI（兼容接口）
OPENAI_API_KEY=sk-xxxxxxxx
OPENAI_BASE_URL=https://api.openai.com/v1

# GPU 加速（需要 NVIDIA GPU + CUDA）
USE_CUDA=true

# 高级 PDF 解析（需要 MinerU）
ENABLE_MINERU=false

API 调用示例

# Chat Completions（流式）
curl http://localhost:8682/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-plus",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

# 知识库检索
curl -X POST http://localhost:8682/v1/retrieval \
  -H "Content-Type: application/json" \
  -d '{"query": "产品特性", "knowledgebase_id": "xxx", "top_k": 5}'

ReAct 工具调用

Agent 默认 20 步推理（MAX_RECURSION_STEPS=20），内置工具：

工具	说明
知识库检索	对配置的知识库进行 RAG 检索
联网搜索	阿里云 IQS 或 Tavily
网页浏览	访问并解析指定 URL
代码沙箱	云端 Python 沙箱，数据分析和图表生成
Text-to-SQL	自然语言查询 MySQL / PostgreSQL
附件解析	读取分析上传的文件
思考推理	结构化反思与推理
任务规划	复杂多步骤任务分解

多租户与 RBAC

# 多租户隔离：所有资源按 tenant_id 隔离
# RBAC 三级：用户 → 角色 → 文档，精确到 Chunk 级别访问控制
# 配置项（.env）：
# MULTI_TENANT_ENABLED=true
# RBAC_ENABLED=true

典型适用场景

企业知识库问答：内部文档 / 财报 / 手册上传，多租户隔离，精确权限控制
复杂分析任务：财务对比分析、市场调研（ReAct + T2SQL + 代码沙箱）
多模态客服：用户上传截图 / 产品图，AI 理解图片内容后结合知识库回答
联网实时问答：结合 IQS/Tavily 联网搜索，回答需要最新信息的问题
AI Agent 工具后端：将知识库检索暴露为 MCP 工具，供外部 Claude / GPT 等 Agent 调用

坑与注意

坑	说明
向量库选型	`local`（Chroma）仅向量检索；生产建议 Milvus / Elasticsearch（向量 + 全文 + 混合）
PDF 解析质量	默认解析质量有限；`ENABLE_MINERU=true` 需额外配置
Python 版本	必须 3.11+（poetry install 会检查）
Redis 必须启动	`./scripts/start.sh` 依赖 Redis，本地需先启动 `redis-server`
多租户需配置	`MULTI_TENANT_ENABLED=true` 需配合 PostgreSQL；sqlite 不支持生产多租户
EAS 部署依赖阿里云	一键部署只能到阿里云 PAI-EAS，其他云需 docker 手动部署

⚠️ 风险边界：MCP 服务端将知识库暴露为工具时，需注意权限控制（RBAC 需开启）。联网搜索默认走阿里云 IQS 或 Tavily，Tavily 需自备 API key。代码沙箱执行 Python 代码，生产环境建议配网络隔离。

与同类对比

维度	传统 RAG（LangChain RAG）	PAI-RAG
文档格式	PDF / TXT	20+（含视频/图片）
检索模式	向量	向量 + 全文 + 混合 + Rerank
任务类型	简单问答	ReAct 多步推理
工具生态	无	MCP 客户端 + 服务端 + 代码沙箱 + T2SQL
多模态	无	图片理解 + 视频解析
企业能力	需自建	多租户 + RBAC + OpenTelemetry
部署	复杂	Docker 一键 / EAS 一键

类似框架：Dify（更偏无代码流程编排）、FastGPT（中文优化但工具生态较弱）、LangGraph（更灵活但需更多配置）。PAI-RAG 优势在阿里云 PAI 生态集成 + 企业级开箱即用。

一句话推荐结论

如果你在阿里云 PAI 生态内、需要快速搭企业级 Agentic RAG，选 PAI-RAG；如果你的 Agent 需要 MCP 工具生态 + 多模态 + 复杂推理，同时不想从 LangChain 开始手写，选 PAI-RAG。如果只需要轻量 RAG 或完全自建，LangChain / LangGraph 更灵活。

原始仓库：https://github.com/aigc-apps/PAI-RAG