跳到内容

开发者文档

作为 Argilla 开发者，您已经是社区的一份子，您的贡献对我们的发展至关重要。本指南将帮助您设置开发环境并开始贡献。

Argilla 核心组件

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

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

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

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

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

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

Argilla 仓库

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

如何贡献？

在开始开发之前，我们建议阅读我们的贡献指南，以了解贡献流程和要遵循的准则。一旦您克隆了 Argilla 仓库并检出到正确的 branch，您就可以开始设置您的开发环境。

设置 Python 环境

要处理 Argilla Python SDK，您必须在系统上安装 Argilla 包。

创建虚拟环境

我们建议为 SDK 开发创建一个专用的虚拟环境，以防止冲突。为此，您可以使用您选择的管理器，例如 venv、conda、pyenv 或 uv。

从克隆的 Argilla 仓库的根目录，您应该在终端中移动到 argilla 文件夹。

cd argilla

接下来，激活您的虚拟环境并进行所需的安装

# Install the `pdm` package manager
pip install pdm

# Install argilla in editable mode and the development dependencies
pdm install --dev

代码检查和格式化

为了保持一致的代码格式，请安装 pre-commit hooks 以在每次提交之前自动运行。

pre-commit install

此外，运行以下脚本以检查代码格式和代码检查

pdm run format
pdm run lint

运行测试

在每个开发周期结束时运行测试是必不可少的，以确保没有破坏性更改。

# Run all tests
pdm run tests

# Run specific tests
pytest tests/integration
pytest tests/unit
运行代码检查、格式化和测试

您可以使用以下命令一次运行所有检查

    pdm run all

设置数据库

要运行您的开发环境，您需要设置 Argilla 的数据库。

向量数据库

Argilla 默认支持 ElasticSearch 作为其向量数据库的主要搜索引擎。有关设置 OpenSearch 的更多信息，请查看服务器配置。

您可以使用 Docker 在本地运行 ElasticSearch

# Argilla supports ElasticSearch versions >=8.5
docker run -d --name elasticsearch-for-argilla -p 9200:9200 -p 9300:9300 -e "ES_JAVA_OPTS=-Xms512m -Xmx512m" -e "discovery.type=single-node" -e "xpack.security.enabled=false" docker.elastic.co/elasticsearch/elasticsearch:8.5.3

安装 Docker

您可以在 Docker 网站上找到 Windows、macOS 和 Linux 的 Docker 安装指南。

关系数据库

Argilla 将使用 SQLite 作为默认的内置选项来存储有关用户、工作区等的关系数据库信息。无需额外配置即可开始使用 SQLite。

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

管理数据库

有关数据库迁移和用户管理的更多信息，请参阅 Argilla 服务器 README。

设置服务器

设置数据库后，您可以启动 Argilla 服务器。要运行服务器，您可以查看 Argilla 服务器 README 文件。

设置前端

可选地，如果您需要运行 Argilla 前端，您可以按照 Argilla 前端 README 中的说明进行操作。

设置文档

文档对于为用户提供有关 Argilla 的全面指南至关重要。

从 main 或 develop 分支？

如果您正在更新、改进或修复当前文档而无需更改代码，请在 main 分支上工作。对于需要文档的新功能或错误修复，请使用 develop 分支。

要为文档做出贡献并在本地生成文档，请确保您已安装“设置 Python 环境”部分中所示的开发依赖项，并运行以下命令以使用 mkdocs 创建开发服务器

mkdocs serve

文档指南

如前所述，我们使用 mkdocs 来构建文档。您可以使用 markdown 格式编写文档，它将自动转换为 HTML。此外，您可以包含表格、选项卡、图像等元素，如本指南所示。我们建议遵循以下指南

  • 使用清晰简洁的语言：通过使用直截了当的语言并包含有意义的示例，确保所有用户都能轻松理解文档。图像不易维护，因此仅在必要时使用图像，并将它们放置在 docs/assets/images 目录中的相应文件夹中。
  • 验证代码片段：仔细检查所有代码片段是否正确且可运行。
  • 检查拼写和语法：检查文档的拼写和语法。
  • 更新目录：如果您添加新页面，请将其包含在相关的 index.md 或 mkdocs.yml 文件中。

贡献教程

您还可以为“社区”部分贡献教程 (.ipynb)。我们建议使教程与现有教程的结构保持一致。例如，请查看本教程。