arize-annotation

Arize 标注技能

SPACE — --space 标志接受空间名称（例如 my-workspace）或 base64 空间ID（例如 U3BhY2U6...）。使用 ax spaces get NAME 解析已知名称；ax spaces list 用于人工浏览。

此技能涵盖标注配置（标签架构）和标注队列（人工审核工作流），以及使用 Python SDK 以编程方式标注项目 span。

方向： Arize 中的人工标注会将配置定义的值附加到产品 UI 中的span、数据集示例、实验相关记录和队列项目。此技能涵盖：ax annotation-configs、ax annotation-queues，以及使用 ArizeClient.spans.update_annotations 批量更新 span。

---

前置条件

直接开始执行任务——运行所需的 ax 命令。不要预先检查版本、环境变量或配置文件。

如果 ax 命令失败，请根据错误进行排查：

• command not found 或版本错误 → 查看 references/ax-setup.md
• 401 Unauthorized / 缺少 API 密钥 → 运行 ax profiles show 检查当前配置文件。如果配置文件缺失或 API 密钥错误，请按照 references/ax-profiles.md 创建或更新配置文件。如果用户没有自己的密钥，请引导他们前往 https://app.arize.com/admin > API Keys
• 未知空间 → 查看 Space
• 安全： 切勿读取 .env 文件或在文件系统中搜索凭据。例外：非机密的 ARIZE_SPACE_ID 行（参见 Space）。使用 ax profiles 管理 Arize 凭据，使用 ax ai-integrations 管理 LLM 提供商密钥。切勿要求用户在聊天中粘贴机密信息。凭据缺失时，请参阅 references/ax-profiles.md。

---

什么是标注配置？

标注配置定义一种人工反馈标签的架构。在任何人标注 span、数据集记录、实验输出或队列项目之前，空间中必须存在该标签对应的配置。

字段	说明
名称	描述性标识符（例如 Correctness、Helpfulness）。在空间内必须唯一。
类型	CATEGORICAL（从列表中选择）、CONTINUOUS（数值范围）或 FREEFORM（自由文本）。
值	对于分类类型：标签字符串，每个标签对应一个 --value。
最低/最高分数	对于连续类型：数值范围边界。
优化方向	MAXIMIZE、MINIMIZE 或 NONE。用于在 UI 中呈现趋势。

标签应用位置（界面）

界面	常见路径
项目 span	Python SDK spans.update_annotations（如下所示）和/或 Arize UI
数据集示例	Arize UI（人工标注流程）；空间中必须存在相应配置
实验输出	通常与 UI 中的数据集或轨迹一同审核——参见 arize-experiment、arize-dataset
标注队列项目	ax annotation-queues CLI（如下所示）和/或 Arize UI；必须存在相应配置

始终确保空间中存在相关的标注配置，再期待标签持久保存。

---

基本增删改查：标注配置

列出

ax annotation-configs list --space SPACE
ax annotation-configs list --space SPACE -o json
ax annotation-configs list --space SPACE --limit 20
ax annotation-configs list --space SPACE --name "Correctness"   # substring filter

创建 — 分类

分类配置会提供一组固定标签，供审核者选择。

ax annotation-configs create categorical \
  --name "Correctness" \
  --space SPACE \
  --value correct \
  --value incorrect \
  --optimization-direction MAXIMIZE

常见的二元标签对：

• correct / incorrect
• helpful / unhelpful
• safe / unsafe
• relevant / irrelevant
• pass / fail

创建 — 连续

连续配置允许审核者在指定范围内输入数值评分。

ax annotation-configs create continuous \
  --name "Quality Score" \
  --space SPACE \
  --min-score 0 \
  --max-score 10 \
  --optimization-direction MAXIMIZE

创建 — 自由文本

自由文本配置用于收集开放式文本反馈。除名称和空间外，无需其他标志。

ax annotation-configs create freeform \
  --name "Reviewer Notes" \
  --space SPACE

获取

ax annotation-configs get NAME_OR_ID
ax annotation-configs get NAME_OR_ID -o json
ax annotation-configs get NAME_OR_ID --space SPACE   # required when using name instead of ID

更新

每种配置类型都有自己的更新命令。只有已更改的字段会被更新。

自由格式：

