THU-MIG/edge-dit.cpp

一、项目定位

edge-dit.cpp 是清华大学 THU-MIG 团队发起的一个开源、DiT-first 的 C/C++ 原生推理引擎，专为在本地和资源受限设备上运行 Diffusion Transformer（DiT）而设计。它基于 ggml 张量/图运行时构建，目标是在没有 Python、没有 PyTorch 依赖的前提下，为 FLUX.1/FLUX.2、SD3/SD3.5、Qwen-Image、Wan 2.1、MiniMax-H3 等主流 DiT 模型族提供统一的 text-to-image、image editing、video generation 推理能力。项目通过 --auto-fit、layered offload、per-component offload、VAE tiling、离线 GGUF 量化（ed-convert + imatrix）以及 CUDA 专用算子（cuDNN SDPA、edge CUDA norm/RoPE/modulation、CUDA Graphs、SageAttention2 风格 INT8-QK 等）把 20GB+ 的大模型塞进 24GB 甚至更小的显存。 项目目前处于 alpha / public preview 阶段：README 顶部徽章明确标 status-alpha-orange，版本号 v0.1.0，README 声明 v0.x 的 API、ABI、CLI flags、HTTP schemas 公开但尚未稳定。从目录与提交热点看，src/dit_models（39 次提交）和 src/core（12 次）是最活跃区域，bindings/python（8 次）、examples/server（7 次）紧随其后，说明团队正在快速扩展模型覆盖与对外接口。最近提交集中在 LTX-2.3 视频/音频管线、MiniMax-H3 性能数据、FLUX latent channels 修复等，属于功能扩展与性能打磨并行期。 与同类项目的关系：它站在 ggml 之上，借鉴 stable-diffusion.cpp 的 DiT 实现思路，但把重心放在 DiT 原生支持、多后端（CUDA first-class，CPU/Metal/Vulkan 可选）以及面向边缘设备的显存-精度自动调度上，是「llama.cpp / sd.cpp 生态里专门做 DiT 的那一支」。

解决什么问题、给谁用

解决的核心问题是：主流 DiT 模型（FLUX、SD3、Qwen-Image、Wan、MiniMax-H3 等）在本地和资源受限设备上推理时面临的显存爆炸、加载慢、依赖重、跨模型/跨任务需要多套工具链的痛点。具体表现为——大模型无法常驻 24GB 以下显存；PyTorch/Diffusers 运行时对边缘部署不友好；不同 DiT 家族需要各自专用推理栈；few-step distilled 模型缺乏自动调度；端侧（CPU/Metal/Vulkan）缺少统一的 DiT 运行时。 目标用户与典型场景： - 端侧/边缘部署工程师：需要在笔记本、嵌入式设备、Mac（Metal）、非 NVIDIA GPU（Vulkan）上跑 FLUX/SD3/Qwen-Image，要求无 Python、显存可控、可离线量化。 - 扩散模型应用开发者：通过 C API、CLI、HTTP server、Python bindings 把 DiT 推理嵌入产品，覆盖 t2i、editing、video 三类任务。 - 推理性能/系统优化工程师：研究 offload 策略、算子融合、并行执行（CFG/sequence parallelism、NCCL/MPI 多 worker）、量化对质量的影响。 - 学术/工业研究员：复现、对比不同 DiT 模型在统一运行时下的速度、显存、图像质量（benchmark/ 目录提供了完整的评测框架）。

同类项目与差别

• stable-diffusion.cpp (leejet/stable-diffusion.cpp)：edge-dit.cpp 直接参考其 DiT 实现，但 sd.cpp 更偏 UNet + 传统扩散模型（SD1.5/SDXL），DiT 是后来加入；edge-dit.cpp 以 DiT 为第一公民，提供更系统的 DiT 显存调度（auto-fit、layered offload）和更多 DiT 家族（FLUX.2、Qwen-Image、MiniMax-H3）的原生支持。
• llama.cpp / ggml：edge-dit.cpp 基于 ggml 作为底层张量/图运行时，复用其多后端（CUDA/Metal/Vulkan/OpenCL/SYCL/HIP）和 GGUF 生态；但 ggml 本身不感知 DiT 语义，edge-dit.cpp 在之上构建了 DiT 专用算子、调度逻辑和模型族适配层。
• HuggingFace Diffusers (PyTorch)：Diffusers 是 Python/PyTorch 生态的事实标准，功能最全但运行时重、对边缘部署不友好；edge-dit.cpp 用纯 C/C++ 复现其子集（FLUX、SD3、Qwen-Image、Wan、MiniMax-H3），在 4090/H200 上 DiT 采样速度普遍快于 Diffusers w8，且峰值 VRAM 更低，但模型覆盖与灵活性不及 Diffusers。
• ComfyUI (前端) + 各后端：ComfyUI 是节点式工作流前端，依赖 Diffusers 等后端；edge-dit.cpp 是底层引擎，提供 C API/HTTP server/Python bindings 可被类似前端集成，但不提供可视化工作流。
• NVIDIA TensorRT / TensorRT-LLM：TensorRT 专注 NVIDIA 平台的极致推理优化，需逐模型构建 engine；edge-dit.cpp 追求跨平台（CUDA/Metal/Vulkan/CPU）和免编译的 GGUF 加载，优化粒度更偏系统级调度而非单算子极致融合。

