UltraRAG：基于 MCP 和 YAML 配置的 RAG 框架实践

UltraRAG 是一个面向 RAG（Retrieval-Augmented Generation，检索增强生成）的开源框架，由清华 THUNLP、东北大学 NEUIR、OpenBMB 等团队联合推出。它的重点不只是“把文档塞进向量库再问答”，而是把 RAG 系统里的检索、重排、生成、评估、语料构建等环节拆成标准化组件，再通过 MCP（Model Context Protocol，模型上下文协议）连接起来。

它解决的核心麻烦是：复杂 RAG 系统通常要写很多胶水代码。文档解析、切分、索引、检索、重排、大模型调用、结果评估，每个环节都可能换工具、换模型、换参数。UltraRAG 的做法是把这些环节变成可组合的 MCP Server，再用 YAML 配置声明 Pipeline，让实验流程更容易复现，也更容易替换其中某个模块。

项目地址和相关资源：

代码仓库：https://github.com/OpenBMB/UltraRAG
教程文档：https://ultrarag.openbmb.cn/
数据集：https://modelscope.cn/datasets/UltraRAG/UltraRAG_Benchmark

RAG 系统到底在解决什么问题

大语言模型本身会根据训练时学到的知识生成答案，但它有几个天然限制：

问题	表现	RAG 的处理方式
知识不够新	模型不知道最新文档、内部知识库、企业制度	回答前先检索外部知识
容易编造	没有依据时仍可能生成看似合理的内容	把检索到的证据交给模型
私有数据无法直接进入模型	企业资料、论文、报告不在训练集中	建立本地知识库或私有索引
长文档难一次性塞进上下文	PDF、书籍、网页太长	切分、索引、按问题召回片段

典型 RAG 流程可以画成这样：

flowchart LR
    A[用户问题] --> B[查询改写或问题理解]
    B --> C[检索器 Retriever]
    C --> D[候选文档片段]
    D --> E[重排器 Reranker]
    E --> F[高相关证据]
    F --> G[大模型 Generator]
    G --> H[带依据的回答]

    I[(知识库)] --> C
    J[文档解析与切分] --> I

一个最小可用的 RAG 系统通常包含三条链路：

语料构建链路：把 PDF、Word、网页、电子书等资料解析成统一格式，再切成适合检索的小块。
在线问答链路：用户提问后，从知识库里召回相关内容，再交给大模型生成答案。
评估分析链路：对检索命中率、回答准确性、引用证据等指标做评估，方便调参和对比实验。

UltraRAG 的价值就在于把这些链路标准化，而不是让每个项目都从零拼一套脚手架。

UltraRAG 的核心设计：RAG 组件 MCP Server 化

MCP 可以理解为大模型应用和外部工具之间的一套通信规范。模型应用不需要直接知道某个工具的内部实现，只要按照协议调用工具暴露出来的能力即可。

UltraRAG 把 RAG 里的关键组件封装成独立 MCP Server，每个 Server 对外提供函数级 Tool 接口。MCP Client 负责读取 YAML 配置，并按照配置把这些工具串成一条 Pipeline。

flowchart TB
    Y[YAML Pipeline 配置] --> C[MCP Client / Pipeline Runner]

    C --> P[Parser MCP Server<br/>文档解析与切分]
    C --> R[Retriever MCP Server<br/>文本/图像检索]
    C --> K[Reranker MCP Server<br/>候选结果重排]
    C --> G[Generator MCP Server<br/>大模型生成]
    C --> E[Evaluator MCP Server<br/>评估与指标统计]
    C --> V[Case Study Viewer<br/>结果浏览与分析]

    P --> KB[(知识库 / 索引)]
    KB --> R
    R --> K
    K --> G
    G --> E
    E --> V

这种结构有两个直接好处。

一是组件可以替换。比如检索器从向量检索换成混合检索，或者生成模型从一个 LLM（Large Language Model，大语言模型）换成另一个模型，理论上只需要调整对应模块的配置，而不是改完整业务代码。

