taolib.harness.eval.metrics

taolib.harness.eval.metrics#

指标收集器 - 评估指标的协议、预置实现、注册表与聚合工具。

本模块提供可扩展的指标体系：

Classes#

CompositeMetric

组合指标 - 对若干子指标按权重线性加权求总分。

ContainsMatch

包含匹配指标 - 期望文本是否被实际文本包含。

CostMetric

成本估算指标 - 按 prompt/completion 单价折算总成本（美元）。

ExactMatch

精确匹配指标 - 字符串完全一致返回 1.0，否则 0.0。

LatencyMetric

延迟测量指标 - 直接读取 kwargs['latency']（秒）。

Metric

指标接口 - 任意可计算评估指标的最小契约。

MetricAggregator

指标聚合器 - 对一系列样本计算均值、分位、标准差。

MetricRegistry

指标注册表 - 支持按名称登记/查询/批量装配。

MetricSummary

单个指标在一组样本上的统计摘要。

TokenUsageMetric

Token 用量指标 - 读取 kwargs['tokens'] 字典并按字段累加。

Module Contents#

class taolib.harness.eval.metrics.CompositeMetric(name: str, components: collections.abc.Sequence[tuple[Metric, float]])#

组合指标 - 对若干子指标按权重线性加权求总分。

compute(predicted: Any, expected: Any, /, **kwargs: Any) → MetricValue#
name#
class taolib.harness.eval.metrics.ContainsMatch(*, case_sensitive: bool = False)#

包含匹配指标 - 期望文本是否被实际文本包含。

compute(predicted: Any, expected: Any, /, **_: Any) → MetricValue#
name = 'contains_match'#
class taolib.harness.eval.metrics.CostMetric(*, prompt_price_per_1k: float = 0.0, completion_price_per_1k: float = 0.0)#

成本估算指标 - 按 prompt/completion 单价折算总成本（美元）。

compute(predicted: Any, expected: Any, /, **kwargs: Any) → MetricValue#
name = 'cost'#
class taolib.harness.eval.metrics.ExactMatch(*, case_sensitive: bool = True, strip: bool = True)#

精确匹配指标 - 字符串完全一致返回 1.0，否则 0.0。

compute(predicted: Any, expected: Any, /, **_: Any) → MetricValue#
name = 'exact_match'#
class taolib.harness.eval.metrics.LatencyMetric#

延迟测量指标 - 直接读取 kwargs['latency']（秒）。

compute(predicted: Any, expected: Any, /, **kwargs: Any) → MetricValue#
name = 'latency'#
class taolib.harness.eval.metrics.Metric#

Bases: Protocol

指标接口 - 任意可计算评估指标的最小契约。

compute(predicted: Any, expected: Any, /, **kwargs: Any) → MetricValue#

计算单次指标得分。

参数:

  • predicted -- Agent 实际输出。

  • expected -- 期望输出（可选，部分指标如延迟无需期望值）。

  • **kwargs -- 额外上下文（如 latency、tokens）。

name: str#

指标名，用于在结果与报告中标识该指标。

class taolib.harness.eval.metrics.MetricAggregator#

指标聚合器 - 对一系列样本计算均值、分位、标准差。

static aggregate(name: str, values: collections.abc.Iterable[float]) → MetricSummary#

聚合指定名称下的一组样本。

static aggregate_many(rows: collections.abc.Iterable[collections.abc.Mapping[str, float]]) → dict[str, MetricSummary]#

对每个指标列分别聚合，返回 {metric_name: summary} 映射。

class taolib.harness.eval.metrics.MetricRegistry#

指标注册表 - 支持按名称登记/查询/批量装配。

get(name: str) → Metric#

按名称获取指标，不存在则抛出 KeyError。

names() → list[str]#

所有已登记的指标名。

register(metric: Metric, *, alias: str | None = None) → None#

登记一个指标实例。

resolve(names: collections.abc.Iterable[str]) → list[Metric]#

按名称批量解析指标实例列表。

unregister(name: str) → Metric | None#

注销并返回原指标。

classmethod with_defaults() → MetricRegistry#

构造内置默认指标的注册表。

class taolib.harness.eval.metrics.MetricSummary#

Bases: pydantic.BaseModel

单个指标在一组样本上的统计摘要。

count: int = 0#
maximum: float = 0.0#
mean: float = 0.0#
minimum: float = 0.0#
model_config#
name: str#
p50: float = 0.0#
p95: float = 0.0#
p99: float = 0.0#
samples: list[float]#
stdev: float = 0.0#
class taolib.harness.eval.metrics.TokenUsageMetric(*, field: str = 'total')#

Token 用量指标 - 读取 kwargs['tokens'] 字典并按字段累加。

compute(predicted: Any, expected: Any, /, **kwargs: Any) → MetricValue#
name = 'tokens'#