核心能力

阶段：alpha / public preview（v0.1.0，2026-07-11 公开预览；README 徽章 status-alpha-orange；v0.x API/ABI/CLI/HTTP 公开但不稳定；Metal 标 Experimental，Vulkan 标 Functional 但部分模型仍在优化）

技术栈：C11 / C++17；ggml（third_party/ggml，作为底层张量/图运行时，通过 git submodule 引入）；CMake >= 3.20 构建系统；CUDA/cuDNN/NCCL（可选，用于 CUDA 后端与分布式）；oneDNN（third_party/onednn，可选，CPU bf16 AMX matmul 加速）；Vulkan / Metal / OpenCL / SYCL / HIP（通过 ggml 后端可选）；nlohmann/json、cpp-httplib、stb_image_resize/write（third_party/）；Python bindings（bindings/python/）；GitHub Actions CI（.github/workflows）

规模：版本 v0.1.0-alpha（2026-07-11 公开预览）；最近推送 2026-09-01；根目录含 17 个顶级目录；benchmark/ 123 文件；bindings/ 110 文件；docs/ 22 文件；src/ 220 文件；third_party 含 ggml、onednn、httplib.h、json.hpp、stb 等；提交热点集中在 src/dit_models（39）、src/core（12）、bindings/python（8）、examples/server（7）；无 Release 记录（releases 为空数组）；README 显示 4090/H200 多模型 benchmark 数据；star 数未提供（需验证）。

二、架构与代码地图

edge-dit.cpp 的代码组织可以清晰地划分为五层，自顶向下分别是： 1. 接入层（Access Layer） 负责对外暴露统一接口，包括 CLI（examples/cli/main.cpp、examples/cli/sample_main.cpp、examples/cli/convert_main.cpp）、原生 HTTP 服务器（examples/server/main.cpp、examples/server/routes.cpp、examples/server/runtime.cpp）、C API（include/edge-dit.h）以及 Python 绑定（bindings/python/src/edge_dit/ 下的 engine.py、server.py、_capi.py、config.py 等）。这一层把用户请求翻译成内部参数结构 ed_ctx_params_t / ed_image_generation_params_t / ed_video_generation_params_t，然后交给调度层。 2. 调度层（Scheduling Layer） 核心是 src/core/runtime/edge_dit_engine.cpp 中的 EdgeDitEngine 类，它持有 ModelRuntime、ModelLoader、DiTPipeline 和 ParallelContext，负责初始化后端、加载模型、选择 pipeline、驱动生成循环。ModelRuntime（src/core/runtime/model_runtime.cpp）封装 ggml 后端初始化、设备选择（CUDA/CPU/Metal/Vulkan）、per-component backend 分配（RuntimeBackends）以及 GenerationControl 状态机。ModelLoader（src/core/runtime/model_loader.cpp）负责从 Diffusers 目录、safetensors、GGUF 等格式读取权重并映射到 ggml tensor。 3. 执行层（Execution Layer） 以 src/dit_models/pipelines/ 下的各 pipeline 实现为中心：FluxPipeline、FluxKontextPipeline、SD3Pipeline、QwenImagePipeline、QwenImageEditPipeline、WanPipeline、LTX2Pipeline、MiniMaxH3Pipeline，它们都继承自 DiTPipeline 基类（src/dit_models/pipelines/dit_pipeline.hpp）。每个 pipeline 内部组合了 diffusion transformer（src/dit_models/models/）、text encoder（CLIP/T5/LLM）、VAE、conditioner、scheduler 等组件，并通过 ggml 计算图执行去噪循环。src/core/optimization/cache/ 提供了 timestep/block 级别的计算复用（DiCache、EasyCache、MagCache、SageCache、TaylorSeer、UCache 等策略）。 4. Kernel 层（Kernel Layer） 包含 ggml 后端的扩展算子：src/core/backend/ggml/cuda/ 下的 ed_cuda_norm.cu、ed_cuda_rope.cu、ed_cuda_modulation.cu、ed_cuda_attention_v_prep.cu、ed_cuda_sage_attn.cu、ed_cuda_sp_flux.cu、ed_async_offload.cu，以及 src/core/backend/cuDNN/ 下的 ed_cudnn_sdpa.cu、ed_cudnn_conv2d.cu、ed_cudnn_conv3d.cu、ed_cudnn_conv_transpose_1d.cu。这些是 CUDA 性能的关键路径，通过 CMake 选项 ED_ENABLE_CUDA_NORM、ED_ENABLE_CUDA_ROPE、ED_ENABLE_CUDA_MODULATION、ED_ENABLE_CUDA_GRAPHS、ED_ENABLE_CUDA_SAGE_ATTN、ED_ENABLE_CUDNN_SDPA 控制。src/core/backend/ggml/ggml_graph_cut.cpp 实现了 layered offload 所需的图切割。 5. 工具层（Tooling Layer） 包括离线量化工具 src/utils/model_io/（convert.cpp、gguf_io.cpp、safetensors_io.cpp、pickle_io.cpp、torch_legacy_io.cpp、torch_zip_io.cpp）、imatrix 校准（tools/imatrix/calibrate.py、tools/imatrix/ggml_quant.py）、benchmark 框架（benchmark/ 目录，含 run.py、engine/runners/edge_dit.py、evaluation/ 下的 CLIP/SSIM/LPIPS/aesthetic 等指标）、Python 前端控制台（bindings/python/frontend/server-console/）。

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

