企业官网建设流程全解析

Argilla 开发者指南：搭建 Python SDK、FastAPI Server 与前端的一体化开发环境

【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argilla

本指南面向希望参与 Argilla 开发的贡献者，系统讲解如何基于 monorepo 仓库搭建完整的本地开发环境：从安装 Python SDK 与开发依赖、接入代码格式化与静态检查工具、运行单元与集成测试，到启动 ElasticSearch/SQLite 数据库、FastAPI 后端服务、Vue.js 前端以及 mkdocs 文档站点。读完本文，你将能够在本地一键运行 Argilla 全栈开发链路，并按照项目规范提交高质量代码。

认识 Argilla 的核心组件

在动手配置环境之前，先建立对 Argilla 架构的整体认知。Argilla 是一个面向 AI 工程师与领域专家、用于构建高质量数据集（如文本/图像标注、偏好数据）的协作工具，其技术栈由以下几个核心组件构成：

• Documentation（文档）：官方文档是探索、理解并有效使用 Argilla 生态各核心组件的综合指南，同时承担着社区贡献的载体角色。
• Python SDK：可通过pip install argilla安装的 Python 客户端，用于与 Argilla Server 和 Argilla UI 交互，提供管理数据、配置与标注工作流的 API。
• FastAPI Server：Argilla 的核心后端，基于 Python FastAPI 实现。它负责数据的预处理与存储（写入向量数据库），同时在关系数据库中保存应用信息，通过 REST API 向 Python SDK 与 UI 提供数据访问能力，并附带用于可视化数据的 Web 界面。
• Relational Database（关系数据库）：用于存储记录元数据与标注信息。默认内置 SQLite，可与 Argilla Server 一起部署；也可以使用独立的 PostgreSQL。
• Vector Database（向量数据库）：用于存储记录数据并执行可扩展的向量相似性搜索与基础文档搜索。目前支持 ElasticSearch 与 OpenSearch，二者均可作为独立 Docker 镜像部署。
• Vue.js UI：用于可视化并标注数据、管理用户与团队的前端 Web 应用，与 Argilla Server 一同打包进 Argilla Docker 镜像中直接部署。

理解 monorepo 仓库结构

Argilla 采用monorepo结构，所有组件都集中在同一个仓库中，主要分为以下目录：

• argilla：Python SDK 工程（对应 Python 包的源码与测试）；
• argilla-server：FastAPI Server 工程（后端 API、数据库模型、搜索引擎集成等）；
• argilla-frontend：Vue.js UI 工程（Nuxt 2 + TypeScript 前端）；
• argilla/docs：文档工程（mkdocs 站点源文件）；
• examples：部署方案（Docker、Kubernetes/Helm、Nginx、Traefik）、脚本与 notebook 等示例资源。

以 SDK 为例，其源码位于argilla/src/argilla，按_api、_models、_helpers、datasets、records、settings、users、webhooks、workspaces等模块组织，客户端入口在argilla/src/argilla/client.py。测试则分为tests/integration（对接真实服务端的端到端测试）与tests/unit（本地单元测试）。

开始之前：先阅读贡献指南

在搭建开发环境之前，建议先阅读贡献指南，了解贡献流程与必须遵循的规范，包括：

• 如何 fork Argilla 仓库 并配置upstream远程仓库；
• 如何 创建新分支：切勿直接在main或develop分支上开发，且应牢记main分支仅用于文档工作，其他改动一律基于develop分支；
• 如何规范填写CHANGELOG.md条目与提交 Pull Request。

完成 fork 与分支切换后，即可按照下文开始配置本地开发环境。

搭建 Python 开发环境

要对 Argilla Python SDK 进行开发，首先需要在本机安装 Argilla 包。强烈建议为 SDK 开发创建独立的虚拟环境，以避免依赖冲突，可以使用venv、conda、pyenv或uv等任意你习惯的环境管理器。

从克隆后的 Argilla 仓库根目录进入argilla文件夹：

cd argilla

接着激活虚拟环境并安装依赖。项目使用PDM作为包管理器与任务编排工具：

# 安装 pdm 包管理器 pip install pdm # 以可编辑模式安装 argilla，并安装开发依赖 pdm install --dev

pdm install --dev会依据argilla/pyproject.toml中[tool.pdm.dev-dependencies]声明的开发依赖进行安装，其中包括pytest、pytest-mock、pytest-httpx、ruff、black、flake8、pre-commit，以及文档构建所需的mkdocs-material、mkdocstrings、mkdocs-literate-nav、mknotebooks、mike等工具。从依赖清单可以看出，SDK 运行环境要求 Python>= 3.9，其核心运行时依赖为httpx、pydantic>=2.6、huggingface_hub、tqdm、rich、datasets与pillow等。

