arize-annotation

Arize 标注 Skill

SPACE — 所有 --space 标志和 ARIZE_SPACE 环境变量都接受 space 名称（例如 my-workspace）或 base64 space ID（例如 U3BhY2U6...）。使用 ax spaces list 查找你的 space。

本 skill 涵盖 标注配置（标签 schema）和 标注队列（人工审核工作流），以及通过 Python SDK 以编程方式对项目 span 进行标注。

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

---

前提条件

直接开始任务 —— 运行你需要的 ax 命令。不要预先检查版本、环境变量或 profile。

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

• command not found 或版本错误 → 参见 references/ax-setup.md
• 401 Unauthorized / 缺少 API key → 运行 ax profiles show 检查当前 profile。如果 profile 缺失或 API key 错误，请按照 references/ax-profiles.md 创建/更新它。如果用户没有自己的 key，请引导他们前往 https://app.arize.com/admin > API Keys
• Space 未知 → 运行 ax spaces list 按名称选择，或询问用户
• 安全： 切勿读取 .env 文件或在文件系统中搜索凭据。使用 ax profiles 获取 Arize 凭据，使用 ax ai-integrations 获取大模型提供商 key。如果无法通过这些渠道获取凭据，请询问用户。

---

概念

什么是标注配置？

标注配置 定义了单种类型人工反馈标签的 schema。在任何人可以对 span、数据集记录、实验输出或队列项进行标注之前，该 space 中必须存在该标签对应的配置。

字段	描述
名称	描述性标识符（例如 Correctness、Helpfulness）。在 space 内必须唯一。
类型	categorical（从列表中选择）、continuous（数值范围）或 freeform（自由文本）。
值	对于 categorical：由 {"label": str, "score": number} 对组成的数组。
最小/最大分数	对于 continuous：数值边界。
优化方向	分数越高越好（maximize）还是越差（minimize）。用于在 UI 中渲染趋势。

标签应用于何处（表面）

表面	典型路径
项目 span	Python SDK spans.update_annotations（见下文）和/或 Arize UI
数据集样本	Arize UI（人工标注流程）；配置必须存在于该 space 中
实验输出	通常在 UI 中与数据集或 trace 一起审核 —— 参见 arize-experiment、arize-dataset
标注队列项	ax annotation-queues CLI（见下文）和/或 Arize UI；配置必须存在

在期望标签持久化之前，请始终确保相关的 标注配置 已存在于该 space 中。

---

基本 CRUD：标注配置

列表

ax annotation-configs list --space SPACE
ax annotation-configs list --space SPACE -o json
ax annotation-configs list --space SPACE --limit 20

创建 —— Categorical

Categorical 配置向审核者提供一组固定的标签供其选择。

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

常见的二元标签对：

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

创建 —— Continuous

Continuous 配置允许审核者在定义的范围内输入数值分数。

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

创建 —— Freeform

Freeform 配置收集开放式的文本反馈。除了名称、space 和类型之外，不需要额外的标志。

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

获取

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 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

标注队列将记录（span、数据集样本、实验运行）路由给人工审核人员。每个队列关联一个或多个标注配置，这些配置定义了审核人员可以应用的标签。

列出 / 获取

ax annotation-queues list --space SPACE
ax annotation-queues list --space SPACE -o json

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 可关联多个配置或审核人员。

更新

列表类标志（--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

为记录提交标注

标注按配置名称进行 upsert —— 每个标注配置调用一次。至少提供 --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

分配记录

将用户分配为审核特定记录：

ax annotation-queues assign-record NAME_OR_ID RECORD_ID --space SPACE

删除记录

ax annotation-queues delete-records NAME_OR_ID --space SPACE

---

将标注应用到 Span（Python SDK）

当你已经拥有标签（例如来自审核导出或外部标注工具）时，可使用 Python SDK 批量将标注应用到项目 span。

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"],
    project_name="your-project",
    dataframe=annotations_df,
    validate=True,
)

DataFrame 列结构：

列	必填	描述
context.span_id	是	要标注的 span
annotation.<name>.label	其中之一	分类或自由形式标签
annotation.<name>.score	其中之一	数值分数
annotation.<name>.updated_by	否	标注者标识（邮箱或姓名）
annotation.<name>.updated_at	否	时间戳，自 epoch 起的毫秒数
annotation.notes	否	关于该 span 的自由形式备注

限制： 标注仅适用于提交前 31 天内的 span。

---

故障排除

问题	解决方案
ax: command not found	参见 references/ax-setup.md
401 Unauthorized	API key 可能无权访问此空间。请在 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。
Queue not found	ax annotation-queues list --space SPACE；验证队列名称或 ID
Record not appearing in queue	确保与队列关联的标注配置存在；检查 ax annotation-configs list --space SPACE
Span SDK errors or missing spans	确认 project_name、space_id 和 span ID；使用 arize-trace 导出 span

---

相关技能

• arize-trace：导出 span 以查找 span ID 和时间范围
• arize-dataset：查找数据集 ID 和样本 ID
• arize-evaluator：自动化 LLM-as-judge 与人工标注并行
• arize-experiment：与数据集和评估工作流关联的实验
• arize-link：Arize UI 中标注配置和队列的深度链接

---

保存凭据以供将来使用

参见 references/ax-profiles.md § 保存凭据以供将来使用。