---
title: 架构
description: 一次运行如何从命令走到产物、分数和证据，以及每一步由哪一层负责。
---

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

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

<ArchDiagram id="system" locale="zh" />

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

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

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

## 谁负责什么

层与层只通过可序列化契约说话：`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。

## 接下来读哪页

多数事情会跨两页。加模型要看 [模型运行时](/zh/docs/maintainers/architecture/model-runtime) 和 [评测核心](/zh/docs/maintainers/architecture/evaluation-core)。加 benchmark 要看 [基准和数据](/zh/docs/maintainers/architecture/benchmarks-data) 和 [工作流](/zh/docs/maintainers/architecture/workflow)。

**跟着一次运行走**

<Cards>
  <Card title="工作流" description="从 CLI 到产物、指标、scorecard 和报告的一条评测。" href="/zh/docs/maintainers/architecture/workflow" />
  <Card title="使用界面与编排" description="CLI、TUI、MCP 如何把意图收成 runner 能执行的请求。" href="/zh/docs/maintainers/architecture/surfaces-orchestration" />
  <Card title="评测核心" description="分发、三条运行路径、指标和 scorecard。" href="/zh/docs/maintainers/architecture/evaluation-core" />
</Cards>

**改模型或 benchmark**

<Cards>
  <Card title="模型运行时" description="pipeline、operator 与 artifact 契约。OpenVLA 是完整例子。" href="/zh/docs/maintainers/architecture/model-runtime" />
  <Card title="Runtime 组装" description="pipeline、operator、synthesis、representation、memory 的基类职责。" href="/zh/docs/maintainers/architecture/runtime-assembly" />
  <Card title="原生 Diffusion" description="框架自有的采样内核，以及研究扩展往哪里接。" href="/zh/docs/maintainers/architecture/native-diffusion" />
  <Card title="核心基础设施" description="worldfoundry/core 里共享的加载、attention、分布式、VRAM、kernel 和 memory。" href="/zh/docs/maintainers/architecture/core-infrastructure" />
  <Card title="基准和数据" description="manifest、数据集、官方 evaluator 和就绪检查。" href="/zh/docs/maintainers/architecture/benchmarks-data" />
  <Card title="Studio 内部" description="预览壳，执行契约与 CLI 相同。" href="/zh/docs/maintainers/architecture/studio-internals" />
</Cards>

**查路径**

<Cards>
  <Card title="代码地图" description="目录对应职责，以及每个包该先打开的文件。" href="/zh/docs/maintainers/architecture/file-index" />
</Cards>

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

- **跑一次评测** — [快速开始](/zh/docs/quickstart)，再看 [评测](/zh/docs/evaluation) 和 [CLI 参考](/zh/docs/reference/cli)。
- **选模型** — [支持的模型](/zh/docs/guides/supported-models)，然后 `worldfoundry-eval zoo model-show` 和 `preflight runtime --profile <benchmark-id>`。
- **加模型** — [添加模型](/zh/docs/guides/add-model)，再看 [模型运行时](/zh/docs/maintainers/architecture/model-runtime)。
- **加 benchmark** — [添加基准](/zh/docs/guides/add-benchmark)，再看 [基准和数据](/zh/docs/maintainers/architecture/benchmarks-data)。
- **读一次运行留下的文件** — [评测核心](/zh/docs/maintainers/architecture/evaluation-core)，再打开真实输出目录里的 `report.md`、`scorecard.json` 和 metrics summary。
- **看支持状态** — [支持的模型](/zh/docs/guides/supported-models)，然后 `zoo model-show` / `zoo benchmark-show`。