跳转到主要内容
此功能为实验性功能。标志、输出结构和行为可能会在不同版本之间发生变化。请在受控工作流中使用，并在 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

​
这个命令的作用

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

​
标记

  • --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

​
另请参见