基于 awesome-copilot 的 Arize 人工标注实战：Annotation Config、Queue 编排与 Python SDK 批量打标-北京尧图网络

基于 awesome-copilot 的 Arize 人工标注实战Annotation Config、Queue 编排与 Python SDK 批量打标【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot导读本指南以 awesome-copilot 仓库中的arize-annotation技能为核心系统讲解如何在 Arize 上搭建完整的人工反馈标注体系——从定义标签 Schemaannotation config、编排人工审核队列annotation queue到通过axCLI 完成队列标注、再用 Python SDK 对项目 spans 批量回填标注。读完本文你将掌握三类标签类型categorical / continuous / freeform的创建与 CRUD、队列的创建与派发、spans.update_annotations的 DataFrame 列契约以及一套可复制的排障流程能够直接在真实项目里落地人机协同评估闭环。一、技能定位在 awesome-copilot 中的角色arize-annotation是 awesome-copilot 社区技能库中 Arize 观测平台系列技能之一位于 skills/arize-annotation/SKILL.md配套两个按需加载的参考文档skills/arize-annotation/references/ax-setup.md 与 skills/arize-annotation/references/ax-profiles.md。技能元信息SKILL.md front matter明确了它的适用范围与触发条件name: arize-annotation description: Creates and manages annotation configs (categorical, continuous, freeform label schemas) and annotation queues (human review workflows) on Arize. Applies human annotations to project spans via the Python SDK. compatibility: Requires the ax CLI and a configured Arize profile.author:arizeversion1.0前置条件axCLI 与已配置的 Arize profile见下文第三节适用场景用户提到 annotation config、annotation queue、label schema、human feedback、bulk annotate spans、update_annotations、labeling queue、annotate record、human review 等关键词时激活。在技能体系中它与 skills/arize-trace/SKILL.md导出 spans、定位 span_id、skills/arize-dataset/SKILL.md数据集示例、skills/arize-evaluator/SKILL.mdLLM-as-judge 自动化评估、skills/arize-experiment/SKILL.md实验以及 skills/arize-link/SKILL.md深链跳转 UI共同构成采集 → 评估 → 标注 → 实验的完整链路本技能负责其中人类标注这一环。整个技能库的安装与使用方式参见 docs/README.skills.md例如通过gh skills install github/awesome-copilot arize-annotation安装。核心方向Skill DirectionHuman labeling in Arize attaches values defined by configs tospans、dataset examples、experiment-related records和queue items在 product UI 中。本技能覆盖ax annotation-configs、ax annotation-queues以及通过ArizeClient.spans.update_annotations批量更新 spans。一句话概括其架构思想标注 config 定义可以标什么标注 queue 决定让谁在什么流程里标Python SDK 负责把已有标签批量写回 spans。二、概念先行Annotation Config 与标注落点2.1 什么是 Annotation ConfigAnnotation config定义了某一类人类反馈标签的 Schema。在任何人对 span、dataset record、experiment output 或 queue item 进行标注之前对应标签的 config 必须已经在该 space 中存在——这是所有标注行为的前置条件。SKILL.md 给出了 config 的字段模型字段说明Name描述性标识如Correctness、Helpfulness在 space 内必须唯一Typecategorical从列表中选择、continuous数值区间、freeform自由文本Values仅 categorical 使用{label: str, score: number}键值对数组Min/Max Score仅 continuous 使用数值上下界Optimization Direction分数越高越好maximize还是越差minimize用于 UI 趋势渲染其中 Values 仅 categorical 使用这一约束值得注意创建 categorical config 时通过重复--value参数传入标签名分数由系统按序分配或由 UI 侧配置而 continuous 类型的标签直接由评分人输入min-score到max-score之间的任意数值。2.2 标签会落在哪些表面surfaces表面典型路径Project spansPython SDKspans.update_annotations下文第五节和/或 Arize UIDataset examplesArize UI人工标注流程config 必须存在于 spaceExperiment outputs常与 dataset、traces 一起在 UI 中评审——参见 skills/arize-experiment/SKILL.md、skills/arize-dataset/SKILL.mdAnnotation queue itemsax annotation-queuesCLI下文第四节和/或 Arize UIconfig 必须存在经验法则在期望标签被持久化之前务必确保相关的annotation config已存在于 space 中。这与自动化评估侧evaluator 必须先存在的约束是对称的——两者共同保证了所有标签列都有 Schema 归属。从底层数据模型看标注最终以annotation.name.label、annotation.name.score、annotation.name.text的形式落在 span 上。skills/arize-trace/SKILL.md 的 Span Column Reference 明确列出了这三个字段意味着人工标注与自动评估写入的是同一套列命名空间自动评估使用eval.{name}.label前缀人工标注使用annotation.{name}.label前缀这正是人机评估结果可以在同一张表格里对比的机制基础。三、动手前准备ax CLI 与 Profile按错误驱动SKILL.md 明确要求不要主动预检版本、环境变量或 profile——直接执行所需命令遇到错误再按错误类型排查。这是技能设计的执行纪律避免在无故障场景下浪费不必要的 API 调用。3.1 通用 SPACE 约定SPACE—— 所有--space标志与ARIZE_SPACE环境变量都接受 space名称如my-workspace或 base64 编码的 spaceID如U3BhY2U6...。用ax spaces list查看自己的 space。3.2 错误驱动的排查路径SKILL.md 给出如下判定树报错处理动作command not found或版本错误查看 skills/arize-annotation/references/ax-setup.md401 Unauthorized/ 缺少 API key运行ax profiles show检查当前 profile缺失或 key 错误则按 skills/arize-annotation/references/ax-profiles.md 创建/更新若用户没有 key引导其到 Arize 控制台 API Keys 页面生成Space 未知运行ax spaces list按名称挑选或询问用户安全红线绝不读取.env文件或在文件系统里搜索凭据。Arize 凭据一律走ax profilesLLM 供应商 key 一律走ax ai-integrations若这些渠道拿不到凭据直接询问用户3.3 ax 安装与版本ax-setup 要点references/ax-setup.md 提供了完整的安装排障指引核心事实版本门槛ax --version必须为0.14.0 及以上大量错误源于安装版本过旧macOS/Linux 安装优先uv tool install arize-ax-cli或pipx install arize-ax-cli、pip install arize-ax-cli检查~/.local/bin/ax、~/Library/Python/*/bin/axWindows (PowerShell)pip install arize-ax-cli检查%APPDATA%\Python\Scripts\ax.exe等路径升级uv tool install --force --reinstall arize-ax-cli/pipx upgrade arize-ax-cli/pip install --upgrade arize-ax-cliSSL 证书错误macOS 设SSL_CERT_FILE/etc/ssl/cert.pemLinux 设/etc/ssl/certs/ca-certificates.crt兜底用certifi路径。3.4 Profile 与凭据管理ax-profiles 要点references/ax-profiles.md 规定了一条铁律绝不要把原始 API key 作为命令行参数直接传入必须通过ARIZE_API_KEY环境变量引用# 先确保 ARIZE_API_KEY 已在 shell 中导出 export ARIZE_API_KEY... # 用户在自己的终端粘贴 key # 创建新 profile可选 --region可命名 ax profiles create --api-key $ARIZE_API_KEY ax profiles create --api-key $ARIZE_API_KEY --region us-east-1b ax profiles create work --api-key $ARIZE_API_KEY --region us-east-1b # 修复现有 profile只改指定字段其余保留 ax profiles update --api-key $ARIZE_API_KEY ax profiles update --region us-east-1b ax profiles update --api-key $ARIZE_API_KEY --region us-east-1b # 使用命名 profile ax spans export PROJECT -p work其他要点推荐创建scoped service key而非个人用户 keyservice key 不绑定个人账号、更适合程序化使用key 是space 作用域的务必为正确的 space 复制space 没有 profile 标志需保存为环境变量ARIZE_SPACE接受名称或 base64 IDmacOS/Linux 写入~/.zshrc或~/.bashrcWindows 用[System.Environment]::SetEnvironmentVariable(ARIZE_SPACE, my-workspace, User)会话结束时若用户手动提供过凭据且未来自已保存的 profile/环境变量应主动询问是否保存AskQuestion保存同样走ax profiles create/update --api-key $ARIZE_API_KEY。四、Annotation Config 的基础 CRUD4.1 列表查询ax annotation-configs list --space SPACE ax annotation-configs list --space SPACE -o json ax annotation-configs list --space SPACE --limit 20-o json适合后续脚本解析例如提取 config ID 传给 queue 创建命令。4.2 创建 Categorical分类标签分类 config 为评审者提供一组固定标签供选择是最常见的标注形态ax annotation-configs create \ --name Correctness \ --space SPACE \ --type categorical \ --value correct \ --value incorrect \ --optimization-direction maximize常用二元标签对可直接套用correct/incorrecthelpful/unhelpfulsafe/unsaferelevant/irrelevantpass/fail从实践看二元标签与 skills/arize-evaluator/SKILL.md 中 LLM-as-judge 的二元分类设计保持一致该技能明确推荐二元标签以提高 judge 模型的一致性这意味着同一组 config 语义既能被人工评审也能被自动评估复用。4.3 创建 Continuous连续分值连续 config 允许评审者在定义区间内输入数值分数ax annotation-configs create \ --name Quality Score \ --space SPACE \ --type continuous \ --min-score 0 \ --max-score 10 \ --optimization-direction maximize--min-score/--max-score是连续类型的核心参数决定可打分区间。4.4 创建 Freeform自由文本自由文本 config 收集开放式反馈除 name、space、type 外无需额外参数ax annotation-configs create \ --name Reviewer Notes \ --space SPACE \ --type freeform4.5 查询单个 configax annotation-configs get NAME_OR_ID ax annotation-configs get NAME_OR_ID -o json ax annotation-configs get NAME_OR_ID --space SPACE # 使用名称而非 ID 时必须指定注意当以名称查询时--space是必需的以 base64 ID 查询则不需要。4.6 删除 configax annotation-configs delete NAME_OR_ID ax annotation-configs delete NAME_OR_ID --space SPACE # 使用名称而非 ID 时必须指定 ax annotation-configs delete NAME_OR_ID --force # 跳过确认重要警告删除不可逆。与该 config 关联的 annotation queue 关联关系也会在产品中被移除queue 本身可能保留但需要在 Arize UI 中修复关联。因此删除前务必确认该 config 没有被正在运行的标注流程引用。五、Annotation Queue人工审核工作流编排Annotation queue将记录spans、dataset examples、experiment runs路由给人类评审者。每个 queue 关联一个或多个 annotation config这些 config 决定了评审者可以打哪些标签。5.1 列表与查询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 json5.2 创建 queue至少需要一个--annotation-config-idax annotation-queues create \ --name Correctness Review \ --space SPACE \ --annotation-config-id CONFIG_ID \ --annotator-email reviewerexample.com \ --instructions Label each response as correct or incorrect. \ --assignment-method all # 或: random关键参数参数说明--annotation-config-id关联的标注 config可重复传参挂多个 config--annotator-email评审者邮箱可重复传参添加多名评审者--instructions给评审者的任务说明--assignment-methodall所有评审者都标或random随机分配5.3 更新 queue —— 注意全量替换语义重要陷阱列表类标志--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最后一个示例会清掉原先的 config 列表仅保留CONFIG_ID_A与CONFIG_ID_B两个关联。5.4 删除 queueax annotation-queues delete NAME_OR_ID --space SPACE ax annotation-queues delete NAME_OR_ID --space SPACE --force # 跳过确认5.5 查看 queue 中的记录ax annotation-queues list-records NAME_OR_ID --space SPACE ax annotation-queues list-records NAME_OR_ID --space SPACE --limit 50 -o json5.6 为记录提交标注标注按 config 名称 upsert——每个 config 调用一次。--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这条命令是本技能在 queue 场景下的核心写操作配合list-records拿到的RECORD_ID即可完成端到端的取件 → 评审 → 回写。5.7 指派与删除记录# 指派用户评审特定记录 ax annotation-queues assign-record NAME_OR_ID RECORD_ID --space SPACE # 删除记录 ax annotation-queues delete-records NAME_OR_ID --space SPACE六、用 Python SDK 对 Project Spans 批量标注当标签已经存在例如来自评审导出或外部标注工具时无需逐条走 queue可以直接用 Python SDK 批量写回project spansimport pandas as pd from arize import ArizeClient import os client ArizeClient(api_keyos.environ[ARIZE_API_KEY]) # 构建带标注列的 DataFrame # 必填: context.span_id annotation.name.label 或 annotation.name.score 至少其一 annotations_df pd.DataFrame([ { context.span_id: span_001, annotation.Correctness.label: correct, annotation.Correctness.updated_by: reviewerexample.com, }, { context.span_id: span_002, annotation.Correctness.label: incorrect, annotation.Correctness.updated_by: reviewerexample.com, }, ]) response client.spans.update_annotations( space_idos.environ[ARIZE_SPACE], project_nameyour-project, dataframeannotations_df, validateTrue, )DataFrame 列契约列必填说明context.span_id是要标注的 spanannotation.name.label至少其一分类或自由文本标签annotation.name.score至少其一数值分数annotation.name.updated_by否标注者标识邮箱或姓名annotation.name.updated_at否自 epoch 起的毫秒时间戳annotation.notes否针对 span 的自由备注已知限制标注仅适用于提交时刻之前 31 天以内的 spans——超过窗口的旧 span 无法通过该接口回填。与导出链路打通context.span_id的来源通常是 skills/arize-trace/SKILL.md 的导出结果ax spans export PROJECT --trace-id TRACE_ID --output-dir .arize-tmp-traces导出 JSON 中的context.span_id、start_time字段可直接用于构造annotations_df同时也方便你在回填前确认 span 是否落在 31 天窗口内。这也解释了为何技能间存在依赖先arize-trace拿 span 清单再arize-annotation批量打标构成导出 → 标注的标准数据管道。七、排障速查表SKILL.md 汇总了常见问题与解决方案是运行本技能最重要的实战参考问题解决方案ax: command not found查看 skills/arize-annotation/references/ax-setup.md401 UnauthorizedAPI key 可能无权访问该 space。在 Arize 控制台 API Keys 页面确认Annotation config not foundax annotation-configs list --space SPACE或用ax annotation-configs get NAME_OR_ID --space SPACE创建时409 Conflict名称已在 space 中存在。换名或获取现有 config IDQueue 未找到ax annotation-queues list --space SPACE核对 queue 名称或 ID记录未出现在 queue 中确保 queue 关联的 annotation config 存在检查ax annotation-configs list --space SPACESpan SDK 报错或找不到 span核对project_name、space_id与 span IDs用 arize-trace 导出 spans 确认排查顺序建议先确认 config 存在标注的前提再确认 queue 关联正确最后核对 span 标识与时间窗口。八、关联技能与完整评估链路在 awesome-copilot 技能体系中本技能与其它 Arize 技能形成互补skills/arize-trace/SKILL.md导出 spans获取span_id、时间范围与annotation.name.*列的实际落点skills/arize-dataset/SKILL.md查找 dataset ID 与 example ID用于 dataset 示例的标注上下文skills/arize-evaluator/SKILL.mdLLM-as-judge 自动化评估与人工标注形成机器初筛人工抽检/兜底的双轨机制skills/arize-experiment/SKILL.md实验与 dataset、评估工作流绑定skills/arize-link/SKILL.md生成指向 annotation configs 与 queues 的 Arize UI 深链便于团队成员直接打开评审界面。典型端到端流程arize-trace导出 spans 发现质量问题 →arize-annotation建立 config queue 让人工评审 →arize-evaluator对同类指标做自动评估 → 两边结果在 UI 中对比 → 结果回填 spans 用于arize-experiment实验对比。九、会话收尾凭据保存提醒按照 references/ax-profiles.md 的约定会话结束时若用户在本次对话中手动提供过凭据、且这些值并非来自已保存的 profile 或环境变量则应主动询问是否保存Would you like to save your Arize credentials so you dont have to enter them next time?。以下情况跳过保存流程API key 已来自既有 profile 或ARIZE_API_KEYspace 已通过ARIZE_SPACE设置用户只使用了 base64 project ID未涉及 space。保存动作仍走ax profiles create/update --api-key $ARIZE_API_KEYspace 以环境变量方式持久化——全程不触碰原始 key 明文。十、实践清单快速回顾建 config 先行任何标注操作前确认目标 space 中已存在对应的 categorical / continuous / freeform configqueue 编排用ax annotation-queues create挂载 config、指定评审者与assignment-method记住列表类字段是全量替换语义队列内标注annotate-record按 config 名称 upsert--label/--score/--text至少给一个批量回填已有标签时用client.spans.update_annotations一次写回多个 span遵守 DataFrame 列契约与 31 天窗口限制安全纪律凭据只走ax profiles与ax ai-integrations永不读取.env、永不把 key 明文传给命令行参数排障顺序config 存在性 → queue 关联 → span 标识与时间窗口逐层缩小问题范围。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

基于 awesome-copilot 的 Arize 人工标注实战：Annotation Config、Queue 编排与 Python SDK 批量打标

相关推荐

无锡南途科技：AI搜索驱动下内容生态的信任重构

开源提示词模板库实战：从结构化设计到跨模型复用

Agent记忆四层架构与四大流派实战指南

更多资讯

农场管理系统开发：Flask与Django技术选型实战

在 .NET 中使用 Semantic Kernel 集成 AWS Bedrock Agent：环境准备、配置与七个实战示例

Text-to-CAD实战：用自然语言一句话生成可编辑三维模型

中小企业管理软件的关联输入功能设计与实现

大模型任务系统架构设计与JSON Schema驱动开发实践

YOLO目标检测工程实战：从原理拆解到工业部署避坑指南

今日更新

SpacetimeDB C++ 模块库实战：用 C++20 在数据库内构建 WebAssembly 模块

别踩雷！不是所有 AI 写作工具都靠谱，2026 高校认可工具精选

SSM+MySQL幼儿园管理系统源码解析：从部署到优化

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？