代码格式化与静态检查

为了保持代码风格一致，需要安装pre-commit钩子，使其在每次提交前自动执行检查：

pre-commit install

仓库根目录的.pre-commit-config.yaml定义了这些钩子的具体行为：包括 YAML/行尾/空白检查（pre-commit-hooks）、Python 代码的ruff-format与ruff --fix（针对argilla/src与argilla-server/src下的 Python 文件）、Python 源码的 License 头自动插入（基于LICENSE_HEADER文件），以及 notebook 的nbstripout清理（保留输出计数与输出内容）。

此外，还可以直接运行以下脚本检查代码格式与 lint：

pdm run format pdm run lint

这两个命令由argilla/pyproject.toml中[tool.pdm.scripts]定义：format执行black .，lint执行ruff check，二者均遵循line-length = 120的配置。

运行测试

每个开发周期结束时运行测试必不可少，这是确保没有引入破坏性变更的关键手段：

# 运行全部测试 pdm run tests # 运行指定测试 pytest tests/integration pytest tests/unit

pdm run tests实际执行的是pytest tests，并通过env_file = ".env.test"注入测试环境变量。其中tests/integration下的用例（如test_create_datasets.py、test_query_records.py、test_export_records.py等）会走完整的 SDK 调用链路，验证与真实 Argilla Server 的交互。

如果希望一次性执行格式检查、lint 与全部测试，可以运行组合命令：

pdm run all

它等价于顺序执行format、lint、test三个脚本（见[tool.pdm.scripts]中all = { composite = ["format", "lint", "test"] }的定义）。

配置数据库

运行开发环境还需要配置 Argilla 的两类数据库：向量数据库（搜索后端）与关系数据库（元数据存储）。

向量数据库：ElasticSearch

Argilla 默认以 ElasticSearch 作为搜索后端，支持ElasticSearch >= 8.5的版本。可以使用 Docker 在本地启动一个单节点实例：

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

该命令会以单节点模式运行 ElasticSearch 8.5.3，映射 9200（HTTP）与 9300（节点间通信）端口，关闭 xpack 安全校验以简化本地开发，并分配 512MB 的 JVM 堆内存。如果你的机器尚未安装 Docker，可以参考 Docker 官方文档按 Windows、macOS、Linux 平台完成安装后再执行上述命令。

如果希望改用 OpenSearch，可以参考服务端配置文档。需要特别注意的是，自 Argilla 1.19.0 起必须显式设置ARGILLA_SEARCH_ENGINE=opensearch或ARGILLA_SEARCH_ENGINE=elasticsearch（默认值为elasticsearch），且 Elasticsearch 最低版本要求为 8.5.0、OpenSearch 最低版本要求为 2.4.0，请在启动前确认后端版本。

关系数据库：SQLite 与 PostgreSQL

Argilla 默认使用SQLite作为内置关系数据库，用于存储用户、工作区、数据集等信息，无需额外配置即可使用。默认情况下，数据库文件会创建在~/.argilla/argilla.db，你可以通过设置ARGILLA_DATABASE_URL与ARGILLA_HOME_PATH环境变量来修改这一位置。

从服务端配置文档可以看到，ARGILLA_DATABASE_URL的默认值为sqlite:///$ARGILLA_HOME_PATH/argilla.db?check_same_thread=False，这意味着数据库文件的存放路径由ARGILLA_HOME_PATH（默认~/.argilla）决定。同时，若使用 SQLite，还可配置ARGILLA_DATABASE_SQLITE_TIMEOUT（默认 15 秒，控制表被锁定时抛出OperationalError前的等待时间）；若使用 PostgreSQL，则可配置连接池参数ARGILLA_DATABASE_POSTGRESQL_POOL_SIZE（默认 15）与ARGILLA_DATABASE_POSTGRESQL_MAX_OVERFLOW（默认 10）。

关于数据库迁移（Alembic）与用户管理的更多细节，可以参考 Argilla Server 的 README，其中介绍了python -m argilla_server database migrate、python -m argilla_server database revisions、python -m argilla_server database users create_default等命令行操作。

启动 Argilla Server

数据库就绪后即可启动 Argilla Server。最快的路径是使用 Argilla Server README 中提供的开发命令：

pdm server-dev

该命令会串联执行数据库迁移、创建默认用户并启动开发服务器。查看argilla-server/pyproject.toml中[tool.pdm.scripts]的定义可以确认其内部行为：

