LangChain 中文文档

主题

参与贡献

贡献文档

无障碍文档是 LangChain 的重要组成部分。我们欢迎新功能和集成的文档，也欢迎社区对现有文档的改进。

这些是我们开源项目的贡献指南，但它们也适用于 LangSmith 文档。

贡献 ​

快速编辑 ​

对于快速更改，例如修复拼写错误或更改链接，您可以直接在 GitHub 上编辑，无需设置本地开发环境：

前提条件：

  1. 在您要编辑的页面底部，点击 Edit this page on GitHub 链接。
  2. GitHub 会提示您将仓库 fork 到您的账户。确保 fork 到您的 个人账户。
  3. 直接在 GitHub 的网页编辑器中修改。
  4. 点击 Commit changes... 并为您的提交提供一个描述性标题，例如 fix(docs): summary of change。如果适用，请添加扩展描述。
  5. GitHub 将重定向您以创建拉取请求（pull request）。给它一个标题（通常与提交相同）并遵循 PR 模板清单。

文档 PR 通常会在几天内得到审核。请关注您的 PR 以处理维护者的任何反馈。

除非您有新的信息需要提供，否则不要催促 PR——维护者会在他们时间允许的情况下处理。

较大的编辑和新增内容 ​

对于较大的更改、新增内容或持续贡献，需要在您的机器上设置本地开发环境。我们的文档构建管道提供本地预览，这对于确保您的更改在提交前按预期显示非常重要。

设置本地环境 ​

在您处理此项目之前，请确保已安装以下内容：

必需：

  • python >= 3.13, < 4.0
  • uv - Python 包管理器（用于依赖管理）
  • Node.js 和 npm - 用于 Mintlify CLI 和参考文档构建
  • Make - 用于运行构建命令
  • Git - 用于版本控制

可选但推荐：

bash
npm install -g markdownlint-cli
  • pnpm - 仅当您处理参考文档时需要
bash
npm install -g pnpm@10.14.0

设置步骤：

  1. 克隆 langchain-ai/docs 仓库。按照 IDE_SETUP.md 中概述的步骤操作。

  2. 安装依赖项：

bash
make install

此命令将： - 使用 uv sync --all-groups 安装 Python 依赖项 - 通过 npm 全局安装 Mintlify CLI

  1. 验证您的设置：
bash
make build

这应该能无错误地构建文档。

安装后，您将可以使用 docs 命令：

bash
docs --help

常用命令：

  • docs dev - 启动开发模式，支持文件监视和热重载
  • docs build - 构建文档

更多详情请参见可用命令。

编辑文档 ​

仅编辑 src/ 目录中的文件 – build/ 目录是自动生成的。

  1. 确保您的环境已设置好，并且您已按照 IDE_SETUP.md 中的步骤配置了您的 IDE/编辑器以自动应用正确的设置。

  2. 编辑 src/ 中的文件

    • 对 markdown 文件进行更改，构建系统将自动检测更改并重建受影响的文件。
    • 如果 OSS 内容在 Python 和 JavaScript/TypeScript 之间有所不同，请在同一文件中添加两种语言的内容。否则，两种语言的内容将完全相同。
    • 使用 Mintlify 语法进行格式化。

  3. 启动开发模式以在本地预览更改：

bash
docs dev

这将在 http://localhost:3000 启动一个支持热重载的开发服务器。

  1. 迭代

    • 继续编辑并立即看到更改反映出来。
    • 开发服务器仅重建已更改的文件，以获得更快的反馈。

  2. 运行质量检查以确保您的更改有效。

  3. 获得相关审核者的批准。

LangChain 团队成员可以生成可共享的预览构建

  1. 发布到生产环境（仅限团队成员）。

创建可共享的预览构建 ​

只有 LangChain 团队成员可以创建可共享的预览构建。

说明

预览对于与他人共享进行中的工作更改非常有用。

当您创建或更新 PR 时，会自动为您生成一个预览分支/ID。PR 上会留下一条包含该 ID 的评论，然后您可以使用该 ID 生成预览。（如果需要，您也可以手动运行此工作流。）

  1. 从评论中复制预览分支的 ID。
  2. 在 Mintlify 仪表板中，点击 Create preview deployment。
  3. 输入预览分支的 ID。
  4. 点击 Create deployment。 手动更新将显示在 Previews 表中。
  5. 选择预览并点击 Visit 以查看预览构建。

要使用最新更改重新部署预览构建，请在 Mintlify 仪表板上点击 Redeploy。

运行质量检查 ​

在提交更改之前，请确保您的代码通过格式化和代码检查：

bash
# 检查损坏的链接
make mint-broken-links

# 自动格式化代码
make format

# 检查代码检查问题
make lint

# 修复 markdown 问题
make lint_md_fix

# 运行测试以确保您的更改不会破坏现有功能
make test

更多详情，请参阅 README 中的可用命令部分。

发布到生产环境 ​

只有内部团队成员可以发布到生产环境。

说明

一旦您的分支被合并到 main，您需要将更改推送到 prod，以便它们呈现在实时文档站点上。使用 Publish documentation GH action：

  1. 转到 Publish documentation。
  2. 点击 Run workflow 按钮。
  3. 选择要部署的 main 分支。
  4. 点击 Run workflow。

文档类型 ​

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

操作指南

面向知道要完成什么任务的用户的任务导向说明。

概念指南

提供更深层次理解和见解的解释。

