Skip to main content

LangChain 文档样式指南

简介​

随着 LangChain 的不断发展，覆盖其功能所需的文档内容也在不断增长。
本页面为所有为 LangChain 编写文档的人员提供编写指南，同时介绍我们关于文档组织和结构的一些理念。

理念​

LangChain 的文档力求遵循 Diataxis 框架。
根据该框架，所有文档内容可以归入以下四类之一：

  • 教程：带领读者一步步完成一个项目的指导性内容。
  • 操作指南：指导读者解决实际问题的步骤指南。
  • 参考文档：关于系统技术细节及使用方式的技术性描述。
  • 解释说明：对特定主题进行解释和阐述的内容。

每种类型都服务于不同的目的，并要求特定的写作和结构方式。

分类​

基于上述理念，我们将 LangChain 的文档划分为以下类别。在编写新文档时，理解这些分类将有助于内容的组织：

入门​

入门章节 包括对 LangChain 的高层次介绍、快速上手指南（展示 LangChain 各种功能），以及安装和项目设置相关的操作说明。

该部分包含 操作指南 和 解释说明 类型的内容。

使用场景​

使用场景 是指导用户如何使用 LangChain 完成特定任务（如 RAG、信息提取等）的指南。
对于首次使用 LangChain 的开发者来说，快速入门指南是一个不错的起点，他们可以通过实际原型来学习，然后回过头来理解各个部分的原理。
这些内容应体现 LangChain 的核心优势。

这里的快速入门页应属于 操作指南 类别，而其他页面则用于对更深入的概念和策略进行 解释说明。

note

以下各节大致按抽象程度递增的顺序列出。

表达式语言​

LangChain 表达式语言 (LCEL) 是大多数 LangChain 组件组合在一起的基础方式。本节旨在教会开发者如何有效使用 LangChain 的基本组件进行构建。

该部分应包含教用户如何流式传输和使用 LCEL 基本组件的 教程，对特定行为的 解释说明，以及 Runnable 接口不同方法的 参考文档。

组件​

如何使用章节 覆盖了比 LCEL 抽象层级更高的概念。
诸如 BaseChatModel 和 BaseRetriever 等抽象基类应在此处介绍，其核心实现如 ChatPromptTemplate 和 RecursiveCharacterTextSplitter 也应包含在内。自定义指南也属于此部分。

该部分应主要包含概念性的 教程、参考文档 和对所涵盖组件的 解释说明。

note

通常情况下，表达式语言 和 组件 部分（组件部分的 组合 小节除外）中涉及的所有内容，仅限于 @langchain/core 中存在的组件。

集成​

integrations 页面 包含组件的具体实现，通常涉及第三方 API 和服务。
在这种情况下，一般由第三方合作伙伴维护这些内容。

该部分应主要包含 解释说明 和 参考文档，不过由于内容由第三方提供，因此在形式上比其他部分更灵活。

note

集成 部分中涉及的概念一般应存在于 @langchain/community 或特定合作伙伴的包中。

教程与生态系统​

integrations 页面 包含组件的具体实现，通常涉及第三方 API 和服务。
在这种情况下，一般由第三方合作伙伴维护这些内容。

该部分应主要包含 解释说明 和 参考文档，不过由于内容由第三方提供，因此在形式上比其他部分更灵活。

API 参考文档​

LangChain 的 API 参考文档。顾名思义，这部分主要是 参考文档，但也包含一些以 解释说明 为主的内容。

新开发者学习路径示例​

我们设计文档时，旨在帮助新接触 LangChain 的开发者。以下是预期的学习路径：

  • 开发者访问 https://js.langchain.com，阅读简介和图示。
  • 如果他们只是好奇，可能会前往 快速入门 了解 LangChain 的整体功能。
  • 如果他们有明确的任务目标，则会前往使用场景部分。使用场景应提供一个具体切入点，展示 LangChain 可以为他们带来的价值，并作为框架的良好入口。
  • 接着，他们可以学习 LangChain 基础知识，通过表达式语言部分深入了解。
  • 然后，他们可以学习 LangChain 的各种组件和集成方式。
  • 最后，他们可以通过指南部分获取更多高级知识。

当然，这只是一个理想路径 — 实际上，各章节之间不可避免地会相互引用不同层级的概念。

编写指南​

在编写和组织文档时，请注意以下其他建议：

链接到其他章节​

由于文档各部分并非独立存在，因此应尽可能链接到其他章节，以帮助开发者在阅读时即时了解不熟悉的概念。

这包括链接到 API 参考文档以及概念性章节！

简洁性​

总体上，采用“少即是多”的原则。如果已有某个章节对某个概念进行了良好解释，除非你当前的内容有新的角度，否则应优先链接而非重复解释。

代码示例也应保持简洁。

通用写作风格​

  • 尽可能使用主动语态和现在时态。
  • 使用示例和代码片段来说明概念和用法。
  • 使用适当的标题层级（#、##、### 等）来组织内容结构。
  • 使用项目符号和编号列表将信息分解为易于消化的小块。
  • 多使用表格（尤其适用于 参考文档）和图表来可视化呈现信息。
  • 对较长的文档页面包含目录以帮助导航，对较短页面则隐藏目录。

Was this page helpful?


You can also leave detailed feedback on GitHub.