Skip to main content
我们欢迎对 LangChain 文档的贡献，包括新功能、集成以及现有文档的改进。

​
本地开发快速入门

要运行文档的本地预览： 
git clone https://github.com/langchain-ai/docs.git

cd docs

make install

make dev
这将在 http://localhost:3000 启动一个带有热重载的开发服务器。编辑 src/ 中的文件并立即看到更改。
使用 AI 编码助手？ 安装 LangChain Skills 以提高您在 LangChain 生态系统任务上的表现，然后点击此页面右上角的“复制页面”按钮并粘贴原始内容到您的助手中自动设置环境。
如果本地预览出现问题，请尝试运行 mint update 确保使用的是最新版本的 Mintlify。
必需：可选：

​
编辑文档

对于拼写错误或小更改，无需本地设置即可直接在 GitHub 上进行编辑：
  1. 在任何页面底部点击 Edit this page on GitHub。
  2. 分支到您的个人账户。
  3. 在 GitHub 的 Web 编辑器中进行更改。
  4. 创建一个拉取请求。
仅编辑 src/ 中的文件— build/ 目录会自动生成。
  1. 按照我们的 写作标准 编辑 src/ 中的文件。
  2. 在提交之前运行 质量检查。
  3. 创建一个拉取请求以供审查。
所有拉取请求必须链接到已获维护者批准解决方案的问题或讨论。请参阅我们的 拉取请求要求。
当您创建或更新一个 PR 时，会自动生成一个 预览分支/ID。会在 PR 中留下一条评论附带该 ID。
  1. 复制评论中的预览分支的 ID
  2. 在 Mintlify 控制台 中点击 创建预览部署
  3. 输入预览分支的 ID 并点击 创建部署
  4. 选择预览并点击 访问 查看
要重新部署以包含最新更改，请在控制台中点击 重新部署。

​
运行质量检查

提交更改之前，请确保您的代码通过了格式化和 linting 检查： 
# 检查断言链接
make broken-links

# 自动格式化代码
make format

# 检查 linting 问题
make lint

# 修复 markdown 问题
make lint_md_fix

# 运行测试以确保您的更改不会破坏现有功能
make test
更多细节请参阅 README 中的 可用命令 部分。

​
文档类型

所有文档都属于以下四种之一：

操作指南

为已知目标任务的用户提供的具体任务说明。

概念性指南

提供深入理解与见解的解释。

参考文档

描述 API 和实现细节的技术说明。

教程

通过具体实践活动引导用户建立理解的课程。
如适用，所有文档必须包含 Python 和 JavaScript/TypeScript 内容。更多细节请参阅 共存于 Python 和 JavaScript/TypeScript 内容 部分。

​
操作指南

操作指南为已知目标任务的用户提供具体任务说明。示例见 LangChain 和 LangGraph 标签页。
  • 任务导向：专注于特定的任务或问题
  • 步骤分解：将任务分解为更小的步骤
  • 实践操作：提供具体的示例和代码片段
  • 重点在于 “如何” 而不是 “为什么”
  • 使用具体的示例和代码片段
  • 将任务分解为更小的步骤
  • 链接到相关的概念性指南和参考文档

​
概念性指南

概念性指南抽象地解释核心概念，提供深入理解。
  • 理解导向：解释事物为何如此工作
  • 宽广视角：比其他类型更宽广的视图
  • 设计导向：解释决策和权衡
  • 背景丰富：使用类比和比较
  • 重点在于 “为什么” 而不是 “如何”
  • 提供补充信息，这些信息不一定对于功能的使用是必要的
  • 可以使用类比并参考替代方案
  • 避免过多地混合参考内容
  • 链接到相关的教程和操作指南

​
参考文档

参考文档包含详细、低级的信息，描述了具体的功能以及如何使用它们。

Python 参考

JavaScript/TypeScript 参考

一个好的参考文档应该：
  • 描述了存在什么（所有参数、选项、返回值）
  • 是全面且结构化的，便于查找
  • 作为技术细节的权威来源
  • 保持一致；遵循现有模式的提供方特定文档
  • 包括基本使用（代码片段）和常见边缘情况/失败模式
  • 注意当功能需要特定版本时
  • 新集成或提供商需要专门的参考页面
  • 复杂的配置选项需要详细的解释
  • API 变更引入了新参数或行为
  • 社区经常询问关于特定功能的问题

​
教程

教程是较长形式的逐步指南，通过具体的实践活动引导用户建立理解。教程通常在 Learn 标签页中找到。
除非有特别需要，否则我们一般不会合并来自外部贡献者的新的教程。如果您觉得某个主题缺少文档或没有充分涵盖，请打开一个新问题。
  • 实践导向：专注于具体的实践活动以建立理解。
  • 步骤分解：将活动分解为更小的步骤。
  • 实践操作：提供顺序的工作代码片段。
  • 补充信息：提供额外的上下文和信息，这些信息不一定对于功能使用是必要的。
  • 代码片段应按顺序且在用户遵循步骤时可工作。
  • 提供一些活动背景，但链接到相关的概念性指南和参考文档以获取更多详细信息。

