Skip to main content

LangChain 文档样式指南

¥LangChain Documentation Style Guide

介绍​

¥Introduction

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

¥As LangChain continues to grow, the surface area of documentation required to cover it continues to grow too. This page provides guidelines for anyone writing documentation for LangChain, as well as some of our philosophies around organization and structure.

理念​

¥Philosophy

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

¥LangChain's documentation aspires to follow the Diataxis framework. Under this framework, all documentation falls under one of four categories:

  • 教程：本课程将引导读者完成一系列概念性步骤，最终完成一个项目。

    ¥Tutorials: Lessons that take the reader by the hand through a series of conceptual steps to complete a project.

  • 操作指南：指南将引导读者完成解决实际问题所需的步骤。

    ¥How-to guides: Guides that take the reader through the steps required to solve a real-world problem.

    • 最清晰的例子是我们的 用例 页面。

      ¥The clearest examples of this are our Use case pages.

  • 参考：机器的技术描述及其操作方法。

    ¥Reference: Technical descriptions of the machinery and how to operate it.

  • 说明：阐明和阐释特定主题的说明。

    ¥Explanation: Explanations that clarify and illuminate a particular topic.

每个类别都有不同的用途，需要特定的方法来编写和构建内容。

¥Each category serves a distinct purpose and requires a specific approach to writing and structuring the content.

分类法​

¥Taxonomy

考虑到以上几点，我们将 LangChain 的文档进行了分类。在提交新文档时，以以下方式思考会很有帮助：

¥Keeping the above in mind, we have sorted LangChain's docs into categories. It is helpful to think in these terms when contributing new documentation:

开始使用​

¥Getting started

入门部分 包含 LangChain 的高级介绍、介绍 LangChain 各项功能的快速入门指南，以及有关安装和项目设置的具体说明。

¥The getting started section includes a high-level introduction to LangChain, a quickstart that tours LangChain's various features, and logistical instructions around installation and project setup.

它包含操作指南和说明的元素。

¥It contains elements of How-to guides and Explanations.

用例​

¥Use cases

用例 是指南，旨在展示如何使用 LangChain 完成特定任务（RAG、信息提取等）。对于首次使用 LangChain 的开发者来说，快速入门应该是不错的切入点，他们更喜欢通过获得一些实用的原型，然后回顾性地拆解各个部分来学习。这些要求应该反映 LangChain 的优势。

¥Use cases are guides that are meant to show how to use LangChain to accomplish a specific task (RAG, information extraction, etc.). The quickstarts should be good entrypoints for first-time LangChain developers who prefer to learn by getting something practical prototyped, then taking the pieces apart retrospectively. These should mirror what LangChain is good at.

这里的快速入门页面应该属于“操作指南”类别，其他页面则旨在解释与主要“快乐路径”相关的更深入的概念和策略。

¥The quickstart pages here should fit the How-to guide category, with the other pages intended to be Explanations of more in-depth concepts and strategies that accompany the main happy paths.

note

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

¥The below sections are listed roughly in order of increasing level of abstraction.

表达式语言​

¥Expression Language

LangChain 表达式语言 (LCEL) 是大多数 LangChain 组件组合的基本方式，本节旨在指导开发者如何使用它来有效地构建 LangChain 的原语。

¥LangChain Expression Language (LCEL) is the fundamental way that most LangChain components fit together, and this section is designed to teach developers how to use it to build with LangChain's primitives effectively.

本节主要包含一些教程，教你如何流式传输以及如何使用 LCEL 原语执行更抽象的任务，一些特定行为的说明，以及一些关于如何在 Runnable 接口中使用不同方法的参考。

¥This section should contains Tutorials that teach how to stream and use LCEL primitives for more abstract tasks, Explanations of specific behaviors, and some References for how to use different methods in the Runnable interface.

组件​

¥Components

如何分段 涵盖的概念比 LCEL 高一个抽象级别。本文将介绍抽象基类（例如 BaseChatModel 和 BaseRetriever），以及这些基类的核心实现（例如 ChatPromptTemplate 和 RecursiveCharacterTextSplitter）。自定义指南也属于此处。

¥The how to section covers concepts one level of abstraction higher than LCEL. Abstract base classes like BaseChatModel and BaseRetriever should be covered here, as well as core implementations of these base classes, such as ChatPromptTemplate and RecursiveCharacterTextSplitter. Customization guides belong here too.

本节主要包含概念性教程、参考以及它们所涵盖组件的说明。

¥This section should contain mostly conceptual Tutorials, References, and Explanations of the components they cover.

note