server = { cmd = "uvicorn argilla_server:app --port 6900 --reload" } migrate = { cmd = "alembic upgrade head" } worker = { cmd = "python -m argilla_server worker" } server-dev.composite = [ "migrate", "cli database users create_default", "server", ]

也就是说，pdm server-dev等价于依次执行「数据库迁移 → 创建默认用户 → 以热重载方式在 6900 端口启动 uvicorn 服务」。

你也可以在argilla-server目录下分别执行各步骤，或直接以模块方式启动：

# 应用数据库迁移 python -m argilla_server database migrate # 创建默认用户 python -m argilla_server database users create_default # 启动 uvicorn FastAPI 服务 pdm server # 等价于 uvicorn argilla_server:app --port 6900 --reload

Server 启动后可访问http://localhost:6900查看 Web 界面，FastAPI 自动生成的 REST API 文档位于http://localhost:6900/api/v1/docs。

启动前端（可选）

如果你需要在前端工程上做开发，可以按 Argilla Frontend README 的说明操作。前端基于 Nuxt 2 + Vue 2 + TypeScript 构建（见argilla-frontend/package.json），安装依赖并启动本地开发服务器：

npm i npm run dev

如需构建静态产物，可以执行：

npm run generate

前端工程还内置了 ESLint 与 Jest 测试（npm run lint、npm test），以及基于 Playwright 的端到端测试（npm run e2e，测试规格文件位于argilla-frontend/e2e），在改动 UI 后建议一并验证。

搭建文档开发环境

文档是用户全面了解 Argilla 的重要资源，也是贡献者最容易入手的切入点。

选择正确的分支

• 如果你是在不涉及代码改动的前提下更新、改进或修复现有文档，请在main分支上工作；
• 如果是为新功能或 bug 修复编写配套文档，请使用develop分支。

本地预览文档

在完成"搭建 Python 开发环境"一节中的开发依赖安装后（开发依赖中已包含mkdocs-material与相关插件），在argilla目录下运行以下命令启动 mkdocs 开发服务器：

mkdocs serve

mkdocs 的站点配置位于argilla/mkdocs.yml：文档采用 Material 主题，启用了即时导航、代码复制、搜索建议与高亮等特性；通过mkdocstrings从 Python 源码自动生成 API 参考页；gen-files插件在 CI 环境下自动生成 changelog 与热门 issue 页面；导航结构由nav配置定义，社区文档（包括本文所在的developer.md）均在其中注册。需要说明的是，mkdocs 的watch配置会监听src/argilla目录，因此修改 SDK 源码时文档站会自动热更新。

文档编写规范

项目使用 mkdocs 将 Markdown 文档自动转换为 HTML，支持表格、Tab 切换、图片等元素。撰写文档时请遵循以下准则：

• 使用清晰简洁的语言：确保文档对各类用户都易于理解，提供有意义的示例。图片不易维护，仅在必要时使用，并放在docs/assets/images目录下对应的文件夹中；
• 验证代码片段：反复确认所有代码片段正确且可运行；
• 检查拼写与语法：提交前仔细校对文档的拼写和语法；
• 更新目录结构：如果新增了页面，记得将其加入相应的index.md或mkdocs.yml文件中。

贡献教程

你也可以向 "Community" 板块贡献 notebook 教程（.ipynb），建议尽量与现有教程的结构保持一致。可以参考文本分类教程作为示例模板——仓库中现有的教程还覆盖了 token 分类、图像分类、图像偏好等主题。

小结：完整的本地开发工作流

综合以上各节，一个完整的 Argilla 本地开发工作流可以概括为：

1. 准备仓库：fork 并 clone 仓库，从develop分支切出特性分支；
2. 配置 SDK 环境：进入argilla目录，pip install pdm && pdm install --dev，并pre-commit install；
3. 启动依赖服务：用 Docker 启动 ElasticSearch 8.5.3（或配置 OpenSearch），SQLite 开箱即用；
4. 启动后端：在argilla-server目录执行pdm server-dev（自动完成迁移、建默认用户并起服务）；
5. 可选启动前端：在argilla-frontend目录执行npm i && npm run dev；
6. 开发与验证：编码后用pdm run format、pdm run lint、pdm run tests（或一条pdm run all）完成全量检查，再提交 PR；
7. 文档改动：若是文档类贡献，在main分支上编辑，并用mkdocs serve本地预览后再提交。

按此流程即可在本地完整复现 Argilla 的 SDK、Server、前端与文档四套工程，为高质量贡献打好基础。

【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argilla