AI Infra 系列写作风格指南

这个文档记录本系列的写作风格和原则，后续写作保持一致。

整体定位

  • 目标读者：有后端/运维经验的工程师，想了解或转型 AI Infra
  • 核心价值：看完能上手干活，能去面试
  • 内容深度：通俗易懂但有干货，新手能入门，老手能学到东西

语言风格

要做的

  1. 说人话，像工程师之间聊天，不是老师在讲课

    • 好：「GPU 利用率普遍只有 30-40%，挺惨的」
    • 差：「GPU 利用率普遍处于较低水平，这是一个值得关注的问题」

  2. 口语化表达，自然、直接

    • 好：「你可能会想：直接 SSH 到机器上跑不就行了？」
    • 差：「读者可能会产生疑问：为什么不能直接通过 SSH 连接到机器执行脚本？」

  3. 简洁，不啰嗦

    • 好：「小规模确实可以。但想象一下这个场景：」
    • 差：「对于小规模的场景来说，这种方式确实是可行的。但是，让我们设想一下以下这样的场景：」

  4. 有观点，敢下判断

    • 好：「大厂基本都是自研，因为有很多定制需求」
    • 差：「大型企业通常会根据自身需求选择是否进行自主研发」

不要做的

  1. 不要说教，减少「你需要」「你应该」

    • 差：「你需要理解这个概念」「你应该先学习基础知识」
    • 好：「这个概念是...」「前置知识包括...」

  2. 不要用空洞的形容词

    • 差：「这是一个非常重要的概念」「这个技术非常强大」
    • 好：直接说为什么重要、强大在哪

  3. 不要堆砌术语，第一次出现的术语要解释

    • 差：「用 NCCL 做 AllReduce 同步梯度」
    • 好：「用 NCCL（NVIDIA 的多卡通信库）做 AllReduce（把所有卡的梯度汇总）」

  4. 不要用 emoji

  5. 不要套路化开头结尾

    • 差：「今天我们来聊聊...」「希望这篇文章对你有所帮助」
    • 好：直接切入主题

内容结构

文章开头

  • 直接说这篇讲什么，1-3 段即可
  • 可以从一个具体场景或问题切入
  • 不要「今天我们来聊聊」这种套话
# 好的开头示例

做 AI Infra，第一个要学会的命令就是 `nvidia-smi`。

这个命令是查看 GPU 状态的，相当于 GPU 的 `top`。机器上 GPU 用得怎么样、谁在用、还剩多少显存，都靠它来看。

这篇文章会把 nvidia-smi 的输出逐行解释清楚。

正文结构

  • 用清晰的标题分层，读者能快速定位
  • 每个概念讲清楚：是什么、为什么、怎么做
  • 代码/配置要有，而且要解释关键参数
  • 适当标注「面试常问」「常见坑」这类提示

文章结尾

  • 简单总结要点（不用太长）
  • 预告下一篇（自然过渡）
  • 不要「希望对你有帮助」「欢迎点赞收藏」

技术内容

代码和配置

  • 必须有，而且要能跑
  • 关键参数加注释解释
  • 复杂配置要逐字段讲解
# 好的示例
apiVersion: apps/v1
kind: Deployment
spec:
  containers:
  - name: vllm
    args:
    - "--gpu-memory-utilization=0.85"    # 用 85% 显存，留点余量
    readinessProbe:
      initialDelaySeconds: 60    # 模型加载要时间，别太早开始检查

数据和对比

  • 多用表格对比，一目了然
  • 数据要有来源或标注是估算
  • 不要只说「A 比 B 快」，要说快多少

排查和实操

  • 给出具体命令，读者能直接用
  • 常见问题列出来，附排查思路
  • 不要只说「可能是 XXX 问题」，要说怎么确认、怎么解决

格式规范

标点

  • 中文标点，句号用「。」不用「.」
  • 英文术语保持原样，如 GPU、Kubernetes、NCCL
  • 中英文之间加空格

标题

  • 一级标题：文章标题
  • 二级标题：大的章节
  • 三级标题：小节
  • 四级及以下：尽量少用

代码块

  • 指定语言类型（yaml、bash、python 等）
  • 命令要带 $ 提示符或注释说明
  • 输出要和命令分开，或用注释标注

强调

  • 关键概念用 加粗
  • 代码/命令用 行内代码
  • 不要用 斜体（中文斜体不好看）

单篇文章规格

  • 字数：3000-5000 字
  • 代码占比：20-30%
  • 表格：每篇 1-3 个
  • 配图：按需，不强求

检查清单

写完一篇后检查：

  • [ ] 开头是否直接切入，没有套话
  • [ ] 术语第一次出现是否解释了
  • [ ] 代码/配置是否有注释
  • [ ] 是否有「你需要」「你应该」等说教句式
  • [ ] 是否有空洞的形容词
  • [ ] 结尾是否简洁，没有套话
  • [ ] 整体读起来是否像聊天而不是讲课