Skip to content

Add an API-based LLM Judge metric for SLU answers - #38

Merged
Jason040114 merged 3 commits into
X-LANCE:mainfrom
zh820:feat/llm-judge
Nov 10, 2026
Merged

Jason040114 merged 3 commits into
X-LANCE:mainfrom
zh820:feat/llm-judge

Conversation

@zh820

@zh820 zh820 commented Oct 28, 2026

Copy link
Copy Markdown
Contributor

Start Here

Read Contributing. If the category is unclear, use
Add Evaluation Capabilities.

Summary

Add an optional API-based LLM Judge metric for textual SLU answers.

  • Accept questions and candidate answers, with optional text context, choices,
    and aligned reference answers.
  • Return an integer score from 1 to 5 and a reason for each sample.
  • Aggregate by arithmetic mean only when every sample succeeds.
    Failed batches retain per-sample evidence and report a null aggregate.
  • Preserve the existing default accuracy routes.
  • Add offline node, CLI, failure-handling, and report compatibility tests.

PR Type

  • New task
  • New metric
  • New pipeline route
  • Node/tool/version change
  • Maintenance

Guide followed: docs/pr_guides/new_metric.md.
Documentation requirements are still pending.

Guide followed:

Evaluation Identity

  • Reported metric: llm_judge
  • execution_metrics: llm_judge
  • Added pipeline_id: slu.any.llm_judge.llm_judge_v1
  • Default route changed: no
  • Score comparability changed: a new score is introduced; existing accuracy
    scores are unchanged. Judge scores are not directly equivalent to accuracy.

Score definition: each sample receives an integer in [1, 5], with higher
being better. The aggregate is the sum of sample scores divided by the
number of samples, provided all samples succeed.

Changed Declarations

  • Task manifest: yes
  • Task routes: yes
  • Node manifest: yes
  • node_env.yaml: yes
  • Node README follows docs/node_readme_template.md: no — pending
  • Catalog regenerated: yes
  • Catalog discovery task or curated bundle changed: no
  • Documentation coverage: pending. The current commit contains implementation,
    declarations, the generated pipeline catalog, and tests. The node README,
    task guide, and generated atlas still need review/update. Unrelated README
    translations are not included.

Validation

Commands run in the prepared local/Linux environments:

python -m pytest tests/test_llm_judge_slu.py tests/test_llm_judge_errors.py -q
python -m ruff check .
python -m pytest tests --ignore=tests/test_evaluation_env_check.py -ra -q
python -m pytest tests/test_evaluation_env_check.py -q \
  -k "in_process or pip_runtime or dry_run or doctor or cache_dir or se_pip_runtime_nodes_are_declared"
python scripts/generate_pipeline_catalog.py
git diff --check

Results:

  • Focused Judge tests: 153 passed.
  • Portable suite: 674 passed, 65 skipped.
  • Selected environment metadata tests: 15 passed.
  • Ruff and whitespace checks passed.
  • Wheel/sdist build, packaged node assets, and installed-wheel Judge CLI passed.

The skipped portable tests require existing optional normalization environments,
dependencies, or harness-only artifacts. No focused Judge tests were skipped.

Exact pipeline selection and preservation through describe -> run -> report
are covered by:

  • test_slu_judge_routes_and_default_accuracy
  • test_cli_routes_describe_run_and_standard_outputs
  • test_judge_report_matches_accuracy_envelope

Expected pipeline:
slu.any.llm_judge.llm_judge_v1

Runtime Smoke Test

This is an API-based node without local model checkpoints or GPU requirements.

A real API smoke test completed successfully for three textual samples.
Automated tests use fake credentials and mocked API responses; no real API
credentials are required by CI.

Safety

  • No .venv, checkpoints, generated reports, local cache paths, or credentials committed
  • No private absolute paths in committed config or docs
  • Score-affecting behavior is declared in route/node identity
  • Existing default route behavior is tested and preserved

@PigeonDan1

Copy link
Copy Markdown
Collaborator

#38 审阅反馈与修改要求

