架构

WorldFoundry 把 模型执行 和 benchmark 评分 拆开，再用进程退出后仍能打开的文件把两边接住。

模型写出归一化 artifact。Benchmark 只评这些文件，不碰 checkpoint。Runner 记录实际发生了什么。所以视频模型和视觉-语言-动作（VLA）策略可以共用同一套 GenerationResult 行和 scorecard.json，哪怕推理完全不在同一个 runtime。也因此你可以先生成、先目检，再另开一次评分，而不必重新加载模型。

调用图

一次运行如何穿过各层

入口

使用界面CLI / TUI / MCP / Studio

intent dataclass

控制平面

编排prepare_evaluation / execute_preparedorchestration/service.py

execute_prepared_evaluation()

执行

模型运行时Pipeline · Operator · Synthesis

Benchmark 运行时Metrics · official runners

同一请求可以只生成、只评分已有文件，或两者都做

GenerationResult · metrics/summary.json

证据

报告scorecard.json + report.md

图上是一次运行：界面把意图收成请求，执行侧生成或评分（或两者都做），reporting 写下证据。Catalog、原生 diffusion 内核和 Studio 在这条脊线旁边：它们有自己的归属规则，但不是图上多出来的方块。

第一次 快速开始 跑通之后再读这页，用来建立命令背后的心智模型。设计 是更粗的四层地图；改动涉及「归谁」时，以下面这份清单为准。

一次 evaluate 跑完，输出目录本身就是契约。你应能打开 requests.jsonl 和 results.jsonl（每条样本一行）、metrics/summary.json、scorecard.json（资格记录；report.md 由它派生）以及 run_manifest.json（身份和状态）。缺文件时，工作流 标明该由哪一阶段写出。

谁负责什么

层与层只通过可序列化契约说话：GenerationRequest、GenerationResult、BenchmarkSpec 和 scorecard 字段。不要共享全局状态，也不要把机器本地路径当成接口。若改动属于模型运行时，就不要把打分逻辑塞进 runner；若属于 reporting，就不要假设某种 checkpoint 布局。

• 使用界面与编排 — 命令、运行模式、resume、输出位置。不管模型内部怎么推理。
• 模型运行时 — pipeline、operator、本地 runtime、托管 API，以及归一化生成结果。不管 benchmark 怎么打分。
• 原生 Diffusion — worldfoundry/base_models/diffusion_model 里的采样循环和本地 diffusion 契约。不依赖上游 pipeline 框架，也不反向依赖编排和评测。
• Benchmark 运行时 — manifest、数据集、evaluator、指标和结果归一化。不负责加载模型或摆 checkpoint。
• Catalog 与就绪 — 元数据、来源、资产、环境、blocker 和支持状态。不写代码里跑不起来的 runtime 行为。
• Reporting — manifest、摘要、report.md、scorecard.json 和榜单资格。不把缺失资产或跳过的步骤藏起来。
• Studio — 同一套 catalog 与 runtime 契约上的交互预览。不把只能在 UI 里工作的核心逻辑藏进界面。

拍板时用的原则

日常 review 里常见的分岔都在这里：为什么 catalog 可以先写意图、代码后落地；为什么 official validation 不等于一次正式 benchmark；为什么只做 artifact 检查也要写 manifest。

• 统一的公开 runner 契约 — 每条模型路径最终都落到同一种结果形态，benchmark 不必关心文件是哪个 runtime 写的。
• Operator 加 pipeline — 可运行方法两边都要有，输入才明确、才可复现。
• 证据先于声明 — Catalog 可以描述意图；支持状态必须对得上真正能跑的东西。
• 外部代码先当出处 — 官方仓库和 checkpoint 要记录。本机 checkout 路径不是 runtime 依赖。
• 只有一份原生 diffusion 内核 — 上游树是实现参考，不是 backend。可复用的采样算法在仓库里只留一份。
• Official validation 不是 benchmark 对齐 — 导入官方文件只证明结果链路通。Benchmark-ready 还要有真实数据、指标和 scorecard。

接下来读哪页

多数事情会跨两页。加模型要看 模型运行时 和 评测核心。加 benchmark 要看 基准和数据 和 工作流。

跟着一次运行走

改模型或 benchmark

查路径

如果是带着具体任务进来的：

• 跑一次评测 — 快速开始，再看 评测 和 CLI 参考。
• 选模型 — 支持的模型，然后 worldfoundry-eval zoo model-show 和 preflight runtime --profile <benchmark-id>。
• 加模型 — 添加模型，再看 模型运行时。
• 加 benchmark — 添加基准，再看 基准和数据。
• 读一次运行留下的文件 — 评测核心，再打开真实输出目录里的 report.md、scorecard.json 和 metrics summary。
• 看支持状态 — 支持的模型，然后 zoo model-show / zoo benchmark-show。