规范指南.md

内容规范指南

本文档约定 hello-rocm 中教程类 Markdown（及配套资源）的写法与目录规范，以 01-Deploy/models/Qwen3/ 与 Gemma4 同级目录为参考实现。新稿请尽量对齐，降低读者切换模型时的认知成本。

1. 目录与命名

类型	约定	示例
模型专项根目录	01-Deploy/models/<系列名>/，系列名与 README「已支持模型」一致	Qwen3、Gemma4
环境准备	固定文件名，便于交叉引用	env-prepare-ubuntu24-rocm7.md
推理总览	可选；与 Qwen3 一致时使用	Ubuntu24.04-rocm7-infer-deploy.md
框架部署文	<框架小写>-rocm7-deploy.md	vllm-rocm7-deploy.md、lm-studio-rocm7-deploy.md
配图目录	模型目录下 images/，不再使用 images/media/ 等多余层级	images/image1.png

微调 Notebook、长文记录等放在 02-Fine-tune/models/<系列名>/，命名建议带序号与主题，如 01-Qwen3-8B-LoRA.ipynb。

2. 文档结构（与 Qwen3 教程对齐）

1. 一级标题 / 开篇

   • 使用 ## 作为主标题（与现有导出风格一致）。
   • 首段说明：系统（如 Ubuntu 24.04）、ROCm 大版本（如 ROCm 7+）、主题（某框架 + 某模型示例）。
   • 示例参考：lm-studio-rocm7-deploy.md 开头两段。

2. 前置条件

   • 使用引用块 > 或单独小节，明确依赖的环境准备文档，例如：
     参考同目录下 env-prepare-ubuntu24-rocm7.md。

3. 分节

   • 可使用「一、二、」或「### 1.」「#### 1.1」层级，同一篇内保持一种风格。
   • 大步骤之间用 --- 分隔（与 Qwen3 多篇一致）。

4. 命令与代码

   • Shell 使用 ```bash围栏；仅展示输出时用纯文本或注释说明。
   • 官方文档、脚本 URL 使用完整 https:// 链接。

5. 图片

   • 统一放在 ./images/ 下，引用格式示例：<img src="./images/image1.png" style="..." />。
   • 路径不要写 ./images/media/，除非仓库中确实存在该目录。
   • 新增图片建议按 image1.png、image2.png 递增，并在文中顺序引用，便于 diff 与审查。

6. 交叉引用

   • 同目录文件：相对路径 ./xxx.md。
   • 根 README 或其它模块：../ 或从仓库根开始的相对路径，以 GitHub 上可点击为准。

3. README 与「已支持模型」

• 新增一整条模型线（新目录）时，应在 README.md 的 「已支持模型」 中增加分组行与链接，格式与 Qwen3 / Gemma4 表格一致。
• 仅增加单篇子教程时，若适合暴露在总表，可增一行链接；否则至少在 01-Deploy/README.md 或对应模块 README 中列出。

4. 语言与风格

• 正文以简体中文为主；专有名词（ROCm、vLLM、CUDA 等）保持业界通用写法。
• 避免歧义：写清「宿主机 /容器」「系统级安装 / 虚拟环境」等边界。
• 版本号、命令与官方文档变更较快，修改时尽量注明针对的 ROCm 或框架版本（可在文首或「前置条件」中说明）。

5. 自检清单（提交前）

• 文内所有相对链接在仓库中真实存在。
• 所有 img src 指向的图片路径存在（且与 images/ 实际结构一致）。
• 新增模型线已更新 README「已支持模型」（如适用）。
• 无仅本地有效的绝对路径或个人信息。

---

维护者可根据仓库演进修订本页；有重大约定变更时，建议在 CONTRIBUTING.md 中同步提示。