> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Annotations > Defina esquemas de anotação e aplique feedback humano estruturado a traces e spans de LLM no AI Studio, pela API e pelo SDK ou pela CLI. 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. > [!NOTE] > > **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** > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] 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 > [card] [Annotations](#create-annotations) > > 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. > [card] [Annotation Queues](/docs/pt-BR/ai-studio/observability/annotation-queues.md#use-annotation-queues) > > Organize fluxos de trabalho de revisão de anotações. Filtre e apresente Traces relevantes para revisão em massa. > [card] [Annotations API](/docs/pt-BR/ai-studio/observability/annotations-api.md) > > 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. > [tab] 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](/docs/pt-BR/ai-studio/observability/annotation-queues.md#use-annotation-queues). > > 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 > > > [!NOTE] > > > > 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. > > > [!TIP] > > > > 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. > > > [!NOTE] > > > > 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 > [!NOTE] > > 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. > [accordion] 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. | > [accordion] 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 | > > > [!NOTE] > > > > É 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](/docs/pt-BR/ai-studio/observability/traces.md) ou Logs e use o painel **Annotations**. * **Em uma [Annotation Queue](/docs/pt-BR/ai-studio/observability/annotation-queues.md#use-annotation-queues)**: revise em massa um conjunto selecionado de Traces. Preencha uma fila com [Trace Automations](/docs/pt-BR/ai-studio/observability/automations.md) 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](#annotations-in-experiments)**: aplique anotações enquanto revisa as saídas do experimento. > [!NOTE] > > 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. > [tab] AI Studio > > Os recursos de anotação diferem entre Logs e [Traces](/docs/pt-BR/ai-studio/observability/traces.md). 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](/docs/pt-BR/ai-studio/observability/traces.md#correct-an-evaluator-result). > > > [tab] Traces > > > > Acesse a visualização [Traces](/docs/pt-BR/ai-studio/observability/traces.md) e selecione um único trace. O painel **Annotations** será exibido, permitindo aplicar feedback humano à resposta de IA. > > > [tab] Logs > > > > Acesse a visualização Logs e selecione um único log. O painel **Annotations** será exibido, permitindo aplicar feedback humano e fornecer correções à resposta de IA. > > > > Para fazer uma correção, use o botão **Add correction** abaixo da resposta gerada pela IA: > > > > Clique para adicionar uma correção, o que abre um editor para revisar manualmente a resposta do modelo. Selecione **Save** para armazenar a correção. > > > > > [!NOTE] > > > > > > As correções são valiosas para criar datasets selecionados. Saiba mais em Criando um dataset selecionado. > [tab] API & SDK > > 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](/docs/pt-BR/ai-studio/observability/annotations-api.md). > > > [accordion] Adicionar vários defeitos > > > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > > 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"] > > } > > ] > > }' > > ``` > > > [accordion] Adicionar uma pontuação numérica > > > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > > 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" > > } > > }' > > ``` > > > [accordion] Adicionar uma correção de texto > > > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > > 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." > > } > > ] > > }' > > ``` > > > [!NOTE] > > > > Para tratamento de erros, limites de lote e restrições, consulte [Annotations API](/docs/pt-BR/ai-studio/observability/annotations-api.md#error-handling). ## 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. > [!NOTE] > > A [correção de um resultado de Evaluator](/docs/pt-BR/ai-studio/observability/traces.md#correct-an-evaluator-result) 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.