序列元数据模式

每个序列都带有两类彼此独立的元数据：

技术有效性。 这段录制是否可用？Avala 根据验收标准和质量目标报告它。参见下文的“技术有效性”一节。
行为结果。 人或机器人做了什么？任务是否成功？Avala 将其存储为该序列的结果标签。

一个序列可以在技术上有效，同时展示一次失败。失败的序列往往最有用。两个维度保持分开，因此筛选干净数据时不会丢掉有用的失败，筛选成功序列时也不会掩盖损坏的传感器。

结果标签

每个序列最多有一个当前结果标签。每次写入都会记录一个新版本。较早的版本仍可在标签历史中读取。

示例

下面是一次带有滑落和恢复的人类示范的标签，即 GET .../sequences/<sequence-uid>/outcome/ 返回的内容：

{
  "uid": "<outcome-uid>",
  "sequence_uid": "<sequence-uid>",
  "version": 2,
  "is_current": true,
  "outcome": "mistake_and_recovery",
  "progress": 1.0,
  "quality": 4,
  "speed": 3,
  "subtasks": [
    { "label": "Load the plate into the lower rack", "start_ts": 0.0, "end_ts": 19.8, "outcome": "mistake_and_recovery" },
    { "label": "Pull out the lower rack", "start_ts": 0.0, "end_ts": 6.2, "outcome": "expert_success" },
    { "label": "Place the wet plate in a free slot", "start_ts": 6.2, "end_ts": 19.8, "outcome": "mistake_and_recovery" }
  ],
  "hand_actions": {
    "left": [
      { "start_ts": 0.0, "end_ts": 6.2, "action": "pulling the lower rack out by its front edge", "object": "dishwasher rack", "verb": "pull", "contact": true },
      { "start_ts": 6.2, "end_ts": 19.8, "action": "holding the rack steady", "object": "dishwasher rack", "verb": "hold", "contact": true }
    ],
    "right": [
      { "start_ts": 6.2, "end_ts": 9.1, "action": "carrying the wet plate to the rack", "object": "plate", "verb": "carry", "contact": true },
      { "start_ts": 9.1, "end_ts": 10.4, "action": "the plate slips out of the grasp", "object": "plate", "verb": null, "contact": false },
      { "start_ts": 10.4, "end_ts": 14.7, "action": "regrasping the plate by its rim", "object": "plate", "verb": "grasp", "contact": true },
      { "start_ts": 14.7, "end_ts": 19.8, "action": "placing the plate in a free slot", "object": "plate", "verb": "place", "contact": true }
    ]
  },
  "mistake_type": "slip_during_place",
  "recovery_type": "regrasp",
  "failure_stage": "place",
  "autonomy_level": "human_demonstration",
  "model_version": "",
  "evaluation_membership": "train",
  "leakage_groups": {
    "location": "loc_8f2a",
    "object": "obj_set_31",
    "mechanism": "dishwasher_pull_rack_v2",
    "operator": "op_5c1e",
    "environment_family": "kitchen_galley"
  },
  "source": "human",
  "source_metadata": {},
  "labeled_by": "<user-uid>",
  "confidence": null,
  "created_at": "2026-09-30T17:42:11.204000Z",
  "updated_at": "2026-09-30T17:42:11.204000Z"
}

这些值用于说明标签的结构。它们不描述真实的交付。

字段

所有时间戳都是距序列开始的秒数。

字段	类型	含义
`uid`	string	此标签版本的 ID。只读。
`sequence_uid`	string	标签所属的序列。只读。
`version`	integer	标签版本，从 1 开始。每次写入加一。只读。
`is_current`	boolean	当前版本为 `true`。只读。
`outcome`	string	行为结果。必填。参见下文的“结果值”。
`progress`	number or null	任务进度，从 0 到 1。
`quality`	integer or null	执行质量，从 1 到 5。
`speed`	integer or null	执行速度，从 1 到 5。
`subtasks`	list	带标签的时间范围。参见下文的“子任务”。
`hand_actions`	object	按手划分的动作流：`left` 和 `right`。参见下文的“手部动作”。
`mistake_type`	string	您为错误类型设定的标记。最多 128 个字符。未设置时为空。
`recovery_type`	string	您为恢复类型设定的标记。最多 128 个字符。未设置时为空。
`failure_stage`	string	您为失败发生的阶段设定的标记。最多 128 个字符。未设置时为空。
`autonomy_level`	string	由谁控制。参见下文的“自主级别”。未设置时为空。
`model_version`	string	驱动机器人的策略或模型版本。最多 255 个字符。人类示范时为空。
`evaluation_membership`	string	`train`、`held_out_eval` 或 `none`。未设置时为空。参见下文的“评估成员资格”。
`leakage_groups`	object	用于保持数据划分干净的组 ID。参见下文的“泄漏组”。
`source`	string	标签的写入方：`human`、`model` 或 `imported`。默认为 `human`。
`source_metadata`	object	导入来源信息。参见下文的“来源元数据”。
`labeled_by`	string or null	写入该版本的用户的 UID。仅返回给可以编辑该数据集的调用方。只读。
`confidence`	number or null	模型置信度，从 0 到 1。仅当 `source` 为 `model` 时接受。
`created_at`, `updated_at`	string	该版本的时间戳。只读。

