Een evaluatie uitvoeren in GitHub Actie (preview)

Belangrijk

Items die zijn gemarkeerd als voorbeeld in dit artikel, zijn momenteel beschikbaar als preview-versie. Deze preview wordt aangeboden zonder een service level agreement en Microsoft raadt dit niet aan voor productieworkloads. Bepaalde functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure previews voor meer informatie.

Met deze GitHub Action kunt u offline evaluatie uitvoeren van Microsoft Foundry Agents in uw CI/CD-pipelines. Het stroomlijnt het offline evaluatieproces, zodat u potentiële problemen kunt identificeren en verbeteringen kunt aanbrengen voordat u een update voor productie publiceert.

Als u deze actie wilt gebruiken, geeft u een gegevensset op met testquery's en een lijst met evaluators. Met deze actie worden uw agents aangeroepen met de query's, worden de evaluaties uitgevoerd en wordt een overzichtsrapport gegenereerd.

Functies

  • Agent Evaluation: Automatiseer de evaluatie vooraf van Microsoft Foundry-agents in uw CI/CD-werkstroom.
  • Evaluators: Gebruik alle evaluators uit de Foundry-evaluatorcatalogus.
  • Statistische analyse: evaluatieresultaten omvatten betrouwbaarheidsintervallen en test op statistische significantie om te bepalen of wijzigingen zinvol zijn en niet vanwege willekeurige variatie.

De categorieën van evaluatoren

Voorwaarden

Tip

De aanbevolen manier om te verifiëren is met behulp van Microsoft Entra ID, die u kunt gebruiken om veilig verbinding te maken met uw Azure-resources. U kunt het verificatieproces automatiseren met behulp van de actie Azure Login GitHub. Zie Azure aanmeldingsactie met OpenID Connect voor meer informatie.

Hoe AI-agentevaluaties in te stellen

Invoer voor AI-agentevaluaties

Parameters

Naam Vereist? Beschrijving
azure-ai-project-endpoint Ja Eindpunt van uw Microsoft Foundry-Project. Als u deze waarde wilt vinden, opent u uw project in de Foundry-portal en kopieert u het eindpunt op de overzichtspagina .
implementatienaam Ja De naam van een Azure AI-modelimplementatie die moet worden gebruikt voor evaluatie. Zoek bestaande implementaties onder Modellen en eindpunten in de Foundry-portal.
gegevenspad Ja Pad naar het bestand met de beoordelaars en invoeropdrachten voor evaluaties.
agent-IDs Ja ID van een of meer agents die moeten worden geëvalueerd in het formaat agent-name:version (bijvoorbeeld my-agent:1 of my-agent:1,my-agent:2). Meerdere agents worden door komma's gescheiden en vergeleken met statistische testresultaten.
basislijn-agent-id Nee Id van de basislijnagent die moet worden vergeleken bij het evalueren van meerdere agents. Als deze niet is opgegeven, wordt de eerste agent gebruikt.

Opmerking

Als u uw agent-id en versie wilt vinden, opent u uw project in de Foundry-portal, gaat u naar Agents, selecteert u uw agent en kopieert u de agent-id in het detailvenster. De versie is het versienummer van de implementatie (bijvoorbeeld my-agent:1).

Gegevensbestand

Het invoergegevensbestand moet een JSON-bestand met de volgende structuur zijn:

Veld Type Vereist? Beschrijving
Naam string Ja Naam van de evaluatiegegevensset.
Beoordelaars string[] Ja Lijst met te gebruiken evaluatornamen. Bekijk de lijst met beschikbare evaluatoren in de evaluatiecatalogus van je project in Foundry portal: Evaluaties Evaluatorcatalogus Bouwen.
Gegevens object[] Ja Matrix van invoerobjecten met query en optionele evaluatorvelden zoals ground_truth, context. Automatisch toegewezen voor beoordelaars; gebruik data_mapping om te overschrijven.
openai_graders Object Nee Configuratie voor op OpenAI gebaseerde evaluators (label_model, score_model, string_check, enzovoort).
evaluator_parameters Object Nee Evaluatiespecifieke initialisatieparameters (bijvoorbeeld drempelwaarden, aangepaste instellingen).
gegevenskoppeling Object Nee Aangepaste gegevensveldtoewijzingen (automatisch gegenereerd op basis van gegevens indien niet opgegeven).

Eenvoudig voorbeeldgegevensbestand

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

Aanvullende voorbeeldgegevensbestanden

Bestandsnaam Beschrijving
dataset-tiny.json Gegevensset met een klein aantal testquery's en evaluators.
dataset.json Gegevensset met alle ondersteunde evaluatortypen en voldoende query's voor berekening van betrouwbaarheidsinterval en statistische test.
dataset-builtin-evaluators.json Voorbeeld van ingebouwde Foundry-evaluators (bijvoorbeeld coherentie, vloeiendheid, relevantie, verankering, meetwaarden).
dataset-openai-graders.json Voorbeeld van op OpenAI gebaseerde graders (labelmodellen, scoremodellen, overeenkomsten met tekst, tekenreekscontroles).
dataset-custom-evaluators.json Voorbeeld van aangepaste evaluators met de evaluatorparameters.
dataset-data-mapping.json Voorbeeld van gegevenstoewijzing waarin wordt getoond hoe u automatische veldtoewijzingen overschrijft met aangepaste kolomnamen van gegevens.

Werkstroom voor evaluaties van AI-agents

Als u de GitHub-actie wilt gebruiken, voegt u de GitHub-actie toe aan uw CI/CD-werkstromen. Geef de triggercriteria op, zoals bij doorvoeren en de bestandspaden om uw geautomatiseerde werkstromen te activeren.

Tip

Als u de kosten wilt minimaliseren, moet u niet elke doorvoering evalueren.

In dit voorbeeld ziet u hoe u ai-agentevaluatie kunt uitvoeren wanneer u verschillende agents vergelijkt met behulp van agent-id's.

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

Uitvoer van AI-agentevaluaties

Evaluatieresultaten worden uitgevoerd in de samenvattingssectie voor elke AI-evaluatie-GitHub-actie die wordt uitgevoerd onder Actions in GitHub. In het rapport worden evaluatiescores weergegeven voor elke metrische waarde, betrouwbaarheidsintervallen en , wanneer u meerdere agents evalueert, een paarsgewijze statistische vergelijking die aangeeft of verschillen zinvol of binnen willekeurige variatie zijn.

In de volgende schermopname ziet u een voorbeeldrapport waarin twee agents worden vergeleken.

Schermafbeelding van GitHub Actions werkstroomoverzicht met scoren voor agentevaluatie met betrouwbaarheidsintervallen en paarsgewijze statistische vergelijking voor twee agents.

Gebruik de azd-evaluatie-extensie als kwaliteitscontrole

U kunt de Azure Developer CLI-evaluatieextensie (azd) gebruiken om een geregistreerde evaluatie uit te voeren en een pull-aanvraag te blokkeren wanneer het slagingspercentage lager is dan een drempelwaarde. Deze werkstroom maakt gebruik van GitHub OpenID Connect (OIDC), zodat er geen clientgeheim wordt opgeslagen.

De opslagplaats voorbereiden

Voordat u de werkstroom configureert, moet u het volgende doen:

  • Een Azure-abonnement en een Foundry-project dat het evaluatiedoel bevat.
  • Beheerderstoegang voor het configureren van GitHub Actions variabelen, geheimen, omgevingen en beveiligingsregels.
  • Een ingecheckte evaluatiedefinitie en deterministische evaluatiegegevensset.
  • De Azure Developer CLI (azd), versie 1.33.0 of hoger, die vereist is voor de evaluatie-extensie. Zie Install the Azure Developer CLI voor installatie-instructies.
  • De azure.ai.evaluations extensie, die de evaluatieopdrachten levert. Het Foundry-pakket azd (microsoft.foundry) bevat het niet.

Installeer de azure.ai.evaluations extensie en controleer of de evaluatieopdrachten beschikbaar zijn. Voer in uw werkstroom dezelfde opdrachten uit in een stap nadat u azd hebt geïnstalleerd. Zie De Azure Developer CLI Foundry-extensies installeren voor meer informatie over de Foundry-extensies van Foundry.

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

GitHub OIDC en minimale bevoegdheden configureren

Maak een Microsoft Entra app of door de gebruiker toegewezen beheerde identiteit en voeg federatieve identiteitsaanmeldingsgegevens toe voor het token dat is uitgegeven aan de workflow. Gebruik deze vaste waarden:

Federatieve aanmeldingsgegevensveld Value
Issuer https://token.actions.githubusercontent.com
Audiëntie api://AzureADTokenExchange
Subject De exacte sub claim in het GitHub OIDC-token

Een repository in een organisatie of onderneming die gebruikmaakt van een onveranderbaar aangepast subject kan een subject met deze vorm hebben:

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

Naslaginformatie: OpenID Connect-verwijzing

Kopieer geen eigenaar- of repository-id's uit een andere repository. Vraag een token aan in uw werkstroom, decodeer de payload zonder het token af te drukken en inspecteer alleen de iss, aud en sub claims. Configureer de federatieve referentiegegevens zodat deze exact overeenkomen met de werkelijke claims. GitHub standaardonderwerp voor een taak die gebruikmaakt van een omgeving, kan een andere vorm hebben en een organisatie of onderneming kan de onderwerpclaim aanpassen.

Zie Verifiëren bij Azure vanuit GitHub Actions met OpenID Connect voor het instellen van Microsoft Entra-workloadidentiteit.

Wijs alleen deze rollen toe aan de identiteit:

  • Foundry User op Foundry-projectniveau.
  • Bijdrager op het toegewezen bereik van de resourcegroep, als u dit afstemt met azd up.

Belangrijk

De rollen Foundry RBAC zijn onlangs hernoemd. Foundry User, Foundry Owner, Foundry Account Owner en Foundry Project Manager zijn eerder benoemd Azure AI-gebruiker, Azure AI-eigenaar Azure AI-accounteigenaar en Azure AI Project Manager. Het kan zijn dat u op sommige plekken nog steeds de vorige namen ziet terwijl de naamswijziging wordt doorgevoerd. De rol-id's en basismachtigingen worden niet gewijzigd door de naamswijziging.

De resourcegroepresourcerol is vereist wanneer u met azd up synchroniseert, omdat azd up een Azure Resource Manager-implementatie registreert wanneer deze resources inricht. Wijs Contributor niet toe aan het abonnementsbereik.

De liveomgeving beveiligen en configureren

Maak een beveiligde GitHub-omgeving met de naam live-evaluation. Voeg vereiste revisoren toe en beperk implementatiebranches indien nodig voor uw opslagplaats. Zie Omgevingen beheren voor implementatie voor meer informatie.

Sla de werkstroomwaarden als volgt op. Voeg AZURE_CLIENT_SECRET niet toe; OIDC vervangt het.

Naam GitHub-opslag Purpose
AZURE_CLIENT_ID live-evaluation omgevingssleutel Microsoft Entra client-id van de toepassing of beheerde identiteit.
AZURE_TENANT_ID live-evaluation environment secret Tenant-id van Microsoft Entra.
AZURE_SUBSCRIPTION_ID live-evaluation omgevingsgeheimen Abonnement dat de toegewezen resourcegroep bevat.
AZURE_AI_PROJECT_ENDPOINT live-evaluation secret van de omgeving Foundry-projecteindpunt dat wordt gebruikt door de evaluatie-extensie.
AZURE_LOCATION live-evaluation omgevingsvariabele Azure regio voor de azd omgeving.
AZURE_RESOURCE_GROUP live-evaluation omgevingsvariabele Speciale resourcegroep voor afstemmingsmetagegevens.
AZD_EVAL_LIVE_PR_GATE repositoryvariabele Ingesteld op de exacte waarde true om de livetaak in te schakelen.

Houd AZD_CONFIG_DIR onder RUNNER_TEMP, en verifieer niet-interactief:

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

Naslaginformatie: naslaginformatie voor Azure Developer CLI

De taak moet beschikken over id-token: write en contents: read machtigingen. Gate it zodat alleen pull requests voor dezelfde repository of handmatige dispatch vanuit de default branch toegang kunnen krijgen tot de beveiligde omgeving. Pull-aanvragen voor fork moeten de taak overslaan en de werkstroom mag pull_request_target niet gebruiken.

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

Naslaginformatie: GitHub Actions-contexten

Maak elke GitHub-actie vast aan een beoordeelde volledige commit-SHA.

Een inerte infrastructuursjabloon opgeven wanneer azd up er een vereist

Als u een alleen-evaluatieproject op azd up afstemt in plaats van op azd ai eval create, richt het project geen workloadresources in. Als azd up --no-prompt meldt dat het infra/main.bicep niet kan vinden of compileren, voegt u dat bestand toe met deze geneste inerte deployment:

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: []
    }
  }
}

Het interne sjabloon bevat geen workload-resources. De marker maakt alleen een implementatierecord voor Azure Resource Manager aan.

Zie Microsoft.Resources-implementaties voor meer informatie.

De exacte evaluatie uitvoeren

Houd de levenscyclus in deze volgorde:

  1. De ingecheckte evaluatiedefinitie vergelijken. Voer azd up --no-prompt uit wanneer het project infrastructuur inricht. Voor een evaluatieproject voert u in plaats daarvan de opdracht azd ai eval create ci-f1-quality --no-prompt uit. Met dit commando worden de gedeclareerde datasets, evaluators en evaluatie geregistreerd zonder infrastructuur in te richten.
  2. Voer azd ai eval run start --eval ci-f1-quality --no-prompt --no-wait -o jsonuit.
  3. Lees .run_id vanuit de vastgelegde JSON zonder de waarde naar het logboek te schrijven.
  4. Voer azd ai eval run show <run-id> --eval ci-f1-quality --wait --fail-on pass-rate=0.8 --no-prompt -o jsonuit.
  5. Exporteer die exacte run met azd ai eval run output export <run-id> --eval ci-f1-quality --format json --output-file <runner-temp-file> --no-prompt.
  6. Valideer de voltooide status, het totaalaantal, de geëxporteerde rijen en bewijs op de allowlist voordat u uploadt.

Onbewerkte standaarduitvoer en standaardfout vastleggen in RUNNER_TEMP. Sla de uitvoerings-id op in het geheugen of een tijdelijk runner-bestand en gebruik deze alleen als het positionele argument voor de show en output export opdrachten.

Gebruik een afzonderlijke GitHub Actions stap voor elke levenscyclusfase. Bij succes kunt u alleen een opgeschoonde opdrachtregel en samenvatting afdrukken, zoals afstemming voltooid, uitvoering geaccepteerd waarbij de ID is gemaskeerd, uiteindelijke status en tellingen, uitkomst van de controle, geëxporteerd aantal rijen en de preview van bewijs op de allowlist.

Voor --fail-on pass-rate=0.8 is de pass rate het aantal geslaagde testcases gedeeld door het totale aantal testcases. Mislukte, foutieve, overgeslagen en anderszins niet-geslaagde rijen tellen mee voor de uitvoering. Een geldig voltooide run onder de drempelwaarde is een kwaliteitsschending. De azd CLI reduceert de exitcode van een extensie tot één code, dus de opdracht wordt afgesloten met code 1 voor een kwaliteitsschending en voor een operationele fout. Een kwaliteitsschending drukt de reden van de poort en het bericht evaluation quality gate not met af. Authenticatie, netwerk, onjuiste of onvolledige resultaten en inconsistenties bij export zijn operationele fouten.

Upload alleen bewijzen die op de allowlist staan

Maak een nieuw bewijsdocument op basis van het gevalideerde resultaat in plaats van onbewerkte CLI- of service-uitvoer te uploaden. Alleen de geaggregeerde status, aantallen en drempelwaarde behouden, plus deze velden voor elk gecontroleerd voorbeeld: query, response, ground_truth, score, en 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
    }
  ]
}

Controleer vóór het uploaden of de artefactmap alleen het verwachte bewijsbestand bevat. Druk nooit JWT's, eindpunten, run-ID's, inloggegevens, gebruikersinfo, URL-queryreeksen of ruwe authenticatie-, CLI- of servicepayloads af en upload deze nooit. Bewaar onbewerkte bestanden in runner-tijdelijke opslag, maskeer vastgelegde foutdiagnosegegevens en verwijder de bestanden in een always()- of finally-opschoonpad.

Controleer de poort

Voer de workflow handmatig uit in de standaardbranch voordat u pullrequestblokkering inschakelt. Bevestig dat:

  1. OIDC-verificatie slaagt zonder clientgeheim.
  2. De afstemmingsstap registreert de ingediende evaluatie.
  3. De asynchrone start wordt geaccepteerd zonder de uitvoerings-id weer te geven.
  4. Het show commando rapporteert completed en dwingt de 0.8 slagingspercentagedrempel af.
  5. De export bevat alleen rijen van de exacte run.
  6. Het geüploade artefact bevat alleen het toegestane bewijsschema.
  7. Onbewerkte tijdelijke runner-bestanden worden zowel bij succes als bij mislukking verwijderd.

Problemen met de poort oplossen

Symptom Oplossing
Microsoft Entra ID weigert het federatieve token. Vergelijk de werkelijke iss, aud en sub claims van het token met de gefedereerde referentie. Ga er niet van uit dat er een environment-subject is en kopieer niet de id's van een andere repository.
azd up rapporteert een ontbrekend abonnement, locatie of resourcegroep. Configureer AZURE_SUBSCRIPTION_ID, AZURE_LOCATIONen AZURE_RESOURCE_GROUP in de beveiligde omgeving en geef ze door aan de taak.
azd up kan infra/main.bicep niet vinden of compileren. Voeg de inerte infrastructuursjabloon toe die in dit artikel wordt beschreven, of maak in plaats daarvan een evaluatieproject compatibel met azd ai eval create.
azd ai eval is geen herkend commando. Voer azd ext install azure.ai.evaluations uit en voer azd ext list uit om te bevestigen dat de extensie is geïnstalleerd. Het microsoft.foundry pakket bevat het niet.
Reconciliatie retourneert een autorisatiefout. Wijs Foundry User alleen toe aan het Foundry-project en, als u azd up gebruikt, Inzender alleen aan de dedicated resourcegroep. Wacht even tot nieuwe roltoewijzingen zijn doorgevoerd.
Het commando wordt afgesloten met code 1 en drukt evaluation quality gate not met af. Behandel het resultaat als een kwaliteitsregressie. Controleer de opgeschoonde tellingen en bewijs uit de allowlist-steekproef.
Het commando wordt afgesloten met code 1 zonder dat bericht. Behandel het resultaat als een operationele fout. Inspecteer alleen geredigeerde diagnostische gegevens voor verificatie-, netwerk-, onjuist opgemaakte resultaten, onvolledige uitvoering of exportfouten.
Een fork-pull-aanvraag probeert een OIDC-token aan te vragen. Vereis een head-check van dezelfde repository, behoud AZD_EVAL_LIVE_PR_GATE als standaard uitgeschakeld en gebruik pull_request_target niet.

Verwijder na controle tijdelijke testresources en roltoewijzingen die u niet meer nodig hebt. Verwijder tijdelijke federatieve aanmeldingsgegevens en behoud de toegewezen resourcegroep alleen als de quality gate deze blijft gebruiken.