企业官网建设流程全解析

使用 Zeno 可视化 Ragas 评估结果：RAG 评测指标的上传与交互式探索实战指南

【免费下载链接】ragasSupercharge Your LLM Application Evaluations 🚀项目地址: https://gitcode.com/gh_mirrors/ra/ragas

本指南讲解如何把 Ragas 的 RAG 评估结果（context_precision、faithfulness、answer_relevancy、context_recall 等指标得分）一键上传到 Zeno 评估平台，通过自定义视图与指标面板进行可视化、探索与多模型对比。读完本文，你将掌握从运行 Ragas 评估、导出 DataFrame，到在 Zeno 上创建项目、定义 RAG 视图、上传数据集与系统输出的完整工作流，从而把枯燥的指标数字变成可交互、可下钻、可分享的评估报告。

为什么要把 Ragas 结果可视化到 Zeno

Ragas 的evaluate()会为每个样本逐条计算多项指标得分，最终返回一个EvaluationResult对象。直接打印或查看 DataFrame 只能看到一行行数字，很难回答这样几个问题：

• 哪类问题（如单跳事实型、多跳推理型）得分普遍偏低？
• 检索上下文与生成答案之间存在什么样的对应关系？
• 更换模型或提示词后，哪些样本的分数发生了变化、变化方向如何？

Zeno 正是为了解决这类"探索式评估"问题而设计：它支持把原始数据（问题、上下文、标准答案）、系统输出（模型回答）和指标得分一起上传，并在浏览器中提供按列排序、过滤、分组、逐样本下钻、跨系统对比等能力。搭配 Ragas 的评估流程，可以形成"评测 → 上传 → 探索 → 定位问题 → 迭代 → 再对比"的闭环。

需要说明的是，zeno-client属于第三方生态包，本仓库源码（src/ragas/）中并不包含 Zeno 的集成代码，两者的衔接完全通过标准的 pandas DataFrame 完成——这正是本文工作流的核心枢纽。

第一步：安装与准备

安装 zeno-client

在已安装ragas的 Python 环境中执行：

pip install zeno-client

注册账号并获取 API Key

• 在 Zeno Hub 平台注册账号；
• 在账号设置页面生成一个 API Key；
• 后续所有上传操作都需要该 Key，建议通过环境变量注入，避免硬编码到代码里。

第二步：运行 Ragas 评估并导出结果

导入所需模块

import os import pandas as pd from datasets import load_dataset from zeno_client import ZenoClient, ZenoMetric from ragas import evaluate from ragas.metrics import ( answer_relevancy, context_precision, context_recall, faithfulness, )

配置 API Key

# Set API keys os.environ["OPENAI_API_KEY"] = "your-openai-api-key" os.environ["ZENO_API_KEY"] = "your-zeno-api-key"

OPENAI_API_KEY供 Ragas 评估时使用的 LLM（如 faithfulness、answer_relevancy 等指标需要 LLM 打分）调用；ZENO_API_KEY供ZenoClient上传数据使用。

加载数据集并执行评估

沿用 Getting Started 指南（见 docs/getstarted/evals.md）的评估流程，使用 FIQA 金融问答数据集的ragas_eval子集：

fiqa_eval = load_dataset("vibrantlabsai/fiqa", "ragas_eval") result = evaluate( fiqa_eval["baseline"], metrics=[ context_precision, faithfulness, answer_relevancy, context_recall, ], ) df = result.to_pandas() df.head()

这里选择的四个指标分别覆盖 RAG 链路的不同环节：

• context_precision：检索到的上下文中相关信息的占比（衡量检索精度）；
• faithfulness：生成答案与检索上下文之间的事实一致性（衡量生成忠实度）；
• answer_relevancy：答案对问题的相关程度；
• context_recall：标准答案中的信息被检索上下文覆盖的比例（衡量召回）。

to_pandas()的底层原理

从源码看，evaluate()（定义见 src/ragas/evaluation.py）返回的EvaluationResult内部同时保存了scores（每条样本的指标得分列表）和dataset（原始评估数据集）。EvaluationResult.to_pandas()（实现见 src/ragas/dataset_schema.py）的工作方式如下：

1. 将scores转为scores_df；
2. 调用dataset.to_pandas()将原始样本转为dataset_df（底层通过model_dump()展开SingleTurnSample等数据模型，见 src/ragas/dataset.py）；
3. 用pd.concat([dataset_df, scores_df], axis=1)按行横向拼接。

因此df中每行既包含原始样本字段（question、contexts、answer、ground_truth 等），又并列着四个指标得分列。Zeno 上传所需的全部信息都来自这个 DataFrame。SingleTurnSample的字段定义可参见 src/ragas/dataset_schema.py，其中user_input、retrieved_contexts、response、reference与 Zeno 视图中的 question、texts、answer、ground_truth 一一对应。

第三步：在 Zeno 上创建项目

拿到df后，先在 Zeno 上创建一个项目，并用自定义 RAG 视图声明每条样本如何渲染，同时声明需要按哪些指标列进行统计：

