契约与 artifact

连接模型执行与评测的可序列化 request、result 和 artifact 类型。

最后更新: 2026年7月22日

本页内容

ArtifactReflocal_path_for_urienrich_artifact_refGenerationRequestGenerationResultnormalize_generation_statusis_generation_result_successful序列化往返

这些契约是只依赖标准库的 dataclass，可以通过 JSON 跨进程、跨环境传递。正因为存在这个边界，评测才能消费模型输出，而不必 import 生成该输出的模型 runtime。

本页 symbol 均从 worldfoundry.evaluation.api 导入。

`ArtifactRef`

ArtifactRef 指向输出，但不把文件字节塞进记录。kind 表示 artifact 的语义角色，sha256、size_bytes、MIME 与媒体 metadata 则让本地输出可以检查和审计。

artifact = ArtifactRef.from_uri(
    "runs/matrix-game-2/generated.mp4",
    kind="generated_video",
    media_metadata={"fps": 12, "width": 640, "height": 352},
)

class ArtifactRef(uri: str,kind: str,sha256: str | None = None,size_bytes: int | None = None,mime_type: str | None = None,media_metadata: Mapping[str, Any] | None = None,metadata: Mapping[str, Any] | None = None,schema_version: str = ARTIFACT_REF_SCHEMA_VERSION)

clsworldfoundry.evaluation.api.ArtifactReffrom worldfoundry.evaluation.api import ArtifactRef

源码

简介

指向产物的可移植引用（本地路径或 URI），可附带大小、哈希与媒体元数据。用于跨进程传递输出，而不嵌入文件字节。

属性

uristr
kindstr
sha256str | None: 默认值: None
size_bytesint | None: 默认值: None
mime_typestr | None: 默认值: None
media_metadataMapping[str, Any]: 默认值: <dict factory>
metadataMapping[str, Any]: 默认值: <dict factory>
schema_versionstr: 默认值: ARTIFACT_REF_SCHEMA_VERSION

方法

cmeth

from_path(path: str | Path,kind: str,uri: str | None = None,mime_type: str | None = None,media_metadata: Mapping[str, Any] | None = None,metadata: Mapping[str, Any] | None = None) -> 'ArtifactRef'

源码

简介

该类型上的公开 classmethod。

参数

pathstr | Path
kindstr
uristr | None: 默认值: None
mime_typestr | None: 默认值: None
media_metadataMapping[str, Any] | None: 默认值: None
metadataMapping[str, Any] | None: 默认值: None

返回值: 'ArtifactRef'

cmeth

from_bytes(data: bytes,uri: str,kind: str,mime_type: str | None = None,media_metadata: Mapping[str, Any] | None = None,metadata: Mapping[str, Any] | None = None) -> 'ArtifactRef'

源码

简介

该类型上的公开 classmethod。

参数

databytes
uristr
kindstr
mime_typestr | None: 默认值: None
media_metadataMapping[str, Any] | None: 默认值: None
metadataMapping[str, Any] | None: 默认值: None

返回值: 'ArtifactRef'

cmeth

from_uri(uri: str | Path,kind: str,base_dir: str | Path | None = None,mime_type: str | None = None,media_metadata: Mapping[str, Any] | None = None,metadata: Mapping[str, Any] | None = None) -> 'ArtifactRef'

源码

简介

该类型上的公开 classmethod。

参数

uristr | Path
kindstr
base_dirstr | Path | None: 默认值: None
mime_typestr | None: 默认值: None
media_metadataMapping[str, Any] | None: 默认值: None
metadataMapping[str, Any] | None: 默认值: None

返回值: 'ArtifactRef'

cmethfrom_dict(data: Mapping[str, Any]) -> 'ArtifactRef'源码

简介

该类型上的公开 classmethod。

参数

dataMapping[str, Any]

返回值: 'ArtifactRef'

`local_path_for_uri`

把 URI 当作本地文件之前应先使用这个 helper。HTTP、对象存储、Hugging Face 和内存 URI 返回 None；相对本地路径可以通过 base_dir 解析。

def local_path_for_uri(uri: str | Path,base_dir: str | Path | None = None) -> Path | None

funcworldfoundry.evaluation.api.local_path_for_urifrom worldfoundry.evaluation.api import local_path_for_uri

源码

简介

在可能时把 URI 解析为本地路径；远程或非文件协议返回 None，避免把 HTTP/对象存储地址误当成本地文件。

参数

uristr | Path
base_dirstr | Path | None: 默认值: None

返回值: Path | None

`enrich_artifact_ref`

当引用能解析到真实本地文件时，这个函数会补上 hash 和文件大小。远程或缺失 artifact 保持原样，不会被假装成已验证文件。

def enrich_artifact_ref(artifact: ArtifactRef,base_dir: str | Path | None = None) -> ArtifactRef

funcworldfoundry.evaluation.api.enrich_artifact_reffrom worldfoundry.evaluation.api import enrich_artifact_ref

源码

简介

当 URI 对应本地已存在文件时，为 ArtifactRef 补齐大小与 SHA-256；缺失或远程引用保持不变。

参数

artifactArtifactRef
base_dirstr | Path | None: 默认值: None

返回值: ArtifactRef

`GenerationRequest`

一个 request 表示一个 sample，而不是整个 batch。源媒体或文字放入 inputs，动作或相机路径放入 controls，seed、FPS 等原生采样设置放入 generation_kwargs，期望输出形态放入 output_schema。

