WorldFoundry
English中文

核心基础设施

worldfoundry/core 共享层 —— 加载、attention、分布式、VRAM、kernel、memory，以及“可复用原语只在此处”的规则。

编辑此页GitHubMarkdown

本页内容
本层为何存在子包职责依赖规则被谁消费不属于此处的内容归属与合并原则回归检查

本层为何存在

worldfoundry/core 是每个 model family 都复用、但都不拥有的共享推理基础设施。checkpoint 加载、state-dict remap、attention 后端、分布式 collectives、VRAM 放置与 offload、kernel、配置、媒体 IO、memory 契约、安全 guardrails 都只在此实现一次。family 包（worldfoundry/base_models/*、worldfoundry/synthesis/*、worldfoundry/pipelines/*）组合这些原语，但不得重新实现它们。

当你打算把某个工具复制进某个模型目录时，本层就是你要先读的。规则很明确：多个 family 已实际复用的原语放进 core；绑定特定模型的适配器放回对应模型。扩散如何消费本层见 原生扩散，pipeline/operator 如何消费见 模型运行时。

子包职责

子包

  • attention

    后端、旋转位置编码、序列布局、KV 缓存、稀疏及并行 attention。

    阅读入口 backends/, rotary/, sequence/, cache/, sparse/, parallel/

  • distributed

    进程启动、通信算子、模型并行组、序列并行运行时和参数分片。

    阅读入口 runtime/, collectives/, model_parallel/, sequence_parallel/, sharding/

  • model_loading

    模型构建、加载策略及权重转换；checkpoints 统一管理安全加载和 state-dict 赋值。

    阅读入口 checkpoints/, factory.py, inference_model.py, lora.py

  • io

    资源获取、文件系统、结构化格式及推理输入数据。

    阅读入口 assets/, filesystem/, formats/, inputs/, paths.py, manifests.py

  • media

    图片、音频、视频编解码，帧处理、输出类型及结果预览。

    阅读入口 codecs/, processing/, types.py, resolutions.py, artifacts.py

  • execution

    设备与进程生命周期、推理策略、运行时缓存、CUDA Graph 回放及实时执行编排。

    阅读入口 graphs/, realtime/, inference.py, inference_runtime.py, process.py

  • configuration

    结构化及 Python 配置、Hydra 适配、参数覆盖、延迟构建和校验。

    阅读入口 lazy_config/, hydra.py, hydra_utils.py, overrides.py, python.py, validators.py

  • nn

    共享神经网络模块、transformer 算子、扩散原语、latent 编解码及激活 checkpoint。

    阅读入口 blocks/, transformer/, diffusion/, latent/, checkpointing/

  • acceleration

    通用缓存、token 裁剪和可选低精度线性算子。

    阅读入口 quantization/, cache.py, token_pruning.py, technology.py

  • kernels

    扩散、MoE、量化 GEMM 等底层算子及分派，含可选 Triton 实现。

    阅读入口 capabilities.py, registry.py, diffusion.py, moe.py, quantized_gemm.py

  • vram

    物理参数放置、meta 初始化、磁盘权重、CPU offload 和 encoder 生命周期。

    阅读入口 device_map.py, initialization.py, disk_map.py, layerwise_offload.py, encoder_lifecycle.py

  • memory

    语义及上下文记忆契约、检索、条件构建和持久化。

    阅读入口 base.py, conditioning.py, media.py, mosaic.py, retrieval.py, store.py

  • geometry

    相机变换、姿态条件、轨迹及 RGBD 重投影。

    阅读入口 transforms.py, pose.py, trajectory.py, conditioning.py, warp.py

  • observability

    日志、终端格式、计时、性能分析及可选 NVTX 标记。

    阅读入口 logging_setup.py, formatting.py, colors.py, time.py, torchprofile.py

  • safety

    安全过滤和视频输入约束。

    阅读入口 guardrails.py, video_io.py

  • utils

    通用 Python 对象及树结构工具、tensor 和数组工具。

    阅读入口 python/, tensors/

依赖规则

core 可依赖 PyTorch、diffusers 的 model/operator 原语与窄范围第三方库。它不得 import worldfoundry.pipelines、worldfoundry.synthesis、worldfoundry.operators、worldfoundry.base_models 的 family 包，或 worldfoundry.evaluation 或 worldfoundry.studio。依赖边是从 family 包指向 core，绝不反向。

这让 family 包保持精简：一个模型目录只含 checkpoint 兼容的张量算子与契约适配器，而不是第二份 offload manager、分布式 bootstrap、kernel registry 或量化系统。当你发现自己要在 family 包里加这些东西时，先把它移到 core 再 import。

扩散包在其自身边界上重申此规则，见 原生扩散。通用 attention、transformer、加载、offload 原语在 core；扩散域契约、scheduler、recipe 在 base_models/diffusion_model。

被谁消费

  • 扩散 —— base_models/diffusion_model 经 core/model_loading 加载 checkpoint，经 core/attention 跑 attention，经 core/vram 做 offload。其 optimizations/ 只是 core policy 的再导出，不是并行实现。
  • Hosted 与 native runtime —— synthesis/ 经 core/io 准备输入，经 core/media 写出结果。
  • Memory —— core/memory/base.py 定义契约；synthesis/*/memory 的流式/长上下文状态与 synthesis/action_generation/memory.py 的动作策略 trace 状态实现它。
  • 分布式执行 —— core/distributed 是模型并行组初始化的唯一位置；任何 family 包都不得自启 NCCL group。

不属于此处的内容

训练入口、数据集、dataloader、loss、callback、仅增强模块、实验脚本都不属于 core，也不属于 base_models。core 是推理基础设施；若某模块只在训练时有用，不要加到这里。

全包目录级地图见 代码地图。模型调用如何流经这些原语见 模型运行时 与 Runtime 组装。

归属与合并原则

  • checkpoint 合并进 model_loading/checkpoints，统一管理权重加载、赋值和转换。
  • 媒体编解码与原 video 处理统一归到 media；下载和文件系统操作留在 io。
  • CUDA Graph、预热、帧预取和执行重叠归到 execution；encoder 的参数放置和生命周期归到 vram。
  • memory 与 vram 分开：前者管理上下文记忆及检索，后者管理物理显存、参数放置和 offload。
  • 配置工具从 io 移到 configuration，终端格式从 io 移到 observability，运行时调度从 utils 移到 execution。
  • Wan 的序列并行适配器和 VGGT 的观测预处理归到对应模型；仓库代码盘点归到 scripts/model_zoo。

公开的延迟加载函数及类入口保持稳定。内部模块使用实际所属的新路径，已删除目录不留下兼容转发壳。

回归检查

tests/core/test_core_module_boundaries.py 无需可选模型依赖即可检查延迟加载目标及 core 引用，并阻止 core 反向依赖模型或应用包。实际导出解析在模型环境中测试。

涉及实际模型的变更还需通过 make test-geometry：固定输入、权重、环境和随机种子，与接受过的基准输出比较数值，并检查回放记录的源码哈希仍对应当前代码。目录迁移必须同时保持计算行为和引用有效。