A Anaxagore
← 所有项目

Contribution Tasks

hao-ai-lab/FastVideo

高度契合。虽然你目前没有 NVIDIA GPU，但 FastVideo 正在大力扩展 Apple Silicon (MLX/MPS) 支持，且其复杂的分布式调度和内存管理逻辑完全可以在纯 CPU 环境下开发与单测。你的端侧部署经验和系统架构能力可以在 mlx_runtime 和纯逻辑层发挥巨大作用。

当前方向：项目正处于高速迭代期，重点向 0.2.x 版本演进，近期密集增加了对 Apple Silicon (FastMetal-QAD)、DGX Spark 和 ROCm 的支持，同时在优化端侧显存占用和多模态输入的处理。

★ 4486Fork 4705 个候选任务Gemini：gemini-3.1-pro-preview

更新于 2026-10-08T07:37:23+00:00 · 本次生成失败，展示上次结果 · 打开仓库 ↗

一、项目定位

FastVideo 是一个面向视频生成大模型（如 Wan2.1/2.2, MiniMax-H3 等 DiT 架构）的端到端统一推理与后训练（Post-training）加速框架。它的核心价值在于打破了“训练”与“推理”的壁垒，通过算法层（DMD2 蒸馏、Video Sparse Attention 稀疏注意力、Self-Forcing 因果蒸馏）与系统层（定制 CUDA/Triton 算子、序列并行、Attn-QAT 量化）的深度协同，实现了极速甚至实时的视频生成（如其内置的 Dreamverse 实时流应用）。目前项目处于高速迭代与多硬件平台扩展期（正向 0.2.x 版本演进，近期密集提交了对 Apple Silicon、DGX Spark 和 ROCm 的支持）。 针对你的硬约束（仅有一台 16GB Apple Silicon MacBook Air，无本地 NVIDIA GPU）：虽然你擅长 CUDA/Triton 和高端 GPU 性能优化，但由于缺乏本地验证环境，直接开发前沿 CUDA 算子（如仓库中已出现的 sm100a 或 FP8 算子）会非常痛苦，Colab 免费 T4（仅支持 sm75）无法验证这些新特性。你的最佳切入路径有两条：第一，发挥你的端侧部署与量化经验，深耕 fastvideo/mlx_runtime 目录，为 FastMetal-QAD 模型编写或优化基于 Apple Metal 的底层算子，这完全可以在你的 Mac 上本地闭环；第二，发挥你的分布式训练性能经验，在纯 CPU 环境下开发和单测 fastvideo/distributed 中的 Sequence Parallelism（序列并行）切分逻辑或 FSDP2 调度策略，仅在最终提交前用 Colab T4 做几十分钟的集成冒烟测试。

解决什么问题、给谁用

开源视频生成大模型（DiT）面临计算量巨大、显存占用极高、推理极慢的痛点，难以在消费级硬件或端侧实时运行；同时，社区缺乏一个将数据预处理、微调、稀疏化蒸馏（DMD2）、量化感知训练（QAT）与高性能推理后端无缝打通的开箱即用框架。FastVideo 旨在为 AI 研究员和应用开发者提供一站式解决方案，典型场景包括：1) 对开源 DiT 模型进行稀疏蒸馏以获得 50x 加速；2) 在多卡环境部署长视频的序列并行推理服务；3) 在 Apple Silicon Mac 上本地运行 FastMetal-QAD 模型；4) 部署 Dreamverse 实现“Vibe Directing”实时互动视频生成。

视频生成模型算法研究员（需快速验证蒸馏/稀疏化算法）、AI 视频应用开发者（需接入高性能 API 或部署实时视频流）、以及希望在本地（如 Mac 或单张 4090）运行视频生成的端侧极客。

同类项目与差别

核心能力

能力在哪成熟度
Apple Silicon MLX Runtimefastvideo/mlx_runtime成熟
Custom CUDA Kernelsfastvideo-kernel/csrc成熟
Video Sparse Attention (VSA)fastvideo/attention/vsa成熟
Sequence Parallelism (Distributed Inference)fastvideo/distributed成熟
DMD2 / Sparse Distillationexamples/distill成熟
Realtime Video Generation (Dreamverse)apps/dreamverse成熟
Attn-QAT Trainingfastvideo/training成熟
Causal Distillation (Self-Forcing)examples/inference/basic/basic_self_forcing_causal_wan2_2_i2v.py实验
Block Sparse Attention (SM100a)tests/test_block_sparse_sm100a.py实验
ComfyUI Integrationcomfyui/成熟

阶段：高速发展与多平台扩展期（已发布 V1，正向 0.2.x 迭代，近期高频提交 Apple Silicon、DGX Spark、ROCm 支持及新模型适配）。

技术栈：Python >= 3.10；C++ / CUDA (fastvideo-kernel)；PyTorch (torch==2.12.0)；MLX (Apple Silicon)；Diffusers / Transformers / Accelerate；uv / setuptools / CMake / wheel；pre-commit (yapf, ruff, mypy, codespell)；pytest；Buildkite / GitHub Actions

规模：核心代码库 fastvideo 包含 1353 个文件，examples 319 个文件，apps 308 个文件，tests 164 个文件，定制算子库 fastvideo-kernel 105 个文件。近期提交极其频繁（如 2026年9月14日-18日期间有大量 bugfix 和 perf 提交），提交热点集中在 docs/cookbook (17)、fastvideo/tests (11) 和 fastvideo/pipelines (6)。已发布 0.1.6, 0.1.7, 0.2.0 等多个 Release。

