Annotations

Depois de observar uma aplicação em produção, o próximo passo é anotar e selecionar esses dados para criar datasets de avaliação. Esse processo transforma logs brutos de produção em casos de teste de alta qualidade que impulsionam melhorias sistemáticas.

A Feedback API está obsoleta. As integrações existentes com a Feedback API continuam funcionando. Use Annotations para capturar avaliações, comentários e correções de usuários em requisições concluídas.

Casos de uso

Coleta de feedback de qualidade

Capture avaliações de positivo/negativo, pontuações personalizadas ou rótulos categóricos em respostas de IA. Crie um ciclo de feedback que destaque gerações de baixa qualidade para revisão.

Revisão de compliance e QA

Sinalize respostas com defeitos específicos (alucinação, fuga do tema, conteúdo inadequado) usando chaves de anotação estruturadas compartilhadas por toda a equipe.

Curadoria de datasets

Anote Traces com correções e rótulos de qualidade e, em seguida, exporte subconjuntos selecionados como datasets de treinamento para experimentos futuros.

Fluxos de trabalho human-in-the-loop

Encaminhe Traces para Annotation Queues para uma revisão sistemática por especialistas. Combine com Trace Automations para destacar automaticamente Traces que atendem a critérios específicos.

Conceitos Três conceitos trabalham juntos para formar o sistema de anotações:

Annotations: as categorias de feedback configuradas para um projeto, como uma avaliação de qualidade ou uma tag de defeito
Annotation Queues: fluxos de trabalho organizados para revisar Traces em massa pelo AI Studio
Annotations API: a API e o SDK para aplicar valores de feedback a um Trace ou span de forma programática

Defina schemas de anotação: chaves, tipos de valor e regras de validação. Disponíveis em spans de chat completion e responses assim que criados.

Annotation Queues

Organize fluxos de trabalho de revisão de anotações. Filtre e apresente Traces relevantes para revisão em massa.

Annotations API

Aplique feedback humano estruturado a Traces e spans de forma programática pela API e pelo SDK.

Criar Annotations

Cada anotação precisa ser definida no projeto antes de poder ser usada. A definição estabelece a chave, o título e o tipo de valor; aplicar uma anotação a um Trace exige corresponder a uma dessas definições. As chaves fornecidas pelo workspace, rating e correction, são compartilhadas entre projetos, e cada projeto precisa defini-las antes que seus valores apareçam nas páginas dele.

AI Studio

Para criar uma anotação, acesse Optimization > Annotations no AI Studio, ou Settings > Annotations no AI Gateway, e pressione o botão . As anotações também podem ser criadas diretamente a partir de uma Annotation Queue.Cada anotação usa um de três tipos de valor:

Categorical: opções de botão com rótulos personalizados, como bom/ruim ou salvo/excluído
Range: um controle deslizante de pontuação personalizado, por exemplo, uma escala de 0 a 100
Open field: entrada de texto livre para comentários detalhados

Depois de criada, uma anotação fica disponível em todos os spans de chat completion e de responses do projeto. Nenhuma configuração ou filtragem adicional é necessária.

Selecione o projeto antes de criar uma definição. Uma anotação criada dentro de um projeto pertence a esse projeto, o que mantém o conjunto de anotações de cada projeto focado nas próprias necessidades de revisão. Definições criadas no nível do workspace permanecem disponíveis em todos os projetos.

Excluir uma anotação a remove de todas as Annotation Queues e Experiments que a utilizam, de modo que ela deixa de aparecer como opção de revisão nesses locais. As anotações já registradas em um Trace são preservadas: todos os pontos de dados anotados continuam armazenados e consultáveis.

Annotations comuns Legacy

As chaves rating e correction são compartilhadas em todo o workspace. Um valor gravado em qualquer uma delas só aparece nas páginas de um projeto depois que esse projeto define a mesma anotação.

Avaliação

Avalie a qualidade geral das respostas de IA:

Avaliação	Descrição
good	A resposta foi útil e precisa.
bad	A resposta não foi útil ou foi imprecisa.

Defeitos

Identifique problemas específicos nas respostas de IA:

Defeito	Descrição
grammatical	Respostas que contêm erros gramaticais
spelling	Respostas que contêm erros de ortografia
hallucination	Respostas que contêm alucinações ou imprecisões factuais
repetition	Respostas que contêm repetições desnecessárias
inappropriate	Respostas consideradas inadequadas ou ofensivas
off_topic	Respostas que não abordam a consulta do usuário
incompleteness	Respostas incompletas ou que abordam a consulta apenas parcialmente
ambiguity	Respostas vagas ou pouco claras

É possível selecionar vários defeitos para uma resposta usando uma anotação configurada com um valor do tipo array.

Usar Annotations

As anotações podem ser aplicadas em qualquer lugar onde um Trace ou span seja revisado:

Diretamente em um Trace ou Log: abra um único Trace ou Log na visualização Traces ou Logs e use o painel Annotations.
Em uma Annotation Queue: revise em massa um conjunto selecionado de Traces. Preencha uma fila com Trace Automations ou adicionando manualmente Traces ou Logs individuais.
De forma programática: aplique feedback pela API e pelo SDK usando a aba API & SDK abaixo.
Em um Experiment: aplique anotações enquanto revisa as saídas do experimento.

Toda anotação aplicada em uma Annotation Queue é gravada de volta no Trace de origem. Como os valores ficam no Trace, eles podem ser consultados com o Toqan Router MCP e usados para executar análises sobre os dados revisados.

AI Studio
API & SDK

Os recursos de anotação diferem entre Logs e Traces. Os Logs suportam feedback humano e correções de texto na resposta de IA. Os Traces suportam feedback humano e a correção de um resultado de evaluator.

Traces
Logs

Acesse a visualização Traces e selecione um único trace. O painel Annotations será exibido, permitindo aplicar feedback humano à resposta de IA.

Exemplos rápidos de como anotar respostas de LLM. Para o guia de uso completo (campos da requisição, valores de anotação, correções, semântica de lote e remoção e tratamento de erros), consulte Annotations API.

Adicionar vários defeitos

curl -X POST "https://router.toqan.ai/eu/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "key": "defects",
        "value": ["grammatical", "spelling", "ambiguity"]
      }
    ]
  }'

Adicionar uma pontuação numérica

curl -X POST "https://router.toqan.ai/eu/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "key": "star-rating",
        "value": 4
      }
    ],
    "metadata": {
      "identity_id": "user-123"
    }
  }'

Adicionar uma correção de texto

curl -X POST "https://router.toqan.ai/eu/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "key": "correction",
        "value": "The correct answer should emphasize scalability and fault tolerance."
      }
    ]
  }'

Para tratamento de erros, limites de lote e restrições, consulte Annotations API.

Annotations em Experiments

As anotações também podem ser aplicadas fora das Annotation Queues, durante a revisão das saídas de um Experiment. Na tela de revisão do experimento, as anotações definidas para o projeto aparecem ao lado das pontuações dos Evaluators, para que as saídas possam ser anotadas manualmente como parte de uma execução de avaliação.

A correção de um resultado de Evaluator não está disponível na tela de revisão do experimento. As anotações e as pontuações dos Evaluators continuam sendo exibidas conforme descrito acima.

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

Annotations

Annotations

Annotation Queues

Annotations API

Criar Annotations

Annotations comuns Legacy

Usar Annotations

Annotations em Experiments

Annotations

Annotation Queues

Annotations API

​Criar Annotations

​Annotations comuns Legacy

​Usar Annotations

​Annotations em Experiments

Criar Annotations

Annotations comuns Legacy

Usar Annotations

Annotations em Experiments