贡献代码
要为该项目做出贡献,请遵循 “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
接下来,尝试运行以下常见任务
✅ 常见任务
我们的目标是让您尽可能轻松地为该项目做出贡献。除非另有说明,否则以下所有命令都应在工作区目录(例如 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 来强制执行标准代码风格规则。要运行代码风格检查器,请运行
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",
],
// ...
这将确保入口点包含在发布的包中,以及在生成的文档中。
文档
贡献文档
安装依赖项
注意:只有在您本地构建文档站点时才需要执行这些步骤。
- Quarto - 将 Jupyter 笔记本(
.ipynb
文件)转换为.mdx
文件以在 Docusaurus 中提供服务的包。 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