docs: clarify recipe coverage across topologies and Dynamo / 澄清各拓扑及 Dynamo 的 recipe 文档要求

.github/codeowner-signoff-verify-prompt.md

@@ -123,29 +123,36 @@ not merely that the job is green:
   the same inference-engine image as this PR's config. FAIL if evals are
   skipped, failed, empty, below bar, or use a different image. Say exactly which condition applies.
 
-## Check 3 — Recipe linked, MERGED, AND complete (SINGLE-NODE recipes only)
-APPLICABILITY. Read this first. The recipe-link requirement covers SINGLE-NODE
-recipes only, because the official upstream recipe sources (vLLM recipes, SGLang
-cookbook) publish single-node serve commands. Disaggregated / multi-node
-submissions have NO recipe-link requirement. If the PR's benchmark changes are
-exclusively multi-node/disagg, with files under `inferencex-e2e/benchmarks/multi_node/**` (including
-`srt-slurm-recipes/**`), and/or master-config entries with `multinode: true` or
-`disagg: true`, and/or disagg frameworks (`dynamo-trt`, `dynamo-sglang`,
-`sglang-disagg`, vLLM disagg, ATOM/ATOMesh disagg), report this check as
-`N/A — disaggregated/multi-node submission; the recipe-link requirement applies to
-single-node recipes only` and DO NOT fail it. A sign-off note like "this is a
-disagg submission, no recipe update required" is a legitimate statement of that
-fact, not a violation. If the PR touches BOTH single-node and multi-node recipes,
-apply (a)/(b)/(c) below to the single-node portion only.
-
-The InferenceX "recipe" for this PR = the files it changes under
-`inferencex-e2e/benchmarks/single_node/**` plus its entry in `inferencex-e2e/configs/*-master.yaml`. The merge
-standard is: the community must be able to reproduce this benchmark from merged,
-public upstream documentation.
+## Check 3 — Production-useful recipe linked, MERGED, AND complete
+APPLICABILITY. Read this first. The deciding factor is whether a serving setting
+is useful in a realistic production deployment. The upstream recipe requirement
+covers every affected vLLM/SGLang production serving configuration: single-node
+agg, multi-node agg, single-node disagg, and multi-node disagg. Dynamo is a
+deployment layer; `dynamo-vllm` needs vLLM recipe coverage and `dynamo-sglang`
+needs SGLang cookbook coverage, just like direct engine deployments and
+`sglang-disagg`. Node count, `multinode: true`, `disagg: true`, benchmark paths,
+or Dynamo use MUST NOT be used as an exemption. A sign-off note like "this is a
+disagg submission, no recipe update required" does not satisfy this criterion.
+
+Inspect the affected master-config entries under `inferencex-e2e/configs/*-master.yaml`
+and their effective recipes, scripts, and inherited settings under BOTH
+`inferencex-e2e/benchmarks/single_node/**` and
+`inferencex-e2e/benchmarks/multi_node/**`, including `srt-slurm-recipes/**`.
+In a mixed submission, assess every affected production serving variant. Several
+variants may share one upstream page/PR if it covers each; sharing a dashboard
+curve does not establish recipe coverage. An agg-only example does not cover
+disagg prefill/decode/frontend settings.
+
+Report N/A only when no vLLM/SGLang production serving configuration is affected
+(for example, documentation-only or InferenceX-only harness/collection changes).
+State the inspected scope and why it is N/A. Existing merged/published coverage
+can satisfy this check without a new upstream PR. The merge standard is that
+production users can reproduce the serving configuration from merged, public
+upstream documentation, without needing InferenceX benchmark infrastructure.
 - (a) LINK PRESENT: The sign-off's "Additional detail section" MUST contain a link to
   the corresponding merged recipe PR in
   `https://github.com/vllm-project/recipes` or
