# RAGView

RAGView 用于基于真实业务数据评测和选择 RAG 方案，帮助您无需复杂部署，即可快速对比不同 RAG 路线在检索质量、回答表现、响应速度和资源消耗等维度的差异，选出更适合自身业务场景的方案。

RAGView 目前提供以下核心模块：

- **RAG 空间**：展示平台已接入、可评测的 RAG 路线，支持查看路线详情并进入评测。
- **RAG 竞技场**：上传文档、添加多条 RAG 路线后进行同题对比，直观查看各路线的回答结果与运行指标。
- **文档集**：管理评测用的知识库文档，可作为评测任务的数据来源，并支持从文档集自动生成评测集。
- **评测集**：管理评测用的题目数据，支持上传、自动生成、编辑与导出。
- **评测任务**：对评测集逐题执行多条 RAG 路线的检索、生成与评估，产出指标统计、逐题明细与可下载的评测报告。
- **评估器**：查看平台预置的全部评测指标及其定义与计算逻辑。

> 评测过程会使用模型和应用沙箱资源，将按照实际资源用量计费。

## 支持范围

- 当前支持对平台已适配并标注为「可评测」的 RAG 路线进行在线评测，路线及版本以「RAG 空间」页面展示为准。
- 文档集限时免费，最多 10 个，每个文档集最多 100M；文档集与竞技场支持 PDF、DOC、DOCX、TXT、MD、XLS、XLSX 格式，单文件不超过 10MB。
- 评测集限时免费，最多 10 个，每个评测集最多 10000 行；支持上传 xlsx、json 文件，单文件不超过 100MB。
- 单个评测任务与竞技场单轮对比均最多添加 4 条 RAG 路线。
- 评测结果保留 90 天，请及时查看或下载报告。

## 准备工作

在使用 RAGView 前，请确认：

1. 项目下已创建可用的 API Key，且该 Key 拥有沙箱权限和所需文本模型及 Embedding 模型的调用权限。
2. 账户余额满足评测所产生的模型及沙箱资源费用。
3. 已准备包含知识库文档的文档集，以及包含题目数据的评测集；两者均可在新建评测任务时直接创建。

## 快速开始

RAGView 提供两种评测方式，可按场景选择：

| 方式 | 适用场景 | 特点 |
| --- | --- | --- |
| RAG 竞技场 | 快速验证单条问题 | 即时执行，同题对比多条路线的回答与指标，不产出报告 |
| 评测任务 | 批量评测与横向选型 | 对评测集逐题执行，产出指标统计、逐题明细与可下载的评测报告 |

使用 **评测任务** 的完整流程如下：

| 步骤 | 操作 | 说明 |
| --- | --- | --- |
| 01 | 准备文档集 | 上传文档作为知识库来源，可从文档集自动生成评测集 |
| 02 | 准备评测集 | 上传题目文件，或使用文档集自动生成的评测集 |
| 03 | 创建评测任务 | 填写任务名称与 API Key，添加最多 4 条 RAG 路线 |
| 04 | 选择数据与指标 | 选择文档集、评测集，勾选评估指标与评估模型 |
| 05 | 查看结果 | 在任务详情页查看指标统计与逐题明细 |
| 06 | 下载报告 | 任务完成后下载评测报告 |

## 浏览 RAG 空间

进入 **模型服务平台 > 应用探索 > RAGView**，默认展示 **RAG 空间** 页面。

页面以卡片形式展示平台已上线的 RAG 路线，每张卡片包含：

| 信息 | 说明 |
| --- | --- |
| 路线名称 / 版本 | RAG 路线标识及当前最新可用版本 |
| 简介 | 路线的使用场景和技术特点 |
| 开源状态 | 展示是否已开源；开源路线同时展示开源协议、来源（GitHub）和 Stars 数 |
| 可评测标记 | 标记「可评测」的路线可直接发起评测 |

## 使用 RAG 竞技场评测

点击进入 **RAG 竞技场** 标签页。竞技场用于对多条 RAG 路线进行单题对比，评估回答差异。

