企业官网建设流程全解析

Argilla 2.x 迁移指南：将 Users、Workspaces 与 Legacy 数据集迁移到新版 SDK 与服务器

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

Argilla 从 1.x 升级到 2.x 后，SDK 与数据模型发生了根本性重构：旧版任务专用数据集（Task-specific datasets）已被统一的Settings+Dataset+Record模型取代。本指南基于 migrate_from_legacy_datasets.md，结合仓库内argilla（新 SDK）、argilla-v1（兼容层）与argilla-server（服务端）的实际源码，完整讲解如何将 V1 服务器上的用户、工作区与 legacy 数据集迁移到 Argilla 2.x，读完即可按步骤实操完成迁移。

1. 迁移背景：为什么需要迁移

Argilla 2.x 引入了一套全新的、可扩展的 SDK 与服务器架构。旧版 SDK 中，数据集按照标注任务被划分为多个专用类型：

这三个类在仓库中的定义可参见 argilla-v1/src/argilla_v1/client/datasets.py。新版 SDK 中，它们被统一为通用的Dataset+Settings+Record模型，旧版的record.inputs、prediction、annotation等专用字段结构也被Fields、Questions、Suggestions、Responses等通用概念取代。

一个重要例外：FeedbackDataset不需要迁移——它本身就是 Argilla V2 数据格式的过渡命名。但由于 2.x 版本修改了搜索引擎的索引结构，仍需通过启用 Docker 环境变量REINDEX_DATASETS来重建搜索索引（在 Hugging Face Space 中运行时该步骤会自动执行）。该变量在 argilla-server 配置文档 中有说明：当值为true或1时，数据集会在搜索引擎中重建索引，默认值为0。

前提条件

• 一个运行着 legacy 数据集、版本为Argilla 1.x的服务器实例；
• 一个Argilla >= 1.29的服务器实例（如果没有，可参照 快速开始指南 创建）；
• 环境中已安装新版argillaSDK 包。

⚠️重要警告：本指南会在新服务器上重建所有 Users 与 Workspaces，因此它们会获得新的密码和新的 ID。如果希望保留原有密码与 ID，可以先把数据集复制到一个临时 V2 实例，将当前实例升级到 2.0 后，再把数据集复制回原实例。

迁移策略：同一服务器还是新服务器

如果你的 legacy 数据集位于1.29 之后发布版本的服务器上，可以选择在同一台服务器上把 legacy 数据集重建为新数据集，之后将服务器升级到 Argilla 2.0 并继续使用。升级后 legacy 数据集在新服务器上不可见，但底层存储层仍会保留这些数据，必要时仍可访问。

安装新版 SDK

迁移指南需要使用新版argilla包，它内置了v1模块，允许你连接 Argilla V1 服务器：

pip install "argilla>=2.0.0"

从源码看，argilla.v1模块本质上是argilla_v1包的转发层：在 argilla/src/argilla/v1/init.py 中，它通过from argilla_v1 import *导入旧版 API，若未安装argilla-v1包会提示pip install "argilla[legacy]"；同时该模块会发出DeprecationWarning，说明它仅用于迁移目的、未来将被移除。

2. 迁移 Users 与 Workspaces

迁移用户与工作区分为两步：

1. 从 V1 服务器检索旧用户与旧工作区——使用新argilla包中的v1模块；
2. 在 V2 服务器上重建用户与工作区——以name作为唯一标识符。

Step 1：检索旧用户与旧工作区

使用v1模块连接 Argilla V1 服务器：

import argilla.v1 as rg_v1 # 初始化 API：连接一个版本低于 2.0 的 Argilla 服务器 api_url = "<your-url>" api_key = "<your-api-key>" rg_v1.init(api_url, api_key)

随后从 V1 服务器加载User与Workspace：

users_v1 = rg_v1.User.list() workspaces_v1 = rg_v1.Workspace.list()

Step 2：在 V2 服务器上重建用户与工作区

先在 V2 服务器上建立连接。Argilla类是连接服务端 API 的主入口（定义于 argilla/src/argilla/client.py），其api_url默认取ARGILLA_API_URL环境变量、回退到http://localhost:6900，api_key默认取ARGILLA_API_KEY环境变量：

import argilla as rg client = rg.Argilla()

然后重建工作区与用户：

for workspace in workspaces_v1: rg.Workspace( id=workspace.id, name=workspace.name, ).create()

