执行摘要

• 一句话：重构 SGLang-Diffusion 文档，区分无损/有损优化并更新模型兼容表
• 推荐动作：对于文档维护者，值得精读本 PR 的分类方式和结构，特别是 performance-optimization.mdx 作为调优入口点的设计（区分无损/有损）以及 compatibility_matrix.mdx 的表格化管理方案。对于开发者，只需关注更新后的 CLI 参数和优化优先级。无需深入审查。

功能与动机

原先的文档以一次性基准测试和特性笔记为主，缺乏稳定且分类清晰的用户导向页面。作者在 PR body 中提出要 'Reorganize the SGLang-Diffusion docs around stable user-facing pages instead of feature notes and one-off benchmark notes'，并且 'Update the performance docs to separate output-preserving/system-level optimizations from approximate/quality-tradeoff optimizations'，旨在让性能调优入口更清晰，防止用户混淆无损和有损优化。

实现拆解

1. 重构导航配置 (docs_new/docs.json)：将 SGLang Diffusion 的页面重新分组为 Usage、Performance Optimization、Caching Acceleration（带 approx 标签）、References 和 Development 五大块，移除了旧的 Inference Batching 组将其合并到 Performance Optimization 组，并调整了多个页面的顺序，使结构更扁平易浏览。
2. 重写性能优化入口 (docs_new/docs/sglang-diffusion/performance-optimization.mdx)：从简要概览改为中心决策页面，明确区分输出保持（无损）和近似（有损）两类优化，并给出推荐的调优优先级顺序：先选择 Serving 模式 → Attention 后端 → 序列并行 → 批处理 → 性能分析。
3. 大幅更新模型兼容性矩阵 (docs_new/docs/sglang-diffusion/compatibility_matrix.mdx)：从简单叙述改为包含表格的分 Tab 结构（Image / Video / Long-tail），列出 FLUX、Z-Image、Qwen-Image、SD3/SD3.5、SANA 等家族及其 Hugging Face ID；同时保留详细的 per-optimization 矩阵。
4. 转换环序列并行页 (docs_new/docs/sglang-diffusion/ring_sp_performance.mdx)：从具体的 Wan2.2-TI2V-5B 基准测试页改为通用的序列并行配置指南，说明 --sp-degree、--ulysses-degree、--ring-degree 的关系，并提供推荐命令。
5. 添加自定义 CSS 样式 (docs_new/custom.css)：新增 .sgd-model-table-wrap、.sgd-model-table、.sgd-chip、.sgd-id-list 等十余个类，专门用于美化模型兼容性表格和芯片标签，支持亮/暗模式。
6. 更新附属文档：小幅修改 index.mdx（索引页增加概述）、installation.mdx（更新 pip 命令示例）、teacache.mdx（添加 tag: approx 并修正阈值说明）、cli.mdx（命令行参数示例）、deployment_cookbook.mdx（引用新文档结构）、caching-acceleration.mdx、progressive_resolution.mdx 等，使整体文案和链接保持一致。

关键文件：

• docs_new/docs/sglang-diffusion/compatibility_matrix.mdx（模块 文档页面；类别 other；类型 core-logic）: 改动最大（+179/-144），从简短列表转为含选项卡和表格的模型兼容性矩阵，新增 FLUX、Z-Image、Qwen-Image 等族表，是用户查找支持模型的核心页面。
• docs_new/docs/sglang-diffusion/performance-optimization.mdx（模块 文档页面；类别 other；类型 core-logic）: 重写为性能调优决策入口，明确区分输出保持和无损/近似两类优化，并提出推荐的调优优先级，是理解整个文档组织思想的关键。
• docs_new/docs.json（模块 导航配置；类别 config；类型 configuration）: 定义侧边栏导航结构，将页面重新分组为 Usage、Performance Optimization（内含 Caching Acceleration 子组）、References、Development，直接影响用户浏览路径。
• docs_new/custom.css（模块 样式表；类别 other；类型 core-logic）: 新增约120行 CSS，用于美化模型兼容性表格和芯片标签，支持亮/暗模式，直接提升文档视觉一致性和可读性。
• docs_new/docs/sglang-diffusion/ring_sp_performance.mdx（模块 文档页面；类别 other；类型 core-logic）: 从特定模型基准测试转换为通用序列并行配置指南，添加推荐命令和度选择表格，改变文档性质，是这次重构中内容转型的代表。

关键符号：未识别

关键源码片段

docs_new/docs.json

定义侧边栏导航结构，将页面重新分组为 Usage、Performance Optimization（内含 Caching Acceleration 子组）、References、Development，直接影响用户浏览路径。

