开发者文档#

成为 Argilla 的开发者意味着你是 Argilla 社区的一份子，并且你正在为 Argilla 的开发做出贡献。此页面将引导你完成设置开发环境并开始为 Argilla 做出贡献所需的步骤。Argilla 构建于不同的核心组件之上

  • 文档：Argilla 的文档是宝贵的资源，为寻求探索、理解和有效利用 Argilla 生态系统核心组件的用户提供全面而深入的指南。

  • Python SDK：一个 Python SDK，可以使用 pip install argilla 安装，用于与 Argilla 服务器和 Argilla UI 交互。它提供了一个 API 来管理数据、配置和标注工作流。

  • FastAPI 服务器：Argilla 的核心是一个 Python FastAPI server，它通过预处理数据并将其存储在向量数据库中来管理数据。此外，它还将应用程序信息存储在关系数据库中。它提供了一个 REST API，用于与来自 Python SDK 和 Argilla UI 的数据进行交互。它还提供了一个 Web 界面来可视化数据。

  • 关系数据库：一个关系数据库，用于存储记录的元数据和标注。SQLite 用作默认的内置选项，并与 Argilla 服务器分开部署，但也可以使用单独的 PostgreSQL。

  • Redis：Redis 用于存储有关后台作业的信息，并且是 Argilla 服务器的必需依赖项。

  • 向量数据库：一个向量数据库，用于存储记录数据并执行可扩展的向量相似性搜索和基本文档搜索。我们目前支持 ElasticSearch 和 AWS OpenSearch，它们可以作为单独的 Docker 镜像部署。

  • Vue.js UI：一个 Web 应用程序，用于可视化和标注你的数据、用户和团队。它使用 Vue.js 构建，并与 Argilla 服务器一起直接部署在我们的 Argilla Docker 镜像中。

Argilla 仓库具有 monorepo 结构，这意味着所有组件都位于同一个仓库中：argilla-io/argilla。此仓库分为以下文件夹

为了正确安装，你需要

然后，你可以开始 做出你的贡献！

设置文档环境#

为了开始你的 Argilla 贡献之旅，强烈建议你沉浸在文档中。为此，我们建议你创建一个虚拟环境并按照以下步骤操作。要构建文档，只需要一组减少的依赖项。

克隆 Argilla 仓库#

首先，你必须 fork 我们的仓库并将 fork 克隆到你的计算机。有关更多信息，你可以查看我们的 指南。

git clone https://github.com/[your-github-username]/argilla.git
cd argilla

为了使你的 fork 的 main 分支与我们的仓库保持同步，你应该将其添加为 上游远程分支

git remote add upstream https://github.com/argilla-io/argilla.git

请记住，要处理文档，你将使用从 main 创建的分支。

安装依赖项#

要构建文档，请确保通过安装所需的依赖项来设置你的系统。

pip install -r docs/_source/requirements.txt

在安装过程中，你可能会遇到以下错误：需要 Microsoft Visual C++ 14.0 或更高版本。为了轻松解决此问题，请查看此链接。

构建文档#

为了构建文档，使用了 sphinx，一个开源文档生成器，也就是说，它使用 reStructuredText 来编写文档。使用 Sphinx 的命令行工具，它接受纯文本的源文件集合，并将其生成为 HTML 格式。它还自动创建目录、索引页和搜索功能，从而增强导航。为此，需要以下文件

  • index.rst：这是我们文档的主要入口点，可以在根 URL 访问。它通常包含目录（使用 toc 树），将用户连接到其他文档部分。

  • conf.py：此文件可以自定义文档的输出。

  • Makefile：Sphinx 提供的关键组件，充当本地开发的主要工具。

  • 其他 .rst 文件：这些文件用于文档的特定子章节。

  • Markdown 文件：带有纯文本的源文件。

在我们的例子中，我们依赖 MyST-Parser 来方便我们使用 Markdown。因此，至关重要的是，在编写文档时，我们利用正确的交叉引用来连接各个部分和文档。下面，你可以找到常用交叉引用的典型示例

# To reference a previous section