for user in users_v1: user_v2 = rg.User( id=user.id, username=user.username, first_name=user.first_name, last_name=user.last_name, role=user.role, password="<your_chosen_password>" # (1) ).create() if user.role == "owner": continue for workspace in user.workspaces: workspace_v2 = client.workspaces(name=workspace.name) if workspace_v2 is None: continue user.add_to_workspace(workspace_v2)

1. 你需要为新用户选择一个新密码。若想以编程方式生成随机密码，可使用uuid包；请务必记录所选密码，因为之后无法再检索。

代码要点说明：

• client.workspaces(name=...)是工作区集合的可调用查找接口：存在则返回Workspace，不存在返回None（见 client.py）；
• user.add_to_workspace(workspace)是 用户资源类 提供的方法，用于把用户加入指定工作区；
• 跳过owner角色是因为 owner 天然拥有全部工作区，无需显式加入。

完成上述两步后，用户与工作区即成功迁移到 Argilla V2，可以继续后续的数据集迁移。

3. 迁移 Datasets：三步走

数据集迁移分为三步：

1. 从 V1 服务器检索 legacy 数据集；
2. 按 Argilla V2 格式定义新数据集；
3. 将记录上传到新数据集并转换字段与属性。

Step 1：检索 legacy 数据集

同样使用v1模块连接 V1 服务器：

import argilla.v1 as rg_v1 # 初始化 API：连接一个版本低于 2.0 的 Argilla 服务器 api_url = "<your-url>" api_key = "<your-api-key>" rg_v1.init(api_url, api_key)

然后加载数据集的设置与记录：

dataset_name = "news-programmatic-labeling" workspace = "demo" settings_v1 = rg_v1.load_dataset_settings(dataset_name, workspace) records_v1 = rg_v1.load(dataset_name, workspace) hf_dataset = records_v1.to_datasets()

• load_dataset_settings(name, workspace)会从 V1 服务器加载数据集设置（如标签 schema），其实现见 argilla-v1/src/argilla_v1/datasets/init.py；
• rg_v1.load(name, workspace)返回一个Dataset对象，支持query、vector、ids、limit、sort、id_from、batch_size等检索参数（完整签名见 argilla-v1/src/argilla_v1/client/api.py），对于大数据集可以配合limit与id_from分批加载；
• to_datasets()将 V1 记录转换为 Hugging Facedatasets.Dataset对象，其中每条记录的字段包括text、inputs、metadata、vectors、prediction、prediction_agent、annotation、annotation_agent等（见 argilla-v1/src/argilla_v1/client/datasets.py）。

至此，legacy 数据集已加载到hf_dataset对象中。

Step 2：定义新数据集

新数据集以Settings与Dataset类定义。首先连接 V2 服务器：

import argilla as rg client = rg.Argilla()

然后根据任务类型定义设置。注意：设置中的fields、metadata、vectors必须覆盖旧数据集记录中实际出现的全部字段，questions的名称必须与后续记录转换函数中使用的question_name一一对应。

单标签分类（Single-label classification）

settings = rg.Settings( fields=[ rg.TextField(name="text"), # (1) ], questions=[ rg.LabelQuestion(name="label", labels=settings_v1.label_schema), ], metadata=[ rg.TermsMetadataProperty(name="split"), # (2) ], vectors=[ rg.VectorField(name='mini-lm-sentence-transformers', dimensions=384), # (3) ], )

1. DatasetForTextClassification的默认字段是text，但务必提供record.inputs中包含的所有字段。
2. 务必提供数据集中可用的所有相关元数据字段。
3. 务必提供数据集中可用的所有相关向量。

多标签分类（Multi-label classification）

settings = rg.Settings( fields=[ rg.TextField(name="text"), # (1) ], questions=[ rg.MultiLabelQuestion(name="labels", labels=settings_v1.label_schema), ], metadata=[ rg.TermsMetadataProperty(name="split"), # (2) ], vectors=[ rg.VectorField(name='mini-lm-sentence-transformers', dimensions=384), # (3) ], )

1. DatasetForTextClassification的默认字段是text，但应提供record.inputs中包含的所有字段。
2. 务必提供数据集中可用的所有相关元数据字段。
3. 务必提供数据集中可用的所有相关向量。

序列标注（Token classification）

settings = rg.Settings( fields=[ rg.TextField(name="text"), ], questions=[ rg.SpanQuestion(name="spans", labels=settings_v1.label_schema), ], metadata=[ rg.TermsMetadataProperty(name="split"), # (1) ], vectors=[ rg.VectorField(name='mini-lm-sentence-transformers', dimensions=384), # (2) ], )

1. 务必提供数据集中可用的所有相关元数据字段。
2. 务必提供数据集中可用的所有相关向量。

文本生成（Text generation）

settings = rg.Settings( fields=[ rg.TextField(name="text"), ], questions=[ rg.TextQuestion(name="text_generation"), ], metadata=[ rg.TermsMetadataProperty(name="split"), # (1) ], vectors=[ rg.VectorField(name='mini-lm-sentence-transformers', dimensions=384), # (2) ], )

1. 应提供数据集中可用的所有相关元数据字段。
2. 应提供数据集中可用的所有相关向量。

字段类型与底层模型对应关系：上述各设置类均有对应的服务端数据模型：rg.TextField对应TextFieldSettings（argilla/src/argilla/_models/_settings/_fields.py），LabelQuestion/MultiLabelQuestion/SpanQuestion/TextQuestion对应 _questions.py 中同名模型，TermsMetadataProperty对应 _metadata.py，VectorField对应 _vectors.py。定义 Settings 时传入的参数会通过 API 序列化为服务端的字段、问题与元数据配置，因此名称与旧数据集实际内容保持一致是迁移成功的前提。

最后，在 V2 服务器上创建新数据集：

dataset = rg.Dataset(name=dataset_name, workspace=workspace, settings=settings) dataset.create()

注意：如果同名数据集已存在，create方法会抛出异常。可以先检查数据集是否存在，存在则删除后再创建：

dataset = client.datasets(name=dataset_name, workspace=workspace) if dataset is not None: dataset.delete()

其中client.datasets(name=..., workspace=...)是数据集集合的查找接口，找不到时返回None（见 argilla/src/argilla/client.py）。

Step 3：上传数据集记录

新版argillaSDK 使用通用的Record类，而 legacy 数据集有各自的专用记录类，因此需要编写转换函数把 V1 格式记录转换为通用Record。下面是单标签 / 多标签分类、序列标注与文本生成四类任务的示例转换函数，可按需修改。

单标签分类

def map_to_record_for_single_label(data: dict, users_by_name: dict, current_user: rg.User) -> rg.Record: """ This function maps a text classification record dictionary to the new Argilla record.""" suggestions = [] responses = [] if prediction := data.get("prediction"): label, score = prediction[0].values() agent = data["prediction_agent"] suggestions.append( rg.Suggestion( question_name="label", # (1) value=label, score=score, agent=agent ) ) if annotation := data.get("annotation"): user_id = users_by_name.get(data["annotation_agent"], current_user).id responses.append( rg.Response( question_name="label", # (2) value=annotation, user_id=user_id ) ) return rg.Record( id=data["id"], fields=data["inputs"], # The inputs field should be a dictionary with the same keys as the `fields` in the settings metadata=data["metadata"], # The metadata field should be a dictionary with the same keys as the `metadata` in the settings vectors=data.get("vectors") or {}, suggestions=suggestions, responses=responses, )

1. 确保question_name与问题设置中的问题名称一致。
2. 确保question_name与问题设置中的问题名称一致。

多标签分类

def map_to_record_for_multi_label(data: dict, users_by_name: dict, current_user: rg.User) -> rg.Record: """ This function maps a text classification record dictionary to the new Argilla record.""" suggestions = [] responses = [] if prediction := data.get("prediction"): labels, scores = zip(*[(pred["label"], pred["score"]) for pred in prediction]) agent = data["prediction_agent"] suggestions.append( rg.Suggestion( question_name="labels", # (1) value=labels, score=scores, agent=agent ) ) if annotation := data.get("annotation"): user_id = users_by_name.get(data["annotation_agent"], current_user).id responses.append( rg.Response( question_name="labels", # (2) value=annotation, user_id=user_id ) ) return rg.Record( id=data["id"], fields=data["inputs"], # The inputs field should be a dictionary with the same keys as the `fields` in the settings metadata=data["metadata"], # The metadata field should be a dictionary with the same keys as the `metadata` in the settings vectors=data.get("vectors") or {}, suggestions=suggestions, responses=responses, )

1. 确保question_name与问题设置中的问题名称一致。
2. 确保question_name与问题设置中的问题名称一致。

序列标注

def map_to_record_for_span(data: dict, users_by_name: dict, current_user: rg.User) -> rg.Record: """ This function maps a token classification record dictionary to the new Argilla record.""" suggestions = [] responses = [] if prediction := data.get("prediction"): scores = [span["score"] for span in prediction] agent = data["prediction_agent"] suggestions.append( rg.Suggestion( question_name="spans", # (1) value=prediction, score=scores, agent=agent ) ) if annotation := data.get("annotation"): user_id = users_by_name.get(data["annotation_agent"], current_user).id responses.append( rg.Response( question_name="spans", # (2) value=annotation, user_id=user_id ) ) return rg.Record( id=data["id"], fields={"text": data["text"]}, # The inputs field should be a dictionary with the same keys as the `fields` in the settings metadata=data["metadata"], # The metadata field should be a dictionary with the same keys as the `metadata` in the settings vectors=data.get("vectors") or {}, # The vectors field should be a dictionary with the same keys as the `vectors` in the settings suggestions=suggestions, responses=responses, )

1. 确保question_name与问题设置中的问题名称一致。
2. 确保question_name与问题设置中的问题名称一致。

文本生成

def map_to_record_for_text_generation(data: dict, users_by_name: dict, current_user: rg.User) -> rg.Record: """ This function maps a text2text record dictionary to the new Argilla record.""" suggestions = [] responses = [] if prediction := data.get("prediction"): first = prediction[0] agent = data["prediction_agent"] suggestions.append( rg.Suggestion( question_name="text_generation", # (1) value=first["text"], score=first["score"], agent=agent ) ) if annotation := data.get("annotation"): # From data[annotation] user_id = users_by_name.get(data["annotation_agent"], current_user).id responses.append( rg.Response( question_name="text_generation", # (2) value=annotation, user_id=user_id ) ) return rg.Record( id=data["id"], fields={"text": data["text"]}, # The inputs field should be a dictionary with the same keys as the `fields` in the settings metadata=data["metadata"], # The metadata field should be a dictionary with the same keys as the `metadata` in the settings vectors=data.get("vectors") or {}, # The vectors field should be a dictionary with the same keys as the `vectors` in the settings suggestions=suggestions, responses=responses, )

1. 确保question_name与问题设置中的问题名称一致。
2. 确保question_name与问题设置中的问题名称一致。

上述转换函数的共同设计逻辑：

• prediction（模型预测）映射为Suggestion：V1 的prediction_agent记录预测来源，转换后作为 Suggestion 的agent；单标签取prediction[0]的 label/score，多标签拆包为 labels/scores 两个元组，序列标注取所有 span 的 score 列表，文本生成取第一条预测的text与score；
• annotation（人工标注）映射为Response：通过users_by_name把annotation_agent解析为 V2 用户 ID，作为 Response 的user_id；
• fields、metadata、vectors的键必须与 Settings 中定义的字段名一致，否则记录写入会失败。

转换函数依赖users_by_name字典与current_user对象来把 Response 分配给正确用户，需要先从 V2 服务器加载现有用户与当前用户：

users_by_name = {user.username: user for user in client.users} current_user = client.me

• client.users返回服务器上的用户集合（Users，可迭代，见 client.py）；
• client.me返回当前登录用户（User，见 client.py）。

最后，遍历hf_records调用映射函数生成Record列表，并用log方法上传：

records = [] for data in hf_records: records.append(map_to_record_for_single_label(data, users_by_name, current_user)) # Upload the records to the new dataset dataset.records.log(records)

DatasetRecords.log是记录上传的入口（argilla/src/argilla/records/_dataset_records.py）：它接收Record列表、dict 列表或 Hugging Face Dataset，支持mapping、user_id、batch_size（默认 256）与on_error（默认抛异常）等参数；底层通过_api.bulk_upsert分批写入服务端，并自动把批次大小限制在单次 bulk 允许的最大记录数之内。若记录包含已知id则更新，否则新增。

至此，你的 legacy 数据集已成功迁移到 Argilla V2。

4. 迁移对照速查表

5. 常见问题与注意事项

1. 密码与 ID 会被重置：本指南的迁移方式在新服务器上重建用户与工作区，会生成新的密码和 ID；需要保留原始凭据时，应走"临时 V2 实例中转 → 升级原实例 → 复制回原实例"的路径。
2. 同名数据集冲突：create遇到同名数据集会抛异常，先通过client.datasets(name=..., workspace=...)检查并用dataset.delete()清理。
3. 字段名必须严格对应：Settings中的fields/metadata/vectors名称、Record中的字段字典键、Suggestion/Response中的question_name三者必须互相匹配，任何一处不一致都会导致写入失败或数据错位。
4. FeedbackDataset的索引重建：升级到 2.x 后，即使数据格式无需迁移，也要注意搜索引擎索引结构已变化，需通过 Docker 环境变量REINDEX_DATASETS=true触发重建（Hugging Face Space 会自动执行）。
5. v1模块是过渡方案：argilla.v1仅为迁移目的提供、已被标记为弃用（deprecated），应在完成迁移后尽快切换到新版 API，不要在新代码中继续依赖。

6. 进一步阅读

• Argilla SDK How-to 指南总览（含用户、工作区、数据集、记录、标注分发、查询过滤、导入导出等进阶指南）
• 管理用户与凭据、管理工作区
• 创建、更新与删除数据集、新增、更新与删除记录
• Argilla Server 配置（环境变量与 Docker 镜像）

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