Skip to main content
易于访问的文档是 LangChain 的重要组成部分。我们欢迎为新功能/集成撰写新文档,也欢迎社区对现有文档进行改进。
通常情况下,除非有迫切需求,我们不会合并来自外部贡献者的新教程。
所有文档均属于以下四种类别之一:

概念指南

提供更深层次理解与洞察的解释性内容

参考文档

API 和实现细节的技术描述

教程

引导用户通过实践操作逐步建立理解的学习材料

操作指南

面向明确目标用户的任务导向型操作说明

快速入门

快速编辑:修复拼写错误

对于简单的修改(如修正拼写错误),您无需配置本地开发环境,可直接在 GitHub 上编辑:
前提条件:
  • 拥有 GitHub 账户
  • 熟悉 GitHub Web 界面提交 Pull Request 的基本操作
1

找到页面

导航至任意文档页,点击页面底部的“建议编辑”链接
2

Fork 仓库

GitHub 将提示您将仓库 Fork 到您的账户。请务必 Fork 至您的
3

进行修改

在 GitHub 的网页编辑器中直接修正拼写错误
4

提交更改

点击 Commit changes...,并为提交起一个描述性标题,例如 fix(docs): 描述
5

创建 Pull Request

GitHub 将引导您创建 Pull Request。标题格式如 docs: 修正 X 中的拼写错误,并遵循 PR 模板中的检查清单
文档类 PR 通常会在几天内完成审核。请关注您的 PR,及时响应维护者的反馈。

完整开发 IDE 配置

对于较大规模的修改或持续贡献,请设置本地开发环境。我们的文档使用 Mintlify 构建,支持本地预览和实时重载。
1

本地仓库

