3.3 · 问题项与字段（Questions and Fields）

人工复核与反馈数据 · 聚焦本章的模块关系、源码依据与实现要点。

项目Argilla 章节3.3 状态全文译文模块检索、召回与索引、接口与服务契约、评测、反馈与人工复核、测试、发布与运维

项目要点页2.5 参考项目项目章节目录Argilla DeepWiki 原始章节Questions and Fields 上一章3.2 下一章4

源码线索

README.md
argilla-server/src/argilla_server/api/schemas/v1/suggestions.py
argilla-server/tests/unit/validators/test_records_bulk.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/getting_started/faq.md
argilla/docs/getting_started/how-to-configure-argilla-on-huggingface.md

模块标签

检索、召回与索引
接口与服务契约
评测、反馈与人工复核
测试、发布与运维
界面与交互

章节正文

问题项与字段

原始 DeepWiki 页面https://deepwiki.com/argilla-io/argilla/3.3-questions-and-fields

问题与字段

问题与字段概述

在 Argilla 中，数据标注过程围绕两个关键概念构建：

字段：展示组件，用于向用户显示待标注的数据（文本、图片、聊天记录或自定义内容）
问题：标注组件，用于收集用户对数据的反馈（标签、评分、文本等）

Argilla · 问题与字段概述 · 图 1

来源： argilla/src/argilla/settings/_resource.py:46-64 argilla/src/argilla/settings/_resource.py:90-121 README.md:42-69

字段类型

字段定义了向标注者展示哪些数据。Argilla 提供了几种内置字段类型，用于处理不同类型的内容：

Argilla · 字段类型 · 图 2

来源： argilla/src/argilla/settings/_field.py:45-295 argilla/tests/unit/test_create_datasets.py:34-43

TextField

TextField 用于向标注者展示文本内容。它支持可选的 Markdown 渲染，是 Argilla 中最常用的字段类型。

rg.TextField(
    name="text",
    title="文档文本",  # 可选，但建议为 UI 清晰性而设置
    use_markdown=False,     # 设置为 True 以渲染 Markdown
    required=True,          # 默认为 True
    description="待分类的文本"  # 可选的帮助文本
)

来源： argilla/src/argilla/settings/_field.py:98-136 README.md:117-121

ImageField

ImageField 用于向标注者展示图片。它接受图片 URL、Base64 编码的图片或文件路径。

rg.ImageField(
    name="image",
    title="文档图片",
    required=True,
    description="待分类的图片"
)

来源： argilla/src/argilla/settings/_field.py:138-167

ChatField

ChatField 专为展示包含多个角色（如"用户"和"助手"）消息的聊天对话而设计。它适用于标注对话数据，尤其是大语言模型（LLM）评估场景。

rg.ChatField(
    name="chat",
    title="对话",
    use_markdown=True,  # 聊天字段默认为 True
    required=True,
    description="待评估的聊天对话"
)

来源： argilla/src/argilla/settings/_field.py:169-208

CustomField

CustomField 提供了使用 HTML、CSS 和 JavaScript 创建自定义 UI 组件的灵活性。它支持基于模板的方法，用于展示复杂或交互式内容。

rg.CustomField(
    name="custom",
    title="自定义展示",
    template="<div>{{field.key}}</div>",  # 使用 Handlebars 语法的模板
    advanced_mode=False,  # 设置为 True 以使用自定义 JavaScript
    required=True,
    description="自定义字段描述"
)

来源： argilla/src/argilla/settings/_field.py:210-279 argilla/docs/how_to_guides/custom_fields.md:11-22

问题类型

问题定义了标注者应标注数据的哪些方面。Argilla 提供了几种内置问题类型，用于收集不同类型的标注：

Argilla · 问题类型 · 图 3

来源： argilla/src/argilla/settings/_question.py:50-97 argilla/tests/unit/test_settings/test_settings.py:77-100

LabelQuestion

LabelQuestion 用于单标签分类任务，标注者从预定义的选项集中选择一个标签。

