A Anaxagore
← 所有项目

Contribution Tasks

modelscope/DiffSynth-Engine

候选人的 GPU kernel / 训练性能专长与仓库的 attention 后端、sampler 数值正确性、跨平台兼容性高度匹配；当前仓库 kernels/ 为空壳、algorithm 层缺少数值对齐测试、Apple Silicon 支持缺少验证，这些都能在 CPU / Mac 上完成，无需本地 GPU。

当前方向：仓库当前开发主轴是新模型接入（Flux2、Z-Image、Qwen-Image-Edit、Wan S2V）和 NPU/Ascend 后端扩展；utils/ 与 configs 层持续优化跨平台兼容性；algorithm 层（sampler/scheduler）是刻意重新实现的核心组件，但缺乏数值对齐验证。

★ 433Fork 506 个候选任务Gemini：LongCat-2.0

更新于 2026-11-05T07:57:30+00:00 · 本次生成失败，展示上次结果 · 打开仓库 ↗

一、项目定位

DiffSynth-Engine 是阿里 ModelScope 团队维护的一个面向扩散模型（Diffusion）推理的高性能引擎，核心定位是把 DiT、Wan2.x 系列视频模型、Qwen-Image、Flux 等主流生成模型做成一套自研、低依赖、可跨平台的推理管线。README 明示它“重新实现了 sampler、scheduler 等关键组件”，刻意避免引入 k-diffusion / ldm / sgm 等第三方扩散库依赖，以此换取更可控的内存、量化与调度策略。目前主仓库规模约 211 个核心模块文件 + 156 个测试文件，最近提交热点集中在 diffsynth_engine/models、diffsynth_engine/pipelines、tests/data，说明模型接入与管线适配是当前开发主轴。Release 已到 v0.7.0（2026-01-19），v0.6.0 起开始支持 Wan2.2-S2V 这种音频驱动视频模型，节奏约 2–3 周一版，属于快速迭代但尚未进入稳定 ABI 阶段的项目。它既不是纯研究代码也不是端到端训练框架，而是介于 diffusers 与 TensorRT 之间的“推理运行时 + 模型格式 + 并行/量化策略”层。

解决什么问题、给谁用

解决的核心问题是：扩散模型（尤其是 DiT 类图像 / 视频生成模型）在真实部署时面临的显存占用高、依赖重、跨平台体验差、量化与 offload 策略碎片化等痛点。具体包括：(1) 把 Flux.1 Dev、Wan2.2-S2V、Qwen-Image-Edit 等大体量模型通过 FP8/INT8 量化 + 分片 offload 塞进有限显存；(2) 去掉对 k-diffusion/sgm 的依赖，把 scheduler、采样器、并行策略内聚到一套实现里，方便针对不同硬件做性能调优；(3) 在 Windows / macOS Apple Silicon / Linux 上提供统一 API，让同一份 config 能跑在不同设备上。目标用户是做扩散模型部署、推理优化、端侧落地的工程师，以及需要在低资源环境下跑 Flux/Wan/Qwen 等模型的开发者。典型场景：用 FluxImagePipeline.from_pretrained 快速出图；用 load_lora 接 CivitAI 风格 LoRA；用 yunchang（仅 Linux）做长上下文并行；用 ODTSR 做 Qwen-Image 上采样后处理。

(1) 扩散模型推理/部署工程师——需要把 DiT、Wan2.x、Flux、Qwen-Image 以低显存跑起来，关注 FP8/INT8、offload、并行切片；(2) 视频生成方向开发者——用 Wan2.2-S2V / Wan2.2 / DiT-HY 做 text-to-video、image-to-video、speech-to-video，需要管线级 API 与示例；(3) 端侧/跨平台用户——希望在 MacBook Air Apple Silicon 或低配 N 卡上跑生成任务；(4) 想做 kernel/性能贡献的 CUDA 工程师——仓库含 kernels/ 目录与 Triton/CUDA 优化空间，但当前很多后端仍以 PyTorch 原生算子为主，是潜在切入点。

同类项目与差别

核心能力

能力在哪成熟度
自研 sampler / scheduler，无 k-diffusion / ldm / sgm 依赖diffsynth_engine/algorithm/, diffsynth_engine/pipelines/成熟
Flux 系列图像管线（text-to-image、LoRA、Flux.2-Klein）diffsynth_engine/pipelines/ (FluxImagePipeline 等), examples/flux_*.py成熟
Wan2.x / Wan2.2 / Wan2.2-S2V 视频管线（t2v / i2v / speech-to-video）diffsynth_engine/pipelines/, examples/wan_*.py成熟
Qwen-Image / Qwen-Image-Edit / ODTSR 上采样后处理diffsynth_engine/pipelines/, examples/qwen_image_*.py, examples/odtsr_upscale_tool_example.py成熟
FP8 / INT8 量化与显存 offload 策略diffsynth_engine/utils/, diffsynth_engine/models/, README 量化描述成熟
并行推理（yunchang 长上下文并行，Linux only）pyproject.toml (yunchang ; sys_platform == 'linux'), examples/flux_parallel.py, examples/qwen_image_parallel.py, examples/wan_parallel.py实验
Apple Silicon / macOS / Windows / Linux 跨平台README, pyproject.toml, tests/, examples/成熟
CivitAI 格式 LoRA 加载diffsynth_engine/pipelines/ (load_lora), examples/flux_lora.py, examples/wan_lora.py成熟
Triton / CUDA kernel 层diffsynth_engine/kernels/实验
ONNX / TensorRT / 端侧部署后端pyproject.toml (onnxruntime), examples/memory_predict_model/, examples/model_perf_benchmark.py实验
贡献指南与规范流程README Contributing 节、.pre-commit-config.yaml缺失

阶段：快速迭代的“生产可用但 ABI 未冻结”阶段。Release 已到 v0.7.0，README 与 docs 有明确教程与示例，支持多模型、多平台、多量化；但 README Contributing 仍写 TODO: Please refer to CONTRIBUTING.md，且存在 breaking change 记录（v0.4.0 from_pretrained 改动），说明接口仍在演进。

技术栈：Python 3.10+；PyTorch >=2.6, <=2.8；torchvision, numpy, scipy, einops；safetensors, gguf；modelscope (模型下载/管理)；tokenizers, sentencepiece, ftfy, regex；torchsde (SDE 采样相关)；pillow, imageio[ffmpeg], opencv-python, moviepy, librosa, scikit-image, trimesh；onnxruntime (可选)；yunchang (仅 Linux，长上下文并行)；flufl.lock；setuptools + setuptools_scm 构建；ruff + pre-commit + pytest (dev)

规模：仓库核心模块文件约 211 个（diffsynth_engine/），测试文件 156 个（tests/），示例脚本 30 个（examples/）。最近提交热点：models 10、pipelines 6、test_pipelines 5、utils 4，说明开发与测试同步进行。Release 至少到 v0.7.0（2026-01-19），v0.4.0 起有明确 changelog 与 breaking change 记录。最近提交时间 2026-05–2026-03，仍在活跃维护。star、fork、issues 等社交数字未提供，需验证。

