Ragas 评估与测试集生成成本核算实战:TokenUsageParser、TokenUsage 与 total_cost 全解析

原创2026-09-21 19:35:591,396 阅读
文章标签:人工智能AI 评测模型评测RAG大模型LLMOps数据增强

Ragas 评估与测试集生成成本核算实战:TokenUsageParser、TokenUsage 与 total_cost 全解析

在基于 LLM 的评估(evaluation)与测试集生成(test set generation)流程中,成本是上线前必须考虑的核心因素:一次完整的多指标评估会调用成百上千次 LLM 推理,每次推理都产生输入/输出 token 费用。Ragas 为此提供了一套轻量、可插拔的计费工具链——TokenUsageParser、TokenUsage 与 CostCallbackHandler。读完本文,你将掌握:为什么 Ragas 默认不统计 token 用量、如何接入内置解析器或编写自定义解析器、如何在 evaluate() 与 TestsetGenerator 中启用成本统计,以及如何用 total_tokens() / total_cost() 精确核算单次或多次运行的投入。

为什么默认不统计 token 用量

在 evaluate() 或 aevaluate() 的默认行为中,Ragas 不会计算 token 用量。原因很直接:LangChain 系的 LLM 封装并不会以统一格式返回 token 用量信息——OpenAI、Anthropic、Bedrock、Azure AI 等各家的 LLMResult / ChatResult 结构差异明显,甚至同一家在不同调用路径下也可能缺字段。因此,Ragas 把"从 LLM 返回结果中提取 token 数据"这一步抽象成可替换的函数,即 TokenUsageParser,由使用者按需注入。

这意味着:你不需要为了计费付出额外推理成本,也无需改变现有评估代码——只需在调用时多传一个参数。

核心概念:TokenUsageParser 与 TokenUsage

TokenUsageParser:一个函数类型

从源码 src/ragas/cost.py 可以看到其类型定义:

TokenUsageParser = t.Callable[[t.Union[LLMResult, ChatResult]], "TokenUsage"]

它本质是一个函数:接收 LangChain 模型 generate_prompt() 返回的 LLMResult 或 ChatResult,输出一个 Ragas 约定的 TokenUsage 对象。任何满足"入参是结果对象、出参是 TokenUsage"的可调用对象都可以作为解析器。

TokenUsage:统一的数据结构

TokenUsage 是 Pydantic 模型(src/ragas/cost.py),包含三个字段:

字段 类型 说明
input_tokens int 输入(prompt)token 数
output_tokens int 输出(completion)token 数
model str = "" 模型名,用于多模型场景下的分类聚合

TokenUsage 还实现了 __add__ 运算符重载:两个同模型(或模型字段为空)的用量可以直接相加;若模型不同则抛出 ValueError,避免混算不同模型的 token。其 cost() 方法则负责把 token 数乘以单价换算为金额。

内置解析器:四大厂商开箱即用

src/ragas/cost.py 提供了四个内置解析器,可直接 import:

from ragas.cost import (
    get_token_usage_for_openai,
    get_token_usage_for_anthropic,
    get_token_usage_for_bedrock,
    get_token_usage_for_azure_ai,
)
  • get_token_usage_for_openai:从 llm_result.llm_output["token_usage"] 中读取 prompt_tokens / completion_tokens,模型名取自 model_name;
  • get_token_usage_for_anthropic:遍历 generations,从每条 ChatGeneration.message.response_metadata 的 usage.input_tokens / usage.output_tokens 聚合;
  • get_token_usage_for_bedrock:从 response_metadata 的 usage.prompt_tokens / usage.completion_tokens 聚合,模型名取 model_id;
  • get_token_usage_for_azure_ai:从 llm_output["token_usage"] 读取 input_tokens / output_tokens。

这些解析器的行为都被单元测试覆盖在 tests/unit/test_cost.py 中,例如对 OpenAI 结果的断言 TokenUsage(input_tokens=10, output_tokens=10, model="gpt-4o")。若某字段缺失,解析器会回退为 0,且当 llm_output 为 None 时记录 info 日志并返回全 0 的 TokenUsage,不会中断评估流程——这是容错设计,保证在计费信息缺失时评估照常进行。

实战一:在 evaluate() 中接入解析器并核算成本

1. 准备 LLM 并单独验证解析器

先实例化模型并直接调用 generate_prompt(),验证解析器能否正确解析:

import os

os.environ["OPENAI_API_KEY"] = "your-api-key"

