理清这团乱麻
大约 3 年前，当我加入 Hugging Face 时，Transformers 的文档与今天的形式大不相同。它侧重于文本模型以及如何训练或使用它们来对自然语言任务（文本分类、摘要、语言建模等）进行推理。
今天的 Transformers 文档主版本与近 3 年前的 4.10.0 版本对比。
随着 transformer 模型越来越成为 AI 的默认方法，文档也大幅扩展，包含了新的模型和新的使用模式。但新内容的增加是渐进式的，没有真正考虑到受众和 Transformers 库的演变。
我认为这就是文档体验 (DocX) 感觉脱节、难以导航和过时的原因。基本上，一团糟。
这就是为什么有必要重新设计 Transformers 文档，以理清这一团糟。目标是：
- 为有兴趣用 AI 构建产品的开发者编写。
- 允许有机的文档结构和自然的增长，而不是僵化地遵循预定义的结构。
- 通过集成内容而非将其修订到现有文档中，创造更统一的文档体验。
新的受众
在我看来，那些明白 AI 不仅仅是集成的 API，而是一种构建所有技术的新范式的公司，以及那些在内部发展这种能力（即构建、训练自己的模型）的公司，将能够比其他公司构建出好 100 倍的产品，并获得差异化和长期价值。
— clem 🤗 (@ClementDelangue) 2023 年 3 月 3 日
Transformers 文档最初是为机器学习工程师、研究人员和模型爱好者编写的。
现在 AI 更加主流和成熟，而不仅仅是一时的风尚，开发者们越来越有兴趣学习如何将 AI 构建到产品中。这意味着要认识到开发者与文档的交互方式不同于机器学习工程师和研究人员。
两个关键的区别是：
- 开发者通常从代码示例开始，并寻找解决他们试图解决的问题的方法。
- 不熟悉 AI 的开发者可能会对 Transformers 感到不知所措。如果你不了解它们的使用背景，代码示例的价值就会降低，甚至变得毫无用处。
通过这次重新设计，Transformers 文档将更加代码优先和以解决方案为导向。代码和初级机器学习概念的解释将紧密结合，以提供更完整和对初学者友好的入门体验。
一旦开发者有了基本的了解，他们就可以逐步提升自己的 Transformers 知识水平。
走向更有机的结构
我在 Hugging Face 的第一个项目之一就是将 Transformers 文档与 Diátaxis 对齐，这是一种基于用户需求（学习、解决问题、理解、参考）的文档方法。
新名称、新内容、新外观和新地址。https://#/PlmtSMQDNX
— Daniele Procida (@evildmp) 2021 年 4 月 8 日
这可能是世界上最好的文档编写系统！pic.twitter.com/LTCnIZmRwJ
但在某个时候，我开始将 Diátaxis 用作计划而不是指南。我试图强行将内容整齐地归入 4 个预设类别之一。
僵化的结构阻碍了自然形成的内容结构的出现，并妨碍了文档的适应和扩展。关于一个主题的文档很快就跨越了几个部分，因为这是结构所规定的，而不是因为它合理。
结构复杂没关系，但如果它复杂且不容易找到方向，那就不可取了。
这次重新设计将用灵活性取代僵化，使文档能够成长和演变。
集成与修订
年轮提供了过去的气候记录（干旱、洪水、野火等）。在某种程度上，Transformers 文档也有自己的年轮或时代，记录了它的演变：
- 不仅仅是文本时代：Transformer 模型被用于其他模态，如计算机视觉、音频、多模态，而不仅仅是文本。
- 大语言模型 (LLM) 时代：Transformer 模型的参数扩展到数十亿，导致了与它们交互的新方式，例如提示和聊天。你开始看到更多关于如何高效训练 LLM 的文档，比如使用参数高效微调 (PEFT) 方法、分布式训练和数据并行。
- 优化时代：除非你是 GPU 富豪，否则运行 LLM 进行推理或训练可能是一个挑战，所以现在人们对如何为 GPU 穷人普及 LLM 产生了极大的兴趣。有更多关于诸如量化、FlashAttention、优化键值缓存、低秩适应 (LoRA) 等方法的文档。
每个时代都渐进地向文档中添加新内容，使其先前部分失衡和模糊。内容分布在更广的面上，导航也变得更加复杂。
在年轮模型中，新内容逐层叠加在先前内容之上。而在集成模型中，内容作为整个文档的一部分共存。
重新设计将有助于重新平衡整体文档体验。内容将感觉像是原生的和集成的，而不是附加的。
下一步
这篇文章探讨了我们寻求重新设计 Transformers 文档的原因和动机。
敬请期待下一篇文章，它将更详细地识别混乱之处，并回答一些重要问题，例如，目标用户和利益相关者是谁，内容的当前状态如何，以及它如何被解读。
特别感谢 [@evilpingwin](https://x.com/evilpingwin) 为重新设计文档提供的反馈和动力。