二、架构与代码地图

DiffSynth-Engine 采用经典的「接入层 / 调度层 / 模型层 / 执行层 / 工具层」五层结构，自上而下职责清晰。接入层（pipelines + tools + examples）面向用户，提供 FluxImagePipeline、WanVideoPipeline、QwenImagePipeline 等高级封装，以及 FluxInpaintingTool 等后处理工具，负责组装模型、管理 LoRA 加载与并行策略。调度层（configs + algorithm）承载所有配置 dataclass（FluxPipelineConfig、WanPipelineConfig、AttentionConfig、OptimizationConfig、ParallelConfig 等）以及自研的 sampler 与 noise_scheduler，刻意不依赖 k-diffusion / sgm，支持 Flow Match Euler、DPM-Solver、DEIS、Brownian Tree 等多种采样器。模型层（models）是仓库最大的模块，按模型族分目录（flux / flux2 / sd / sdxl / sd3 / wan / qwen_image / z_image / hunyuan3d / text_encoder / vae / basic），每个模型目录下由 StateDictConverter 负责权重映射，PreTrainedModel 负责 forward，basic 子目录提供 Attention、LoRA、FBCache、VideoSparseAttention 等可复用原语。执行层（kernels + utils）提供底层算子调度与基础设施：kernels 目录目前为空壳（__init__.py），说明 kernel 实现以第三方库（Flash Attention 2/3/4、xformers、Sage Attention、VSA）为主；utils 则提供 offload、parallel、fp8_linear、gguf、memory 预测、platform flag 等工具，是跨硬件兼容的关键。工具层（tokenizers + processor）封装 CLIP/T5/Qwen2/Wan tokenizer 与 Canny/Depth 等 ControlNet 前置处理器。这种分层让「加新模型」只需在 models/ 和 pipelines/ 各加一个目录/文件，加新 kernel 只需在 basic/ 或 utils/ 加适配器，不影响其他层。

接入层调度层模型层执行层测试层其他examples → pipelines：调用调用pipelines → configs：配置配置pipelines → models：组装组装pipelines → algorithm：采样采样models → models/basic：原语原语models/basic → utils：flagflagpipelines → utils：offloadoffloadpipelines → tokenizers：编码编码pipelines → processor：预处理预处理tools → pipelines：组合configs → utils：flagflagalgorithm → models：调用调用tests → pipelines：测试测试tests → models：测试测试kernels → models/basic：预留预留pipelinespipelinestoolstoolsexamplesexamplesconfigsconfigsalgorithmalgorithmtokenizerstokenizersprocessorprocessormodelsmodelsutilsutilskernelskernelsteststestsmodels/basicmodels/basic
DiffSynth-Engine 五层架构图：接入层（pipelines/tools/examples）→ 调度层（configs/algorithm）→ 模型层（models/basic/tokenizers/processor）→ 执行层（utils/kernels），tests 横向覆盖所有层
模块 / 路径职责 · 入口 · 依赖
pipelines
diffsynth_engine/pipelines
约 12 个核心文件		用户接入层，封装端到端推理流程，管理模型加载、LoRA、并行、offload 与采样调度
入口：BasePipeline, FluxImagePipeline.from_pretrained, WanVideoPipeline, QwenImagePipeline, WanSpeech2VideoPipeline, Flux2KleinPipeline
依赖：configs, models, algorithm, utils
commit 热点第 3（6 次），每次新模型接入都从这里切入；from_pretrained 是核心工厂方法
configs
diffsynth_engine/configs
约 2 个核心文件（pipeline.py, controlnet.py）		统一配置层，定义所有 pipeline 的 dataclass 配置（模型路径、dtype、并行、优化、attention 实现等）
入口：FluxPipelineConfig, WanPipelineConfig, QwenImagePipelineConfig, AttentionConfig, OptimizationConfig, ParallelConfig, AttnImpl, BaseStateDicts, FluxStateDicts
依赖：utils/flag
所有新模型扩展必须先在这里加对应的 *PipelineConfig 和 *StateDicts
algorithm
diffsynth_engine/algorithm
约 12 个文件（sampler + noise_scheduler 各 6 个）		自研采样与噪声调度层，不依赖 k-diffusion/sgm，支持 Flow Match 与 Stable Diffusion 两大类
入口：flow_match/flow_match_euler.py, stable_diffusion/euler.py, stable_diffusion/dpmpp_2m.py, stable_diffusion/deis.py, stable_diffusion/brownian_tree.py, recifited_flow.py
依赖：torch
README 明示这是刻意重新实现的核心组件，是性能调优的重点区域
models
diffsynth_engine/models
约 50+ 个文件（仓库最大模块，commit 热点第 1，10 次）		模型实现层，按模型族分目录，每个目录包含 DiT/UNet、VAE、TextEncoder、StateDictConverter
入口：PreTrainedModel, StateDictConverter, flux_dit.py, wan_dit.py, qwen_image_dit.py, sd_unet.py, attention.py
依赖：models/basic, utils, configs
basic/ 子目录提供 Attention、LoRA、FBCache、VideoSparseAttention 等共享原语；新模型接入的主战场
models/basic
diffsynth_engine/models/basic
约 8 个文件		可复用模型原语层，封装 Attention、LoRA 融合、FBCache、VideoSparseAttention、TimeStep 等
入口：Attention, LoRA, FBCache, VideoSparseAttention, timestep.py, transformer_helper.py
依赖：utils/flag, utils/platform
Attention 类是所有 DiT/UNet 的核心，支持 FA2/3/4、xformers、SDPA、Sage、Sparge、VSA 等多种后端
utils
diffsynth_engine/utils
约 15 个文件（commit 热点第 5，4 次）		基础设施层，提供 offload、parallel、fp8_linear、gguf、memory 预测、platform flag 等底层工具
入口：offload.py, parallel.py, fp8_linear.py, gguf.py, memory/memory_predcit_model.py, flag.py, platform.py, loader.py, cache.py
依赖：torch
offload 与 parallel 是跨硬件兼容的关键；memory_predcit_model 用于无 GPU 时预测显存占用
tools
diffsynth_engine/tools
约 6 个文件		高级工具层，提供 inpainting、outpainting、reference、replace、upscaler 等后处理工具
入口：FluxInpaintingTool, FluxOutpaintingTool, FluxIPAdapterRefTool, FluxReduxRefTool, FluxReplaceByControlTool, qwen_image_upscaler_tool.py
依赖：pipelines, processor
ODTSR upscaler（qwen_image_upscaler_tool）是最近新增功能（v0.7.0）
tokenizers
diffsynth_engine/tokenizers
约 7 个文件		Tokenizer 封装层，支持 CLIP、T5、Qwen2、Qwen2-VL、Wan 等
入口：tokenizers/clip.py, tokenizers/t5.py, tokenizers/qwen2.py, tokenizers/wan.py, tokenizers/base.py
依赖：tokenizers 库, sentencepiece
每个新模型常伴随新的 tokenizer，如 Wan S2V 的音频 tokenizer
processor
diffsynth_engine/processor
约 2 个文件		图像预处理器层，为 ControlNet 提供 Canny、Depth 等条件输入
入口：canny_processor.py, depth_processor.py
依赖：opencv, torch
目前仅支持基础 ControlNet 预处理，扩展 Union ControlNet 需在此加新 processor
kernels
diffsynth_engine/kernels
仅 __init__.py		自定义 kernel 层（目前为空壳），为未来 Triton/CuTe kernel 预留入口
入口：需验证
依赖：需验证
当前所有 attention kernel 通过 utils/flag 动态选择第三方库（FA2/3/4、xformers、Sage），无自研 Triton kernel
examples
examples
约 30 个文件		示例与基准测试层，展示各模型用法、并行、LoRA、显存预测、性能基准
入口：flux_text_to_image.py, flux_parallel.py, wan_text_to_video.py, qwen_image_edit.py, model_perf_benchmark.py, memory_predict_model/
依赖：pipelines, configs
model_perf_benchmark.py 和 memory_predict_model/ 是性能工程师的核心参考
tests
tests
约 156 个文件（commit 热点第 2/4）		测试覆盖层，按 models/pipelines/algorithm/tokenizers/tools 分目录，共 156 个测试文件
入口：test_pipelines/test_flux_image.py, test_pipelines/test_wan_video.py, test_models/flux/test_flux_dit.py, test_algorithm/test_sampler.py
依赖：所有模块
tests/data/ 是热点（10 次），说明测试数据管理频繁变动；新模型接入必须同步加测试
目录树（按文件数）
  • diffsynth_engine/ 211 个文件
    __init__.py, algorithm, conf, configs, kernels, models, pipelines, processor, tokenizers, tools, utils
  • tests/ 156 个文件
    __init__.py, common, data, test_algorithm, test_models, test_pipelines, test_tokenizers, test_tools
  • examples/ 30 个文件
    flux_lora.py, flux_parallel.py, flux_text_to_image.py, input, memory_predict_model, model_benchmark_readme.md, model_perf_benchmark.py, odtsr_upscale_tool_example.py, qwen_image_edit.py, qwen_image_edit_2511.py, qwen_image_eligen.py, qwen_image_parallel.py, sdxl_text_to_image.py, wan_dmd_image_to_video.py
  • assets/ 3 个文件
    dingtalk.png, showcase.jpeg, tongyi.svg
  • docs/ 2 个文件
    tutorial.md, tutorial_zh.md
  • .gitattributes/ 1 个文件
  • .github/ 1 个文件
    workflows
  • .gitignore/ 1 个文件
  • .pre-commit-config.yaml/ 1 个文件
  • LICENSE/ 1 个文件
  • MANIFEST.in/ 1 个文件
  • README.md/ 1 个文件
  • pyproject.toml/ 1 个文件
  • setup.py/ 1 个文件

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