二、架构与代码地图

FastVideo 的架构设计高度模块化，旨在打破训练与推理的壁垒，同时兼顾前沿 GPU 算力与端侧部署。针对你的硬约束（仅有 Mac），整体架构可划分为五层，其中有两层是你绝佳的切入点： 1. 应用与入口层 (Application & Entrypoints)：最上层是面向最终用户的应用（如 apps/dreamverse 实时流应用和 apps/fastvideo_studio 任务管理 UI），以及面向开发者的 Python API 入口（fastvideo/entrypoints/video_generator.py）。这一层负责接收用户 Prompt、解析配置（fastvideo/api），并统筹整个生成任务。 2. 调度与管线层 (Pipeline & Distributed Scheduling)：核心控制中枢。fastvideo/pipelines 负责管理扩散模型的去噪循环（Denoising Loop）、CFG 缩放等算法逻辑；fastvideo/distributed 负责多卡环境下的 Sequence Parallelism（序列并行）切分与 FSDP2 调度。对于只有 Mac 的你，这里的分布式切分逻辑完全可以在纯 CPU 环境下开发和单测，是绝佳的切入点。 3. 模型层 (Models)：位于 fastvideo/models，定义了各种 DiT 架构（如 Wan2.1/2.2, MiniMax-H3, FLUX 等）的组网逻辑。这里将 Transformer Block 的计算图与底层的具体算子解耦。 4. 执行路由层 (Execution Routing)：位于 fastvideo/attention。这是一个高度抽象的注意力后端路由层（如 backends/abstract.py），根据当前硬件环境和配置，动态将 Attention 计算分发给最合适的底层实现（如 FlashAttn, SageAttn, BSA, 或 MLX）。 5. 硬件与 Kernel 层 (Hardware & Kernels)：性能压榨的极地。包含针对 NVIDIA GPU 的 fastvideo-kernel（如 sm100a 块稀疏算子、attn_qat_infer 量化算子），以及针对 Apple Silicon 的 fastvideo/mlx_runtime。由于你缺乏本地 NVIDIA GPU，深耕 mlx_runtime，为 FastMetal-QAD 编写基于 Metal 的底层算子，将是你发挥端侧部署与量化经验、且能在本地完美闭环的最佳战场。

ApplicatiAPI LayerPipeline Model LayHardware Dreamverse → Entrypoints：发起生成请求发起生成请求Entrypoints → API：解析配置Entrypoints → Pipelines：启动管线启动管线Pipelines → Distributed：获取切分策略Pipelines → Models：执行 DiT Blo执行 DiT BloModels → AttentionRouting：请求注意力计算AttentionRouting → MLXRuntime：派发 Metal 算派发 Metal 算AttentionRouting → CUDAKernels：派发 CUDA 算子派发 CUDA 算子DreamverseDreamverseEntrypointsEntrypointsAPIAPIPipelinesPipelinesDistributedDistributedModelsModelsAttentionRoutingAttentionRoutingMLXRuntimeMLXRuntimeCUDAKernelsCUDAKernels
FastVideo 架构图：从顶层 API 到底层硬件算子的完整调用链路，展示了高度解耦的路由机制。
模块 / 路径职责 · 入口 · 依赖
Entrypoints
fastvideo/entrypoints
数十文件		推理与生成的顶层入口，统筹模型加载与管线执行。
入口：VideoGenerator
依赖：API, Pipelines, Models
用户调用的起点，封装了复杂的底层初始化逻辑。
API
fastvideo/api
数十文件		定义核心数据结构、配置 Schema 与请求解析。
入口：fastvideo/api/schema.py, fastvideo/api/sampling_param.py
依赖：无
包含 Pydantic 模型和预设配置，确保输入合法性。
Pipelines
fastvideo/pipelines
数十文件		执行扩散模型的去噪循环（Denoising Loop）与蒸馏算法逻辑。
入口：需验证
依赖：Models, Distributed
近期提交热点，支持 DMD2 蒸馏和 Self-Forcing 因果生成。
Distributed
fastvideo/distributed
数十文件		处理多卡环境下的序列并行（SP）切分与 FSDP2 调度。
入口：需验证
依赖：无
纯逻辑层，可在 Mac 上通过 Mock 进程数进行纯 CPU 单测，适合你切入。
Models
fastvideo/models
百级文件		定义各类 DiT 视频生成大模型（Wan, MiniMax-H3 等）的组网结构。
入口：需验证
依赖：AttentionRouting
将 Transformer Block 与底层算子解耦。
AttentionRouting
fastvideo/attention
数十文件		注意力后端的抽象与动态路由，根据硬件派发算子。
入口：fastvideo/attention/backends/abstract.py
依赖：MLXRuntime, CUDAKernels
支持 FlashAttn, SageAttn, BSA 等多种后端。
MLXRuntime
fastvideo/mlx_runtime
数十文件		Apple Silicon 专属运行时，基于 Metal 优化端侧推理。
入口：需验证
依赖：无
你的主战场！可以在 Mac 上本地闭环开发 FastMetal-QAD 的底层算子。
CUDAKernels
fastvideo-kernel
百级文件		极致优化的 CUDA/Triton 算子库（如 sm100a 稀疏算子、FP4/FP8 量化）。
入口：fastvideo-kernel/attn_qat_infer/api.py
依赖：无
独立编译的 C++ 扩展，虽然你无法本地运行，但可作为架构参考。
Dreamverse
apps/dreamverse
百级文件		实时视频生成与 Vibe Directing 互动应用。
入口：apps/dreamverse/dreamverse/main.py
依赖：Entrypoints
展示 FastVideo 极速推理能力的标杆级全栈应用。
目录树（按文件数）
  • fastvideo/ 1353 个文件
    AGENTS.md, __init__.py, api, attention, benchmarks, configs, dataset, distributed, entrypoints, envs.py, eval, fastvideo_args.py, forward_context.py, hooks
  • examples/ 319 个文件
    datasets, distill, inference, serving, train, training
  • apps/ 308 个文件
    dreamverse, fastvideo_studio, performance_dashboard
  • tests/ 164 个文件
    README.md, __init__.py, bench_block_sparse_sm100a.py, local_tests, test_block_sparse_bwd_sm100a.py, test_block_sparse_sm100a.py, test_block_sparse_sm100a_dispatch.py, test_bsa.py, test_fasth3_packaging.py
  • docs/ 110 个文件
    README.md, api, assets, attention, contributing, cookbook, design, distillation, generate_examples.py, getting_started, index.md, inference, training, utilities
  • fastvideo-kernel/ 105 个文件
    CMakeLists.txt, LICENSE, MANIFEST.in, README.md, attn_qat_infer, benchmarks, build.sh, csrc, include, pyproject.toml, python, tests
  • scripts/ 73 个文件
    check_docs_links.py, checkpoint_conversion, dataset_preparation, demo_anyflow_14b.py, distill, finetune, huggingface, inference, lora_extraction, ltx2_sr_alignment.py, preprocess, smoke_test_openai_video_api.py, train, validate_wan.sh
  • .agents/ 48 个文件
    lessons, scripts, skills
  • assets/ 48 个文件
    8steps, eval, fastwan.png, full.svg, girl.png, icon-simple.svg, images, logos, motorcycle.mp4, perf.png, prompt.txt, prompts, sliding_tile_attn_map.png, videos
  • .github/ 27 个文件
    ISSUE_TEMPLATE, PULL_REQUEST_TEMPLATE.md, mergify.yml, scripts, workflows
  • .buildkite/ 24 个文件
    performance-benchmarks, pipeline.yml, scripts
  • comfyui/ 17 个文件
    README.md, __init__.py, assets, examples, video_generator, web
  • docker/ 3 个文件
    Dockerfile, rocm7_1.Dockerfile, uv-excludes
  • .dockerignore/ 1 个文件
  • .gitignore/ 1 个文件
  • .gitmodules/ 1 个文件

