eval

此功能为实验性功能。标志、输出结构和行为可能会在不同版本之间发生变化。请在受控工作流中使用，并在 CI 中固定版本。随着评估工作流逐渐成熟，报告架构和评分行为可能会发生变化。

使用 eval 命令在具有代表性的评估集上对翻译质量进行基准测试，并在 CI 中强制执行质量阈值。

用法

hyperlocalise eval run --eval-set <path> [flags]
hyperlocalise eval compare --candidate <path> --baseline <path> [flags]

评估运行

在你的评估集上运行一个或多个实验变体。

求值流程

eval set
  |
  v
expand experiment matrix
  |
  v
translate each case with each experiment
  |
  +--> heuristic lane
  |      - placeholder / ICU / tag checks
  |      - length / forbidden-term / locale checks
  |      - reference similarity
  |
  +--> judge lane (optional)
  |      - llm-rubric
  |      - factuality
  |      - g-eval
  |      - model-graded-closedqa
  |      - answer-relevance
  |      - context-faithfulness
  |      - context-recall
  |
  v
per-run result
  - quality.weightedAggregate
  - judgeAggregateScore
  - finalScore
  - decision
  |
  v
report aggregates
  - overall aggregate
  - byLocale

这个命令的作用

从--eval-set加载评估数据集。
从数据集 experiments 中，或从你选择的配置文件、提供商、模型和提示覆盖中扩展实验变体。
针对每个实验变体执行每个用例。
使用内置启发式通道对每个翻译进行评分。
当你同时传入 --eval-provider 和 --eval-model 时，可选地添加一个 LLM 裁判通道。
将启发式质量和成功的裁判得分协调为每次运行一个finalScore。
当你传入 --output 时，会写入一份 JSON 报告。
打印简洁的每个实验摘要表。

标记

--eval-set：评估数据集的路径（.yaml、.yml）（必需）
--profile：配置文件名称覆盖（可重复）
--provider：提供程序覆盖（可重复）
--model：模型覆盖（可重复）
--prompt-file：提示文件覆盖
--prompt：内联提示覆盖（与--prompt-file互斥）
--eval-provider：用于 LLM 评估的提供程序。当请求 judge 评估时，默认为 openai。
--eval-model：用于 LLM 评估的模型。当请求 judge 评估时，默认为 gpt-5.2。
--eval-prompt-file：评估提示文件覆盖
--eval-prompt：内联评估提示覆盖（与 --eval-prompt-file 互斥）
--assertion：要运行的 judge 断言（可重复）。支持的值：llm-rubric、factuality、g-eval、model-graded-closedqa、answer-relevance、context-faithfulness、context-recall
--baseline：使用 --interactive 时用于比较的基线评估报告 JSON 路径
--output: JSON 输出报告路径

当你请求评审评估时，LLM 评估模式会开启，无论是显式通过 --eval-provider、--eval-model、--eval-prompt 或 --assertion，还是通过 eval-set 评审断言隐式开启。如果请求了评审评估，而你省略了 provider/model，Hyperlocalise 将默认使用 openai 和 gpt-5.2。你的翻译标志保持其当前含义。--eval-* 标志只控制评审通道。在 LLM 评估模式下，参考译文是可选的。当存在时，评估器会将它们用作风格和语气指导。在 YAML eval-set 格式中，reference 是正常的目标侧字段。assert 是可选的。数据集级别的 experiments 和 judge 是可选的。如果你在 YAML 中定义了它们，并且没有传递 CLI 覆盖项，eval run 会直接使用这些设置。如果你传入 --profile、--provider、--model 或 --prompt 中的任意一个，CLI 实验矩阵将覆盖数据集 experiments。如果你传入 --eval-provider、--eval-model、--eval-prompt 或 --assertion 中的任意一个，这些 CLI 值将覆盖数据集 judge 字段。如果你不传入任何--assertion，默认的 judge 断言是llm-rubric。未知的断言名称会快速失败。

评分机制如何运作

quality.weightedAggregate 是该次运行的内置启发式评分。
judgeAggregateScore 是该运行中成功的 judge 断言的平均值。
finalScore 是报告中用于诊断的调和后分数。
decision 是此次运行的粗略结果：pass、review 或 fail。

当前对账规则：