例如，两个模型可以接收相同的 sample_id 和动作序列，即使各自 operator 最终把这些控制量转换成完全不同的原生参数名。

class GenerationRequest(sample_id: str,task_name: str | None = None,task_id: str | None = None,split: str = 'default',request_id: str | None = None,inputs: Mapping[str, Any] | None = None,controls: Mapping[str, Any] | None = None,generation_kwargs: Mapping[str, Any] | None = None,output_schema: Mapping[str, Any] | None = None,cache_policy: Mapping[str, Any] | None = None,schema_version: str = GENERATION_REQUEST_SCHEMA_VERSION)

clsworldfoundry.evaluation.api.GenerationRequestfrom worldfoundry.evaluation.api import GenerationRequest

源码

简介

单条样本的生成请求：输入、控制量、采样参数与期望输出。应按样本构造，而不是把整批塞进一个 request。

属性

sample_idstr
task_namestr
splitstr: 默认值: 'default'
request_idstr | None: 默认值: None
inputsMapping[str, Any]: 默认值: <dict factory>
controlsMapping[str, Any]: 默认值: <dict factory>
generation_kwargsMapping[str, Any]: 默认值: <dict factory>
output_schemaMapping[str, Any]: 默认值: <dict factory>
cache_policyMapping[str, Any]: 默认值: <dict factory>
schema_versionstr: 默认值: GENERATION_REQUEST_SCHEMA_VERSION

方法

proptask_id -> str源码

简介

该类型上的公开 property。

参数

self

返回值: str

cmethfrom_dict(data: Mapping[str, Any]) -> 'GenerationRequest'源码

简介

该类型上的公开 classmethod。

参数

dataMapping[str, Any]

返回值: 'GenerationRequest'

`GenerationResult`

Result 记录对应 sample 实际发生了什么。成功输出写入 artifacts，执行信息进入 timings 与 metadata；失败则保留 status 和 error，而不是创建占位 artifact 冒充成功。

result = GenerationResult(
    sample_id=request.sample_id,
    model_id="matrix-game-2",
    artifacts={"generated_video": artifact},
    timings={"generation_seconds": 49.75},
)

class GenerationResult(sample_id: str,request_id: str | None = None,model_id: str = '',artifacts: Mapping[str, ArtifactRef] = <dict factory>,status: str = 'succeeded',error: str | None = None,timings: Mapping[str, Any] = <dict factory>,metadata: Mapping[str, Any] = <dict factory>,schema_version: str = GENERATION_RESULT_SCHEMA_VERSION)

clsworldfoundry.evaluation.api.GenerationResultfrom worldfoundry.evaluation.api import GenerationResult

源码

简介

单条样本的规范化生成结果：成功时放 artifacts，失败时保留 status/error。Benchmark 与 metric 消费该结构，而不是模型 runtime。

属性

sample_idstr
request_idstr | None: 默认值: None
model_idstr: 默认值: ''
artifactsMapping[str, ArtifactRef]: 默认值: <dict factory>
statusstr: 默认值: 'succeeded'
errorstr | None: 默认值: None
timingsMapping[str, Any]: 默认值: <dict factory>
metadataMapping[str, Any]: 默认值: <dict factory>
schema_versionstr: 默认值: GENERATION_RESULT_SCHEMA_VERSION

方法

cmethfrom_dict(data: Mapping[str, Any]) -> 'GenerationResult'源码

简介

该类型上的公开 classmethod。

参数

dataMapping[str, Any]

返回值: 'GenerationResult'

`normalize_generation_status`

不同 runner 可能返回 success、completed 或 done 等近义状态。这个 helper 先归一化文字，再交给成功判定；它不会检查引用文件是否真实存在。

def normalize_generation_status(status: Any) -> str

funcworldfoundry.evaluation.api.normalize_generation_statusfrom worldfoundry.evaluation.api import normalize_generation_status

源码

简介

把相近的状态词（success/completed/done 等）归一成规范 status，供成功判定使用；不检查产物文件是否存在。

参数

statusAny: Raw status value from a generation runner or result row.

返回值: str

`is_generation_result_successful`

当归一化状态属于成功集合且 error 为空时，result 被视为执行成功。Artifact 是否存在、benchmark 是否完整、结果是否具备 leaderboard 资格仍是独立检查。

def is_generation_result_successful(result: 'GenerationResult') -> bool

funcworldfoundry.evaluation.api.is_generation_result_successfulfrom worldfoundry.evaluation.api import is_generation_result_successful

源码

简介

当归一化 status 属于成功集合且 error 为空时返回 True。产物是否存在、是否可上榜需另行校验。

参数

result'GenerationResult': Generation result emitted by an runner or loaded from disk.

返回值: bool

序列化往返

三个契约类都继承共享 JSON contract 方法。Ledger 行可以用 to_json() 写出，再用 from_json() 或 from_dict() 恢复。

payload = result.to_json()
restored = GenerationResult.from_json(payload)

assert restored.sample_id == result.sample_id
assert restored.artifacts["generated_video"].kind == "generated_video"

序列化成功只证明记录形态有效，并不证明模型确实运行、视频视觉正确或结果具备 leaderboard 资格。更强的声明需要 runtime validation 与 scorecard 证据。