一次调用怎么流过这些模块

以一次典型的端到端视频生成请求（如执行 examples/inference/basic/basic_wan2_2_i2v.py）为例，数据流转如下： 1. 请求初始化与配置解析：用户通过 VideoGenerator.from_pretrained() 实例化生成器。系统进入 fastvideo/api，解析 SamplingParam（如步数、CFG、分辨率）和 PipelineConfig。此时，系统会探测硬件环境。如果在 Apple Silicon 上，会自动将后端指向 MLX；如果在多卡 GPU 上，则初始化 NCCL/MPI 环境。 2. 分布式策略构建（CPU 调度点）：如果启用了序列并行（Sequence Parallelism），请求会进入 fastvideo/distributed。在这里，长视频的 Latent Tensor 会在 CPU 层面被逻辑切分，计算出每张卡的通信拓扑和切片索引（你可以在 Mac 上通过 Mock 进程数来单测这部分逻辑）。 3. 去噪管线执行：进入 fastvideo/pipelines。管线根据 DMD2 蒸馏或标准 ODE 求解器，启动 Denoising Loop。每一步迭代，Latent Tensor 和条件特征（Text/Image Embeddings）被送入 fastvideo/models 中的 DiT Block。 4. 注意力计算路由：在 DiT Block 内部，遇到最耗时的 Attention 计算时，调用 fastvideo/attention/backends/abstract.py。路由层根据配置（如 FASTVIDEO_ATTENTION_BACKEND 环境变量）将张量派发。 5. 底层 Kernel 执行： - Mac 本地路径：请求路由至 fastvideo/mlx_runtime，调用基于 Apple Metal 优化的 QAD（Quantization-Aware Distillation）算子，完成低比特矩阵乘法与注意力计算。 - GPU 路径：请求路由至 fastvideo-kernel，调用如 attn_qat_infer（FP4/FP8 量化注意力）或 block_sparse_attn（VSA 稀疏注意力）的 CUDA/Triton 算子。 6. 解码与输出：去噪循环结束后，最终的 Latent Tensor 通过 VAE 解码为像素级视频帧，封装为 VideoResult 返回，或通过 apps/dreamverse 的 WebSocket 实时推流给前端。

1发起请求Entrypoints · fastvideo/entrypoints/video_generator.py2解析配置API · fastvideo/api/schema.py3分布式切分Distributed · fastvideo/distributed/4启动去噪Pipelines · fastvideo/pipelines/5模型前向Models · fastvideo/models/6算子路由AttentionRouting · fastvideo/attention/backends/abstract.py7执行算子MLXRuntime · fastvideo/mlx_runtime/

关键类型与函数

名称路径用途
VideoGeneratorfastvideo/entrypoints/video_generator.py推理入口类，统筹模型加载与生成管线。
PipelineConfigfastvideo/api/schema.py定义生成管线的核心配置结构。
SamplingParamfastvideo/api/sampling_param.py封装用户请求的采样参数（步数、CFG、分辨率等）。
GenerationResultfastvideo/api/results.py统一的生成结果返回类型，包含视频帧数据。
AttentionBackendfastvideo/attention/backends/abstract.py注意力后端的抽象基类，所有自定义算子必须实现它以接入路由。
sageattn_blackwellfastvideo-kernel/attn_qat_infer/api.py针对 Blackwell 架构优化的量化注意力 API。
JobRunnerapps/fastvideo_studio/job_runner.pyUI 任务调度器，管理后台的异步生成任务。
CreateJobRequestapps/fastvideo_studio/models/create_job_request.py前端发起生成任务的数据模型。

