4 · 用户指南（User Guide）

用户指南

用户指南

相关源文件

本章引用的主要源码文件：

• README.md
• argilla-server/src/argilla_server/api/schemas/v1/suggestions.py
• argilla/README.md
• argilla/docs/assets/images/getting_started/dataset_configurator.png
• argilla/docs/assets/images/how_to_guides/custom_field/3d_object_viewer.png
• argilla/docs/assets/images/how_to_guides/custom_field/images_in_two_columns.png
• argilla/docs/assets/images/how_to_guides/custom_field/metadata_table.png
• argilla/docs/community/adding_language.md
• argilla/docs/getting_started/faq.md
• argilla/docs/getting_started/how-to-configure-argilla-on-huggingface.md
• argilla/docs/getting_started/how-to-deploy-argilla-with-docker.md
• argilla/docs/getting_started/quickstart.md
• argilla/docs/how_to_guides/annotate.md
• argilla/docs/how_to_guides/custom_fields.md
• argilla/docs/how_to_guides/dataset.md
• argilla/docs/how_to_guides/distribution.md
• argilla/docs/how_to_guides/import_export.md
• argilla/docs/how_to_guides/index.md
• argilla/docs/how_to_guides/query.md
• argilla/docs/how_to_guides/record.md
• argilla/docs/index.md
• argilla/docs/reference/argilla/client.md
• argilla/docs/reference/argilla/datasets/dataset_records.md
• argilla/docs/reference/argilla/records/metadata.md
• argilla/docs/reference/argilla/records/records.md
• argilla/docs/reference/argilla/records/responses.md
• argilla/docs/reference/argilla/records/suggestions.md
• argilla/docs/reference/argilla/search.md
• argilla/docs/reference/argilla/settings/fields.md
• argilla/docs/tutorials/image_classification.ipynb
• argilla/docs/tutorials/image_preference.ipynb
• argilla/docs/tutorials/index.md
• argilla/docs/tutorials/text_classification.ipynb
• argilla/docs/tutorials/token_classification.ipynb
• argilla/mkdocs.yml
• argilla/src/argilla/_models/_dataset_progress.py
• argilla/src/argilla/settings/_question.py

本用户指南提供了关于如何使用 Argilla 创建、管理和标注数据集的全面信息，帮助您为 AI 项目构建高质量的数据集合。内容涵盖了从连接到 Argilla 到导出已标注数据集的完整工作流。

关于部署 Argilla 的信息，请参阅入门指南。

关于详细的 API 参考文档，请参阅API 参考。

系统概览

Argilla 的架构由客户端组件和服务端组件组成，它们之间相互交互：

来源： README.md:34-45 argilla/mkdocs.yml:4-6

核心数据模型

来源： argilla/docs/how_to_guides/dataset.md:8-11 argilla/docs/how_to_guides/record.md:8-11 argilla/src/argilla/settings/_question.py:39-47

连接到 Argilla

部署 Argilla 后（请参阅入门指南），您可以使用 Python SDK 连接到它：

import argilla as rg

client = rg.Argilla(
    api_url="https://[your-owner-name]-[your_space_name].hf.space",
    api_key="[your-api-key]"
)

对于私有的 Hugging Face Spaces，需要包含您的令牌：

import argilla as rg

HF_TOKEN = "..."

client = rg.Argilla(
    api_url="<api_url>",
    api_key="<api_key>",
    headers={"Authorization": f"Bearer {HF_TOKEN}"}
)

您可以通过调用以下方法来验证连接：

client.me  # 这会返回您的用户信息

来源： argilla/docs/getting_started/quickstart.md:128-145 argilla/docs/getting_started/how-to-configure-argilla-on-huggingface.md:102-111 argilla/docs/reference/argilla/client.md:22-31

创建和管理数据集

配置数据集

要创建数据集，首先使用 Settings 类定义其设置，然后使用 Dataset 类创建它：

import argilla as rg

