[Test] Add a docs drift check for server_arguments.mdx (#38520)
Signed-off-by: Martin Hickey <martin.hickey@ie.ibm.com> Co-authored-by: Cheng Wan <54331508+ch-wan@users.noreply.github.com> Co-authored-by: Cheng Wan <cheng.wan@radixark.ai>
This commit is contained in:
co-authored by
Cheng Wan
Cheng Wan
parent
785005d21b
commit
f795fe352d
@@ -29,6 +29,8 @@ on:
|
||||
value: ${{ jobs.run.outputs.multimodal_gen }}
|
||||
renderer:
|
||||
value: ${{ jobs.run.outputs.renderer }}
|
||||
server_args_docs:
|
||||
value: ${{ jobs.run.outputs.server_args_docs }}
|
||||
rust_workspace:
|
||||
value: ${{ jobs.run.outputs.rust_workspace }}
|
||||
partitions:
|
||||
@@ -53,6 +55,7 @@ jobs:
|
||||
jit_kernel: ${{ steps.filter.outputs.jit_kernel || steps.run-mode.outputs.run_all_tests }}
|
||||
multimodal_gen: ${{ steps.filter.outputs.multimodal_gen || steps.run-mode.outputs.run_all_tests }}
|
||||
renderer: ${{ steps.filter.outputs.renderer || steps.run-mode.outputs.run_all_tests }}
|
||||
server_args_docs: ${{ steps.filter.outputs.server_args_docs || steps.run-mode.outputs.run_all_tests }}
|
||||
rust_workspace: ${{ steps.filter.outputs.rust_workspace || steps.run-mode.outputs.run_all_tests }}
|
||||
partitions: ${{ steps.partitions.outputs.partitions }}
|
||||
partition_model_sha: ${{ steps.partition-model-sha.outputs.sha }}
|
||||
@@ -115,6 +118,13 @@ jobs:
|
||||
renderer:
|
||||
- "rust/sglang-renderer/**"
|
||||
- "rust/sglang-processor/**"
|
||||
server_args_docs:
|
||||
# test_server_args_docs_coverage.py diffs this doc and its allowlist
|
||||
# against the CLI, so a docs only edit can break that test. Kept out
|
||||
# of main_package which also gates every GPU stage. Only the CPU
|
||||
# stage reads this.
|
||||
- "docs/docs/advanced_features/server_arguments.mdx"
|
||||
- "docs/docs/advanced_features/server_arguments_undocumented.txt"
|
||||
simulator:
|
||||
- ".github/workflows/pr-test-extra.yml"
|
||||
- ".github/workflows/_pr-test-simulator-cpu.yml"
|
||||
@@ -271,6 +281,7 @@ jobs:
|
||||
echo "| jit_kernel | ${{ steps.filter.outputs.jit_kernel || steps.run-mode.outputs.run_all_tests }} |"
|
||||
echo "| multimodal_gen | ${{ steps.filter.outputs.multimodal_gen || steps.run-mode.outputs.run_all_tests }} |"
|
||||
echo "| rust_workspace | ${{ steps.filter.outputs.rust_workspace || steps.run-mode.outputs.run_all_tests }} |"
|
||||
echo "| server_args_docs | ${{ steps.filter.outputs.server_args_docs || steps.run-mode.outputs.run_all_tests }} |"
|
||||
echo "| b200_runner | ${{ steps.set-runner.outputs.b200_runner }} |"
|
||||
echo "| enable_retry | ${{ steps.set-retry.outputs.enable_retry }} |"
|
||||
echo "| continue_on_error | ${{ steps.set-continue-on-error.outputs.continue_on_error }} |"
|
||||
|
||||
@@ -13,7 +13,7 @@ on:
|
||||
type: string
|
||||
required: true
|
||||
check_changes:
|
||||
description: 'toJson(needs.check-changes.outputs). Read via fromJson(...).main_package / renderer / rust_workspace / continue_on_error / partition_model_sha.'
|
||||
description: 'toJson(needs.check-changes.outputs). Read via fromJson(...).main_package / renderer / server_args_docs / rust_workspace / continue_on_error / partition_model_sha.'
|
||||
type: string
|
||||
required: true
|
||||
caller_inputs:
|
||||
@@ -49,7 +49,7 @@ jobs:
|
||||
# emits a skipped entry for wait-for-jobs to match. The schedule /
|
||||
# parallel-dispatch / !failure() half stays on the caller, where the
|
||||
# `needs` context it guards actually lives.
|
||||
if: fromJson(inputs.check_changes).main_package == 'true' || fromJson(inputs.check_changes).renderer == 'true'
|
||||
if: fromJson(inputs.check_changes).main_package == 'true' || fromJson(inputs.check_changes).renderer == 'true' || fromJson(inputs.check_changes).server_args_docs == 'true'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 240
|
||||
env:
|
||||
|
||||
@@ -5,3 +5,6 @@
|
||||
# Draft content
|
||||
drafts/
|
||||
*.draft.mdx
|
||||
|
||||
# Data read by test_server_args_docs_coverage.py, not a page
|
||||
advanced_features/server_arguments_undocumented.txt
|
||||
|
||||
@@ -780,12 +780,6 @@ Please consult the documentation below and [server_args.py](https://github.com/s
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`False`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>bool flag (set to enable)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--custom-sigquit-handler`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Register a custom sigquit handler so you can do additional cleanup after the server is shutdown. This is only available for Engine, not for CLI.</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`None`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Type: str</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--batch-notify-size`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Number of streaming notifications to batch before yielding to the event loop. Reduces asyncio wakeup overhead under high concurrency.</td>
|
||||
@@ -1611,6 +1605,12 @@ Combining `--enable-response-store` with `--disaggregation-mode=prefill` or `dec
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>The accept probability of a draft token is raised from its target probability p to min(1, p / threshold_acc).</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`1.0`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Type: float</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--speculative-use-block-verification`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Use block verification for EAGLE/EAGLE3/NEXTN on CUDA or ROCm (requires topk=1).</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`False`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Type: bool</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--speculative-token-map`</td>
|
||||
@@ -2968,12 +2968,6 @@ This option does not disable required attention or MoE collectives, including ex
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>The input filename for dumping tensors</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`None`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Type: str</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--debug-tensor-dump-inject`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Inject the outputs from jax as the input of every layer.</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`False`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Type: str</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
@@ -3050,8 +3044,8 @@ This option does not disable required attention or MoE collectives, including ex
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>bool flag (set to enable)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--optimistic-prefill-retries`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Number of optimistic prefill retries that will skip the bootstrap wait.</td>
|
||||
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--optimistic-prefill-attempts`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Number of optimistic prefill forward passes that skip the bootstrap wait.</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`0`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Type: int</td>
|
||||
</tr>
|
||||
@@ -3434,36 +3428,3 @@ This option does not disable required attention or MoE collectives, including ex
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
## Deprecated arguments
|
||||
<table style={{width: "100%", borderCollapse: "collapse", tableLayout: "fixed"}}>
|
||||
<colgroup>
|
||||
<col style={{width: "25%"}} />
|
||||
<col style={{width: "25%"}} />
|
||||
<col style={{width: "25%"}} />
|
||||
<col style={{width: "25%"}} />
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr style={{borderBottom: "2px solid #d55816"}}>
|
||||
<th style={{textAlign: "left", padding: "10px 12px", fontWeight: 700, whiteSpace: "nowrap", backgroundColor: "rgba(255,255,255,0.02)"}}>Argument</th>
|
||||
<th style={{textAlign: "left", padding: "10px 12px", fontWeight: 700, whiteSpace: "nowrap", backgroundColor: "rgba(255,255,255,0.05)"}}>Description</th>
|
||||
<th style={{textAlign: "left", padding: "10px 12px", fontWeight: 700, whiteSpace: "nowrap", backgroundColor: "rgba(255,255,255,0.02)"}}>Defaults</th>
|
||||
<th style={{textAlign: "left", padding: "10px 12px", fontWeight: 700, whiteSpace: "nowrap", backgroundColor: "rgba(255,255,255,0.05)"}}>Options</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<tr>
|
||||
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>`--hybrid-kvcache-ratio`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Mix ratio in [0,1] between uniform and hybrid kv buffers (0.0 = pure uniform: swa_size / full_size = 1)(1.0 = pure hybrid: swa_size / full_size = local_attention_size / context_length)</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`None`</td>
|
||||
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>Optional[float]</td>
|
||||
</tr>
|
||||
|
||||
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
# Live ServerArgs flags with no row in server_arguments.mdx. One flag per line.
|
||||
# test/registered/unit/server_args/test_server_args_docs_coverage.py reads this
|
||||
# list. It may only shrink: when you add a row for a flag, delete it here.
|
||||
--c128-page-size
|
||||
--constrained-json-max-whitespace-cnt
|
||||
--cuda-graph-prefill-max-context
|
||||
--decoupled-spec-bind-endpoint
|
||||
--decoupled-spec-connect-endpoints
|
||||
--decoupled-spec-rank
|
||||
--decoupled-spec-role
|
||||
--deepep-v2-mode
|
||||
--disable-aiter-allreduce-fusion-in-decode
|
||||
--disable-aiter-allreduce-fusion-in-prefill
|
||||
--disaggregation-decode-extra-slots
|
||||
--disaggregation-decode-host-receive-threshold
|
||||
--disaggregation-decode-retraction-backup
|
||||
--disaggregation-enable-kv-checksum
|
||||
--dsa-paged-mqa-logits-backend
|
||||
--dsv4-attn-backend
|
||||
--dsv4-prefill-backend
|
||||
--dwdp-size
|
||||
--elastic-ep-initial-size
|
||||
--elastic-ep-join-mode
|
||||
--elastic-ep-join-rank-offset
|
||||
--elastic-ep-scale-timeout
|
||||
--enable-cp-decode-attn-tp
|
||||
--enable-decoder-swa-bounded-replay
|
||||
--enable-dense-mlp-attn-tp
|
||||
--enable-dsa-cache-layer-split
|
||||
--enable-dsa-fused-indexer
|
||||
--enable-encoder-swa-bounded-replay
|
||||
--enable-flexkv
|
||||
--enable-layernorm-sp
|
||||
--enable-lean-attention
|
||||
--enable-linear-replayssm
|
||||
--enable-linear-replayssm-spec
|
||||
--enable-linker-mla-dedup
|
||||
--enable-pd-role-switch
|
||||
--enable-response-store
|
||||
--enable-scattered-sconv
|
||||
--enable-session-radix-cache
|
||||
--enable-shared-experts-attn-tp
|
||||
--enable-tp-lm-head-all-to-all
|
||||
--enable-unified-cache-external-linker
|
||||
--enable-w4a4-mxfp4-megamoe
|
||||
--flexkv-config-file
|
||||
--fuseep-mode
|
||||
--gated-launch-port
|
||||
--grpc-port
|
||||
--grpc-response-timeout-secs
|
||||
--hicache-host-memory-fraction
|
||||
--hicache-host-memory-mode
|
||||
--hicache-storage-prefetch-retry-max-attempts
|
||||
--hicache-storage-prefetch-retry-poll-interval
|
||||
--http2-initial-connection-window-size
|
||||
--linear-attn-verify-backend
|
||||
--linear-replayssm-cache-len
|
||||
--mamba-max-states-per-path
|
||||
--max-ep-size
|
||||
--min-free-slots-delay
|
||||
--mm-feature-transport
|
||||
--mm-global-cache-backend
|
||||
--mm-io-worker-num
|
||||
--mm-preprocess-cache-size-mb
|
||||
--mm-processor-worker-num
|
||||
--otlp-service-name
|
||||
--prefill-decode-interval
|
||||
--prefill-kv-cache-dequant-dtype
|
||||
--qsa-indexer-dtype
|
||||
--radix-eviction-policy-config
|
||||
--return-input-ids
|
||||
--return-output-ids
|
||||
--sampling-mask-max-tokens
|
||||
--shared-experts-tp-size
|
||||
--sidecar
|
||||
--sidecar-args
|
||||
--smg-grpc-mode
|
||||
--spec-trace-dir
|
||||
--speculative-domino-candidate-pool-size
|
||||
--speculative-draft-kv-cache-dtype
|
||||
--speculative-draft-sink-size
|
||||
--speculative-dspark-align-verify-tokens-to-graph-tier
|
||||
--speculative-dspark-block-size
|
||||
--speculative-dspark-confidence-sts-path
|
||||
--speculative-dspark-sps-table-path
|
||||
--speculative-use-rejection-sampling
|
||||
--startup-weight-load-mode
|
||||
--swa-prefix-tails
|
||||
--trust-mm-content-hashes
|
||||
--trust-request-chat-template
|
||||
--unified-cache-external-linker-backend
|
||||
--uno-lora-path
|
||||
--weight-cache-mode
|
||||
--weight-cache-socket
|
||||
--weight-cache-timeout
|
||||
@@ -0,0 +1,145 @@
|
||||
"""Every live ServerArgs flag needs a row in server_arguments.mdx and every flag
|
||||
the doc names must still register. The allowlist may only shrink.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import re
|
||||
import unittest
|
||||
from collections.abc import Iterable
|
||||
from pathlib import Path
|
||||
|
||||
from sglang.srt.arg_groups.argparse_actions import (
|
||||
DeprecatedAction,
|
||||
DeprecatedAliasStoreAction,
|
||||
DeprecatedStoreConstAction,
|
||||
DeprecatedStoreTrueAction,
|
||||
)
|
||||
from sglang.srt.server_args import ServerArgs
|
||||
from sglang.test.ci.ci_register import register_cpu_ci
|
||||
from sglang.test.test_utils import CustomTestCase
|
||||
|
||||
register_cpu_ci(est_time=5, suite="base-a-test-cpu")
|
||||
|
||||
_DOC_DIR = Path(__file__).resolve().parents[4] / "docs" / "docs" / "advanced_features"
|
||||
_DOC_PATH = _DOC_DIR / "server_arguments.mdx"
|
||||
# Live flags with no row. May only shrink. Kept beside the doc, outside the
|
||||
# main_package CI paths, so a PR that backfills rows runs only the CPU stage.
|
||||
_UNDOCUMENTED_PATH = _DOC_DIR / "server_arguments_undocumented.txt"
|
||||
|
||||
_DEPRECATED_ACTION_TYPES = (
|
||||
DeprecatedAction,
|
||||
DeprecatedStoreTrueAction,
|
||||
DeprecatedStoreConstAction,
|
||||
DeprecatedAliasStoreAction,
|
||||
)
|
||||
|
||||
# Argument, Description, Defaults, Options.
|
||||
_DOC_COLUMNS = 4
|
||||
|
||||
# Only delimited mentions count, so a prose wildcard like `--cuda-graph-*`
|
||||
# never becomes a fabricated flag name.
|
||||
_ROW_FLAG_RE = re.compile(r"`(--[a-zA-Z0-9][\w-]*)`|<code>(--[a-zA-Z0-9][\w-]*)</code>")
|
||||
|
||||
|
||||
def _undocumented() -> frozenset[str]:
|
||||
lines = _UNDOCUMENTED_PATH.read_text(encoding="utf-8").splitlines()
|
||||
return frozenset(
|
||||
line.strip() for line in lines if line.strip() and not line.startswith("#")
|
||||
)
|
||||
|
||||
|
||||
_UNDOCUMENTED = _undocumented()
|
||||
|
||||
|
||||
def _parser_actions() -> tuple[list[argparse.Action], list[argparse.Action]]:
|
||||
parser = argparse.ArgumentParser(add_help=False)
|
||||
ServerArgs.add_cli_args(parser)
|
||||
live, deprecated = [], []
|
||||
for action in parser._actions:
|
||||
(deprecated if isinstance(action, _DEPRECATED_ACTION_TYPES) else live).append(
|
||||
action
|
||||
)
|
||||
return live, deprecated
|
||||
|
||||
|
||||
def _doc_rows() -> list[list[str]]:
|
||||
text = _DOC_PATH.read_text(encoding="utf-8-sig")
|
||||
rows = [
|
||||
re.findall(r"<td[^>]*>(.*?)</td>", row, re.S)
|
||||
for row in re.findall(r"<tr[^>]*>(.*?)</tr>", text, re.S)
|
||||
]
|
||||
# Header rows hold only <th> cells.
|
||||
return [cells for cells in rows if cells]
|
||||
|
||||
|
||||
def _flags_in(cells: Iterable[str]) -> set[str]:
|
||||
return {
|
||||
match.group(1) or match.group(2)
|
||||
for cell in cells
|
||||
for match in _ROW_FLAG_RE.finditer(cell)
|
||||
}
|
||||
|
||||
|
||||
class TestServerArgsDocsCoverage(CustomTestCase):
|
||||
@classmethod
|
||||
def setUpClass(cls):
|
||||
cls.live_actions, deprecated_actions = _parser_actions()
|
||||
cls.rows = _doc_rows()
|
||||
argument_column_flags = _flags_in(cells[0] for cells in cls.rows)
|
||||
cls.uncovered = {
|
||||
action.option_strings[0]
|
||||
for action in cls.live_actions
|
||||
# Any alias counts.
|
||||
if argument_column_flags.isdisjoint(action.option_strings)
|
||||
}
|
||||
registered = {
|
||||
o for a in cls.live_actions + deprecated_actions for o in a.option_strings
|
||||
}
|
||||
cls.stale = _flags_in(cell for cells in cls.rows for cell in cells) - registered
|
||||
|
||||
def test_every_row_has_four_cells(self):
|
||||
"""Coverage reads only the first cell. A row the cell regex splits wrongly
|
||||
can pass description text off as the Argument column and hide a gap."""
|
||||
misshapen = [cells[0][:80] for cells in self.rows if len(cells) != _DOC_COLUMNS]
|
||||
self.assertFalse(
|
||||
misshapen,
|
||||
f"these rows do not have {_DOC_COLUMNS} cells, so their first cell may "
|
||||
"not be the Argument column:\n " + "\n ".join(misshapen),
|
||||
)
|
||||
|
||||
def test_no_new_undocumented_flags(self):
|
||||
added = sorted(self.uncovered - _UNDOCUMENTED)
|
||||
self.assertFalse(
|
||||
added,
|
||||
"these live flags have no row in server_arguments.mdx and are not "
|
||||
"on the allow list. Add a row (lift the help text from the "
|
||||
"field's Arg(help=...)) or if it is a deliberate omission, add "
|
||||
f"it to {_UNDOCUMENTED_PATH.name}:\n " + "\n ".join(added),
|
||||
)
|
||||
|
||||
def test_undocumented_allowlist_is_current(self):
|
||||
live_options = {a.option_strings[0] for a in self.live_actions}
|
||||
outdated = []
|
||||
for flag in sorted(_UNDOCUMENTED - self.uncovered):
|
||||
reason = "now documented" if flag in live_options else "flag is gone"
|
||||
outdated.append(f"{flag} ({reason})")
|
||||
self.assertFalse(
|
||||
outdated,
|
||||
f"these entries in {_UNDOCUMENTED_PATH.name} are out of date. "
|
||||
"Remove them from the file:\n " + "\n ".join(outdated),
|
||||
)
|
||||
|
||||
def test_no_stale_rows(self):
|
||||
stale = sorted(self.stale)
|
||||
self.assertFalse(
|
||||
stale,
|
||||
"server_arguments.mdx names these flags but they no longer register "
|
||||
"as a current or deprecated flag. The flag was renamed (possibly via "
|
||||
"cli_name=) or removed, or its field has no CLI surface (no A[] "
|
||||
"annotation, or Arg(no_cli=True)). Fix or delete the mention:\n "
|
||||
+ "\n ".join(stale),
|
||||
)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user