扩展点

最近在动的地方

建议阅读顺序

  1. README.md
  2. fastvideo/entrypoints/video_generator.py
  3. fastvideo/api/schema.py
  4. fastvideo/pipelines/
  5. fastvideo/models/
  6. fastvideo/attention/backends/abstract.py
  7. fastvideo/mlx_runtime/
  8. fastvideo/distributed/
  9. fastvideo-kernel/

三、本地跑起来（没有 GPU 的 Mac）

安装

  1. git clone https://github.com/hao-ai-lab/FastVideo.git
  2. cd FastVideo
  3. uv venv --python 3.12 --seed
  4. source .venv/bin/activate
  5. uv pip install -e '.[mlx,dev]'
  6. pre-commit install --hook-type pre-commit --hook-type commit-msg

哪些路径能真跑

1. 完全可在 Mac (CPU/Metal) 闭环：fastvideo/mlx_runtime/（Apple Silicon 专属算子与推理后端，这是你发挥端侧部署经验的主战场）；fastvideo/distributed/（序列并行与 FSDP2 的切分逻辑，纯 CPU 即可开发与单测）；fastvideo/pipelines/ 与 fastvideo/models/（计算图构建与调度逻辑）。 2. 只能读代码或用 Colab T4 验证：fastvideo-kernel/ 下的 CUDA/Triton 算子。注意，T4 仅支持 sm75，仓库中前沿的 sm100a (Blackwell)、FP8 (fp8_wan2_1_1_3b.py)、NVFP4 (nvfp4_qat_wan2_1_1_3b.py) 算子在 T4 上绝对无法运行，只能做最基础的 Triton 算子冒烟测试。pyproject.toml 中已通过 sys_platform == 'linux' 巧妙屏蔽了 Mac 上的 fastvideo-kernel 和 flashinfer-python 编译，因此本地不会报错。

最小可运行

  1. python examples/inference/basic/mlx_wan_prompt_to_video.py
  2. python examples/inference/basic/mlx_fasth3.py
  3. python examples/inference/basic/mlx_wan_decode_benchmark.py
  4. FASTVIDEO_ATTENTION_BACKEND=SDPA python examples/inference/basic/basic.py
  5. pytest fastvideo/tests/ -k 'distributed'

测试

测试框架为 pytest。主要目录分为 fastvideo/tests/ (包级别测试) 和 tests/local_tests/ (本地组件测试)。CPU 子集跑法：运行 pytest fastvideo/tests/ --ignore=fastvideo/tests/ssim/。根据 AGENTS.md 明确指出，ssim/ 目录包含重度依赖 GPU 的画质回归测试，在 Mac 上必须跳过。纯 CPU/MLX 测试耗时通常在几分钟内。

调试

CI

CI 结合了 GitHub Actions (.github/workflows/) 与 Buildkite (.buildkite/pipeline.yml，用于 performance-benchmarks)。PR 会被严格的 pre-commit 钩子卡住（包含 yapf, ruff, mypy, codespell）。此外，涉及模型输出的修改会被 GPU 节点上的 SSIM 画质回归测试卡住。

坑

四、维护者与社区

仓库处于高速迭代期。近期提交非常密集（如 2026年9月14日至18日每天都有多个 Commit 合并）。Release 频率大约每 4-5 个月发布一次大版本（证据：0.1.6 于 2025-08-29，0.1.7 于 2026-01-05，0.2.0 于 2026-06-04）。

谁角色依据
Davids048推理、Dreamverse 应用与分布式特性维护者被指派处理 #1834 (Dreamverse 模式选择) 和 #1822 (FSDP inference with precomputed quantized weights)。
Satyam-53CI/CD、性能看板与基础设施维护者被指派处理 #1374 (性能回归追踪增强), #1632 (DGX Spark CI), #1633 和 #1604 (Worker 日志与看板配置)。
H1yori233模型集成追踪维护者被指派处理 #1407 ([tracker] Open add-model PRs)。
macthecadillac训练与分布式逻辑维护者被指派处理 #1592 (Modal GPU 训练) 和 #775 (TDM 特性)。
alexzmsKernel 打包与分发维护者被指派处理 #1318 (distribute fastvideo kernels)。

流程与 Review 风格

贡献流程规范严格：1. 重大变更或讨论需先提交带有 [RFC]: 标签的 Issue（如 #1374, #1606）。2. 本地开发强依赖 pre-commit，必须执行 pre-commit install --hook-type pre-commit --hook-type commit-msg。3. PR 必须包含明确的测试证据（pytest 或 SSIM 输出，若跳过需说明理由），并关联相关 Issue。4. Commit 信息需遵循 [tag]: subject (#PR) 格式（如 [bugfix]: ..., [feat]: ...）。

务实且高度关注性能与回归测试。从 AGENTS.md 要求 PR 必须提供 SSIM/pytest 证据，以及 #1374 专门追踪性能回归可以看出，Review 过程会严格把关代码对生成质量和推理速度的影响。响应速度快，近期 Issue（如 #1850, #1834）均有快速跟进和指派。

渠道

这里的规矩

维护者现在最想要的帮助

五、切入方案