审阅 head:8d564f448e824037123dcac2c2252880706fa624。

可选 SLU 文本 Judge 的接入方向合理,现有 accuracy 默认路线应继续保留。当前请保持 Draft,由作者完成下面的修复、文档和测试后再提交审阅。

1. HTTP 响应截断会丢失整批报告

call_judge() 中 response.read() 可能抛出 http.client.IncompleteRead,该异常没有被现有 OSError / UnicodeError / ValueError 捕获并转换为 JudgeError。样本循环因此直接退出,executor 返回前就失败,report.json 和 pipeline_description.json 均未写出。

已通过真实本地 HTTP 服务复现:

  • 第一条正常返回 4 分。
  • 第二条声明 Content-Length: 9999,只发送 12 bytes 后断开。
  • CLI exit 1,消息为 IncompleteRead(12 bytes read, 9987 more expected);此前成功样本的报告也未保存。
  • 安装 wheel 后复现结果相同。

请在 HTTP adapter 边界处理实际传输/协议异常(包括 http.client.HTTPException),转换成稳定错误码,沿用已有的逐样本失败记录和完整批次聚合政策。无需为此引入新环节或大范围吞掉所有实现异常。

必要回归:第一条成功、第二条响应截断,最终仍落报告,包含两条样本结果,num_scored=1、num_failed=1、总分 null,CLI exit 1。HTTP 失败不能被转换为 0 分后参与均值。

2. Catalog / atlas 未完整重生成

原 head 执行 scripts/generate_pipeline_catalog.py 后,Judge 条目从两条 SLU accuracy 条目之前移动到之后。虽然总数仍为 171,git diff --exit-code docs/pipeline_catalog.jsonl 返回 1,说明现有 catalog CI 就会失败。

三份 atlas 产物也未同步。在本地模拟合入最新 main 后,Git 无文本冲突,KOMOS 保留,catalog 共 178 条;但条目顺序和图谱仍有差异,不能通过最新 main 的 catalog/atlas freshness 检查。

请先同步最新 main,再通过生成器更新并提交 catalog 和三份 atlas,保持现有检查。不要通过删除检查或手动调整生成结果来绕过问题。

3. 产品要求:rubric 由用户输入,默认采用百分制

这里调整此前“由仓库提供默认五档 rubric”的建议:具体评分 rubric 由用户自行定义并作为输入提供;框架默认使用 0–100 分、越高越好的百分制。

请相应修改接口和实现:

  • 为用户 rubric 提供明确的输入方式,例如配置中的文本或一个 rubric 文件。缺失、空白 rubric 应在调用 API 前给出清楚的输入错误。
  • 默认评分范围改为 [0, 100],同步请求提示、响应校验、报告 score_range、文档和测试。有限数值的整数/小数及精度政策请明确说明;布尔、非有限值和越界分数应拒绝。
  • 现有固定“1–5 分”提示与整数验证不能继续与用户 rubric 冲突,也不要简单把旧五分制乘 20 当成这次接口修改。
  • 框架负责承载 rubric、约束输出、校验响应和聚合;具体正确性/完整性/相关性评分标准由用户定义。
  • 报告应能追溯实际 rubric、其内容哈希/版本、有效分数范围和裁判配置,不记录 API key。保持现有“全部成功才计算样本等权均值,否则总分 null”的行为。
  • 0–100 是本指标的评分尺度,不自动代表 accuracy 百分比;现有 accuracy 的定义与默认行为应保持原样。

请说明 ref/context 与证据要求:Judge 无法直接听音频,对于依赖音频事实的问题,用户应提供足以判断的文本证据或参考答案,并在 rubric 中定义证据不足如何处理。

4. 文档和声明需要补齐