rg.LabelQuestion(
    name="sentiment",
    title="文档情感",
    labels=["positive", "negative", "neutral"],
    visible_labels=3,  # 可选：一次可见的标签数量
    required=True,
    description="选择文本的情感"
)

来源： README.md:115-121 argilla/docs/reference/argilla/settings/settings.md:20-22

MultiLabelQuestion

MultiLabelQuestion 允许标注者从预定义集中选择多个标签，适用于内容可能属于多个类别的多标签分类任务。

rg.MultiLabelQuestion(
    name="topics",
    title="文档主题",
    labels=["politics", "sports", "technology", "entertainment", "business"],
    visible_labels=5,  # 可选：一次可见的标签数量
    required=True,
    description="选择所有适用的主题"
)

RatingQuestion

RatingQuestion 按等级收集数值评分，通常用于评估质量或相关性。

rg.RatingQuestion(
    name="quality",
    title="响应质量",
    values=[1, 2, 3, 4, 5],  # 评分等级
    required=True,
    description="对响应的质量进行评分"
)

来源： argilla/tests/unit/test_settings/test_settings_from_features.py:289-301

RankingQuestion

RankingQuestion 允许标注者按偏好顺序对多个选项进行排序，适用于偏好标注任务。

rg.RankingQuestion(
    name="ranking",
    title="响应排序",
    values=["response1", "response2", "response3"],  # 待排序的选项
    required=True,
    description="将响应从最佳到最差进行排序"
)

来源： argilla/docs/reference/argilla/settings/settings.md:91-108

TextQuestion

TextQuestion 收集标注者的自由文本响应，适用于开放式反馈或解释。

rg.TextQuestion(
    name="feedback",
    title="反馈",
    use_markdown=False,
    use_textarea=True,  # 使用更大的文本区域进行输入
    required=True,
    description="提供关于内容的反馈"
)

SpanQuestion

SpanQuestion 允许标注者在文本字段中高亮并标记特定的跨度（文本片段），适用于命名实体识别（NER）和其他跨度级标注任务。

rg.SpanQuestion(
    name="entities",
    title="命名实体",
    field="text",  # 引用一个 TextField 进行标注
    labels=["person", "organization", "location", "date"],
    visible_labels=4,  # 可选：一次可见的标签数量
    required=True,
    description="在文本中高亮并标记命名实体"
)

来源： argilla/tests/unit/test_settings/test_settings.py:86-92

配置字段与问题

字段和问题是作为数据集设置的一部分进行配置的。以下是设置方法：

Argilla · 配置字段与问题 · 图 4

来源： argilla/src/argilla/settings/_resource.py:195-229 argilla/src/argilla/datasets/_resource.py:158-169 argilla/docs/getting_started/quickstart.md:109-141

基本配置示例

以下是一个使用字段和问题设置数据集的基本示例：

import argilla as rg

# 使用字段和问题定义设置
settings = rg.Settings(
    guidelines="将评论分类为正面或负面。",
    fields=[
        rg.TextField(
            name="review",
            title="评论文本",
            use_markdown=False,
        ),
    ],
    questions=[
        rg.LabelQuestion(
            name="sentiment",
            title="这条评论的情感是什么？",
            labels=["positive", "negative"],
        )
    ],
)

# 创建并发布数据集
dataset = rg.Dataset(
    name="sentiment_analysis",
    settings=settings,
)
dataset.create()

来源： README.md:106-138 argilla/docs/getting_started/quickstart.md:109-138

添加或修改字段与问题

可以使用 add 方法从设置中添加或移除字段和问题：

# 添加新字段
settings.add(rg.ImageField(name="product_image"))

# 添加新问题
settings.add(rg.RatingQuestion(name="helpfulness", values=[1, 2, 3, 4, 5]))

# 移除字段
settings.fields.remove("product_image")

# 移除问题
settings.questions.remove("helpfulness")

来源： argilla/src/argilla/settings/_resource.py:291-326 argilla/tests/unit/test_settings/test_settings.py:227-270 argilla/docs/reference/argilla/settings/settings.md:36-58

