From e1a0c6be2c35561fffc1849fad7203d28f440351 Mon Sep 17 00:00:00 2001 From: Wenjie Zhang Date: Sun, 14 Dec 2025 22:39:20 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E5=93=81=E7=89=8C?= =?UTF-8?q?=E8=89=B2=E6=9D=BF=E5=92=8C=E7=9F=A5=E8=AF=86=E5=BA=93=E8=AF=84?= =?UTF-8?q?=E4=BC=B0=E6=96=87=E6=A1=A3=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 调整品牌文档中的CSS变量命名以更符合色板规范 - 重构知识库评估文档结构，简化内容并增加实用指南 - 添加数据集构建工具推荐和评估指标说明表格 --- docs/latest/advanced/branding.md | 6 +- docs/latest/intro/evaluation.md | 146 ++++++++----------------------- 2 files changed, 38 insertions(+), 114 deletions(-) diff --git a/docs/latest/advanced/branding.md b/docs/latest/advanced/branding.md index d8ed4b84..3e65020e 100644 --- a/docs/latest/advanced/branding.md +++ b/docs/latest/advanced/branding.md @@ -42,8 +42,8 @@ YUXI_BRAND_FILE_PATH=src/config/static/info.local.yaml ```css :root { --main-color: #1890ff; /* 主色调 */ - --main-bg: #f0f2f5; /* 背景色 */ - --main-text: #262626; /* 文字色 */ - --main-border: #d9d9d9; /* 边框色 */ + --main-1000: #f0f2f5; /* 色板 */ + --main-900: #e6f7ff; /* 色板 */ + /* ... 其他色板 */ } ``` diff --git a/docs/latest/intro/evaluation.md b/docs/latest/intro/evaluation.md index ec2f35ea..fb3a3880 100644 --- a/docs/latest/intro/evaluation.md +++ b/docs/latest/intro/evaluation.md @@ -1,133 +1,57 @@ -# 知识库评估 +# 知识库评估使用与开发指南 -Yuxi-Know 提供了完整的 RAG 系统评估解决方案，帮助您科学地衡量知识库的检索质量和答案准确性。评估系统通过标准化的基准测试、多维度的指标计算和直观的结果展示，让您能够全面了解系统性能并持续优化。 +知识库评估功能用于测试 RAG 系统的检索和生成质量。通过预设的测试问题和标准答案（或自动生成评估），量化评估系统在不同场景下的表现。 -> **注意**：目前评估功能仅支持 Milvus 类型的知识库。 +**适用场景**：验证知识库上线前的效果、对比不同配置下的检索效果、定期监控知识库质量变化、调优检索参数。 -## 评估基准 +**注意**：当前版本仅支持 Milvus 类型的知识库。 -评估基准是衡量知识库性能的标准数据集，包含了测试问题、相关的黄金文档块 ID 和标准答案。系统支持两种创建评估基准的方式。 +## 如何创建评估基准 -### 手动上传评估基准 +### 1. 上传评估文件 -您可以通过上传 JSONL 格式的文件创建评估基准。每行代表一个测试样本，必须包含 `query` 字段（查询问题），可选地包含 `gold_chunk_ids`（黄金文档块 ID 列表）和 `gold_answer`（标准答案）。 - -- 当基准包含黄金文档块 ID 时，系统会计算检索指标（如 Recall@K、F1@K） -- 当基准包含标准答案时，系统会使用 LLM 作为评判者评估生成答案的准确性 -- 同时包含两者时，系统会进行全面的检索和生成质量评估 - -也可以从 easy dataset 自动生成评估基准。 - -#### JSONL 文件格式示例 +准备 JSONL 格式的文件，每行一个测试样本： ```json -{"query": "什么是人工智能？", "gold_chunk_ids": ["chunk_001", "chunk_002"], "gold_answer": "人工智能是计算机科学的一个分支，致力于创建能够执行通常需要人类智能的任务的系统。"} -{"query": "机器学习的主要类型有哪些？", "gold_chunk_ids": ["chunk_005"], "gold_answer": "机器学习主要包括监督学习、无监督学习和强化学习三种主要类型。"} -{"query": "深度学习的应用领域", "gold_chunk_ids": ["chunk_010", "chunk_011", "chunk_012"]} +{"query": "什么是人工智能？", "gold_chunk_ids": ["chunk_001", "chunk_002"], "gold_answer": "人工智能是计算机科学的一个分支"} +{"query": "机器学习的主要类型有哪些？", "gold_chunk_ids": ["chunk_005"], "gold_answer": "主要包括监督学习、无监督学习和强化学习"} +{"query": "深度学习的应用领域", "gold_chunk_ids": ["chunk_010", "chunk_011"]} ``` -每行一个独立的 JSON 对象，包含以下字段： -- `query`（必需）：查询问题 -- `gold_chunk_ids`（可选）：黄金文档块 ID 列表 +**字段说明**： +- `query`（必需）：测试问题 +- `gold_chunk_ids`（可选）：相关文档块的 ID 列表 - `gold_answer`（可选）：标准答案 -### 自动生成评估基准 +::: tip 数据集构建 +可以使用 [EasyDataset](https://github.com/ConardLi/easy-dataset) 从文档批量生成问答对、可视化编辑、导出多种格式和数据质量检查。挺好用的，推荐。注意导出的时候的字段需要修改为 `query`、`gold_chunk_ids`、`gold_answer`。 +::: -系统可以根据知识库内容自动生成评估基准。生成过程包括： -1. **随机采样**：从知识库中随机选择文档块作为基础材料 -2. **相似度计算**：使用指定的嵌入模型计算文档块间的相似度，选取相似文档作为上下文 -3. **问题生成**：使用 LLM 基于采样到的文档生成相关查询问题和标准答案 -4. **质量保证**：确保生成的问题能由提供的上下文准确回答，且黄金文档块 ID 与上下文匹配 +### 2. 自动生成评估基准 -生成参数说明： -- **问题数量**：控制生成的问题总数（1-100） -- **相似 chunks 数量**：每个问题关联的相似文档块数量（0-10） -- **LLM 模型**：用于生成问题和答案的语言模型 -- **Embedding 模型**：用于计算文档相似度的嵌入模型 -- **Temperature**：控制生成内容的随机性（0-2） -- **Max Tokens**：限制生成内容的最大长度 +Yuxi 也实现了一个简易的、可以基于现有知识库自动生成测试数据。流程是：随机采样一个 chunk → 用嵌入模型找相似 chunk → 用 LLM 生成问题和答案。 -## 评估指标 +**推荐参数设置**： +- 问题数量：10-50 个 +- 相似文档数：每个问题 2-5 个 -系统提供多维度的评估指标，全面衡量 RAG 系统的性能。 +## 运行评估任务 -### 检索评估指标 +1. 选择评估基准后在知识库页面点击"评估"标签 -当基准包含黄金文档块 ID 时，系统会计算以下指标： +2. 配置参数： + - **答案生成模型（可选）**：如果选择了，则会基于检索的 chunk 生成答案，然后用评判模型评估答案的准确性 + - **评判模型（可选）**：如果选择了，则会用评判模型评估答案的准确性，判断是否与标准答案一致，因此选择评判模型时，必须选择答案生成模型。 -- **Recall@K**：在前 K 个检索结果中找到的相关文档比例，衡量检索的召回能力 -- **F1@K**：Precision@K 和 Recall@K 的调和平均值，综合评估检索精确度和召回率 +3. 点击"开始评估"： +系统会逐个处理测试问题，执行检索和生成，计算各项指标。评估在后台运行，可以继续其他操作。 -默认计算 K=1、3、5、10 的指标值，让您了解不同检索深度下的性能表现。 +**主要指标**： -### 答案评估指标 - -当基准包含标准答案时，系统会使用指定的 Judge LLM 评估生成答案的质量： - -- **答案准确性**：LLM 评判者基于事实一致性判断生成答案是否正确 -- **评判理由**：提供详细的判定依据，便于理解和分析 - -评判过程会忽略措辞差异，专注于核心事实的准确性。 - -### 综合评分 - -系统会计算一个整体评分，将所有检索指标和答案准确性的分数进行平均，提供一个直观的性能概览。 - -## 评估流程 - -### 执行评估 - -1. **选择基准**：从知识库的评估基准列表中选择合适的基准 -2. **配置模型**： - - 答案生成模型：用于基于检索到的文档生成答案 - - 答案评判模型：用于评估生成答案的准确性（仅当基准包含标准答案时需要） -3. **检索配置**：可以调整检索参数，如相似度阈值、返回文档数量等 -4. **启动评估**：系统会在后台异步执行评估任务 - -### 实时进度追踪 - -评估过程中，您可以： -- 查看实时进度和当前已完成的问题数量 -- 监控中间结果，了解各项指标的实时变化 -- 取消正在运行的评估任务 - -### 结果分析 - -评估完成后，系统提供详细的结果报告： - -- **整体性能概览**：展示各项指标的平均得分和总体评分 -- **检索配置记录**：保存评估时使用的检索和生成配置，确保结果可重现 -- **详细结果表格**：每个问题的具体表现，包括： - - 原始查询和生成答案 - - 检索到的文档列表 - - 各项指标的得分 - - 答案正确性评判和理由 - -## 评估历史 - -系统会自动保存所有评估记录，您可以： -- 查看历史评估列表，包括执行时间、基准信息、总体评分等 -- 对比不同配置下的评估结果，分析优化效果 -- 删除不需要的评估记录 -- 基于历史结果调整系统配置 - -## 最佳实践 - -### 基准设计建议 - -- **代表性问题**：确保基准覆盖知识库的主要内容和典型应用场景 -- **难度梯度**：包含不同难度级别的问题，全面评估系统能力 -- **数据质量**：黄金答案应准确、完整，黄金文档块应与问题高度相关 - -### 评估频率 - -- **定期评估**：在知识库更新或系统配置调整后进行评估 -- **版本对比**：记录每次评估的结果，追踪性能变化趋势 -- **A/B 测试**：对比不同配置下的性能，选择最优方案 - -### 结果解读 - -- **检索指标**：重点关注 Recall@1 和 Recall@5，它们反映了用户最可能查看的文档质量 -- **答案准确性**：结合评判理由分析错误原因，是检索不足还是生成质量问题 -- **综合评分**：作为参考，但更应关注具体指标的改进方向 \ No newline at end of file +| 指标 | 含义 | 如何看待 | +|------|------|----------| +| Recall@1 | 第一个结果包含正确文档的比例 | 最重要的指标，反映用户第一眼看到的准确率 | +| Recall@5 | 前5个结果包含正确文档的比例 | 综合检索效果，应该大于 0.8 | +| F1@K | 精确率和召回率的调和平均 | 平衡指标，用于对比不同配置 | +| 答案准确性 | 生成答案是否与标准答案一致 | 检查 LLM 理解和表达能力 |