二是实验可以复现。RAG 实验最怕“代码里藏了参数”，比如 chunk size、top-k、rerank 模型、prompt 模板、评估指标都散落在脚本里。UltraRAG 倾向于把这些选择写进 YAML，方便保存、比较和复跑。

YAML 配置在 RAG Pipeline 里负责什么

YAML（YAML Ain't Markup Language，一种常见配置文件格式）适合描述层级结构。UltraRAG 用它声明一个 RAG Pipeline，包括数据来源、解析方式、检索器、生成模型、评估任务等。

可以把 YAML 配置看成一份“实验说明书”：

# 这是简化后的结构示意，用来说明 UltraRAG 配置驱动的思想。
# 实际字段以官方文档为准。

pipeline:
  name: paper_qa_demo

data:
  source:
    type: pdf
    path: ./data/attention_is_all_you_need.pdf

parser:
  engine: mineru
  split:
    chunk_size: 512
    chunk_overlap: 64

index:
  type: vector
  embedding_model: your-embedding-model
  output_dir: ./indexes/paper_qa_demo

retriever:
  top_k: 20

reranker:
  enabled: true
  top_k: 5

generator:
  model: your-llm
  prompt_template: ./prompts/qa_with_citations.txt

evaluation:
  enabled: true
  metrics:
    - retrieval_recall
    - answer_quality

真正运行时，配置文件会驱动多个步骤：

flowchart LR
    A[编写 YAML 配置] --> B[编译 Pipeline]
    B --> C[检查组件与参数]
    C --> D[构建知识库]
    D --> E[运行问答]
    E --> F[生成结果]
    F --> G[评估与可视化分析]

这不代表完全不需要工程配置。模型 API Key、GPU 环境、依赖安装、数据路径、向量库位置仍然要准备好。UltraRAG 降低的是 RAG 流程编排和实验切换的成本，而不是替代所有部署工作。

2.1 版本的三个重点能力

UltraRAG 2.1 主要强化了多模态、知识接入和统一工作流。

原生多模态：文本、图像、PDF 版面一起处理

传统 RAG 通常只处理纯文本。PDF 里的表格、公式、图表、多栏排版经常会在解析阶段丢失信息，导致模型回答时只能看到不完整的文本。

UltraRAG 的多模态能力把文本和图像纳入同一套框架，尤其是 VisRAG Pipeline 可以支持从 PDF 到多模态问答的闭环。

flowchart LR
    A[PDF 文档] --> B[PDF 解析]
    B --> C[文本内容]
    B --> D[页面图像]
    B --> E[表格 / 公式 / 图表布局]

    C --> F[文本索引]
    D --> G[视觉索引]
    E --> H[结构化信息]

    I[用户问题] --> J[多模态检索]
    F --> J
    G --> J
    H --> J

    J --> K[相关页面与片段]
    K --> L[多模态生成模型]
    L --> M[答案]

这类设计适合处理论文、咨询报告、技术白皮书、财报等文档。比如用户问“论文中的表 4 说明了什么”，系统不能只看正文段落，还需要定位到表格所在页面，并理解表格内容。多模态 RAG 的意义就在这里。

知识接入与语料构建自动化

构建 RAG 知识库时，最耗时的环节常常不是检索，而是“把资料变成可检索语料”。

UltraRAG 支持多格式文档解析，例如 Word、电子书、网页存档等，并提供自动分块能力。对于 PDF，它集成了 MinerU，用来处理复杂版面、多栏结构、表格和图文混排。

常见文档处理差异如下：

文档类型	主要难点	UltraRAG 侧重点
普通文本	内容长、需要合理切分	自动分块、统一格式
Word	标题层级、列表、表格	保留结构后构建语料
PDF	多栏、页眉页脚、公式、图表	MinerU 解析与版面还原
报告/论文	图表和正文互相引用	文本与页面图像共同检索
网页存档	HTML 噪声、导航栏、广告区域	清洗后进入知识库