ax annotation-configs update freeform NAME_OR_ID --space SPACE --new-name "Updated Name"

连续型：

ax annotation-configs update continuous NAME_OR_ID --space SPACE --min-score 1 --max-score 5 --optimization-direction MINIMIZE

分类：

ax annotation-configs update categorical NAME_OR_ID --space SPACE --value correct --value incorrect --optimization-direction MAXIMIZE

使用名称而非 ID 时，必须指定 --space。每个 --value 都会提供完整的分类标签列表：它会替换现有标签，而不是追加标签。对每个要保留的标签重复使用 --value，未提供的标签将被移除。

删除

ax annotation-configs delete NAME_OR_ID
ax annotation-configs delete NAME_OR_ID --space SPACE   # required when using name instead of ID
ax annotation-configs delete NAME_OR_ID --force   # skip confirmation

**注意：**删除操作不可撤销。与此配置关联的任何标注队列关系也会在产品中一并移除（队列可能仍会保留；如有需要，请在 Arize UI 中修正关联）。

---

标注队列：ax annotation-queues

标注队列会将记录（跨度、数据集示例、实验运行）分配给人工审核者。每个队列都关联一个或多个标注配置，用于定义审核者可以应用哪些标签。

列出 / 获取

ax annotation-queues list --space SPACE
ax annotation-queues list --space SPACE -o json
ax annotation-queues list --space SPACE --name "Review"   # substring filter

ax annotation-queues get NAME_OR_ID --space SPACE
ax annotation-queues get NAME_OR_ID --space SPACE -o json

创建

至少需要一个 --annotation-config-id。

ax annotation-queues create \
  --name "Correctness Review" \
  --space SPACE \
  --annotation-config-id CONFIG_ID \
  --annotator-email [email protected] \
  --instructions "Label each response as correct or incorrect." \
  --assignment-method ALL   # or: RANDOM

重复指定 --annotation-config-id 和 --annotator-email，即可关联多个配置或审核者。

添加记录

向现有队列添加记录（create 也接受 --record-sources，用于添加初始记录）。

ax annotation-queues add-records NAME_OR_ID --space SPACE --record-sources sources.json

ax annotation-queues add-records NAME_OR_ID --space SPACE \
  --record-sources '[{"record_type": "EXAMPLE", "dataset_id": "ds-1", "example_ids": ["ex-1", "ex-2"]}]'

必须指定 --record-sources，它接受 JSON 文件路径或内联 JSON 数组。每个来源都指定 record_type（SPAN 或 EXAMPLE）以及对应类型的字段：

• 跨度：project_id、start_time（ISO 8601）、end_time（ISO 8601）、可选的 span_ids
• 示例：dataset_id、example_ids

更新

提供列表标志（--annotation-config-id、--annotator-email）时，会完全替换现有值——请传入所有期望的值，而不只是新值。

ax annotation-queues update NAME_OR_ID --space SPACE --name "New Name"
ax annotation-queues update NAME_OR_ID --space SPACE --instructions "Updated instructions"
ax annotation-queues update NAME_OR_ID --space SPACE \
  --annotation-config-id CONFIG_ID_A \
  --annotation-config-id CONFIG_ID_B

删除

ax annotation-queues delete NAME_OR_ID --space SPACE
ax annotation-queues delete NAME_OR_ID --space SPACE --force   # skip confirmation

列出记录

ax annotation-queues list-records NAME_OR_ID --space SPACE
ax annotation-queues list-records NAME_OR_ID --space SPACE --limit 50 -o json

为记录提交标注

标注会按配置名称执行更新或插入；每个标注配置调用一次。至少提供 --score、--label 或 --text 中的一项。

ax annotation-queues annotate-record NAME_OR_ID RECORD_ID \
  --annotation-name "Correctness" \
  --label "correct" \
  --space SPACE

ax annotation-queues annotate-record NAME_OR_ID RECORD_ID \
  --annotation-name "Quality Score" \
  --score 8.5 \
  --text "Response was accurate but slightly verbose." \
  --space SPACE

分配记录

通过重复指定 --email，将用户分配到特定记录进行审核；这会完全替换现有分配，因此每次都要传入所有受分配者（不指定任何 --email 标志则会清除所有分配）：