一般来说，Expression Language 和 Components 部分涵盖的所有内容（Composition 部分组件除外）应该仅涵盖 @langchain/core 中存在的组件。

¥As a general rule of thumb, everything covered in the Expression Language and Components sections (with the exception of the Composition section of components) should cover only components that exist in @langchain/core.

集成​

¥Integrations

integrations 是组件的具体实现。这些模型通常涉及第三方 API 和服务。如果是这种情况，一般来说，这些由第三方合作伙伴维护。

¥The integrations are specific implementations of components. These often involve third-party APIs and services. If this is the case, as a general rule, these are maintained by the third-party partner.

本节主要包含说明和参考，但此处的实际内容比其他部分更灵活，并且更多地由第三方提供商自行决定。

¥This section should contain mostly Explanations and References, though the actual content here is more flexible than other sections and more at the discretion of the third-party provider.

note

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

¥Concepts covered in Integrations should generally exist in @langchain/community or specific partner packages.

教程和生态系统​

¥Tutorials and Ecosystem

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

¥The Tutorials and Ecosystem sections should contain guides that address higher-level problems than the sections above. This includes, but is not limited to, considerations around productionization and development workflows.

这些要求主要包含操作指南、说明和教程。

¥These should contain mostly How-to guides, Explanations, and Tutorials.

API 参考​

¥API references

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

¥LangChain's API references. Should act as References (as the name implies) with some Explanation-focused content as well.

开发者旅程示例​

¥Sample developer journey

我们已经设置了文档来帮助 LangChain 的新开发者。让我们逐步了解预期路径：

¥We have set up our docs to assist a new developer to LangChain. Let's walk through the intended path:

  • 开发者选择 https://langchain.nodejs.cn，并阅读简介和图表。

    ¥The developer lands on https://langchain.nodejs.cn, and reads through the introduction and the diagram.

  • 如果他们只是好奇，他们可能会被 快速入门 吸引，以便更深入地了解 LangChain 包含的内容。

    ¥If they are just curious, they may be drawn to the Quickstart to get a high-level tour of what LangChain contains.

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

    ¥If they have a specific task in mind that they want to accomplish, they will be drawn to the Use-Case section. The use-case should provide a good, concrete hook that shows the value LangChain can provide them and be a good entrypoint to the framework.

  • 然后，它们可以通过表达式语言部分进一步了解 LangChain 的基础知识。

    ¥They can then move to learn more about the fundamentals of LangChain through the Expression Language sections.

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

    ¥Next, they can learn about LangChain's various components and integrations.

  • 最后，他们可以通过指南获取更多知识。

    ¥Finally, they can get additional knowledge through the Guides.

当然，这只是理想情况 - 章节不可避免地会引用其他章节中记录的较低或较高级别的概念。

¥This is only an ideal of course - sections will inevitably reference lower or higher-level concepts that are documented in other sections.

指南​

¥Guidelines

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

¥Here are some other guidelines you should think about when writing and organizing documentation.

链接到其他部分​

¥Linking to other sections

由于文档的各个部分并非孤立存在，因此尽可能频繁地链接到其他部分非常重要，这样开发者就可以在线了解更多关于不熟悉主题的信息。

¥Because sections of the docs do not exist in a vacuum, it is important to link to other sections as often as possible to allow a developer to learn more about an unfamiliar topic inline.

包含 API 参考链接以及概念部分！

¥This includes linking to the API references as well as conceptual sections!

简洁性​

¥Conciseness

一般来说，采取少即是多的方法。如果某个部分已经对某个概念进行了很好的解释，你应该链接到它，而不是重新解释它，除非你正在记录的概念出现了一些新的问题。

¥In general, take a less-is-more approach. If a section with a good explanation of a concept already exists, you should link to it rather than re-explain it, unless the concept you are documenting presents some new wrinkle.

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

¥Be concise, including in code samples.

通用样式​

¥General style

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

    ¥Use active voice and present tense whenever possible.

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

    ¥Use examples and code snippets to illustrate concepts and usage.

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

    ¥Use appropriate header levels (#, ##, ###, etc.) to organize the content hierarchically.

  • 使用项目符号和编号列表将信息分解为易于理解的块。

    ¥Use bullet points and numbered lists to break down information into easily digestible chunks.

  • 经常使用表格（尤其是在参考部分）和图表来直观地呈现信息。

    ¥Use tables (especially for Reference sections) and diagrams often to present information visually.

  • 在较长的文档页面中包含目录，以帮助读者浏览内容；在较短的页面中隐藏目录。

    ¥Include the table of contents for longer documentation pages to help readers navigate the content, but hide it for shorter pages.