贡献代码

要为此项目做出贡献，请遵循 “fork and pull request” 工作流程。除非您是维护者，否则请勿尝试直接推送到此仓库。

打开 pull request 时，请遵循已签入的 pull request 模板。请注意相关问题并标记相关的维护者。

Pull request 必须先通过格式化、代码检查和测试检查才能合并。有关如何在本地运行这些检查，请参阅 测试 和 格式化和代码检查。

维护出色的文档和测试至关重要。如果您

• 修复错误
  • 请尽可能添加相关的单元测试或集成测试。这些测试位于 **/tests/*.test.ts 和 **/tests/*.int.test.ts/ 中。
• 进行改进
  • 请更新任何受影响的示例 notebook 和文档。这些内容位于 docs 中。
  • 在相关时更新单元测试和集成测试。
• 添加功能
  • 在 docs/core_docs/docs 中添加演示 notebook/MDX 文件。
  • 添加单元测试和集成测试。

我们是一个小型且注重进度的团队。如果您想添加或更改任何内容，打开 pull request 是引起我们注意的最佳方式。

🚀 快速开始

本快速入门指南解释了如何在本地运行仓库。有关开发容器，请参阅 .devcontainer 文件夹。

🏭 发布流程

目前，LangChain 采用临时的发布流程：发布由开发人员高频率地进行，并发布到 npm。

LangChain 遵循 semver 版本控制标准。但是，作为 1.0 之前的软件，即使是补丁版本也可能包含 非向后兼容的更改。

如果您的贡献已纳入发布版本，我们希望在 Twitter 上表扬您（仅在您愿意的情况下）！如果您有希望我们提及的 Twitter 帐户，请在 PR 中或以其他方式告知我们。

集成发布

发布脚本只能在干净的 main 分支上执行，且没有未提交的更改，从软件包根目录开始。如果从仓库的 fork 分支工作，请确保先将 fork 的 main 分支与上游 main 分支同步。

您可以通过调用 yarn release 来调用该脚本。如果已向集成软件包添加了新的依赖项，请先安装它们（即运行 yarn，然后运行 yarn release）。

此脚本可以传递三个参数，一个必需参数和两个可选参数。

• 必需: <workspace name>。例如：@langchain/core 要发布的软件包的名称。可以在软件包的 package.json 的 name 值中找到
• 可选: --bump-deps 例如 --bump-deps 将查找仓库中所有依赖于此工作区的软件包，并检出一个新分支，更新依赖版本，运行 yarn install，提交并推送到新分支。通常，这不是必需的。
• 可选: --tag <tag> 例如 --tag beta 向 NPM 版本添加标签。如果您想推送候选版本，这将非常有用。

此脚本会自动增加软件包版本，使用更改创建一个新的发布分支，将该分支推送到 GitHub，使用 release-it 自动发布到 NPM，以及更多取决于传递的标志的操作。

在此脚本执行到一半时，系统会提示您输入 NPM OTP（通常来自身份验证器应用程序）。此值不会存储在任何地方，仅用于验证 NPM 发布。

注意 除非发布 langchain，否则对于 Publish @langchain/<package> to npm? 之后的所有提示，都应回答 no。然后，应使用以下提交消息手动提交更改：<package>[patch]: Release <new version>。例如：groq[patch]: Release 0.0.1。

如果要发布 langchain、@langchain/core 或 @langchain/community 中的任何一个，则必须运行 Docker。这些软件包运行 LangChain 的导出测试，这些测试在 docker 容器内运行。

完整示例：yarn release @langchain/core。

🛠️ 工具

本项目使用以下工具，如果您计划贡献代码，则值得熟悉这些工具

• yarn (v3.4.1) - 依赖管理
• eslint - 强制执行标准代码检查规则
• prettier - 强制执行标准代码格式化
• jest - 测试代码
• TypeDoc - 从注释生成参考文档
• Docusaurus - 用于文档的静态站点生成

🚀 快速开始

克隆此仓库，然后 cd 进入它

cd langchainjs

接下来，尝试运行以下常用任务

✅ 常用任务

我们的目标是让您尽可能轻松地为此项目做出贡献。除非另有说明，否则以下所有命令都应从工作区目录（例如 langchain、libs/langchain-community）中运行。

cd langchain

或者，如果您正在进行社区集成

cd libs/langchain-community

设置

前提条件：需要 Node 版本 18+。请检查 node 版本 node -v 并在需要时更新它。

要开始使用，您需要安装项目的依赖项。为此，请运行

yarn

然后，您需要切换目录到 langchain-core 并通过运行以下命令构建核心

cd ../langchain-core
yarn
yarn build

代码检查

我们使用 eslint 来强制执行标准代码检查规则。要运行 linter，请运行

yarn lint

格式化

我们使用 prettier 来强制执行代码格式化样式。要运行格式化程序，请运行

yarn format

要仅检查格式差异而不修复它们，请运行

yarn format:check

测试

通常，测试应添加到 tests/ 文件夹中，与它们正在测试的模块位于同一位置。

单元测试 涵盖不需要调用外部 API 的模块化逻辑。

如果您添加新逻辑，请添加单元测试。单元测试应命名为 *.test.ts。

要仅运行单元测试，请运行

yarn test

运行单个测试

要运行单个测试，请从工作区内运行以下命令

yarn test:single /path/to/yourtest.test.ts

这对于开发单个功能非常有用。

集成测试 涵盖需要调用外部 API 的逻辑（通常与其他服务集成）。

如果您添加对新外部 API 的支持，请添加新的集成测试。集成测试应命名为 *.int.test.ts。

请注意，大多数集成测试都需要凭据或其他设置。您可能需要设置一个 langchain/.env 或 libs/langchain-community/.env 文件，例如 此处 的示例。

我们通常建议仅使用 yarn test:single 运行集成测试，但如果您想运行所有集成测试，请运行

yarn test:integration

构建

要构建项目，请运行

yarn build

添加入口点

LangChain 公开了用户可以从中导入的多个子路径，例如

import { OpenAI } from "langchain/llms/openai";

我们将这些子路径称为“入口点”。通常，如果您要添加与第三方库的新集成，则应创建新的入口点。如果您要添加没有任何外部依赖项的独立功能，则可以将其添加到现有的入口点。

为了声明用户可以从中导入的新入口点，您应该编辑 langchain/langchain.config.js 或 libs/langchain-community/langchain.config.js 文件。要添加从 tools/index.ts 导入的入口点 tools，您需要将以下内容添加到 config 变量内的 entrypoints 键中

// ...
entrypoints: {
  // ...
  tools: "tools/index",
},
// ...

如果您要添加需要安装第三方依赖项的新集成，则必须将入口点添加到 requiresOptionalDependency 数组中，该数组也位于 langchain/langchain.config.js 或 libs/langchain-community/langchain.config.js 中。

// ...
requiresOptionalDependency: [
  // ...
  "tools/index",
],
// ...

这将确保入口点包含在已发布的软件包和生成的文档中。

文档

贡献文档

安装依赖项

注意：您只需在本地构建文档站点时才需要执行这些步骤。

1. Quarto - 将 Jupyter notebook (.ipynb 文件) 转换为 .mdx 文件以在 Docusaurus 中提供的软件包。
2. yarn build --filter=core_docs - 就这么简单！（或者您可以直接从 docs/core_docs/ 运行 yarn build）

所有 notebook 都将转换为 .md 文件并自动被 gitignore。如果您想创建非 notebook 文档，则必须是 .mdx 文件。

编写 Notebook

在 notebook 中添加新依赖项时，您必须更新 LangChain 仓库根目录中的 deno.json 中的导入映射。

这是必需的，因为 notebook 使用 Deno 运行时，并且 Deno 的导入格式与 Node.js 不同。

示例

// Import in Node:
import { z } from "zod";
// Import in Deno:
import { z } from "npm:/zod";

有关更多详细信息，请参阅 deno.json 中的示例。

文档主要由 TypeDoc 从代码自动生成。

因此，我们要求您为所有类和方法添加良好的文档。

与代码检查类似，我们认识到文档可能很烦人。如果您不想这样做，请联系项目维护者，他们可以帮助您。我们不希望这成为贡献优秀代码的障碍。

文档和框架位于 docs/ 文件夹下。示例代码从 examples/ 文件夹下导入。

运行示例

如果您添加了新的主要功能，则添加一个示例来展示如何使用它会很有帮助。我们的大多数用户发现示例是最有帮助的文档类型。

可以在 examples/src 目录中添加示例，例如 examples/src/path/to/example。然后可以在仓库的顶层使用 yarn example path/to/example 调用此示例。

要运行需要环境变量的示例，您需要在 examples/.env 下添加一个 .env 文件。

本地构建文档

要在本地生成和查看文档，请更改到项目根目录并运行 yarn 以确保依赖项安装在 docs/ 和 examples/ 工作区中

cd ..
yarn

然后运行

yarn docs

高级

环境测试 测试 LangChain 是否可以在不同的 JS 环境中工作，包括 Node.js（ESM 和 CJS）、Edge 环境（例如 Cloudflare Workers）和浏览器（使用 Webpack）。

要使用 Docker 运行环境测试，请从项目根目录运行以下命令

yarn test:exports:docker