WorldFoundry
English中文

契约与 artifact

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

编辑此页GitHubMarkdown

本页内容
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},
)
类

ArtifactRef

源码
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)
worldfoundry.evaluation.apifrom 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

方法

cmethfrom_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,compute_hash: bool = True) -> 'ArtifactRef'源码

简介

from_path — Build a reference to a local file, hashing it unless `compute_hash=False`.

源码 docstring

Build a reference to a local file, hashing it unless `compute_hash=False`.

Set `compute_hash=False to skip the full-file SHA-256 read for large artifacts (e.g. multi-GB videos); the cheap size_bytes` stat is always recorded.

参数

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

返回值

'ArtifactRef'
cmethfrom_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'
cmethfrom_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,compute_hash: bool = True) -> '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
compute_hashbool默认值 True

返回值

'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 解析。

函数

local_path_for_uri

源码
def local_path_for_uri(uri: str | Path,base_dir: str | Path | None = None) -> Path | None
worldfoundry.evaluation.apifrom 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 保持原样，不会被假装成已验证文件。

函数

enrich_artifact_ref

源码
def enrich_artifact_ref(artifact: ArtifactRef,base_dir: str | Path | None = None,compute_hash: bool = True) -> ArtifactRef
worldfoundry.evaluation.apifrom worldfoundry.evaluation.api import enrich_artifact_ref

简介

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

源码 docstring

Return an ArtifactRef with file hash/size when its URI points to a local file.

Set `compute_hash=False to only fill the cheap size_bytes` stat and skip the full-file SHA-256 read (useful for very large artifacts).

参数

artifactArtifactRef
base_dirstr | Path | None默认值 None
compute_hashbool默认值 True

返回值

ArtifactRef

GenerationRequest

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

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

类

GenerationRequest

源码
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)
worldfoundry.evaluation.apifrom 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},
)
类

GenerationResult

源码
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)
worldfoundry.evaluation.apifrom 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 先归一化文字，再交给成功判定；它不会检查引用文件是否真实存在。

函数

normalize_generation_status

源码
def normalize_generation_status(status: Any) -> str
worldfoundry.evaluation.apifrom worldfoundry.evaluation.api import normalize_generation_status

简介

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

源码 docstring

Return the canonical lowercase generation status text.

Missing/blank statuses normalize to `"unknown"` (fail-closed): an incomplete result row written by an external runner must not be treated as a scoreable success. Callers that own an in-process success signal (e.g. a pipeline returning normally) should set the status explicitly.

参数

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

返回值

str

is_generation_result_successful

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

函数

is_generation_result_successful

源码
def is_generation_result_successful(result: 'GenerationResult') -> bool
worldfoundry.evaluation.apifrom 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 证据。