5.1 · 开发设置（Development Setup）

开发设置

开发环境搭建

相关源文件

本 Wiki 页面基于以下文件生成：

• .dockerignore
• .gitignore
• .pre-commit-config.yaml
• argilla-frontend/dev.frontend.Dockerfile
• argilla-frontend/package-lock.json
• docs/_source/_common/tabs/argilla_install_python.md
• docs/_source/community/contributing.md
• docs/_source/community/developer_docs.md
• docs/_source/community/migration-rubrix.md
• docs/_source/getting_started/installation/deployments/docker.md
• docs/_source/getting_started/installation/deployments/docker_compose.md
• docs/_source/getting_started/installation/deployments/python.md
• docs/_source/reference/cli.md
• docs/_source/reference/notebooks.rst
• docs/migration-rubrix.md
• docs/template.ipynb

本文档提供了为参与 Argilla 项目贡献而搭建开发环境的详细说明。内容涵盖在本地运行代码库所需的必要步骤，包括环境搭建、依赖安装以及所需服务的配置。

有关开发环境搭建完成后的贡献工作流流程，请参见贡献工作流。

Argilla 架构总览

在深入开发环境搭建之前，了解 Argilla 架构中你将打交道的核心组件会很有帮助。

来源：docs/_source/community/developer_docs.md:9-31

前置条件

在搭建开发环境之前，请确保已安装以下软件：

来源：docs/_source/community/developer_docs.md:158-164，docs/_source/community/developer_docs.md:276-277

克隆仓库

首先，Fork Argilla 仓库并将你的 Fork 克隆到本地机器：

git clone https://github.com/[你的 GitHub 用户名]/argilla.git
cd argilla

为了保持你的 Fork 的 main/develop 分支与原始仓库同步，将其添加为上游远程仓库：

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

来源：docs/_source/community/developer_docs.md:162-171，docs/_source/community/contributing.md:83-85

搭建 Python 环境

Argilla 提供了两种搭建 Python 环境的选项：

选项一：使用 pip

1. 创建并激活虚拟环境：

python -m venv .env
source .env/bin/activate  # Windows 系统：.env\Scripts\activate

1. 以可编辑模式安装 Argilla 并附带所需附加组件：

# 基础开发
pip install -e .

# 服务器开发
pip install -e ".[server]"

# 完整开发环境搭建
pip install -e ".[server,listeners,postgresql,integrations,tests]"

来源：docs/_source/community/developer_docs.md:193-224

选项二：使用 conda

1. 创建并激活 conda 环境：

conda env create -f environment_dev.yml
conda activate argilla

这会以可编辑模式安装 Argilla 并附带所有服务器依赖。

来源：docs/_source/community/developer_docs.md:232-243

安装 Pre-commit 钩子

为了维护代码质量和一致性，请安装 pre-commit 钩子：

pip install pre-commit
pre-commit install

当你提交变更时，pre-commit 钩子会自动根据项目标准检查和格式化你的代码。

来源：docs/_source/community/developer_docs.md:249-261，.pre-commit-config.yaml:1-95

搭建数据库

Argilla 需要三个数据库才能正常运行：

向量数据库（Elasticsearch/OpenSearch）

该数据库存储记录数据并执行向量相似性搜索。

docker network create argilla-net

docker run -d --name elasticsearch-for-argilla \
  --network argilla-net \
  -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

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

来源：docs/_source/community/developer_docs.md:269-291，docs/_source/getting_started/installation/deployments/docker.md:8-19

关系数据库（SQLite/PostgreSQL）

Argilla 默认使用内置的 SQLite 来存储用户、工作空间等信息。无需额外配置即可开始使用 SQLite。

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

运行数据库迁移

初始化数据库模式：

argilla server database migrate

创建默认用户

创建一个用于认证的默认用户：

argilla server database users create_default

来源：docs/_source/community/developer_docs.md:293-342

Redis

Redis 用于后台任务。你可以使用 Docker 运行它：

docker run -d --name redis-for-argilla \
  --network argilla-net \
  -p 6379:6379 \
  redis:alpine

来源：docs/_source/community/developer_docs.md:23

运行 Argilla 组件

在开发环境和所需服务搭建完成后，你可以运行 Argilla 的不同组件。

运行 Argilla 服务器

运行 Argilla 服务器：

argilla server start

这会在 http://localhost:6900 上启动服务器。

有关服务器配置的更多详情，请参考 argilla-server 的 README.md 文件。

来源：docs/_source/community/developer_docs.md:345-347，docs/_source/reference/cli.md:173-186

运行前端

有关前端开发，请参考 argilla-frontend 的 README.md 文件。

来源：docs/_source/community/developer_docs.md:349-351，argilla-frontend/dev.frontend.Dockerfile:14-26

运行测试

测试是开发过程中不可或缺的一部分。Argilla 为每个组件提供了不同的测试套件。

运行 Python SDK 测试

运行所有测试：

pytest tests

仅运行单元测试：

pytest tests/unit

运行集成测试：

pytest tests/integration

来源：docs/_source/community/developer_docs.md:363-380

运行 Argilla 服务器测试

运行服务器测试：

pdm test test/unit

使用 PostgreSQL：

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

来源：docs/_source/community/developer_docs.md:382-393

运行前端测试

运行前端测试：

npm run test

来源：docs/_source/community/developer_docs.md:395-401

常见开发任务

重建数据库

如果你需要将数据库重置为干净状态：

# 删除数据库
rm ~/.argilla/argilla.db

# 运行迁移
argilla server database migrate

# 创建默认用户
argilla server database users create_default

来源：docs/_source/community/developer_docs.md:328-342

包附加组件

在开发 Argilla 时，你可能需要根据具体工作内容安装不同的附加组件：

示例：

pip install -e ".[server,postgresql]"

来源：docs/_source/getting_started/installation/deployments/python.md:10-18，docs/_source/_common/tabs/argilla_install_python.md:1-26

Docker 开发

对于基于 Docker 的开发，你可以使用提供的 Docker Compose 文件：

wget -O docker-compose.yaml https://raw.githubusercontent.com/argilla-io/argilla/develop/docker-compose.yaml
docker-compose up -d

这会启动 Elasticsearch 和 Argilla 服务器。

来源：docs/_source/getting_started/installation/deployments/docker_compose.md:7-32

贡献的后续步骤

开发环境搭建完成后，你就可以开始为 Argilla 做贡献了。有关贡献工作流的详情，包括创建分支、进行变更和提交拉取请求，请参见贡献工作流。

有关 Argilla 中使用的持续集成/持续部署（CI/CD）管线的更多信息，请参见持续集成/持续部署（CI/CD）管线。

来源：docs/_source/community/developer_docs.md:353-362，docs/_source/community/contributing.md:32-211