基于 Ragas CLI 模板的 LLM 基准评测实战:用 `benchmark_llm` 横向对比折扣计算任务的模型准确率
基于 Ragas CLI 模板的 LLM 基准评测实战:用 benchmark_llm 横向对比折扣计算任务的模型准确率
benchmark_llm 是 Ragas CLI 提供的一个 LLM 基准评测模板,它围绕"根据客户画像计算折扣百分比"这一结构化输出任务,对 GPT、Claude、Gemini 等不同模型进行统一的准确率评测与横向对比。本文将以该模板为骨架,带你走通「创建项目 → 安装依赖 → 运行评测 → 多模型对比 → 结果分析 → 自定义任务」的完整链路,并结合仓库中的 evals.py、prompt.py 与 discrete_metric 等源码实现,讲清模板背后的评测原理,使你能够直接用一套标准化的流程为自己的 LLM 应用做模型选型。
模板概览:它评测什么
benchmark_llm 模板的核心思路非常简单:用同一份数据集、同一条 Prompt、同一个评分函数,去驱动多个 LLM 完成同一项任务,从而量化比较各模型的差异。在默认模板中:
- 任务:根据给定的客户画像(年龄、收入、会员等级、在籍时长等)计算应享受的折扣百分比;
- 模型:通过
--model参数指定 GPT-4o、GPT-3.5、Claude、Gemini 等任意 OpenAI 兼容模型; - 输出格式:要求模型以 JSON 返回,包含
discount_percentage、reason、applied_rules字段; - 指标:
discount_accuracy(折扣准确率),判定结果为correct/incorrect两种离散取值。
与其他 CLI 模板(如 rag_eval、agent_evals)侧重 RAG 检索质量或 Agent 行为不同,benchmark_llm 关注的是模型在受控业务规则下的推理与结构化输出能力,非常适合作为模型选型、版本迭代(如从 gpt-3.5-turbo 升级到 gpt-4o)时的客观参照。
快速开始:从空目录到跑出第一份基准
该模板属于 Ragas CLI 的 quickstart 模板体系,相关入口说明见 docs/howtos/cli/index.md。确保已安装 ragas(pip install ragas 或 uvx ragas --help 免安装运行)后,按以下步骤操作:
1. 创建项目
ragas quickstart benchmark_llm
cd benchmark_llm
不带模板名执行 ragas quickstart 可列出全部可用模板;-o, --output-dir 可指定项目创建目录(默认当前目录)。
2. 安装依赖
uv sync
模板通过 pyproject.toml + uv 管理依赖(包含 ragas、openai、python-dotenv、pandas 等),uv sync 会根据锁文件一次性装齐。不使用 uv 时,也可按 pyproject.toml 中的依赖列表用 pip install 手动安装。
3. 配置 API Key
export OPENAI_API_KEY="your-openai-key"
# 其他提供商的 Key 按需导出
evals.py 与 prompt.py 都会调用 load_dotenv(".env") 加载本地 .env 文件,因此你也可以把 Key 写进项目根目录的 .env 中。注意 prompt.py 中的 get_client() 采用惰性初始化——只有真正发起请求时才读取 OPENAI_API_KEY 并创建 AsyncOpenAI 客户端,这样执行 --help 等不触发模型调用的操作时不会因缺 Key 报错。
4. 运行评测
文档中的简化写法是:
uv run python evals.py --model gpt-4o
需要说明的是:从源码看,模板的 evals.py 实际通过 argparse 提供了 run 与 compare 两个子命令,最直接的运行方式为:
# 运行单个模型的基准评测
uv run python evals.py run --model gpt-4o
# 指定实验名称(默认以模型名命名)
uv run python evals.py run --model gpt-4o --name my_first_run
# 合并多个实验 CSV 进行横向对比
uv run python evals.py compare --inputs evals/experiments/a.csv evals/experiments/b.csv --output comparison.csv
运行结束后终端会打印用例数量与准确率摘要(如 gpt-4o Accuracy: 90.00%),结果 CSV 保存在 evals/experiments/ 目录下。
项目结构解读
benchmark_llm/
├── README.md # 项目文档
├── pyproject.toml # 项目配置与依赖
├── prompt.py # Prompt 实现(模型调用入口)
├── evals.py # 评测工作流(指标 + 实验编排 + CLI)
├── __init__.py # Python 包标记
└── evals/
├── datasets/
│ └── discount_benchmark.csv # 客户画像与期望折扣
├── experiments/ # 评测结果(CSV)
└── logs/ # 执行日志
其中 prompt.py 与 evals.py 是模板的两大核心,下面分别深入。
核心一:Prompt 实现(prompt.py)
prompt.py 定义了折扣计算的系统提示词与模型调用函数,是"业务规则"的载体:
SYSTEM_PROMPT = """
You are a discount calculation assistant. I will provide a customer profile and you must calculate their discount percentage and explain your reasoning.
Discount rules:
- Age 65+ OR student status: 15% discount
- Annual income < $30,000: 20% discount
- Premium member for 2+ years: 10% discount
- New customer (< 6 months): 5% discount
Rules can stack up to a maximum of 35% discount.
Respond in JSON format only:
{
"discount_percentage": number,
"reason": "clear explanation of which rules apply and calculations",
"applied_rules": ["list", "of", "applied", "rule", "names"]
}
"""
规则设计上有两个值得留意的点:规则可叠加(如"65 岁以上 + 低收入"可能同时命中 15% 与 20%),但上限封顶 35%;同时要求模型只输出 JSON。这让任务同时考验模型的规则推理能力、条件叠加(cap)约束能力和结构化输出稳定性——正是评测结构化输出任务的理想场景。
模型调用函数为:
async def run_prompt(prompt: str, model: str = DEFAULT_MODEL):
client = get_client()
response = await client.chat.completions.create(
model=model,
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": prompt},
],
)
response = response.choices[0].message.content.strip()
return response
它使用 AsyncOpenAI 异步客户端,并通过 response_format={"type": "json_object"} 强制模型以 JSON 输出,默认模型为 DEFAULT_MODEL = "gpt-4.1-nano-2025-04-14"(见 prompt.py)。模板中"单条 profile 手测"可直接复用:
from prompt import run_prompt
profile = "Premium customer, 5 years tenure, $50k annual spend"
result = await run_prompt(profile, model="gpt-4o")
# 返回: {"discount_percentage": 15, ...}
核心二:评测工作流(evals.py)
evals.py 是模板的评测引擎,分为指标定义、实验编排、CLI 三个层次。
离散指标 discount_accuracy
@discrete_metric(name="discount_accuracy", allowed_values=["correct", "incorrect"])
def discount_accuracy(prediction: str, expected_discount):
"""Check if the discount prediction is correct."""
parsed_json = json.loads(prediction)
predicted_discount = parsed_json.get("discount_percentage")
expected_discount_int = int(expected_discount)
if predicted_discount == expected_discount_int:
return MetricResult(
value="correct",
reason=f"Correctly calculated discount={expected_discount_int}%",
)
else:
return MetricResult(
value="incorrect",
reason=f"Expected discount={expected_discount_int}%; Got discount={predicted_discount}%",
)
这里的 discrete_metric 装饰器来自 src/ragas/metrics/discrete.py,它把普通函数包装成 DiscreteMetric 实例:allowed_values 限定输出的离散类别(默认为 <a href="https://link.gitcode.com/i/93c010569b25fdd674a7db70845a26e9" target="_blank">"pass", "fail"]),并自动生成带 value 与 reason 两个字段的响应模型。返回值 MetricResult(定义于 [src/ragas/metrics/result.py)在携带原始值的同时保留推理理由(reason),既可用于后续准确率统计,也能在分析失败用例时直接看到"期望多少、模型给了多少"的原因说明。
实验编排 @experiment
@experiment()
async def benchmark_experiment(row, model_name: str):
"""Benchmark experiment function that evaluates a model on discount calculation."""
# Get model response
response = await run_prompt(row["customer_profile"], model=model_name)
# Parse response (strict JSON mode expected)
try:
parsed_json = json.loads(response)
predicted_discount = parsed_json.get("discount_percentage")
except Exception:
predicted_discount = None
# Score the response
score = discount_accuracy.score(
prediction=response, expected_discount=row["expected_discount"]
)
return {
**row,
"model": model_name,
"response": response,
"predicted_discount": predicted_discount,
"score": score.value,
"score_reason": score.reason,
}
@experiment 装饰器来自 src/ragas/experiment.py 的 ExperimentProtocol/ExperimentWrapper 机制:被装饰的异步函数自动获得 arun(dataset, name=..., **kwargs) 方法,逐行消费数据集,并把每行的返回结果聚合为 Experiment(DataTable 子类)保存为 CSV。每个实验行会保留客户画像原文、模型名、原始响应、解析出的折扣值、评分与评分理由,形成可审计的评测痕迹。
数据加载与 compare 合并对比
load_dataset()从evals/datasets/discount_benchmark.csv加载数据;若本地缺失会尝试从远端自动下载(见 evals.py),再通过Dataset.load(name="discount_benchmark", backend="local/csv", root_dir=current_dir)读取。compare_inputs_to_output()是模板的"对比神器":要求各实验 CSV 均含id列作为对齐键,校验 ID 集合一致后,以第一个文件的顺序为基准,把每个模型的response/score/score_reason拼接到同一张宽表中,并打印各模型准确率(见 evals.py)。合并结果默认写入evals/experiments/<时间戳>-comparison.csv。
测试数据:discount_benchmark.csv
模板自带的测试集 discount_benchmark.csv 共 10 条用例,每条包含四个字段:
| 字段 | 说明 |
|---|---|
id |
用例唯一标识,compare 合并时作为对齐键 |
customer_profile |
客户画像的自然语言描述(年龄、收入、会员等) |
expected_discount |
期望折扣百分比(Ground Truth) |
description |
用例命中的规则组合说明 |
数据覆盖了丰富的规则组合场景:
- 单规则:如"仅高龄"(70 岁退休人员 → 15%)、"仅低收入"(年收入 2.5 万美元 → 20%)、"仅 2 年以上高级会员"(→ 10%)、"无任何规则命中"(→ 0%);
- 多规则叠加且封顶:如"高龄 + 低收入 + 新客户"(15% + 20% + 5% = 40% → 封顶 35%)、"学生 + 低收入 + 3 年高级会员"(同样封顶 35%);
- 边界情况:64 岁下月满 65、收入恰好 3 万美元、Premium 时长 1 年 6 个月(不足 2 年)等,专门用来考验模型对边界条件的判断是否严格。
这种"简单规则 + 刻意设置的陷阱用例"的数据结构,能有效放大模型之间的推理差异,是基准测试集设计的良好示范——你也可以按照同样的模式构建自己的业务基准集。
多模型横向对比
评测多个模型的方式,就是让同一份数据集分别跑不同 --model:
# GPT-4 系列
uv run python evals.py run --model gpt-4o
# GPT-3.5
uv run python evals.py run --model gpt-3.5-turbo
# Claude
uv run python evals.py run --model claude-3-5-sonnet-20241022
# Gemini / 其他 OpenAI 兼容模型
uv run python evals.py run --model gemini-1.5-pro
每次运行都会在 evals/experiments/ 下生成独立的 CSV。之后用 compare 子命令一键合并:
uv run python evals.py compare \
--inputs evals/experiments/<run1>.csv evals/experiments/<run2>.csv evals/experiments/<run3>.csv
compare 会输出一张以 id 对齐的宽表,每个模型各占一组 response / score / score_reason 列,并在终端打印各模型准确率。这张表可以直接用 pandas 进一步分析:
import pandas as pd
gpt4_results = pd.read_csv("evals/experiments/gpt4_benchmark.csv")
gpt35_results = pd.read_csv("evals/experiments/gpt35_benchmark.csv")
print(f"GPT-4 Accuracy: {(gpt4_results['score'] == 'correct').mean():.1%}")
print(f"GPT-3.5 Accuracy: {(gpt35_results['score'] == 'correct').mean():.1%}")
说明:文档示例中读取
discount_accuracy列,而当前模板实验输出的是score列,两者语义一致(均为指标取值);对比脚本 evals.py 内部也按score == "correct"计算准确率,读者以实际生成的 CSV 列名为准。
除了准确率,score_reason 列能让你逐条查看模型判错的原因——例如是"规则漏判"还是"封顶未生效",从而区分不同模型的失败模式。
自定义:把模板改造成你的基准
换一个任务
benchmark_llm 的价值在于"任务可换、评测框架不变"。只需改 prompt.py 的 SYSTEM_PROMPT 与 evals.py 中打分函数的解析逻辑,即可评测其他能力:
# 代码生成
prompt = "Generate Python code to {task}"
# 摘要
prompt = "Summarize this text in 50 words: {text}"
# 分类
prompt = "Classify this email as spam/not-spam: {email}"
相应的,把 discount_accuracy 换成你自己的离散指标(如 classification_accuracy),allowed_values 改为 ["correct", "incorrect"] 或任意类别集合,并在实验中解析新的响应字段即可。模板已实现的数据加载、@experiment 编排、CSV 落盘与 compare 合并能力全部复用,无需重写。
追加成本与延迟指标
模型选型不只比准确率,prompt.py 的 run_prompt 是异步函数,可以在实验函数内计时,并把成本与延迟一并写进结果:
import time
start = time.time()
response = await run_prompt(profile, model=model_name)
latency = time.time() - start
# 将 latency 与 token 用量等一并加入返回 dict,随实验 CSV 一起保存
结合 score_reason 与延迟、成本数据,你就可以绘制出"准确率 × 延迟 × 成本"的选型决策矩阵。
下一步
- Judge Alignment —— 衡量 LLM-as-Judge 与人工标注的对齐程度,适合在选定模型后校准评测可靠性;
- Prompt Evaluation —— 固定模型、对比不同 Prompt 变体的效果,与本文的"固定 Prompt、对比模型"互为镜像;
- CLI 模板总览 —— 查看更多 quickstart 模板(rag_eval、agent_evals、text2sql、workflow_eval 等);
- 指标底层原理可参考 src/ragas/metrics/discrete.py 与 src/ragas/experiment.py,理解装饰器如何把普通函数升级为可批量评测的实验与指标。