一次典型推理请求（以 Flux 文生图为例）的数据流如下：(1) 用户调用 FluxImagePipeline.from_pretrained(config)，config 是 FluxPipelineConfig dataclass，包含 model_path、model_dtype、device、offload_mode、dit_attn_impl、parallelism 等；(2) from_pretrained 内部通过 loader.py 从 HuggingFace/ModelScope 下载或缓存模型权重（safetensors/gguf），然后按 FluxStateDicts 定义的 key 映射分别实例化 flux_dit.py（FluxDiT）、flux_text_encoder.py（CLIP/T5）、flux_vae.py（AutoencoderKL），每个模型继承 PreTrainedModel，其构造函数根据 OptimizationConfig 决定是否启用 fp8_linear（FP8 线性层替换）和 fbcache（First Block Cache）；(3) 用户调用 pipe(prompt="a cat")，进入 BasePipeline.__call__，先通过 tokenizers/ 对 prompt 编码得 text_embeddings，再通过 utils/parallel.py 按 ParallelConfig（SP-Ulysses/Ring、TP、FSDP、CFG-Parallel）切分输入；(4) 进入采样循环，由 algorithm/sampler/（如 flow_match_euler.py）与 algorithm/noise_scheduler/（如 recifited_flow.py）协同，每一步调用 FluxDiT.forward，内部通过 models/basic/attention.py 的 Attention 类执行 self-attention（根据 AttnImpl 选择 FA2/3/4/xformers/SDPA/Sage/Sparge/VSA），utils/offload.py 在步骤间将非活跃子模型 offload 到 CPU 或磁盘；(5) 采样完成后，latent 送入 flux_vae.py 解码，经 utils/image.py 后处理返回 PIL Image。关键调度点：from_pretrained 的模型组装、__call__ 的并行分发、采样循环中的 offload 切换、Attention 后端动态选择。关键数据结构：*PipelineConfig（配置）、BaseStateDicts（权重映射）、PreTrainedModel（模型基类）、Attention（注意力原语）、LoRA（LoRA 融合模块）。

1构建配置FluxPipelineConfig.basic_config · diffsynth_engine/configs/pipeline.py2加载模型FluxImagePipeline.from_pretrained · diffsynth_engine/pipelines/flux_image.py3编码 prompttokenizers/clip.py · diffsynth_engine/tokenizers/clip.py4并行分发parallel.py · diffsynth_engine/utils/parallel.py5采样循环flow_match_euler.py · diffsynth_engine/algorithm/sampler/flow_match/flow_match_eul6DiT forwardFluxDiT · diffsynth_engine/models/flux/flux_dit.py7Attention 计算Attention · diffsynth_engine/models/basic/attention.py8VAE 解码flux_vae.py · diffsynth_engine/models/flux/flux_vae.py9返回图像BasePipeline.__call__ · diffsynth_engine/pipelines/base.py

关键类型与函数

名称路径用途
BasePipelinediffsynth_engine/pipelines/base.py
FluxImagePipelinediffsynth_engine/pipelines/flux_image.py
WanVideoPipelinediffsynth_engine/pipelines/wan_video.py
PreTrainedModeldiffsynth_engine/models/base.py
StateDictConverterdiffsynth_engine/models/base.py
Attentiondiffsynth_engine/models/basic/attention.py
AttnImpldiffsynth_engine/configs/pipeline.py
FluxPipelineConfigdiffsynth_engine/configs/pipeline.py
OptimizationConfigdiffsynth_engine/configs/pipeline.py
ParallelConfigdiffsynth_engine/configs/pipeline.py
offloaddiffsynth_engine/utils/offload.py
flagdiffsynth_engine/utils/flag.py
VideoSparseAttentiondiffsynth_engine/models/basic/video_sparse_attention.py
LoRAdiffsynth_engine/models/basic/lora.py
fp8_lineardiffsynth_engine/utils/fp8_linear.py

扩展点

最近在动的地方