// docs_new/docs.json 中 SGLang Diffusion 导航组配置（核心部分）
{
  "group": "SGLang Diffusion",
  "icon": "sparkles",
  "pages": [
    "docs/sglang-diffusion/index",
    "docs/sglang-diffusion/installation",
    "docs/sglang-diffusion/compatibility_matrix",
    "docs/sglang-diffusion/disaggregation",
    {
      "group": "Usage",
      "pages": [
        "docs/sglang-diffusion/api/cli",
        "docs/sglang-diffusion/api/openai_api",
        "docs/sglang-diffusion/api/post_processing"
      ]
    },
    {
      "group": "Performance Optimization",
      "pages": [
        "docs/sglang-diffusion/performance-optimization",
        // ... 其他页面
        {
          "group": "Caching Acceleration",
          "root": "docs/sglang-diffusion/caching-acceleration",
          "tag": "approx",  // 明确标注为近似优化
          "pages": [
            "docs/sglang-diffusion/cache_dit",
            "docs/sglang-diffusion/teacache"
          ]
        },
        "docs/sglang-diffusion/progressive_resolution",
        "docs/sglang-diffusion/quantization",
        "docs/sglang-diffusion/profiling"
      ]
    },
    {
      "group": "References",
      "pages": ["docs/sglang-diffusion/environment_variables"]
    },
    {
      "group": "Development",
      "pages": [
        "docs/sglang-diffusion/support_new_models",
        "docs/sglang-diffusion/ci_perf",
        "docs/sglang-diffusion/contributing"
      ]
    }
  ]
}

/ 重点：Caching Acceleration 子组增加了 "tag": "approx" 标记，在侧边栏可显示标签，帮助用户区分无损/有损优化。 /

docs_new/custom.css

新增约120行 CSS，用于美化模型兼容性表格和芯片标签，支持亮/暗模式，直接提升文档视觉一致性和可读性。

/* docs_new/custom.css — 新增的 SGLang Diffusion 模型表格样式 */
​
/* 表格外层容器，带圆角和滚动 */
.sgd-model-table-wrap {
  margin: 1rem 0 1.5rem;
  overflow-x: auto;
  border: 1px solid rgba(17, 24, 39, 0.12);
  border-radius: 8px;
  background: rgba(255, 255, 255, 0.55);
  scrollbar-width: thin;
}
​
/* 表格本身，最小宽度确保列不挤压 */
.sgd-model-table {
  min-width: 760px;
  table-layout: auto;
  border-collapse: separate;
  border-spacing: 0;
  font-size: 0.875rem;
}
​
/* 表头使用橙色色调 */
.sgd-model-table thead th {
  border-bottom: 1px solid rgba(213, 88, 22, 0.24);
  background: rgba(213, 88, 22, 0.08) !important;
  color: rgb(124, 45, 18);
}
​
/* 芯片标签，用于显示优化标识 */
.sgd-chip {
  display: inline-flex;
  align-items: center;
  margin: 2px 4px 2px 0;
  padding: 2px 8px;
  border: 1px solid rgba(213, 88, 22, 0.22);
  border-radius: 999px;
  background: rgba(213, 88, 22, 0.08);
  color: rgb(154, 52, 18);
  font-size: 0.75rem;
  font-weight: 650;
}
​
/* 暗色模式适配 */
html.dark .sgd-model-table-wrap {
  border-color: rgba(255, 255, 255, 0.12);
  background: rgba(255, 255, 255, 0.025);
}

评论区精华

该 PR 由作者自行合并，无 review 讨论。仅存在 gemini-code-assist[bot] 的两条自动配额警告，无实质讨论。

• 暂无高价值评论线程

风险与影响

• 风险：低风险。纯文档变更，不影响运行时。但需注意：
  • docs.json 中删除了 docs/sglang-diffusion/quantization 等页面的独立条目，改为嵌套在 Performance Optimization 组下，若用户收藏了旧 URL 可能需手动适应（但 docs 侧边栏路径未变，仅导航树结构调整）。
  • ring_sp_performance.mdx 从特定模型基准测试改为通用指南，原先的基准数据完全移除，若用户依赖旧数据可能需要访问 git 历史。
  • CLI 命令示例中的路径从绝对路径 /model/HuggingFace/... 改为相对路径 Wan-AI/...，需确保用户理解不同。
  • 无自动化测试覆盖文档的渲染结果，但作者已检查 Mintlify 本地预览。
  • 影响：直接影响：文档用户（开发者、部署工程师）将看到更清晰的侧边栏分组、表格化模型兼容信息以及性能调优的优先级指南。间接影响：文档维护者将更容易在分组中添加新模型或优化，而不需要重新组织整体结构。范围：仅限 docs_new/ 目录下的 SGLang Diffusion 相关页面（约 18 个文件），不涉及其他模块。
  • 风险标记：导航结构调整可能导致用户迷路, 基准测试数据移除, CLI 命令示例变更

关联脉络

• PR #27766 [Docs] Remove the legacy release-docs.yml deploy workflow: 同属文档基础设施调整，但27766是删除旧文档部署工作流，本PR是内容重构，两者关联较弱，仅在“文档维护”维度相关。