### 1. 上传文档

在左侧「文档」区域，单击 **选择文档** 上传一份文档，作为本轮评测的知识库来源。

- 支持 PDF、DOC、DOCX、TXT、MD、XLS、XLSX，单文件不超过 10MB。
- 上传过的文档会保留在 **历史文档** 中（最多保留最近上传的 10 个），可查看并删除其中的历史文件。
- 提问时将对当前文档生成快照，之后更换文档不影响已提交的问答结果。

> 竞技场上传的文档独立保存，不会出现在 **文档集** 列表中；**文档集** 中的文件也不会自动出现在竞技场。

> 文档内容将传入云端沙箱用于构建知识库。请避免上传包含明文密钥、个人敏感信息的文件。

### 2. 配置评估器（可选）

在左侧「评估器」区域勾选需要计算的评测指标，并可指定 **评估器 LLM 模型** 与 **评估器 Embedding 模型**。

如需指标评测，当前仅支持平台预置的评估器，各指标的详细定义与计算逻辑可在「评估器」页面查看。部分评估指标需要依赖 LLM 模型、Embedding 模型、参考答案和参考上下文。

### 3. 添加 RAG 路线

在右侧「对战区」单击 **添加路线**，从可评测路线中选择要对比的路线，最多可添加 4 条路线。

添加后，每条路线以独立卡片展示，可查看路线名称与版本，并支持单独删除。

### 4. 提问并对比结果

在页面底部输入框输入测试问题并发送，所有已添加路线将并行执行检索和问答。提问后会使用模型和沙箱资源，将以实际资源用量计费。

评测过程中，每条路线卡片顶部实时展示运行状态（运行中 / 已完成 / 运行失败），执行中展示当前阶段日志。

运行完成后，每条路线卡片展示：

| 信息       | 说明                                             |
| -------- | ---------------------------------------------- |
| 生成回答     | 该路线针对问题生成的完整回答，支持 Markdown 排版                  |
| TTFT     | 首 Token 延迟，从发起请求到返回首个 Token 的耗时                |
| 总用时      | 本次问答的执行总耗时                                     |
| Token 用量 | 本次问答消耗的 Token 总数                               |
| 召回上下文    | 该路线本次检索到的上下文片段数，单击可展开查看内容明细                    |
| 评估器得分    | 各勾选评估器对本条回答的评分明细                               |
| 错误信息     | 若运行失败，展示失败原因（如 inference failed）；单条路线失败不影响其他路线 |

## 准备文档集

点击进入 **文档集** 标签页，管理评测用的知识库文档。文档集可作为评测任务的数据来源，也可用于自动生成评测集。

列表展示全部文档集，包含名称、文档数、大小、更新时间，支持 **查看**、**去评测**、**生成评测集**，以及通过行末的 **⋯** 执行 **重命名**、**删除**。

单击 **去评测** 可直接以该文档集发起评测任务。

### 1. 创建文档集

单击右上角 **创建文档集**，输入文档集名称后确认。限时免费期间最多可创建 10 个文档集，每个文档集最多 100M。

### 2. 添加与管理文件

在文档集详情页，单击 **添加文件**，可单击选择或拖拽文件到上传区域，支持一次批量上传多个文件。上传文件不影响已提交、已完成的评测任务。

| 项目 | 说明 |
| --- | --- |
| 支持格式 | PDF、DOC、DOCX、TXT、MD、XLS、XLSX |
| 单文件大小 | 不超过 10MB |

文件列表展示文件名、大小、上传时间，支持 **下载** 与 **删除**。文档集详情页的 **下载文档集** 可将整个文档集打包下载。

> 文档内容将传入云端沙箱用于构建知识库。请避免上传包含明文密钥、个人敏感信息的文件。

### 3. 生成评测集

在文档集列表单击 **生成评测集**，打开「自动生成评测集」弹窗，系统将基于文档内容生成问题、参考上下文和参考答案。