settings = rg.Settings(
    guidelines="将评论分类为正面或负面。",
    fields=[
        rg.TextField(
            name="review",
            title="评论文本",
            use_markdown=False,
        ),
    ],
    questions=[
        rg.LabelQuestion(
            name="sentiment_label",
            title="这篇文章属于哪个类别？",
            labels=["positive", "negative"],
        )
    ],
)

dataset = rg.Dataset(
    name="my_dataset",
    workspace="my_workspace",  # 可选：默认为您的第一个工作空间
    settings=settings,
)
dataset.create()

来源： argilla/docs/tutorials/text_classification.ipynb:154-172 argilla/docs/how_to_guides/dataset.md:58-86

字段类型

Argilla 支持以下字段类型来展示不同类型的数据：

来源： argilla/docs/how_to_guides/dataset.md:147-207 argilla/docs/reference/argilla/settings/fields.md:8-39

问题类型

问题定义了要从标注者那里收集的反馈：

来源： argilla/docs/how_to_guides/dataset.md:214-326 argilla/src/argilla/settings/_question.py:39-47

元数据和向量

元数据属性支持过滤和排序：

# 用于分类过滤的术语元数据
terms_metadata = rg.TermsMetadataProperty(
    name="terms",
    options=["group-a", "group-b", "group-c"],
    title="标注组",
    visible_for_annotators=True,
)

# 用于数值过滤的整数元数据
integer_metadata = rg.IntegerMetadataProperty(
    name="integer",
    title="输入长度",
    min=42,
    max=1984,
)

# 用于数值过滤的浮点数元数据
float_metadata = rg.FloatMetadataProperty(
    name="float",
    title="阅读难度",
    min=-92.29914,
    max=119.6975,
)

向量支持语义搜索：

vector_field = rg.VectorField(
    name="my_vector",
    title="我的向量",
    dimensions=768
)

来源： argilla/docs/how_to_guides/dataset.md:332-391

指南和任务分配

指南帮助标注者理解任务：

guidelines = "在此数据集中，您将看到一系列评论。您的任务是将每条评论分类为正面或负面。"

任务分配设置用于配置记录如何在团队成员之间分配：

task_distribution = rg.TaskDistribution(min_submitted=2)

来源： argilla/docs/how_to_guides/dataset.md:393-425

管理数据集

您可以列出、检索、更新和删除数据集：

# 列出所有数据集
for dataset in client.datasets:
    print(dataset.name)

# 按名称检索数据集
dataset = client.datasets(name="my_dataset")

# 更新数据集设置
dataset.settings.fields["text"].use_markdown = True
dataset.settings.guidelines = "更新后的指南"
dataset.update()

# 删除数据集
dataset.delete()

来源： argilla/docs/how_to_guides/dataset.md:428-625

添加和管理记录

创建数据集后，您可以向其中添加记录以供标注。

添加记录

可以通过多种方式添加记录：

使用记录对象

records = [
    rg.Record(
        fields={"review": "这部电影太棒了！"},
        metadata={"source": "imdb"},
        vectors={"my_vector": [0.1, 0.2, 0.3]},
    ),
    rg.Record(
        fields={"review": "我一点也不喜欢这部电影。"},
        metadata={"source": "rotten_tomatoes"},
        vectors={"my_vector": [0.4, 0.5, 0.6]},
    ),
]
dataset.records.log(records)

来源： argilla/docs/how_to_guides/record.md:48-77 argilla/docs/reference/argilla/records/records.md:14-25

使用数据结构

data = [
    {
        "review": "这部电影太棒了！",
        "source": "imdb",
        "my_vector": [0.1, 0.2, 0.3],
    },
    {
        "review": "我一点也不喜欢这部电影。",
        "source": "rotten_tomatoes",
        "my_vector": [0.4, 0.5, 0.6],
    },
]
dataset.records.log(data)

如果您的数据结构与字段名称不匹配，可以使用映射：

