Arize Annotation Skill

SPACE — Todas as flags --space e a variável de ambiente ARIZE_SPACE aceitam um nome de espaço (ex: my-workspace) ou um ID de espaço em base64 (ex: U3BhY2U6...). Encontre o seu com ax spaces list.

Esta skill abrange configurações de anotação (o esquema de rótulos) e filas de anotação (fluxos de trabalho de revisão humana), bem como a anotação programática de trechos de projeto via SDK Python.

Direção: A rotulagem humana na Arize anexa valores definidos por configurações a trechos, exemplos de dataset, registros relacionados a experimentos e itens de fila na interface do produto. Esta skill abrange: ax annotation-configs, ax annotation-queues e atualizações em massa de trechos com ArizeClient.spans.update_annotations.

Pré-requisitos

Prossiga diretamente com a tarefa — execute o comando ax que você precisa. NÃO verifique versões, variáveis de ambiente ou perfis antecipadamente.

Se um comando ax falhar, solucione o problema com base no erro:

• Erro de command not found ou de versão → consulte references/ax-setup.md
• 401 Unauthorized / chave de API ausente → execute ax profiles show para inspecionar o perfil atual. Se o perfil estiver ausente ou a chave de API estiver incorreta, siga references/ax-profiles.md para criá-lo/atualizá-lo. Se o usuário não tiver a chave, direcione-o para https://app.arize.com/admin > API Keys
• Espaço desconhecido → execute ax spaces list para escolher por nome, ou pergunte ao usuário
• Segurança: Nunca leia arquivos .env ou procure no sistema de arquivos por credenciais. Use ax profiles para credenciais Arize e ax ai-integrations para chaves de provedores de LLM. Se as credenciais não estiverem disponíveis por meio desses canais, pergunte ao usuário.

Conceitos

O que é uma Configuração de Anotação?

Uma configuração de anotação define o esquema para um único tipo de rótulo de feedback humano. Antes que alguém possa anotar um trecho, registro de dataset, saída de experimento ou item de fila, uma configuração deve existir para esse rótulo no espaço.

Onde os rótulos são aplicados (superfícies)

Sempre garanta que a configuração de anotação relevante exista no espaço antes de esperar que os rótulos persistam.

CRUD Básico: Configurações de Anotação

Listar

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

Criar — Categórico

Configurações categóricas apresentam um conjunto fixo de rótulos para os revisores escolherem.

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

Pares comuns de rótulos binários:

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

Criar — Contínuo

Configurações contínuas permitem que os revisores insiram uma pontuação numérica dentro de um intervalo definido.

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

Criar — Livre

Configurações livres coletam feedback de texto aberto. Nenhum sinalizador adicional é necessário além de nome, espaço e tipo.

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

Obter

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

Excluir

ax annotation-configs delete NOME_OU_ID

…