在 Arize 上创建标注配置与人工审核队列并批量标注…

当需要在 Arize 中定义标注标签 schema、搭建人工审核队列，或通过 CLI/Python SDK 对 span 批量写入人工标注时使用。

适用场景

解决思路

1. 直接执行所需的 ax 命令，不要预先检查版本、环境变量或 profile；命令失败后再按错误排查：command not found 或版本错误查 references/ax-setup.md；401 Unauthorized 或缺少 API key 时运行 ax profiles show 检查当前 profile，缺失或错误则按 references/ax-profiles.md 创建/更新，用户没有 key 就引导其到 https://app.arize.com/admin > API Keys；space 未知时运行 ax spaces list 按名称选择或询问用户。
2. 安全要求：绝不读取 .env 文件或在文件系统中搜索凭据；Arize 凭据用 ax profiles，LLM 提供商密钥用 ax ai-integrations；绝不让用户把密钥粘贴到聊天中。
3. --space 参数可接受 space 名称（如 my-workspace）或 base64 space ID（如 U3BhY2U6...），用 ax spaces list 查找。
4. 列出标注配置：ax annotation-configs list --space SPACE，可加 -o json、--limit 20、--name "Correctness"（子串过滤）。
5. 创建分类配置：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。
6. 创建连续配置：ax annotation-configs create continuous --name "Quality Score" --space SPACE --min-score 0 --max-score 10 --optimization-direction MAXIMIZE。
7. 创建自由文本配置：ax annotation-configs create freeform --name "Reviewer Notes" --space SPACE。
8. 获取配置：ax annotation-configs get NAME_OR_ID，可加 -o json；用名称而非 ID 时必须加 --space SPACE。
9. 更新自由文本配置：ax annotation-configs update freeform NAME_OR_ID --space SPACE --new-name "Updated Name"。
10. 更新连续配置：ax annotation-configs update continuous NAME_OR_ID --space SPACE --min-score 1 --max-score 5 --optimization-direction MINIMIZE。
11. 更新分类配置：ax annotation-configs update categorical NAME_OR_ID --space SPACE --value correct --value incorrect --optimization-direction MAXIMIZE；每个 --value 提供完整标签列表，会替换而非追加，需重复列出所有要保留的标签。
12. 删除配置：ax annotation-configs delete NAME_OR_ID，可加 --space SPACE（用名称时必需）和 --force 跳过确认；删除不可逆，队列关联也会被移除。
13. 列出/获取标注队列：ax annotation-queues list --space SPACE（可加 -o json、--name "Review" 子串过滤）；ax annotation-queues get NAME_OR_ID --space SPACE（可加 -o json）。
14. 创建队列：ax annotation-queues create --name "Correctness Review" --space SPACE --annotation-config-id CONFIG_ID --annotator-email reviewer@example.com --instructions "Label each response as correct or incorrect." --assignment-method ALL（或 RANDOM）；至少需要一个 --annotation-config-id，可重复 --annotation-config-id 和 --annotator-email 附加多个配置或审核人。
15. 向队列添加记录：ax annotation-queues add-records NAME_OR_ID --space SPACE --record-sources sources.json，或内联 JSON 如 '[{"record_type": "EXAMPLE", "dataset_id": "ds-1", "example_ids": ["ex-1", "ex-2"]}]'；每个 source 指定 record_type（SPAN 或 EXAMPLE）及类型字段：Span 用 project_id、start_time（ISO 8601）、end_time（ISO 8601）、可选 span_ids；Example 用 dataset_id、example_ids。
16. 更新队列：ax annotation-queues update NAME_OR_ID --space SPACE --name "New Name"，或 --instructions "Updated instructions"，或重复 --annotation-config-id CONFIG_ID_A --annotation-config-id CONFIG_ID_B；列表类参数（--annotation-config-id、--annotator-email）提供时会完全替换原值，需传入所有期望值。
17. 删除队列：ax annotation-queues delete NAME_OR_ID --space SPACE，可加 --force 跳过确认。
18. 列出队列记录：ax annotation-queues list-records NAME_OR_ID --space SPACE，可加 --limit 50 -o json。
19. 提交记录标注：ax annotation-queues annotate-record NAME_OR_ID RECORD_ID --annotation-name "Correctness" --label "correct" --space SPACE，或 --annotation-name "Quality Score" --score 8.5 --text "Response was accurate but slightly verbose." --space SPACE；按配置名 upsert，每个配置调用一次，至少提供 --score、--label、--text 之一。
20. 分配记录审核人：ax annotation-queues assign-record NAME_OR_ID RECORD_ID --email user@example.com --space SPACE；重复 --email 指定多人，会完全替换现有分配，不传 --email 则清空所有分配。
21. 删除队列记录：ax annotation-queues delete-records NAME_OR_ID --space SPACE。
22. 用 Python SDK 批量标注 span：用 ArizeClient(api_key=os.environ["ARIZE_API_KEY"]) 创建客户端，构建 DataFrame（必需 context.span_id 加至少一个 annotation.<name>.label 或 annotation.<name>.score；可选 annotation.<name>.updated_by、annotation.<name>.updated_at（毫秒时间戳）、annotation.notes），调用 client.spans.update_annotations(space_id=os.environ["ARIZE_SPACE_ID"], project_name="your-project", dataframe=annotations_df, validate=True)。
23. 注意：标注仅适用于提交前 31 天内的 span。
24. 用 CLI 批量标注：所有命令接受 CSV、JSON、JSONL 或 Parquet 文件，每次请求最多 1000 条标注，采用 upsert 语义；span 用 ax spans annotate PROJECT --file annotations.json，数据集样本用 ax datasets annotate-examples NAME_OR_ID --file annotations.json，实验运行用 ax experiments annotate-runs NAME_OR_ID --file annotations.json --dataset DATASET，均支持 --space SPACE。
25. 排查常见问题：401 Unauthorized 时确认 API key 是否有该 space 权限；Annotation config not found 时用 ax annotation-configs list --space SPACE 或 get 确认；409 Conflict on create 表示名称已存在，换名或取现有配置 ID；队列找不到时用 ax annotation-queues list --space SPACE 核对；记录不出现在队列时确认队列关联的标注配置存在；span SDK 报错或找不到 span 时确认 project_name、space_id 和 span ID，可用 arize-trace 导出 span。

适用边界 · 注意事项

• 未安装 ax CLI（≥ 0.33.0）或未配置 Arize profile 时无法使用本技能。
• 需要标注超过 31 天前的 span 时，SDK 批量标注不适用。
• 不想依赖 Arize 云服务或付费账号时，本技能不适用。