基于 Ragas CLI 模板的 LLM 基准评测实战:用 `benchmark_llm` 横向对比折扣计算任务的模型准确率

原创2026-09-21 16:26:501,928 阅读
文章标签:人工智能AI 评测模型评测RAG大模型LLMOps数据增强

基于 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,理解装饰器如何把普通函数升级为可批量评测的实验与指标。
登录后查看全文
ragas