在记录中使用字段与问题

使用数据集时，记录包含字段数据，标注者提供对问题的响应。系统还支持建议，即针对问题的预计算模型预测。

Argilla · 在记录中使用字段与问题 · 图 5

来源： argilla/src/argilla/responses.py:40-65 argilla/src/argilla/suggestions.py:27-50 argilla/docs/how_to_guides/annotate.md:84-100

记录字段数据的日志记录

向数据集添加记录的方法：

# 记录单条记录
dataset.records.log(
    records={
        "review": "I love this product, it works great!",
        "sentiment": "positive"  # 将作为建议添加
    }
)

# 记录多条记录
dataset.records.log(
    records=[
        {"review": "I love this product!", "sentiment": "positive"},
        {"review": "This product is terrible.", "sentiment": "negative"}
    ]
)

# 使用映射处理外部数据源
dataset.records.log(
    records=external_data,
    mapping={"text": "review", "label": "sentiment"}
)

来源： README.md:140-151 argilla/docs/getting_started/quickstart.md:139-142

使用响应与建议

响应是通过 UI 收集的用户标注，而建议是预计算的预测，可以指导标注者：

# 访问记录的响应
for record in dataset.records(with_responses=True):
    for response in record.responses:
        print(f"问题：{response.question_name}，值：{response.value}")

# 向记录添加建议
from argilla import Suggestion
suggestion = Suggestion(
    question_name="sentiment",
    value="positive",
    score=0.95,  # 可选的置信度分数
    agent="gpt-4"  # 可选的来源标识符
)
record.suggestions.add(suggestion)

来源： argilla/src/argilla/responses.py:40-290 argilla/src/argilla/suggestions.py:27-165 argilla/docs/how_to_guides/annotate.md:84-100

使用模板处理常见标注任务

Argilla 为常见标注任务提供了内置模板：

任务类型	模板方法	描述
分类	`Settings.for_classification(labels=["positive", "negative"])`	创建一个包含文本字段和标签问题的数据集
排序	`Settings.for_ranking()`	创建一个包含指令和响应字段的数据集，用于比较
评分	`Settings.for_rating()`	创建一个包含指令和响应字段以及评分问题的数据集

来源： argilla/docs/reference/argilla/settings/settings.md:62-137

最佳实践

使用描述性名称命名字段和问题，清晰表明其用途
提供清晰的标题和描述，以指导标注者
根据标注需求设置适当的 required 标志
对于复杂标注，考虑使用自定义字段配合 HTML 模板
使用建议通过提供模型预测来加速标注
对于文本标注，考虑Markdown 渲染是否能提高可读性
对于长文本，使用跨度问题而非对整个文本应用标签

来源： argilla/docs/how_to_guides/annotate.md:40-69 argilla/docs/how_to_guides/custom_fields.md:26-57

高级功能

带模板的自定义字段

对于复杂的可视化需求，CustomField 允许您创建自定义的 HTML/CSS/JavaScript 模板：

template = """
<style>
#container {
    display: flex;
    gap: 10px;
}
.column {
    flex: 1;
}
</style>
<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_comparison",
    template=template,
)

来源： argilla/docs/how_to_guides/custom_fields.md:36-66 argilla/docs/how_to_guides/custom_fields.md:106-152

从 Hugging Face Hub 导入

从 Hugging Face Hub 导入数据集时，Argilla 可以自动检测并映射字段和问题：

# 使用自动字段/问题检测导入
dataset = rg.Dataset.from_hub(
    repo_id="stanfordnlp/imdb",
    settings="auto"
)

# 使用自定义字段/问题映射导入
dataset = rg.Dataset.from_hub(
    repo_id="stanfordnlp/imdb",
    settings=rg.Settings.from_hub(
        repo_id="stanfordnlp/imdb",
        feature_mapping={"text": "field", "label": "question"}
    )
)

来源：

argilla/docs/getting_started/quickstart.md:85-100
argilla/src/argilla/settings/_io/_hub.py:203-300
argilla/src/argilla/datasets/_io/_hub.py:114-211