企业官网建设流程全解析

A2UI 评估框架实战：基于 Inspect AI 的模型生成能力评测、数据集加密与结果分析

【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui

A2UI 的评估框架（位于eval/目录）用于验证一个模型或对话历史能否稳定产出符合 A2UI 协议 Schema 与语义规则的 UI 载荷。它构建在 Inspect AI 之上，由数据集（Dataset）、求解器（Solver）、评分器（Scorer）三部分组成，并通过 Transcrypt 对评测数据做静态加密以防基准被模型训练数据"污染"。读完本文，你将掌握完整的评测执行流程（含云端与 Ollama 本地 Gemma 评测）、main.py各命令行参数的真实含义、多阶段评分的源码实现，以及数据集贡献与结果分析的标准操作。

一、框架定位与设计骨架

eval/目录是 A2UI 项目中专门存放"评测测试（evals）"的位置：一个评测用例验证"某提示词或对话历史能否产出预期的 UI 结果"。完整的架构设计见 eval/DESIGN.md，其核心思想是功能解耦——评测逻辑与被测模型、传输协议互不绑定，从而保持 A2UI"框架无关、可移植到 Flutter / React / 原生 Web 渲染"的立场。

从 eval/tasks.py 与 eval/a2ui_eval/scorers.py 的源码结构看，设计文档中描述的三大支柱落地为：

任务层暴露了两个协议版本的 Task 工厂：tasks.py 中的a2ui_v0_9_1_eval（默认目录specification/v0_9_1/catalogs/basic/catalog.json）与a2ui_v1_0_eval（默认目录specification/v1_0/catalogs/basic/catalog.json）。在 eval/main.py 中可以看到分发规则：策略为express、elemental、atom、direct时走 v1.0 任务，其余（如subagent_tool）走 v0.9.1 任务。

框架还直接复用 A2UI Python SDK（依赖声明见 eval/pyproject.toml 中的a2ui-agent-sdk）：parse_response负责从 markdown 中抽取 JSON 载荷，目录校验器validator负责 Schema 合规检查，避免评测脚本手写一遍解析与校验逻辑。

二、评测数据集：为什么必须加密、为什么要求完整多轮上下文

2.1 静态加密（Transcrypt）

