[SKILL] Sync SGLang skill docs (#23921)

2026-04-28 17:05:36 +08:00
parent 71160e4ddb
commit 7824903417
25 changed files with 4199 additions and 1949 deletions
@@ -246,10 +246,14 @@ The `PipelineConfig` holds static model configuration and defines callback metho

 from dataclasses import dataclass, field

+import torch
+
+from sglang.multimodal_gen.configs.models import DiTConfig, VAEConfig
 from sglang.multimodal_gen.configs.pipeline_configs.base import (
-    ImagePipelineConfig,      # for image generation
-    # SpatialImagePipelineConfig,  # alternative base
-    # VideoPipelineConfig,         # for video generation
+    ImagePipelineConfig,
+    ModelTaskType,
+    # PipelineConfig,              # common base for many video pipelines
+    # SpatialImagePipelineConfig,  # alternative base for spatial image models
 )
 from sglang.multimodal_gen.configs.models.dits.mymodel import MyModelDitConfig
 from sglang.multimodal_gen.configs.models.vaes.mymodel import MyModelVAEConfig
@@ -314,6 +318,11 @@ class MyModelPipelineConfig(ImagePipelineConfig):
        return frames
 ```

+There is no separate `VideoPipelineConfig` base class. For video models, choose
+`ModelTaskType.T2V`, `ModelTaskType.I2V`, or `ModelTaskType.TI2V`, and follow
+existing video configs such as Wan, LTX, Hunyuan, Helios, or MOVA when deciding
+whether to subclass `PipelineConfig` directly or use a model-specific base.
+
 **Important**: The `prepare_pos_cond_kwargs` / `prepare_neg_cond_kwargs` methods define what the DiT receives at each denoising step. These must match the DiT's `forward()` signature.

 ### Step 6: Implement the BeforeDenoisingStage (Core Step)
@@ -502,15 +511,21 @@ In `python/sglang/multimodal_gen/registry.py`, register your configs:

 ```python
 register_configs(
-    model_family="my_model",
    sampling_param_cls=MyModelSamplingParams,
    pipeline_config_cls=MyModelPipelineConfig,
    hf_model_paths=[
        "org/my-model-name",  # HuggingFace model ID(s)
    ],
+    model_detectors=[
+        lambda path: "my-model" in path.lower(),
+    ],
 )
 ```

+`register_configs()` does not take a `model_family` argument. It registers the
+sampling and pipeline config classes, then resolves models by exact
+`hf_model_paths` or optional detector predicates.
+
 The `EntryClass` in your pipeline file is automatically discovered by the registry's `_discover_and_register_pipelines()` function -- no additional registration needed for the pipeline class itself.

 ### Step 9: Verify Output Quality
@@ -590,4 +605,5 @@ After the model produces non-noise output, read
 [references/testing-and-accuracy.md](references/testing-and-accuracy.md) before
 adding GPU cases, component-accuracy skips/hooks, suite entries, or benchmark
 claims. That reference tracks the current `gpu_cases.py` / `testcase_configs.py`
-/ `run_suite.py` split and the component-accuracy decision rules.
+/ `accuracy_testcase_configs.py` / `run_suite.py` split and the component-accuracy
+decision rules.
@@ -7,6 +7,9 @@ produce a non-noise image or video.

 - Add concrete GPU integration cases in `python/sglang/multimodal_gen/test/server/gpu_cases.py`.
 - Keep reusable dataclasses, constants, thresholds, and testcase factory helpers in `python/sglang/multimodal_gen/test/server/testcase_configs.py`.
+- Add the case id to `python/sglang/multimodal_gen/test/server/accuracy_testcase_configs.py`
+  only when it should be part of component-accuracy coverage. Adding a GPU case
+  alone does not enroll it there.
 - Let `python/sglang/multimodal_gen/test/run_suite.py` own suite selection, runtime-based partitioning, and standalone test files. Do not hard-code CI shard lists elsewhere.
 - If a new standalone test file is added to a suite, update `STANDALONE_FILE_EST_TIMES` after the first measured CI/runtime value is known.

@@ -22,8 +25,8 @@ PYTHONPATH=python python3 python/sglang/multimodal_gen/test/run_suite.py --suite

 If you add a new entry to `ONE_GPU_CASES`, `TWO_GPU_CASES`, or a B200-specific
 case group in `gpu_cases.py`, treat component accuracy as part of the
-model-adding workflow. Do not assume the new testcase will automatically fit the
-existing component-accuracy harness.
+model-adding workflow. Do not assume the new testcase will automatically fit or
+enter the existing component-accuracy harness.

 The component-accuracy harness compares SGLang components against Diffusers/HF
 reference components. This is stricter than pipeline-level inference. New GPU
@@ -46,9 +49,12 @@ cases commonly fail here for one of three reasons:

 When adding a new GPU case, make this decision explicitly:

+- if the case should have component-accuracy coverage, add its case id to
+  `accuracy_testcase_configs.py`
 - if the family needs minimal harness wiring, add the smallest possible change in `accuracy_hooks.py`
 - if the case is only a variant of an already covered source component and topology, add a skip in `accuracy_config.py`
 - if the HF/Diffusers reference component cannot be compared faithfully, add a skip in `accuracy_config.py`
+- if the case is intentionally GPU-smoke-only, leave it out of `accuracy_testcase_configs.py` and keep that choice explicit in the PR notes

 Do not add a new GPU case and wait for CI to discover missing component-accuracy
 wiring.
@@ -32,6 +32,7 @@ First use [../sglang-diffusion-benchmark-profile/SKILL.md](../sglang-diffusion-b
 - collect the perf dump baseline
 - capture one representative `torch.profiler` trace
 - rule out existing mainline fast paths
+- prove the run stayed on the native SGLang diffusion backend, not a diffusers fallback

 If a future specialized optimization skill matches the kernel family better than AKO4ALL, hand off there instead. The diagnosis contract stays the same.

@@ -127,5 +128,9 @@ See [references/ako-loop.md](references/ako-loop.md) for the checklist and commo

 - Treat AKO4ALL repo hygiene as a gate, not a suggestion.
 - Prefer exact local snapshot validation over hand-wavy “remote tree is close enough”.
+- Do not start or justify kernel work from traces collected after
+  `Falling back to diffusers backend`, `Using diffusers backend`, or
+  `Loaded diffusers pipeline`; fix backend selection and rerun the
+  benchmark/profile workflow first.
 - Keep model-level validation honest: if microbench improves but denoise does not, do not keep the AKO-only variant in the main code path.
 - When writing conclusions, explain the win in terms of measurable causes such as lower registers per thread, higher occupancy, fewer executed instructions, or better scheduler eligibility.