data = [
    {
        "text": "这部电影太棒了！",
        "origin": "imdb",
        "embedding": [0.1, 0.2, 0.3],
    },
]
dataset.records.log(
    data,
    mapping={
        "text": "review",
        "origin": "source",
        "embedding": "my_vector",
    }
)

来源： argilla/docs/how_to_guides/record.md:84-119 argilla/docs/reference/argilla/datasets/dataset_records.md:49-90

使用 Hugging Face 数据集

from datasets import load_dataset

hf_dataset = load_dataset("imdb", split="train[:100]")
dataset.records.log(records=hf_dataset, mapping={"text": "review"})

来源： argilla/docs/how_to_guides/record.md:125-154 argilla/docs/reference/argilla/datasets/dataset_records.md:92-116

按类型设置字段格式

不同的字段类型需要不同的数据格式：

文本字段

record = rg.Record(
    fields={"text": "你好，世界，你还好吗？"}
)

图片字段

record = rg.Record(
    fields={"image": "https://example.com/image.jpg"}  # URL
)

# 或者本地路径
record = rg.Record(
    fields={"image": "path/to/image.jpg"}
)

# 或者 PIL Image 对象
from PIL import Image
record = rg.Record(
    fields={"image": Image.open("path/to/image.jpg")}
)

聊天字段

record = rg.Record(
    fields={
        "chat": [
            {"role": "user", "content": "什么是 Argilla？"},
            {"role": "assistant", "content": "Argilla 是一个面向 AI 工程师和领域专家的协作工具，用于构建高质量数据集。"},
        ]
    }
)

自定义字段

record = rg.Record(
    fields={"custom": {"key": "value"}}
)

来源： argilla/docs/how_to_guides/record.md:156-213 argilla/docs/reference/argilla/records/records.md:26-41

添加建议

建议是预先计算好的答案，有助于加快标注速度：

record = rg.Record(
    fields={"review": "这部电影太棒了！"},
    suggestions=[
        rg.Suggestion(
            "sentiment_label",
            "positive",
            score=0.9,
            agent="model_name"
        )
    ],
)

或者使用带映射的字典结构：

data = [
    {
        "review": "这部电影太棒了！",
        "label": "positive",
        "score": 0.9,
        "agent": "model_name",
    },
]
dataset.records.log(
    data=data,
    mapping={
        "label": "sentiment_label.suggestion",
        "score": "sentiment_label.suggestion.score",
        "agent": "sentiment_label.suggestion.agent",
    },
)

来源： argilla/docs/how_to_guides/record.md:327-402 argilla/docs/reference/argilla/records/suggestions.md:16-42

管理回答

回答是标注者提供的答案：

record = rg.Record(
    fields={"review": "这部电影太棒了！"},
    responses=[
        rg.Response("sentiment_label", "positive", user_id=user.id)
    ],
)

来源： argilla/docs/how_to_guides/record.md:404-462 argilla/docs/reference/argilla/records/responses.md:16-37

更新和删除记录

要更新记录，需要先检索它们，然后重新记录并应用更改：

# 更新元数据
for record in dataset.records(with_metadata=True):
    record.metadata["new_field"] = "new_value"
dataset.records.log(list(dataset.records(with_metadata=True)))

# 删除记录
records_to_delete = list(dataset.records)[:5]
dataset.records.delete(records=records_to_delete)

来源： argilla/docs/how_to_guides/record.md:486-612

标注工作流

Argilla 通过其 Web UI 提供了一个灵活的标注界面。

标注界面概览

Argilla UI 包含以下几个关键组件：

1. 顶部栏：包含导航、数据集设置和配置文件选项
2. 左侧面板：显示控制面板和记录卡片
3. 右侧面板：包含标注表单
4. 底部面板：显示指南和标注进度

来源： argilla/docs/how_to_guides/annotate.md:14-39

标注视图

Argilla 提供两种主要的标注视图：

聚焦视图

一次显示一条记录，用于详细标注。这对于需要集中注意力的复杂标注任务非常有用。