| 字段 | 说明 |
| --- | --- |
| 来源文档集 | 当前文档集，并展示其有效文档数与大小 |
| Key（必填） | 用于生成评测数据，仅展示当前项目下有权限的 Key |
| 文本模型（必填） | 用于生成评测数据的模型 |
| 问题数量 | 选填，最多 10000 条；留空则按文档集大小自动计算 |
| 策略配置 | 出题策略 Prompt，可自定义生成规则 |

单击 **开始生成** 后异步执行，完成后自动创建一个评测集，命名规则为「文档集名称-测试集」。

- 可在 **评测集** 标签页单击 **生成记录**，查看自动生成评测集的历史记录，包含关联文档集、模型、数据量、状态与 Token 消耗，并支持按状态筛选。
- 生成记录中的 **查看** 可跳转到对应的评测集。
- 自动生成的题目建议先审阅一遍，可按需编辑或删除（见下文「准备评测集」）。

> 该功能依赖大模型，将基于实际用量根据大模型定价计费，具体费用以账单为准。若评测集数量已达上限，需先删除不再使用的评测集。

## 准备评测集

点击进入 **评测集** 标签页，管理评测用的题目数据。评测集可由文件上传创建，也可由文档集自动生成。

列表展示评测集名称、数据量、来源、关联文档集、更新时间，支持 **查看**、**去评测**，以及通过行末的 **⋯** 执行 **重命名**、**导出为 XLSX**、**删除**。来源分为「自动生成」与「手动上传」两种，前者由文档集自动生成，后者通过上传文件创建。

### 1. 创建评测集

单击右上角 **创建评测集**，上传一个 xlsx 或 json 文件即可创建。

| 项目 | 说明 |
| --- | --- |
| 支持格式 | xlsx、json，仅支持单个文件 |
| 文件大小 | 不超过 100MB |
| 数据行数 | 单文件包含测试问题不超过 1 万条 |
| 必填字段 | `id`、`query`、`context`、`answer` |

- `id`：题目唯一标识，增量更新时按该字段匹配。
- `query`：用户问题。
- `context`：参考上下文。
- `answer`：参考答案。

评测集名称可选，最多 50 字，留空则使用「文件名 + 时间戳」。上传面板中提供 **下载 XLSX 示例** 与 **下载 JSON 示例**。

### 2. 更新评测集数据

在评测集详情页单击 **更新数据**，上传包含 `id`、`query`、`context`、`answer` 字段的文件，并选择更新方式：

| 方式 | 说明 |
| --- | --- |
| 全量覆盖 | 使用文件内容替换当前评测集全部数据，请谨慎操作 |
| 增量更新 | 按 ID 匹配更新，未匹配 ID 将新增，原有未上传数据保持不变 |

### 3. 查看与编辑题目

评测集详情页展示基本信息（评测集名称、数据量、更新时间、关联文档集）与题目列表，题目列表包含序号（ID）、用户问题、参考上下文、参考答案。

- 单击 **查看** 打开数据详情面板，可逐条翻阅题目。
- 单击 **编辑** 修改用户问题、参考上下文与参考答案，其中用户问题为必填。
- 单击 **删除** 移除单条题目。

> 删除题目后不可恢复，请谨慎操作。

## 发起评测任务

点击进入 **评测任务** 标签页，对评测集逐题执行多条 RAG 路线的检索、生成与评估，产出指标统计、逐题明细与可下载的评测报告。

> 评测结果保留 90 天，到期后不可查看，请及时下载报告。

任务列表支持按日期范围、任务状态、单条 RAG 路线筛选，展示任务名称 / ID、状态、文档集、评测集、RAG 路线、创建时间，单击 **查看** 进入任务详情。任务状态包括排队中、运行中、已完成、失败、已取消。

### 1. 填写基本信息

单击右上角 **新建评测任务**，进入创建页。

| 字段 | 说明 |
| --- | --- |
| 任务名称（可选） | 最多 50 字，留空则使用「评测任务 + 时间戳」 |
| API Key | 用于执行本次评测任务，任务中涉及模型调用的所有环节都将使用该 Key |
| 任务简介（可选） | 最多 200 字 |