​
写作标准

参考文档有不同的标准 - 请参阅 参考文档贡献指南 以获取更多详细信息。

​
Mintlify 组件

使用 Mintlify 组件 来增强可读性：
  • <Note> 用于提供有益的补充信息
  • <Warning> 用于重要的警告和重大变更
  • <Tip> 用于最佳实践和建议
  • <Info> 用于中立的上下文信息
  • <Check> 用于成功确认

​
页面结构

每个文档页面必须以 YAML 前端文件开头： 
---
title: "清晰、具体的标题"
sidebarTitle: "侧边栏中的简短标题（可选）"
---

​
共存于 Python 和 JavaScript/TypeScript 内容

在可能的情况下，所有文档都必须同时写成 Python 和 JavaScript/TypeScript。为此，我们使用自定义的内联语法来区分应在一种或两种语言中出现的部分： 
:::python
Python 特定内容。实际文档中省略了前导反斜杠（`before python`）。
:::

:::js
JavaScript/TypeScript 特定内容。实际文档中省略了前导反斜杠（`before js`）。
:::

两种语言的内容（未包裹）
这将在 /oss/python/concepts/foo.mdx 和 /oss/javascript/concepts/foo.mdx 生成两个输出（每种语言一个）。每个输出的页面都需要添加到 /src/docs.json 文件中以包含在导航中。
我们不希望缺乏一致性阻碍贡献。如果某个功能仅在一个语言中有，则可以在该语言中拥有文档直到另一个语言赶上。在这种情况下，请包括一个说明，指出该功能尚未在其他语言中可用的注释。如果您需要帮助将内容从 Python 转换为 JavaScript/TypeScript，请在 社区 Slack 中寻求帮助或在您的 PR 中标记维护者。

​
质量标准

​
通用准则

多个页面覆盖相同内容难以维护且会引起混淆。每个概念或功能应只有一个权威页面。链接到其他指南而不是重新解释。
文档部分不是孤立存在的。经常链接到其他部分，以允许用户学习不熟悉的主题。这包括链接到 API 参考和概念性章节。
采用少即是多的方法。如果其他章节已有良好的解释，请链接到该章节而不是重新解释，除非您的内容提供了新的视角。

​
可访问性要求

确保文档对所有用户都是可访问的：
  • 结构化内容以方便扫描，使用标题和列表
  • 使用具体的、可操作的链接文本而非“点击这里”
  • 包含描述性的替代文字（alt text）以供所有图像和图表使用

​
交叉引用

使用一致的交叉引用将文档与 API 参考文档连接起来。 从文档到 API 参考： 使用 @[] 语法链接到 API 参考页面： 
参见 @[`ChatAnthropic`] 获取所有配置选项。

@[`bind_tools`][ChatAnthropic.bind_tools] 方法接受...
构建管道会根据当前语言范围（Python 或 JavaScript）将这些转换为适当的 Markdown 链接。例如，@[ChatAnthropic] 在构建不同版本的文档时会变成指向 Python 或 JS API 参考页面的链接，但仅当 link_map.py 文件中存在条目！
@[] 语法由 handle_auto_links.py 处理。它在包含 Python 和 JavaScript 范围的 link_map.py 文件中查找链接键，该文件中包含字典映射。支持的格式：
语法结果
@[ChatAnthropic]链接显示为 “ChatAnthropic”
@[`ChatAnthropic`]链接显示为 `ChatAnthropic`（代码格式化）
@[text][ChatAnthropic]链接显示为 “text” 且 ChatAnthropic 是链接映射中的键
\@[ChatAnthropic]转义：渲染为纯文本 @[ChatAnthropic]（无链接 - 此页面中使用的）
添加新链接：如果未在映射中找到链接，则会在输出中保持不变。要添加新的自动链接：
  1. 打开 pipeline/preprocessors/link_map.py
  2. 在 LINK_MAPS 中为适当的范围 (python 或 js) 添加条目
  3. 键是用于 @[key] 或 @[text][key] 的链接名称，值是相对于参考主机的路径
从 API 参考草图到开源文档： 有关更多详细信息，请参阅 README 中关于如何从 API 参考草图链接到 Python 开源文档。具体请参阅 mkdocstrings 的跨参考链接语法。

​
本地化

如果功能同时存在于 SDK 中，则为 Python 和 JavaScript/TypeScript 共存 进行文档编写。如果仅支持一种语言，请确保该功能及其引用仅在该语言中可见。

​
内代码文档

示例必须正确、尽可能可复制粘贴并在提交拉取请求之前经过测试。标记非可运行的片段（例如伪代码或说明性片段）。

​
获取帮助

我们的目标是使开发者的设置尽可能简单。如果您遇到任何设置问题，请在 社区 Slack 中提问或创建一个 论坛帖子。内部团队成员可以在 #documentation Slack 通道中联系。
在 GitHub 上编辑此页面：Edit this page on GitHub 或 创建问题。
通过 MCP 将这些文档与 Claude、VSCode 等连接，以获得实时答案：Connect these docs。