参考

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

教程

引导用户通过实践活动来建立理解的课程。

在适用的情况下，所有文档都必须同时包含 Python 和 JavaScript/TypeScript 内容。更多详情，请参见共置 Python 和 JavaScript/TypeScript 内容部分。

操作指南 ​

操作指南是面向知道要完成什么任务的用户的任务导向说明。操作指南的示例位于 LangChain 和 LangGraph 选项卡上。

特点
  • 任务导向：专注于特定任务或问题
  • 分步说明：将任务分解为更小的步骤
  • 实践性强：提供具体示例和代码片段
技巧
  • 关注 如何做 而非 为什么
  • 使用具体示例和代码片段
  • 将任务分解为更小的步骤
  • 链接到相关的概念指南和参考
示例

概念指南 ​

概念指南抽象地涵盖核心概念，提供深入理解。

特点
  • 理解导向：解释事物为何如此运作
  • 视角广阔：比其他类型更高、更广的视角
  • 设计导向：解释决策和权衡
  • 上下文丰富：使用类比和比较
技巧
  • 关注 "为什么" 而非 "如何做"
  • 提供不一定为使用功能所必需的补充信息
  • 可以使用类比并参考替代方案
  • 避免混入过多的参考内容
  • 链接到相关的教程和操作指南
示例

参考 ​

参考文档包含详细的、低层级的信息，准确描述存在哪些功能以及如何使用它们。

Python 参考

JavaScript/TypeScript 参考

一个好的参考应该：

  • 描述存在什么（所有参数、选项、返回值）
  • 全面且结构清晰，便于查找
  • 作为技术细节的权威来源
贡献参考文档

请参阅 Python 参考文档的贡献指南。

LangChain 参考最佳实践
  • 保持一致；遵循特定于提供商的文档的现有模式
  • 包括基本用法（代码片段）和常见的边缘情况/失败模式
  • 注意功能何时需要特定版本
何时创建新的参考文档
  • 新的集成或提供商需要专门的参考页面
  • 复杂的配置选项需要详细解释
  • API 变更引入了新参数或行为
  • 社区经常询问有关特定功能的问题

教程 ​

教程是较长篇幅的分步指南，它建立在自身基础上，引导用户完成特定的实践活动以建立理解。教程通常位于 Learn 选项卡上。

我们通常不会在没有迫切需求的情况下合并来自外部贡献者的新教程。如果您认为某个主题在文档中缺失或覆盖不足，请创建一个新 issue。

特点
  • 实践性强：专注于通过实践活动建立理解。
  • 分步说明：将活动分解为更小的步骤。
  • 动手操作：提供连续的、可运行的代码片段。
  • 补充性：提供不一定为使用功能所必需的额外上下文和信息。
技巧
  • 如果用户按顺序遵循步骤，代码片段应该是连续且可运行的。
  • 为活动提供一些上下文，但链接到相关的概念指南和参考以获取更详细的信息。
示例

编写标准 ​

参考文档有不同的标准 - 详情请参阅参考文档贡献指南。

Mintlify 组件 ​

使用 Mintlify 组件 来增强可读性：

标注框
结构
代码
  • <Note> 用于有用的补充信息
  • <Warning> 用于重要的警告和破坏性变更
  • <Tip> 用于最佳实践和建议
  • <Info> 用于中立的上下文信息
  • <Check> 用于成功确认

页面结构 ​

每个文档页面必须以 YAML frontmatter 开头：

yaml
---
title: "清晰、具体的标题"
sidebarTitle: "侧边栏的简短标题（可选）"
---

共置 Python 和 JavaScript/TypeScript 内容 ​

所有文档在可能的情况下都必须用 Python 和 JavaScript/TypeScript 两种语言编写。为此，我们使用自定义的内联语法来区分应出现在一种或两种语言中的部分：

mdx
\:::python
Python 特定内容。在实际文档中，`python` 前面的反斜杠被省略。
\:::

\:::js
JavaScript/TypeScript 特定内容。在实际文档中，`js` 前面的反斜杠被省略。
\:::

两种语言的通用内容（未包装）

这将生成两个输出（每种语言一个），分别位于 /oss/python/concepts/foo.mdx 和 /oss/javascript/concepts/foo.mdx。每个输出的页面都需要添加到 /src/docs.json 文件中才能包含在导航中。

我们不希望缺乏对等性阻碍贡献。如果某个功能仅在一个语言中可用，那么在该语言赶上之前，仅在该语言中提供文档是可以的。在这种情况下，请包含一个说明，指出该功能在另一种语言中尚不可用。

如果您需要帮助在 Python 和 JavaScript/TypeScript 之间翻译内容，请在社区 Slack 中提问或在您的 PR 中标记维护者。

质量标准 ​

通用指南 ​

避免重复

多个页面覆盖相同的材料难以维护并导致混淆。每个概念或功能应该只有一个规范页面。链接到其他指南，而不是重新解释。

频繁链接

文档部分不是孤立存在的。频繁链接到其他部分，以便用户了解不熟悉的主题。这包括链接到 API 参考和概念部分。

简洁明了

采取少即是多的方法。如果存在另一个解释良好的部分，请链接到它而不是重新解释，除非您的内容提供了新的角度。

无障碍要求 ​

确保文档对所有用户都是可访问的：

  • 使用标题和列表构建内容，便于扫描
  • 使用具体、

LangChain 中文文档

Copyright © 王码码