以编程方式使用文档

我们欢迎为 LangChain 文档做出贡献，包括新功能、 集成以及对现有文档的改进。

快速开始 - 本地开发

要运行文档的本地预览：

git clone https://github.com/langchain-ai/docs.git
cd docs
make install
make dev

这会启动一个热重载的开发服务器，地址为 http://localhost:3000。在 src/ 中编辑文件，即可立即查看更改。

Prerequisites

Required: - Python 3.13+ - uv - Python 包管理器 - Node.js 和 npm - Make - Git

Optional: - markdownlint-cli - npm install -g markdownlint-cli - Mintlify MDX VSCode 扩展

编辑文档

Quick edits on GitHub

对于拼写错误或小的更改，可以直接在 GitHub 上编辑，无需本地设置：

1. 点击 **在 GitHub 上编辑此页面** 在任意页面底部。 1. Fork 到您的个人账户。 1. 在 GitHub 的网页编辑器中进行更改。 1. 创建拉取请求。

  1. 编辑 src/ 遵循我们的 编写标准.
  2. 运行 质量检查 提交前。
  3. 创建拉取请求以供审核。

Create a sharable preview build (LangChain team only)

当您创建或更新 PR 时，会自动生成一个 preview branch/ID 。评论将留在 PR 上，包含 ID。

  1. 从评论中复制预览分支的 ID
  2. 在 Mintlify 仪表板，点击 **创建预览部署**
  3. 输入预览分支的 ID，然后点击 **创建部署**
  4. 选择预览并点击 **访问** 进行查看

要使用最新更改重新部署，请点击 **重新部署** 在仪表板上。

运行质量检查

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

# Check broken links
make broken-links

# Format code automatically
make format

# Check for linting issues
make lint

# Fix markdown issues
make lint_md_fix

# Run tests to ensure your changes don't break existing functionality
make test

有关更多详细信息，请参阅 可用命令 部分中的 README.

All pull requests are automatically checked by CI/CD. The same linting and formatting standards will be enforced, and PRs cannot be merged if these checks fail.

文档类型

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

How-to guides

面向用户的任务导向指导，用户知道他们想要完成什么。

Conceptual guides

提供更深入理解和见解的解释。

Reference

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

Tutorials

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

操作指南

操作指南是面向用户的任务导向指导，用户知道他们想要完成什么。操作指南的示例在 LangChain 和 LangGraph tabs.

Characteristics

- **Task-focused**：专注于特定的任务或问题 - **Step-by-step**：将任务分解为更小的步骤 - **Hands-on**：提供具体的示例和代码片段

Tips

- 关注 **方法** 而不是 **原因** - 使用具体的示例和代码片段 - 将任务分解为更小的步骤 - 链接到相关的概念指南和参考资料

Examples

- 消息 - 工具 - 流式处理

概念指南

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

Characteristics

- **Understanding-focused**：解释事情为何如此运作 - **更广阔的视角**：比其他类型更高更宽的视角 - **Design-oriented**：解释决策和权衡 - **Context-rich**：使用类比和比较

Tips

- 关注 **"原因"** 而不是"方法" - 提供不一定对功能使用必需的补充信息 - 可以使用类比和参考替代方案 - 避免混入过多的参考内容 - 链接到相关的教程和操作指南

Examples

- 内存 - 上下文 - Graph API - Functional API

参考

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

Python reference

JavaScript/TypeScript reference

好的参考应该： - 描述现有的内容（所有参数、选项、返回值） - 全面且结构化，便于查找 - 作为技术细节的权威来源

Contributing to references

此处生成的 API 参考文档 reference.langchain.com 是在此仓库外部构建和部署的。如需报告其中的错误、缺失的包或损坏的页面， 请提交参考文档问题.

LangChain reference best practices

- **保持一致**；遵循现有模式编写提供商特定文档 - Include both basic usage (code snippets) and common edge cases/failure modes - 注意功能所需的特定版本

When to create new reference documentation

- 新的集成或提供商需要专门的参考页面 - 复杂的配置选项需要详细说明 - API 变更引入新参数或行为 - 社区经常询问有关特定功能的问题

教程

教程是较长的分步指南，逐步递进，引导用户完成特定的实践活动以建立理解。教程通常位于 学习 tab.

Characteristics

- **实用性**：专注于实践活动以建立理解。 - **Step-by-step**：将活动分解为更小的步骤。 - **Hands-on**：提供顺序且可运行的代码片段。 - **补充性**：提供不一定对功能使用必需的额外背景和信息。

Tips

- 代码片段应该是顺序的且可运行的，如果用户按顺序遵循步骤。 - 为活动提供一些背景，但链接到相关的概念指南和参考资料以获取更详细的信息。

Examples

- 语义搜索 - RAG 代理

写作标准

Mintlify 组件

使用 Mintlify 组件 增强可读性：

Callouts

- <aside class="callout"><strong>提示</strong> 用于有用的补充信息 - <aside class="callout"><strong>警告</strong> 用于重要警告和破坏性变更 - <aside class="callout"><strong>建议</strong> 用于最佳实践和建议 - <aside class="callout"><strong>信息</strong> 用于中性背景信息 - <aside class="callout"><strong>检查</strong> 用于成功确认

Structure

- ` 用于顺序流程的概述。 **不要** 用于冗长的步骤列表或教程。 - 用于平台特定内容。 - 和 <section class="mdx-block"> 用于可默认折叠的辅助信息（例如，完整代码示例）。 - 和 ` 用于高亮内容。

Code

