跳至主要内容

贡献代码

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

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

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

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

  • 修复错误
    • 如果可能,请添加相关的单元测试或集成测试。这些位于 **/tests/*.test.ts**/tests/*.int.test.ts/ 中。
  • 进行改进
    • 更新任何受影响的示例笔记本和文档。这些位于 docs 中。
    • 更新相关的单元测试和集成测试。
  • 添加功能
    • docs/core_docs/docs 中添加一个演示笔记本/MDX 文件。
    • 添加单元测试和集成测试。

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

🚀 快速入门

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

🏭 发布流程

截至目前,LangChain 采用了一种临时发布流程:发布由开发人员高频率地进行并发布到 npm

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

如果您的贡献已包含在某个版本中,我们会希望在 Twitter 上给您署名(当然,只有在您希望的情况下!)。如果您有一个希望我们提到的 Twitter 帐户,请在 PR 中或以其他方式告知我们。

集成发布

发布脚本只能在全新 main 分支上执行,且没有未提交的更改,从包根目录执行。如果从仓库的 fork 中工作,请确保首先将 fork 的 main 分支与上游 main 分支同步。

您可以通过调用 yarn release 来调用脚本。如果已将新依赖项添加到集成包中,请先安装它们(即运行 yarn,然后运行 yarn release)。

此脚本可以接收三个参数,一个必需,两个可选。

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

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

在此脚本的执行过程中,系统会提示您输入 NPM OTP(通常来自身份验证器应用程序)。此值不会存储在任何地方,仅用于对 NPM 发布进行身份验证。

注意 除非发布 langchain@langchain/core@langchain/community,否则对于 Publish @langchain/<package> to npm? 之后的提示,应全部回答 no。然后,应使用以下提交消息手动提交更改:<package>[patch]: Release <新版本>。例如: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 langchainjs

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

✅ 常见任务

我们的目标是让您尽可能轻松地为该项目做出贡献。除非另有说明,否则以下所有命令都应在工作区目录(例如 langchainlibs/langchain-community)中运行。

cd langchain

或者,如果您正在处理社区集成

cd libs/langchain-community

设置

先决条件:需要 Node 版本 18+。请检查 node 版本 node -v,并在需要时更新它。

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

yarn

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

cd ../langchain-core
yarn
yarn build

代码风格检查

我们使用 eslint 来强制执行标准代码风格规则。要运行代码风格检查器,请运行

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/.envlibs/langchain-community/.env 文件,例如 此处所示的示例。

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

yarn test:integration

构建

要构建项目,请运行

yarn build

添加入口点

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

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

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

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

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

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

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

这将确保入口点包含在发布的包中,以及在生成的文档中。

文档

贡献文档

安装依赖项

注意:只有在您本地构建文档站点时才需要执行这些步骤。
  1. Quarto - 将 Jupyter 笔记本(.ipynb 文件)转换为 .mdx 文件以在 Docusaurus 中提供服务的包。
  2. yarn build --filter=core_docs - 就这么简单!(或者您可以简单地从docs/core_docs/运行yarn build

所有笔记本都转换为.md文件并自动忽略git。如果您想创建一个非笔记本文档,它必须是.mdx文件。

编写笔记本

在笔记本内部添加新依赖项时,必须更新LangChain存储库根目录中deno.json内的导入映射。

这是必需的,因为笔记本使用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

此页面是否有帮助?


您还可以留下详细的反馈 在 GitHub 上.