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 中的组件。

集成​

集成 是组件的具体实现。这些通常涉及第三方 API 和服务。

一般来说，这些由第三方合作伙伴维护。

本部分应主要包含 解释 和 参考资料，尽管这里的实际内容比其他部分更灵活，更多地取决于第三方提供者的自由裁量。

note

集成 中涵盖的概念通常存在于 langchain_community 或特定合作伙伴包中。

指南和生态系统​

指南 和 生态系统 部分应包含解决比上述部分更高级问题的指南。

这包括但不限于生产化和开发工作流程方面的考虑。

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

API 参考​

LangChain 的 API 参考。应该作为参考（正如其名称所示），其中还包含一些解释为主的内容。

开发者示例路径​

我们已经设置了我们的文档，以帮助新的 LangChain 开发者。让我们走一遍预期的路径：

  • 开发者登陆 https://python.langchain.com，并阅读介绍和图表。

  • 如果他们只是好奇，他们可能会被引导到快速入门，以便对 LangChain 包含的内容有一个高层次的了解。

  • 如果他们有特定的任务想要完成，他们将被引导到用例部分。用例应该提供一个很好的、具体的钩子，展示 LangChain 可以为他们提供的价值，并成为框架的一个很好的入口点。

  • 然后，他们可以通过表达语言部分了解更多关于 LangChain 基础知识。

  • 接下来，他们可以了解 LangChain 的各种组件和集成。

  • 最后，他们可以通过指南获得额外的知识。

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

指南​

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

链接到其他部分​

因为文档的各个部分并不孤立存在，所以尽可能经常地链接到其他部分，以便开发者可以在不熟悉的主题中学到更多。

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

简洁性​

一般来说，采取少即是多的方法。如果已经存在一个对概念有很好解释的部分，你应该链接到它，而不是重新解释它，除非你所记录的概念呈现了一些新的变化。

要简洁，包括在代码示例中。

一般风格​

  • 尽可能使用主动语态和现在时态。

  • 使用示例和代码片段来说明概念和用法。

  • 使用适当的标题级别（#、##、###等）来按层次组织内容。

  • 使用项目符号和编号列表来将信息分解成易于消化的块。

  • 经常使用表格（特别是对于参考部分）和图表来以视觉方式呈现信息。

  • 对于较长的文档页面，包括目录以帮助读者导航内容，但对于较短的页面则隐藏目录。

Was this page helpful?


You can leave detailed feedback on GitHub.