LangChain 文档风格指南

介绍

随着 LangChain 不断发展，涵盖它的文档表面积也在不断增加。此页面为所有为 LangChain 编写文档的人提供指南，以及我们围绕组织和结构的一些理念。

理念

LangChain 的文档旨在遵循 Diataxis 框架。在这个框架下，所有文档都属于以下四个类别之一

• 教程：通过一系列概念性步骤，手把手地带领读者完成一个项目。
  • 这方面的一个例子是我们的 LCEL 流式处理指南。
  • 我们关于 自定义组件 的指南也是其中之一。
• 操作指南：引导读者完成解决现实世界问题所需的步骤。
  • 这方面的最清晰例子是我们的 用例 页面。
• 参考：对机器及其操作方式的技术描述。
  • 我们的 可运行 页面就是这方面的例子。
  • 另一个例子是 API 参考页面。
• 解释：阐明和解释特定主题的解释。

每个类别都有不同的目的，需要针对编写和构建内容采用不同的方法。

分类法

牢记以上内容，我们将 LangChain 的文档分成了类别。在贡献新的文档时，以这些术语思考非常有用。

入门

The 入门部分 包含对 LangChain 的高级介绍、快速入门（介绍 LangChain 的各种功能）以及有关安装和项目设置的逻辑说明。

它包含 操作指南 和 解释 的元素。

用例

用例 是旨在展示如何使用 LangChain 完成特定任务（RAG、信息提取等）的指南。快速入门应该是第一次使用 LangChain 的开发人员的良好起点，他们更喜欢通过将实际的东西原型化来学习，然后回顾性地拆解各个部分。这些应该反映 LangChain 的优势所在。

此处的快速入门页面应该适合 操作指南 类别，其他页面旨在作为更深入的概念和策略的 解释，这些概念和策略伴随主要的成功路径。

注意

以下部分按抽象级别递增的顺序排列。

表达式语言

LangChain 表达式语言 (LCEL) 是大多数 LangChain 组件协同工作的主要方式，此部分旨在教授开发人员如何使用它来有效地使用 LangChain 的基元进行构建。

此部分应包含 教程，教授如何流式传输和使用 LCEL 基元来完成更抽象的任务，包含 解释 特定的行为，以及一些 参考，介绍如何在可运行接口中使用不同的方法。

组件

The 操作指南部分 涵盖比 LCEL 更高一个抽象级别的概念。抽象基类（如 BaseChatModel 和 BaseRetriever）应在此处涵盖，核心实现（如 ChatPromptTemplate 和 RecursiveCharacterTextSplitter）也应在此处涵盖。自定义指南也应该放在这里。

此部分应主要包含针对其涵盖组件的概念性 教程、参考 和 解释。

注意

作为一般经验法则，Expression Language 和 Components 部分（除了 Composition 部分的组件）中涵盖的所有内容，都应仅涵盖 @langchain/core 中存在的组件。

集成

The 集成 是组件的特定实现。这些通常涉及第三方 API 和服务。如果是这种情况，作为一般规则，这些由第三方合作伙伴维护。

此部分应主要包含 解释 和 参考，不过此处的实际内容比其他部分更加灵活，更多地取决于第三方提供商的判断。

注意

Integrations 中涵盖的概念通常应该存在于 @langchain/community 或特定的合作伙伴软件包中。

教程和生态系统

The 教程 和 生态系统 部分应包含解决比上面部分更高级别问题的指南。这包括但不限于围绕生产化和开发工作流程的考虑因素。

这些应主要包含 操作指南、解释 和 教程。

API 参考

LangChain 的 API 参考。应充当 参考（顾名思义），但也包含一些以 解释 为重点的内容。

示例开发人员旅程

我们已经设置了我们的文档来帮助新开发人员使用 LangChain。让我们来看看预期的路径。

• 开发人员会访问 https://js.langchain.ac.cn，并阅读介绍和图表。
• 如果他们只是出于好奇，他们可能会被 快速入门 所吸引，以便对 LangChain 的内容有一个高级的了解。
• 如果他们心中有一个想要完成的特定任务，他们会被用例部分所吸引。用例应该提供一个良好的、具体的钩子，展示 LangChain 可以提供的价值，并且是进入框架的良好起点。
• 然后，他们可以通过表达式语言部分来学习更多关于 LangChain 基础知识的内容。
• 接下来，他们可以学习 LangChain 的各种组件和集成。
• 最后，他们可以通过指南获得更多知识。

当然，这只是一个理想的路径——部分内容不可避免地会引用其他部分中记录的更低或更高级别的概念。

指南

以下是编写和组织文档时应考虑的其他一些指南。

链接到其他部分

由于文档部分并非孤立存在，因此尽可能地链接到其他部分非常重要，以便开发人员可以更深入地了解陌生的主题。

这包括链接到 API 参考和概念性部分！

简洁

总的来说，采用少即是多的方法。如果某个部分已经包含对某个概念的良好解释，那么你应该链接到它，而不是重新解释它，除非你记录的概念提出了一些新的问题。

言简意赅，包括代码示例。

通用风格

• 尽可能使用主动语态和现在时。
• 使用示例和代码片段来说明概念和用法。
• 使用适当的标题级别（#、##、### 等）来按层次结构组织内容。
• 使用项目符号和编号列表将信息分解成易于理解的块。
• 经常使用表格（尤其是针对 参考 部分）和图表来直观地呈现信息。
• 为较长的文档页面包含目录，以帮助读者浏览内容，但对于较短的页面隐藏目录。