[](#explicit-targets).

# To reference a section in another document

(my_target)= ## Explicit targets
Reference [](my_target).

# To add explicit references

- {ref}`my target`.
- {ref}`Target to paragraph <target_to_paragraph>`.

# To link to a page in the same directory

- {doc}`reference`
- {doc}`/guides/reference`
- {doc}`Custom title </guides/reference>`

因此，一旦文档编写或修复完成，如果安装顺利，则使用 sphinx-autobuild 使用以下命令持续部署网页

sphinx-autobuild docs/_source docs/_build/html

这将创建一个 _build/html 文件夹，该文件夹在 http://127.0.0.1:8000 上提供。此外，它还会开始监视 docs/source 目录中的更改。当检测到 docs/source 中的更改时，文档将被重建，并且任何打开的浏览器窗口都将自动重新加载。确保所有文件都已正确索引。KeyboardInterrupt (ctrl+c) 将停止服务器。以下是服务器输出运行和停止的示例

The HTML pages are in docs\_build\html.
[I 231024 10:58:36 server:335] Serving on http://127.0.0.1:8000
[I 231024 10:58:36 handlers:62] Start watching changes
[I 231024 10:58:36 handlers:64] Start detecting changes
[I 231024 11:00:53 server:358] Shutting down...

故障排除 如果你在构建文档时收到警告，则可以按以下方式处理它们

  • 如果它们是 toctree 或标题下划线警告，则可以忽略它们。

  • 如果它们是导入错误，则可以通过从 docs/_source/requirements.txt 重新安装 autodoc 和 argilla 来解决它们

设置开发环境#

要为 Argilla 的核心产品工作和开发，你需要正确运行 Argilla 的所有子系统。在本节中，我们将展示如何安装 Argilla 包、数据库和服务器。前端是可选的，仅在运行 UI 时才需要，但你也可以在此处找到如何运行它。

创建 Python 环境#

克隆 Argilla 仓库#

要为 Argilla 开发设置你的系统，首先，你必须 fork 我们的仓库，并将 fork 克隆到你的计算机。

git clone https://github.com/[your-github-username]/argilla.git
cd argilla

为了使你的 fork 的 main/develop 分支与我们的仓库保持同步，你应该将其添加为 上游远程分支

git remote add upstream https://github.com/argilla-io/argilla.git

安装依赖项#

你将需要安装 argilla 和你喜欢的额外依赖项，以便能够在你的 Python 客户端或命令行界面 (CLI) 中使用 Argilla。有两种安装方法，你可以根据你的用例选择其中一种

  • 使用 pip 安装 argilla：推荐用于非广泛的、一次性贡献，因为它只会安装所需的软件包。

  • 使用 conda 安装 argilla：推荐用于全面的、持续的贡献，因为它将创建一个用于开发的包罗万象的环境。

使用 pip 安装#

如果你选择通过 pip 安装 Argilla，你可以轻松地在你的终端上执行此操作。首先，通过以下方式直接进入终端中的 argilla 文件夹

cd argilla

现在，建议创建一个 Python 虚拟环境，按照以下命令操作

python -m venv .env
source .env/bin/activate

然后，你只需要使用以下命令安装 Argilla。请注意，我们将使用 pip 命令中的 -e/–editable 标志以可编辑模式安装它，以避免每次代码修改都重新安装它，但是如果你不打算修改代码，则可以忽略 -e/–editable 标志。

pip install -e .

或者仅安装 server 额外项

pip install -e ".[server]"

或者你可以安装所有额外项，这些额外项也是通过 pytest 运行测试所必需的，以确保已实现的功能或错误修复程序按预期工作，并且单元/集成测试通过。如果你遇到任何软件包或依赖项问题，请考虑升级或降级相关软件包以解决问题。

pip install -e ".[server,listeners,postgresql,integrations,tests]"
使用 conda 安装#

如果你想使用 conda 安装 Argilla，首先请确保你的系统上安装了最新版本的 conda。你可以访问 anaconda 页面 并按照那里的教程在你的系统上干净地安装 conda。

确保你在 argilla 文件夹中。然后，你可以继续创建一个新的 conda 开发环境，然后激活它

conda env create -f environment_dev.yml
conda activate argilla

在新的 Conda 环境中，Argilla 将已以可编辑模式安装，并包含所有服务器依赖项。但是，如果你愿意安装任何其他依赖项，你可以通过 pip 来安装你自己的依赖项，或者只查看除 server 额外项之外的可用额外项，它们是：listeners、postgresql 和 tests；所有这些都可以安装为 pip install -e ".[<EXTRA_NAME>]"。

现在，Argilla 包已在你的系统上设置，你需要进行进一步的安装以进行全面的开发设置。

安装代码格式化工具#

为了保持一致的代码格式，我们使用 pre-commit hooks。因此，你首先需要安装 pre-commit （如果尚未安装），通过 pip 如下所示

pip install pre-commit

然后，你可以继续进行 pre-commit hooks 安装，只需运行

pre-commit install

设置数据库#

Argilla 构建于两个数据库之上：向量数据库和关系数据库。向量数据库存储所有记录数据，并且是执行可扩展向量相似性搜索以及基本向量搜索的组件。另一方面，关系数据库存储记录和注释的元数据，以及用户和工作区信息。

向量数据库#

Argilla 支持 ElasticSearch 和 OpenSearch 作为其向量数据库的主要搜索引擎。两者之一是正确运行 Argilla 开发环境所必需的。

要安装 Elasticsearch 或 Opensearch，并在稍后在你的服务器上使用 Argilla，你首先需要在你的系统上安装 Docker。你可以在 Docker 网站上找到 Windows、macOS 和 Linux 的 Docker 安装指南。

要安装 ElasticSearch 或 OpenSearch，你可以参考 设置和安装 指南。

注意

Argilla 支持 ElasticSearch 版本 >=8.5 和 OpenSearch 版本 >=2.4。

注意

对于 OpenSearch 中的向量搜索，应用的过滤器使用 post_filter 步骤，因为存在一个错误，该错误导致使用 Argilla 的过滤 + knn 的查询失败。请参阅 https://github.com/opensearch-project/k-NN/issues/1286

当将过滤与此引擎的向量搜索结合使用时，这可能会导致意外的结果。

关系数据库和迁移#

Argilla 将使用 SQLite 作为默认的内置选项来存储有关用户、工作区等关系数据库的信息。启动并使用 SQLite 不需要额外的配置。

默认情况下，数据库文件将在 ~/.argilla/argilla.db 创建，这可以通过为 ARGILLA_DATABASE_URL 和 ARGILLA_HOME_PATH 环境变量设置不同的值来配置。

运行数据库迁移#

从 Argilla 1.16.0 开始，FeedbackDataset 的数据以及用户和工作区信息都存储在 SQL 数据库（SQLite 或 PostgreSQL）中。对于每个 Argilla 版本，你可能需要将数据库模式更新到较新版本。在这里，你可以找到如何执行此数据库迁移。

你可以通过执行以下命令来运行数据库迁移

argilla server database migrate

默认的 SQLite 数据库将在 ~/.argilla/argilla.db 创建。这可以通过为 ARGILLA_DATABASE_URL 和 ARGILLA_HOME_PATH 环境变量设置不同的值来更改。

创建默认用户#

要在你的系统上运行 Argilla 数据库和服务器，你至少应该创建默认用户。或者，你可以跳过默认用户，直接创建你将设置其凭据的用户。你可以参考 用户管理 页面获取详细信息。

要创建默认用户，你可以运行以下命令

argilla server database users create_default
重新创建数据库#

有时，可能需要从头开始重新创建数据库，以确保你的开发环境处于干净状态。例如，运行 Argilla 测试套件或解决可能与数据库不一致相关的问题。

首先，你需要使用以下命令删除 Argilla 数据库

rm ~/.argilla/argilla.db

删除数据库后，你需要运行 数据库迁移 任务。通过执行这些步骤，你将拥有一个全新的干净数据库可以使用。

设置 Argilla 服务器#

如果你想在 Argilla 的服务器上工作，请访问 argilla-server README.md 文件，以了解如何设置服务器并在本地计算机上运行它。

设置 Argilla 前端#

如果你想在 Argilla 的前端工作，请访问 argilla-frontend README.md 文件，以了解如何设置前端并在本地计算机上运行它。

做出你的贡献#

现在一切都已启动并运行，你可以开始开发并为 Argilla 做出贡献了！你可以参考我们的 贡献者指南，以了解如何组织你的贡献并将其上传到仓库。

运行测试#

运行 Argilla Python SDK 的测试#

在每个开发周期结束时运行测试对于确保没有重大更改至关重要。在你的 Argilla 环境中，你可以按如下所示运行所有测试（在 argilla 项目文件夹下）

pytest tests

你还可以通过提供正确的路径来仅运行单元测试

pytest tests/unit

为了运行更重的集成测试，你可以使用 tests/integration 文件夹运行 pytest

pytest tests/integration

运行 Argilla 服务器的测试#

要运行 Argilla 服务器的测试，你可以使用以下命令（在 argilla 项目文件夹下）

pdm test test/unit

你还可以设置 PostgreSQL 数据库而不是默认的 sqlite 后端

ARGILLA_DATABASE_URL=postgresql://postgres:postgres@localhost:5432 pdm test tests/unit

运行 Argilla 前端的测试#

要运行 Argilla 前端的测试，你可以使用以下命令（在 argilla 项目文件夹下）

npm run test