Argilla Questions 详解用rg.Question为数据集定义高质量反馈标注方案【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argillaArgilla 通过Questions问题来收集反馈无论是人工标注者还是模型都通过回答这些问题来为记录Record打上标签、评分、排序或撰写文本。本篇技术指南以 argilla/docs/reference/argilla/settings/questions.md 为核心结合 SDK 源码与单元测试系统讲解 Argilla 六种问题类型LabelQuestion、MultiLabelQuestion、RankingQuestion、TextQuestion、RatingQuestion、SpanQuestion的实例化方式、参数语义、底层模型与校验逻辑并给出与rg.Settings、rg.Dataset、rg.Response组合使用的完整实战示例。读完本文你将能够为任意数据标注/RLHF 场景设计一套完整、可校验、可落地的问答式标注方案。Questions 在 Argilla 中的作用在 Argilla 的数据模型中一个数据集Dataset的Settings由四类要素构成fields字段、questions问题、vectors向量与metadata元数据其中questions 定义了标注者或模型需要回答什么。其定位可以从 Settings 源码 的构造函数中直观看到settings rg.Settings( fields..., questions..., vectors..., metadata..., )一个典型的最小可用数据集至少需要同时包含fields和questions——Settings._validate_empty_settings明确要求两者都非空否则抛出SettingsError(Fields and questions are required)见 argilla/src/argilla/settings/_resource.py。同时Settings._validate_duplicate_names保证所有属性字段、问题、向量、元数据的名称在数据集中全局唯一argilla/src/argilla/settings/_resource.py。在服务端问题类型由 argilla-server/src/argilla_server/enums.py 中的QuestionType枚举统一定义共六种与 SDK 的六个类一一对应服务端枚举值SDK 类反馈形态textTextQuestion自由文本ratingRatingQuestion从 0-10 的整数序列中选一个分值label_selectionLabelQuestion从多个标签中单选一个multi_label_selectionMultiLabelQuestion从多个标签中多选若干个rankingRankingQuestion对一组选项进行排序spanSpanQuestion在文本字段中划取片段并赋予标签SDK 侧的question_from_model工厂函数正是根据model.type将这六种类型映射到对应类见 argilla/src/argilla/settings/_question.py客户端在从服务端拉取数据集配置时会走这条反序列化路径。定义第一个 LabelQuestion按照原文档的第一个示例最简单的用法是实例化LabelQuestion并放入Settingsimport argilla as rg label_question rg.LabelQuestion(namelabel, labels[positive, negative]) settings rg.Settings( fields[ rg.TextField(nametext), ], questions[ label_question, ], )随后将settings传给Dataset并调用create()即可在服务端创建数据集dataset rg.Dataset(namemy_dataset, settingssettings) dataset.create()LabelQuestion 参数语义从 LabelQuestion 实现 可以看到它的完整参数签名rg.LabelQuestion( name: str, labels: Union[List[str], Dict[str, str]], title: Optional[str] None, description: Optional[str] None, required: bool True, visible_labels: Optional[int] None, client: Optional[Argilla] None, )各参数说明如下name问题的唯一标识名用于在 SDK/API 中引用该问题如record.responses[label]也是Settings中全局唯一性校验的对象labels可选项列表。可以是字符串列表[positive, negative]也可以是内部值 → UI 显示文本的字典{positive: 正向, negative: 负向}。底层通过_render_values_as_options将二者统一转换为[{value: ..., text: ...}]的 options 结构见 argilla/src/argilla/settings/_question.pytitleUI 中显示的问题标题未指定时默认取name由 QuestionModel._title_default 实现descriptionUI 中显示的问题描述用于给标注者解释作答要求required该问题是否必答默认为True。注意至少一个问题必须是必答的这一约束visible_labelsUI 中一次展示的标签数量超出部分折叠。None表示全部展示。底层模型LabelQuestionSettings.visible_options有最小值为 3 的约束ge_MIN_VISIBLE_OPTIONS见 argilla/src/argilla/_models/_settings/_questions.py。需要留意的是底层模型的两条自动校验逻辑argilla/src/argilla/_models/_settings/_questions.py标签唯一性options中的value不允许重复重复会抛出ValueError(All labels must be unique)visible_options 自动补全当visible_options为None且选项数 ≥ 3 时模型会自动将其设置为全部选项数。也就是说只要标签不少于 3 个展示全部是默认行为。组合不同类型的问题Questions 的价值在于按需自由组合。原文档给出了一个标签 文本的组合示例用于同时收集分类结果与解释性文本label_question rg.LabelQuestion(namelabel, labels[positive, negative]) text_question rg.TextQuestion(nameresponse) settings rg.Settings( fields[ rg.TextField(nametext), ], questions[ label_question, text_question, ], ) dataset rg.Dataset( namemy_dataset, settingssettings, )这种组合能力来自Settings.questions属性它是一个SettingsProperties序列容器支持按名称字符串、UUID 或整数下标访问也支持add()/remove()动态增删见 argilla/src/argilla/settings/_resource.py。例如在创建数据集之前动态追加一个问题settings.add(rg.TextQuestion(namenotes, use_markdownTrue)) # 或直接对 questions 容器操作 settings.questions.add(rg.RatingQuestion(namedifficulty, values[1, 2, 3])) settings.questions.remove(notes)当settings.add()遇到同名属性时会默认覆盖overrideTrue并给出警告若传overrideFalse则抛出SettingsErrorargilla/src/argilla/settings/_resource.py。需要说明的是Settings一旦用于在服务端创建数据集其配置便固定下来服务端校验器也明确禁止为已发布published的数据集创建新问题见 argilla-server/src/argilla_server/validators/questions.py。因此问题设计应在数据集创建前完成。六种问题类型逐一详解TextQuestion自由文本回答TextQuestion让标注者输入任意文本适合开放性问题、解释、纠错等场景实现见 argilla/src/argilla/settings/_question.pyrg.TextQuestion( nameresponse, title你的回答, # UI 标题默认取 name description请用一句话总结该文本的情感倾向, requiredTrue, use_markdownFalse, )其中use_markdown决定 UI 是否将回答按 Markdown 渲染置为True后回答支持 Markdown 排版、LaTeX 公式以及嵌入多媒体内容与 PDF。该选项序列化为TextQuestionSettings.use_markdown默认为Falseargilla/src/argilla/_models/_settings/_questions.py。从源码看use_markdown与rg.TextField的use_markdown是同一类渲染能力的复用。RatingQuestion评分RatingQuestion让标注者从连续的整数序列中选择一个分值适用于打分/评级类任务实现见 argilla/src/argilla/settings/_question.pyrg.RatingQuestion( namequality, values[1, 2, 3, 4, 5], title质量评分, requiredTrue, )关键约束是values必须是[0, 10]范围内的整数列表且底层同样校验值的唯一性argilla/src/argilla/_models/_settings/_questions.py。回答时标注者从这些离散值中选择其一。RankingQuestion排序RankingQuestion让标注者对一组选项通常是多个模型输出进行排序是 RLHF 数据采集的核心问题类型实现见 argilla/src/argilla/settings/_question.pyrg.RankingQuestion( namepreference, values[response_a, response_b, response_c], )values同样支持列表或值 → 显示文本的字典两种形式且必须是唯一的argilla/src/argilla/_models/_settings/_questions.py。排序结果在回答中以有序列表的形式存储例如[response_b, response_a, response_c]表示首选response_b。MultiLabelQuestion多标签MultiLabelQuestion继承自LabelQuestion允许标注者同时选择多个标签适合多标签分类场景实现见 argilla/src/argilla/settings/_question.pyrg.MultiLabelQuestion( nametopics, labels[科技, 财经, 体育, 娱乐, 健康], visible_labels3, labels_ordernatural, # natural 或 suggestion )它在LabelQuestion基础上新增了labels_order参数natural默认按声明顺序展示标签suggestion优先展示与模型建议Suggestion关联的标签并按建议分数排序若有。该值序列化为MultiLabelQuestionSettings.options_orderargilla/src/argilla/_models/_settings/_questions.py。SpanQuestion文本片段标注SpanQuestion让标注者在指定的文本字段中划取一段文本并赋予标签是命名实体识别NER、信息抽取类任务的核心实现见 argilla/src/argilla/settings/_question.pyrg.SpanQuestion( nameentities, fieldtext, # 必须指向数据集中的一个文本字段 labels[PER, ORG, LOC, MISC], allow_overlappingFalse, # 是否允许片段重叠 visible_labelsNone, )它独有的参数field该 span 问题作用的目标文本字段名。底层SpanQuestionSettings.field默认为None服务端校验器会严格检查该字段确实存在于数据集字段列表中否则返回UnprocessableEntityError见 argilla-server/src/argilla_server/validators/questions.pyallow_overlapping是否允许标注片段相互重叠默认Falsevisible_labels同LabelQuestionUI 中一次展示的标签数最小值为 3None表示全部选项数 ≥ 3 时自动补全见 argilla/src/argilla/_models/_settings/_questions.py。另外服务端还规定同一个字段只能被一个 span 问题使用。若两个 span 问题指向同一字段服务端会拒绝创建argilla-server/src/argilla_server/validators/questions.py。回答问题Response 与各问题类型的值格式定义好问题后用户或模型通过Response回答作答。原文档特别提示向记录添加带回答的数据时请参考 rg.Response 类文档。该文档明确了一个重要区分Response通常由用户在 UI 中创建或从数据源作为标签消费而Suggestion通常来自模型预测。不同问题类型对应的rg.Response值格式如下完整示例见 argilla/docs/reference/argilla/records/responses.md问题类型value格式示例LabelQuestion单个字符串positiveMultiLabelQuestion字符串列表[positive, negative]RankingQuestion有序字符串列表[1, 3, 2]RatingQuestion整数4SpanQuestion片段字典列表[{start: 0, end: 9, label: MISC}]TextQuestion字符串value写入记录的基本方式dataset.records.log( [ rg.Record( fields{text: Hello World, how are you?}, responses[rg.Response(label, negative, user_iduser.id)], ) ] )也可以直接用字典形式键为问题名加.response后缀dataset.records.log( [ { text: Hello World, how are you?, label.response: negative, }, ] )读取时通过问题名作为记录属性访问for record in dataset.records: for response in record.responses[label]: print(response.value) print(response.user_id)底层机制从 SDK 对象到服务端 API理解 Questions 的底层流转有助于排查问题。一次数据集创建过程中Settings.create()会依次调用fields._create()、questions._create()、vectors._create()、metadata._create()argilla/src/argilla/settings/_resource.py其中每个问题通过 QuestionsAPI.create 发往服务端POST /api/v1/datasets/{dataset_id}/questions Body: QuestionModel.model_dump()序列化的核心是QuestionModelargilla/src/argilla/_models/_settings/_questions.py其结构为{ name: str, # 问题名 settings: { # 按 type 区分的配置负载 type: label_selection | multi_label_selection | ranking | text | rating | span, # 不同类型的字段options / visible_options / use_markdown / values / field ... }, title: str, # 默认取 name description: Optional[str], required: bool, # 默认 True dataset_id: Optional[UUID], }其中settings是一个以type为判别字段的联合类型Annotated[Union[...], Field(discriminatortype)]保证了一种类型只有一种合法配置结构argilla/src/argilla/_models/_settings/_questions.py。服务端QuestionType枚举与 SDK 完全对齐argilla-server/src/argilla_server/enums.py校验器进一步约束span 问题的field必须存在于数据集中、且不能被两个 span 问题共享、已发布数据集不允许再增删问题argilla-server/src/argilla_server/validators/questions.py。单元测试覆盖了六种问题类的实例化与属性读写例如 argilla/tests/unit/test_settings/test_settings_questions.py 验证了LabelQuestion支持列表与字典两种标签形式、visible_labels透传、labels_ordersuggestion等行为可作为自定义问题配置的回归参考。快速选型指南标注需求推荐问题类型关键参数二分类 / 多分类单选LabelQuestionlabels、visible_labels多标签分类MultiLabelQuestionlabels、labels_order、visible_labels偏好排序RLHFRankingQuestionvalues质量评分 / 打分RatingQuestionvalues整数0-10自由文本 / 解释说明TextQuestionuse_markdown命名实体 / 片段抽取SpanQuestionfield、labels、allow_overlapping小结本文以 questions.md 为主线完整覆盖了 Argilla 六种问题类型的定义、参数、底层模型与服务端校验并结合 rg.Response 说明了各类型的回答格式。实践要点可归纳为三点问题设计先行数据集一旦发布published便不能再增删问题因此务必在dataset.create()之前通过rg.Settings一次性定义完整的问题方案名称全局唯一name既是 API 引用键也是 UI 标题未指定title时默认来源同时在字段、问题、向量、元数据之间全局唯一组合而非单选将LabelQuestion与TextQuestion、RatingQuestion与TextQuestion等自由组合可以采集远超单一题型的丰富反馈为后续微调、评测与 RLHF 提供高质量标注数据。【免费下载链接】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），仅供参考