> 提交任务将自动创建云端沙箱环境来执行评测，沙箱资源与模型调用均按实际用量计费。请确认所选 API Key 已开启沙箱和模型权限。

### 2. 添加 RAG 路线

在 **评测对象** 区域单击 **添加 RAG 路线**，从可评测路线中选择要对比的路线，最多添加 4 条。每条路线可展开查看其生效配置。

### 3. 选择评测数据

在 **评测数据** 区域选择本次评测使用的 **文档集** 与 **评测集**，也可单击 **新建文档集** / **新建评测集** 直接创建。单击 **刷新候选** 可重新拉取最新的候选列表。

### 4. 选择评估指标

在 **评估指标** 区域选择需要计算的指标，默认选中全部指标，至少需要选择一个评估器。部分指标需要依赖 LLM 模型与 Embedding 模型，可在此指定 **评估器 LLM 模型** 与 **评估器 Embedding 模型**。

> 提交评测会使用模型与沙箱资源，并按实际资源用量计费。

### 5. 查看任务结果

任务提交后异步执行，可在任务详情页查看结果，详情页包含三个页签。

**基础信息**：任务状态、创建时间、完成时间、任务简介，以及评测配置（文档集、评测集、RAG 路线、评估器）。页面下方的「运行信息」区域按路线切换，展示索引耗时、总 Token、答案生成率、平均延迟，以及以下七个执行阶段：

| 阶段 | 说明 |
| --- | --- |
| 配置快照 | 固化本次评测使用的路线配置 |
| 排队调度 | 任务排队与派发 |
| 沙箱启动 | 启动云端沙箱环境 |
| 文档解析 | 解析知识库文档 |
| 向量索引 | 构建向量索引，记录索引阶段的 Token 消耗 |
| 逐题问答 | 逐题执行检索与回答生成 |
| 评测打分 | 计算各评估指标得分 |

**指标统计**：包含多路线指标对比雷达图、单指标路线对比柱状图，以及各路线的指标明细表。

**逐题明细**：按路线切换查看每道题的题目、参考上下文、参考答案、检索上下文、生成答案与各评估器得分。

任务失败时，同样在「运行信息」中按路线切换，查看各路线的状态与进度，先定位是哪条路线失败，再检查该路线相关的模型权限、账户余额与文档内容后重新提交。

### 6. 下载评测报告

任务完成后，可在任务详情页单击 **下载报告**，下载以「任务名称_生成时间_语言」命名的压缩包，解压后包含：

| 文件 | 内容 |
| --- | --- |
| HTML 报告 | 任务信息、评测配置、运行信息与指标统计（指标雷达图、单指标路线对比） |
| Excel 评测明细 | 按 RAG 路线分工作表（如 `rag-dsrag @v0.5.6`），逐题记录题目、生成结果与各评估器得分 |

报告为静态文件，可直接用于内部分享与归档。

> 报告仅在任务完成后可下载；若提示报告生成中，请稍后重试。

## 查看评估器

点击进入 **评估器** 标签页，可查看平台预置的全部评估指标。单击指标卡片的 **查看说明**，可在侧边面板查看该指标的完整定义：

| 信息   | 说明                                                |
| ---- | ------------------------------------------------- |
| 分类   | 指标类型：LLM 或 Code                                   |
| 目标   | 指标标识及评估目标                                         |
| 来源   | 指标来源                                              |
| 输入参数 | 指标计算所需的字段及格式，如 question、contexts、reference_answer |
| 输出参数 | 指标输出的类型和取值范围                                      |
| 函数逻辑 | 指标的代码实现或 LLM Prompt，可直接查看和复制                      |

## 如何解读评测结果

评测指标大致可分为三类，建议按以下顺序阅读：