mistake_type、recovery_type 和 failure_stage 是自由文本。请使用计划的失败分类体系中的标记，以便序列能清晰地分组。

结果值

结果	含义
`expert_success`	任务完成。执行流畅，达到专家速度。
`slow_success`	任务完成。执行正确，明显慢于专家速度。
`partial_success`	任务的一部分完成。未达到最终目标状态。
`mistake_and_recovery`	出现错误，例如滑落、抓空或放错位置。执行者在没有外部帮助的情况下恢复并完成任务。
`intervention`	有人介入纠正或完成任务。
`unsafe`	序列中包含不安全的动作或状态。
`aborted`	尝试在任务完成前停止，且没有恢复。
`failure`	尝试结束，任务未达成。
`novel_strategy`	任务以一种有效但不同于常用策略的方式完成。
`inefficient_strategy`	任务完成，但有可避免的多余动作、重复尝试或绕路。

每个子任务可以带有取自同一列表的自身结果。

自主级别

值	含义
`human_demonstration`	由人执行任务。
`teleoperation`	由人远程操控机器人。
`autonomous`	机器人按其策略运行。
`shared_autonomy`	策略与人共同控制。
`intervention`	在序列进行中，人从策略手中接管控制。

子任务

每个子任务的形式为 {label, start_ts, end_ts, outcome}。

字段	规则
`label`	子任务的自然语言描述。必填。1 到 500 个字符。
`start_ts`, `end_ts`	有限数值，大于或等于 0。`end_ts` 不小于 `start_ts`。
`outcome`	一个结果值，或 `null`。

一个标签最多包含 256 个子任务。列表必须按 start_ts 排序。任意两个子任务要么互不相交，要么一个完全包含另一个，例如一个阶段及其步骤。首尾相接视为不相交。部分重叠会被拒绝。当两个子任务同时开始时，先列出外层的那个。

手部动作

hand_actions 包含两个独立的流：left 和 right。每一项描述一只手在一个时间范围内所做的事。

字段	规则
`start_ts`, `end_ts`	有限数值，大于或等于 0。`end_ts` 不小于 `start_ts`。
`action`	动作的自然语言描述。必填。1 到 500 个字符。
`object`	手所操作的物体。可选。最多 255 个字符。
`verb`	描述该动作的简短动词。可选。最多 64 个字符。
`contact`	手接触物体时为 `true`，未接触时为 `false`，未知时为 `null`。只接受 JSON 布尔值。

在同一只手内，各项按 start_ts 排序，且不得重叠。一项在上一项结束时或之后开始。首尾相接没有问题。
两只手之间可以自由重叠。
每只手最多 3,600 项，即按每秒一个标签计算的一小时。
left 和 right 是仅有的两个键。两者都可以省略。省略的手存储为空列表。
空的 object 或 verb 存储为 null。每个存储的项都包含全部六个字段。

序列时长

当 Avala 知道序列的时长时，每个子任务的 end_ts 和每个手部动作的 end_ts 都不得超过时长加 1 秒。多出的这一秒是为按每秒一个写入的标签留出的余量。当序列恰好有一个已提取且记录了长度的 MCAP 文件时，Avala 知道其时长。对于其他序列，会跳过此项检查。

评估成员资格

evaluation_membership 把序列放入一个划分：

值	含义
`train`	该序列可用于训练。
`held_out_eval`	该序列属于一个留出评估集。请将其排除在训练之外。
`none`	该序列不属于任何一个划分。

