diff --git a/knowledge/repos/vllm-omni/ci/_index.md b/knowledge/repos/vllm-omni/ci/_index.md index cee1066..d3b5255 100644 --- a/knowledge/repos/vllm-omni/ci/_index.md +++ b/knowledge/repos/vllm-omni/ci/_index.md @@ -1,7 +1,7 @@ --- title: "vLLM-Omni CI" created: 2026-07-10 -updated: 2026-07-10 +updated: 2026-08-04 type: index tags: [vllm-omni, ci] sources: [] @@ -21,5 +21,6 @@ sources: [] | 遇到什么 | 查看哪里 | |---|---| +| 修改 Buildkite 选择器、pytest marker、硬件队列、golden 或质量阈值 | [CI 规则](rules.md) | | 查看仓库特有 CI 陷阱 | [CI guides](guides/_index.md) | | 调查历史 CI 失败 | [CI incidents](incidents/_index.md) | diff --git a/knowledge/repos/vllm-omni/ci/rules.md b/knowledge/repos/vllm-omni/ci/rules.md new file mode 100644 index 0000000..1ce9d58 --- /dev/null +++ b/knowledge/repos/vllm-omni/ci/rules.md @@ -0,0 +1,45 @@ +--- +title: "vLLM-Omni CI 规则" +created: 2026-08-04 +updated: 2026-08-04 +type: rule +tags: [vllm-omni, ci] +sources: ["PR #5436", "PR #5695", "PR #5696", .buildkite/, tests/helpers/mark.py] +confidence: high +--- + +# vLLM-Omni CI 规则 + +只有 `VOMNI-CI-数字字母` 是可审计规则 ID。 + +## Direct 代码快速入口 + +| PR 描述信号 | 规则 | 第一批 live 源码 | +|---|---|---| +| Buildkite path、label、pytest selector、marker、队列、卡数或目标分支 | `VOMNI-CI-1a` | 命中 `.buildkite/` step → pytest 命令 → changed test 的 `pytestmark` / `hardware_test` | +| 平台专有 golden、阈值、accuracy/performance lane | `VOMNI-CI-1b` | changed test case → golden selector → scorer/threshold → 实际 CI hardware marker | + +## VOMNI-CI-1a — 选择器改动必须闭合到实际收集的测试集合 + +- 触发：新增、拆分、收窄或移动 Buildkite step，或修改 path、label、pytest `-m`、 + hardware marker、队列、卡数及非默认目标分支。 +- 强制：冻结 PR 的真实 target base；分别在 base/head 收集测试，并把 + `path/label → pytest selector → test marker → hardware/queue/card count` 逐项对齐； + 每个被移除的平台或测试都必须有明确归类。 +- 禁止：从文件名推断收集集合；在 `main` 上验证一个目标为 release/challenge 分支的 + diff；把未解释的掉测、平台移除或 label 变化当作纯 CI 重排。 +- 验收：保存 base/head 的 collection diff，head 中每个选中测试都能到达匹配的 runner， + 每个掉测都有 `moved`、`intentionally removed` 或 `still covered elsewhere` 结论，并用 + 实际 target branch 跑一次选择器 smoke。 ^[PR #5695] ^[PR #5696] + +## VOMNI-CI-1b — 平台专有质量 oracle 必须来自同一硬件 case + +- 触发：按 CUDA/ROCm/NPU 或具体硬件选择 golden、评分器、阈值或质量 job。 +- 强制：golden provenance、测试输入、模型 revision、执行参数、marker、队列和实际硬件 + 属于同一个 case；平台分支必须显式选择 oracle，未命中的平台保持原合同。 +- 禁止：用另一硬件的本地输出生成 golden；用无法解释的阈值放宽吸收平台漂移；修改 + 一个平台时顺带改变其他平台的 baseline。 +- 验收：目标 CI runner 产出的 artifact 可复现提交 golden 的 digest 和评分，目标平台 + 命中专属 oracle，至少一个未改平台 control 仍选择原 oracle；阈值证据同时满足 + [DIFF-3a](../components/diffusion/rules.md#diff-3a--质量阈值必须由完全相同的测试-case-产生)。 + ^[PR #5436] diff --git a/knowledge/repos/vllm-omni/components/diffusion/_index.md b/knowledge/repos/vllm-omni/components/diffusion/_index.md index 572eef8..987e88c 100644 --- a/knowledge/repos/vllm-omni/components/diffusion/_index.md +++ b/knowledge/repos/vllm-omni/components/diffusion/_index.md @@ -1,7 +1,7 @@ --- title: "Diffusion" created: 2026-07-10 -updated: 2026-07-31 +updated: 2026-08-04 type: index tags: [vllm-omni, components, diffusion] sources: [] @@ -16,7 +16,8 @@ sources: [] ## 什么时候查这里 - 根因位于共享 diffusion 代码，可能影响多个模型。 -- 调查 denoise loop、diffusion runner、scheduler 或共享 attention 执行机制。 +- 调查 denoise loop、diffusion runner、scheduler、attention backend 选择或 packed + sequence boundary。 ## 不放什么 @@ -28,7 +29,7 @@ sources: [] | 遇到什么 | 查看哪里 | |---|---| | 理解共享职责和数据流 | [architecture](architecture.md) | -| 根据 PR 描述直达 execution parity、checkpoint/distributed 或 quality evidence 的规则组与第一批源码 | [rules 与代码地图](rules.md) | +| 根据 PR 描述直达 execution parity、attention backend、checkpoint/distributed 或 quality evidence 的规则组与第一批源码 | [rules 与代码地图](rules.md) | | diffusion step 与 request/continuous batching | [step and batching](step-and-batching.md) | | Cache-DiT、TeaCache 和 prefix cache | [cache acceleration](cache-acceleration.md) | | TP/PP/SP/CFG/VAE/HSDP 等并行策略 | [parallelism](parallelism.md) | diff --git a/knowledge/repos/vllm-omni/components/diffusion/rules.md b/knowledge/repos/vllm-omni/components/diffusion/rules.md index 7a573e7..618333b 100644 --- a/knowledge/repos/vllm-omni/components/diffusion/rules.md +++ b/knowledge/repos/vllm-omni/components/diffusion/rules.md @@ -1,10 +1,10 @@ --- title: "Diffusion 共享规则" created: 2026-07-20 -updated: 2026-07-31 +updated: 2026-08-04 type: rule tags: [vllm-omni, components, diffusion] -sources: ["PR #4341", "PR #5001", "PR #5087", "PR #5088", "PR #5136", vllm_omni/diffusion/worker/diffusion_model_runner.py, vllm_omni/diffusion/model_loader/diffusers_loader.py, vllm_omni/diffusion/distributed/hsdp.py] +sources: ["PR #4341", "PR #5001", "PR #5087", "PR #5088", "PR #5136", "PR #5691", vllm_omni/diffusion/worker/diffusion_model_runner.py, vllm_omni/diffusion/model_loader/diffusers_loader.py, vllm_omni/diffusion/distributed/hsdp.py, vllm_omni/diffusion/attention/backends/flash_attn.py, vllm_omni/diffusion/attention/backends/ring/ring_selector.py] confidence: high --- @@ -22,6 +22,8 @@ confidence: high |---|---|---| | CUDA Graph、compile、fused scheduler/solver、cache path、eager parity | `execution-parity`：`DIFF-1a` | `vllm_omni/diffusion/compile.py::regionally_compile` → `vllm_omni/diffusion/worker/diffusion_model_runner.py::{DiffusionModelRunner.execute_model,execute_model_batch}` → 命中模型的 denoise/solver consumer | | seed、request-local generator、guidance=0、并发 RNG、batched generators | `execution-parity`：`DIFF-1b` | `vllm_omni/inputs/data.py::OmniDiffusionSamplingParams` → `diffusion_model_runner.py::DiffusionModelRunner._initialize_generator` → `request_batch.py::DiffusionRequestBatch.collate_sampling_param_generators` | +| FA4/FA3/FA2、optional import/ABI、CUDA capability、Ring LSE/window | `attention-backend`：`DIFF-1c` | `diffusion/attention/backends/utils/fa.py` → `ring/ring_selector.py::select_flash_attn_impl` → local/ring wrapper | +| packed varlen、`cu_seqlens_*`、padding boundary、Ring/Ulysses parity | `attention-backend`：`DIFF-1d` | metadata producer → `attention/backends/flash_attn.py::FlashAttentionImpl.forward` → `attention/layer.py::{_run_local_attention,_run_ring_attention}` | | ModelOpt/checkpoint adapter、weight/scale remap、unknown tensor、resolution path | `checkpoint-distributed`：`DIFF-2a` | `vllm_omni/diffusion/model_loader/diffusers_loader.py::{DiffusersPipelineLoader._get_checkpoint_adapter,load_weights}` → `checkpoint_adapters/modelopt.py::{ModelOptFp8CheckpointAdapter._resolve_target_and_output_names,adapt}` | | HSDP/FSDP、`fully_shard`、DeviceMesh、packed/scalar parameter、FP8 | `checkpoint-distributed`：`DIFF-2b` | `vllm_omni/diffusion/distributed/hsdp.py::{apply_hsdp_to_model,shard_model}` → `model_loader/diffusers_loader.py::DiffusersPipelineLoader._load_model_with_hsdp` → `quantization/hsdp_fp8.py::prepare_fp8_layers_for_fsdp` | | component quantization、text encoder/transformer/VAE 独立配置、owner prefix、meta/offload | `checkpoint-distributed`：`DIFF-2c` | `vllm_omni/diffusion/data.py::OmniDiffusionConfig._propagate_quantization_from_tf_config` → `model_loader/diffusers_loader.py::{DiffusersPipelineLoader._get_weight_sources,_process_weights_after_loading}` → 命中 component 的真实 linear consumer | @@ -31,6 +33,7 @@ confidence: high |---|---|---| | `core` | 每次共享 diffusion 审查 | `DIFF-1a`, `DIFF-1b` | | `execution-parity` | graph/eager、solver、RNG、generator、zero/default | `DIFF-1a`, `DIFF-1b` | +| `attention-backend` | Flash backend selection、packed varlen、Ring/Ulysses、padding boundary | `DIFF-1c`, `DIFF-1d` | | `checkpoint-distributed` | checkpoint、quantization、HSDP/FSDP | `DIFF-2a`, `DIFF-2b`, `DIFF-2c` | | `quality-evidence` | 质量阈值、offload、A/B case | `DIFF-3a` | | `author-routing` | 只供 Direct reviewer 导航，不作为 finding 规则 | `DIFF-0a`, `DIFF-0b` | @@ -57,6 +60,31 @@ confidence: high 到达 consumer。Cosmos3 的落地约束见 [Cosmos3 规则](../../models/cosmos3/rules.md)。 ^[PR #5001] +### DIFF-1c — 可选 attention backend 的选择、包装和 Ring 语义必须一致 + +- 触发：增加或修改 FA4/FA3/FA2 discovery、optional extra、CUDA capability selector、 + local/Ring wrapper、window 或 LSE 返回值。 +- 强制：同时验证硬件 capability 与目标 symbol 可用性；import/ABI 失败只能降级到下一条 + 已支持路径并留下可见原因；local 与 Ring 对 window、softmax scale、causal 和 LSE 的 + 约定必须一致。 +- 禁止：只按 GPU 名称或已安装 package 选择 backend；显式请求不可用实现后静默换成语义 + 不同的 kernel；Ring wrapper 丢弃上层需要的 LSE 或改变 unlimited-window sentinel。 +- 验收：用 capability × FA4/FA3/FA2 可用性矩阵验证选择优先级和显式失败；local/Ring wrapper + 参数与返回值测试对齐，并至少运行一次真实 backend smoke，证明 packaging extra、文档命令 + 和 runtime import 指向同一实现。 ^[PR #5691] + +### DIFF-1d — packed varlen 边界是原子合同，所有并行路径都必须保留 + +- 触发：producer 或 backend 读写 `cu_seqlens_q`、`cu_seqlens_k`、`max_seqlen_q`、 + `max_seqlen_k`，或把带 padding 的 packed 输入送入 Ring/Ulysses/hybrid attention。 +- 强制：四个字段一起生产、转发和消费；每条启用的 parallel/backend 路径必须把相同 + sequence boundary 交给 kernel，无法表达时在执行前明确拒绝。 +- 禁止：只提供部分 metadata；在 Ring 路径丢弃边界；假设已分配但 backend 忽略的 + `attn_mask` 能阻止真实 token 关注 padding 或下一条 packed sequence。 +- 验收：缺任一字段立即失败；两个不同长度样本的 packed 结果分别与独立运行对齐且无 + cross-sequence attention；local 与每个声明支持的 Ring/Ulysses 组合做数值 parity， + 不支持的组合有 fail-fast 测试。 ^[PR #5691] + ## Checkpoint 与分布式加载 ### DIFF-2a — checkpoint remap 必须追到已注册且真实消费的目标 diff --git a/knowledge/repos/vllm-omni/components/serving/_index.md b/knowledge/repos/vllm-omni/components/serving/_index.md index 072bf42..4d6acf3 100644 --- a/knowledge/repos/vllm-omni/components/serving/_index.md +++ b/knowledge/repos/vllm-omni/components/serving/_index.md @@ -1,7 +1,7 @@ --- title: "Serving" created: 2026-07-10 -updated: 2026-07-31 +updated: 2026-08-04 type: index tags: [vllm-omni, components, serving] sources: [] @@ -16,6 +16,7 @@ sources: [] ## 什么时候查这里 - CLI、HTTP、OpenAI-compatible API 或 offline/online 请求行为不一致。 +- serve flag 迁移、multipart media 限额、临时 artifact 所有权或后台任务 cleanup。 - 参数在入口处丢失、默认值改变，或请求没有进入预期 engine 路径。 ## 不放什么 @@ -28,4 +29,4 @@ sources: [] | 遇到什么 | 查看哪里 | |---|---| | 理解入口到 engine 的边界 | [architecture](architecture.md) | -| 根据 PR 描述直达 request contract、streaming format、artifact readiness 或 metrics 的规则组与第一批源码 | [rules 与代码地图](rules.md) | +| 根据 PR 描述直达 request contract、upload lifecycle、public CLI、streaming format、artifact readiness 或 metrics 的规则组与第一批源码 | [rules 与代码地图](rules.md) | diff --git a/knowledge/repos/vllm-omni/components/serving/rules.md b/knowledge/repos/vllm-omni/components/serving/rules.md index 8aa99a5..5de6d1e 100644 --- a/knowledge/repos/vllm-omni/components/serving/rules.md +++ b/knowledge/repos/vllm-omni/components/serving/rules.md @@ -1,10 +1,10 @@ --- title: "Serving 规则" created: 2026-07-20 -updated: 2026-07-31 +updated: 2026-08-04 type: rule tags: [vllm-omni, components, serving] -sources: ["PR #3576", "PR #4718", "PR #4834", "PR #4905", "PR #4912", "PR #5157", "claude-workflow-starter-private@09dca46", "zuiho-kai/claude-workflow-starter@c217fc6", vllm_omni/entrypoints/async_omni.py, vllm_omni/entrypoints/openai/diffusion_request_utils.py, vllm_omni/entrypoints/openai/serving_speech.py, vllm_omni/metrics/prometheus.py] +sources: ["PR #3576", "PR #4718", "PR #4834", "PR #4905", "PR #4912", "PR #5157", "PR #5647", "PR #5691", "claude-workflow-starter-private@09dca46", "zuiho-kai/claude-workflow-starter@c217fc6", vllm_omni/entrypoints/async_omni.py, vllm_omni/entrypoints/cli/serve.py, vllm_omni/entrypoints/openai/api_server.py, vllm_omni/entrypoints/openai/diffusion_request_utils.py, vllm_omni/entrypoints/openai/serving_speech.py, vllm_omni/metrics/prometheus.py] confidence: high --- @@ -19,7 +19,9 @@ confidence: high | PR 描述在做什么 | 精确规则组 | 第一批 live 源码 | |---|---|---| -| `extra_body`、flattened/nested/canonical/legacy 输入、alias、`negative_prompt`、diffusion request extras | `request-contract`：`SERV-4a`–`4h` | `vllm_omni/entrypoints/openai/diffusion_request_utils.py::{normalize_diffusion_request_args,apply_normalized_diffusion_request_extra_args}` → `serving_chat.py::{OmniOpenAIServingChat._preprocess_chat,OmniOpenAIServingChat.generate_diffusion_images}` | +| `extra_body`、flattened/nested/canonical/legacy 输入、alias、`negative_prompt`、diffusion request extras | `request-contract`：`SERV-4a`–`4i` | `vllm_omni/entrypoints/openai/diffusion_request_utils.py::{normalize_diffusion_request_args,apply_normalized_diffusion_request_extra_args}` → `serving_chat.py::{OmniOpenAIServingChat._preprocess_chat,OmniOpenAIServingChat.generate_diffusion_images}` | +| multipart `UploadFile`、重复 media、临时文件、413、sync/async cleanup | `upload-lifecycle`：`SERV-4b`, `SERV-4c`, `SERV-4d`, `SERV-4i` | `vllm_omni/entrypoints/openai/api_server.py::{_parse_video_form,_persist_uploaded_video_references,_run_video_generation_job,create_video_sync}` → 模型 owner 的 task/source matrix | +| serve flag 删除/改名、Helm value、headless forwarding、内部兼容字段 | `public-cli-contract`：`SERV-6a`, `SERV-6b` | `vllm_omni/entrypoints/cli/serve.py::{OmniServeCommand.subparser_init,run_headless}` → public wrappers/charts → `entrypoints/utils.py::load_and_resolve_stage_configs` | | `chat_template_kwargs`、raw HTTP/SDK `extra_body`、text/audio modalities、choices、空音频 | `chat-multimodal-contract`：`SERV-4c` + 命中模型规则 | upstream `ChatCompletionRequest` → `serving_chat.py::{OmniOpenAIServingChat._preprocess_chat,OmniOpenAIServingChat.chat_completion_full_generator,OmniOpenAIServingChat._create_text_choice,OmniOpenAIServingChat._create_audio_choice}` | | endpoint restriction、unsupported route、capability、completions/chat/speech 400 | `endpoint-capability`：`SERV-4c`, `SERV-4d` | `config/endpoint_policy.py::{OmniServingCapability,shutdown_unsupported_routes}` → `config/config_factory.py::StageConfigFactory.get_pipeline_endpoint_restrictions` → `engine/async_omni_engine.py::AsyncOmniEngine.__init__` → `entrypoints/openai/api_server.py::build_app` | | sleep/wake、partial stage/tag、idempotency、ACK、generation admission | `engine-lifecycle`：`SERV-5a`, `SERV-5b` | `entrypoints/async_omni.py::{AsyncOmni.sleep,AsyncOmni.wake_up,AsyncOmni.generate}` → `worker/base.py::{handle_sleep_task,handle_wake_task}` / `diffusion/worker/diffusion_worker.py` | @@ -36,7 +38,9 @@ confidence: high | `chat-multimodal-contract` | chat template kwargs、SDK flatten、text/audio response shape | `SERV-4c` + 命中模型规则 | | `endpoint-capability` | endpoint restriction、unsupported route、公开 400 | `SERV-4c`, `SERV-4d` | | `engine-lifecycle` | sleep/wake、partial stage/tag、ACK、generation admission | `SERV-5a`, `SERV-5b` | -| `request-contract` | 请求字段、来源、冲突、dispatcher、consumer view | `SERV-4a`, `SERV-4b`, `SERV-4c`, `SERV-4d`, `SERV-4e`, `SERV-4f`, `SERV-4g`, `SERV-4h` | +| `upload-lifecycle` | multipart media、临时 artifact、大小限制、后台任务 cleanup | `SERV-4b`, `SERV-4c`, `SERV-4d`, `SERV-4i` | +| `public-cli-contract` | serve flag、wrapper/chart key、headless、公开/内部兼容边界 | `SERV-6a`, `SERV-6b` | +| `request-contract` | 请求字段、来源、冲突、dispatcher、consumer view | `SERV-4a`, `SERV-4b`, `SERV-4c`, `SERV-4d`, `SERV-4e`, `SERV-4f`, `SERV-4g`, `SERV-4h`, `SERV-4i` | | `author-routing` | 只供 Direct reviewer 导航，不作为 finding 规则 | `SERV-0a`, `SERV-0b` | ## SERV-1a — 所有可预判错误在第一个 streaming chunk 前返回 @@ -171,6 +175,19 @@ confidence: high - 禁止：继续堆 helper、compatibility branch 或 reviewer-specific patch。 - 验收：恢复编码前 owner、consumer、删除项和 diff 预算都有可检查记录。 +### SERV-4i — multipart artifact 在 I/O 前验合同、在所有终态释放 + +- 触发：公开请求接收一个或多个 `UploadFile`、URL media，或把输入物化后交给后台任务。 +- 强制：在 read/download/persist/decode 前完成 dispatcher、模型 capability 与 + source/task matrix 校验；流式执行 count、per-file 和 aggregate byte 上限，超限返回 + 413；只清理由当前请求创建的 artifact，并保留输入顺序直到最终 consumer 完成。 +- 禁止：把无限 multipart 先复制到临时目录再校验；让非法组合进入 engine 后变成 sync + 500 或 async failed job；只在成功路径或 audio 分支 cleanup。 +- 验收：sync/async 都覆盖冲突 400、超限中途 413、setup 失败、generation 失败、timeout、 + cancellation、missing-job/early-return 与成功；无效请求未调用持久化或 engine，所有已创建 + 路径在每个终态消失，用户提供的非 owned 路径不被删除。MiniMax H3 的具体矩阵见 + [MiniMax H3 规则](../../models/minimax-h3/rules.md)。 ^[PR #5691] + ## Engine 生命周期合同 ### SERV-5a — sleep/wake 状态必须保留 stage 和 tag 作用域 @@ -192,5 +209,30 @@ confidence: high sleep → wake → generate，不支持的 stage 在调用 worker 前明确拒绝。 ^[PR #4834] ^[PR #4905] ^[PR #4912] +## Public CLI 兼容边界 + +### SERV-6a — 公开 serve 入口退役必须在所有 producer 上 fail closed + +- 触发：删除或改名 serve CLI option、wrapper/chart key 或公开配置文件入口。 +- 强制：parser、headless builder、脚本、chart、测试和公开 serving 文档在同一批迁移到 + canonical replacement；已删除的外部 key 必须显式拒绝并给出迁移目标。当前 serve + 部署 YAML 的唯一公开 flag 是 `--deploy-config`。 +- 禁止：删除是有意 breaking change 时又加静默 alias/fallback；wrapper 接受但忽略旧值； + 留下仍会发出旧 flag 的可运行命令。 +- 验收：replacement 可解析且到达最终 consumer，旧 option parser 失败；standard/headless + 发出同一 canonical 值，wrapper/chart 同时有正向与旧 key 拒绝测试，公开 serve 调用扫描 + 不再命中退役 flag。 ^[PR #5647] + +### SERV-6b — 兼容性按 ingress 分类，不能按同名 symbol 推断 + +- 触发：公开 CLI 已移除，但 Python/direct API、offline example 或 resolver 仍保留同名字段。 +- 强制：分别列出 public CLI、wrapper/chart、offline example、Python/direct 和内部 resolver； + public 行为由 Serving owner 决定，仍保留的 loader/schema 语义交给 + [Configuration rules](../configuration/rules.md) 并记录明确 follow-up 边界。 +- 禁止：因为仓库仍出现 `stage_configs_path` 就恢复公开 serve flag；也不能因为 public parser + 已删除就宣称所有内部兼容路径已移除。 +- 验收：公开 rejection 与 canonical forwarding 测试通过；每个暂留内部/direct 路径有独立 + compatibility test，直到后续迁移显式删除。 ^[PR #5647] + 请求到 engine 的边界见 [Serving architecture](architecture.md)；公开协议通用检查见 [review contracts](../../../../general/review/guides/reviewer-lens-contracts.md)。 diff --git a/knowledge/repos/vllm-omni/models/minimax-h3/_index.md b/knowledge/repos/vllm-omni/models/minimax-h3/_index.md new file mode 100644 index 0000000..d8dc51d --- /dev/null +++ b/knowledge/repos/vllm-omni/models/minimax-h3/_index.md @@ -0,0 +1,34 @@ +--- +title: "MiniMax H3" +created: 2026-08-04 +updated: 2026-08-04 +type: index +tags: [vllm-omni, models, diffusion] +sources: ["PR #5691", "PR #5699", "PR #5709", vllm_omni/diffusion/models/minimax_h3/] +confidence: high +--- + +# MiniMax H3 + +## 名称与范围 + +- 正式 owner：`MiniMaxH3Pipeline` / `MiniMaxAI/MiniMax-H3`。 +- checkpoint 分区：`FL2VA` 服务 T2VA/FL2VA；`Ref2VA` 服务 image+audio 或 + multi-video Ref2VA。 +- 主要源码：`vllm_omni/diffusion/models/minimax_h3/`；注册入口在 + `vllm_omni/diffusion/registry.py`。 +- 共享依赖：[Diffusion rules](../../components/diffusion/rules.md)、 + [Serving rules](../../components/serving/rules.md) 和 [CI rules](../../ci/rules.md)。 + +## 什么时候查这里 + +- 修改 H3 task/reference matrix、frame/audio/latent shape、text-encoder TP、专有 loader、 + reference audio fallback 或 joint video/audio accuracy oracle。 +- 问题属于共享 attention backend、HTTP artifact 生命周期或 CI 选择器时，回到上面的 + component owner，不把共享合同复制到模型页。 + +## 目录内容 + +| 遇到什么 | 查看哪里 | +|---|---| +| task/conditioning、数值 shape、并行 topology、权重加载、音频 fallback 或 accuracy evidence | [MiniMax H3 规则](rules.md) | diff --git a/knowledge/repos/vllm-omni/models/minimax-h3/rules.md b/knowledge/repos/vllm-omni/models/minimax-h3/rules.md new file mode 100644 index 0000000..2bde63d --- /dev/null +++ b/knowledge/repos/vllm-omni/models/minimax-h3/rules.md @@ -0,0 +1,118 @@ +--- +title: "MiniMax H3 规则" +created: 2026-08-04 +updated: 2026-08-04 +type: rule +tags: [vllm-omni, models, diffusion] +sources: ["PR #5691", "PR #5699", "PR #5709", vllm_omni/diffusion/models/minimax_h3/pipeline_minimax_h3.py, vllm_omni/diffusion/models/minimax_h3/reference_video.py, vllm_omni/diffusion/models/minimax_h3/encoder.py, tests/e2e/accuracy/minimax_h3/] +confidence: high +--- + +# MiniMax H3 规则 + +只有 `MMH3-数字字母` 是可审计规则 ID。 + +## Direct 代码快速入口 + +| PR 描述信号 | 规则组 | 第一批 live 源码 | +|---|---|---| +| T2VA/FL2VA/Ref2VA、partition、image/audio/video reference、batch | `task-conditioning`：`MMH3-1a` | checkpoint metadata → `pipeline_minimax_h3.py` task normalization/validation → public video dispatcher | +| fps、frame/latent alignment、audio rate、spatial shape、VAE dtype、condition pinning | `numerical-shape`：`MMH3-1b` | `time_request.py` → `pipeline_minimax_h3.py` → `vae.py` → `denoise_loop.py` | +| CFG、text-encoder TP、DiT TP、Ulysses、VAE tile parallel | `parallel-topology`：`MMH3-2a` | `pipeline_minimax_h3.py::_build_text_encoder_group` → encoder collectives → transformer/VAE validators | +| QKV、gate/up、retained encoder layer、FP8/quantization loader | `checkpoint-loading`：`MMH3-2b` | `encoder.py::{_map_weight_name,_load_weights}` → fused parameter `weight_loader` | +| torchaudio、TorchCodec、soundfile、ffmpeg、reference soundtrack | `reference-audio`：`MMH3-3a` | `reference_video.py::{load_audio_file,load_video_audio}` → pipeline `_load_audio` → audio VAE | +| official T2VA reference、golden revision、SSIM/PSNR、audio quality | `joint-accuracy`：`MMH3-4a` | `tests/e2e/accuracy/minimax_h3/` exact case → `/v1/videos/sync` → video/audio scorers | + +| 审查组 | 什么时候触发 | 规则 ID | +|---|---|---| +| `core` | 每次 MiniMax H3 审查 | `MMH3-1a`, `MMH3-1b` | +| `task-conditioning` | task、partition、reference source、batch | `MMH3-1a` | +| `numerical-shape` | frame/audio/latent shape、dtype、condition rows | `MMH3-1b` | +| `parallel-topology` | 任一并行 axis 或 distributed reference encode | `MMH3-2a` | +| `checkpoint-loading` | mapper、fused parameter、retained layer、quantization | `MMH3-2b` | +| `reference-audio` | audio/video decode backend 或平台适配 | `MMH3-3a` | +| `joint-accuracy` | golden、revision、阈值、支持声明 | `MMH3-4a` | + +## Task、shape 与 conditioning + +### MMH3-1a — partition、task 和 conditioning source 作为一张矩阵校验 + +- 触发：修改 checkpoint task metadata、video API reference 字段、H3 task 路由或 batch。 +- 强制：`FL2VA` partition 只接受无 media 的 T2VA 或恰好一张 image 的 FL2VA； + `Ref2VA` partition 只接受“恰好一张 image + 一条 standalone audio”或“按表单顺序的一条 + 及以上 video，使用各自 soundtrack 且无 standalone audio”；prompt 非空，当前 diffusion + batch 只接受一个请求。公开入口必须按 [SERV-4i](../../components/serving/rules.md) 在 I/O + 前执行同一矩阵。 +- 禁止：跨 partition/task fallback；混合 image/video source；multi-video 再带 + `audio_reference`；让非法组合进入 engine 后才失败。 +- 验收：每个正向 cell 和所有相邻负向 cell 都经过 pipeline 与 sync/async 公开入口； + 错误为一致 4xx，且负向 case 未持久化文件、未启动 model generation。 ^[PR #5691] + +### MMH3-1b — timing、latent shape 和 condition pinning 属于 checkpoint 数值合同 + +- 触发：修改 duration/frame 归一化、video/audio latent、spatial padding、VAE dtype、seeded + preprocessing 或 denoise condition row。 +- 强制：保持 24 FPS、frame 数 `17n+5`、video latent 长度 `5n+2`、audio latent 40 Hz、 + spatial dimension 对齐 32；video VAE 的 FP32 边界和每步重新 pin condition rows 必须由 + 明确 checkpoint 证据才能改变。 +- 禁止：用通用 `round()` 或相邻模型的公式替代 H3 对齐；为省显存静默降低 VAE 精度； + 只在初始 step 固定 conditioning 后允许后续 denoise 漂移。 +- 验收：边界 duration/size 的 exact-vector 与 round-trip 测试覆盖 dtype 和 latent shape；固定 + seed 逐步断言 condition rows，最终 MP4 同时验证 24 FPS 和 32 kHz audio metadata。 + ^[PR #5691] + +## 并行与 checkpoint + +### MMH3-2a — 每个并行 axis 独立 fail fast，encoder subgroup 对所有 rank 都有定义 + +- 触发：修改 CFG、text-encoder TP、DiT TP、Ulysses/Ring、VAE parallel 或 distributed + reference encode。 +- 强制：CFG size 固定为 1；encoder TP 是前 N 个 DiT rank 的合法 subgroup，并满足 + attention head/KV divisibility；DiT TP 与 Ulysses 分别满足维度约束；VAE parallel 只用 + native tile 且 size 为 1 或完整 DiT group。所有 world rank 以同一顺序创建 group；成员 + 获得 coordinator，非成员获得不访问 group membership/collective 的安全 handle。 +- 禁止：把 `NON_GROUP_MEMBER` 包成要求当前 rank 属组的 coordinator；只在 N=world 时测 + encoder TP；让不同 rank 因 reference 类型不同而跳过 collective。 +- 验收：多进程覆盖 N=1、N