youtu-rag

腾讯出品：让 RAG 系统自己决定"怎么找答案"

在企业知识库场景中，传统的 RAG（检索增强生成）系统长期存在一个根本性缺陷：它像一个只会"背课文"的学生——无论用户问什么问题，它都走同样的流程：切分文档、向量化、向量检索、拼接生成。这种僵化的处理方式，在面对"上个月销售报表里毛利率是多少"、"对比竞品 A 和 B 的技术方案差异"这类需要动态判断的问题时，往往力不从心。

Youtu-RAG 是腾讯云 AI 平台团队（TencentCloudADP）开源的新一代 Agentic RAG 系统。与传统 RAG 不同，它给 AI 装上了"决策大脑"——让 Agent 自主判断是否需要检索、以什么方式检索、从哪个数据源检索，以及是否需要调用记忆模块。这种"自主决策 + 记忆驱动"的范式，代表了 RAG 系统进化的新方向。

---

一、背景与起源：从"被动检索"到"主动决策"

RAG（Retrieval-Augmented Generation，检索增强生成）技术自 2020 年被提出以来，已成为大模型落地企业知识库的事实标准。然而，传统 RAG 系统存在三大痼疾：

1. 隐私风险：调用第三方 API 时，企业内部文档数据必须上传到外部服务器，存在数据泄露隐患
2. 记忆缺失：每次对话都是"从零开始"，无法积累跨会话的知识和经验
3. 检索僵化：无论问题类型，一律走"向量化检索"一条路，无法根据实际需求灵活选择策略

Youtu-RAG 由腾讯云 AI 平台团队开发，核心作者为 felixyfyu（腾讯内部员工）。项目以 "Local Deployment · Autonomous Decision · Memory-Driven"（本地部署 · 自主决策 · 记忆驱动）为设计理念，目标是将 RAG 系统从被动检索工具升级为具有自主决策能力的智能助手。值得关注的是，该项目明确支持本地部署，数据全程不出域，满足企业对数据安全的刚性需求。

---

二、核心能力：双层记忆 + 自主决策 Agent

2.1 自主决策引擎（Adaptive Retrieval Engine）

Youtu-RAG 的 Agent 不再盲目执行固定流程，而是根据问题类型、历史对话上下文，动态决定：

• 是否需要检索：简单的事实性问题可能直接回答，无需检索
• 采用什么检索策略：向量检索、元数据过滤、数据库 SQL 查询、网页搜索等，按需选择
• 是否调用记忆模块：根据历史经验判断是否有相似问题的处理模式

这种决策能力依托于 OpenAI Agents SDK（版本 0.3.3）实现，支持 Tool Calling、Function Calling 等标准 Agent 交互协议。

2.2 双层记忆机制（Dual-Layer Memory）

Youtu-RAG 实现了业界少见的双层记忆架构：

• 短时记忆（Short-Term Memory）：单次会话内的对话上下文，用于维持多轮对话连贯性
• 长时记忆（Long-Term Memory）：跨会话知识积累，记住之前处理过的类似问题和最佳答案

长时记忆通过 MySQL 数据库持久化存储，支持 Q&A 经验学习——当 Agent 成功解决一个问题后，相关模式会被记录，在遇到类似场景时自动复用。

2.3 多格式文件解析

项目采用"文件即知识"的架构设计，支持超过 16 种文件格式：

类别	支持格式
文档	PDF、Word、Markdown、纯文本
表格	Excel（.xlsx/.xls）、CSV
图片	PNG、JPG（配合 OCR 解析）
演示	PowerPoint（.pptx）
数据库	MySQL、SQLite（直连查询）

文档解析层集成了 pymupdf（PDF）、openpyxl（Excel）、python-docx（Word）、python-pptx（PPT）等主流库，确保解析质量。

---

三、技术架构：分层模块化设计

Youtu-RAG 的核心代码位于 utu/ 目录，采用清晰的分层架构：