Avala 为每个评估组中的序列设置 held_out_eval。这些序列从不出现在训练发布版本中。参见评估。

泄漏组

泄漏组防止近似重复的数据同时落在训练集和评估集两侧。leakage_groups 接受以下键，每个键对应一个最多 255 个字符的组 ID：

键	归为一组的序列共享
`location`	同一个住所、场地或房间。
`object`	同一套实物物体。
`mechanism`	同一台电器或同一个机构单元。
`operator`	同一名采集员或遥操作员。
`environment_family`	同类环境和布局，例如狭长型厨房。

其他任何键都会被拒绝。每个键都是可选的。 Avala 构建评估组时，确保评估组中的任何组值都不会出现在任何训练发布版本中。您可以用同样的方式划分自己的数据：按组留出，绝不按随机序列留出。Avala 的组 ID 是假名化的，因此您可以分组和划分，而无需知道涉及的人员或地点。

来源元数据

source_metadata 记录导入的标签来自哪里，例如 {"importer": "...", "run_id": "...", "task": "...", "log_path": "..."}。

它是一个扁平对象，最多 20 个键。
每个键为 1 到 64 个字符。
每个值是最多 512 个字符的字符串、有限数值或布尔值。
嵌套对象、列表和 null 值会被拒绝。

写入方式

一次写入会整体替换当前标签，并记录一个新版本。您省略的任何可选字段都存储为未设置，不会从上一个版本复制。
写入需要数据集的编辑权限。读取所需的权限与读取该序列相同，包括公开数据集。
除非 source 为 model，否则 confidence 会被拒绝。
读取没有标签的序列会返回 404。

技术有效性

技术有效性不属于结果标签。Avala 根据验收引擎和质量目标报告它，它没有自己的 JSON 模式。 验收标准。 采集活动中的每次采集都会得到一个机器判定：accept、quarantine 或 reject。判定依据以下标准：

标准	检查内容
`capture_health`	MCAP 文件通过校验，且采集活动要求的通道都存在。
`frame_rate`	摄像头帧率在整个片段中保持稳定，没有持续的崩溃。
`completeness`	时长接近采集活动要求的时长。
`framing`	在检测器观察的时间里，手可见的时间足够长。
`shake`	在片段的大部分时间里，摄像头没有抖动。

每项标准报告 pass、fail、insufficient_evidence 或 skipped。未通过的标准会记录一个原因代码，例如 acceptance_frame_rate_drop 或 hands_not_visible。随后由审核员确认或推翻该判定。原因代码列在验收小时中。使用 MCP 工具读取验收结果：get_result_acceptance 用于单次采集，get_campaign_acceptance_summary 用于一个采集活动。list_capture_submissions 包含每次采集的机器验收摘要。 质量目标。 项目可以为质量指标设定阈值，例如验收率、拒收率和问题率。当某个指标越过阈值时，Avala 会发出警报。使用 MCP 工具 list_quality_targets 读取它们。不属于机器标准的计划检查，例如标定、同意和时间戳同步，会作为拒收原因在覆盖报告中报告。参见验收小时。

读取和写入结果标签

REST 端点位于 https://api.avala.ai/api/v1 之下：

方法和路径	作用
`GET /datasets/{owner}/{slug}/sequences/{sequence_uid}/outcome/`	一个序列的当前标签。未标注时返回 `404`。
`PUT /datasets/{owner}/{slug}/sequences/{sequence_uid}/outcome/`	记录一个新的当前标签。
`GET /datasets/{owner}/{slug}/sequences/{sequence_uid}/outcome/history/`	标签的每个版本，最新的在前。
`GET /datasets/{owner}/{slug}/sequence-outcomes/`	数据集中的当前标签，分页返回。

数据集列表接受筛选条件 outcome、evaluation_membership、source 和 autonomy_level。每个条件接受一个值或逗号分隔的列表，序列匹配列表中的任意一个值即可。model_version 精确匹配一个版本。未知的筛选值返回 400。序列列表 GET /datasets/{owner}/{slug}/sequences/ 以同样的形式接受 outcome 和 evaluation_membership，返回当前标签匹配的序列。

写入标签

