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

问题项与字段（中文译文）

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

翻译时间：2026-05-27T08:44:45.029Z

翻译模型：deepseek-chat

原文字符数：22882

项目：Argilla (argilla)

---

问题与字段

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

• 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
• 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/distribution.md
• argilla/docs/how_to_guides/query.md
• argilla/docs/index.md
• argilla/docs/reference/argilla/client.md
• argilla/docs/reference/argilla/search.md
• argilla/docs/reference/argilla/settings/settings.md
• argilla/docs/reference/argilla/settings/task_distribution.md
• argilla/src/argilla/_exceptions/__init__.py
• argilla/src/argilla/_exceptions/_hub.py
• argilla/src/argilla/_exceptions/_responses.py
• argilla/src/argilla/_exceptions/_suggestions.py
• argilla/src/argilla/_models/_dataset_progress.py
• argilla/src/argilla/datasets/_io/_disk.py
• argilla/src/argilla/datasets/_io/_hub.py
• argilla/src/argilla/datasets/_resource.py
• argilla/src/argilla/responses.py
• argilla/src/argilla/settings/_common.py
• argilla/src/argilla/settings/_field.py
• argilla/src/argilla/settings/_io/_hub.py
• argilla/src/argilla/settings/_question.py
• argilla/src/argilla/settings/_resource.py
• argilla/src/argilla/settings/_task_distribution.py
• argilla/src/argilla/suggestions.py
• argilla/tests/integration/test_create_datasets.py
• argilla/tests/integration/test_import_features.py
• argilla/tests/integration/test_update_dataset_settings.py
• argilla/tests/unit/test_resources/test_datasets.py
• argilla/tests/unit/test_resources/test_responses.py
• argilla/tests/unit/test_settings/test_settings.py
• argilla/tests/unit/test_settings/test_settings_from_features.py
• argilla/tests/unit/test_settings/test_settings_mapping_record_ingestion.py

本文档提供了关于问题与字段的说明，它们是 Argilla 数据标注系统的核心构建块。问题代表用户执行的标注任务，而字段代表被标注的数据。两者共同定义了数据在 Argilla UI 中的展示方式以及标注的收集方式。

关于问题与字段如何融入更广泛的数据集结构，请参阅数据集与设置。关于标注如何存储和处理，请参阅记录与响应。

问题与字段概述

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

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

flowchart TD
    subgraph "数据集设置"
        direction TB
        F["字段"] --> |"展示内容"| UI
        Q["问题"] --> |"标注内容"| UI
        G["指南"]
    end

    subgraph "标注界面"
        direction TB
        UI["用户界面"]
        UI --> |"标注"| R["响应"]
        UI --> |"显示"| S["建议"]
    end

    subgraph "数据"
        direction TB
        R["响应"] --> |"与记录一起存储"| REC["记录"]
        S["建议"] --> |"与记录一起存储"| REC
    end

来源：

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

字段类型

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

classDiagram
    class FieldBase {
        <<抽象>>
        +name: string
        +title: string
        +required: boolean
        +description: string
        +validate()
        +create()
        +update()
        +delete()
    }

    class TextField {
        +use_markdown: boolean
    }

    class ImageField {
    }

    class ChatField {
        +use_markdown: boolean
    }

    class CustomField {
        +template: string
        +advanced_mode: boolean
    }

    FieldBase <|-- TextField
    FieldBase <|-- ImageField
    FieldBase <|-- ChatField
    FieldBase <|-- CustomField

来源：

• 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 提供了几种内置问题类型，用于收集不同类型的标注：

classDiagram
    class QuestionBase {
        <<抽象>>
        +name: string
        +title: string
        +required: boolean
        +description: string
        +validate()
        +create()
        +update()
        +delete()
    }

    class LabelQuestion {
        +labels: List[string]
        +visible_labels: int
    }

    class MultiLabelQuestion {
        +labels: List[string]
        +visible_labels: int
    }

    class RatingQuestion {
        +values: List[number]
    }

    class RankingQuestion {
        +values: List[string]
    }

    class TextQuestion {
        +use_markdown: boolean
        +use_textarea: boolean
    }

    class SpanQuestion {
        +field: string
        +labels: List[string]
        +visible_labels: int
    }

    QuestionBase <|-- LabelQuestion
    QuestionBase <|-- MultiLabelQuestion
    QuestionBase <|-- RatingQuestion
    QuestionBase <|-- RankingQuestion
    QuestionBase <|-- TextQuestion
    QuestionBase <|-- SpanQuestion

来源：

• 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

配置字段与问题

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

flowchart LR
    subgraph "代码设置流程"
        direction LR
        F["定义字段"] --> S["创建设置"]
        Q["定义问题"] --> S
        S --> D["创建数据集"]
        D --> C["dataset.create()"]
    end

    subgraph "API 交互流程"
        direction TB
        C --> |"POST /api/v1/datasets"| API["Argilla 服务器"]
        API --> |"返回数据集 ID"| D1["数据集已创建"]
        D1 --> |"POST 设置"| API
        API --> |"发布数据集"| D2["数据集已发布"]
    end

来源：

• 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

在记录中使用字段与问题

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

flowchart TD
    subgraph "记录结构"
        direction TB
        R["记录"]
        R --> F["字段（待展示的数据）"]
        R --> M["元数据（附加信息）"]
        R --> V["向量（嵌入向量）"]
        R --> RS["响应（人工标注）"]
        R --> S["建议（模型预测）"]
    end

    subgraph "标注流程"
        direction LR
        F --> |"展示给"| A["标注者"]
        S --> |"建议给"| A
        A --> |"创建"| RS
    end

来源：

• 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