from langchain_openai.chat_models import ChatOpenAI
from langchain_core.prompt_values import StringPromptValue
from ragas.cost import get_token_usage_for_openai

gpt4o = ChatOpenAI(model="gpt-4o")
p = StringPromptValue(text="hai there")
llm_result = gpt4o.generate_prompt([p])

get_token_usage_for_openai(llm_result)
# TokenUsage(input_tokens=9, output_tokens=9, model='')

这是最小可复现路径:先确认"模型返回结构 → 解析器 → TokenUsage"链路通畅,再进入完整评估。

2. 构建评估数据集与指标

沿用 快速开始示例 的用法,加载 Hugging Face 数据集构造 EvaluationDataset,并定义一个带参考答案的方面评判指标:

from datasets import load_dataset
from ragas import EvaluationDataset
from ragas.metrics._aspect_critic import AspectCriticWithReference

dataset = load_dataset("vibrantlabsai/amnesty_qa", "english_v3")

eval_dataset = EvaluationDataset.from_hf_dataset(dataset["eval"])

metric = AspectCriticWithReference(
    name="answer_correctness",
    definition="is the response correct compared to reference",
)

3. 通过 token_usage_parser 参数启用计费

evaluate() 的 token_usage_parser 参数(src/ragas/evaluation.py)接受任意 TokenUsageParser。传入后会触发内部逻辑:在 evaluation.py 中,Ragas 会实例化 CostCallbackHandler(token_usage_parser=...) 并把它注册进 LangChain 的回调管理器,从而在每次 LLM 调用结束时自动收集用量:

from ragas import evaluate
from ragas.cost import get_token_usage_for_openai

results = evaluate(
    eval_dataset[:5],
    metrics=[metric],
    llm=gpt4o,
    token_usage_parser=get_token_usage_for_openai,
)

4. 查看总 token 用量

评估完成后,EvaluationResult.total_tokens()(src/ragas/dataset_schema.py)返回累计用量:

results.total_tokens()
# TokenUsage(input_tokens=5463, output_tokens=355, model='')

从底层实现看,total_tokens() 委托给 CostCallbackHandler.total_tokens():handler 把所有收集到的 TokenUsage 按 model 字段分组累加,若只有一种模型则直接返回单个 TokenUsage,多模型则返回 TokenUsage 列表(src/ragas/cost.py)。

5. 换算为真实花费

EvaluationResult.total_cost()(src/ragas/dataset_schema.py)接受两个单价参数:cost_per_input_token 与 cost_per_output_token(单位:每 token 的价格,美元)。

以 GPT-4o 官方按量计费口径为例:输入 $5 / 1M tokens、输出 $15 / 1M tokens:

results.total_cost(cost_per_input_token=5 / 1e6, cost_per_output_token=15 / 1e6)
# 0.03264

即这次 5 条样本的单指标评估,约花费 $0.033。核算公式对应 TokenUsage.cost() 的实现:input_tokens × 输入单价 + output_tokens × 输出单价;若只传输入单价,输出单价默认与输入单价相同。

6. 多模型场景:per_model_costs 参数

若评估流程同时使用多个模型(例如 LLM 评判 + 嵌入模型 + 生成模型),不同模型单价不同,此时应使用 CostCallbackHandler.total_cost() 的 per_model_costs 参数(src/ragas/cost.py):

results.total_cost(
    per_model_costs={
        "gpt-4o": (5 / 1e6, 15 / 1e6),
        "gpt-4o-mini": (0.15 / 1e6, 0.6 / 1e6),
    }
)

实现逻辑是:先按 model 字段分组各模型用量;若只有一种模型,则优先查 per_model_costs(找不到会抛出 ValueError),否则退化为使用统一的 cost_per_input_token / cost_per_output_token;若存在多种模型,则遍历 per_model_costs 逐模型求和。三种传参方式中,未提供任何成本参数时直接抛错提示,避免静默返回无意义结果。

7. 忘记配置解析器会怎样

如果没传 token_usage_parser 就调用 total_tokens() / total_cost(),会得到明确的 ValueError(src/ragas/dataset_schema.py):

The evaluate() run was not configured for computing cost. Please provide a token_usage_parser function to evaluate() to compute cost.

这既是防呆,也是提示:成本统计是显式开启的能力,不会偷偷影响默认评估行为。

实战二:测试集生成的成本核算

成本核算同样适用于测试集生成。TestsetGenerator 的 generate() 方法同样接受 token_usage_parser(src/ragas/testset/synthesizers/generate.py),内部以同样的方式挂载 CostCallbackHandler(generate.py):