开源仓库中的评测数据随时可能被模型训练爬虫索引，一旦提示词与"金标准"答案被记忆化，后续模型分数虚高——这就是数据污染。A2UI 的对策是用Transcrypt对eval/datasets/*.yaml做透明加密：

• 首次设置时，在eval/目录下初始化：

  bin/transcrypt -p <PASSWORD>

  之后 Git 会在git add时透明加密、在 checkout 时透明解密（通过.gitattributes中的 clean/smudge filter）。

• 为什么选 Transcrypt 而非 git-crypt：从设计文档看，它用密码字符串而非二进制密钥文件解锁，对 CI/CD 中以环境变量注入密钥更友好；且它是独立脚本，贡献者无需安装系统级依赖。

• 若拉取到的更新改变了加密配置（例如从 MD5 迁移到 PBKDF2），可能遇到解密错误或 OpenSSL 弃用警告。升级步骤：

  bin/transcrypt --upgrade git checkout HEAD -- $(git ls-crypt)

  第一条命令更新.git目录下的本地 filter 脚本（保留已保存密码），第二条命令让文件重新经过升级后的 smudge filter 完成解密。

2.2 数据点格式

每个数据点是eval/datasets/<dataset_name>.yaml列表中的一项，必须符合 eval/datasets/dataset_schema.json。字段定义（来自 eval/CONTRIBUTING_USE_CASES.md）：

• name（必填，字符串）：样本唯一标识，小写下划线风格；
• description（必填，字符串）：场景测试目的的简要说明；
• catalog（必填，字符串）：组件目录相对路径，标准组件用'specification/{version}/catalogs/basic/catalog.json'；
• messages（必填，数组）：按时间顺序排列的对话轮次，包含user、带tool_calls的assistant、带tool_call_id的tool以及system；
• system_prompt（可选）：领域系统指令；
• target（可选）：给 LLM-as-a-judge 的评分量规；省略时默认回退到description；
• dataset（可选）：逻辑数据集名，省略时默认取文件名。

关键约束：target必须是定性量规，而不是硬编码 JSON 字符串——否则评测会被绑定到某一种推理格式（JSON vs XML vs DSL），失去跨格式可比性。

2.3 未加密的参考样例

由于eval/datasets/*.yaml在 Git 中是密文，浏览仓库时看不到明文。仓库提供了一个未加密的多轮参考样例 eval/examples/example_eval_case.json，演示了一个"订机票"场景：领域 system prompt、两次工具调用（其中一次是无关的天气查询，用于检验模型抗干扰能力）、工具返回载荷、最终 UI 生成请求，以及定性评分量规。该文件会由 CI 测试自动校验其符合数据集 Schema。

贡献流程与脱敏规范（生产日志 → 结构规格 → 合成数据 → 人工审计）详见 eval/CONTRIBUTING_USE_CASES.md。

三、运行评测：前置条件与 main.py 全部参数

确保工作目录为eval/。

3.1 前置条件

1. 设置 Gemini API key（评分器使用 LLM-as-a-judge，必须有）：

   export GEMINI_API_KEY="your_api_key"

2. 首次需按上文初始化 Transcrypt 解密数据集。

3.2 执行评测

运行全部数据集：

uv run main.py

指定单个或多个数据集：

# 运行单个数据集 uv run main.py --dataset multi_turn_conversation_dataset # 运行多个数据集 uv run main.py --datasets core_v0_9_1,multi_turn_conversation_dataset

跨推理格式对比（directJSON、expressXML 标签、elementalDSL 等）：

uv run main.py --dataset multi_turn_conversation_dataset --strategies direct,express,elemental

2 样本快速自检（固定使用gemini-3.1-flash-lite）：

uv run main.py --sanity

3.3 参数详解（源码级）

以下参数均定义在 eval/main.py 中，补充默认值与行为细节：

模型名解析规则在resolve_model_name（main.py#L45-L60）：内置别名表把gemma-4-26b→google/gemma-4-26b-a4b-it、gemini-3.8-flash→google/gemini-3.8-flash、gemma4:e2b→ollama/gemma4:e2b等；含:的名字按 Ollama 标签约定自动补ollama/前缀，以gemma-/gemini-开头的补google/前缀。

另外，main.py启动时设置了INSPECT_MAX_CONNECTIONS=10与INSPECT_MODEL_MAX_BACKOFF=300（main.py#L22-L24），用于压低连接限流、避免 503 错误。

3.4 多阶段评分是怎么打的

Task 中挂载了两个评分器（tasks.py#L104-L113）：

1. a2ui_scorer（程序化结构/Schema 校验）：实现于 eval/a2ui_eval/scorers.py。它从样本元数据取出catalog路径，构造目录配置并取validator；先用 SDK 的parse_response从模型输出中抽取 A2UI JSON，若无载荷记 0 分（"No A2UI JSON found in response"），校验通过记 1 分。注意它会提前识别 "Compilation/validation failed:" 前缀——这是策略层编译失败时的显式信号。
2. measured_model_graded_qa（LLM-as-a-judge）：包装 Inspect 的model_graded_qa，附加 token 用量与耗时统计写入state.metadata（evaluation_duration_seconds、evaluation_input_tokens等，见 scorers.py#L107-L143）。评审模型按 tasks.py 中的GRADER_INSTRUCTIONS给出 C（正确）/ P（部分）/ I（错误）等级，量规明确"组件顺序、组件 ID 命名、标签措辞的合理变体不扣分；缺组件或实质错误判 I"。

求解器侧，eval/a2ui_eval/strategies/format.py 的format_system_prompt会按所选策略实例化InferenceFormat（DirectJsonFormat/ExpressFormat/ElementalFormat/AtomFormat），调用其prompt_generator.generate(..., include_schema=True)生成协议提示词，再与样本自带的领域system_prompt拼成 "Domain Instructions + UI Protocol Instructions" 注入到消息序列头部。这解释了为什么不同推理格式可以用同一份数据集横向对比：数据与格式提示解耦。

四、评测 Gemma 模型（Express 格式）

Gemma 可以通过**云端（Google AI Studio / Gemini API，无需本地 GPU）或本地 Ollama（需 GPU）**两种方式评测。注意：Gemma 评测不在默认或 CI 流程中运行，CI 评测继续使用google/gemini-3.8-flash。

无论云端还是 Ollama，评分始终使用 Gemini Flash 作为 LLM-as-a-judge，因此都必须设置GEMINI_API_KEY。

4.1 云端执行

• 移动/端侧档位（--model gemma或--model gemma-4-26b）：对应google/gemma-4-26b-a4b-it，26B 总参数、4B 激活参数的 MoE 模型，代表可运行在现代移动硬件上的轻量模型档位。
• 大/工作站档位（--model gemma-large或--model gemma-4-31b）：对应google/gemma-4-31b-it，31B 稠密模型，推理能力更强。

# 移动档位 + Express 格式 uv run main.py --model gemma --strategies express # 大档位（31B）+ Express 格式 uv run main.py --model gemma-large --strategies express # 指定数据集或限制样本数做快速检查 uv run main.py --model gemma --strategies express --dataset core_v1_0 --limit 3

4.2 本地 / 边缘执行（Ollama，GPU 加速）

面向可完全离线运行在标准或旗舰智能手机上的边缘优化模型（需 6–8 GB 内存）：

• Gemma 4 E2B（--model gemma-e2b或--model gemma4:e2b）：ollama/gemma4:e2b，面向标准智能手机（约 6 GB RAM）；
• Gemma 4 E4B（--model gemma-e4b或--model gemma4:e4b）：ollama/gemma4:e4b，面向近期旗舰智能手机（约 8 GB RAM）；
• Gemma 2 2B（--model gemma-2b或--model gemma2:2b）：ollama/gemma2:2b，轻量 2B 开源模型。

前置步骤：

# 1. 安装 Ollama 并启动守护进程 ollama serve # 2. 拉取目标模型 ollama pull gemma4:e2b ollama pull gemma4:e4b # 3. 对本地 Ollama 实例运行评测 uv run main.py --model gemma-e2b --strategies express --dataset core_v1_0 --limit 3

LLM-as-a-Judge 铁律：Gemma 模型绝不可用作评审模型（--grading-model）。评审模型必须保持为 Gemini Flash 系列（如google/gemini-3.8-flash或google/gemini-3.1-flash-lite）以保证评分一致、无偏；Ollama 评测前务必确认已设置GEMINI_API_KEY。这条规则在源码中是硬校验，不只是文档约束。

五、查看结果、单元测试与 Schema 校验

5.1 Inspect 日志查看器

uv run inspect view start

启动本地 Web 服务（通常http://localhost:7575），可交互式浏览每条样本的完整 trace 与评审模型给出的判分理由。

从评测日志文件打印控制台摘要或 markdown 表格：

uv run python bin/report_evals.py logs/<log_filename>.eval

5.2 单元测试与数据集校验

uv run python -m pytest

这会运行 eval/tests/ 下的测试（test_dataset.py负责把所有数据集文件对照dataset_schema.json做 JSON Schema 校验，test_main.py、test_scorers.py、test_strategies.py、test_run_ci_evals.py分别覆盖 CLI 行为、评分器标定、策略实现与 CI 评测脚本）。贡献新数据点前的最小验证闭环是：

cd eval uv run python -m pytest tests/test_dataset.py # Schema 合规 export GEMINI_API_KEY="your_api_key" uv run main.py --dataset <dataset_name> --sanity # 小规模实跑 uv run inspect view start # 查看 trace 与判分

六、迭代式格式优化与基线

eval/还包含一套针对 A2UI 推理格式（Atom、Express、Elemental、Direct JSON）的基准对比与迭代优化资产：

• eval/iterative_format_optimizer/baselines/{atom,direct_json,elemental,express}/：各格式在不同 token 预算（budget_0、budget_897、budget_1795、unbounded）下的run_meta.json基线结果；
• eval/iterative_format_optimizer/history/：逐轮优化的历史记录（每轮含 diff、说明与结果元数据），例如history/atom/下从run_001到run_052的编译器/提示词优化轨迹，以及history_summary.md汇总；
• 优化流程指南见 eval/iterative_format_optimizer/skills/inference-format-optimizer/SKILL.md。

从目录结构看，这套机制的用途是：以"token 预算 vs 得分"曲线为坐标，反复对某推理格式的提示词、编译器模板做增量改进并留痕，使express/atom等实验格式能在可控长度下逼近direct_json的得分。

七、小结

eval/目录把"模型能否可靠生成 A2UI UI"这一问题工程化为一条可复现流水线：加密的多轮数据集提供真实、含噪声的评测上下文；main.py以 Inspect AI 的eval_set驱动多策略并发评测；a2ui_scorer与measured_model_graded_qa分别守住"协议合法性"与"意图达成"两道关；Inspect View 与report_evals.py负责结果复盘。上手路径可概括为四步：解锁 Transcrypt →export GEMINI_API_KEY→uv run main.py --sanity自检 →uv run inspect view start查看 trace；贡献数据则走 CONTRIBUTING_USE_CASES.md 的脱敏与 Schema 校验流程。

【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui