Så här kör du en utvärdering i GitHub åtgärd (förhandsversion)

Den här GitHub-åtgärden möjliggör offlineutvärdering av Microsoft Foundry Agents i dina CI/CD-pipelines. Det effektiviserar offlineutvärderingsprocessen, så att du kan identifiera potentiella problem och göra förbättringar innan du släpper en uppdatering till produktion.

Om du vill använda den här åtgärden anger du en datauppsättning med testfrågor och en lista över utvärderare. Den här åtgärden anropar dina agenter med frågorna, kör utvärderingarna och genererar en sammanfattningsrapport.

Funktioner

• Agent Evaluation: Automatisera förhandsproduktionsbedömning av Microsoft Foundry-agenter i ditt CI/CD-arbetsflöde.
• Utvärderare: Använd utvärderare från Foundry-utvärderingskatalogen.
• Statistisk analys: Utvärderingsresultat inkluderar konfidensintervall och test för statistisk signifikans för att avgöra om ändringar är meningsfulla och inte på grund av slumpmässig variation.

Utvärderarkategorier

• Agentutvärderingar: Utvärderare på process- och systemnivå för agentarbetsflöden.
• RAG-utvärderare: Utvärdera processer från slutpunkt till slutpunkt och hämtning i RAG-system.
• Risk- och säkerhetsutvärderare: Bedömer risker och säkerhetsproblem i svar.
• Utvärderare för generell användning: Kvalitetsutvärdering, till exempel konsekvens och flyt.
• OpenAI-baserade granskare: Använd OpenAI-granskare inklusive strängkontroll, textlikhet och poäng/etikettmodell.
• Anpassade utvärderare: Definiera dina egna anpassade utvärderare med hjälp av Python kod eller LLM-as-a-judge-mönster.

Förutsättningar

• Ett projekt. Mer information finns i Skapa ett projekt.
• En Foundry-agent.

Så här konfigurerar du AI-agentutvärderingar

Indata för AI-agentutvärderingar

Parametrar

Datafil

Indatafilen ska vara en JSON-fil med följande struktur:

Grundläggande exempeldatafil

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

Ytterligare exempeldatafiler

Arbetsflöde för AI-agentutvärderingar

Om du vill använda åtgärden GitHub lägger du till åtgärden GitHub i dina CI/CD-arbetsflöden. Ange kriterierna för utlösning, till exempel vid commit, och de filvägar som utlöser dina automatiserade arbetsflöden.

Det här exemplet visar hur du kan köra AI Agent Evaluation när du jämför olika agenter med hjälp av agent-ID:n.

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

Utdata för AI-agentutvärderingar

Utvärderingsresultat skickas till sammanfattningsavsnittet för varje AI-utvärdering GitHub såtgärd som körs under Actions i GitHub. Rapporten visar utvärderingspoäng för varje mått, konfidensintervall och – när du utvärderar flera agenter – en parvis statistisk jämförelse som anger om skillnaderna är meningsfulla eller inom slumpmässig variation.

Följande skärmbild visar en exempelrapport som jämför två agenter.

Använda azd-utvärderingstillägget som en kvalitetsgrind

Du kan använda utvärderingstillägget Azure Developer CLI (azd) för att köra en registrerad utvärdering och blockera en pull-begäran när dess passeringshastighet ligger under ett tröskelvärde. Det här arbetsflödet använder GitHub OpenID Connect (OIDC), så det lagrar ingen klienthemlighet.

Förbereda lagringsplatsen

Innan du konfigurerar arbetsflödet, kontrollera att du har följande:

• En Azure-prenumeration och ett Foundry-projekt som innehåller utvärderingsmålet.
• Administratörsåtkomst för att konfigurera GitHub Actions variabler, hemligheter, miljöer och skyddsregler.
• En incheckad utvärderingsdefinition och deterministisk utvärderingsdatauppsättning.
• Azure Developer CLI (azd), version 1.33.0 eller senare, som krävs av utvärderingstillägget. Installationsinstruktioner finns i Installera Azure Developer CLI.
• Tillägget azure.ai.evaluations , som innehåller utvärderingskommandona. Foundry-paketet azd (microsoft.foundry) innehåller det inte.

azure.ai.evaluations Installera tillägget och kontrollera att utvärderingskommandona är tillgängliga. Kör samma kommandon i arbetsflödet i ett steg när du har installerat azd. Mer information om Foundry-tilläggen finns i Installera Foundry-tilläggen för Azure Developer CLI.

azd ext install azure.ai.evaluations
azd ai eval --help

Konfigurera GitHub OIDC och minsta behörighet

Skapa en Microsoft Entra-applikation eller användartilldelad hanterad identitet och lägg till en federerad identitetsuppgift för token som utfärdats till arbetsflödet. Använd dessa fasta värden:

En repository i en organisation eller ett företag som använder ett oföränderligt anpassat subject kan ha ett subject med den här formen:

repository_owner_id:<owner-id>:repository_id:<repo-id>:pull_request

Referens: OpenID Connect-referens

Kopiera inte ägar- eller repo-ID:t från ett annat repo. Begär en token i arbetsflödet, avkoda nyttolasten utan att skriva ut token och granska endast claimsen iss, aud och sub. Konfigurera den federerade autentiseringsuppgiften så att den matchar de faktiska anspråken exakt. GitHubs standardsubjekt för ett jobb som använder en miljö kan ha en annan form, och en organisation eller ett enterprise kan anpassa subjektanspråket.

Information om konfiguration av arbetsbelastningsidentitet för Microsoft Entra finns i Autentisera mot Azure från GitHub Actions med OpenID Connect.

Tilldela identiteten endast dessa roller:

• Foundry-användare på Foundry-projektnivå.
• Deltagare på omfångsnivån för den dedikerade resursgruppen, om du stämmer av med azd up.

Resursgruppsrollen krävs när du avstäms med azd up, eftersom azd up registrerar en Azure Resource Manager distribution när den etableras. Tilldela inte Contributor på prenumerationsnivå.

Skydda och konfigurera produktionsmiljön

Skapa en skyddad GitHub-miljö med namnet live-evaluation. Lägg till obligatoriska granskare och begränsa driftsättningsgrenar vid behov för din lagringsplats. Mer information finns i Hantera miljöer för driftsättning.

Lagra arbetsflödesvärdena på följande sätt. Lägg inte till AZURE_CLIENT_SECRET; OIDC ersätter det.

Behåll AZD_CONFIG_DIR under RUNNER_TEMP, och autentisera icke-interaktivt:

azd auth login `
  --client-id $env:AZURE_CLIENT_ID `
  --tenant-id $env:AZURE_TENANT_ID `
  --federated-credential-provider github `
  --no-prompt

Referens: Azure CLI-referens för utvecklare

Jobbet måste ha behörighet för contents: read och id-token: write. Gate den så att endast pull-begäranden från samma repo eller en manuell utlösning från standardgrenen kan komma in i den skyddade miljön. Pull-begäranden från fork måste hoppa över jobbet och arbetsflödet får inte använda pull_request_target.

on:
  pull_request:
  workflow_dispatch:

permissions:
  contents: read
  id-token: write

jobs:
  live-evaluation:
    if: >-
      vars.AZD_EVAL_LIVE_PR_GATE == 'true' &&
      ((github.event_name == 'pull_request' &&
      github.event.pull_request.head.repo.full_name == github.repository) ||
      (github.event_name == 'workflow_dispatch' &&
      github.ref_name == github.event.repository.default_branch))
    environment:
      name: live-evaluation

referens: referens för kontexter i GitHub Actions

Fäst varje GitHub Action på en granskad fullständig commit-SHA.

Tillhandahåll en inert-infrastrukturmall när azd up kräver en

Om du avstämmer ett utvärderingsprojekt med azd up i stället för azd ai eval create, tilldelar projektet inga arbetsbelastningsresurser. Om azd up --no-prompt rapporterar att den inte kan hitta eller kompilera infra/main.bicep, lägger du till filen med den här inerta kapslade distributionen:

targetScope = 'resourceGroup'

resource reconciliationMarker 'Microsoft.Resources/deployments@2022-09-01' = {
  name: 'azd-eval-hero-reconciliation'
  properties: {
    mode: 'Incremental'
    template: {
      '$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#'
      contentVersion: '1.0.0.0'
      resources: []
    }
  }
}

Den inre mallen innehåller inga workloadresurser. Markören skapar bara en distributionspost för Azure Resource Manager.

Mer information finns i Microsoft.Resources-distributioner.

Kör den exakta utvärderingen

Behåll livscykeln i den här ordningen:

1. Stäm av den incheckade utvärderingsdefinitionen. Kör azd up --no-prompt när projektet provisionerar infrastruktur. För ett projekt endast för utvärdering, kör azd ai eval create ci-f1-quality --no-prompt i stället. Det här kommandot registrerar de deklarerade datauppsättningarna, utvärderarna och utvärderingen utan att etablera infrastrukturen.
2. Kör azd ai eval run start --eval ci-f1-quality --no-prompt --no-wait -o json.
3. Läs .run_id från den insamlade JSON-filen utan att skriva värdet till loggen.
4. Kör azd ai eval run show <run-id> --eval ci-f1-quality --wait --fail-on pass-rate=0.8 --no-prompt -o json.
5. Exportera den exakta körningen med azd ai eval run output export <run-id> --eval ci-f1-quality --format json --output-file <runner-temp-file> --no-prompt.
6. Verifiera att statusen är slutförd, aggregeringsantal, exporterade rader och tillåtlistade bevis före uppladdning.

Samla in råa standardutdata och standardfel i RUNNER_TEMP. Lagra körnings-ID:t i minnet eller en tillfällig fil och använd det endast som positionsargument för kommandona show och output export.

Använd ett separat GitHub Actions steg för varje livscykelfas. När det lyckas skriver du bara ut en sanerad kommandorad och sammanfattning, till exempel slutförd avstämning, kör accepterad med sitt ID redigerat, slutlig status och antal, gate-utfall, exporterat radantal och förhandsvisning av tillåten evidens.

För --fail-on pass-rate=0.8 är godkännandegrad godkända testfall dividerat med totalt antal testfall. Misslyckade, felaktiga, överhoppade och andra icke godkända rader räknas mot körningen. En giltig slutförd testkörning under tröskelvärdet är en kvalitetsavvikelse. azd CLI slår ihop ett tilläggs avslutskod, så kommandot avslutas med kod 1 för en kvalitetsöverträdelse och för ett driftfel. En kvalitetsöverträdelse skriver ut orsaken för gate och meddelandet evaluation quality gate not met. Autentisering, nätverk, felaktiga eller ofullständiga resultat och exportinkonsekvenser är driftsfel.

Ladda endast upp godkända underlag

Skapa ett nytt underlagsdokument från det verifierade resultatet i stället för att ladda upp råa CLI- eller tjänstutdata. Behåll endast aggregerad status, antal och tröskelvärde, plus dessa fält för varje granskat exempel: query, response, ground_truth, scoreoch passed.

{
  "status": "completed",
  "counts": {
    "passed": 2,
    "failed": 0,
    "errored": 0
  },
  "threshold": 0.8,
  "samples": [
    {
      "query": "<allowlisted query>",
      "response": "<allowlisted response>",
      "ground_truth": "<allowlisted ground truth>",
      "score": 1.0,
      "passed": true
    }
  ]
}

Kontrollera att artefaktkatalogen endast innehåller den förväntade bevisfilen före uppladdningen. Skriv aldrig ut eller ladda upp JWT:er, endpoints, run-ID:n, autentiseringsuppgifter, userinfo, URL-frågesträngar eller råautentisering, CLI eller service payloads. Behåll rådatafiler i tillfällig lagring, maskera insamlad feldiagnostik och ta bort filerna i en always()- eller finally-rensningssökväg.

Kontrollera gatewayen

Kör arbetsflödet manuellt från standardgrenen innan du aktiverar pull request-spärr. Bekräfta att:

1. OIDC-autentisering lyckas utan en klienthemlighet.
2. Avstämningssteget registrerar den incheckade bedömningen.
3. Asynkron start godkänns utan att körnings-ID:t visas.
4. Kommandot show rapporterar completed och tillämpar tröskelvärdet för godkännandegrad för 0.8.
5. Exporten innehåller endast rader från den exakta körningen.
6. Den uppladdade artefakten innehåller endast schemat för tillåtlistade bevis.
7. Råa runner-temporära filer tas bort vid lyckat och misslyckat resultat.

Felsök grinden

Efter verifieringen tar du bort tillfälliga testresurser och rolltilldelningar som du inte längre behöver. Ta bort tillfälliga federerade autentiseringsuppgifter och behåll endast den dedikerade resursgruppen om kvalitetsgrinden fortsätter att använda den.

Relaterat innehåll

• Evaluation i Azure DevOps
• Köra agentutvärderingar med azd CLI
• Installera CLI Foundry-tilläggen för Azure Developer
• Så här utvärderar du generativa AI-modeller och program med Microsoft Foundry
• Så här visar du utvärderingsresultat i Foundry-portalen