请按现有 docs/contributing.md 的 Documentation Coverage 完成:

  • 根 README.md / README_ZH.md 的 SLU 指标说明加入可选 Judge;沿用 SLU 任务入口。
  • docs/tasks/slu.md 增加精确 route、输入格式、可选 ref、用户 rubric、百分制、配置方式、成功/失败输出和限制。
  • tasks/slu/README.md 不再把所有 SLU 描述为固定两节点 accuracy pipeline,分别说明 accuracy 与 Judge。
  • 新增 nodes/scoring/llm_judge/README.md,按节点模板补用途、schema、版本计算、运行方式与限制。
  • task manifest 的 pipeline_nodes 与实际 route 一致。
  • 提供可直接执行的 describe → 设置 run_args.llm_config / rubric → run → report 样例,以及通过环境变量提供 API key 的配置示例。

用户需要能看懂如何接入自己的 rubric、调用指定服务和复核结果。仅在 PR body 中标记 documentation pending 还不足以合并。

5. 简化建议:标准库节点可使用 in_process

该节点只用标准库,没有 pip 依赖;当前 runtime: pip 的 dry-run 是 # no pip packages declared,路线却将其列为需要 setup 的节点。

建议评估改为 in_process,避免用户准备空环境。配置、凭据和响应检查留在 scoring 节点内部,不增加顶层 inference/validation 环节。env check: ok 应明确只代表运行环境可用,不能被当成凭据、API 服务或评分质量已验证。

6. CI 问题及建议的测试/CI PR

远端 Core 40674313095 当前为 action_required,0 个 job 已执行。本地结果是:原 head portable 685 passed / 54 skipped,Judge 专项 153 passed,环境元数据 15 passed / 16 deselected;合入最新 main 的本地组合 694 passed / 54 skipped。这些通过结果不覆盖上面已独立复现的断流反例,catalog freshness 也有确定失败。

请同时提交有针对性的测试/CI 修改,并在更新后的精确 head 上跑完整 Core:

  1. 在现有 portable suite 增加 HTTP read 截断/协议异常回归,检查部分成功证据、失败计数、null 总分和退出码。
  2. 覆盖用户 rubric 的读取与实际传入、缺失/空白时不发 API 请求、百分制 0/100 边界、非法数值,以及报告中的 rubric/config 追溯。
  3. 覆盖百分制的成功均值与失败批次 null 聚合,继续保留 accuracy 两种输出模式、默认 route、节点身份和报告兼容回归。
  4. 如果改用 in_process,补对应的环境发现/check/dry-run 回归,确认无需空 pip setup。
  5. 保留并通过现有 catalog/atlas freshness、Python 3.10/3.11/3.12、lint、CLI 和 package checks。

建议把必要的回归测试随本 PR 一起提交;如果发现确实需要改动共享 workflow,请另提一个范围小、用途清楚的 CI PR,并说明现有检查漏掉了什么。现有 Core 已能执行这些测试,通常无需新建 workflow/job,不要增加只检查名称/文件存在的重复用例,也无需公共 CI 使用真实密钥、付费 API 或 GPU。

请补一份可复核的少量真实 API smoke 记录,注明模型、用户 rubric、分数范围、输入和输出;它用于确认真实接入,不应被描述为评分准确率的充分验证。

完成上述作者侧修改、文档和 CI 后,再转为 ready for review。本次反馈只提出审阅意见,没有代为修复本 PR。

@zh820
zh820 marked this pull request as ready for review November 8, 2026 03:50
@zh820

zh820 commented Nov 8, 2026

Copy link
Copy Markdown
Contributor Author

已根据反馈完成本轮修复,并合并最新上游 main。

已补充 HTTP 截断/协议异常、用户 rubric、百分制、失败批次 null 聚合及 in_process 环境相关回归测试,同时更新文档、catalog 和三份 atlas。

本地 Linux Python 3.10/3.11/3.12 各 829 passed、9 skipped;跳过项为旧 harness 材料相关测试和可选 srmrpy 测试。lint、CLI、构建和 wheel 安装验证均通过。真实 API smoke 记录已补在 docs/tasks/slu.md,仅用于确认接入行为。

当前远程 Core 仍在等待维护者批准。麻烦批准运行最新提交的 CI,我会继续跟进检查结果并处理失败项,谢谢。

@Jason040114
Jason040114 merged commit 137fbcc into X-LANCE:main Nov 10, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants