doc: add doc best-practice/index#392
Conversation
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
There was a problem hiding this comment.
Pull request overview
Adds new best-practice documentation index pages (EN/ZH) intended to guide readers to the right operational/deployment docs via an index table, decision matrix, and scenario-based reading paths.
Changes:
- Introduces
00-index.mdfor English and Chinese best-practice documentation navigation. - Adds model-size and deployment-architecture based recommendations, plus a quick decision matrix and typical scenario paths.
- Adds a dependency chain and FAQ-style quick references to related documents/topics.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.
| File | Description |
|---|---|
| doc/best-practice/zh/00-index.md | New Chinese best-practice index with document mapping, decision matrix, and scenario paths. |
| doc/best-practice/en/00-index.md | New English best-practice index with document mapping, decision matrix, and scenario paths. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | 1 | [Multi-Role Configuration & Role Topology](01-deploy-inference-service.md) | 4 deployment topologies (Aggregated/PD-disaggregated × single-node/multi-node) | | ||
| | 2 | [Simplifying Configuration with RoleTemplates](02-using-role-templates.md) | Reuse role configuration via RoleTemplate | | ||
| | 3 | [Configuring Rolling Update Strategies](03-configuring-rolling-updates.md) | Rolling update parameters and strategy selection | | ||
| | 8 | [Configuring Autoscaling for RBG Services](08-configuring-autoscaling.md) | HPA/KEDA/RBG Planner — three scaling solutions | | ||
| | 9 | [Large-Scale Cluster Resource Estimation, Configuration, and Stress Testing](09-stress-testing-and-tuning.md) | Controller resource estimation and stress testing tools | |
| ## Medium Models (7B-70B, Single-Node Multi-GPU) | ||
| **Typical models**: Qwen-72B, Llama-3-70B, DeepSeek-V2-Lite | ||
|
|
||
| | Scenario | Recommended Document | Notes | | ||
| | --- | --- | --- | | ||
| | **First deployment** | Document 1 (Aggregated deployment + multi-node multi-GPU) | Use LeaderWorkerPattern for tensor parallelism | |
| ## Small Models (<7B, Single GPU) | ||
| **Typical models**: Qwen-1.8B, Llama-3-8B, GLM-4-9B |
| 2. Run the /stress-test Skill | ||
| ↓ Execute stress test, collect performance data |
| | 1 | [多角色配置&角色拓扑](01-deploy-inference-service.md) | 4 种部署拓扑（聚合/PD分离 × 单机/多机） | | ||
| | 2 | [使用 RoleTemplate 简化配置](02-using-role-templates.md) | 通过 RoleTemplate 复用角色配置 | | ||
| | 3 | [配置滚动更新策略](03-configuring-rolling-updates.md) | 滚动更新的参数和策略选择 | | ||
| | 8 | [为 RBG 服务配置弹性伸缩策略](08-configuring-autoscaling.md) | HPA/KEDA/RBG Planner 三种伸缩方案 | | ||
| | 9 | [大规模集群资源评估、配置与压测](09-stress-testing-and-tuning.md) | Controller 资源评估和压测工具 | |
| ## 中型模型（7B-70B，单机多 GPU） | ||
| **典型模型**：Qwen-72B、Llama-3-70B、DeepSeek-V2-Lite | ||
|
|
||
| | 场景 | 推荐文档 | 说明 | | ||
| | --- | --- | --- | | ||
| | **首次部署** | 文档 1（聚合部署 + 多机多卡） | 使用 LeaderWorkerPattern 进行张量并行 | |
| ## 小型模型（<7B，单 GPU） | ||
| **典型模型**：Qwen-1.8B、Llama-3-8B、GLM-4-9B |
| 2. 运行 /stress-test Skill | ||
| ↓ 执行压测，收集性能数据 |
|
/copilot review |
|
@gemini-code-assist /review |
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
|
This PR adds a well-structured documentation index for the best-practice series (EN + ZH). The content organization and scenario-based navigation approach are solid, but there are several issues that need to be addressed before merge:
Please fix issues 1-3 and the CI should pass. The rest are non-blocking suggestions. |
|
|
||
| --- | ||
|
|
||
| # Choosing Documents by Model Size |
There was a problem hiding this comment.
Both files use multiple # (H1) headings throughout, but the repo's markdownlint config enforces MD025 (single-title/single-h1). CI reports 14 errors across both files.
Fix: keep only the very first heading as # and demote all other top-level sections to ##. Adjust sub-headings accordingly (## -> ###, etc.).
| # Documentation Index | ||
| This best practice documentation series covers the full range of scenarios from deployment to operations. Below is a quick index of all documents: | ||
|
|
||
| | # | Document | Core Content | |
There was a problem hiding this comment.
The index table uses file-based numbering (#1, #2, #3, #8, #9, #10), but the body text uses a different logical numbering (1-10 sequential). This creates contradictions:
- Body "Document 7" = Autoscaling, but Index [FEATURES] RBG YAML Deduplication & Simplification for RBG #8 =
08-configuring-autoscaling.md(Autoscaling) - Body "Document 6" = Mooncake Store, but Index [KEP-8] Introduce template reference to reduce YAML duplication #10 =
10-deploy-mooncake-store-with-rbg.md(Mooncake Store) - Body "Document 10" = Service Discovery, but no such entry exists in the index
- Body "Document 8" = CoordinatedPolicy, but Index [FEATURES] RBG YAML Deduplication & Simplification for RBG #8 = Autoscaling
Please unify the numbering scheme so the index table and all body references are consistent.
| Model size determines deployment topology and resource requirements — this is the first dimension for selecting documents. | ||
|
|
||
| ## Small Models (<7B, Single GPU) | ||
| **Typical models**: Qwen-1.8B, Llama-3-8B, GLM-4-9B |
There was a problem hiding this comment.
"Small Models (<7B)" lists Llama-3-8B (8B) and GLM-4-9B (9B) as typical models, both of which exceed the stated <7B threshold. Either raise the threshold (e.g., "<=9B") or replace the examples with actual <7B models (e.g., Qwen-1.8B, Llama-3.2-3B). The same issue exists in the Chinese version at the same line.
|
|
||
| | Scenario | Recommended Document | Notes | | ||
| | --- | --- | --- | | ||
| | **First deployment** | Document 1 (Aggregated deployment + multi-node multi-GPU) | Use LeaderWorkerPattern for tensor parallelism | |
There was a problem hiding this comment.
The section header says "Medium Models (7B-70B, Single-Node Multi-GPU)" but the first deployment row recommends "Aggregated deployment + multi-node multi-GPU". If medium models can require multi-node for TP, the header should reflect that.
|
|
||
| | # | Document | Core Content | | ||
| | --- | --- | --- | | ||
| | 1 | [Multi-Role Configuration & Role Topology](01-deploy-inference-service.md) | 4 deployment topologies (Aggregated/PD-disaggregated × single-node/multi-node) | |
There was a problem hiding this comment.
The linked files (01-.md through 10-.md) don't exist in the repository. If these will be added in follow-up PRs, consider adding a brief note at the top mentioning that the referenced documents are being added incrementally, so readers aren't surprised by 404s.
| ↓ Understand Controller resource requirements and configuration guidelines | ||
|
|
||
| 2. Run the /stress-test Skill | ||
| ↓ Execute stress test, collect performance data |
There was a problem hiding this comment.
"Run the /stress-test Skill" (line 268) assumes readers use a specific tool interface. Consider linking to the underlying stress test documentation or describing the command so the guidance is actionable for all readers.
No description provided.