!聚焦视图

批量视图

一次显示多条记录，用于快速标注相似项目。这对于简单的标注任务或概览数据集非常有用。

!批量视图

来源： argilla/docs/how_to_guides/annotate.md:89-122

记录状态

记录按其状态进行组织：

• 待处理：没有回答的记录
• 草稿：有部分回答的记录
• 已提交：有已提交回答的记录
• 已丢弃：已被丢弃的记录

来源： argilla/docs/how_to_guides/annotate.md:66-76

搜索和过滤数据

您可以在 UI 中使用以下方式搜索和过滤数据：

• 关键词搜索：在文本字段中搜索特定术语
• 过滤器：按元数据、回答和建议进行过滤
• 语义搜索：基于向量相似性查找相似记录
• 排序：按各种属性排序

来源： argilla/docs/how_to_guides/annotate.md:138-191

以编程方式查询记录

import argilla as rg

# 按搜索词查询
query = rg.Query(query="positive")
records = dataset.records(query=query).to_list(flatten=True)

# 按条件过滤
filter_condition = rg.Filter(("sentiment_label", "==", "positive"))
records = dataset.records(filter=filter_condition).to_list(flatten=True)

# 带过滤器的组合查询
query_with_filter = rg.Query(
    query="movie",
    filter=rg.Filter(("sentiment_label", "==", "positive"))
)
records = dataset.records(query=query_with_filter).to_list(flatten=True)

# 使用向量查找相似记录
similar = rg.Similar(name="my_vector", value=[0.1, 0.2, 0.3])
records = dataset.records(similar=similar).to_list(flatten=True)

来源： argilla/docs/how_to_guides/query.md:44-103 argilla/docs/reference/argilla/search.md:10-17

导出数据集

Argilla 提供了多种导出数据集和记录的方法。

导出到 Python

您可以将数据集的记录以多种格式导出到 Python：

# 作为字典
exported_records = dataset.records.to_dict()

# 作为字典列表
exported_records = dataset.records.to_list(flatten=True)

# 作为 Hugging Face 数据集
exported_dataset = dataset.records.to_datasets()

来源： argilla/docs/how_to_guides/import_export.md:224-282

导出到本地磁盘

您可以将数据集保存到本地磁盘：

dataset.to_disk(path="<path-empty-directory>")

要重新加载它：

imported_dataset = rg.Dataset.from_disk(path="<path-dataset-directory>")

来源： argilla/docs/how_to_guides/import_export.md:176-211

导出到 Hugging Face Hub

您可以将数据集推送到 Hugging Face Hub：

dataset.to_hub(repo_id="<my_org>/<my_dataset>")

要重新加载它：

imported_dataset = rg.Dataset.from_hub(repo_id="<my_org>/<my_dataset>")

来源： argilla/docs/how_to_guides/import_export.md:86-173 argilla/docs/getting_started/quickstart.md:152-164

示例工作流

文本分类

# 创建用于文本分类的数据集
settings = rg.Settings(
    guidelines="将评论分类为正面或负面。",
    fields=[
        rg.TextField(name="review", title="评论文本"),
    ],
    questions=[
        rg.LabelQuestion(name="sentiment", labels=["positive", "negative"]),
    ],
)
dataset = rg.Dataset(name="text_classification", settings=settings).create()

# 添加记录
from datasets import load_dataset
hf_dataset = load_dataset("imdb", split="train[:100]")
dataset.records.log(records=hf_dataset, mapping={"text": "review"})

# 添加模型建议
model = train_model(model_name="TaylorAI/bge-micro-v2", dataset=zero_ds)
for record in dataset.records():
    record.suggestions = [
        rg.Suggestion(
            "sentiment",
            predict(model, record.fields["review"], ["positive", "negative"]),
            score=0.9,
            agent="model_name"
        )
    ]
dataset.records.log(list(dataset.records()))

