knowledge(vllm-omni): 2 change(s) from refine

knowledge/repos/vllm-omni/components/configuration/_index.md

@@ -61,3 +61,5 @@ sources: ["claude-workflow-starter-private@296ea45", vllm_omni/config/]
 - [性能基准扩档与基线推导规则](rules-perf-baseline-derivation.md)
 - [Thinker prefix cache deploy 默认值](rules-thinker-prefix-cache.md)
 - [vLLM-Omni 配置：环境变量清单与测试同步规则](rules-environment-variables.md)
+- [vllm-omni 配置 · engine args 评审规则](rules-engine-args.md)
+- [Torch Compile Hash 稳定性与模型侧编译日志规则](rules-compile-hash.md)

knowledge/repos/vllm-omni/components/configuration/rules-compile-hash.md

@@ -0,0 +1,19 @@
+---
+title: "Torch Compile Hash 稳定性与模型侧编译日志规则"
+created: 2026-10-26
+updated: 2026-10-26
+type: rule
+tags: [vllm-omni, components, config]
+sources: ["PR #8899"]
+---
+
+# Torch Compile Hash 稳定性与模型侧编译日志规则
+
+## VLLM-OMNI-PR8899-COMPILE-HASH — torch compile hash 必须排除 per-launch UUID 且模型侧编译要可观测
+
+- 触发：修改会进入 vLLM `ModelConfig` hash factors 的 Omni 字段（`stage_connector_config`、`omni_kv_config` 里的 `connector_config`、含 `wakeup_scope` 等 per-launch `extra` key 的 transfer config），或模型在 vLLM compile wrapper 之外直接调用 `torch.compile`（如 `qwen3_code_predictor.py` 的 `_setup_compile`）。
+- 强制：`OmniModelConfig.compute_hash()` 必须在对象浅拷贝上先用 `connector_hash_factors()`（`vllm_omni/distributed/omni_connectors/utils/config.py`，当前排除集合 `PER_LAUNCH_EXTRA_KEYS = {"wakeup_scope"}`）过滤 `stage_connector_config` 与 `omni_kv_config` 中的 `connector_config`（浅拷贝共享内层 dict，替换前先复制该 dict），再委托 upstream `compute_hash()`；模型实际读取的 connector 设置（如 `extra.codec_chunk_frames`）必须继续改变 hash。`torch.compile` 是惰性的：模型侧直接编译要用 `vllm_omni/utils/torch_compile.py` 的 `log_torch_compile_stats` 包裹触发首次编译执行的调用块（本例 `_setup_compile` 内包住 `_warmup_buckets()`），而不是包裹 `torch.compile` 调用本身，以记录该 block 的 Inductor FX graph cache hit/miss/bypass 与耗时。把环境变量纳入 inventory（本例 `TORCHINDUCTOR_CACHE_DIR` 归入 PLATFORM_EXTERNAL）必须同步 `environment_variable_inventory.py` 分类与数量快照。
+- 禁止：让 per-launch UUID 留在 compile cache key 中，使重复启动本应命中的编译与后续依赖 `TORCHINDUCTOR_CACHE_DIR` 的启动期编译（如 code predictor）出现不必要的 cache miss；为求 hash 稳定直接 mutate `self` 或过滤掉模型实际读取的 connector 设置；把 `log_torch_compile_stats` 包在 `torch.compile` 调用处（惰性编译下记录不到执行统计）或省略模型侧编译的可观测性；纳入/调整 inventory 环境变量而不更新分类与快照计数。
+- 验收：用真实 deploy YAML（qwen3_tts）对 stage 0/1 各构建两次 `OmniEngineArgs.create_engine_config().compute_hash()`，断言同一配置两次 hash 相同；再断言改变 `codec_chunk_frames` 等 connector extra 仍产生不同 hash（`tests/engine/test_arg_utils.py`）；env inventory 分类与数量快照同步通过（PLATFORM_EXTERNAL 30→31）。^[PR #8899]
+
+<!-- kb:rule status=active since=v0.30.0 -->

knowledge/repos/vllm-omni/components/configuration/rules-engine-args.md

@@ -0,0 +1,19 @@
+---
+title: "vllm-omni 配置 · engine args 评审规则"
+created: 2026-10-26
+updated: 2026-10-26
+type: rule
+tags: [vllm-omni, components, config]
+sources: ["PR #8585"]
+---
+
+# vllm-omni 配置 · engine args 评审规则
+
+## VLLM-OMNI-PR8585-DIFFARGS-FROMCLI — 非并行 diffusion engine 参数必须在 OmniEngineArgs 声明并镜像 SHARED_FIELDS
+
+- 触发：改动 `vllm_omni/engine/arg_utils.py` 中 `OmniEngineArgs` 的 diffusion 字段声明或 `SHARED_FIELDS` 集合；新增、改名或删除 serve CLI 注册在 `OrchestratorArgs` 上、而 diffusion stage 引擎会消费的非并行 engine 参数（含 `vllm_omni/engine/stage_init_utils.py` 对这些参数的下游传递）；或改动 `tests/engine/test_arg_utils.py` 的非并行参数测试与 `DIFFUSION_NON_PARALLEL_ENGINE_ARGS` 表。
+- 强制：`OmniEngineArgs.from_cli_args`（继承自 vLLM `EngineArgs.from_cli_args`）只保留 dataclass 已声明的字段，未声明的 knob 在库路径上于到达 diffusion stage 前被静默丢弃（#8503 的根因，是 #7564/#7652 只覆盖 `text_encoder_tp_size` 的失效模式的推广）。因此每个此类非并行参数（`num_gpus`、`cache_backend`、`cache_config`、`step_execution`、`flow_shift`、`boundary_ratio`、`vae_use_tiling`、`diffusion_compile_*`、`diffusion_load_format`、`diffusion_kv_cache_*`、`diffusion_offload_config`、`default_sampling_params` 等）都必须以 `None` 默认值声明在 `OmniEngineArgs` 上，使 unset 值保持未设置不向下游传播；并因两个类同时声明而镜像进 `SHARED_FIELDS`（由 `tests/engine/test_arg_utils_shared_fields.py` 守护）。新增此类参数时必须同步加入 `DIFFUSION_NON_PARALLEL_ENGINE_ARGS`，且取值须与 `OmniDiffusionConfig` 默认值不同，使被静默重置的字段能被 `test_from_cli_args_preserves_non_parallel_diffusion_engine_args` 抓住；落地语义由 `test_non_parallel_diffusion_engine_args_reach_default_diffusion_config` 式验证：显式覆盖经 `StageConfigFactory.create_default_diffusion` 后，`cache_backend`/`step_execution`/`flow_shift` 等直达 `engine_args`，`num_gpus` 解析为 `parallel_config.data_parallel_size`。既有 raw-kwargs 的 `validate_omni_diffusion_kwargs` fail-closed 校验保持不变。
+- 禁止：让新的非并行 diffusion 参数只存在于 `OrchestratorArgs` 而不声明到 `OmniEngineArgs`（库路径会静默丢弃）；把这些字段的 dataclass 默认值写成非 `None` 常量使 unset 值被传播；把 orchestrator 专属字段（`enable_ar_profiler`、`log_file`、`replica_id`、`omni_replica_address`）声明到 `OmniEngineArgs`；把 #8037 的 11 个并行 knob（由 #8041 处理，与本集合字段不相交）混入本规则范围；测试取值与 `OmniDiffusionConfig` 默认值相同，导致丢弃无法被发现；删除上述回归测试或从表中移除既有字段。
+- 验收：`pytest tests/engine/test_arg_utils.py`（含两个非并行参数测试）与 `tests/engine/test_arg_utils_shared_fields.py` 通过；`OmniEngineArgs` 声明的每个非并行 diffusion 字段默认值为 `None` 且出现在 `SHARED_FIELDS`；同一参数作为 raw kwargs 与 from_cli_args 路径均能到达 diffusion stage。^[PR #8585]
+
+<!-- kb:rule status=active since=v0.30.0 -->