跳至主要内容

LangChain 文档风格指南

介绍​

随着 LangChain 不断发展，覆盖其内容所需的文档范围也在不断扩大。本页为所有编写 LangChain 文档的人员提供指南，以及我们关于组织和结构的一些理念。

理念​

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

  • **教程**：手把手指导读者完成一系列概念步骤以完成项目。
  • **操作指南**：指导读者完成解决现实世界问题的步骤。
    • 最典型的例子是我们 用例 页面。
  • **参考**：对机器及其操作方式的技术描述。
  • **解释**：阐明特定主题的解释。

每个类别都服务于不同的目的，需要针对写作和内容结构采用不同的方法。

分类​

牢记以上内容，我们已将 LangChain 的文档按类别分类。在贡献新文档时，采用这些分类有助于进行思考。

入门​

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

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

用例​

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

此处的快速入门页面应符合 **操作指南** 类别，而其他页面则旨在提供 **解释**，深入介绍与主要快乐路径相关的更深层次的概念和策略。

注意

以下部分按抽象级别从低到高排列。

表达式语言​

LangChain 表达式语言 (LCEL) 是大多数 LangChain 组件组合在一起的基础方式，本部分旨在教授开发人员如何使用它来有效地使用 LangChain 的基本组件进行构建。

本部分应包含 **教程**，教导如何流式处理和使用 LCEL 基本组件完成更抽象的任务，**解释** 特定行为，以及一些 **参考**，说明如何在可执行接口中使用不同的方法。

组件​

在 操作指南部分 中，介绍了比 LCEL 更高抽象级别上的概念。应在此介绍抽象基类（如 BaseChatModel 和 BaseRetriever），以及这些基类的核心实现，如 ChatPromptTemplate 和 RecursiveCharacterTextSplitter。自定义指南也应归属于此部分。

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

注意

一般来说，表达式语言 和 组件 部分（除了 组件 部分中的 组合 部分）中涵盖的所有内容都应仅覆盖 @langchain/core 中存在的组件。

集成​

在 集成部分 中，介绍了组件的特定实现。这些通常会涉及第三方 API 和服务。如果是这种情况，一般来说，这些内容由第三方合作伙伴维护。

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

注意

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

教程和生态系统​

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

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

API 参考​

LangChain 的 API 参考。应充当 **参考**（顾名思义），并包含一些以 **解释** 为中心的內容。

示例开发人员旅程​

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

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

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

指南​

在编写和组织文档时，您应该考虑以下其他指南。

链接到其他部分​

由于文档的部分内容并非孤立存在，因此尽可能链接到其他部分非常重要，以便开发人员能够在行内了解更多关于不熟悉主题的信息。

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

简洁​

一般来说，采用少即是多的方法。如果已存在一个具有良好解释概念的部分，您应该链接到它，而不是重新解释它，除非您记录的概念提出了一些新的问题。

保持简洁，包括代码示例。

通用风格​

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

此页面对您有帮助吗？


您也可以留下详细的反馈意见 在 GitHub 上.