| fix(doc): 修复 quick_start.md 文档及 mkdocs 渲染问题
Co-authored-by: xuchi<xuchicolson@163.com>
# message auto-generated for no-merge-commit merge:
!1019 merge A00252 into dev
fix(doc): 修复 quick_start.md 文档及 mkdocs 渲染问题
Created-by: martinXuc
Commit-by: xuchi
Merged-by: ascend-robot
Description: <!--
PR描述模板更新日期：20251225
-->
# 合入背景
Fixes https://gitcode.com/Ascend/MindIE-LLM/issues/591
根据 issue #591 的用户反馈，修复 quick_start.md 在 mkdocs 渲染、命令可用性、格式规范性等方面的问题，同时补充 whl 包安装方式的差异化说明，提升文档的可用性和准确性。
本次 PR 还同步了 upstream/dev 的最新代码，并解决了 merge 冲突。
# 修改内容
本次 PR 涉及对 quick_start.md 文档、mkdocs 渲染 hook 以及 mkdocs 配置的修改：
### 1. 修复 quick_start.md 格式、命令及 mkdocs 渲染问题
**命令修复：**
- --shm-size 从 1g 改为 500g，避免大模型推理时共享内存不足
- 镜像名称从硬编码的 mindie:3.0.0-800I-A2-py311-openeuler24.03-lts 替换为 {IMAGE_ID} 占位符，用户根据实际下载的镜像替换
- 数据集名称 demo_gsm8k_* → gsm8k_*，修正为正确的数据集名
- 精度测试命令 --models vllm_api_general_chat → vllm_api_stream_chat，与配置文件一致
- 精度测试回显中 demo_gsm8k → gsm8k，vllm_api_general_chat → vllm_api_stream_chat
- 环境变量步骤锚点 ID 从 step3 改为 setup_env，语义更清晰
**内容增补：**
- 表 2（容器内各组件安装路径）后新增 NOTE 说明，补充 whl 包 vs run 包安装方式的路径差异
- CAUTION 后新增 NOTE 说明，补充 whl 包安装时使用 mindie-llm-server 命令拉起服务
- AISBench 路径说明整合：新增 {ais_bench_path} 占位符，统一说明镜像集成版和 git 安装版的路径差异
- 步骤 3.d：编辑 config.json 后设置权限为 640（chmod 640 config.json）
- 性能测试"准备数据集"路径统一使用 {ais_bench_path}
- 性能测试"安装 AISBench 工具"增加跳转链接至精度测试章节
- 图片补 alt text（MD045）
**内容删除：**
- 删除文件权限检查步骤（chmod 命令集），因默认路径权限已正确，且 whl 包安装方式不需要
- 删除重复的 "Daemon start success!" 回显提示
- 删除 docker exec 后的 NOTE（外部链接，信息量少）
**格式修复：**
- 列表内代码块缩进从 5 空格修正为 4 空格，修复 mkdocs 渲染时列表断裂问题
- 表格添加列对齐标记空格，确保在 GitHub 和 mkdocs 上均正确渲染
- json 代码块格式修正（删除多余缩进）
- NOTE/CAUTION 标记规范化：> [!NOTE]说明 → > [!NOTE] 说明
- 参数名、路径等使用反引号包裹，增加可读性
**排版规范化：**
- 全篇应用"盘古之白"规范：中英文之间、中文与数字之间加空格
### 2. 修复 pre-commit 检测问题
- 修复 github_admonition.py 中的 trailing whitespace 和 unused import
### 3. 新增 mkdocs hook 修复列表内 admonition 渲染
- github_admonition.py：修复正则表达式，排除嵌套 [! 模式的误匹配；当 admonition 在列表项内时，在其后插入 <!-- --> 注释强制列表闭合
- 新增 list_break.py hook：检测被 <!-- --> 标记的列表内 admonition，在其后的 ## 标题前再插入一列 <!-- -->，解决 Python-Markdown 在列表项内 admonition 后遇到标题时不闭合 <li> 的渲染问题
### 4. 注册新 hook
- mkdocs.yml：注册 list_break.py hook
### 5. 同步 upstream/dev 并解决 merge 冲突
- Merge branch dev of gitcode.com:Ascend/MindIE-LLM 到 A00252，同步上游最新代码
- 解决 4 个冲突：产品表格、参数表格、chmod 步骤删除、发送请求链接
# 资料变更
涉及。修改 docs/zh/user_guide/quick_start/quick_start.md 文档。
# 接口变更
不涉及。
# 测试结果
本次为文档和 mkdocs 渲染工具修复，已在本地验证：
- 修改后的 hook 对现有其他 admonition 无影响，渲染正确
- 修复的代码块缩进和表格格式在 mkdocs serve 预览下渲染正常
- 命令修改基于实际使用场景验证（--shm-size、数据集名、模型配置名）
- 确认 vllm_api_stream_chat 配置可用于精度测试（AISBench 查询验证）
- markdownlint 全线通过，零报错
# CheckList
- [x] 代码注释完备
- [x] 正确记录错误日志
- [x] 进行了返回值校验 (禁止使用void屏蔽安全函数、自研函数返回值；考虑接口的异常场景；调用底层组件接口时，需要进行返回值校验)
- [x] 进行了空指针校验
- [x] 若存在资源申请，使用后资源被正确的释放了
- [x] 若涉及多线程场景，考虑了并发场景，不存在死锁问题
- [x] 按照[代码仓中提供的格式模板](https://gitcode.com/Ascend/MindIE-LLM/blob/master/.clang-format)，使用clang-format工具格式化代码
- [x] 符合Ascend社区的编码规范。[C++ 语言编程指导](https://gitcode.com/Ascend/community/blob/master/docs/contributor/Ascend-cpp-coding-style-guide.md) | [C++ 语言安全编程指导](https://gitcode.com/Ascend/community/blob/master/docs/contributor/Ascend-cpp-secure-coding-guide.md)
See merge request: Ascend/MindIE-LLM!1019 | 3 天前 |