client = ZenoClient(os.environ["ZENO_API_KEY"]) project = client.create_project( name="Ragas FICA eval", description="Evaluation of RAG model using Ragas on the FICA dataset", view={ "data": { "type": "vstack", "keys": { "question": {"type": "markdown"}, "texts": { "type": "list", "elements": {"type": "markdown"}, "border": True, "pad": True, }, }, }, "label": { "type": "markdown", }, "output": { "type": "vstack", "keys": { "answer": {"type": "markdown"}, "ground_truth": { "type": "list", "elements": {"type": "markdown"}, "border": True, "pad": True, }, }, }, "size": "large", }, metrics=[ ZenoMetric( name="context_precision", type="mean", columns=["context_precision"] ), ZenoMetric(name="faithfulness", type="mean", columns=["faithfulness"]), ZenoMetric(name="answer_relevancy", type="mean", columns=["answer_relevancy"]), ZenoMetric(name="context_recall", type="mean", columns=["context_recall"]), ], )

要点说明：

• view声明了 Zeno 界面上"数据"与"输出"两栏的渲染结构：问题用 markdown 展示，检索上下文以带边框的 markdown 列表（vstack纵向堆叠）展示，标准答案和模型回答同样用 markdown/列表呈现；
• metrics中的每个ZenoMetric对应一个指标列，type="mean"表示在项目面板上以均值聚合该列，columns指向df中对应的列名；
• 项目名称与描述会显示在 Zeno Hub 的项目页面上，建议命名包含数据集与评测目标，便于后续检索与分享。

第四步：上传基础数据集

项目创建后，先把"数据 + 标准答案"作为基础数据集上传。这里的关键是从df重组出 Zeno 期望的三列结构：

data_df = pd.DataFrame( { "data": df.apply( lambda x: {"question": x["question"], "texts": list(x["contexts"])}, axis=1 ), "label": df["ground_truth"].apply(lambda x: "\n".join(x)), } ) data_df["id"] = data_df.index project.upload_dataset( data_df, id_column="id", data_column="data", label_column="label" )

• data列是结构化对象，包含question与texts（检索上下文列表），与项目view中声明的data渲染结构对应；
• label列存放标准答案（ground_truth），多条时用换行连接；
• id列是样本唯一标识，后续上传系统输出时必须用相同的id才能对齐到对应样本。

第五步：上传系统输出与指标得分

最后，把模型输出（answer）与四项 Ragas 指标得分作为一个"系统"上传。你可以为每个待对比的模型/版本重复执行这一步，从而在同一个项目里横向对比多个系统的表现：

output_df = df[ [ "context_precision", "faithfulness", "answer_relevancy", "context_recall", ] ].copy() output_df["output"] = df.apply( lambda x: {"answer": x["answer"], "ground_truth": list(x["ground_truth"])}, axis=1 ) output_df["id"] = output_df.index project.upload_system( output_df, name="Base System", id_column="id", output_column="output" )

• output_df保留了四个指标列，Zeno 会依据项目中声明的ZenoMetric对它们进行统计展示；
• output列存放模型生成的答案，与view中的output渲染结构对应；
• name="Base System"是该系统的展示名，后续上传其他系统（如调优后的提示词、换用其他 LLM）时使用不同名称即可并排对比；
• id_column与数据集上传时保持一致，保证输出与样本正确匹配。

完整工作流回顾与实战建议

整个流程可以归纳为五步：

1. 评测：用ragas.evaluate()跑出四项 RAG 指标，result.to_pandas()得到同时含原始字段与得分列的 DataFrame；
2. 建项：ZenoClient.create_project()声明自定义 RAG 视图与指标聚合方式；
3. 传数据：upload_dataset()上传问题、检索上下文与标准答案；
4. 传系统：upload_system()上传模型回答与指标得分；
5. 对比迭代：对每个候选系统重复第 4 步，在 Zeno 中下钻分析。

实战中值得注意的几点：

• 多系统对比：迭代提示词、更换 LLM 或调整检索策略后，用相同的id与指标列再跑一轮evaluate()并upload_system()，即可在 Zeno 中直接看到各系统在同一批样本上的得分差异；
• 指标列必须与df列名严格一致：ZenoMetric(columns=[...])与upload_system的 DataFrame 列名、view中的字段名三处需要对齐，否则数据无法正确渲染或统计；
• 逐样本下钻：Zeno 中点击任一数据点即可同时看到问题、检索上下文、模型回答与标准答案，非常适合定位 faithfulness 或 context_precision 偏低的失败样本，反哺数据清洗与提示词优化。

深入阅读

• 评估入口与返回类型：src/ragas/evaluation.py
• EvaluationResult.to_pandas()拼接实现：src/ragas/dataset_schema.py
• SingleTurnSample样本字段定义：src/ragas/dataset_schema.py
• 四个指标在ragas.metrics中的导出位置：src/ragas/metrics/init.py
• Getting Started 评估入门：docs/getstarted/evals.md

【免费下载链接】ragasSupercharge Your LLM Application Evaluations 🚀项目地址: https://gitcode.com/gh_mirrors/ra/ragas