| 关注点 | 建议先看的指标 | 说明 |
| --- | --- | --- |
| 检索质量 | 上下文召回率、上下文精确度 | 召回率反映该找到的内容有没有找全，精确度反映检索到的内容里有多少是相关的。两者同时偏低，问题通常出在文档分块与索引策略 |
| 回答是否可信 | 忠实度、事实正确性 | 忠实度反映回答是否只依据检索到的上下文，事实正确性反映回答内容与事实是否一致。这两项偏低说明存在编造风险 |
| 最终效果 | 答案正确性、精确匹配 | 答案正确性综合衡量回答与参考答案的接近程度；精确匹配要求与参考答案完全一致，通常很低甚至为 0，属于正常现象，不建议作为主要依据 |

- 报告中的 **均分** 是各评估指标的综合得分，适合快速横向比较路线优劣。
- 某条指标差距明显时，可切换到 **逐题明细** 查看具体题目，判断是「没检索到」还是「检索到了但没答对」。
- 建议固定文档集与评测集、只变化 RAG 路线，这样对比结果才具备可比性。

> 各指标的完整定义与计算逻辑，可在 **评估器** 标签页单击指标卡片的 **查看说明** 查看。

## 计费说明

- RAGView 本身不收取功能费用，仅对评测过程中实际消耗的**模型调用**和**应用沙箱资源**计费。
- 文档集与评测集当前限时免费，不产生额外功能费用。
- 生成评测集与提交评测任务不单独收费，但过程中的模型调用会计入模型费用。
- Token 用量、沙箱运行时长以账单为准，可在 **消费中心 > 导出记录** 中查询 RAGView 来源的消耗明细。
- 勾选 LLM 类评估器时，计算指标会使用评估器 LLM 模型产生额外 Token 消耗，建议根据评估精度要求选择合适的模型。
- 评测任务中**每条 RAG 路线在独立沙箱中各自构建索引**，因此路线数越多，索引阶段的 Token 消耗与耗时越高，且大致成正比。

### 成本与耗时预期

评测任务的耗时与费用主要由两个阶段决定：

| 阶段 | 主要影响因素 | 说明 |
| --- | --- | --- |
| 索引 | 文档集大小、路线数 | 每条路线独立建索引，通常是耗时与 Token 消耗的主要来源 |
| 逐题问答与评测打分 | 评测集题目数、评估指标数 | 与题目数成正比；勾选的 LLM 类评估器越多，消耗越高 |

以 25 个文档（约 63.8MB）的文档集、20 道题、4 条路线为例：单条路线索引阶段消耗约 900 万 input Token、耗时约 37 分钟；各路线并行执行，整个任务耗时约 43 分钟。文档集或题目数量成倍增长时，耗时与费用也会成倍上升，建议先用小批量数据验证流程，再提交全量评测。

## 常见问题

### 为什么竞技场路线卡片显示「运行失败 / inference failed」？

常见原因包括：生成模型无调用权限、账户余额不足、文档解析失败或沙箱资源异常。请依次确认 API Key 权限、账户余额和文档内容后重试；单条路线失败不影响其他路线的问答结果，可删除失败路线后重新添加。

### 评测结果可以导出吗？

可以。评测任务完成后，可在任务详情页单击 **下载报告**，获取包含 HTML 报告与 Excel 评测明细的压缩包。评测集本身也可通过 **⋯ > 导出为 XLSX** 导出题目数据。

### 全量覆盖和增量更新有什么区别？

全量覆盖会用上传文件的内容替换评测集当前的全部数据，请谨慎操作；增量更新按 `id` 匹配更新已有题目，文件内未匹配的 `id` 会新增，评测集中未被文件涉及的数据保持不变。

### 评测任务显示「失败」怎么办？

评测任务包含多条 RAG 路线，请在任务详情页的「运行信息」中按路线切换，查看各路线的状态与进度，先定位是哪条路线失败。常见原因包括模型无调用权限、账户余额不足、文档解析失败或沙箱资源异常，确认后可重新提交任务。

### 为什么无法创建或生成评测集？

评测集限时免费额度为最多 10 个。若已达上限，请先在 **评测集** 标签页删除不再使用的评测集，再重新创建或生成。

### 下载报告时提示「报告生成中」怎么办？

报告为异步生成，任务刚完成时可能尚未就绪，请稍后重试。若任务状态不是「已完成」，需等待任务执行完成后再下载。