建议长期负责：fastvideo/mlx_runtime (Apple Silicon 推理后端) 与 fastvideo/distributed (分布式调度逻辑)
这是在你的硬约束（仅有 16GB Mac，无本地 NVIDIA GPU）下，唯一能通向核心 Maintainer 的双轨路径。一方面，mlx_runtime 是你发挥端侧部署与量化经验的主战场，你可以将 CUDA 算子优化的思想降维应用到 Metal 上，且完全在本地闭环测试；另一方面，distributed 目录下的序列并行（Sequence Parallelism）和 FSDP2 调度本质上是计算图切分与通信拓扑设计，纯 CPU 即可完成逻辑开发与单测。这两个模块既是当前项目高速扩张的核心（见近期 MLX 和 Spark 的密集提交），又能完美避开你无法运行 sm100a 或 FP8 CUDA 算子的硬件劣势。

它现在缺什么（你无 GPU 也能补）

缺口依据为什么是你
Apple Silicon (MLX) 后端的算子性能与显存优化（如针对 16GB 内存的极致 Offload）仓库近期密集增加了对 Apple Silicon 的支持（如 fastvideo/mlx_runtime 目录，以及 README 中提到的 FastMetal-QAD 模型），且最近的 Commit（如 [perf] H3 decode: offload the frozen VAEs）显示团队正在高度关注显存 Offload 优化。你拥有 16GB Mac，这是复现端侧显存瓶颈的绝佳环境；你的端侧部署与量化经验（TensorRT/量化）可以降维打击，将 CUDA/Triton 的显存复用与算子融合思想迁移到 Metal/MLX 上。
分布式切分逻辑（Sequence Parallelism / FSDP2）的纯 CPU 单元测试与 Mock项目包含 fastvideo/distributed 目录，且测试套件中有 pytest fastvideo/tests/ -k 'distributed'。但分布式逻辑通常强依赖多 GPU 环境，缺乏在纯 CPU 下验证切分拓扑和通信原语（如 ulysses_all_to_all 的 Python 侧 Mock）的测试。你精通分布式训练性能，完全可以在不依赖 GPU 的情况下，在 Mac 上用纯 PyTorch CPU 编写张量切分、形状推导和通信路由的单测，保障核心逻辑的鲁棒性。
Attention 路由层在无 GPU 环境下的优雅降级与 SDPA 对齐fastvideo/attention/backends/ 目录下有 abstract.py、flash_attn.py、sdpa.py 等。目前前沿算子（如 attn_qat_infer）强依赖 CUDA，缺乏在 CPU/Mac 上使用标准 SDPA 进行数学等价性验证的机制。你熟悉 PyTorch 内核与算子融合，能够编写高精度的 CPU SDPA 对照组，用于在 CI 中验证 QAT（量化感知训练）或 VSA（视频稀疏注意力）的数学正确性。
Triton 算子的 CPU Mock 与基础冒烟测试fastvideo-kernel/python/fastvideo_kernel/triton_kernels/ 包含大量 Triton 算子（如 fused_compress_topk.py）。CI 中虽然有 DGX Spark，但缺乏轻量级的 Triton 逻辑验证。你精通 Triton，知道如何将 Triton 的 Block/Grid 逻辑抽象为纯 Python 循环或 CPU 张量操作，从而在 Mac 上验证索引计算（Index Math）的正确性。
端侧量化模型（FastMetal-QAD）的性能 Benchmark 脚本完善examples/inference/basic/ 下有 mlx_wan_decode_benchmark.py 和 mlx_wan_quant_benchmark.py，但端侧性能看板（Dashboard）和自动化回归追踪仍需加强（Issue #1374 追踪性能回归）。你擅长性能工程，可以在本地 Mac 上完善这些 Benchmark 脚本，增加对显存峰值（Peak Memory）和吞吐量（Tokens/s）的精确统计。
DiT 模型计算图构建层（Models）与底层算子（Kernels）的解耦验证fastvideo/models 负责组网，fastvideo/attention 负责路由。随着模型增多（Wan2.1, MiniMax-H3, FLUX），需要确保计算图在没有 fastvideo-kernel 时能安全 fallback 到 MLX 或纯 PyTorch。你的系统架构视野能帮助梳理 fastvideo/models 中的硬编码 CUDA 依赖，将其重构为通过 registry.py 或 abstract.py 动态分发，完全在 Mac 上闭环开发。

第 1–30 天：看懂并露面

第 31–60 天：稳定产出

第 61–90 天：接管一块

第一批 PR

题目范围为什么安全
[test]: Add pure CPU unit tests for Sequence Parallelism slicing logicfastvideo/tests/, fastvideo/distributed/纯 Python/PyTorch 逻辑，不涉及任何 GPU Kernel。通过 Mock 通信组（Process Group），在单机 CPU 上验证张量切分（Slice）和拼接（Concat）的形状正确性。这填补了 CI 在分布式逻辑上的测试空白，且绝对不会引发硬件相关的 Regression。
[perf]: Optimize MLX memory offloading for 16GB Apple Siliconfastvideo/mlx_runtime/, fastvideo/models/直接针对你的硬约束（16GB Mac）进行优化。参考近期 H3 模型的 Offload 提交，将不参与当前计算的权重（如 Text Encoder 或 VAE）在 MLX 后端更积极地卸载到统一内存。完全在本地闭环测试，不影响 CUDA 链路。
[misc]: Add SDPA fallback validation for Attn-QAT on CPUfastvideo/attention/backends/sdpa.py, fastvideo/tests/利用标准的 torch.nn.functional.scaled_dot_product_attention，在 CPU 上实现量化感知训练（Attn-QAT）的数学等价对照组。这不仅帮助你在无 GPU 环境下理解 QAT 逻辑，也为项目提供了一个无需编译 fastvideo-kernel 即可验证算法正确性的基准。
[docs]: Document MLX runtime architecture and FastMetal-QAD memory requirementsdocs/inference/, docs/getting_started/高价值且零风险。通过阅读源码，将 mlx_runtime 的架构设计、FastMetal-QAD 在 16GB/32GB Mac 上的显存占用实测数据补充到 MkDocs 文档中，帮助社区其他 Mac 用户快速上手。

