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

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 ServerArgilla 的核心后端基于 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结构所有组件都集中在同一个仓库中主要分为以下目录argillaPython SDK 工程对应 Python 包的源码与测试argilla-serverFastAPI Server 工程后端 API、数据库模型、搜索引擎集成等argilla-frontendVue.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 --devpdm 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、pydantic2.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清理保留输出计数与输出内容。此外还可以直接运行以下脚本检查代码格式与 lintpdm 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/unitpdm 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 的两类数据库向量数据库搜索后端与关系数据库元数据存储。向量数据库ElasticSearchArgilla 默认以 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.typesingle-node \ -e xpack.security.enabledfalse \ docker.elastic.co/elasticsearch/elasticsearch:8.5.3该命令会以单节点模式运行 ElasticSearch 8.5.3映射 9200HTTP与 9300节点间通信端口关闭 xpack 安全校验以简化本地开发并分配 512MB 的 JVM 堆内存。如果你的机器尚未安装 Docker可以参考 Docker 官方文档按 Windows、macOS、Linux 平台完成安装后再执行上述命令。如果希望改用 OpenSearch可以参考服务端配置文档。需要特别注意的是自 Argilla 1.19.0 起必须显式设置ARGILLA_SEARCH_ENGINEopensearch或ARGILLA_SEARCH_ENGINEelasticsearch默认值为elasticsearch且 Elasticsearch 最低版本要求为 8.5.0、OpenSearch 最低版本要求为 2.4.0请在启动前确认后端版本。关系数据库SQLite 与 PostgreSQLArgilla 默认使用SQLite作为内置关系数据库用于存储用户、工作区、数据集等信息无需额外配置即可使用。默认情况下数据库文件会创建在~/.argilla/argilla.db你可以通过设置ARGILLA_DATABASE_URL与ARGILLA_HOME_PATH环境变量来修改这一位置。从服务端配置文档可以看到ARGILLA_DATABASE_URL的默认值为sqlite:///$ARGILLA_HOME_PATH/argilla.db?check_same_threadFalse这意味着数据库文件的存放路径由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 --reloadServer 启动后可访问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 servemkdocs 的站点配置位于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 本地开发工作流可以概括为准备仓库fork 并 clone 仓库从develop分支切出特性分支配置 SDK 环境进入argilla目录pip install pdm pdm install --dev并pre-commit install启动依赖服务用 Docker 启动 ElasticSearch 8.5.3或配置 OpenSearchSQLite 开箱即用启动后端在argilla-server目录执行pdm server-dev自动完成迁移、建默认用户并起服务可选启动前端在argilla-frontend目录执行npm i npm run dev开发与验证编码后用pdm run format、pdm run lint、pdm run tests或一条pdm run all完成全量检查再提交 PR文档改动若是文档类贡献在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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考