# 导出已标注数据
status_filter = rg.Query(filter=rg.Filter(("response.status", "==", "submitted")))
submitted = dataset.records(status_filter).to_list(flatten=True)
train_dataset = Dataset.from_list([
    {"text": r["review"], "label": r["sentiment.responses"][0]}
    for r in submitted
])

来源： argilla/docs/tutorials/text_classification.ipynb:154-172 argilla/docs/tutorials/text_classification.ipynb:209-232 argilla/docs/tutorials/text_classification.ipynb:364-376 argilla/docs/tutorials/text_classification.ipynb:425-442

令牌分类（命名实体识别）

# 创建用于命名实体识别的数据集
settings = rg.Settings(
    guidelines="识别文本中的实体。",
    fields=[
        rg.TextField(name="text", title="文本"),
    ],
    questions=[
        rg.SpanQuestion(
            name="entities",
            field="text",
            labels=["PERSON", "ORG", "LOC", "MISC"],
            title="选择文本中的实体",
        ),
    ],
)
dataset = rg.Dataset(name="ner_dataset", settings=settings).create()

# 添加记录
from datasets import load_dataset
hf_dataset = load_dataset("conll2003", split="train[:100]")
dataset.records.log([
    rg.Record(fields={"text": " ".join(tokens)})
    for tokens in hf_dataset["tokens"]
])

# 导出已标注数据用于训练
submitted = dataset.records(
    rg.Query(filter=rg.Filter(("response.status", "==", "submitted")))
).to_list(flatten=True)

来源： argilla/docs/tutorials/token_classification.ipynb:152-196 argilla/docs/tutorials/token_classification.ipynb:245-257 argilla/docs/tutorials/token_classification.ipynb:410-414

标注界面功能

标注界面提供了多种功能，使标注更加高效：

键盘快捷键

来源： argilla/docs/how_to_guides/annotate.md:40-64

建议

如果您的数据集包含模型预测，它们会在 UI 中以火花图标（✨）显示。这些建议是预填的回答，有助于加快标注速度。

来源： argilla/docs/how_to_guides/annotate.md:83-88

进度跟踪

您可以通过 UI 中的进度条和进度面板跟踪标注进度，它们会显示已完成和待完成的记录数量。

来源： argilla/docs/how_to_guides/annotate.md:123-130

高级功能

带模板的自定义字段

自定义字段允许您使用 HTML、CSS 和 JavaScript 创建自定义显示：

css_template = """
<style>
#container { display: flex; gap: 10px; }
.column { flex: 1; }
</style>
"""

html_template = """
<div id="container">
    <div class="column">
        <h3>原始</h3>
        <img src="{{record.fields.image.original}}" />
    </div>
    <div class="column">
        <h3>修订版</h3>
        <img src="{{record.fields.image.revision}}" />
    </div>
</div>
"""

custom_field = rg.CustomField(
    name="image",
    template=css_template + html_template,
)

settings = rg.Settings(
    fields=[custom_field],
    questions=[rg.TextQuestion(name="feedback")],
)

dataset = rg.Dataset(name="custom_field_dataset", settings=settings).create()

来源： argilla/docs/how_to_guides/custom_fields.md:36-96

团队标注的任务分配

任务分配设置允许您配置记录如何在团队成员之间分配：

settings = rg.Settings(
    fields=[rg.TextField(name="text")],
    questions=[rg.LabelQuestion(name="label", labels=["positive", "negative"])],
    distribution=rg.TaskDistribution(min_submitted=2),
)

这可以确保每条记录至少获得来自不同团队成员的 2 次标注。

来源： argilla/docs/how_to_guides/dataset.md:416-423 argilla/docs/how_to_guides/distribution.md:6-8

总结

本用户指南涵盖了使用 Argilla 进行数据集创建、记录管理、标注和导出的基本方面。如需更详细的信息，请参阅文档中的具体操作指南和教程。

来源：

• argilla/docs/how_to_guides/index.md:6-9
• argilla/docs/tutorials/index.md:8-9