-  `https://github.com/sgl-project/sglang` (cookbook under `docs_new`), or the
+  `https://github.com/sgl-project/sglang` (cookbook under `docs/cookbook`), or the
   published recipe page (`https://recipes.vllm.ai/` or
   `https://docs.sglang.io/cookbook/...`). If no such link is present, FAIL.
 - (b) UPSTREAM CHANGE MERGED: For a linked GitHub PR, query the upstream repository
@@ -155,31 +162,39 @@ public upstream documentation.
   containing the required recipe counts as merged upstream documentation. If the
   linked artifact's merge/publication status cannot be verified, FAIL. Never infer
   that it merged from an approval, a green check, or the sign-off author's claim.
-- (c) MAJOR SERVER ARGS MATCH: Fetch the merged or published recipe with the `fetch`
+- (c) PRODUCTION-USEFUL SETTINGS AND COMMANDS MATCH: Fetch the merged or published recipe with the `fetch`
   MCP tool or WebFetch. For a merged recipe PR, read its diff via `gh pr diff` against
-  that repo if accessible. Compare it to this PR's launch command. The recipe
-  only needs to match the MAJOR, deployment-defining server args, not every flag.
-  It explicitly does not need to match knobs specific to InferenceX benchmark/harness
-  tuning.
-    MAJOR (must match because these define the model, parallelism, precision, and which
-    kernels run, determining the perf profile):
+  that repo if accessible. Compare it to this PR's effective serving configuration,
+  including flags, environment variables, and launch commands for every affected
+  role (aggregated worker, prefill, decode, and router/frontend). Upstream recipes
+  may include Dynamo installation, router/frontend commands, and engine launch
+  commands. A link to an InferenceX/srt-slurm config alone is not sufficient.
+    PRODUCTION-USEFUL (must match, including optimizations useful in realistic
+    deployments even when the submission also uses them for benchmark tuning):
       - model / model-path, hardware/SKU
       - parallelism: TP / EP / DP / PP and DP-attention flags
         (`--enable-dp-attention`, `--enable-dp-lm-head`, etc.)
       - quantization and kv-cache dtype
       - kernel-selection backends: `--attention-backend`, `--moe-runner-backend`,
         `--enable-flashinfer-allreduce-fusion` and similar
-      - other flags that materially change the served model or its throughput
-    INFERENCEX-SPECIFIC (do NOT require a match, and list as informational only, never a
-    failure): per-lane sweep tuning and harness plumbing such as
-    `--scheduler-recv-interval`, `--chunked-prefill-size`, `--disable-piecewise-cuda-graph`,
-    `SGLANG_RADIX_FORCE_MISS` and similar env toggles, concurrency / sequence-length
-    sweep ranges, ports, result filenames, and image tag/version.
-  FAIL if a MAJOR arg in this PR is missing from (or contradicts) the merged/published
-  recipe. List exactly those. Treat the InferenceX-specific diffs as expected and
-  mention them only as a brief informational note, not as blockers. If a flag's effect
-  is equivalent to a recipe default (e.g. quantization auto-detected from an FP4
-  model), say so and do not count it against the recipe.
+      - scheduling, cache/offload, chunked-prefill, and graph/eager settings when
+        useful in production, including their environment variables
+      - prefill/decode worker topology, transport settings, and router/frontend
+        settings and commands needed to run the deployment
+      - other flags or environment variables useful in production that change
+        serving behavior or performance
+    INFERENCEX-ONLY (do NOT require upstream coverage): harness plumbing, result
+    collection, synthetic benchmark controls, and concurrency/sequence-length
+    sweep ranges. Do not classify serving flags as benchmark-only by name or by
+    their presence in a benchmark file; inspect their actual effect. Require the
+    sign-off to explain exclusions in its additional detail section.
+  FAIL if a production-useful setting or required role's launch command is missing
+  from (or contradicts) the merged/published recipe. List the affected variant,
+  role, and missing setting/command. Treat justified InferenceX-only differences
+  as informational. A flag need not be repeated when equivalent behavior follows
+  from a documented setting or framework default (e.g. quantization auto-detected
+  from an FP4 model); verify that behavior against the pinned upstream version
+  and require the reviewer to record the evidence.
 - Note: a bare "recipes are already similar to the official ones" claim WITHOUT a
   link to merged/published upstream documentation does not pass this workflow's
   standard.