curl -X PUT \
  "https://api.avala.ai/api/v1/datasets/your-org/kitchen-rollouts/sequences/<sequence-uid>/outcome/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "failure",
    "progress": 0.4,
    "subtasks": [
      { "label": "Place the plate in the lower rack", "start_ts": 0.0, "end_ts": 21.5, "outcome": "failure" }
    ],
    "mistake_type": "slip_during_place",
    "failure_stage": "place",
    "autonomy_level": "autonomous",
    "model_version": "your-policy@2026-09-20",
    "evaluation_membership": "held_out_eval",
    "source": "imported",
    "source_metadata": { "importer": "your-eval-harness", "run_id": "r42", "task": "load_dishwasher" }
  }'

from avala import Client

client = Client()  # reads AVALA_API_KEY

label = client.sequence_outcomes.set(
    "your-org",
    "kitchen-rollouts",
    "<sequence-uid>",
    outcome="failure",
    progress=0.4,
    subtasks=[
        {"label": "Place the plate in the lower rack", "start_ts": 0.0, "end_ts": 21.5, "outcome": "failure"},
    ],
    mistake_type="slip_during_place",
    failure_stage="place",
    autonomy_level="autonomous",
    model_version="your-policy@2026-09-20",
    evaluation_membership="held_out_eval",
    source="imported",
    source_metadata={"importer": "your-eval-harness", "run_id": "r42", "task": "load_dishwasher"},
)
print(label.version, label.outcome)

import Avala from "@avala-ai/sdk";

const avala = new Avala(); // reads AVALA_API_KEY

const label = await avala.sequenceOutcomes.set("your-org", "kitchen-rollouts", "<sequence-uid>", {
  outcome: "failure",
  progress: 0.4,
  subtasks: [{ label: "Place the plate in the lower rack", startTs: 0.0, endTs: 21.5, outcome: "failure" }],
  mistakeType: "slip_during_place",
  failureStage: "place",
  autonomyLevel: "autonomous",
  modelVersion: "your-policy@2026-09-20",
  evaluationMembership: "held_out_eval",
  source: "imported",
  sourceMetadata: { importer: "your-eval-harness", run_id: "r42", task: "load_dishwasher" },
});
console.log(label.version, label.outcome);

avala sequence-outcomes set your-org kitchen-rollouts <sequence-uid> \
  --outcome failure \
  --progress 0.4 \
  --subtasks-file subtasks.json \
  --mistake-type slip_during_place \
  --failure-stage place \
  --autonomy-level autonomous \
  --model-version your-policy@2026-09-20 \
  --evaluation-membership held_out_eval \
  --source imported \
  --source-metadata '{"importer": "your-eval-harness", "run_id": "r42", "task": "load_dishwasher"}'

TypeScript SDK 使用 camelCase 选项名，并发送 API 的 snake_case 字段。sourceMetadata 中的键按原样发送。在 CLI 中，--hand-actions-file 接受一个内容为 {"left": [...], "right": [...]} 的 JSON 文件，--leakage-group KEY=ID 可以重复使用。

读取标签

# Current label of one sequence
curl "https://api.avala.ai/api/v1/datasets/your-org/kitchen-rollouts/sequences/<sequence-uid>/outcome/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

# Every version, newest first
curl "https://api.avala.ai/api/v1/datasets/your-org/kitchen-rollouts/sequences/<sequence-uid>/outcome/history/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

# Failed or aborted held-out sequences
curl "https://api.avala.ai/api/v1/datasets/your-org/kitchen-rollouts/sequence-outcomes/?outcome=failure,aborted&evaluation_membership=held_out_eval" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

# The sequences themselves, filtered by their current label
curl "https://api.avala.ai/api/v1/datasets/your-org/kitchen-rollouts/sequences/?outcome=mistake_and_recovery,intervention" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

from avala import Client

client = Client()

label = client.sequence_outcomes.get("your-org", "kitchen-rollouts", "<sequence-uid>")
versions = client.sequence_outcomes.history("your-org", "kitchen-rollouts", "<sequence-uid>")

page = client.sequence_outcomes.list(
    "your-org",
    "kitchen-rollouts",
    outcome=["failure", "aborted"],
    evaluation_membership="held_out_eval",
    model_version="your-policy@2026-09-20",
)
for item in page:
    print(item.sequence_uid, item.outcome, item.progress)

import Avala from "@avala-ai/sdk";

const avala = new Avala();

const label = await avala.sequenceOutcomes.get("your-org", "kitchen-rollouts", "<sequence-uid>");
const versions = await avala.sequenceOutcomes.history("your-org", "kitchen-rollouts", "<sequence-uid>");