怎么知道自己站住了

风险与对策
  • 在修改 fastvideo/models 或 fastvideo/pipelines 时，无意中破坏了前沿 CUDA 算子（如 sm100a 或 FP8）的调用逻辑，且本地无法测试。：严格遵守架构的解耦设计，所有修改必须通过 fastvideo/attention/backends/abstract.py 路由。提交 PR 前，务必在 Colab T4 上运行 FASTVIDEO_ATTENTION_BACKEND=SDPA python examples/inference/basic/basic.py 进行基础冒烟测试，并依赖 CI 的 GPU 矩阵进行最终把关。
  • 本地代码风格检查失败，导致 PR 被 CI 拒绝。：绝对不要绕过 pre-commit。必须执行 pre-commit install，并在提交前运行 pre-commit run --all-files。注意 pyproject.toml 中配置了 120 行宽限制，且 .pre-commit-config.yaml 有特定的 exclude 规则（如跳过 fastvideo/tests/），尊重这些既有规则。
  • 16GB Mac 显存在运行 DiT 模型时频繁 OOM，导致本地开发受阻。：在开发初期，使用最小的模型（如 FastMetal-1.3B-QAD），或者在代码中编写 Mock 脚本，用随机初始化的极小 Shape 张量（如 1x4x16x16）来验证 MLX 算子逻辑，而不是每次都加载完整权重。
  • 试图在 Colab T4 上验证前沿特性（如 NVFP4 或 Blackwell 稀疏算子）导致挫败。：明确认知 T4 仅支持 sm75。绝不碰 fastvideo-kernel/csrc/ 下的 sm100a 或 fp8 代码。Colab T4 仅用于验证纯 PyTorch 逻辑、Triton 算子的基础 Fallback 以及 Gradio/API 层的连通性。
  • 项目迭代速度极快（每天多个 Commit），本地分支容易与 main 产生严重冲突。：保持高频的 git pull --rebase upstream main。在开发新特性前，先在 Issue 中提交带有 [RFC]: 标签的方案，与维护者对齐后再动手，避免闭门造车导致代码废弃。

六、怎么介入这个项目

社区入口：github.com/hao-ai-lab/FastVideo/discussi · join.slack.com/t/fastvideo/shared_invite · github.com/hao-ai-lab/FastVideo/discussi · hao-ai-lab.github.io/FastVideo/inference

建议顺序

成为长期维护者的路径
  • 深耕 Apple Silicon (MPS/MLX) 后端的算子适配与显存优化，解决端侧部署的痛点
  • 完善纯逻辑层（如 Batching、分布式切分）的 CPU 单测与架构解耦
  • 参与多硬件后端（如 MPS、CPU fallback）的 CI 建设与代码 Review

七、任务卡

任务 1优先 · medium · Mac · 2-3 个晚上

[perf] Reuse cached VAE offload for H3 reference and keyframe encoding

Issue #1880 · [perf] Reuse cached VAE offload for H3 reference and keyframe encoding ↗

无人认领0 条评论installationperformanceplatform更新 2026-09-21

用到的专长：利用你的内存管理和端侧部署经验，优化大模型的内存占用。

目标：复用已有的 VAE CPU offload 缓存，避免在 H3 模型的 keyframe 和 reference 编码时产生额外的 10.4GB 内存拷贝。

为什么值得长期做：优化端侧和低显存设备的内存管理是推理框架的核心竞争力，这能让你深入理解 FastVideo 的内存调度机制，为后续主导 MLX 显存优化打下基础。

怎么介入：Issue 处于 open 状态且无人认领，直接留言认领。
第一个 PR 的边界：仅修改 H3 pipeline 中的 VAE 加载逻辑，不涉及其他模型。
第一步：定位 fastvideo/pipelines/basic/minimax_h3/stages/minimax_h3_latent_preparation.py 中的 _encode_fl2va_conditions 和 _encode_ref2va_conditions。
本机怎么复现 / 验证：在 Mac 上运行 python examples/inference/basic/basic_fasth3_8step.py（修改配置为 CPU 运行并开启 vae_cpu_offload），使用 mprof 观察内存占用曲线。
认领留言（英文，可直接贴到 Issue）
Hi, I'd like to work on this. I will route the video and audio VAE loading/unloading in the input-encoding functions through the helper from #1867 to reuse the host-weight cache. I can validate the memory reduction locally on my 16GB Mac using CPU offload. Expect a PR in 2-3 days.
大致实施方案
  • 查看 PR #1867 引入的 VAE load/unload 辅助函数。
  • 修改 _encode_fl2va_conditions 和 _encode_ref2va_conditions，将直接的 .to(device) 和 .to("cpu") 替换为调用该辅助函数。
  • 对音频 VAE 的加载/卸载逻辑进行同样的替换，确保行为一致。
  • 在 Mac 上使用纯 CPU 模式运行 H3 decode 和编码流程，监控内存峰值，确保没有多余的 CPU 拷贝。
