Como executar uma avaliação no GitHub Action (versão prévia)

Importante

Itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou ter recursos restritos. Para obter mais informações, consulte Supplemental Terms of Use for Microsoft Azure Previews.

Esta GitHub Action permite a execução de avaliações offline dos Microsoft Foundry Agents em seus pipelines de CI/CD. Ele simplifica o processo de avaliação offline, para que você possa identificar possíveis problemas e fazer melhorias antes de lançar uma atualização para a produção.

Para usar essa ação, forneça um conjunto de dados com consultas de teste e uma lista de avaliadores. Essa ação invoca seus agentes com as consultas, executa as avaliações e gera um relatório de resumo.

Características

Agent Evaluation: Automatize a avaliação de pré-produção dos agentes Microsoft Foundry no fluxo de trabalho de CI/CD.
Avaliadores: use qualquer avaliador do catálogo de avaliadores do Foundry.
Análise Estatística: os resultados da avaliação incluem intervalos de confiança e teste de significância estatística para determinar se as alterações são significativas e não devido à variação aleatória.

Categorias de avaliador

Avaliadores de agentes: avaliadores de processos e de nível de sistema para fluxos de trabalho dos agentes.
Avaliadores RAG: Avaliam os processos de ponta a ponta e de recuperação em sistemas RAG.
Avaliadores de risco e segurança: avalie os riscos e as preocupações com a segurança nas respostas.
Avaliadores de finalidade geral: avaliação de qualidade, como coerência e fluência.
Avaliadores baseados em OpenAI: Use avaliadores OpenAI, incluindo verificação de string, similaridade de texto, modelo de pontuação/rótulo.
Avaliadores Personalizados: defina seus próprios avaliadores personalizados usando código Python ou padrões LLM-as-a-judge.

Pré-requisitos

Um projeto. Para saber mais, confira Criar um projeto.
Um agente do Foundry.

Dica

A maneira recomendada de autenticar é usando Microsoft Entra ID, que você pode usar para se conectar com segurança aos recursos do Azure. Você pode automatizar o processo de autenticação usando a ação Azure Logon GitHub. Para saber mais, consulte Ação de logon do Azure com OpenID Connect.

Como configurar avaliações do agente de IA

Entrada para avaliações do agente de IA

Parâmetros

Nome	Necessário?	Descrição
azure-ai-project-endpoint	Sim	Ponto de extremidade do Projeto Microsoft Foundry. Para encontrar esse valor, abra seu projeto no portal do Foundry e copie o ponto de extremidade da página Visão geral .
nome da implantação	Sim	O nome de uma implantação de modelo de IA Azure a ser usada para avaliação. Encontre as implantações existentes em Modelos + endpoints no portal do Foundry.
caminho de dados	Sim	Caminho para o arquivo de dados que contém os avaliadores e as consultas de entrada para avaliações.
ids de agente	Sim	ID de um ou mais agentes a serem avaliados em formato `agent-name:version` (por exemplo, `my-agent:1` ou `my-agent:1,my-agent:2`). Vários agentes são separados por vírgula e comparados com os resultados do teste estatístico.
baseline-agent-id	Não	ID do agente de linha de base com a qual comparar ao avaliar vários agentes. Se não for fornecido, o primeiro agente será usado.

Nota

Para localizar a ID e a versão do agente, abra seu projeto no portal do Foundry, acesse Agentes, selecione seu agente e copie a ID do Agente no painel de detalhes. A versão é o número da versão da implantação (por exemplo, my-agent:1).

Arquivo de dados

O arquivo de dados de entrada deve ser um arquivo JSON com a seguinte estrutura:

Campo	Tipo	Necessário?	Descrição
Nome	cadeia	Sim	Nome do conjunto de dados de avaliação.
avaliadores	string[]	Sim	Lista de nomes de avaliadores a serem usados. Confira a lista de avaliadores disponíveis no catálogo de avaliadores do seu projeto no portal Foundry: Catálogo de Avaliadores > de Build >.
dados	objeto[]	Sim	Matriz de objetos de entrada, com `query` e campos de avaliador opcionais, como `ground_truth`, `context`. Automatizada para avaliadores; use `data_mapping` para substituir.
openai_graders	objeto	Não	Configuração para avaliadores baseados em OpenAI (label_model, score_model, string_check etc.).
evaluator_parameters	objeto	Não	Parâmetros de inicialização específicos do avaliador (por exemplo, limites, configurações personalizadas).
mapeamento de dados	objeto	Não	Mapeamentos de campo de dados personalizados (gerados automaticamente de dados, se não fornecidos).

Arquivo de dados de exemplo básico

{
  "name": "test-data",
  "evaluators": [
    "builtin.fluency",
    "builtin.task_adherence",
    "builtin.violence"
  ],
  "data": [
    {
      "query": "Tell me about Tokyo disneyland"
    },
    {
      "query": "How do I install Python?"
    }
  ]
}

Arquivos de dados de exemplo adicionais

Nome do Arquivo	Descrição
dataset-tiny.json	Conjunto de dados com um pequeno número de consultas de teste e avaliadores.
dataset.json	Conjunto de dados com todos os tipos de avaliador compatíveis e consultas suficientes para cálculo de intervalo de confiança e teste estatístico.
dataset-builtin-evaluators.json	Exemplo de avaliadores internos do Foundry (por exemplo, coerência, fluência, relevância, fundamentação, métricas).
dataset-openai-graders.json	Exemplo de classificadores baseados em OpenAI (modelos de rótulo, modelos de pontuação, similaridade de texto, verificações de cadeia de caracteres).
dataset-custom-evaluators.json	Exemplo de avaliadores personalizados com parâmetros de avaliador.
dataset-data-mapping.json	Exemplo de mapeamento de dados mostrando como substituir mapeamentos automáticos de campo com nomes de coluna de dados personalizados.

Fluxo de trabalho de avaliações do agente de IA

Para usar a Ação GitHub, adicione a Ação GitHub aos fluxos de trabalho de CI/CD. Especifique os critérios de gatilho, como na confirmação, e os caminhos de arquivo para disparar seus fluxos de trabalho automatizados.

Dica

Para minimizar os custos, não execute a avaliação em cada commit.

Este exemplo mostra como você pode executar a Avaliação do Agente de IA ao comparar diferentes agentes usando IDs de agente.

name: "AI Agent Evaluation"

on:
  workflow_dispatch:
  push:
    branches:
      - main

permissions:
  id-token: write
  contents: read

jobs:
  run-action:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Azure login using Federated Credentials
        uses: azure/login@v2
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

      - name: Run Evaluation
        uses: microsoft/ai-agent-evals@v3-beta
        with:
          # Replace placeholders with values for your Foundry Project
          azure-ai-project-endpoint: "<your-ai-project-endpoint>"
          deployment-name: "<your-deployment-name>"
          agent-ids: "<your-ai-agent-ids>"
          data-path: ${{ github.workspace }}/path/to/your/data-file

Resultados das avaliações do agente de IA

Os resultados da avaliação são gerados para a seção resumo de cada ação de avaliação de IA GitHub executada em Actions no GitHub. O relatório mostra as pontuações de avaliação para cada métrica, intervalos de confiança e , quando você avalia vários agentes, uma comparação estatística emparelhada que indica se as diferenças são significativas ou dentro da variação aleatória.

A captura de tela a seguir mostra um relatório de exemplo comparando dois agentes.

Comentários

Esta página foi útil?

Last updated on 2026-04-30