贡献代码

¥Contribute Code

要为此项目做出贡献，请遵循 "分叉和拉取请求" 工作流程。除非你是维护者，否则请勿尝试直接推送到此代码库。

¥To contribute to this project, please follow the "fork and pull request" workflow. Please do not try to push directly to this repo unless you are a maintainer.

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

¥Please follow the checked-in pull request template when opening pull requests. Note related issues and tag relevant maintainers.

拉取请求必须先通过格式、linting 和测试检查才能生效。请参阅 测试 和 格式化和 Linting，了解如何在本地运行这些检查。

¥Pull requests cannot land without passing the formatting, linting, and testing checks first. See Testing and Formatting and Linting for how to run these checks locally.

维护良好的文档和测试至关重要。如果你：

¥It's essential that we maintain great documentation and testing. If you:

• 修复错误

  ¥Fix a bug

  • 尽可能添加相关的单元测试或集成测试。它们存在于 **/tests/*.test.ts 和 **/tests/*.int.test.ts/ 中。

    ¥Add a relevant unit or integration test when possible. These live in **/tests/*.test.ts and **/tests/*.int.test.ts/.

• 改进

  ¥Make an improvement

  • 更新任何受影响的示例注意本和文档。这些在 docs 中可用。

    ¥Update any affected example notebooks and documentation. These live in docs.

  • 在相关时更新单元测试和集成测试。

    ¥Update unit and integration tests when relevant.

• 添加功能

  ¥Add a feature

  • 在 docs/core_docs/docs 中添加一个演示注意本/MDX 文件。

    ¥Add a demo notebook/MDX file in docs/core_docs/docs.

  • 添加单元测试和集成测试。

    ¥Add unit and integration tests.

我们是一个小型的、以进步为导向的团队。如果你想添加或更改某些内容，提交拉取请求是引起我们注意的最佳方式。

¥We are a small, progress-oriented team. If there's something you'd like to add or change, opening a pull request is the best way to get our attention.

🚀 快速开始

¥🚀 Quick Start

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

¥This quick start guide explains how to run the repository locally. For a development container, see the .devcontainer folder.

🏭 发布流程

¥🏭 Release process

目前，LangChain 有一个临时发布流程：版本由开发者高频次剪切并发布到 npm。

¥As of now, LangChain has an ad hoc release process: releases are cut with high frequency by a developer and published to npm.

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

¥LangChain follows the semver versioning standard. However, as pre-1.0 software, even patch releases may contain non-backwards-compatible changes.

如果你的贡献已进入发布版本，我们将在 Twitter 上给予你荣誉（但前提是你愿意）！如果你有希望我们提及的 Twitter 账户，请在 PR 或其他方式中告知我们。

¥If your contribution has made its way into a release, we will want to give you credit on Twitter (only if you want though)! If you have a Twitter account you would like us to mention, please let us know in the PR or in another manner.

集成版本

¥Integration releases

发布脚本只能在新的 main 分支上执行，且该分支没有未提交的更改，并且来自包根目录。如果从存储库的分支进行操作，请确保首先将分支的 main 分支与上游 main 分支同步。

¥The release script can be executed only while on a fresh main branch, with no un-committed changes, from the package root. If working from a fork of the repository, make sure to sync the forked main branch with the upstream main branch first.

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

¥You can invoke the script by calling yarn release. If new dependencies have been added to the integration package, install them first (i.e. run yarn, then yarn release).

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

¥There are three parameters which can be passed to this script, one required and two optional.

• 必需：<workspace name>。例如：@langchain/core 待发布的软件包的名称。可以在包的 package.json 的 name 值中找到

  ¥Required: <workspace name>. eg: @langchain/core The name of the package to release. Can be found in the name value of the package's package.json

• 可选：--bump-deps 例如 --bump-deps 将在代码库中查找所有依赖此工作区的包，并检出一个新分支、更新依赖版本、运行 yarn install、提交并推送到新分支。通常，这不是必需的。

  ¥Optional: --bump-deps eg --bump-deps Will find all packages in the repo which depend on this workspace and checkout a new branch, update the dep version, run yarn install, commit & push to new branch. Generally, this is not necessary.

• 可选：--tag <tag> 例如 --tag beta 为 NPM 版本添加标签。如果你想发布候选版本，这很有用。

  ¥Optional: --tag <tag> eg --tag beta Add a tag to the NPM release. Useful if you want to push a release candidate.

此脚本会自动更新包版本，创建一个包含更改的新发布分支，将分支推送到 GitHub，使用 release-it 自动发布到 NPM，并根据传递的标志执行更多操作。

¥This script automatically bumps the package version, creates a new release branch with the changes, pushes the branch to GitHub, uses release-it to automatically release to NPM, and more depending on the flags passed.

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

¥Halfway through this script, you'll be prompted to enter an NPM OTP (typically from an authenticator app). This value is not stored anywhere and is only used to authenticate the NPM release.

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

¥Unless releasing langchain, no should be answered to all prompts following Publish @langchain/<package> to npm?. Then, the change should be manually committed with the following commit message: <package>[patch]: Release <new version>. E.g.: groq[patch]: Release 0.0.1.

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

¥Docker must be running if releasing one of langchain, @langchain/core or @langchain/community. These packages run LangChain's export tests, which run inside docker containers.

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

¥Full example: yarn release @langchain/core.

🛠️ 工具

¥🛠️ Tooling

本项目使用以下工具，如果你计划做出贡献，这些工具值得熟悉：

¥This project uses the following tools, which are worth getting familiar with if you plan to contribute:

• yarn（v3.4.1） - 依赖管理

  ¥yarn (v3.4.1) - dependency management

• eslint - 强制执行标准 lint 规则

  ¥eslint - enforcing standard lint rules

• prettier - 强制执行标准代码格式

  ¥prettier - enforcing standard code formatting

• jest - 测试代码

  ¥jest - testing code

• TypeDoc - 从评论生成参考文档

  ¥TypeDoc - reference doc generation from comments

• Docusaurus - 用于文档的静态站点生成

  ¥Docusaurus - static site generation for documentation

🚀 快速开始

¥🚀 Quick Start

克隆此代码库，然后 cd 到其中：

¥Clone this repo, then cd into it:

cd langchainjs

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

¥Next, try running the following common tasks:

✅ 常见任务

¥✅ Common Tasks

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

¥Our goal is to make it as easy as possible for you to contribute to this project. All of the below commands should be run from within a workspace directory (e.g. langchain, libs/langchain-community) unless otherwise noted.

cd langchain

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

¥Or, if you are working on a community integration:

cd libs/langchain-community

设置

¥Setup

先决条件：需要 Node 18 及以上版本。请检查 Node 版本 node -v，并在需要时进行更新。

¥Prerequisite: Node version 18+ is required. Please check node version node -v and update it if required.

要开始使用，你需要安装项目的依赖。要执行此操作，请运行：

¥To get started, you will need to install the dependencies for the project. To do so, run:

yarn

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

¥Then, you will need to switch directories into langchain-core and build core by running:

cd ../langchain-core
yarn
yarn build

Linting

我们使用 eslint 来强制执行标准 lint 规则。要运行 linter，请运行：

¥We use eslint to enforce standard lint rules. To run the linter, run:

yarn lint

格式化

¥Formatting

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

¥We use prettier to enforce code formatting style. To run the formatter, run:

yarn format

如果仅检查格式差异而不进行修复，请运行：

¥To just check for formatting differences, without fixing them, run:

yarn format:check

测试

¥Testing

通常，测试应该与正在测试的模块一起添加到 tests/ 文件夹中。

¥In general, tests should be added within a tests/ folder alongside the modules they are testing.

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

¥Unit tests cover modular logic that does not require calls to outside APIs.

如果你添加了新的逻辑，请添加单元测试。单元测试应该被称为 *.test.ts。

¥If you add new logic, please add a unit test. Unit tests should be called *.test.ts.

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

¥To run only unit tests, run:

yarn test

运行单个测试

¥Running a single test

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

¥To run a single test, run the following from within a workspace:

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

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

¥This is useful for developing individual features.

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

¥Integration tests cover logic that requires making calls to outside APIs (often integration with other services).

如果你添加了对新外部 API 的支持，请添加新的集成测试。集成测试应该称为 *.int.test.ts。

¥If you add support for a new external API, please add a new integration test. Integration tests should be called *.int.test.ts.

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

¥Note that most integration tests require credentials or other setup. You will likely need to set up a langchain/.env or libs/langchain-community/.env file like the example here.

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

¥We generally recommend only running integration tests with yarn test:single, but if you want to run all integration tests, run:

yarn test:integration

构建

¥Building

要构建项目，请运行：

¥To build the project, run:

yarn build

添加入口点

¥Adding an Entrypoint

LangChain 提供了多个子路径供用户导入，例如：

¥LangChain exposes multiple subpaths the user can import from, e.g.

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

我们将这些子路径称为 "entrypoints"。通常，如果你要添加与第三方库的新集成，则应该创建一个新的入口点。如果你要添加不带任何外部依赖的独立功能，则可以将其添加到现有的入口点。

¥We call these subpaths "entrypoints". In general, you should create a new entrypoint if you are adding a new integration with a 3rd party library. If you're adding self-contained functionality without any external dependencies, you can add it to an existing entrypoint.

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

¥In order to declare a new entrypoint that users can import from, you should edit the langchain/langchain.config.js or libs/langchain-community/langchain.config.js file. To add an entrypoint tools that imports from tools/index.ts you'd add the following to the entrypoints key inside the config variable:

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

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

¥If you're adding a new integration which requires installing a third party dependency, you must add the entrypoint to the requiresOptionalDependency array, also located inside langchain/langchain.config.js or libs/langchain-community/langchain.config.js.

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

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

¥This will make sure the entrypoint is included in the published package, and in generated documentation.

文档

¥Documentation

贡献文档

¥Contribute Documentation

安装依赖

¥Install dependencies

注意：如果你在本地构建文档站点，则只需遵循以下步骤。

¥Note: you only need to follow these steps if you are building the docs site locally.

1. Quarto - 将 Jupyter 注意本（.ipynb 文件）转换为 .mdx 文件以便在 Docusaurus 中服务的软件包。

   ¥Quarto - package that converts Jupyter notebooks (.ipynb files) into .mdx files for serving in Docusaurus.

2. yarn build --filter=core_docs - 就这么简单！（或者你可以直接从 docs/core_docs/ 运行 yarn build）

   ¥yarn build --filter=core_docs - It's as simple as that! (or you can simply run yarn build from docs/core_docs/)

所有注意本都将转换为 .md 文件并自动被 gitignored。如果你想创建非注意本文档，则必须是 .mdx 文件。

¥All notebooks are converted to .md files and automatically gitignored. If you would like to create a non notebook doc, it must be a .mdx file.

编写注意本

¥Writing Notebooks

在注意本中添加新的依赖时，必须更新 LangChain 代码库根目录中 deno.json 中的导入映射。

¥When adding new dependencies inside the notebook you must update the import map inside deno.json in the root of the LangChain repo.

这是必需的，因为注意本使用 Deno 运行时，而 Deno 导入格式与 Node.js 不同。

¥This is required because the notebooks use the Deno runtime, and Deno formats imports differently than Node.js.

示例：

¥Example:

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

查看 deno.json 中的示例了解更多详情。

¥See examples inside deno.json for more details.

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

¥Docs are largely autogenerated by TypeDoc from the code.

因此，我们要求你为所有类和方法添加完善的文档。

¥For that reason, we ask that you add good documentation to all classes and methods.

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

¥Similar to linting, we recognize documentation can be annoying. If you do not want to do it, please contact a project maintainer, and they can help you with it. We do not want this to be a blocker for good code getting contributed.

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

¥Documentation and the skeleton lives under the docs/ folder. Example code is imported from under the examples/ folder.

运行示例

¥Running examples

如果你添加了一项重要的新功能，最好添加一个示例来展示如何使用它。我们的大多数用户认为示例是最有用的文档。

¥If you add a new major piece of functionality, it is helpful to add an example to showcase how to use it. Most of our users find examples to be the most helpful kind of documentation.

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

¥Examples can be added in the examples/src directory, e.g. examples/src/path/to/example. This example can then be invoked with yarn example path/to/example at the top level of the repo.

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

¥To run examples that require an environment variable, you'll need to add a .env file under examples/.env.

本地构建文档

¥Build Documentation Locally

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

¥To generate and view the documentation locally, change to the project root and run yarn to ensure dependencies get installed in both the docs/ and examples/ workspaces:

cd ..
yarn

然后运行：

¥Then run:

yarn docs

高级

¥Advanced

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

¥Environment tests test whether LangChain works across different JS environments, including Node.js (both ESM and CJS), Edge environments (eg. Cloudflare Workers), and browsers (using Webpack).

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

¥To run the environment tests with Docker, run the following command from the project root:

yarn test:exports:docker