# PR #27767 完整报告 - 仓库：`sgl-project/sglang` - 标题：[codex] Update SGLang-Diffusion docs - 合并时间：2026-06-10 14:18 - 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/27767 --- # 执行摘要 - 一句话：重构 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，直接影响用户浏览路径。 ```jsonc // 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，用于美化模型兼容性表格和芯片标签，支持亮 / 暗模式，直接提升文档视觉一致性和可读性。 ```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 是内容重构，两者关联较弱，仅在“文档维护”维度相关。