#使用 Ragas 评估 RAG

Retrieval-Augmented Generation（RAG）系统结合了检索器和生成器。仅对最终答案进行质量评估通常是不够的：失败可能源于无关或不完整的检索、生成偏离来源，或两者兼有。

Ragas（Retrieval-Augmented Generation Assessment）是一个 Python 框架，通过对上下文忠实度、答案相关性、检索质量等指标进行评分来评估 RAG 行为——具体取决于启用的指标和评估集中的列。

本页重点介绍直接在笔记本或批处理作业中使用 Ragas SDK。与其他评估平台的集成是可选的，此处不做覆盖。

#每个评估样本需要记录的内容

典型的单轮数据行包括：

#Ragas 指标概览

Ragas 提供了丰富的指标目录。典型的 RAG 评估通常只需使用其中一部分。每个指标期望特定的数据集列（例如 question、contexts、answer、ground_truth），可能需要LLM、embeddings、两者或都不需要。名称和导入路径会随版本变化；请参考Ragas 指标文档确认已安装版本的使用方法。

以下列表总结了指标意图和常见用途，但不能替代上游 API 细节。

#核心 RAG 指标

这些指标与检索增强生成质量最直接相关，通常是首选跟踪指标：

除非另有说明，本节中的类均来自 ragas.metrics.collections。

字段和导入要求可能因 Ragas 版本和指标变体而异。请参考已安装版本的Ragas 指标文档确认。

#可选 RAG 指标

这些指标在特定评估场景中有用，尤其是当有参考答案或需要鲁棒性检测时：

对于与 RAG 核心评估关联较弱的指标（例如通用文本重叠指标、基于评分标准的自定义指标、智能体/工具指标、SQL 指标或多模态指标），请参阅Ragas 指标文档。

#选择最小 RAG 指标集

许多 RAG 基准的实用默认组合是：忠实度、答案相关性、上下文精确度和上下文召回率（召回和部分精确度变体需要 ground_truth 或等效字段）。当有参考答案时，可增加答案正确性或语义相似度。指标选择应与数据集中的列和成本限制匹配（基于 LLM 的指标较慢且成本较高）。

#调用 Ragas SDK

现代 Ragas 用法中，从 ragas.metrics.collections 实例化指标，并使用 ascore()（或同步脚本中的 score()）对每行进行评分。

1. 准备兼容 OpenAI 的客户端（AsyncOpenAI）用于 LLM 和 embeddings，然后配置 llm_factory 和 OpenAIEmbeddings（详见示例笔记本中的环境变量配置）。

2. 实例化指标时显式传入依赖（需要时传入 llm、embeddings）。

3. 遍历数据行，调用 metric.ascore(...) 并传入指标特定参数。

   from openai import AsyncOpenAI
   from ragas.embeddings import OpenAIEmbeddings
   from ragas.llms import llm_factory
   from ragas.metrics.collections import AnswerRelevancy, Faithfulness
   
   llm_client = AsyncOpenAI(
       api_key="...",
       base_url="https://your-openai-compatible-endpoint/v1",  # 或 None 使用默认提供商
   )
   embed_client = AsyncOpenAI(
       api_key="...",  # 通常与 LLM 使用同一密钥（当使用同一网关时）
       base_url="https://your-embedding-endpoint/v1",  # 可选；可与 llm_client 相同
   )
   
   llm = llm_factory("your-llm-model", client=llm_client)
   embeddings = OpenAIEmbeddings(model="your-embedding-model", client=embed_client)
   
   faithfulness = Faithfulness(llm=llm)
   answer_relevancy = AnswerRelevancy(llm=llm, embeddings=embeddings)

选择指标时，以下差异会影响评分调用的准备方式：

实际上，主要工作是对齐数据集字段和指标选择，然后使用选定的指标实例对数据行进行评分。

#前提条件

• 推荐使用 Python 3.10 及以上版本。
• 需要访问 LLM API（以及需要嵌入的指标还需访问嵌入 API）。示例笔记本假设兼容 OpenAI 的环境，支持配置凭证和兼容网关的可选基础 URL。
• 评估会发起大量模型调用；成本和延迟随数据行数和指标数量增长。
• 版本锁定：Ragas API 和指标类在不同版本间会变化。为保证基准可复现，请在环境或笔记本中锁定 ragas（及相关包）版本；示例笔记本中有注释的安装行供参考。

#可运行笔记本

下载并在 JupyterLab 或其他 Jupyter 环境中打开笔记本：

• ragas-rag-eval.ipynb

笔记本开头简要回顾了现代指标（ragas.metrics.collections）和显式的 LLM/embedding 配置。权威说明请参阅本页的调用 Ragas SDK部分。

笔记本内容：

1. 安装依赖（可选注释版本锁定以保证可复现）。
2. 创建一个包含 user_input、retrieved_contexts、response 和 reference 的小型 datasets.Dataset。
3. 使用现代指标类运行基线评估，包含忠实度和答案相关性。
4. 添加可选的检索相关指标（上下文精确度和上下文召回率）。
5. 展示汇总和逐行结果，随后是简短的故障排查部分。

#故障排查

• 凭证或端点配置：配置 LLM API 凭证（及兼容网关的可选基础 URL）。如果嵌入使用独立端点，也需配置嵌入凭证，然后分别传入 AsyncOpenAI 客户端给 llm_factory 和 OpenAIEmbeddings。
• 数据集验证错误：确认所选指标所需参数，确保数据集键与现代示例一致（user_input、retrieved_contexts、response、reference）。
• 笔记本异步执行：示例笔记本使用 await metric.ascore(...)。同步脚本请使用 metric.score(...) 或用 asyncio.run(...) 包裹异步代码。
• 版本相关警告：指标类和签名可能随 Ragas 版本变化。为保证可复现，锁定包版本并根据已安装版本文档确认行为。

#结果解读

• 仅在相同数据集和评估配置（判定 LLM、embeddings 和提示）下比较分数；否则差异可能反映配置变化而非 RAG 质量。
• 检索导向评估时，尽可能使用与生产 RAG 检索器相同的嵌入模型，以减少因嵌入空间不匹配导致的指标漂移。
• 使用汇总分数进行趋势跟踪或质量门控，使用逐行分数进行诊断（例如缺失上下文、幻觉或无关检索）。将指标值视为方向性信号，而非绝对真理。

#进一步阅读

• Ragas 文档：https://docs.ragas.io/
• Ragas GitHub 仓库：https://github.com/vibrantlabsai/ragas