Argilla Server 版本演进与核心能力全景解析从 v1.5 到 v2.7 的 API、配置、后台任务与 Webhooks 实战指南【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argillaArgilla Server 是 Argilla 项目面向 AI 工程师与领域专家的高质量数据集协作工具的服务端核心。本文以 argilla-server/CHANGELOG.md 为骨架结合 settings.py、routes.py 等源码系统梳理 Argilla Server 从 v1.5 到 v2.7 的版本演进脉络涵盖 API v1 端点体系、环境变量配置、数据集与字段类型、后台任务队列、Webhooks 事件模型以及破坏性变更与升级迁移要点。读完本文你将能快速判断历史版本间的功能差异掌握当前版本的核心配置项与运维关键动作并能在升级前准确评估 reindex、端点替换等迁移成本。一、版本脉络总览从 SDK 内嵌到独立服务Argilla Server 的版本历史可以划分为三个明显阶段v1.5 ~ v1.23SDK 内嵌阶段服务端作为 Argilla SDK 的一部分发布功能围绕 FeedbackDataset、标注工作流与 CLI 命令展开v1.24服务端独立里程碑CHANGELOG 明确记载这是 Argilla Server 的首个独立发布服务端从此可作为独立包安装使用与 SDK 解耦v1.25 ~ v2.7API v1 完善阶段API v1 全面接管引入向量检索、元数据属性、Webhooks、后台任务RQ Redis、Hugging Face Hub 导入导出等能力并在 v2.0 完成对旧 API 的清理。当前仓库中服务端代码位于 argilla-server/src/argilla_server其入口应用通过 routes.py 将 16 个 v1 路由模块挂载到/api前缀下包括 datasets、fields、questions、metadata_properties、records、responses、suggestions、users、vectors_settings、workspaces、webhooks、jobs、oauth2、settings、authentication 与 info。关键版本时间线如下版本核心主题代表性能力1.6.0用户与权限基础引入 admin/annotator 角色、用户与工作区管理端点、ARGILLA_DATABASE_URL1.8.0API v1 诞生/api/v1/datasets系列端点、FeedbackDataset 客户端支持1.11.0三角色权限体系owner/admin/annotator 三级角色1.18.0元数据体系metadata-properties 端点、Term/Integer/Float 元数据属性1.19.0向量检索vectors-settings 端点、相似记录搜索余弦相似度1.24.0服务独立Argilla Server 独立发布修复ARGILLA_BASE_URL2.0.0破坏性升级移除全部 API v0 端点、新增 records.status 列、需要 reindex2.2.0后台任务引入 rq Redis、chat 类型字段2.3.0自定义字段CustomField、Helm chart2.5.0事件驱动Webhooks 全套端点与事件、Python 3.13、Pydantic v22.6.0Hub 导入导出后台任务化的 HF Hub export/import 端点2.7.0预定义 ID支持按预定义 id 创建用户与工作区二、API v1 端点体系从 v1.8 奠基到 v2.x 完善2.1 资源端点全家桶v1.8.0 建立v1.8.0 一次性引入了 API v1 的完整资源骨架此后几乎所有端点都在此基础上扩展数据集GET/POST /api/v1/datasets、GET/DELETE /api/v1/datasets/{dataset_id}、POST .../publish字段与问题GET/POST /api/v1/datasets/{dataset_id}/fields、.../questions以及对应的单资源删除端点记录GET/POST /api/v1/datasets/{dataset_id}/records、GET /api/v1/me/datasets当前用户可见数据集、POST /api/v1/me/records/{record_id}/responses工作区与用户GET /api/v1/workspaces/{workspace_id}、GET/POST /api/v1/workspaces/{workspace_id}/users服务信息GET /api/v1/version、GET /api/v1/status。从当前源码 records.py 可以看到记录列表端点GET /api/v1/datasets/{dataset_id}/records的完整签名支持include参数可携带 responses、suggestions、vectors、offset/limit分页其中limit被约束在ge1, le1000与 v1.19.0 CHANGELOG 中limit 只接受 1~1000的破坏性变更一致并返回Records(items, total)结构。2.2 记录写入从单条到 bulk再到字段级更新v1.28.0新增POST/PUT /api/v1/datasets/:dataset_id/records/bulk批量端点同时将旧的单条POST/PATCH .../records标记为弃用v2.0.0正式移除弃用的POST /api/v1/datasets/:dataset_id/records与PATCH /api/v1/datasets/:dataset_id/records批量写入成为唯一途径v2.6.0允许在PATCH /api/v1/records/:record_id与PUT /api/v1/datasets/:dataset_id/records/bulk中更新记录字段fields。2.3 搜索体系DSL、过滤、排序与向量v1.20.0起搜索端点支持可选的query属性以及filter、sort结构记录搜索从简单关键词演进为结构化 DSLv2.1.0引入advanced dsl for text searches高级文本搜索 DSL对应源码中 records.py 的POST /datasets/{dataset_id}/records/search与POST /me/datasets/{dataset_id}/records/search两个搜索端点后者按当前用户上下文过滤响应搜索端点同时支持GET .../records/search/suggestions/options返回可检索的 suggestion 选项按问题聚合 agent 列表见 records.py向量检索v1.19.0新增 vectors-settings 的增删改查端点记录支持携带vectors检索时使用余弦相似度计算向量距离并可用include参数按需返回向量。2.4 数据集进度与指标进度类端点经历了两次演进v1.27.0 新增GET /api/v1/datasets/:dataset_id/progress返回单数据集进度指标v2.1.0 新增GET /api/v1/datasets/:dataset_id/users/progress计算各用户进度v2.0.0 将其改造为支持新的数据集分布任务distribution task并在 v2.5.0 的响应中增加users属性源码见 datasets.py。2.5 从 Hub 导入导出异步后台任务v2.4.0 / v2.6.0两个端点将耗时操作从同步请求中剥离全部走后台任务POST /api/v1/datasets/{dataset_id}/importv2.4.0从 Hugging Face 数据集导入请求体包含name、subset、split与字段mappingPOST /api/v1/datasets/{dataset_id}/exportv2.6.0将数据集导出到 Hugging Face Hub额外支持private与token参数并在导出前校验数据集非空。两者均返回202 Accepted与JobSchema{id, status}实际工作由 hub_jobs.py 中的import_dataset_from_hub_job/export_dataset_to_hub_job异步执行并配置了timeoutJOB_TIMEOUT_DISABLED即 -1不设超时与最大 3 次重试见 datasets.py。三、配置体系ARGILLA_前缀环境变量全解析v1.13.0 起 Argilla 移除了所有无前缀环境变量所有合法环境变量均以ARGILLA_开头。这一约束在当前 settings.py 中通过Config.env_prefix ARGILLA_固化。以下按类别展开 CHANGELOG 中出现的核心配置项。3.1 数据库连接与连接池环境变量版本引入默认值说明ARGILLA_DATABASE_URL1.6.0~/.argilla/argilla.dbSQLite数据存储 URL。源码会自动将sqlite协议升级为sqliteaiosqlite、将postgresql升级为postgresqlasyncpg见 settings.pyARGILLA_DATABASE_SQLITE_TIMEOUT2.0.05秒SQLite 事务超时见 constants.pyARGILLA_DATABASE_POSTGRESQL_POOL_SIZE2.0.015连接池中保持打开的连接数ARGILLA_DATABASE_POSTGRESQL_MAX_OVERFLOW2.0.010超出 pool_size 可额外打开的连接数这些参数最终汇入database_engine_args属性SQLite 使用connect_args.timeoutPostgreSQL 使用pool_size与max_overflow见 settings.py。默认常量集中在 constants.py。3.2 Redis 与后台任务v2.2.0引入rqPython RQ库以 Redis 为依赖处理后台任务首个用例是数据集分布策略更新后刷新记录状态的后台任务Unreleased新增ARGILLA_REDIS_USE_CLUSTER用于切换 Redis 集群Cluster与单机Standalone模式。源码 queues.py 据此选择RedisCluster.from_url或redis.from_url队列命名与优先级v2.5.0 引入 high 队列DEFAULT_QUEUE Queue(default, ...)、HIGH_QUEUE Queue(high, ...)见 queues.py。Webhook 事件通知等对时效敏感的任务走 high 队列见 webhook_jobs.py。3.3 搜索与索引环境变量版本引入说明ARGILLA_SEARCH_ENGINE1.19.0取值elasticsearch或opensearch。OpenSearch 用户需2.4并显式设置该变量ARGILLA_ES_MAPPING_TOTAL_FIELDS_LIMIT1.25.0应对大规模标注流程的字段总量上限默认 2000见 settings.pyREINDEX_DATASETS1.25.0quickstart/ 2.0.0server 镜像启动时将数据集与记录重新索引进搜索引擎注意 v1.25.0 与 v2.0.0 均声明索引映射发生变更需要 reindex——这是两个必须规划迁移动作的版本。3.4 认证与安全ARGILLA_AUTH_*v1.23.0 引入新一代认证变量并弃用旧的ARGILLA_LOCAL_AUTH_*后者在 v1.25.0 被移除ARGILLA_AUTH_SECRET_KEYJWT 签名密钥默认随机生成 uuid4见 security/settings.pyARGILLA_AUTH_ALGORITHM默认HS256ARGILLA_AUTH_TOKEN_EXPIRATION会话令牌过期时间默认86400秒1 天ARGILLA_AUTH_OAUTH_CFGOAuth2 YAML 配置文件路径默认.oauth.yaml。上述默认值均可在 security/settings.py 中确认。v1.23.0 同期新增了对 Hugging Face Hub 的 OAuth2 支持。3.5 问题Question选项数量上限ARGILLA_LABEL_SELECTION_OPTIONS_MAX_ITEMSv1.27.0label 与 multi-label 选择题的最大选项数默认500ARGILLA_SPAN_OPTIONS_MAX_ITEMSv1.27.0span 题最大选项数默认500。两者默认值定义在 constants.py并作为字段默认值接入 settings.py。其他问题类约束还包括rating 题取值限定[1, 10]v1.14.0v1.29.0 起允许0、ranking 题最多 50 个选项v1.18.0、visible_options需介于 3 与选项总数之间v1.16.0。3.6 Hugging Face 与遥测ARGILLA_SHOW_HUGGINGFACE_SPACE_PERSISTENT_STORAGE_WARNINGv1.28.0控制是否在 HF Spaces 持久化存储被禁用时展示警告ARGILLA_ENABLE_SHARE_YOUR_PROGRESSv2.6.0启用/禁用share your progress社区进度分享功能默认False见 settings.py并在GET /api/v1/settings中通过argilla.share_your_progress_enabled暴露遥测在 v2.1.0 切换到 HuggingFace 遥测客户端HF_HUB_DISABLE_TELEMETRY1或HF_HUB_OFFLINE1会使其失效见 settings.py。3.7 其他重要配置ARGILLA_HOME_PATHv1.6.0Argilla 相关文件的存放目录默认~/.argillaARGILLA_BASE_URLv1.24.0 修复服务部署的 base url源码会规范化首尾斜杠settings.pyServer-Timing响应头v2.0.0所有响应携带服务端生成响应耗时的毫秒数。四、数据模型演进字段、问题与数据集属性4.1 字段类型text → chat → image → CustomFieldv2.2.0新增chat类型字段支持聊天式对话内容当前 SDK 侧对应 markdown/chat.py 的渲染支持v2.1.0新增image类型字段支持 URL 与 Data URLv2.3.0新增CustomField允许自定义字段渲染逻辑参考 custom_fields.mdv2.0.0为 records 表新增status列支撑记录完成度与分布策略。4.2 问题类型span、rating、ranking、label_selectionv1.26.0新增span问题支持allow_overlapping允许重叠跨度设置v1.27.0v1.12.0新增RankingQuestion与对应的 Ranking 组件v1.9.0引入LabelSelectionQuestionSettings与MultiLabelSelectionQuestionSettings并支持字段/问题的use_markdown属性与响应draft状态v1.28.0为 multi-label 选择问题增加options_order设置以指定选项顺序v1.25.0起支持更新 label/multi-label 选择题的选项。4.3 数据集分布策略Distributionv2.0.0支持在创建与更新数据集时指定distribution属性将记录分配给标注用户的分布任务并将progress、metrics端点改造为适配新任务模型。这一变化对应 CHANGELOG 标记的两处[breaking]变更升级到 2.x 后消费这两个端点的客户端必须同步适配。五、Webhooks 事件体系v2.5.0v2.5.0 为 Argilla Server 引入完整的事件驱动能力管理端点POST /api/v1/webhooks创建、PATCH /api/v1/webhooks/{webhook_id}更新、DELETE /api/v1/webhooks/{webhook_id}删除、GET /api/v1/webhooks列表、POST /api/v1/webhooks/{webhook_id}/ping连通性测试见 webhooks.py事件枚举定义在 enums.py涵盖三类类别事件数据集dataset.created、dataset.updated、dataset.deleted、dataset.published记录record.created、record.updated、record.deleted、record.completed响应response.created、response.updated、response.deleted事件的触发与通知逻辑位于 webhooks/v1 目录datasets/records/responses 三组 build notify 函数并通过 contexts/datasets.py 在领域操作中调用。事件通知投递到high优先队列异步执行webhook_jobs.py。六、CLI 与运维命令演进服务端运维能力随版本逐步增强v1.16.0 为 CLI 大版本用户管理users create、users list、users delete、users updatev1.11.0 起支持改角色工作区管理workspaces list、workspaces create、workspaces add-user、workspaces delete-user数据集管理datasets list、datasets delete、datasets push-to-hub服务信息info、whoami、server_info数据库v1.16.0 将database命令移入server组argilla server databasev1.22.0 彻底移除旧的python -m argilla databasev1.21.0 新增 reindex CLI 任务将数据集与记录重新索引到搜索引擎v1.8.0 新增database revisions命令查看迁移信息database migrate支持--revision参数指定目标版本。注意v2.0.0 移除了 argilla quickstart docker 镜像旧版本仍可用并使用新的argilla-hf-spaces镜像v2.0.0 引入在 HF Spaces 中运行服务端v2.5.0 将默认 Python 版本升级到 3.13、Pydantic 升级到 v2——如果你在自己的镜像中二次构建需同步这些基础依赖。七、升级与迁移清单破坏性变更速查升级 Argilla Server 前请对照以下 CHANGELOG 中标记为[breaking]或需注意的事项逐项检查v1.25.0搜索索引映射变更响应索引用 userid替代username需要 reindex移除ARGILLA_LOCAL_AUTH_*三个变量ARGILLA_USERS_DB_FILE仅用于从 YAML 迁移用户。v1.28.0废弃POST /api/v1/datasets/:dataset_id/records与PATCH /api/v1/dataset/:dataset_id/records改用 bulk 端点。v2.0.0本仓库范围内最大的一次破坏性升级移除全部 API v0 端点移除废弃的POST/PATCH .../records单条端点移除GET /api/v1/me/datasets/:dataset_id/records搜索端点不再支持response_status、metadata、sort_by查询参数改为请求体内的结构化 DSLprogress与metrics端点适配新分布任务搜索索引映射变更需要 reindex。v2.5.0Python 3.13 与 Pydantic v2——检查自定义扩展与依赖兼容性。全局约定所有环境变量必须以ARGILLA_前缀v1.13.0 起记录列表与搜索的limit限制在1~1000v1.19.0 起PATCH /api/v1/records/:record_id在 v2.6.0 起可更新字段。升级路径建议小版本2.4.x → 2.5.x可平滑升级跨大版本1.x → 2.x务必先在测试环境执行 reindex 演练并用GET /api/v1/version、GET /api/v1/status验证服务健康后再切换流量。八、源码参考路径服务入口与路由挂载argilla-server/src/argilla_server/api/routes.py环境变量定义argilla-server/src/argilla_server/settings.py、argilla-server/src/argilla_server/constants.py认证配置JWT/OAuth2argilla-server/src/argilla_server/security/settings.py记录端点实现argilla-server/src/argilla_server/api/handlers/v1/datasets/records.py、records_bulk.py数据集、导入导出端点argilla-server/src/argilla_server/api/handlers/v1/datasets/datasets.pyWebhooks 事件枚举与端点argilla-server/src/argilla_server/webhooks/v1/enums.py、argilla-server/src/argilla_server/api/handlers/v1/webhooks.py后台任务与队列argilla-server/src/argilla_server/jobs/queues.py、hub_jobs.py、dataset_jobs.py领域逻辑数据集上下文、Webhook 触发argilla-server/src/argilla_server/contexts/datasets.py完整变更记录请查阅 argilla-server/CHANGELOG.md 原文其中每个条目均保留了对应的 PR/Issue 编号可作为深入某个具体功能时回溯的索引。【免费下载链接】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），仅供参考