- ` 用于多语言示例。 - 始终在代码块上指定语言标签（例如， 

    - 代码块的标题（例如 `Success`, `Error Response`)
### Mermaid 图表 添加 Mermaid 图表时，请使用 LangChain 品牌配色方案进行节点样式设置。复制 `classDef` 行从任何现有图表，或使用 [`CLAUDE.md`](https://github.com/langchain-ai/docs/blob/main/CLAUDE.md#mermaid-diagram-styling). | 角色 | 填充 | 描边 | 文本 | |------|------|--------|------| | 流程 | `#E5F4FF` | `#006DDD` | `#030710` | | 触发器 | `#F6FFDB` | `#6E8900` | `#2E3900` | | 判断 | `#FDF3FF` | `#7E65AE` | `#504B5F` | | 输出 | `#EBD0F0` | `#885270` | `#441E33` | | 警报 | `#F8E8E6` | `#B27D75` | `#634643` | | 中性 | `#F2FAFF` | `#40668D` | `#2F4B68` | 请勿使用 Tailwind 默认值、Material Design 颜色或其他非品牌配色方案。 ### 页面结构 每个文档页面必须以 YAML frontmatter 开头： yaml

title: "Clear, specific title" sidebarTitle: "Short title for the sidebar (optional)"

### Co-locate Python and JavaScript/TypeScript content

All documentation must be written in both Python and JavaScript/TypeScript when possible. To do so, we use a custom in-line syntax to differentiate between sections that should appear in one or both languages:
mdx :::python Python-specific content. In real docs, the preceding backslash (before `python`) is omitted. :::

:::js JavaScript/TypeScript-specific content. In real docs, the preceding backslash (before js) is omitted. :::

Content for both languages (not wrapped)

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


<aside class="callout"><strong>提示</strong>

    我们不希望缺乏对等性阻止贡献。如果某个功能仅在一种语言中可用，则可以仅以该语言提供文档，直到另一种语言赶上来。在这种情况下，请包含一条说明，指出该功能在另一种语言中尚不可用。

    If you need help translating content between Python and JavaScript/TypeScript, please ask in the [社区 Slack](https://www.langchain.com/join-community) 或在您的 PR 中标记维护者。

</aside>


## 质量标准

### 通用指南



        涵盖相同材料的多个页面难以维护并造成混淆。每个概念或功能应该只有一个规范页面。请链接到其他指南而不是重新解释。
    </section>



<section class="mdx-block"><h3>Link frequently</h3>

        文档部分并非独立存在。频繁链接到其他部分，让用户能够了解不熟悉的主题。这包括链接到 API 参考和概念部分。
    </section>



<section class="mdx-block"><h3>Be concise</h3>

        采取少即是多的方法。如果存在另一部分且有很好的解释，请链接到它而不是重新解释，除非您的内容提出了新的角度。
    </section>



### 无障碍要求

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

- 使用标题和列表组织内容以便于浏览
- 使用具体、可操作的链接文本，而不是"点击这里"
- 为所有图像和图表包含描述性替代文本

### Cross-referencing

使用一致的交叉引用来连接文档与 API 参考文档。

**从文档到 API 参考：**

使用 `@[]` 语法链接到 API 参考页面：
mdx See @[`ChatAnthropic`] for all configuration options.

The @[bind_tools][ChatAnthropic.bind_tools] method accepts... ```

构建管道根据当前语言范围（Python 或 JavaScript）将这些转换为正确的 markdown 链接。例如， @[ChatAnthropic] 会根据正在构建的文档版本成为指向 Python 或 JS API 参考页面的链接， **但前提是 link_map.py 文件中存在相应条目！** 请参阅下文了解详情。

How autolinks work

该 @[] 语法由 handle_auto_links.py处理。它在 link_map.py中查找链接键，其中包含 Python 和 JavaScript 作用域的字典映射。

支持的格式：

语法结果
@[ChatAnthropic]以 "ChatAnthropic" 作为显示文本的链接
` @[ChatAnthropic] `带 ` ChatAnthropic ` （代码格式）作为文本的链接
@[text][ChatAnthropic]以 "text" 作为文本且以 ChatAnthropic 作为链接映射中的键的链接
\@[ChatAnthropic]转义：渲染为字面 @[ChatAnthropic] （无链接——这是本页使用的格式！）

添加新链接：

如果链接映射中找不到该链接，则会在输出中保持不变。要添加新的自动链接：

  1. 打开 pipeline/preprocessors/link_map.py
  2. 在相应的作用域中添加条目（python or js) in LINK_MAPS
  3. 键是在 @[key] or @[text][key]中使用的链接名称，值是相对于引用主机的路径

从 API 参考存根到开源文档：

发布的 Python API 参考中的交叉链接和深层锚点是在此仓库外生成的。如果从 reference.langchain.com 到 docs.langchain.com 的链接有误或已过时， 请提交问题 ，并附上源 URL 和目标 URL。

本地化

如果某个功能在两个 SDK 中都存在，请为 Python and JavaScript/TypeScript together编写文档。如果只支持一种语言，请确保该功能及其引用仅对该语言可见。

代码内文档

示例必须正确，且在可能的情况下可以复制粘贴，并 **经过测试** 后再打开拉取请求。请清楚地标记不可运行的代码片段（例如伪代码或说明性片段）。

获取帮助

我们的目标是让开发者能够尽可能简单地完成设置。如果您在此过程中遇到困难，请在 社区 Slack 提问，或在 论坛发帖。内部团队成员可以在 #documentation Slack 频道联系我们。