from ragas.testset import TestsetGenerator
from ragas.cost import get_token_usage_for_openai

generator = TestsetGenerator(llm=gpt4o, embeddings=embeddings)

testset = generator.generate_with_langchain_docs(
    documents,
    testset_size=10,
    token_usage_parser=get_token_usage_for_openai,
)

testset.total_tokens()
testset.total_cost(cost_per_input_token=5 / 1e6, cost_per_output_token=15 / 1e6)

Testset.total_tokens() 与 Testset.total_cost() 定义在 src/ragas/testset/synthesizers/testset_schema.py,未配置解析器时同样抛出引导性 ValueError。这对于评估"合成 N 条测试数据要花多少钱"、控制批量生成预算非常实用。

自定义解析器:接入任意 LLM 提供商

如果目标提供商不在内置解析器之列,写一个自定义解析器即可。以虚构的 "MyLLM" 为例,假设其用量信息位于 llm_output["usage"]:

from langchain_core.outputs import LLMResult, ChatResult
from ragas.cost import TokenUsage


def get_token_usage_for_myllm(
    llm_result: LLMResult | ChatResult,
) -> TokenUsage:
    llm_output = llm_result.llm_output
    if llm_output is None:
        return TokenUsage(input_tokens=0, output_tokens=0)

    usage = llm_output.get("usage", {})
    return TokenUsage(
        input_tokens=usage.get("input_tokens", 0),
        output_tokens=usage.get("output_tokens", 0),
        model=llm_output.get("model_name", ""),
    )

关键设计约束(与内置解析器保持一致):

  • 入参必须同时兼容 LLMResult 与 ChatResult;
  • 字段缺失时回退为 0,llm_output 为 None 时返回全 0,保证容错;
  • 正确填充 model 字段,多模型聚合才准确。

自定义后同样传入 token_usage_parser=get_token_usage_for_myllm 即可。

底层机制:CostCallbackHandler 如何工作

所有成本统计的底座是 CostCallbackHandler(src/ragas/cost.py),它继承自 LangChain 的 BaseCallbackHandler:

  1. 初始化:构造时接收 TokenUsageParser,内部维护 usage_data: List[TokenUsage] 累积每次调用的用量;
  2. 采集:重写 on_llm_end(response: LLMResult),每次 LLM 调用结束即调用解析器并把结果追加进 usage_data;
  3. 聚合:total_tokens() 按模型分组求和;total_cost() 按单价或 per_model_costs 换算并汇总。

在 evaluate() / aevaluate() 中,当检测到 token_usage_parser is not None 时,Ragas 会创建该 handler 并追加到传入的 callbacks(src/ragas/evaluation.py),因此它只对本次评估生效,不影响全局配置。测试集生成侧(generate.py)采用了完全相同的挂载方式。这一设计也体现在 tests/unit/test_cost.py 中:直接 cost_cb.on_llm_end(...) 后断言 total_tokens() 与 total_cost(0.1) == 2.0,验证了 handler 的独立可测性。

成本核算工作流速查

  1. 确认模型厂商 → 选择内置解析器(OpenAI / Anthropic / Bedrock / Azure AI)或编写自定义解析器;
  2. evaluate(dataset, metrics, llm, token_usage_parser=parser) 或在 TestsetGenerator.generate* 中传入同名参数;
  3. 评估 / 生成结束后调用 results.total_tokens() 或 testset.total_tokens() 查看用量;
  4. 依据最新官方定价,调用 results.total_cost(cost_per_input_token=..., cost_per_output_token=...),多模型时改用 per_model_costs 字典;
  5. 将成本核算固化进 CI 或批量实验脚本,持续监控每次迭代的投入产出。

需要注意的是:文中单价(如 GPT-4o $5/$15 per 1M tokens)仅为文档示例口径,实际应以模型提供商的最新官方定价为准;total_cost 只是按你提供的单价做算术换算,本身不内置任何厂商价目表。

结语

Ragas 的成本统计体系把"token 用量采集"与"费用核算"解耦:解析器负责解决各家 LLM 返回结构不统一的痛点,CostCallbackHandler 以回调方式无侵入地旁路采集,total_tokens() / total_cost() 则提供聚合与换算的最终出口。无论你是想在上线评估前估算预算,还是想为 CI 中的每次回归评估记账,这套机制都能在几乎零改造成本的前提下,让"每次评估花了多少钱"变得一目了然。

登录后查看全文
ragas