快速开始

本节将帮助你快速了解如何基于 UltraRAG 运行一个完整的 RAG Pipeline。UltraRAG 的使用流程主要包括以下三个阶段：

编写 Pipeline 配置文件
编译 Pipeline 并调整参数
运行 Pipeline

此外，你还可以通过可视化工具对运行结果进行分析与评估。

如果尚未安装 UltraRAG，请先参考环境部署。

如需了解更完整的 RAG 开发实践，请查看完整文档。

Step 1：编写 Pipeline 配置文件

请确保当前工作目录位于 UltraRAG 根目录下

在examples文件夹中创建并编写你的 Pipeline 配置文件，例如：

examples/rag_full.yaml

# Vanilla RAG with Corpus Indexing Demo

# MCP Server
servers:
  benchmark: servers/benchmark
  retriever: servers/retriever
  prompt: servers/prompt
  generation: servers/generation
  evaluation: servers/evaluation
  custom: servers/custom

# MCP Client Pipeline
pipeline:
- benchmark.get_data
- retriever.retriever_init
- retriever.retriever_embed
- retriever.retriever_index
- retriever.retriever_search
- generation.generation_init
- prompt.qa_rag_boxed
- generation.generate
- custom.output_extract_from_boxed
- evaluation.evaluate

UltraRAG 的 Pipeline 配置文件需要包含以下两个部分：

servers：声明当前流程所依赖的各个模块（Server）。例如，检索阶段需要使用 retriever Server。
pipeline：定义各 Server 中功能函数（Tool）的调用顺序。本示例展示了从数据加载、检索编码与索引构建，到生成与评测的完整流程。

Step 2：编译 Pipeline 并调整参数

在运行代码前，首先需要配置运行所需的参数。UltraRAG 提供了快捷的 build 指令，可自动生成当前 Pipeline 所依赖的完整参数文件。系统会读取各个 Server 的 parameter.yaml 文件，解析本次流程中涉及的全部参数项，并统一汇总生成到一个独立的配置文件中。执行以下命令：

ultrarag build examples/rag_full.yaml

执行后，终端将输出如下内容：

系统会在examples/parameters/文件夹下生成对应的参数配置文件。打开文件后，可根据实际情况修改相关参数，例如：

examples/parameters/rag_full_parameter.yaml

benchmark:
  benchmark:
    key_map:
      gt_ls: golden_answers
      q_ls: question
    limit: -1
    name: nq
    path: data/sample_nq_10.jsonl
    seed: 42
    shuffle: false
custom: {}
evaluation:
  metrics:
  - acc
  - f1
  - em
  - coverem
  - stringem
  - rouge-1
  - rouge-2
  - rouge-l
  save_path: output/evaluate_results.json
generation:
  backend: vllm
  backend_configs:
    hf:
      batch_size: 8
      gpu_ids: 2,3
      model_name_or_path: openbmb/MiniCPM4-8B
      trust_remote_code: true
    openai:
      api_key: 'abc'
      base_delay: 1.0
      base_url: http://localhost:8000/v1
      concurrency: 8
      model_name: MiniCPM4-8B
      retries: 3
    vllm:
      dtype: auto
      gpu_ids: 5
      gpu_memory_utilization: 0.5
      model_name_or_path: openbmb/MiniCPM4-8B
      model_name_or_path: Qwen/Qwen3-8B
      trust_remote_code: true
  extra_params:
    chat_template_kwargs:
      enable_thinking: false
  sampling_params:
    max_tokens: 2048
    temperature: 0.7
    top_p: 0.8
  system_prompt: ''
prompt:
  template: prompt/qa_boxed.jinja
  template: prompt/qa_rag_boxed.jinja
retriever:
  backend: sentence_transformers
  backend_configs:
    bm25:
      lang: en
      save_path: index/bm25
    infinity:
      bettertransformer: false
      model_warmup: false
      pooling_method: auto
      trust_remote_code: true
    openai:
      api_key: 'abc'
      base_url: https://api.openai.com/v1
      model_name: text-embedding-3-small
    sentence_transformers:
      sentence_transformers_encode:
        encode_chunk_size: 256
        normalize_embeddings: false
        psg_prompt_name: document
        psg_task: null
        q_prompt_name: query
        q_task: null
      trust_remote_code: true
  batch_size: 16
  collection_name: wiki
  corpus_path: data/corpus_example.jsonl
  embedding_path: embedding/embedding.npy
  gpu_ids: '5'
  index_backend: faiss
  index_backend_configs:
    faiss:
      index_chunk_size: 10000
      index_path: index/index.index
      index_use_gpu: true
    milvus:
      id_field_name: id
      id_max_length: 64
      index_chunk_size: 1000
      index_params:
        index_type: AUTOINDEX
        metric_type: IP
      metric_type: IP
      search_params:
        metric_type: IP
        params: {}
      text_field_name: contents
      text_max_length: 60000
      token: null
      uri: index/milvus_demo.db
      vector_field_name: vector
  is_demo: false
  is_multimodal: false
  model_name_or_path: openbmb/MiniCPM-Embedding-Light
  model_name_or_path: Qwen/Qwen3-Embedding-0.6B
  overwrite: false
  query_instruction: ''
  top_k: 5

你可以根据实际情况修改参数，例如：

将 template 调整为RAG模版 prompt/qa_rag_boxed.jinja；
替换检索器与生成器的 model_name_or_path 为本地下载的模型路径；
若在多 GPU 环境下运行，可修改 gpu_ids 以匹配可用设备。

Step 3：运行 Pipeline

当参数配置完成后，即可一键运行完整流程。执行以下命令：

ultrarag run examples/rag_full.yaml

系统将依次执行配置文件中定义的各个 Server 与 Tool，并在终端中实时输出运行日志与进度信息：

运行结束后，结果（如生成内容、评测报告等）将自动保存在对应的输出路径中，如本例中output/memory_nq_rag_full_20251010_145420.json可直接用于后续分析与可视化展示。

Step 4：可视化分析 Case Study

完成流程运行后，可通过内置的可视化工具快速分析生成结果。执行以下命令启动 Case Study Viewer：

python ./script/case_study.py \
  --data output/memory_nq_rag_full_20251010_145420.json \
  --host 127.0.0.1 \
  --port 8080 \
  --title "Case Study Viewer"

运行成功后，终端会显示访问地址。打开浏览器并输入该地址，即可进入 Case Study Viewer 界面，对结果进行交互式浏览与分析。界面示例如下所示：

小结

至此，你已完成从 Pipeline 配置、参数编译到流程运行与可视化分析的完整 RAG 实践流程。 UltraRAG 通过模块化的 MCP 架构与统一的评测体系，使得 RAG 系统的构建、运行与分析更加高效、直观、可复现。你可以在此基础上：

替换不同的模型或检索器，探索多种组合效果；
自定义新的 Server 与 Tool，扩展系统功能；
利用评测模块快速对比实验结果，开展系统性研究。

开始使用

RAG Servers

RAG Client

开发指南

典型实现

Step 1：编写 Pipeline 配置文件

Step 2：编译 Pipeline 并调整参数

Step 3：运行 Pipeline

Step 4：可视化分析 Case Study

小结

​Step 1：编写 Pipeline 配置文件

​Step 2：编译 Pipeline 并调整参数

​Step 3：运行 Pipeline

​Step 4：可视化分析 Case Study

​小结

Step 1：编写 Pipeline 配置文件

Step 2：编译 Pipeline 并调整参数

Step 3：运行 Pipeline

Step 4：可视化分析 Case Study

小结