可能涉及的目录或文件
  • fastvideo/pipelines/basic/minimax_h3/stages/minimax_h3_latent_preparation.py
验收方式
  • 在 Mac 上设置 vae_cpu_offload=True 和 lazy_module_load=False，运行 H3 推理脚本，通过 mprof run 或 psutil 监控内存，确认峰值内存下降。
开工前问题与风险

向维护者确认

  • 对于音频 VAE，是否也需要完全遵循视频 VAE 的 pin_memory 逻辑？

风险

  • 如果辅助函数依赖特定的 CUDA 行为（如 pinned memory），可能需要在 CPU/MPS 上做 fallback 处理。
任务 2优先 · medium · Mac · 1-2 个晚上

[Bug] MPS generation fails when multiprocessing worker returns output tensors

Issue #1846 · [Bug] MPS generation fails when multiprocessing worker returns output tensors ↗

无人认领1 条评论installationperformanceplatform更新 2026-09-14

用到的专长：利用你的 Mac 本地环境和 PyTorch 底层机制理解，修复 MPS 特有的序列化问题。

目标：解决 MPS tensor 在多进程 worker 返回时无法通过 CPU shared memory 序列化的问题。

为什么值得长期做：修复 Apple Silicon 上的多进程通信问题，直接提升 Mac 用户的核心体验，建立你在 MPS 后端维护上的影响力。

怎么介入：Issue 无人认领，但有 linked PR #1847 (closed)。需要先确认 #1847 为什么被 close，或者直接提出新的修复方案。
第一个 PR 的边界：仅修改多进程 executor 中的结果发送逻辑，增加 MPS 到 CPU 的转换。
第一步：定位 fastvideo/worker/multiproc_executor.py 中的 worker_busy_loop。
本机怎么复现 / 验证：在 Mac 上启动 Studio，创建一个 T2I 任务（如 prompt 'a red dinosaur'），观察 worker 进程是否抛出 _share_filename_: only available on CPU 异常。
认领留言（英文，可直接贴到 Issue）
Hi, I can take this up. Since MPS tensors cannot be shared via CPU shared memory, I will add a step to explicitly move MPS tensors to CPU before self.pipe.send() in worker_busy_loop. I will test this locally on my Apple Silicon Mac. I noticed #1847 was closed, is there any specific approach you prefer?
大致实施方案
  • 在 worker_busy_loop 中，拦截 worker 返回的结果字典。
  • 遍历结果，如果发现 tensor 所在的 device 是 mps，则在调用 self.pipe.send() 前，将其显式转换为 CPU tensor (tensor.cpu())。
  • 确保转换逻辑不会影响 CUDA 或纯 CPU 路径的性能（可以加 if tensor.device.type == 'mps' 判断）。
  • 在 Mac 上启动 Studio 并运行一个简单的 T2I 任务，验证图像能否成功返回并显示。
可能涉及的目录或文件
  • fastvideo/worker/multiproc_executor.py
验收方式
  • 在 Mac 上运行 Studio，提交一个 FLUX.2-klein-4B 的 T2I 任务，确认任务能成功完成且前端能收到图像。
开工前问题与风险

向维护者确认

  • 除了 worker 返回结果，是否还有其他 IPC 边界需要处理 MPS tensor 的 CPU 转换？

风险

  • 大 tensor 的 .cpu() 转换可能会带来一定的同步延迟，但对于 MPS 来说这是必须的。
任务 3优先 · high · CPU · 3-4 个晚上

[Feature] Implement batching support for inference (Roadmap Q3)

Issue #1603 · Dev Roadmap 2026 Q3 ↗

已有 PR #17081 条评论scope: trainingscope: inferencescope: attention更新 2026-08-10

用到的专长：利用你的推理性能优化经验，在纯逻辑层实现 batching 调度。

目标：为 FastVideo 的推理管线添加基础的 batching 支持，允许一次传入多个 prompt 并进行批处理去噪。

为什么值得长期做：Batching 是推理框架吞吐量的核心。实现纯逻辑层的 batching 调度，能充分发挥你的系统架构能力，且完全不依赖 GPU。

怎么介入：这是 Roadmap 中的未认领子项。在 Issue #1603 下留言认领该子项。
第一个 PR 的边界：首先在一个基础模型（如 FastWan）的纯 PyTorch/SDPA 路径上实现静态 batching。
第一步：分析 fastvideo/pipelines/ 下的基础 pipeline（如 Wan 或 H3），查看当前的输入处理逻辑。
本机怎么复现 / 验证：在 Mac 上编写测试脚本，调用 generator.generate_video(['prompt1', 'prompt2'])，设置环境变量强制使用 CPU 和 SDPA 后端，验证是否报错。
认领留言（英文，可直接贴到 Issue）
Hi, I'd like to pick up the 'batching support' item from the roadmap. I plan to start by modifying the VideoGenerator and base pipelines to accept a list of prompts, handling the batch dimension for text embeddings and latents. I will validate the logic using the CPU backend. Is there a specific model pipeline I should target first?
大致实施方案
  • 修改 VideoGenerator.generate_video API，使其接受 List[str] 类型的 prompt。
  • 在 pipeline 内部，将多个 prompt 的 text embeddings 沿 batch 维度拼接。
  • 调整 latent 初始化的 shape，使其 batch size 与 prompt 数量一致。
  • 确保底层的 Attention 路由层（如 SDPA fallback）能够正确处理 batch size > 1 的输入。
  • 在 Mac 上使用纯 CPU 模式，传入 2 个 prompt，验证生成的视频/图像张量 shape 正确。