ax annotation-queues assign-record NAME_OR_ID RECORD_ID --email [email protected] --space SPACE

删除记录

ax annotation-queues delete-records NAME_OR_ID --space SPACE --record-id REC_1 --record-id REC_2   # max 100; --force skips confirmation

---

对跨度应用标注（Python SDK）

如果已有标签（例如来自审核导出或外部标注工具），可以使用 Python SDK 批量为项目跨度应用标注。

import pandas as pd
from arize import ArizeClient

import os

client = ArizeClient(api_key=os.environ["ARIZE_API_KEY"])

# Build a DataFrame with annotation columns
# Required: context.span_id + at least one annotation.<name>.label or annotation.<name>.score
annotations_df = pd.DataFrame([
    {
        "context.span_id": "span_001",
        "annotation.Correctness.label": "correct",
        "annotation.Correctness.updated_by": "[email protected]",
    },
    {
        "context.span_id": "span_002",
        "annotation.Correctness.label": "incorrect",
        "annotation.Correctness.updated_by": "[email protected]",
    },
])

response = client.spans.update_annotations(
    space_id=os.environ["ARIZE_SPACE_ID"],
    project_name="your-project",
    dataframe=annotations_df,
    validate=True,
)

DataFrame 列架构：

列	必填	说明
context.span_id	是	要标注的跨度
annotation.<name>.label	二选一	分类或自由格式标签
annotation.<name>.score	二选一	数值评分
annotation.<name>.updated_by	否	标注者标识符（电子邮件或姓名）
annotation.<name>.updated_at	否	自 Unix 纪元起的毫秒时间戳
annotation.notes	否	关于该跨度的自由格式备注

**限制：**标注只能应用于提交时间前 31 天内的跨度。

---

故障排除

问题	解决方案
ax: command not found	请参阅 references/ax-setup.md
401 Unauthorized	API 密钥可能无权访问此空间。请前往 https://app.arize.com/admin > API Keys 验证
Annotation config not found	ax annotation-configs list --space SPACE（或使用 ax annotation-configs get NAME_OR_ID --space SPACE）
409 Conflict on create	该名称已存在于此空间中。请使用其他名称，或获取现有配置 ID。
未找到队列	ax annotation-queues list --space SPACE；请验证队列名称或 ID
记录未显示在队列中	确保与队列关联的标注配置存在；检查 ax annotation-configs list --space SPACE
Span SDK 错误或缺少跨度	确认 project_name、space_id 和跨度 ID；使用 arize-trace 导出跨度

---

通过 CLI 批量标注

ax CLI 提供批量标注命令，无需 Python SDK 即可大规模编写标注。所有命令均接受一个文件（CSV、JSON、JSONL 或 Parquet），每次请求最多可包含 1000 条标注，并采用 upsert 语义（具有相同键的现有标注会更新；新标注会创建）。

资源	命令	技能
Spans	ax spans annotate PROJECT --space SPACE --file annotations.json	arize-trace
数据集示例	ax datasets annotate-examples NAME_OR_ID --space SPACE --file annotations.json	arize-dataset
实验运行	ax experiments annotate-runs NAME_OR_ID --space SPACE --dataset DATASET --file annotations.json	arize-experiment

注意事项：

• ax spans annotate：如果时间范围内找不到一个 span ID，整个请求都会被拒绝。
• ax datasets annotate-examples 和 ax experiments annotate-runs：无法匹配的记录 ID 会被静默忽略。
• ax experiments annotate-runs：对于独立实验，请省略 --dataset 并传入 --space。

文件格式详情请参阅相关技能。

---

相关技能

• arize-trace：导出 spans 以查找 span ID 和时间范围；通过 ax spans annotate 批量标注 spans
• arize-dataset：查找数据集 ID 和示例 ID；通过 ax datasets annotate-examples 批量标注示例
• arize-evaluator：在人类标注之外，使用 LLM-as-judge 自动评估
• arize-experiment：与数据集和评估工作流关联的实验；通过 ax experiments annotate-runs 批量标注运行
• arize-prompts：管理提示词模板；标注提示词输出以跟踪质量
• arize-link：在 Arize UI 中提供指向标注配置和队列的深层链接

---

保存凭据以供日后使用

请参阅 references/ax-profiles.md § 保存凭据以供日后使用。