建议阅读顺序

  1. diffsynth_engine/pipelines/base.py
  2. diffsynth_engine/pipelines/flux_image.py
  3. diffsynth_engine/configs/pipeline.py
  4. diffsynth_engine/models/base.py
  5. diffsynth_engine/models/flux/flux_dit.py
  6. diffsynth_engine/models/basic/attention.py
  7. diffsynth_engine/utils/offload.py
  8. diffsynth_engine/utils/parallel.py
  9. diffsynth_engine/algorithm/sampler/flow_match/flow_match_euler.py
  10. diffsynth_engine/models/wan/wan_dit.py

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

安装

  1. # 1. 克隆仓库 git clone https://github.com/modelscope/diffsynth-engine.git && cd diffsynth-engine # 2. 创建虚拟环境（Apple Silicon 推荐 Python 3.10–3.12） python3 -m venv .venv && source .venv/bin/activate # 3. 安装 PyTorch（仅 CPU/MPS 版本，无 CUDA） pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu # 4. 安装核心依赖（跳过 yunchang，因其仅 Linux 平台可用） pip install numpy safetensors gguf einops ftfy regex sentencepiece tokenizers modelscope flufl.lock scipy torchsde pillow imageio[ffmpeg] onnxruntime opencv-python moviepy librosa scikit-image trimesh # 5. 以可编辑模式安装 diffsynth-engine pip install -e . # 6. 开发模式（可选，用于跑测试） pip install -e '.[dev]' # 注意：以下依赖在 Apple Silicon 上无法使用，需跳过或忽略： # - flash_attn / flash_attn_interface / flash_attn.cute（仅 CUDA GPU） # - xformers（仅 CUDA GPU） # - sageattention / spas_sage_attn（仅 CUDA GPU） # - aiter（仅 AMD/ NVIDIA GPU） # - yunchang（仅 Linux） # - nvidia-nccl（仅 NVIDIA GPU）

哪些路径能真跑

['# 可在 CPU / MPS 上执行的代码路径（无需 GPU）：\n\n# 1. 算法层（纯 Python，无 CUDA 依赖）\n- diffsynth_engine/algorithm/noise_scheduler/ # noise scheduler 实现\n- diffsynth_engine/algorithm/sampler/ # sampler 实现\n\n# 2. Tokenizers（纯 CPU）\n- diffsynth_engine/tokenizers/ # CLIP/T5/Qwen2/Wan tokenizer\n\n# 3. 配置层\n- diffsynth_engine/configs/ # 所有 dataclass 配置\n\n# 4. 处理器\n- diffsynth_engine/processor/ # Canny/Depth 等前置处理器\n\n# 5. 部分工具函数\n- diffsynth_engine/utils/image.py # 图像处理\n- diffsynth_engine/utils/video.py # 视频处理\n- diffsynth_engine/utils/prompt.py # prompt 处理\n- diffsynth_engine/utils/memory/ # 内存预测模型\n\n# 需要 Colab T4 GPU 验证的路径：\n- diffsynth_engine/models/ # 所有 DiT/UNet/VAE 模型\n- diffsynth_engine/pipelines/ # 所有推理管线\n- diffsynth_engine/models/basic/attention.py # Flash Attention / xformers\n- diffsynth_engine/tools/ # 推理工具\n- examples/ # 所有示例脚本']

最小可运行

  1. # 1. 测试 noise scheduler（纯 CPU，无需 GPU） python -c " from diffsynth_engine.algorithm.noise_scheduler.flow_match import FlowMatchScheduler scheduler = FlowMatchScheduler() print('FlowMatchScheduler initialized:', scheduler) " # 2. 测试 sampler（纯 CPU，无需 GPU） python -c " from diffsynth_engine.algorithm.sampler.flow_match import FlowMatchEulerSampler sampler = FlowMatchEulerSampler() print('FlowMatchEulerSampler initialized:', sampler) " # 3. 测试 tokenizer（纯 CPU） python -c " from diffsynth_engine.tokenizers import CLIPTokenizer tokenizer = CLIPTokenizer() print('CLIPTokenizer initialized') " # 4. 测试配置加载（纯 CPU） python -c " from diffsynth_engine import FluxPipelineConfig config = FluxPipelineConfig.basic_config(model_path='test', device='cpu') print('Config created:', config) " # 5. 测试内存预测模型（纯 CPU） python examples/memory_predict_model/profile_model.py --model_path dummy_path # 6. 在 Colab T4 上验证完整推理流程（需 GPU） # python examples/flux_text_to_image.py --model_path /path/to/flux.safetensors --prompt 'a cat' --device cuda:0

测试

["# 测试框架：pytest\n# 测试目录：tests/（共 156 个测试文件）\n\n# 仅跑 CPU 子集（跳过需要 GPU 的测试）：\n\n# 1. 算法层测试（纯 CPU）\npytest tests/test_algorithm/ -v\n\n# 2. Tokenizer 测试（纯 CPU）\npytest tests/test_tokenizers/ -v\n\n# 3. 内存预测模型测试（纯 CPU）\npytest tests/test_tools/ -v -k 'not flux_tools' # flux_tools 需要 GPU\n\n# 估算耗时：\n# - test_algorithm: ~5–10 分钟（CPU）\n# - test_tokenizers: ~3–5 分钟（CPU）\n# - 完整测试套件需要 GPU，不可在本地运行\n\n# 跳过 GPU 测试的技巧：\n# 使用 pytest markers 或 conftest.py 中的 skipif 装饰器\n# 例如：pytest -m 'not gpu' 或查看 tests/common/test_case.py 中的设备检查逻辑"]

调试

CI

['# CI 系统：GitHub Actions\n# 配置文件：.github/workflows/\n\n# PR 会被以下检查卡住：\n# 1. Ruff linting（代码风格检查）\n# - 配置在 pyproject.toml 的 [tool.ruff] 部分\n# - 规则：E4, E7, E9, F（Pyflakes + 部分 pycodestyle）\n# - 行宽：120 字符\n\n# 2. 测试套件\n# - 需要 GPU 的测试在 CI 上会运行（有 GPU 环境）\n# - CPU 测试在 macOS/Linux runner 上运行\n\n# 3. pre-commit hooks\n# - .pre-commit-config.yaml 配置了提交前检查\n# - 运行 pre-commit install 启用\n\n# 本地验证 PR 前建议：\nruff check . # 代码风格检查\npytest tests/test_algorithm/ # 运行 CPU 测试\npytest tests/test_tokenizers/ # 运行 tokenizer 测试\npre-commit run --all-files # 运行所有 pre-commit 检查']

坑

四、维护者与社区

Release 节奏约 2–3 周一版，最近三个 release 日期分别为 v0.7.0 2026-01-19、v0.6.0 2025-09-09、v0.5.0 2025-08-27；commit 热点集中在 2026 年 1–5 月，2026-05-27 仍有 docs review 提交，说明 2025 下半年到 2026 上半年是高频迭代期，但 2026 年下半年（pushed_at 2026-09-03）未见新 release，可能进入平台期或内部开发阶段。

谁角色依据
Zhipeng Di (dipeng)核心作者 / 架构师README citation 列为第一作者；多篇 commit 与 PR 涉及架构级改动。
Guoxuan Zhu核心作者README citation 列为作者之一。
Zhongjie Duan核心作者README citation 列为作者之一。
Zihao Chu核心作者README citation 列为作者之一。
Yingda Chen核心作者README citation 列为作者之一。
Weiyi Lu核心作者README citation 列为作者之一。
ModelScope / MuseAI 团队维护者与发布方pyproject.toml authors 字段写 'MuseAI x ModelScope'；仓库归属 modelscope；联系邮箱 muse@alibaba-inc.com。

流程与 Review 风格

README 的 Contributing 节写明：pip install -e '.[dev]' + pre-commit install，并 TODO 指向 CONTRIBUTING.md（实际仓库中 CONTRIBUTING.md 为空文件，说明贡献指南尚未落地）。pyproject.toml 配置了 ruff（line-length 120，select E4/E7/E9/F）作为 lint/format 工具；.pre-commit-config.yaml 存在，说明 pre-commit 钩子是期望流程。无 CLA/DCO 文件。建议先开 Issue 描述方案再提 PR，因为已有 PR 标题带 'Refactor/'、'feat(npu):'、'fix:' 前缀，说明约定式提交被鼓励。

从可见 PR 推断：(1) 接受带 scope 前缀的 PR 标题（如 feat(npu):、fix(wan_s2v_dit):、performance(ring para):）；(2) 有 review 后修改痕迹——commit 'docs: address review — add methods, drop trailing whitespace' 直接说明 review 反馈被逐条响应；(3) 响应速度中等，Issue #221 2026-01-07 提，PR #250 在 2026-01-29 之前合入；(4) 对 bug fix 接受度快（如 #231、#230 同日双 fix）。但 2026 年下半年无新 release，review 活跃度可能下降。

渠道

这里的规矩

维护者现在最想要的帮助

五、切入方案

建议长期负责：diffsynth_engine/utils/ 模块 + algorithm 层的跨平台兼容性与测试覆盖
utils/ 是跨硬件兼容的关键层（offload、parallel、fp8_linear、memory、platform），algorithm 层（sampler/scheduler）是纯 Python 实现。两者均不依赖 CUDA kernel，可在 CPU/MPS 上完整开发与测试。该模块连接模型层与执行层，长期负责可深入理解整个引擎的调度逻辑，是通向核心维护者的合理路径。

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

缺口依据为什么是你
kernels/ 目录为空壳，缺少原生 CPU/MPS 友好的参考 kernel 实现diffsynth_engine/kernels/ 目录下仅有 __init__.py，无任何实际 kernel 实现；README 声称支持 Apple Silicon，但 attention 实现在无 CUDA 时仅回落到 eager 路径。候选人在无 GPU 条件下仍可编写纯 PyTorch 参考实现（如 fused softmax、tiled matmul、grouped GEMM 的 CPU 版本），为 Apple Silicon 用户提供可用的 fallback，并作为 Triton/CUDA kernel 的对照基准。
缺少 Apple Silicon / CPU 的 CI 测试覆盖tests/ 下有 156 个测试文件，但 runbook 显示大部分测试依赖 CUDA GPU；.github/workflows 下未找到 Apple Silicon 或 CPU-only 的 CI 配置。候选人可在本地 MacBook Air 上运行现有纯 Python 测试（algorithm、tokenizers、configs），并补充 MPS/CPU 兼容的测试用例，无需 GPU 即可贡献 CI 改进。
sampler/scheduler 缺乏数值精度与 diffusers 的对照测试tests/test_algorithm/ 下仅有 test_sampler.py 和 test_scheduler.py，diffsynth-engine 刻意不依赖 k-diffusion/sgm，但未提供与参考实现的数值对齐验证。候选人可在 CPU 上运行 sampler 的数值对比（与 diffusers 0.31.0 的输出做 MSE 验证），这是纯 Python 工作，无需 GPU。
缺少模型加载/推理的内存预测基准与文档examples/memory_predict_model/ 下有 profile_model.py 和 train_model.py，utils/memory/ 下有 memory_predcit_model.py，但 README 和 docs 中未提及内存预测的使用方法。候选人可在 CPU 上运行内存预测脚本，生成文档和示例，帮助用户理解模型显存需求，无需 GPU。
tools/ 模块缺少单元测试覆盖tests/test_tools/ 下仅有 test_flux_tools.py，而 tools/ 目录下有 FluxInpaintingTool、FluxOutpaintingTool、FluxIPAdapterRefTool、FluxReduxRefTool、FluxReplaceByControlTool、QwenImageUpscalerTool 等多个工具类。候选人为未覆盖的工具类补充单元测试，验证接口契约和参数校验逻辑，无需 GPU 即可执行。
configs 模块缺少配置验证与序列化测试configs/ 下有大量 dataclass（FluxPipelineConfig、WanPipelineConfig 等），但 tests/ 下未见 test_configs.py 或类似测试文件。候选人可补充配置的字段校验、默认值、序列化/反序列化测试，这是纯 Python 工作，完全无 GPU 依赖。
缺少端到端的 CPU/MPS 推理示例与文档examples/ 下 30 个示例均假设 CUDA 设备（device="cuda"），README 的 Quick Start 也仅展示 CUDA 用法，尽管声称支持 Apple Silicon。候选人可编写 device="mps" 或 device="cpu" 的示例脚本，并在 docs/tutorial.md 中添加 Apple Silicon 使用说明，无需 GPU。
缺少性能基准脚本与回归测试examples/model_perf_benchmark.py 存在，但未集成到 CI，且缺乏标准化的基准输出格式和回归对比机制。候选人可在 CPU 上运行基准脚本，建立基线数据，并设计轻量级回归检测（如推理步时延阈值），无需 GPU。

第 1–30 天：看懂并露面

第 31–60 天：稳定产出

第 61–90 天：接管一块

第一批 PR

题目范围为什么安全
docs: add Apple Silicon installation guide and CPU usage examplesREADME.md、docs/tutorial.md、新增 examples/text_to_image_cpu.py纯文档和示例代码，不涉及核心逻辑修改；参照 commit db0f911、ff33f33 的 docs 修复先例，风险极低。
test: add unit tests for FluxOutpaintingTool and QwenImageUpscalerTooltests/test_tools/ 下新增测试文件新增测试文件，不修改现有代码；使用 mock 或最小输入验证接口契约，无需 GPU 即可运行。
test: add config validation tests for FluxPipelineConfig and WanPipelineConfigtests/test_configs.py（新建）纯测试代码，验证 dataclass 的默认值和字段类型；不触及运行时逻辑，失败不影响现有功能。
test: add numerical alignment test for FlowMatchEuler sampler against diffuserstests/test_algorithm/test_sampler_numerical.py（新建）新增测试，使用 diffusers 0.31.0（已在 dev dependencies 中）作为参考；仅在 CPU 上运行，不修改 sampler 实现。
docs: add memory prediction usage guide and improve docstrings in utils/memory/README.md、utils/memory/memory_predcit_model.py文档和 docstring 改进，不改变代码行为；memory_predcit_model.py 可在 CPU 上验证示例。

怎么知道自己站住了

风险与对策
  • 项目 2026 年下半年无新 Release（pushed_at 2026-09-03，最后 Release 为 2026-01-19），可能进入维护低谷。：关注 commit 活动（2026-05-27 仍有 docs review），优先做文档和测试贡献，即使合并周期长也能积累可见度。
  • 核心开发团队（ModelScope/MuseAI）可能更关注 CUDA 性能优化，对 CPU/MPS 改进优先级低。：用 Issue 数据说话（统计 Apple Silicon 相关 Issue 数量），展示用户需求；将 CPU 改进包装为'参考实现/对照基准'，服务 CUDA 开发。
  • 无 GPU 条件下无法验证 CUDA kernel 相关改动，贡献范围受限。：聚焦纯 Python 层（algorithm、utils、configs、tests），利用 Colab T4 做最终确认（每次几十分钟），将 CUDA 相关 PR 留给有 GPU 的合作者。
  • tests/test_pipelines/ 下大量测试需要真实模型权重（如 test_flux_image.py），无法在 CPU 上完整运行。：使用 mock 或小模型（如 tests/data/ 下的 fixture）替代；优先运行 tests/test_algorithm/、tests/test_tokenizers/、tests/test_tools/ 等不依赖大模型的测试。
  • CONTRIBUTING.md 为空，社区规范不明确，PR 风格可能与维护者预期不符。：严格遵循现有代码风格（ruff line-length 120）、commit message 格式（如 'docs:'、'test:'、'fix:' 前缀）；首个 PR 选择最小改动，观察 reviewer 反馈后再扩大范围。
  • diffusers 版本锁定为 0.31.0（pyproject.toml dev dependencies），数值对照测试可能因版本差异产生误导。：在测试中明确记录 diffusers 版本；使用 try-except 跳过 diffusers 未安装时的测试，避免硬依赖。
  • Apple Silicon 的 MPS 后端在 PyTorch 中仍有兼容性问题（如某些 op 不支持）。：在文档中明确标注已知限制；提供 device 参数化示例，让用户自行选择 cpu/mps/cuda；在 tests/ 中添加 MPS 可用性检测（torch.backends.mps.is_available()）。
  • 项目依赖的第三方库（如 yunchang 仅 Linux）可能导致跨平台开发环境不一致。：按 runbook 跳过平台特定依赖；在 pyproject.toml 中验证 sys_platform 条件是否正确配置；在 CI 中测试多平台安装。

六、怎么介入这个项目

建议顺序

成为长期维护者的路径
  • diffsynth_engine/utils/ 与 configs 层（跨平台兼容性核心）
  • diffsynth_engine/algorithm/ 数值正确性（sampler/scheduler 验证）
  • tests/ 基建（提升 CI 覆盖与回归防护）

七、任务卡

任务 1优先 · medium · CPU · 2 个晚上

为 FlowMatchEuler sampler 添加与 diffusers 的数值对齐测试（CPU）

Issue #199 · Pytorch version problem ↗

无人认领6 条评论更新 2026-02-03

用到的专长：利用算子数值正确性验证的专长，在 CPU 上建立 sampler 的参考实现对照。

目标：在 tests/test_algorithm/test_sampler_numerical.py（新增）中实现 FlowMatchEuler sampler 与 diffusers 0.31.0 的逐步数值对比，确保 MSE < 1e-5，纯 CPU 运行。

为什么值得长期做：README 明示 sampler/scheduler 是刻意重新实现的核心组件，缺少与参考实现的数值对齐验证；补上这条防线是长期维护 algorithm 层的前提，也是后续性能优化的可信基线。

怎么介入：Issue #199 当前有 6 条评论但无 assignee 且无 open PR，问题聚焦在 torch 2.9 兼容性，但同 Issue 可作为引入数值对齐测试的切入点；建议在 Issue 中说明计划添加 sampler 数值对齐测试以提升跨平台兼容性信心。
第一个 PR 的边界：仅新增 tests/test_algorithm/test_sampler_numerical.py 与可能的 conftest 调整，不修改任何 sampler 实现代码。
第一步：在本地 Mac 上用 pip install -e '.[dev]' 安装，阅读 diffsynth_engine/algorithm/flow_match/flow_match_euler.py 与 diffusers 0.31.0 的 FlowMatchEulerDiscreteScheduler.step() 实现，梳理输入参数映射。
本机怎么复现 / 验证：在 Mac 上 pip install -e '.[dev]' 后运行 pytest tests/test_algorithm/test_sampler.py -v 确认现有测试结构，然后用 python -c "from diffusers import FlowMatchEulerDiscreteScheduler; print(diffusers.__version__)" 确认参考实现可用。
认领留言（英文，可直接贴到 Issue）
I'd like to add numerical alignment tests for the FlowMatchEuler sampler against diffusers 0.31.0. The plan: create tests/test_algorithm/test_sampler_numerical.py that runs both implementations step-by-step on CPU and verifies MSE < 1e-5. This would catch regressions when updating torch/diffusers versions (related to the compatibility issues in this thread). Before I start: should I pin diffusers==0.31.0 in dev dependencies, and would you prefer a single PR covering all samplers or start with just FlowMatchEuler? ETA: 2 evenings.
大致实施方案
    可能涉及的目录或文件
    • diffsynth_engine/algorithm/flow_match/flow_match_euler.py
    • diffsynth_engine/algorithm/noise_scheduler/
    • tests/test_algorithm/test_sampler.py（参考现有测试结构）
    • 新增 tests/test_algorithm/test_sampler_numerical.py
    验收方式
    • pytest tests/test_algorithm/test_sampler_numerical.py -v 在 Mac CPU 上通过
    • 测试应覆盖多组 timestep 与 sigma 组合，报告 MSE
    • CI 中新增的测试可在无 GPU 环境下运行
    开工前问题与风险

    向维护者确认

    • 维护者希望对齐的 diffusers 版本是否固定为 0.31.0（当前 dev dependencies 中已有）？
    • 是否接受在 CI 中新增 diffusers 作为测试依赖？
    • 对齐测试应覆盖哪些 sampler（仅 FlowMatchEuler 还是扩展到 DPMSolver/DEIS）？

    风险

    • diffusers 版本升级可能导致数值漂移，需在测试中固定版本或设置合理容差
    • FlowMatchEuler 实现细节（如 scaling 方式）可能与 diffusers 存在设计差异，需提前确认
    任务 2优先 · medium · CPU · 1 个晚上

    修复 utils/parallel.py 对 torch 2.9 的兼容性（纯逻辑层）

    Issue #199 · Pytorch version problem ↗

    无人认领6 条评论更新 2026-02-03

    用到的专长：利用 CUDA 分布式训练与并行策略的经验，快速定位 torch API 变更并设计兼容层。

    目标：将 from torch.distributed.tensor.parallel._utils import _validate_tp_mesh_dim 替换为 torch 2.9 兼容的导入路径或内联实现，确保在 torch 2.6–2.9 范围内均可导入。

    为什么值得长期做：utils/parallel.py 是跨硬件并行的基础设施，torch 2.9 兼容性问题是真实用户痛点（6 条评论）；修复此问题直接影响仓库的 PyTorch 版本支持声明。

    怎么介入：Issue #199 无 assignee、无 open PR，6 条评论均为问题报告，适合直接认领修复；建议先留言确认兼容范围再动手。
    第一个 PR 的边界：仅修改 diffsynth_engine/utils/parallel.py 的导入逻辑 + 新增 tests/test_utils/test_parallel_import.py，不触及并行运行时逻辑。
    第一步：阅读 diffsynth_engine/utils/parallel.py 第 14 行的导入，查阅 torch 2.9 源码确认 _validate_tp_mesh_dim 的新位置或替代 API。
    本机怎么复现 / 验证：在 Mac 上 python -c "import torch; print(torch.__version__) 确认当前版本，然后 python -c "from diffsynth_engine.utils.parallel import _validate_tp_mesh_dim" 复现 ImportError。
    认领留言（英文，可直接贴到 Issue）
    I'll fix the torch 2.9 compatibility issue in utils/parallel.py. The import torch.distributed.tensor.parallel._utils was relocated/renamed in newer torch versions. My plan: detect the available location via try/except or version check, and add a fallback if needed. I'll also add a test to catch future regressions. Before I start: should I support torch 2.6–2.9 broadly, or is it acceptable to bump the minimum torch version? ETA: 1 evening.
    大致实施方案
      可能涉及的目录或文件
      • diffsynth_engine/utils/parallel.py
      • 新增 tests/test_utils/test_parallel_import.py（验证导入兼容性）
      验收方式
      • 在 Mac 上 python -c "from diffsynth_engine.utils.parallel import *; print('import OK') 通过
      • 若可安装多个 torch 版本，验证 2.6、2.7、2.8、2.9 均可导入
      • CI 中新增 torch 2.9 测试矩阵
      开工前问题与风险

      向维护者确认

      • 维护者是否希望支持 torch 2.6–2.9 的广泛兼容，还是仅修复 2.9 并升级最低版本要求？
      • _validate_tp_mesh_dim 在 torch 2.9 中是否已公开为 torch.distributed.tensor.parallel 的公开 API？

      风险

      • 若 _validate_tp_mesh_dim 在 torch 2.9 中被移除，需内联实现或寻找替代方案
      • 过度兼容代码可能增加维护负担
      任务 3可选 · low · CPU · 1 个晚上

      为 FluxOutpaintingTool / QwenImageUpscalerTool 补充单元测试

      Issue #238 · It is supported of the model wan2.2-fun-a14b-inp ? ↗

      无人认领1 条评论更新 2026-03-23

      用到的专长：利用端侧部署与工具链开发经验，为工具类建立可回归的测试基线。

      目标：在 tests/test_tools/ 下新增 test_qwen_image_upscaler_tool.py，验证 FluxOutpaintingTool 与 QwenImageUpscalerTool 的接口契约、参数校验逻辑，使用 mock 输入避免 GPU 依赖。

      为什么值得长期做：tools/ 模块是后处理扩展点，ODTSR upscaler 是 v0.7.0 新功能；缺少单元测试意味着接口契约未锁定，后续重构风险高。

      怎么介入：Issue #238 本身是关于新模型支持的问题，但与 tools 模块测试无直接关联；建议直接在 Issue 中说明计划为 tools 模块补充测试，或先开新 Issue 提案。
      第一个 PR 的边界：仅新增 tests/test_tools/test_qwen_image_upscaler_tool.py（及可能的 test_flux_outpainting_tool.py），不修改 tools/ 实现。
      第一步：阅读 diffsynth_engine/tools/ 下 FluxOutpaintingTool、QwenImageUpscalerTool 的 __call__ 签名与参数，设计最小 mock 输入（如随机 tensor）。
      本机怎么复现 / 验证：在 Mac 上 pytest tests/test_tools/test_flux_tools.py -v 确认现有测试可运行，然后阅读 diffsynth_engine/tools/qwen_image_upscaler_tool.py 确认 __call__ 签名。
      认领留言（英文，可直接贴到 Issue）
      I noticed that tests/test_tools/ only covers FluxInpaintingTool. I'd like to add unit tests for FluxOutpaintingTool and QwenImageUpscalerTool to lock in their interface contracts. The tests will use mock inputs and run on CPU only. Before I start: is it acceptable to test these tools without loading full model weights (using mock tensors)? ETA: 1 evening.
      大致实施方案
        可能涉及的目录或文件
        • diffsynth_engine/tools/flux_outpainting_tool.py
        • diffsynth_engine/tools/qwen_image_upscaler_tool.py
        • tests/test_tools/test_flux_tools.py（参考现有结构）
        • 新增 tests/test_tools/test_qwen_image_upscaler_tool.py
        验收方式
        • pytest tests/test_tools/ -v 在 Mac CPU 上通过
        • 测试覆盖：输入形状校验、参数边界、返回类型
        • mock 输入确保无 GPU 依赖
        开工前问题与风险

        向维护者确认

        • 维护者是否期望工具类测试覆盖完整的端到端调用（需要 GPU）还是仅验证接口契约？
        • QwenImageUpscalerTool 是否已有内部逻辑可独立于模型权重测试？

        风险

        • 工具类可能强依赖模型加载，需确认是否可 mock 或跳过模型权重
        • 测试可能因接口变更频繁而需要维护
        任务 4可选 · low · CPU · 1 个晚上

        为 FluxPipelineConfig / WanPipelineConfig 添加配置验证测试

        Issue #224 · MAC Ultra pipe.load_lora raise an error "AttributeError: QwenImageDiT has no attribute diffusion_model" ↗

        无人认领2 条评论更新 2026-01-19

        用到的专长：利用训练框架配置管理经验，为 dataclass 配置建立验证基线。

        目标：新建 tests/test_configs.py，验证 FluxPipelineConfig、WanPipelineConfig、QwenImagePipelineConfig 的字段默认值、类型校验、序列化/反序列化正确性。

        为什么值得长期做：configs/ 是每次新模型扩展的必经入口，缺少配置验证意味着字段错误只能在运行时暴露；补上测试是长期维护基础设施的关键。

        怎么介入：Issue #224 聚焦 LoRA 加载 bug，但同属 configs/models 交互问题；建议先开新 Issue 或在 #224 中补充说明计划添加配置测试。
        第一个 PR 的边界：仅新增 tests/test_configs.py，不修改 configs/ 实现代码。
        第一步：阅读 diffsynth_engine/configs/pipeline.py 中各 Config dataclass 的字段定义，使用 pytest + dataclasses.fields 编写验证逻辑。
        本机怎么复现 / 验证：在 Mac 上 python -c "from diffsynth_engine.configs import FluxPipelineConfig; c = FluxPipelineConfig.basic_config(); print(c)" 确认可实例化，然后编写测试。
        认领留言（英文，可直接贴到 Issue）
        I'd like to add unit tests for FluxPipelineConfig, WanPipelineConfig, and QwenImagePipelineConfig to validate field defaults, types, and serialization. This would catch config-related issues like the one reported in #224 earlier. The tests will be pure Python and run on CPU. Before I start: would you prefer validation logic in __post_init__ or just test coverage? ETA: 1 evening.
        大致实施方案
          可能涉及的目录或文件
          • diffsynth_engine/configs/pipeline.py
          • 新增 tests/test_configs.py
          验收方式
          • pytest tests/test_configs.py -v 在 Mac CPU 上通过
          • 测试覆盖：默认值非 None、字段类型正确、必填字段缺失时报错
          • 序列化/反序列化 round-trip 测试
          开工前问题与风险

          向维护者确认

          • 维护者是否希望配置验证在 __post_init__ 中自动执行，还是仅通过测试覆盖？
          • 是否需要验证 configs 与 models 之间的字段映射一致性？

          风险

          • dataclass 字段变更频繁，测试可能需同步更新
          • 过度严格的测试可能阻碍快速迭代
          任务 5可选 · medium · Mac · 2 个晚上

          为 Issue #224 编写 LoRA 加载在 MPS 路径下的回归测试

          Issue #224 · MAC Ultra pipe.load_lora raise an error "AttributeError: QwenImageDiT has no attribute diffusion_model" ↗

          无人认领2 条评论更新 2026-01-19

          用到的专长：利用 LoRA 融合与模型加载的专长，定位属性路径问题并设计防护测试。

          目标：在 tests/test_pipelines/ 下新增 test_lora_loading_mps.py，验证 load_lora 在 QwenImageDiT 上的属性查找逻辑，使用最小 mock 模型避免 GPU 依赖。

          为什么值得长期做：#224 暴露了 LoRA 加载在 QwenImageDiT 上的属性路径问题；补上回归测试可防止未来模型接入时同类 bug 复发。

          怎么介入：Issue #224 无 assignee、无 open PR，2 条评论，适合认领；建议先留言确认根因定位情况，再决定是先修 bug 还是先加测试。
          第一个 PR 的边界：新增 tests/test_pipelines/test_lora_loading.py + 可能的 diffsynth_engine/models/base.py 或 qwen_image_dit.py 小改动，不涉及 pipeline 主逻辑重构。
          第一步：阅读 diffsynth_engine/pipelines/qwen_image.py 第 269 行与 diffsynth_engine/models/base.py 第 44 行，理解 get_submodule(key) 的失败路径。
          本机怎么复现 / 验证：在 Mac 上阅读 diffsynth_engine/pipelines/qwen_image.py 第 269 行与 models/base.py 第 44 行，用 python -c "from diffsynth_engine.models.qwen_image import QwenImageDiT; print(QwenImageDiT.__init__.__code__.co_varnames[:10])" 确认模型结构。
          认领留言（英文，可直接贴到 Issue）
          I'd like to investigate and fix the LoRA loading error on QwenImageDiT (#224). The error AttributeError: QwenImageDiT has no attribute 'diffusion_model' suggests the LoRA key path doesn't match the model structure. My plan: first add a regression test that reproduces the issue with a minimal mock model, then fix the attribute lookup logic. Before I start: has the root cause been identified elsewhere, or should I start from scratch? ETA: 2 evenings.
          大致实施方案
            可能涉及的目录或文件
            • diffsynth_engine/pipelines/qwen_image.py
            • diffsynth_engine/models/base.py
            • diffsynth_engine/models/qwen_image/qwen_image_dit.py
            • 新增 tests/test_pipelines/test_lora_loading.py
            验收方式
            • pytest tests/test_pipelines/test_lora_loading.py -v 在 Mac CPU 上通过
            • 测试应 mock QwenImageDiT 的最小结构，验证 load_lora 不抛出 AttributeError
            • 覆盖：fused=True/False、不同 scale 值
            开工前问题与风险

            向维护者确认

            • 维护者是否已定位 #224 的根因（QwenImageDiT 缺少 diffusion_model 属性）？
            • 是否需要在 QwenImageDiT 中添加 diffusion_model 属性还是修改 LoRA 加载逻辑？

            风险

            • 若根因未修复，回归测试会先失败，需确认是先修 bug 还是先加测试
            • mock 模型可能无法完全复现真实加载路径
            任务 6候补 · low · Mac · 1 个晚上

            文档：添加 Apple Silicon / CPU 使用示例与教程

            Issue #235 · Question about batch inference support ↗

            无人认领0 条评论更新 2026-02-12

            用到的专长：利用端侧部署与跨平台适配经验，为 Apple Silicon 用户提供可用入口。

            目标：新增 examples/text_to_image_mps.py 与 examples/text_to_image_cpu.py，并在 docs/tutorial.md 中添加 Apple Silicon 使用说明（安装、已知限制、fallback 行为）。

            为什么值得长期做：README 声称支持 Apple Silicon，但所有示例均为 device='cuda'；补充 CPU/MPS 示例是跨平台兼容性的门面，也是新用户入门的关键。

            怎么介入：Issue #235 是关于 batch inference 与 HTTP API 的问题，与文档无直接关联；建议先开新 Issue 提案或在社区讨论区询问是否接受 MPS 示例 PR。
            第一个 PR 的边界：新增 2 个示例文件 + docs/tutorial.md 更新，不修改任何实现代码。
            第一步：在 Mac 上运行现有 examples/flux_text_to_image.py 的 CPU 版本（修改 device='cpu'），记录可用性与性能瓶颈。
            本机怎么复现 / 验证：在 Mac 上 python -c "import torch; print(torch.backends.mps.is_available())" 确认 MPS 可用，然后 python examples/flux_text_to_image.py 修改 device='cpu' 测试。
            认领留言（英文，可直接贴到 Issue）
            I'd like to add Apple Silicon / CPU usage examples to improve cross-platform onboarding. The plan: create examples/text_to_image_mps.py and examples/text_to_image_cpu.py, and update docs/tutorial.md with MPS setup notes and known limitations. Before I start: would you prefer these examples in the examples/ folder or as part of the docs? Any specific limitations I should highlight? ETA: 1 evening.
            大致实施方案
              可能涉及的目录或文件
              • examples/flux_text_to_image.py（参考结构）
              • 新增 examples/text_to_image_mps.py
              • 新增 examples/text_to_image_cpu.py
              • docs/tutorial.md
              验收方式
              • 在 Mac 上 python examples/text_to_image_cpu.py 可运行并生成图像（可能很慢但不出错）
              • 文档说明清晰，包含已知限制（如 attention 后端回落 eager）
              开工前问题与风险

              向维护者确认

              • 维护者是否接受在示例中展示 CPU/MPS 的降级行为（如 slower but functional）？
              • 是否需要同步更新 README 的 Quick Start 部分？

              风险

              • CPU 推理可能极慢，需明确标注为开发/调试用途
              • MPS 后端可能有未列出的限制，需实际测试后如实记录