PDF 解析尤其重要。很多 RAG 效果差不是因为模型不行，而是解析阶段把关键信息弄丢了。比如表格被拆成乱码，公式被忽略，多栏正文顺序错乱，都会直接影响最终回答。

统一工作流：检索、生成、评估放进同一套 Pipeline

RAG 不是只要能回答就结束。想要真正调优，需要回答这些问题：

检索阶段有没有找到正确证据？
top-k 取多少合适？
是否需要 rerank？
哪个解析器对 PDF 效果更好？
哪个生成模型更稳定？
回答有没有引用到正确来源？
多模态任务中，视觉信息有没有被用上？

UltraRAG 把检索、生成、评估串成统一流程，适合做实验对比。

flowchart TB
    A[实验配置 A<br/>检索器 1 + 模型 1] --> E[统一评估]
    B[实验配置 B<br/>检索器 2 + 模型 1] --> E
    C[实验配置 C<br/>检索器 1 + 模型 2] --> E
    D[实验配置 D<br/>不同 PDF 解析策略] --> E

    E --> F[指标对比]
    E --> G[Case Study Viewer]
    G --> H[逐条查看问题、证据、回答]

对于研究和内部评测来说，这比手工写多个脚本更容易管理。

两个典型使用场景

论文问答：理解表格、公式和正文关系

以《Attention is All You Need》这类论文为例，用户可能会问：

论文中的表 4 具体说了什么？请结合上下文解释它的含义。

普通文本 RAG 可能只能召回表格附近的文字，表格本体如果解析失败，模型就无法准确解释。多模态 Pipeline 会同时利用页面图像、表格结构和正文内容，让答案更接近人类阅读 PDF 时的方式。

关键流程如下：

sequenceDiagram
    participant U as 用户
    participant P as UltraRAG Pipeline
    participant R as 多模态检索器
    participant M as 生成模型

    U->>P: 提问：表 4 说明什么？
    P->>R: 检索文本片段和页面图像
    R-->>P: 返回表格所在页面、相关正文
    P->>M: 组织证据和问题
    M-->>P: 生成解释性答案
    P-->>U: 返回答案与依据

咨询报告问答：结合图表和正文总结结论

麦肯锡《生成式人工智能的经济潜力》这类报告往往包含大量图表。用户可能会问：

生成式 AI 最有潜力影响哪些企业职能？请结合图表和正文说明它们对组织生产力的影响。

这类问题不能只抽取一句话。系统需要从多个页面中检索相关图表、图注、段落，再把它们合成一个结构化回答。多模态 RAG 的优势在于可以把图表作为证据来源之一，而不是只依赖 OCR 后的零散文字。

适合和不适合的场景

场景	是否适合 UltraRAG	原因
快速搭建 RAG 实验 Pipeline	适合	YAML 配置能减少脚本编排成本
论文、报告、财报问答	适合	多模态和 PDF 解析能力有用
需要比较多个检索器、模型、参数	适合	配置化流程便于复现和评估
企业内部知识库原型验证	适合	多格式文档接入能缩短准备时间
只做一个极简单的 FAQ Bot	不一定适合	直接用轻量向量库和 LLM SDK 可能更快
对线上延迟极度敏感的生产系统	需要二次工程化	MCP 调用、重排、多模态处理都可能增加链路耗时
已有成熟 RAG 平台且流程固定	不一定适合	迁移成本可能高于收益

UltraRAG 更像一个面向复杂 RAG 实验和多模态文档问答的框架，而不是一个“一键上线所有场景”的成品系统。

上手流程

UltraRAG 支持 Conda 环境和 Docker 两类部署方式。实际命令要以仓库和官方文档为准，常见流程大致如下。

使用 Conda 准备环境

git clone https://github.com/OpenBMB/UltraRAG.git
cd UltraRAG

conda create -n ultrarag python=3.10
conda activate ultrarag

pip install -r requirements.txt

如果涉及本地大模型、向量模型或多模态模型，还需要根据模型要求准备 GPU 驱动、CUDA、模型权重或 API Key。