翻译错误会强制 finalScore=0 和 decision=fail
启发式硬性失败强制 finalScore=0 和 decision=fail
当判定车道不可用时，finalScore 会回退到启发式分数
当两条车道都可用时，finalScore = 0.65 * heuristic + 0.35 * judge

汇总表字段

score：实验的平均加权质量分数
pass_rate：实验的成功运行次数 / 总运行次数
placeholder_violations：占位符完整性严重失败违规计数
latency_ms：实验的平均延迟

示例

使用配置中的默认值运行并写入报告：

hyperlocalise eval run \
  --eval-set ./evalsets/core.yaml \
  --output ./artifacts/eval-report.json

运行一组配置文件和提供方/模型覆盖项：

hyperlocalise eval run \
  --eval-set ./evalsets/core.yaml \
  --profile default \
  --profile fast \
  --provider openai \
  --provider anthropic \
  --model gpt-4.1-mini \
  --model claude-sonnet-4-5

使用提示文件覆盖运行：

hyperlocalise eval run \
  --eval-set ./evalsets/core.yaml \
  --prompt-file ./prompts/translation-eval.txt

使用内联评判提示运行 LLM 评估：

hyperlocalise eval run \
  --eval-set ./evalsets/core.yaml \
  --eval-provider openai \
  --eval-model gpt-4.1-mini \
  --eval-prompt "Score translation quality from 0.0 to 1.0 and explain briefly." \
  --output ./artifacts/eval-report.json

一次运行多个断言判定器：

hyperlocalise eval run \
  --eval-set ./evalsets/core.yaml \
  --eval-provider openai \
  --eval-model gpt-4.1-mini \
  --assertion llm-rubric \
  --assertion factuality \
  --assertion g-eval \
  --assertion context-faithfulness \
  --output ./artifacts/eval-report.json

使用评审提示文件运行 LLM 评估：

hyperlocalise eval run \
  --eval-set ./evalsets/core.yaml \
  --eval-provider anthropic \
  --eval-model claude-sonnet-4-5 \
  --eval-prompt-file ./prompts/eval-judge.txt \
  --output ./artifacts/eval-report.json

在 CI 中使用 eval 并检查保存的报告：

hyperlocalise eval run \
  --eval-set ./evalsets/release-gate.yaml \
  --provider openai \
  --model gpt-4.1-mini \
  --eval-provider openai \
  --eval-model gpt-4.1-mini \
  --assertion llm-rubric \
  --assertion factuality \
  --output ./artifacts/eval-candidate.json

报告示例

示例评估集：

experiments:
  - id: ollama-translategemma
    provider: ollama
    model: translategemma
  - id: ollama-lfm2-24b
    provider: ollama
    model: lfm2:24b
judge:
  provider: openai
  model: gpt-5.2
  assertions:
    - llm-rubric
    - factuality
tests:
  - id: checkout-cta
    vars:
      source: "Save account settings"
      context: "Primary CTA on the checkout settings page"
    locales:
      - locale: fr-FR
        reference: "Enregistrer les parametres du compte"
      - locale: de-DE
        reference: "Kontoeinstellungen speichern"

带有显式断言的示例：

experiments:
  - id: ollama-translategemma
    provider: ollama
    model: translategemma
tests:
  - id: checkout-cta
    vars:
      source: "Save account settings"
    assert:
      - type: judge.translation_quality
        threshold: 0.85
    locales:
      - locale: fr-FR
        reference: "Enregistrer les parametres du compte"
        assert:
          - type: contains
            value: "compte"

运行一个已经定义了 Ollama 实验的数据集：

hyperlocalise eval run \
  --eval-set ./eval_dataset/article_001.yaml \
  --output ./artifacts/eval-report.json

由--output写入的 JSON 的精简示例：