克隆我们的文档仓库,除非您仅计划更新 API 参考文档,在这种情况下您可以 Fork 相关仓库(例如 langchainlanggraph
2

了解 Mintlify

查阅 Mintlify 文档,了解组件用法和最佳实践——您也可以参考现有文档作为示例
3

构建系统与开发环境

按照以下步骤设置您的开发环境
本仓库包含配置文件,以确保不同编辑器之间的格式一致性:
  • VSCode
  • 其他 IDE
打开项目时,.vscode/settings.json 中的设置会自动应用,无需额外配置。推荐扩展:在 VSCode 中打开“Extensions”标签页时,可能会提示您自动安装这些扩展。

构建系统

仅编辑 src/ 目录下的文件 —— build/ 目录是自动生成的!
我们的文档采用构建流水线,允许使用 MDX 编写并使用 Mintlify 组件。源文件位于 src/,构建输出位于 build/。您可以运行带热重载的本地开发服务器,在浏览器中即时查看更改效果。
1

安装依赖

如果尚未安装,请先安装 uvmint。同时,请确保已克隆文档仓库
cd docs
uv venv
source .venv/bin/activate
uv sync --all-groups
npm i -g mint
2

启动开发服务器

在项目根目录运行:
docs dev
这将在 http://localhost:3000 启动带热重载的开发服务器(除非另有指定)。
3

进行修改

编辑 src/ 中的文件,并在浏览器中立即看到更改效果

文档类型

在适用的情况下,所有文档必须同时提供 Python 和 JavaScript/TypeScript 版本。详情请参阅本地化指南

概念指南

概念指南从抽象层面介绍核心概念,提供深入理解。
  • 注重理解:解释事物为何如此运作
  • 宏观视角:比其他类型更宽广、更高层次的视野
  • 面向设计:阐释决策与权衡取舍
  • 丰富语境:使用类比与对比
  • 解释设计决策 —— 为什么存在概念 X?
  • 使用类比并引用替代方案
  • 避免混入过多参考内容
  • 链接到相关教程和操作指南
  • 聚焦于 “为什么”,而非“怎么做”
示例页面

参考文档

参考文档包含详细、底层的信息,精确描述现有功能及其使用方法。
  • 信息导向:描述存在的内容
  • 全面覆盖:涵盖所有参数和选项
  • 结构清晰:系统化组织
  • 权威准确:技术细节的权威来源
  • API 参考:从代码文档字符串自动生成
  • 集成指南:特定提供商/工具的手动文档
  • 配置参考:详细的参数规范
  • 模式文档:数据结构和格式规范
  • API 参考:更新源码仓库中的文档字符串
  • 集成指南:在文档仓库/src/ 目录下创建/编辑 .mdx 文件
  • 手动参考:编辑现有页面
  • 集成一致性:遵循现有模式编写特定提供商的文档
  • 代码示例:包含基础用法及常见边缘情况/失败模式
  • 版本兼容性:注明功能所需的特定版本
现有参考文档 何时创建新的参考文档:
  • 新增集成或提供商需专属参考页面
  • 复杂配置选项需详细说明
  • API 变更引入新参数或行为
  • 社区频繁询问特定功能

写作标准

Mintlify 组件

使用适当的 Mintlify 组件 提升可读性:
  • 提示框
  • 结构
  • 代码
  • <Note> 用于补充信息
  • <Warning> 用于重要警告和破坏性变更
  • <Tip> 用于最佳实践和建议
  • <Info> 用于中立的背景信息
  • <Check> 用于成功确认

页面结构

每个文档页面必须以 YAML frontmatter 开头:
---
title: "清晰具体的标题"
---

本地化

在可能的情况下,所有文档必须同时本地化为 Python 和 JavaScript/TypeScript 版本。为此,我们使用自定义内联语法区分应出现在一种或两种语言中的部分:
Python 专属内容。实际文档中,此处 python 前的反斜杠应省略。




适用于两种语言的内容(不加包裹)
我们不希望因语言版本不对称而阻碍贡献。如果某项功能仅在一个语言中可用,则可以仅在该语言中提供文档,直到另一语言跟上为止。在这种情况下,请注明该功能尚未在另一语言中提供。
如果您需要帮助在 Python 和 JavaScript/TypeScript 之间翻译内容,请在社区 Slack 中提问,或在您的 PR 中标记维护者。

质量标准

通用指南

多个页面覆盖相同内容难以维护且易造成混淆。每个概念或功能应仅有一个权威页面。链接到其他指南,而非重复解释。
文档各部分并非孤立存在。频繁链接到其他部分,以便用户了解不熟悉的话题。这包括链接到 API 参考和概念部分。
采取少即是多的原则。若已有良好解释的其他部分,链接过去即可,除非您的内容提供了新视角。

可访问性要求

确保文档对所有用户均可访问:
  • 使用标题和列表结构化内容,便于快速浏览
  • 使用具体、可操作的链接文本,而非“点击这里”
  • 为所有图片和图表提供描述性 alt 文本

测试与验证

提交文档前:
1

测试所有代码

运行所有代码示例,确保其正确无误
2

检查格式

make lint
make format
3

本地构建

docs build
验证构建无错误完成
4

检查链接

确保所有内部链接正常工作

代码内文档

语言与风格

对所有公共函数使用Google 风格文档字符串并完整标注类型提示。
所有文档遵循以下标准:
  • 语气:使用第二人称(“您”)进行指导
  • 时态:使用主动语态和现在时
  • 清晰度:为技术受众编写清晰、直接的语言
  • 一致性:全文使用一致的术语
  • 简洁性:句子简洁,同时提供必要上下文

代码示例

发布前务必测试所有代码示例。切勿包含真实的 API 密钥或机密信息。
代码示例要求:
1

完整性

包含完整、可运行的示例,用户可直接复制执行且无错误
2

真实性

使用真实数据,而非“foo”或“example”等占位符
3

错误处理

展示正确的错误处理和边缘情况管理
4

注释说明

为复杂逻辑添加解释性注释
良好文档化函数示例:
def filter_unknown_users(users: list[str], known_users: set[str]) -> list[str]:
    """过滤掉不在已知用户集合中的用户。

    Args:
        users: 待过滤的用户标识符列表。
        known_users: 已知/有效用户标识符集合。

    Returns:
        不在 known_users 集合中的用户列表。

    Raises:
        ValueError: 若 users 列表包含无效标识符。
    """
    return [user for user in users if user not in known_users]

获取帮助

我们的目标是尽可能简化开发者配置。如在配置过程中遇到任何困难,请在社区 Slack 中提问,或发布论坛帖子
您现在已具备为 LangChain 贡献高质量文档所需的一切!