使用 Docker 部署

git clone https://github.com/OpenBMB/UltraRAG.git
cd UltraRAG

# 具体 Dockerfile、compose 文件名以仓库为准
docker build -t ultrarag .
docker run --rm -it ultrarag

Docker 的优势是环境更容易固定，适合复现实验；Conda 更适合本地调试和修改源码。

运行一个 Pipeline

使用 UltraRAG 时，核心动作可以压缩成三步：

准备知识源和模型配置。
编写 YAML Pipeline。
编译并运行 Pipeline，查看生成结果和评估结果。

官方快速开始文档：

https://ultrarag.openbmb.cn/pages/cn/getting_started/quick_start

一个实践项目里，目录可以按这种方式组织：

rag-demo/
├── data/
│   └── report.pdf
├── configs/
│   └── report_qa.yaml
├── prompts/
│   └── qa_with_evidence.txt
├── indexes/
└── outputs/

这种结构的好处是数据、配置、提示词、索引和输出彼此分离。后续要比较不同模型或不同检索参数，只需要增加新的 YAML 配置，而不是复制一堆脚本。

Case Study Viewer 适合排查什么问题

UltraRAG 内置 Case Study Viewer，用来交互式浏览实验结果。它的价值不是“看起来更直观”，而是帮助定位 RAG 链路里到底哪一步出了问题。

常见排查方式：

现象	可能原因	排查点
回答不相关	检索没召回正确内容	查看 top-k 文档片段
回答漏掉图表信息	PDF 图像或表格没有进入检索链路	检查解析结果和多模态索引
答案有依据但表达混乱	Prompt 或生成模型不合适	对比不同 prompt 模板
检索结果很多但噪声大	chunk 太碎或检索器不合适	调整分块参数、增加 rerank
实验结果波动	参数没有固定或模型调用不稳定	固化 YAML、保存输出和评估记录

RAG 调优不能只看最终答案，必须看中间证据。Viewer 的作用就是把问题、检索结果、生成答案和评估信息放在一起，方便逐条分析。

使用时需要注意的坑

YAML 降低编排成本，但不等于没有工程成本

配置化可以减少胶水代码，但系统仍然依赖模型服务、文档解析工具、向量索引、存储路径和运行环境。尤其是多模态 Pipeline，对显存、解析速度和模型能力都有更高要求。

PDF 解析质量会直接影响问答质量

如果 PDF 解析阶段把多栏正文顺序打乱，或者表格被拆坏，后面的检索和生成很难补救。处理论文、报告、财报时，应该先抽样检查解析结果，而不是直接批量入库。

多模态 RAG 成本更高

文本检索通常比较快，多模态检索和页面图像理解会带来额外计算成本。对线上应用来说，需要在准确率、延迟和成本之间做取舍。

评估指标要和业务问题对应

通用 Benchmark 能帮助比较模型和检索器，但企业知识库、论文问答、报告解读的评价重点并不相同。比如论文问答更关注证据定位和解释准确性，企业制度问答更关注可追溯和低幻觉率。

MCP 化组件适合扩展，但要关注链路稳定性

把组件拆成 MCP Server 后，每个模块更容易替换，也更容易独立调试。但组件越多，链路中的网络调用、序列化、错误处理和版本兼容问题也越多。生产环境需要补充日志、重试、超时控制和监控。

小结

UltraRAG 的核心思路是把 RAG 系统拆成标准化组件，通过 MCP 连接，再用 YAML 描述完整 Pipeline。它适合做复杂 RAG 实验、多模态 PDF 问答、知识库构建和评估对比。

如果目标是处理大量论文、报告、图表型 PDF，或者需要频繁比较不同检索器、生成模型和参数组合，UltraRAG 的配置化工作流会很有帮助。若只是搭一个简单问答 Demo，轻量级向量库加模型 API 可能更直接。对于严肃的 RAG 项目，UltraRAG 更适合作为实验与原型框架，再根据线上要求补齐工程化能力。

菜单