utu/
├── agents/          # Agent 核心（Orchestrator、Workforce、Orchestra）
├── rag/             # RAG 引擎
│   ├── api/         # FastAPI 后端（main.py → uvicorn 启动）
│   ├── document_loaders/  # 文档加载器
│   ├── embeddings/        # 向量化（tiktoken + ChromaDB/FAISS）
│   ├── knowledge_builder/ # 知识库构建
│   ├── knowledge_retrieval/ # 检索模块
│   ├── rag_tools/   # RAG 工具集
│   └── rerankers/   # 重排序
├── context/         # 短时记忆管理
├── db/              # 数据库（MySQL/SQLite）
├── env/             # 环境配置
├── models/          # LLM 接口封装
├── prompts/         # Prompt 模板
└── ui/              # Web UI 路由

关键依赖：

• FastAPI（后端框架）：提供 REST API + WebSocket 流式响应
• OpenAI Agents SDK（Agent 运行时）：支持多 Agent 协作编排
• LangGraph（工作流编排）：管理复杂 Agent 协作逻辑
• ChromaDB / FAISS（向量数据库）：支持本地化向量检索
• MinIO（对象存储）：本地文件管理，满足数据不出域需求

后端启动入口为 utu.rag.api.main:app，通过 uv run uvicorn 在 start.sh 中一键启动。Web UI 位于 frontend/rag_webui/，采用纯原生 HTML/CSS/JavaScript 实现，零前端框架依赖。

---

四、内置 Agent 生态：开箱即用的 8+ 智能体

Youtu-RAG 预置了 8 个以上可直接调用的 Agent，覆盖常见企业知识库场景：

Agent	能力
Web Search Agent	联网搜索，结合 RAG 结果综合回答
KB Search Agent	知识库向量检索
Meta Retrieval Agent	基于元数据的精准过滤检索
Excel Agent	Excel 数据分析与问答
Text2SQL Agent	自然语言转 SQL，查询数据库
Orchestrator Agent	任务编排，协调多个子 Agent 协作
Workforce Agent	批量任务执行
Orchestra Agent	多 Agent 交响乐模式，复杂任务分解

---

五、部署实践：从零到上线

5.1 环境准备

# Python >= 3.12
python --version  # 确认 Python 3.12+

# 安装 uv（推荐）或 pip
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# 复制环境变量配置
cp .env.example .env
# 编辑 .env，填入 LLM API Key、数据库配置等

5.2 配置文件

核心配置位于 configs/ 目录：

• configs/model/base.yaml：LLM 模型配置（支持 OpenAI、Google GenAI 等）
• configs/rag/default.yaml：RAG 默认检索参数
• configs/rag/file_management.yaml：文件解析（OCR、Chunk）配置
• configs/agents/*：各 Agent 的 prompt 和工具配置

5.3 启动服务

# 一键启动（自动加载 .env）
bash start.sh

# 访问地址
# 前端界面：http://localhost:8000
# 监控面板：http://localhost:8000/monitor

注意：项目不提供 Dockerfile 或 docker-compose，需要手动配置 Python 环境和数据库。对于没有 Docker 使用经验的用户，有一定门槛。

---

六、局限与争议

坦诚地说，Youtu-RAG 并非完美方案：

1. 没有容器化支持：缺少 Dockerfile/docker-compose，生产环境部署需要自行编写容器化脚本，增加了 DevOps 工作量
2. 数据库依赖：需要额外部署 MySQL 或 SQLite，对轻量级使用场景略显繁琐
3. Python 3.12 门槛：依赖 openai-agents==0.3.3 等较新库，可能与部分现有环境冲突
4. 国产模型支持：当前主要针对 OpenAI、Google GenAI 设计，本地开源模型（如 Qwen、DeepSeek）的接入文档较少

---

七、行业意义与趋势

Youtu-RAG 的出现，折射出 RAG 技术演进的两个重要趋势：

趋势一：从"检索工具"到"Agent 系统"的升级。传统 RAG 正在向 Agentic RAG 演进，Youtu-RAG 是这一趋势的典型代表。当 Agent 能够自主判断何时检索、检索什么、如何利用检索结果时，系统的智能度和实用性将大幅提升。

趋势二：数据主权需求的崛起。随着企业对数据安全的重视，支持本地部署、数据不出域的 RAG 方案将更受欢迎。Youtu-RAG 内置 MinIO 对象存储，正是这一趋势的体现。

GitHub 地址：https://github.com/TencentCloudADP/youtu-rag 文档地址：https://youtu-rag-docs.vercel.app