const page = await avala.sequenceOutcomes.list("your-org", "kitchen-rollouts", {
  outcome: ["failure", "aborted"],
  evaluationMembership: "held_out_eval",
  modelVersion: "your-policy@2026-09-20",
});
for (const item of page.items) {
  console.log(item.sequenceUid, item.outcome, item.progress);
}

avala sequence-outcomes get your-org kitchen-rollouts <sequence-uid>
avala sequence-outcomes history your-org kitchen-rollouts <sequence-uid>
avala sequence-outcomes list your-org kitchen-rollouts \
  --outcome failure,aborted \
  --evaluation-membership held_out_eval

数据集列表每页最多返回 100 个标签。传入上一页的 cursor 即可继续读取。

通过 MCP 服务器读取标签

MCP 服务器读取结果标签，但不写入。

get_sequence_outcome 接受 owner、slug 和 sequenceUid，返回当前标签。
list_sequence_outcomes 接受 owner 和 slug，以及筛选条件 outcome、evaluationMembership、source、autonomyLevel 和 modelVersion，还有 limit 和 cursor。

两个工具默认返回简短形式。传入 detail: "full" 可包含子任务、手部动作、错误和恢复标记、泄漏组、来源元数据和标注者。连接方法参见与 AI 一起使用 Avala。

通过 LeRobot 导出结果标签

LeRobot 导出器可以把每个序列的当前结果标签写在数据集旁边。一个 Avala 序列成为一个 LeRobot episode。

avala lerobot export your-org/kitchen-rollouts \
  --repo-id your-hf-user/kitchen-rollouts \
  --output ./lerobot-out \
  --include-outcomes

from avala import Client
from avala.lerobot import export_dataset

export_dataset(
    Client(),
    "your-org",
    "kitchen-rollouts",
    repo_id="your-hf-user/kitchen-rollouts",
    output_dir="./lerobot-out",
    include_outcomes=True,
)

标签写入 meta/avala_sequence_outcomes.jsonl：每行一个 JSON 对象，每个已保存的 LeRobot episode 对应一行。LeRobot 自身的 episode 表没有存放这些元数据的位置，因此它是一个单独的文件。每行包含以下键：

键	值
`episode_index`	LeRobot episode 索引。
`avala_sequence_uid`	该 episode 所来自的 Avala 序列。
`outcome`	结果值；序列没有标签时为 `null`。
`outcome_version`	被导出的标签版本。
`progress`, `quality`, `speed`	与标签中相同。
`subtasks`, `hand_actions`	与标签中相同。时间戳是距 episode 开始的秒数。
`mistake_type`, `recovery_type`, `failure_stage`, `autonomy_level`, `model_version`, `evaluation_membership`	与标签中相同，空值以 `null` 代替。
`leakage_groups`	与标签中相同。
`outcome_source`, `outcome_source_metadata`, `outcome_confidence`	标签的 `source`、`source_metadata` 和 `confidence`。

没有标签的序列会得到一行，其中只有 episode_index、avala_sequence_uid 和 "outcome": null。

失败与恢复通道

可恢复的失败作为独立的通道交付：即结果为 mistake_and_recovery 或 intervention 的序列。每个序列的子任务和手部动作标出失败和恢复发生的位置。该通道在发布版本中作为单独的切片交付。您可以在其上训练、为其加权或将其排除。您也可以用 ?outcome=mistake_and_recovery,intervention 自行构建同样的集合。不安全的序列不属于该通道。

入门

机群学习

平台

应用场景

结果标签

示例

字段

结果值

自主级别

子任务

手部动作

序列时长

评估成员资格

泄漏组

来源元数据

写入方式

技术有效性

读取和写入结果标签

写入标签

读取标签

通过 MCP 服务器读取标签

通过 LeRobot 导出结果标签

失败与恢复通道

​结果标签

​示例

​字段

​结果值

​自主级别

​子任务

​手部动作

​序列时长

​评估成员资格

​泄漏组

​来源元数据

​写入方式

​技术有效性

​读取和写入结果标签

​写入标签

​读取标签

​通过 MCP 服务器读取标签

​通过 LeRobot 导出结果标签

​失败与恢复通道

结果标签

示例

字段

结果值

自主级别

子任务

手部动作

序列时长

评估成员资格

泄漏组

来源元数据

写入方式

技术有效性

读取和写入结果标签

写入标签

读取标签

通过 MCP 服务器读取标签

通过 LeRobot 导出结果标签

失败与恢复通道