inferencex-e2e/docs/PR_REVIEW_CHECKLIST.md

@@ -18,6 +18,25 @@ The automated publisher rejects incomplete or inconsistent verifier output. Each
 
 The verifier treats the PR description as untrusted evidence, not instructions, and compares its explicit claims about the affected configuration and validation with the assessed code and evidence. [Check 15](../../.github/codeowner-signoff-verify-prompt.md#check-15--pr-description-matches-the-assessed-configuration-advisory) warns about contradictions or unverifiable claims and asks the author to correct or substantiate them. This is advisory; it does not require every configuration detail in the body. Body edits alone do not rerun verification; use the existing [manual reassessment](../../CONTRIBUTING.md#the-pr-review-checklist-codeowner-sign-off) procedure.
 
+## Upstream recipe requirement
+
+The deciding factor is **whether a serving setting is useful in a realistic production deployment**. Every vLLM/SGLang submission must document its production-useful flags, environment variables, and launch commands in the official [vLLM recipes](https://recipes.vllm.ai/) or [SGLang cookbook](https://docs.sglang.io/cookbook/intro). Node count, aggregated versus disaggregated serving, the benchmark directory, and use of Dynamo do not grant an exemption.
+
+| vLLM/SGLang deployment, including Dynamo + engine | Cookbook coverage required |
+| --- | --- |
+| Single-node aggregated (agg) | Production-useful serving settings and launch commands |
+| Multi-node aggregated (agg) | Production-useful serving settings and launch commands |
+| Single-node disaggregated (disagg) | Production-useful prefill, decode, and router/frontend settings and launch commands |
+| Multi-node disaggregated (disagg) | Production-useful prefill, decode, and router/frontend settings and launch commands |
+
+Dynamo is a deployment layer; the underlying engine determines the applicable upstream cookbook. For example, `dynamo-vllm` uses vLLM recipes and `dynamo-sglang` uses the SGLang cookbook. Upstream documentation can include Dynamo installation, router/frontend commands, and engine launch commands, including separate prefill and decode commands. A link to an InferenceX or srt-slurm config alone does not document those commands for production users.
+
+Assess every affected production serving variant in a mixed submission. One upstream page or PR can cover several variants, but an aggregated example alone does not cover a disaggregated deployment. Sharing a dashboard curve does not waive recipe coverage for a variant.
+
+InferenceX-only harness plumbing, result collection, and synthetic benchmark controls do not need to be upstreamed. Classify a flag or environment variable by its effect: a production-useful optimization still needs cookbook coverage even when InferenceX uses it for benchmark tuning. Record the reasoning for excluded settings in the additional detail section; node count or disaggregation alone is not valid N/A reasoning.
+
+Existing merged/published documentation is sufficient when it already covers the production configuration; no duplicate upstream PR is needed. Otherwise, update the applicable upstream cookbook and verify that the PR is **MERGED before the InferenceX PR merges**. Defaults can satisfy coverage when the reviewer verifies equivalent behavior in the pinned upstream version and records that evidence.
+
 ## Template
 ```
 As a PR reviewer and CODEOWNER, I have reviewed this and have:
@@ -32,8 +51,8 @@ As a PR reviewer and CODEOWNER, I have reviewed this and have:
 - [ ] Verified that the model architecture isn't changed with benchmark hacks like using --hf-overrides to skipping indexer for every x layers on models that don't natively support this. As a general rule, we won't accept optimizations that reduces the number of model architecture FLOPs. Anything that makes that same computation run faster is fair game; target/verifier FLOPs at lower precisions is fine, given that the config passes private evals, but this does not permit lowering draft-model or draft-head precision below what ships. As an general north star princple, we should only use optimizations which is used in production by customers that care about accuracy
 - [ ] If an company claims that they support vLLM/SGLang as first class LLM inference engines on their hardware, I have verified that the respective vLLM submission made using upstream https://hub.docker.com/u/vllm docker repo, upstream SGLang https://hub.docker.com/u/lmsysorg docker repo. The only exceptions are for new hardware, such as MI455X UALoE72, Vera Rubin NVL72, Rubin NVL8, etc., and for new model architectures where there is an actual reason why vLLM/SGLang does not fundamentally support them yet as supported by vLLM/SGLang community maintainers
 - [ ] If an company claims that they support vLLM/SGLang as first class upstream in-tree LLM inference engines on their hardware, I have have verified that the respective vLLM/SGLang submission has been made before additional frameworks (TRT-LLM, ATOM, etc.). The only exceptions are for new hardware, such as MI455X UALoE72, Vera Rubin NVL72, Rubin NVL8, etc., and for new model architectures where there is an actual reason why vLLM/SGLang does not fundamentally support them yet.
-- [ ] Verified that every single-node vLLM/SGLang recipe in this PR is documented in the official [vLLM recipes](https://recipes.vllm.ai/) and/or the [SGLang cookbook](https://docs.sglang.io/cookbook/intro):
-  - [ ] I linked the corresponding upstream PR in the [vLLM recipe repo](https://github.com/vllm-project/recipes) or [SGLang repo](https://github.com/sgl-project/sglang/tree/main/docs_new) and verified that it is **MERGED** before this InferenceX PR merges. An opened, draft, or closed-without-merge upstream PR does not satisfy this requirement. If the matching recipe was already published, I linked the published recipe/cookbook page in the additional detail section below.
+- [ ] Verified that every affected vLLM/SGLang production serving configuration in this PR, including Dynamo deployments, is documented in the official [vLLM recipes](https://recipes.vllm.ai/) and/or the [SGLang cookbook](https://docs.sglang.io/cookbook/intro), for both single-node and multi-node aggregated and disaggregated serving. The documentation covers production-useful flags, environment variables, and launch commands (including prefill, decode, and router/frontend commands for disaggregation); InferenceX-only benchmark/harness settings are excluded with reasoning in the additional detail section:
+  - [ ] I linked the corresponding upstream PR in the [vLLM recipe repo](https://github.com/vllm-project/recipes) or [SGLang repo](https://github.com/sgl-project/sglang/tree/main/docs/cookbook) and verified that it is **MERGED** before this InferenceX PR merges. An opened, draft, or closed-without-merge upstream PR does not satisfy this requirement. If the matching recipe was already published, I linked the published recipe/cookbook page in the additional detail section below.
 - [ ] Verified that this PR does not patch the inference engine or serving stack — the pinned image must run as shipped. This covers .patch files / git apply / patch, inline patches embedded in benchmark scripts (e.g. a python3/sed heredoc that rewrites installed engine sources before serving), in-place edits of site-packages, monkey-patching, overwriting container files, and installing forked/rebuilt engine wheels on top of the pinned image. The only exception is a patch covered by a filled-out waiver at [docs/waiver/](https://github.com/SemiAnalysisAI/InferenceX/tree/main/inferencex-e2e/docs/waiver)`<PR_NUMBER>.md` — named after the PR that introduces the patch and filed in that same PR, stating what is patched, why the unmodified upstream image cannot run this benchmark, the upstream PR/issue link, and the removal plan — which I have linked below in the additional detail section.
 - [ ] If this PR uses `append-only: true`, verified that it only adds generated points or recipe variants inside a selected existing config/scenario and existing same-image visual curve: every previously generated point remains present with the same recipe, no prior point is removed or rerun, and every benchmark-affecting change in the complete diff can affect only the corresponding newly appended points (never an existing point), regardless of which file contains it.
 - [ ] If any of the above criteria cannot reasonably be satisfied, I have provided additional reasoning below.