Executar avaliações off-line

Prévia: avaliação de agentes na plataforma de agentes do Gemini Enterprise

Esse recurso está sujeito aos "Termos da solução pré-GA" na seção Termos gerais de serviço dos Termos específicos de serviço, bem como aos Termos específicos de serviço de IA generativa. Esse recurso permite que os clientes avaliem agentes de IA. Portanto, os Termos específicos de serviço de "Serviços de IA agêntica" se aplicam. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

A avaliação off-line permite medir a performance, a segurança e a qualidade dos seus agentes analisando dados históricos capturados durante o desenvolvimento ou a produção. É possível avaliar rastros individuais (caminhos de execução única) ou sessões completas (históricos de conversas com várias interações) em relação a um conjunto de métricas predefinidas ou personalizadas.

Rastros x sessões

• Rastro:um registro factual e imutável do comportamento do agente, incluindo entradas de modelo, respostas e chamadas de ferramentas. Um rastro representa um único caminho de execução.
• Sessão:abrange toda a interação com várias interações entre um usuário e um agente. Use sessões para avaliar a retenção de contexto e o fluxo conversacional ao longo do tempo.

Antes de começar

Para garantir que você tenha os dados e o ambiente necessários para a avaliação off-line, faça o seguinte:

• Verifique se você tem um ambiente de execução de agente funcionando e implantado com o Cloud Trace ativado.
• Configure um bucket do Cloud Storage para armazenar os resultados da avaliação. Você só precisa fornecer esse caminho uma vez. Ele será preenchido previamente para execuções futuras.
• Se você planeja usar o SDK da plataforma de agentes para avaliação, inicialize o cliente conforme descrito em Avaliar seus agentes.

Requisitos de telemetria

A avaliação off-line exige que o agente exporte indicadores específicos do OpenTelemetry para fornecer o contexto necessário para a avaliação. Esses requisitos são idênticos aos dos monitores on-line:

1. Abrangência do agente de invocação: precisa incluir os seguintes atributos:

   • gen_ai.agent.name: o identificador do agente.
   • gen_ai.agent.description: uma breve descrição da finalidade do agente.
   • gen_ai.conversation.id: um identificador exclusivo para a sessão de conversa específica.

2. Eventos de inferência: o evento gen_ai.client.inference.operation.details precisa capturar:

   • gen_ai.input.messages: os comandos enviados ao agente.
   • gen_ai.output.messages: as respostas geradas pelo agente.
   • gen_ai.system_instructions: os comandos do sistema subjacente.
   • gen_ai.tool.definitions: metadados sobre todas as ferramentas disponíveis para o agente.

Se você estiver usando o Kit de desenvolvimento de agentes, será necessário ativar esses recursos de telemetria definindo as seguintes variáveis de ambiente:

OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'

Gravação de mídia no Cloud Storage

Se o agente usar dados multimodais, como imagens ou documentos grandes, recomendamos gravar as entradas e saídas em um bucket do Cloud Storage em vez de incorporá-las diretamente em abrangências de rastreamento. Configure as seguintes variáveis de ambiente para ativar isso:

OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl'
OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK='upload'
OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH='gs://STORAGE_BUCKET_NAME/PATH'

Para mais informações, consulte Coletar comandos e respostas multimodais.

Criar uma avaliação no registro

1. No Google Cloud console, acesse a página Plataforma de agentes > Agentes > Avaliação.

   Acessar a avaliação

2. Clique em Nova avaliação.

3. Selecione a guia Traces ou Sessões com base na meta de avaliação.

4. Use o ícone de filtro e o seletor de tempo para filtrar dados (por exemplo, por versão ou "Últimas 2 semanas") e selecione os IDs específicos que você quer avaliar.

5. Clique em Continuar.

6. (Opcional) No campo Nome da avaliação, insira um nome para a avaliação ou use o padrão preenchido.

7. No campo Caminho de dados particulares de saída, insira o URI do bucket do Cloud Storage. Após o primeiro uso, esse caminho será preenchido previamente para execuções futuras.

8. Por padrão, todas as quatro métricas principais são adicionadas. Você pode adicionar ou remover métricas conforme necessário.

9. Clique em Avaliar agente.

Avaliar um único rastro ou sessão

É possível acionar avaliações diretamente ao inspecionar caminhos de execução individuais:

1. No Google Cloud console, acesse a página Plataforma de agentes > Agentes.
2. No menu de navegação à esquerda, selecione Implantações.
3. Selecione seu agente.

   Acessar "Implantações"

4. Selecione a guia Rastros.
5. Clique em Visualização da sessão ou Visualização do rastro para inspecionar o caminho de execução.
6. Selecione uma linha específica na tabela para abrir o painel de detalhes.
7. Selecione a guia Avaliação.
8. Se o rastro ou a sessão não tiver sido avaliado, clique em Avaliar para executar uma avaliação ad hoc.

Visualizar os resultados da avaliação

Depois que a avaliação for concluída, você poderá analisar os resultados para identificar lacunas de performance e problemas sistêmicos:

• Conferir os resultados de uma execução:no Google Cloud console, acesse a página Plataforma de agentes > Agentes > Avaliação e selecione a guia Avaliações. Clique em um nome de avaliação para conferir o relatório detalhado.

  Acessar a avaliação

• Detalhar os rastros:em um relatório de resultados, clique em qualquer linha para navegar diretamente até o rastro associado e inspecionar o raciocínio (justificativas) por trás das pontuações.

Para mais informações, consulte Analisar os resultados da avaliação.