Argilla 从 Rubrix 迁移指南：模块重命名、ARGILLA_ 环境变量与 Elasticsearch 索引命名约定

Argilla 从 Rubrix 迁移指南模块重命名、ARGILLA_ 环境变量与 Elasticsearch 索引命名约定【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argilla如果你正在运行一套 Rubrix 服务并希望升级到新的 Argilla 服务端这篇指南讲清楚三件核心事情Python 模块与命令行入口的重命名方式、环境变量从RUBRIX_前缀切换到ARGILLA_前缀的完整处理策略以及 Rubrix 旧版 Elasticsearch 索引.rubrix.*如何被新的ar.datasets/ar.dataset.dataset_id命名约定所取代。读完本文你将能够不改代码逻辑地切换客户端代码、为新旧两套实例准备可回滚的环境配置并通过迁移开关让旧数据集在新 Argilla 服务中“零拷贝”可见。本文以 docs/migration-rubrix.md 为骨架并结合本仓库中 Argilla 服务端的真实源码配置解析、CLI 入口逐条印证文档结论。迁移背景为什么要迁移Rubrix 已更名/演化为 Argilla——面向 AI 工程师与领域专家协作构建高质量数据集的工具。对于既有 Rubrix 部署官方迁移指南给出的核心承诺是客户端代码保持完全兼容服务端数据可以平滑接管。迁移涉及三个层面客户端代码层Python 模块与启动命令的更名纯文本替换即可完成运维配置层环境变量前缀由RUBRIX_改为ARGILLA_数据存储层Elasticsearch 索引命名从.rubrix.*切换到ar.*需要借助迁移开关完成旧索引的接管。Python 模块与命令的重命名客户端import rubrix替换为import argilla文档明确说明模块名从rubrix改为argilla但其余代码保持完全兼容。升级现有代码库时只需要把import rubrix # 旧 import argilla # 新做全局文本替换即可无需改动调用方式。这一点在仓库中可以得到印证新版客户端入口 argilla/src/argilla/init.py 统一导出了client、datasets、workspaces、users、settings、records、responses、vectors、webhooks等子模块即新版对外 API 面的聚合点仓库同时保留了旧版Rubrix 时代的完整客户端包在 argilla-v1/src/argilla_v1 下包含client/、labeling/、metrics/、training/、cli/等目录可作为旧版代码行为的对照参考其配套测试位于 argilla-v1/tests。服务端python -m rubrix替换为argilla server start旧版通过python -m rubrix拉起服务端新版等价命令为argilla server start对应实现位于argilla-server子项目的 CLI 包 argilla-server/src/argilla_server/cli其中 start.py 提供启动入口database/、search_engine/、worker.py等目录分别承载数据库迁移、搜索引擎相关子命令与后台 worker。服务端包的发布名在 argilla-server/pyproject.toml 中声明为argilla-server。如果你的部署走 Docker仓库提供了现成示例可参照将镜像与命令换成 Argilla 版本即可服务端镜像argilla-server/docker/server/Dockerfile端到端部署编排examples/deployments/docker/docker-compose.yaml同目录还包含 nginx 与 traefik 反向代理配置。环境变量前缀从 RUBRIX_ 变为 ARGILLA_规则与源码依据所有环境变量的前缀从RUBRIX_变更为ARGILLA_。从服务端配置源码看这一规则由 pydantic-settings 的Config.env_prefix统一实现见 argilla-server/src/argilla_server/settings.pyclass Config: env_prefix ARGILLA_这意味着 Settings 中的每个字段都会映射为ARGILLA_前缀的环境变量例如Settings 字段环境变量默认值说明elasticsearchARGILLA_ELASTICSEARCHhttp://localhost:9200数据集持久化所用 Elasticsearch 端点database_urlARGILLA_DATABASE_URL自动落到~/.argilla/argilla.db关系型数据库SQLite/PostgreSQL连接串home_pathARGILLA_HOME_PATH~/.argillaArgilla 相关文件存放目录redis_urlARGILLA_REDIS_URLredis://localhost:6379/0Redis 连接任务/队列es_records_index_shards/es_records_index_replicasARGILLA_ES_RECORDS_INDEX_SHARDS/ARGILLA_ES_RECORDS_INDEX_REPLICAS1/0数据集记录索引的分片与副本数无前缀变量的兼容期与回滚建议原文档指出ELASTICSEARCH等不带前缀的环境变量在当前版本仍然可用但未来会被移除应当改用ARGILLA_前缀版本。作为补充仓库内另一份迁移文档 docs/_source/community/migration-rubrix.md 进一步说明自 1.13.0 版本起对无前缀环境变量的支持已被移除所有变量必须带ARGILLA_前缀。做迁移时请以目标 Argilla 版本的实际行为为准并在升级前完成前缀切换。文档给出的关键运维建议是为新旧两套实例复制完整的环境变量配置——即同时保留RUBRIX_*与ARGILLA_*两组变量分别指向 Rubrix 与 Argilla 实例。这样做的收益是迁移过程中如需版本回滚只需切回 Rubrix 实例旧配置原样可用回滚成本被降到最低。Elasticsearch 索引的新命名约定Argilla 为 Elasticsearch 中存储的索引引入了新的命名规则旧新对照如下用途Rubrix 旧命名Argilla 新命名数据集元信息索引汇总所有已创建数据集.rubrix.datasets-v0ar.datasets数据集记录索引每个数据集一个.rubrix.dataset.dataset_id.records-v0ar.dataset.dataset_id新命名约定在服务端配置中有直接定义见 argilla-server/src/argilla_server/settings.py__DATASETS_INDEX_NAME__ ar.datasets __DATASETS_RECORDS_INDEX_NAME__ ar.dataset.{}其中{}占位符在运行时被具体数据集 ID 填充。需要特别注意的是Rubrix 的旧索引名以点.开头Elasticsearch 中点前缀表示系统/隐藏索引而 Argilla 的新索引名ar.*是普通可见索引。因此迁移不能简单重命名索引而要靠下一节的迁移机制通过**别名alias**把旧索引挂到新的命名空间下。启用迁移流程ARGILLA_ENABLE_MIGRATION默认行为新版 Argilla 服务启动时默认不会检查是否已存在旧 Rubrix 实例的数据集。也就是说即使 Rubrix 与 Argilla 共用同一个 Elasticsearch 集群Argilla 启动后也看不到旧数据集。迁移开关的用法要让新 Argilla 服务自动发现旧 Rubrix 数据集并使其可见在启动 Argilla 服务之前设置环境变量ARGILLA_ENABLE_MIGRATIONARGILLA_ENABLE_MIGRATION1 argilla server start迁移过程内部做了什么根据迁移文档的描述开启该开关后迁移流程依次完成两件事数据集元信息复制读取 Rubrix 实例的.rubrix.datasets-v0索引中的数据集信息把信息复制进新的ar.datasets索引。注意是复制元信息数据集名称、配置、用户等管理数据而非搬运记录数据本身记录索引打别名对每一个旧的 Rubrix 记录索引.rubrix.dataset.dataset_id.records-v0创建一个符合新命名约定ar.dataset.dataset_id的别名alias。这一设计的直接好处是不复制数据记录数据仍留在原 Rubrix 索引中Argilla 通过别名访问避免了大规模数据搬迁带来的存储翻倍与停机窗口双向可见旧 Rubrix 服务与旧数据之间的“变化”写入旧索引的数据在 Argilla 侧依然可见渐进式迁移文档明确称该开关“可以帮你更平滑地渐进过渡到 Argilla”即可以先用新服务接管旧数据再逐步把新建工作流迁到 Argilla最后再考虑彻底下线 Rubrix。关于该开关的代码位置需要说明从当前仓库的argilla-server源码结构看ARGILLA_ENABLE_MIGRATION属于早期 Rubrix → Argilla 过渡版本在启动阶段执行的 Elasticsearch 层迁移逻辑当前主干源码中未再出现该开关当前版本中的数据库层迁移改由 Alembic 体系承载参见 argilla-server/src/argilla_server/cli/database/migrate.py 及其 Alembic 脚本目录 argilla-server/src/argilla_server/alembic。若你正处在最初从 Rubrix 迁移的阶段以本节文档描述的启动参数为准。重要限制单向可见文档中有一条必须重视的警告在 Argilla 中新建的数据集不会在旧的 Rubrix 实例中可见。原因是新数据集直接写入ar.datasets与ar.dataset.id索引而旧 Rubrix 服务只读取.rubrix.*命名空间。因此迁移期间应避免依赖旧 Rubrix 实例做数据集管理一切以新 Argilla 服务为准。迁移检查清单与支持渠道结合上述各节一次完整的 Rubrix → Argilla 迁移可以按如下清单执行代码全局替换import rubrix为import argilla见 argilla/src/argilla/init.py 的新版 API 导出面无需其他改动启动命令用argilla server start替换python -m rubrix环境变量复制一套带ARGILLA_前缀的完整配置参考 argilla-server/src/argilla_server/settings.py 的字段清单同时保留原RUBRIX_*配置用于回滚确认 Elasticsearch 端点统一使用ARGILLA_ELASTICSEARCH数据以ARGILLA_ENABLE_MIGRATION1启动新服务确认.rubrix.datasets-v0的信息已进入ar.datasets、旧记录索引已挂上ar.dataset.dataset_id别名验证在 Argilla Web 端登录并核对旧数据集及其记录可正常浏览与标注收尾确认稳定后停止 Rubrix 实例归档其RUBRIX_*配置。最后文档提供了官方支持渠道迁移过程中如遇到问题建议通过社区Discord联系官方团队或直接提交 GitHub issue。另外查阅旧版 Rubrix 的历史文档也有助于理解迁移前的行为细节旧文档链接见 docs/_source/community/migration-rubrix.md 末尾“Old versions of Rubrix”一节的指引。【免费下载链接】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），仅供参考