#使用 Ragas 评估 RAG

检索增强生成（Retrieval-Augmented Generation，RAG）系统将检索器和生成器结合在一起。仅仅衡量最终答案的质量通常是不够的：失败可能来自无关或不完整的检索，来自偏离来源的生成，也可能两者皆有。

Ragas（Retrieval-Augmented Generation Assessment）是一个 Python 框架，可使用一组指标来评估 RAG 行为，例如上下文忠实度、答案相关性、检索质量等——具体取决于启用了哪些指标以及评估集中的可用列。

本页面重点介绍在 notebook 或批处理作业中直接使用 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. 为 LLM 和 embeddings 准备 OpenAI 兼容客户端（AsyncOpenAI），然后配置 llm_factory 和 OpenAIEmbeddings（有关环境变量配置，请参见示例 notebook）。

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",  # or None for provider default
   )
   embed_client = AsyncOpenAI(
       api_key="...",  # often same key as LLM when using one gateway
       base_url="https://your-embedding-endpoint/v1",  # optional; can match 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 的网络连接（对于需要 embeddings 的指标，还需要可访问 embeddings API）。示例 notebook 假定使用 OpenAI 兼容环境，并支持为兼容网关配置凭据和可选的 base URL。
• 需要注意，评估会发起大量模型调用；成本和延迟会随着行数和指标数量而增长。
• 版本固定：Ragas API 和指标类会在不同版本之间变化。为了获得可复现的基准测试，请在环境或 notebook 中固定 ragas（以及相关包）的版本；请参见示例 notebook 中注释掉的安装行。

#可运行的 notebook

在 JupyterLab 或其他 Jupyter 环境中下载并打开该 notebook：

• ragas-rag-eval.ipynb

该 notebook 以简短的 SDK 回顾开始，重点介绍现代指标（ragas.metrics.collections）以及显式的 LLM/embedding 设置。权威说明请参考本页的 调用 Ragas SDK 部分。

该 notebook 会：

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

#故障排查

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

#结果解读

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

#延伸阅读

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