{
  "aggregate": {
    "weightedScore": 0.812,
    "averageJudgeScore": 0.847,
    "finalScore": 0.824,
    "decisionCounts": {
      "pass": 18,
      "review": 3,
      "fail": 1
    },
    "byLocale": {
      "fr-FR": {
        "totalRuns": 10,
        "finalScore": 0.851
      },
      "de-DE": {
        "totalRuns": 12,
        "finalScore": 0.802
      }
    }
  },
  "experimentSummaries": [
    {
      "experimentId": "ollama-translategemma",
      "runCount": 11,
      "successfulRuns": 11,
      "averageJudgeScore": 0.838,
      "weightedScore": 0.806,
      "finalScore": 0.817,
      "decisionCounts": {
        "pass": 8,
        "review": 3
      }
    },
    {
      "experimentId": "ollama-lfm2-24b",
      "runCount": 11,
      "successfulRuns": 11,
      "averageJudgeScore": 0.856,
      "weightedScore": 0.819,
      "finalScore": 0.832,
      "decisionCounts": {
        "pass": 10,
        "review": 1
      }
    }
  ],
  "llmEvaluation": {
    "enabled": true,
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "assertions": [
      "llm-rubric",
      "factuality"
    ],
    "aggregateScore": 0.847,
    "averageScoreByName": {
      "judge:llm-rubric": 0.835,
      "judge:factuality": 0.859
    },
    "failedByName": {
      "judge:factuality": 1
    }
  },
  "runs": [
    {
      "caseId": "checkout.cta",
      "targetLocale": "fr-FR",
      "assertionResults": [
        {
          "type": "judge.translation_quality",
          "passed": true,
          "threshold": 0.85,
          "score": 0.88
        },
        {
          "type": "contains",
          "passed": true,
          "expected": "compte"
        }
      ],
      "judgeAggregateScore": 0.88,
      "quality": {
        "weightedAggregate": 0.91
      },
      "finalScore": 0.9,
      "decision": "pass",
      "judgeResults": {
        "judge:llm-rubric": {
          "score": 0.86
        },
        "judge:factuality": {
          "score": 0.9,
          "details": {
            "grounded": true,
            "hallucinations": []
          }
        }
      }
    }
  ]
}

使用顶层报告进行趋势跟踪，并使用每次运行记录进行诊断：

experimentSummaries 是按 finalScore、weightedScore 或通过/复审/失败混合方式比较模型变体的最快方法。
aggregate.byLocale 是定位回归问题最快的方式。
llmEvaluation.averageScoreByName 显示了是哪一组断言在拖累 judge lane。
assertionResults 显示显式 eval-set 期望是否已通过。
judgeResults 详情解释特定断言的失败，例如幻觉、缺乏支持的主张或缺失的上下文事实。

评估比较

将候选报告与基线报告进行比较。在 CI 中使用此命令以防止质量回退。工作流程保持不变：先运行eval run，然后运行eval compare。

标志

--candidate：候选报告 JSON 路径（必填）
--baseline：基线报告 JSON 路径（必填）
--min-score：最低候选分数
--max-regression：从基线到候选的允许最大分数回退

CI 行为

eval compare 在两个报告都包含可用的 LLM 裁判汇总分数时，优先使用 LLM 汇总分数。否则，它会回退到启发式加权分数。这意味着 eval compare 当前基于以下条件进行门控：

当在两份报告中都启用了 LLM 评估时的 LLM 裁判汇总
在没有可用的 LLM 评判聚合时使用启发式聚合

它目前并不受 finalScore 的限制。当以下情况时，命令会以错误退出：

候选分数低于--min-score，或者
分数回归超过 --max-regression。

示例

仅比较报告并打印汇总值：

hyperlocalise eval compare \
  --candidate ./artifacts/eval-candidate.json \
  --baseline ./artifacts/eval-baseline.json

如果候选分数低于 0.82 或回退幅度超过 0.02，则使 CI 失败：

hyperlocalise eval compare \
  --candidate ./artifacts/eval-candidate.json \
  --baseline ./artifacts/eval-baseline.json \
  --min-score 0.82 \
  --max-regression 0.02

Getting Started

Configuration

Commands

Workflows

Providers

TMS Adapters

Troubleshooting

Reference & Concepts

Contributing

用法

评估运行

求值流程

这个命令的作用

标记

评分机制如何运作

汇总表字段

示例

报告示例

评估比较

标志

CI 行为

示例

另请参见

​用法

​评估运行

​求值流程

​这个命令的作用

​标记

​评分机制如何运作

​汇总表字段

​示例

​报告示例

​评估比较

​标志

​CI 行为

​示例

​另请参见

用法

评估运行

求值流程

这个命令的作用

标记

评分机制如何运作

汇总表字段

示例

报告示例

评估比较

标志

CI 行为

示例

另请参见