一次典型推理请求（以 text-to-image 为例）的数据流如下： 1. 请求入口：用户通过 CLI（examples/cli/main.cpp）或 HTTP server（examples/server/routes.cpp）或 Python（bindings/python/src/edge_dit/engine.py）发起请求。请求参数被填充到 ed_image_generation_params_t（含 prompt、width、height、steps、cfg_scale、seed 等），而上下文参数填充到 ed_ctx_params_t（含 model path、backend、offload 策略、quantization、parallel 配置等）。 2. 引擎初始化：EdgeDitEngine::init()（src/core/runtime/edge_dit_engine.cpp）被调用。它首先通过环境变量（WORLD_SIZE、RANK、LOCAL_RANK）推断分布式配置，创建 ParallelContext。然后 ModelRuntime::init() 根据 ED_BACKEND 或 params.backend 初始化 ggml 后端（CUDA/CPU/Metal/Vulkan），并为每个组件分配独立 backend（RuntimeBackends：backend、clip_backend、vae_backend、control_net_backend），支持 per-component offload。接着 ModelLoader::load() 从指定路径读取权重文件（safetensors/GGUF/Diffusers 目录），通过 utils/model_io/ 下的格式解析器映射到 ggml tensor，返回 TensorMap。最后 create_dit_pipeline() 根据模型版本（SDVersion）创建对应 pipeline（如 FluxPipeline）。 3. Pipeline 准备：DiTPipeline::prepare() 被调用（如 FluxPipeline::prepare()）。它从 TensorMap 中提取 diffusion transformer、text encoder、VAE 的权重，构建 ggml 计算图节点，注册到 PipelineTensorRegistry。同时初始化 scheduler（discrete/karras/exponential/ays/gits/sgm_uniform/simple/smoothstep/kl_optimal/lcm/bong_tangent/ltx2）、denoiser、conditioner。如果启用 auto-fit，会根据 VRAM 预算自动选择量化精度（q8_0 → q4_K）和 per-component placement。 4. 文本编码：EdgeDitEngine::generate_image() 调用 pipeline 的 generate_image()。首先通过 text encoder（CLIP/T5/LLM，位于 src/dit_models/components/text_encoders/）将 prompt 编码为 condition tensor。Tokenizer（BPE/Gemma/Mistral/Qwen2/T5 Unigram）将文本转为 token ID，然后 encoder 模型前向计算得到 embedding。 5. 去噪循环：pipeline 进入 timestep 循环（由 scheduler 控制）。每个 step： - 准备 latent noise（通过 rng_philox.hpp 或 rng_mt19937.hpp 生成） - 通过 diffusion transformer（src/dit_models/models/flux.hpp 等）前向计算，内部调用 ggml 图执行 - CUDA 后端会使用自定义算子（ed_cuda_norm.cu、ed_cuda_rope.cu、ed_cuda_modulation.cu、ed_cudnn_sdpa.cu 等）加速 - 如果启用 layered offload，ggml_graph_cut.cpp 会将图切割，逐 block 在 GPU/CPU 间流转（ed_async_offload.cu 提供双缓冲） - 如果启用 cache（CacheEngine），会复用之前 timestep/block 的中间结果 - CFG parallel（cfg_parallel.cpp）会将 conditional/unconditional 分支并行执行 - Scheduler 更新 latent 6. 解码输出：去噪完成后，latent 通过 VAE decoder（src/dit_models/components/autoencoders/vae.hpp 或 auto_encoder_kl.hpp）解码为图像像素。VAE tiling 支持大图像分块解码以避免 OOM。最终图像通过 stb_image_write.h 或 Python 接口返回给用户。 关键调度点： - EdgeDitEngine::init()：后端选择、模型加载、pipeline 创建 - ModelRuntime::select_pipeline()：根据 SDVersion 分发 - DiTPipeline::prepare()：权重映射、图构建、scheduler 初始化 - ggml_graph_compute()：ggml 图执行（含 CUDA Graphs 捕获） - CacheEngine::decide()：缓存策略决策 - ParallelContext::all_reduce()：分布式通信点

关键类型与函数

扩展点

• 新模型接入：在 src/dit_models/models/ 下新增模型定义（如 xxx.hpp），实现 diffusion transformer 组件；在 src/dit_models/pipelines/ 下新增 pipeline（继承 DiTPipeline），实现 prepare/generate_image/generate_video；在 src/dit_models/pipelines/dit_pipeline.cpp 的 create_dit_pipeline() 中添加版本分支；在 include/edge-dit.h 中添加新的 SDVersion 枚举值
• 新后端接入：在 src/core/backend/ggml/ 下新增后端目录（如 ed_ggml_xxx_ext.hpp），实现自定义算子；在 CMakeLists.txt 中添加新的 ED_GGML_XXX 选项；在 ModelRuntime::init() 中添加后端初始化逻辑
• 新 kernel 接入：在 src/core/backend/ggml/cuda/ 下新增 .cu 文件（如 ed_cuda_xxx.cu），实现 CUDA 算子；在 src/core/backend/ggml/ 下新增对应的 _ext.hpp 声明；在 CMakeLists.txt 中添加 ED_ENABLE_CUDA_XXX 选项；在 pipeline 中调用新算子
• 新调度策略接入：在 src/core/optimization/cache/policy/policies/ 下新增策略文件（如 xxx_policy.cpp），继承 CachePolicy；在 policy_factory.cpp 中注册新策略；在 CacheEngine 中集成决策逻辑
• 新 text encoder 接入：在 src/dit_models/components/text_encoders/ 下新增 encoder 定义（如 xxx.hpp）；在 src/dit_models/components/text_encoders/tokenizers/ 下新增 tokenizer（如果需要）；在 conditioner 中集成新 encoder
• 新 VAE 接入：在 src/dit_models/components/autoencoders/ 下新增 VAE 定义（如 xxx.hpp）；在 pipeline 中替换或扩展 VAE 组件
• 新优化策略接入：在 src/core/optimization/ 下新增模块（如 src/core/optimization/quantization/）；在 ModelRuntime 或 DiTPipeline 中调用新策略
• 新并行策略接入：在 src/core/parallel/backends/ 下新增通信后端（如 xxx_process_group.cpp）；在 ParallelContext 中集成新后端

最近在动的地方

• src/dit_models：提交热点第一名（39 次），是模型覆盖的核心区域，最近提交包括 LTX-2.3 视频/音频管线、MiniMax-H3 性能数据、FLUX latent channels 修复
• src/core：提交热点第二名（12 次），包含 runtime、backend、optimization、parallel 等核心逻辑，是性能优化的关键区域
• bindings/python：提交热点第三名（8 次），Python 绑定和前端控制台，最近提交了 Python 和 web console 使用指南
• examples/server：提交热点第四名（7 次），HTTP 服务器实现，是对外服务的主要接口
• src/core/backend/ggml/cuda/：CUDA 专用算子集合，包含 norm、RoPE、modulation、attention、SageAttention、SP FLUX、async offload，是 CUDA 性能的关键路径
• src/core/optimization/cache/：计算复用框架，支持多种缓存策略（DiCache/EasyCache/MagCache/SageCache/TaylorSeer/UCache），是 timestep/block 级别优化的核心
• src/core/parallel/：轻量级并行运行时，支持 CFG/sequence/tensor parallel，NCCL/MPI/CPU 后端，是分布式训练/推理的基础
• src/utils/model_io/：

建议阅读顺序

1. README.md — 项目概览、功能列表、性能数据、支持模型
2. include/edge-dit.h — C API 和核心类型定义（ed_ctx_params_t、ed_image_generation_params_t、SDVersion 等）
3. src/core/runtime/edge_dit_engine.hpp + edge_dit_engine.cpp — 顶层调度器，理解 init/generate_image/generate_video 流程
4. src/core/runtime/model_runtime.hpp + model_runtime.cpp — 后端初始化、设备选择、per-component backend 分配
5. src/dit_models/pipelines/dit_pipeline.hpp + dit_pipeline.cpp — pipeline 抽象基类和工厂函数
6. src/dit_models/pipelines/flux_pipeline.hpp + flux_pipeline.cpp — 最成熟的 pipeline 实现，理解 FLUX 执行流程
7. src/dit_models/models/flux.hpp — FLUX 模型定义，理解 diffusion transformer 组件
8. src/core/backend/ggml/cuda/ — CUDA 专用算子，理解性能关键路径
9. src/core/optimization/cache/ — 计算复用框架，理解缓存策略
10. src/core/parallel/ — 并行运行时，理解 CFG/sequence/tensor parallel

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

安装

1. git clone --recursive https://github.com/THU-MIG/edge-dit.cpp && cd edge-dit.cpp
2. # 若忘记 --recursive，补拉子模块：
3. # git submodule update --init --recursive
4. # 或 bash scripts/bootstrap.sh
5. # 在 Apple Silicon Mac 上只走 CPU 路径，不启用 CUDA/Metal/Vulkan：
6. bash scripts/build_cpu.sh
7. # 产物默认在 build-cpu/bin/ 下；验证 CLI 能跑：
8. ./build-cpu/bin/ed-cli --help
9. # 可选：安装 Python 绑定做 smoke test（需要 Python 环境）：
10. cd bindings/python && python -m pip install -e '.[dev]'

哪些路径能真跑

['可本地执行：src/core/runtime/model_runtime.cpp 中 init_explicit_backend() 的 request=="cpu" 分支、RuntimeBackends 的 per-component CPU 分配；src/core/parallel/backends/cpu/ 的 cpu_process_group.cpp 与 file_store.cpp；src/core/optimization/cache/ 的 DiCache/TaylorSeer/UCache 等缓存策略（timestep/block 级 cache reuse 在 CPU 上可跑但极慢）；src/dit_models/components/text_encoders/tokenizers/ 下 BPE/CLIP/T5/Qwen2/Mistral/Gemma tokenizer 全部可单测；src/utils/model_io/ 的 safetensors/gguf/pickle/torch_zip 读写与 convert.cpp 权重转换；tools/imatrix/ 的量化校准脚本（CPU 可跑但很慢）；bindings/python/ 下 test_capi_layout.py、test_config_validation.py、test_enum_mapping.py、test_image_conversion.py、test_library_loading.py 等纯 CPU 测试。', '只能读代码或上 Colab T4 验证：src/core/backend/cuDNN/ 全部（ed_cudnn_sdpa.cu、ed_cudnn_conv2d.cu、ed_cudnn_conv3d.cu、ed_cudnn_conv_transpose_1d.cu）；src/core/backend/ggml/cuda/ 全部（ed_cuda_norm.cu、ed_cuda_rope.cu、ed_cuda_modulation.cu、ed_cuda_sage_attn.cu、ed_cuda_sp_flux.cu、ed_async_offload.cu、ed_cuda_attention_v_prep.cu 及 sage/ 下 .cuh）；src/core/backend/ggml/parallel/ 的 NCCL/MPI 多卡通信（ggml_comm.cpp）；src/core/parallel/backends/nccl/；CMakeLists.txt 中 ED_GGML_CUDA/METAL/VULKAN 对应的后端；ED_ENABLE_CUDA_GRAPHS、ED_ENABLE_CUDA_SAGE_ATTN、ED_ENABLE_CUDNN_SDPA 等宏保护的代码；benchmark/ 下依赖真实 GPU 的 engine/measurement/gpu_monitor.py 与 engine/runners/ 的端到端跑分；examples/server/ 的 HTTP 服务（可编译但推理需 GPU 才有意义）。']

最小可运行

1. # 1) CLI 帮助与版本（验证构建产物存在）：
2. ./build-cpu/bin/ed-cli --help
3. # 2) 权重转换冒烟（把 Diffusers/safetensors 转 GGUF，CPU 可跑，需准备一个小模型如 FLUX.1-dev 或 SD3）：
4. ./build-cpu/bin/ed-convert --help
5. # 3) Python 绑定加载与配置校验（无 GPU 也能跑单元测试子集）：
6. cd bindings/python && pytest tests/test_capi_layout.py tests/test_config_validation.py tests/test_enum_mapping.py tests/test_image_conversion.py tests/test_library_loading.py -v
7. # 4) Tokenizer 单测（纯 CPU，验证 text encoder 前端）：
8. # 在 CMake 中若有 tokenizer 测试 target 则直接跑；否则通过 Python bindings 调用 tokenizer 接口做冒烟。
9. # 5) 真实推理冒烟（需下载 GGUF 或原始权重，CPU 极慢但能跑通端到端，建议在 Colab T4 上做最终确认）：
10. ./build-cpu/bin/ed-cli --backend cpu --model /path/to/flux-dev --prompt "a glass teapot on a wooden table" --width 128 --height 128 --steps 1 --output smoke.png

测试

['C++ 测试框架：项目主仓库未显式引入 gtest/gmock（CMakeLists.txt 与 src/ 下未见 test target），C++ 侧验证主要靠 ed-cli --help 与 ed-convert --help 冒烟；Python 侧使用 pytest，入口在 bindings/python/tests/。', '只跑 CPU 子集的命令：cd bindings/python && pytest tests/test_capi_layout.py tests/test_config_validation.py tests/test_enum_mapping.py tests/test_image_conversion.py tests/test_library_loading.py -v。', '真实模型集成测试需显式开启环境变量 EDGE_DIT_RUN_INTEGRATION=1、EDGE_DIT_LIBRARY=<path> 和模型路径，默认不会在普通开发或 CI 中运行（见 CONTRIBUTING.md）。', '耗时：纯 CPU 单元测试（无真实模型）通常 < 1 分钟；带真实权重的集成测试在 CPU 上可能数十分钟到小时级，建议只在 Colab T4 上做。']

调试

• 日志开关：通过环境变量 ED_BACKEND=cpu|auto|metal|cuda|vulkan 强制选择后端；ED_CLI_SINGLE_VISIBLE_DEVICE=1 让多设备场景只看到 device 0；ED_ONEDNN=0 关闭 oneDNN bf16 AMX 加速。
• Flux Kontext 调试：ED_DEBUG_FLUX_KONTEXT_ALIGN=1 开启张量统计日志；ED_FLUX_KONTEXT_ALIGN_DUMP_DIR=<dir> + ED_FLUX_KONTEXT_ALIGN_DUMP_TARGETS=name1,name2 把指定张量 dump 为 .shape + .f32.bin，便于与 PyTorch 参考实现逐张量对比。
• Benchmark 阶段标记：编译时加 -D ED_BENCHMARK_MARKERS=ON（对应 CMakeLists.txt 中 ED_BENCHMARK_MARKERS 选项），src/dit_models/pipelines/dit_pipeline_utils.hpp 中的 emit_phase_marker() 会输出 [[phase]] stage=... event=... t=... 到 stdout，供外部 benchmark harness 做 component-level 延迟归因。
• 断点入口：src/core/runtime/edge_dit_engine.cpp 的 EdgeDitEngine::init() 与 generate_image()/generate_video() 是顶层调度断点；各 pipeline 的 prepare() 与 generate_image() 是模型族级断点；src/dit_models/pipelines/dit_pipeline.cpp 的 create_dit_pipeline() 是 pipeline 分发入口。
• Profiling：src/core/optimization/cache/runtime/cache_engine.cpp 是缓存策略核心，可在这里加计时观察 DiCache/TaylorSeer 命中率；src/core/backend/ggml/ggml_graph_cut.cpp 涉及图切割与 offload 边界，是性能剖析热点。

CI

['CI 配置位于 .github/workflows/（目录下共 5 个文件，具体文件名未在证据中列出，需验证是否为 lint/build/test 矩阵）。', "从 CONTRIBUTING.md 推断 CI 至少包含：CPU 构建验证（bash scripts/build_cpu.sh + ./build-cpu/bin/ed-cli --help）和 Python 绑定测试（cd bindings/python && pip install -e '.[dev]' && pytest）。", 'PR 会被以下卡住：未通过 Python 单元测试；引入生成产物/本地 benchmark 图像/视频/日志/机器特定路径（CONTRIBUTING.md 明确禁止）；包含模型权重或私有数据集；公开行为变更未同步 README 或 docs；性能工作缺少 before/after 延迟或显存数据、硬件/CUDA 版本信息。', '真实模型集成测试（EDGE_DIT_RUN_INTEGRATION=1）默认不在 CI 中运行，需显式开启。']

坑

• 1. 子模块缺失：未 --recursive clone 或未运行 bash scripts/bootstrap.sh 会导致 third_party/ggml 等为空，CMake 配置失败。
• 2. 在 Apple Silicon 上默认不要走 CUDA/Metal/Vulkan：CMakeLists.txt 中 ED_GGML_CUDA/METAL/VULKAN 默认 OFF，scripts/build_cpu.sh 才是正确入口；误用 scripts/build_cuda.sh 会找不到 CUDA toolkit。
• 3. CPU 推理极慢且受内存带宽限制：16GB 统一内存跑 FLUX/SD3 即使 128×128 1 step 也可能耗时很长甚至 OOM，冒烟测试务必用最小分辨率和最少步数，或只跑 tokenizer/convert 等前端路径。
• 4. 真实模型集成测试默认关闭：不要误以为 pytest 没跑过就是测试挂了——带 EDGE_DIT_RUN_INTEGRATION=1 的测试需要显式开启并提供模型路径。
• 5. v0.x API/ABI/CLI 不稳定：README 明确声明 v0.x 的 C API、CLI flags、HTTP schemas 公开但未稳定，写绑定或脚本时注意跟进 include/edge-dit.h 与 docs/api.md 的变更。
• 6. 权重格式陷阱：支持 Diffusers 目录、safetensors（+shard index）、GGUF；但 Qwen-Image Lightning 是 LoRA，必须先 scripts/merge_qwen_lora.py 合并到 base，否则 pipeline 找不到完整权重。
• 7. 调试环境变量拼写敏感：ED_DEBUG_FLUX_KONTEXT_ALIGN、ED_FLUX_KONTEXT_ALIGN_DUMP_DIR、ED_FLUX_KONTEXT_ALIGN_DUMP_TARGETS 是三个独立变量，拼写错误会静默不 dump。

四、维护者与社区

项目处于 alpha 快速迭代期（v0.1.0，2026-07-11 进入 public preview）。最近 30 天（2026-08 至 2026-09-01）至少有 11 个非合并提交，平均约每 2–3 天一次提交，节奏偏快。提交热点集中在 src/dit_models（39 次）、src/core（12 次）、bindings/python（8 次）、examples/server（7 次）、examples/cli（6 次），说明团队在并行扩展模型覆盖、核心运行时与对外接口。Release 方面，仓库目前 releases 为空数组，没有正式 GitHub Release，仅以 README 顶部徽章 status-alpha-orange 与 v0.1.0 版本号标记阶段。

流程与 Review 风格

贡献流程相对轻量，没有 CLA/DCO 或 pre-commit 的强制证据。CONTRIBUTING.md 要求：先 git submodule update --init --recursive，用 bash scripts/build_cpu.sh 或 bash scripts/build_cuda.sh 验证；Python 绑定用 cd bindings/python && pip install -e '.[dev]' && pytest；集成测试需显式环境变量 EDGE_DIT_RUN_INTEGRATION=1、EDGE_DIT_LIBRARY 与模型路径，默认不跑。PR 要求「keep changes focused」，性能工作需附上：model family 与命令行、硬件/CUDA/cuDNN/NCCL 版本、before/after 延迟或显存数据、正确性或图像质量验证。对外行为变更需在同一 PR 更新 README 或 docs。代码风格要求：优先复用既有模式、模型特定优化隔离、不提交生成产物/本地 benchmark 图像/视频/日志/机器路径、不提交模型权重或私有数据集。许可证方面，CONTRIBUTING.md 明确「By contributing, you agree that your contributions are licensed under the Apache License, Version 2.0, unless explicitly stated otherwise」，即默认 Apache-2.0，无需额外 CLA。

由于 pulls 为空数组、Issue #82 的 comments 为 0，无法从公开 PR/Issue 评论中推断具体 review 用语或响应时间。但从 commit 历史看，团队对 main 分支有直接提交（如 Merge remote-tracking branch 'origin.main' 与多个非合并提交），说明维护者可能直接在 main 上迭代或通过内部流程合入，公开 review 样本不足，响应速度与风格「需验证」。

渠道

• GitHub Issues（.github/ISSUE_TEMPLATE）
• GitHub Pull Requests（.github/pull_request_template.md）
• CONTRIBUTING.md
• docs/development.md
• README 中 citation 与仓库 URL https://github.com/THU-MIG/edge-dit.cpp

这里的规矩

• 得体：提 PR 时保持 focused，性能工作附上 model family、命令行、硬件/CUDA/cuDNN/NCCL 版本、before/after 延迟或显存数据；对外行为变更同步更新 README 或 docs；遵循既有代码风格，把模型特定优化隔离到对应模块；不提交生成产物、本地 benchmark 图像/视频/日志、机器路径、模型权重或私有数据集。
• 得体：在 Issue 中先描述清楚问题或功能范围（如 Issue #82 [Feature]: LTX2.3 那样给出明确主题），便于维护者快速分类。
• 不得体：在 PR 中夹带与主题无关的重构或新增抽象，违反「Prefer existing project patterns over new abstractions」原则。
• 不得体：把真实模型权重、私有数据集、本地路径或 benchmark 产物提交进仓库。
• 不得体：在没有 GPU 的 CPU-only 环境里跑集成测试却不设置 EDGE_DIT_RUN_INTEGRATION=1 等显式开关，导致 CI 或本地误触发重负载。

维护者现在最想要的帮助

• LTX-2.3 视频/音频管线完善：最近提交 feat(ltx): add LTX-2.3 video and audio pipeline、perf(ltx): optimize offload and execution paths、fix(ltx): isolate model-specific runtime behavior 显示 LTX 是当前活跃模块，需要 offload 路径、执行路径与模型特定行为的持续打磨。
• MiniMax-H3 性能与文档：docs(minimax-h3): publish RTX 4090 comparison、docs: merge MiniMax-H3 performance results into README、feat(benchmark): add MiniMax-H3 and FLUX.2 manifests 表明团队在推进 MiniMax-H3 的 benchmark 与文档覆盖，需要更多硬件/场景下的性能数据。
• FLUX 系列修复：fix(flux): derive latent channels for auto-fit 说明 FLUX 在 auto-fit 路径仍有 latent channels 相关边界情况需要处理。
• benchmark 基础设施：feat(benchmark): add MiniMax-H3 and FLUX.2 manifests 与 benchmark/ 目录（123 个条目，含 jobs、models、sites、reports、methods、evaluation）显示团队在搭建系统化 benchmark 框架，需要更多模型 manifest、sites 配置与报告生成支持。
• Python 绑定与对外接口：docs(bindings): add Python and web console usage guides、bindings/python 8 次提交，说明 Python 包与 server console 仍在完善，需要绑定层文档、示例与测试覆盖。
• Vulkan 后端优化：README 明确标注「Vulkan still optimizing」且「~1.3x slower than CUDA」，属于已知待改进区域。
• CPU/oneDNN 路径：README 提到 CPU 可选 oneDNN bf16 AMX matmul，scripts/build_cpu.sh 自动启用，但属于 portable fallback，需要更多 CPU 端优化与测试。

五、切入方案

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

第一批 PR

怎么知道自己站住了

• 第一个 PR 在 2 周内被合并，且合并者给了有信息量的 review 评论
• 在 2 个以上 issue 里被维护者 @ 回答或标记为 help wanted 的认领者
• 成为至少 1 个子模块（bindings/python、benchmark、src/utils/model_io）的默认 reviewer
• CPU/Metal 测试在 CI 上稳定通过至少 1 个月，无 flaky
• 在 benchmark 仓库里出现你贡献的 CPU 基线报告，并被其他人引用
• 在项目 discussions 或外部博客看到别人引用你的「无 GPU 贡献」经验
• 维护者邀请你参与 roadmap 讨论或加入 collaborators（即使只是 triage 权限）