可能涉及的目录或文件
  • fastvideo/entrypoints/video_generator.py
  • fastvideo/pipelines/
验收方式
  • 编写单元测试，传入包含 2 个 prompt 的列表，断言输出的视频张量 batch 维度为 2，且在 CPU 上能成功运行完整个去噪循环。
开工前问题与风险

向维护者确认

  • 对于不同长度的 prompt，是否需要实现 padding 和 attention mask？
  • 第一阶段是否只支持静态 batching？

风险

  • 某些底层算子（如特定的 VSA kernel）可能对 batch size 有硬编码限制，需要做好 fallback 或断言。
任务 4可选 · low · Mac · 1 个晚上

[Bug] VBench SceneMetric loads Qwen2.5-Omni on CPU on any non-CUDA accelerator (device_map hardcodes cuda)

Issue #1815 · [Bug] VBench SceneMetric loads Qwen2.5-Omni on CPU on any non-CUDA accelerator (device_map hardcodes cuda) ↗

已有 PR #18171 条评论installationplatformscope: inference更新 2026-09-05

用到的专长：利用你的 Mac 环境，为多后端适配提供真实的 MPS 验证数据。

目标：Review PR #1817，并在 Apple Silicon (MPS) 上验证 SceneMetric 的设备映射逻辑。

为什么值得长期做：参与多硬件后端的适配审查，有助于你熟悉 FastVideo 的设备抽象层。

怎么介入：已有 PR #1817，不要直接开新 PR。去 PR 下 review 并提供 MPS 测试结果。
第一个 PR 的边界：Review 和测试验证，视情况提交补充测试的 PR。
第一步：拉取 PR #1817 的分支到本地。
本机怎么复现 / 验证：在 Mac 上运行包含 SceneMetric 初始化的脚本，传入 device='mps'，检查模型权重的 device 属性是否为 mps。
认领留言（英文，可直接贴到 Issue）
Hi, I have an Apple Silicon Mac and can help verify PR #1817 for the MPS backend. I will test loading Qwen2.5-Omni via SceneMetric on MPS and report the memory usage and latency. Let me know if you need me to add a specific unit test for this.
大致实施方案
  • 检查 PR #1817 的代码，确认其是否正确处理了 mps 设备。
  • 在 Mac 上编写一个简单的测试脚本，调用 SceneMetric 并传入 device="mps"。
  • 验证 Qwen2.5-Omni 模型是否成功加载到 MPS 内存中，而不是 CPU。
  • 如果 PR 缺少对 MPS 的显式测试，可以在 PR 下留言补充测试结果，或者提交一个包含 MPS 测试用例的后续 PR。
可能涉及的目录或文件
  • fastvideo/metrics/
验收方式
  • 在 Mac 上运行 SceneMetric，通过活动监视器确认 GPU 内存被占用，且推理速度显著快于纯 CPU。
开工前问题与风险

向维护者确认

  • 对于 MPS 设备，是否需要特殊的 dtype 转换（如 float16）以避免某些算子不支持？

风险

  • 模型可能包含 MPS 不支持的算子，导致加载到 MPS 后推理失败。
任务 5候补 · low · Mac · 1 个晚上

[Docs] Add Wan-VACE inference example

Issue #1435 · Wan-VACE推理example ↗

无人认领2 条评论stalescope: docsscope: model更新 2026-09-04

用到的专长：通过编写示例代码，快速熟悉 FastVideo 的顶层 API 和模型加载机制。

目标：添加一个 Wan-VACE 模型的推理示例脚本，类似于现有的 wan-control 示例。

为什么值得长期做：完善示例代码是熟悉框架 API 的最佳途径，同时能帮助社区用户快速上手新模型。

怎么介入：Issue 处于 open 状态，直接留言认领。
第一个 PR 的边界：仅添加一个示例 Python 脚本及少量文档更新。
第一步：查看 examples/inference/ 目录下现有的 Wan 模型示例（如 basic_wan2_1_t2v.py）。
本机怎么复现 / 验证：在 Mac 上运行新增的 basic_wan_vace.py，观察是否能成功加载模型并完成至少一步推理。
认领留言（英文，可直接贴到 Issue）
Hi, I can help add the inference example for Wan-VACE. I will create a script under examples/inference/basic/ similar to the existing Wan examples, and test it locally on my Mac using the MPS/CPU backend. I'll submit a PR shortly.
大致实施方案
  • 复制一个基础的 Wan 推理脚本，重命名为 basic_wan_vace.py。
  • 根据 Wan-VACE 的模型结构和加载方式，修改 VideoGenerator.from_pretrained 的参数。
  • 调整输入参数（如是否需要特定的 condition 图像或控制信号）。
  • 在 Mac 上使用 CPU 或 MPS 后端，运行该脚本，确保模型能成功加载并跑通前向传播（可以设置 step=1 以节省时间）。
  • 更新相关的 README 或文档，指向新添加的示例。
可能涉及的目录或文件
  • examples/inference/basic/basic_wan_vace.py
  • docs/inference/inference_quick_start.md
验收方式
  • 在 Mac 上运行 python examples/inference/basic/basic_wan_vace.py，确认脚本能成功执行并输出结果张量。
开工前问题与风险

向维护者确认

  • Wan-VACE 模型是否有特定的预处理要求或特殊的 pipeline 参数？

风险

  • 如果 Wan-VACE 依赖特定的 CUDA 算子，可能在 Mac 上无法完全跑通，需要设置 fallback。