Durchführen einer Evaluation in GitHub Action (Vorschau)

Wichtig

Elemente, die in diesem Artikel als Vorschau gekennzeichnet sind, befinden sich derzeit in der Vorschau. Diese Vorschau wird ohne Service Level Agreement (SLA) bereitgestellt, und Microsoft empfiehlt sie nicht für Produktionsworkloads. Bestimmte Features werden möglicherweise nicht unterstützt oder weisen eingeschränkte Funktionen auf. Weitere Informationen finden Sie unter Supplementale Nutzungsbedingungen für Microsoft Azure Previews.

Diese GitHub Action ermöglicht die Offlineauswertung von Microsoft Foundry Agents innerhalb Ihrer CI/CD-Pipelines. Er optimiert den Offlineauswertungsprozess, sodass Sie potenzielle Probleme erkennen und Verbesserungen vornehmen können, bevor Sie ein Update für die Produktion veröffentlichen.

Um diese Aktion zu verwenden, stellen Sie einen Datensatz mit Testabfragen und einer Liste von Auswertungen bereit. Diese Aktion ruft Ihre Agents mit den Abfragen auf, führt die Auswertungen aus und generiert einen Zusammenfassenden Bericht.

Funktionen

  • Agent Evaluation: Automatisieren Sie die Vorproduktionsbewertung von Microsoft Foundry Agents in Ihrem CI/CD-Workflow.
  • Evaluatoren: Verwenden Sie alle Bewerter aus dem Gießerei-Evaluatorkatalog.
  • Statistische Analyse: Auswertungsergebnisse umfassen Konfidenzintervalle und Tests zur statistischen Signifikanz, um festzustellen, ob Änderungen sinnvoll sind und nicht aufgrund zufälliger Variation.

Bewertungskategorien

Voraussetzungen

Tipp

Die empfohlene Methode zur Authentifizierung ist die Verwendung von Microsoft Entra ID, die Sie verwenden können, um eine sichere Verbindung mit Ihren Azure-Ressourcen herzustellen. Sie können den Authentifizierungsprozess mithilfe der Aktion Azure Anmelden GitHub automatisieren. Weitere Informationen finden Sie unter Azure Anmeldeaktion mit OpenID Connect.

Einrichten von Bewertungen für KI-Agenten

KI-Agenten-Bewertungseingaben

Parameter

Namen Erforderlich? Beschreibung
Azure AI-Projekt-Endpunkt Ja Endpunkt Ihres Microsoft Foundry-Projekts. Um diesen Wert zu finden, öffnen Sie Ihr Projekt im Foundry-Portal und kopieren Sie den Endpunkt auf der Seite "Übersicht".
Bereitstellungsname Ja Der Name eines Azure AI-Modelleinsatzes zur Auswertung. Suchen Sie vorhandene Bereitstellungen unter "Modelle + Endpunkte " im Foundry-Portal.
Datenpfad Ja Pfad zur Datendatei, die die Bewerter und Abfragen für Auswertungen enthält.
Agent-IDs Ja ID eines oder mehrerer Agents, die im Format agent-name:version ausgewertet werden sollen (z. B my-agent:1 . oder my-agent:1,my-agent:2). Mehrere Agenten werden durch Kommas getrennt und mit den Ergebnissen statistischer Tests verglichen.
Baseline-Agenten-ID Nein ID des Basis-Agents, der beim Auswerten mehrerer Agents verglichen werden soll. Wenn nicht angegeben, wird der erste Agent verwendet.

Hinweis

Um Ihre Agent-ID und -Version zu finden, öffnen Sie Ihr Projekt im Foundry-Portal, wechseln Sie zu Agents, wählen Sie Ihren Agent aus, und kopieren Sie die Agent-ID aus dem Detailbereich. Die Version ist die Versionsnummer der Bereitstellung (z. B. my-agent:1).

Datendatei

Die Eingabedatendatei sollte eine JSON-Datei mit der folgenden Struktur sein:

Feld Typ Erforderlich? Beschreibung
Name Schnur Ja Name des Auswertungsdatensatzes.
Bewerter string[] Ja Liste der zu verwendenden Evaluatornamen. Sehen Sie sich die Liste der verfügbaren Evaluator im Evaluatorenkatalog Ihres Projekts im Foundry Portal an: Erstellen >Evaluierungen >Evaluatorenkatalog.
Daten Objekt[] Ja Array von Eingabeobjekten mit query und optionalen Evaluator-Feldern wie ground_truth, context. Automatisch an Auswerter zugeordnet; mit data_mapping überschreiben.
openai_graders Objekt Nein Konfiguration für OpenAI-basierte Bewerter (label_model, score_model, string_check usw.).
Auswerter-Parameter Objekt Nein Evaluatorspezifische Initialisierungsparameter (z. B. Schwellenwerte, benutzerdefinierte Einstellungen).
Datenzuordnung Objekt Nein Benutzerdefinierte Datenfeldzuordnungen (automatisch generiert aus Daten, falls nicht angegeben).

Grundlegende Beispieldatendatei

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

Zusätzliche Beispieldatendateien

Dateiname Beschreibung
dataset-tiny.json Dataset mit einer kleinen Anzahl von Testabfragen und Auswertungen.
dataset.json Dataset mit allen unterstützten Auswertungstypen und ausreichenden Abfragen für die Berechnung von Konfidenzintervallen und statistischen Tests.
dataset-builtin-evaluators.json Integrierte Foundry Evaluatoren (z.B. Kohärenz, Geläufigkeit, Relevanz, Fundiertheit, Metriken).
dataset-openai-graders.json OpenAI-basierte Grader (Beispiel für Beschriftungsmodelle, Bewertungsmodelle, Textähnlichkeit, Zeichenfolgenprüfungen).
dataset-custom-evaluators.json Beispiel für benutzerdefinierte Auswertungen mit Evaluatorenparametern.
dataset-data-mapping.json Beispiel für die Datenzuordnung, das zeigt, wie automatische Feldzuordnungen mit benutzerdefinierten Datenspaltennamen überschrieben werden.

KI-Agenten-Bewertungsworkflow

Um die GitHub Aktion zu verwenden, fügen Sie den CI/CD-Workflows die GitHub Aktion hinzu. Geben Sie die Triggerkriterien an, z. B. beim Commit, und die Dateipfade, um Ihre automatisierten Workflows auszulösen.

Tipp

Um Die Kosten zu minimieren, führen Sie keine Auswertung für jeden Commit aus.

In diesem Beispiel wird gezeigt, wie Sie die KI-Agent-Auswertung ausführen können, wenn Sie verschiedene Agents mithilfe von Agent-IDs vergleichen.

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

Ausgabe für KI-Agent-Auswertungen

Die Bewertungsergebnisse werden im Zusammenfassungsabschnitt für jede ausgeführte GitHub Action-KI-Auswertung unter Actions in GitHub ausgegeben. Der Bericht zeigt Auswertungsergebnisse für jede Metrik, Vertrauenswürdigkeitsintervalle und – wenn Sie mehrere Agents auswerten – einen paarweisen statistischen Vergleich, der angibt, ob Unterschiede sinnvoll oder innerhalb der zufallsvarianzen sind.

Der folgende Screenshot zeigt einen Beispielbericht, in dem zwei Agents verglichen werden.

Screenshot GitHub Actions Workflowzusammenfassung mit Bewertungsergebnissen für Agenten mit Konfidenzintervallen und paarweisem statistischen Vergleich für zwei Agents.

Verwenden Sie die azd-Evaluierungserweiterung als Qualitätsgate

Sie können die Auswertungserweiterung Azure Developer CLI (azd) verwenden, um eine registrierte Auswertung auszuführen und einen Pull Request zu blockieren, wenn die Passrate unter einem Schwellenwert liegt. Dieser Workflow verwendet GitHub OpenID Connect (OIDC), sodass kein geheimer Clientschlüssel gespeichert wird.

Repository vorbereiten

Stellen Sie vor der Konfiguration des Workflows folgendes sicher:

  • Ein Azure-Abonnement und ein Foundry-Projekt, das das Auswertungsziel enthält.
  • Administratorzugriff zum Konfigurieren von GitHub Actions Variablen, Secrets, Umgebungen und Schutzregeln.
  • Eine committete Auswertungsdefinition und ein deterministisches Auswertungsdatenset.
  • Die Azure Developer CLI (azd), Version 1.33.0 oder höher, die von der Evaluierungserweiterung erfordert wird. Installationsanweisungen finden Sie unter Install the Azure Developer CLI.
  • Die Erweiterung azure.ai.evaluations, die die Auswertungsbefehle bereitstellt. Das Foundry-Paket azd (microsoft.foundry) enthält es nicht.

Installieren Sie die azure.ai.evaluations Erweiterung, und überprüfen Sie, ob die Evaluierungsbefehle verfügbar sind. Führen Sie in Ihrem Workflow die gleichen Befehle in einem Schritt aus, nachdem Sie azd installiert haben. Weitere Informationen zu den Foundry-Erweiterungen finden Sie unter Installieren Sie die Azure Developer CLI Foundry-Erweiterungen.

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

Konfigurieren von GitHub OIDC und dem Least-Privilege-Prinzip

Erstellen Sie eine Microsoft Entra-Anwendung oder eine vom Benutzer zugewiesene verwaltete Identität, und fügen Sie eine Verbundidentitätsanmeldeinformation für den Workflow ausgestellte Token hinzu. Verwenden Sie die folgenden festen Werte:

Feld für Verbundanmeldeinformationen Value
Issuer https://token.actions.githubusercontent.com
Publikum api://AzureADTokenExchange
Betreff Der genaue sub Claim im GitHub OIDC-Token

Ein Repository in einer Organisation oder einem Unternehmen, das ein unveränderliches benutzerdefiniertes Subject verwendet, kann ein Subject mit dieser Form haben:

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

Referenz: OpenID Connect-Referenz

Kopieren Sie keine Besitzer- oder Repository-IDs aus einem anderen Repository. Fordern Sie ein Token in Ihrem Workflow an, decodieren Sie die Nutzlast, ohne das Token zu drucken, und prüfen Sie nur die iss, aud und sub Claims. Konfigurieren Sie die Verbundanmeldeinformation so, dass sie genau den tatsächlichen Claims entspricht. Das GitHubs Standardbetreff für einen Auftrag, der eine Umgebung verwendet, kann eine andere Form haben, und eine Organisation oder ein Unternehmen kann den Subject-Claim anpassen.

Informationen zur Einrichtung der Microsoft Entra-Workloadidentität finden Sie unter „Authentifizierung bei Azure aus GitHub Actions mithilfe von OpenID Connect“.

Weisen Sie der Identität nur diese Rollen zu:

  • Foundry User im Bereich des Foundry-Projekts.
  • Mitwirkender im dedizierten Ressourcengruppenbereich, wenn Sie mit azd up abgleichen.

Wichtig

Die Foundry-RBAC-Rollen wurden kürzlich umbenannt. Foundry User, Foundry Owner, Foundry Account Owner und Foundry Project Manager wurden zuvor Azure KI-Benutzer, Azure KI-Besitzer, Azure KI-Kontobesitzer und Azure AI Project Manager benannt. Möglicherweise werden die vorherigen Namen an einigen Stellen weiterhin angezeigt, während der Umbenennungsrollout ausgeführt wird. Die Rollen-IDs und Kernberechtigungen bleiben durch die Umbenennung unverändert.

Die Ressourcengruppenrolle ist erforderlich, wenn Sie mit azd up abgleichen, da azd up beim Bereitstellen eine Azure Resource Manager-Bereitstellung aufzeichnet. Weisen Sie im Bereich des Abonnements keinen Mitwirkenden zu.

Schützen und Konfigurieren der Liveumgebung

Erstellen Sie eine geschützte GitHub Umgebung mit dem Namen live-evaluation. Fügen Sie erforderliche Prüfer hinzu, und beschränken Sie die Bereitstellungsverzweigungen nach Bedarf für Ihr Repository. Weitere Informationen finden Sie unter Verwalten von Umgebungen für die Bereitstellung.

Speichern Sie die Workflowwerte wie folgt. Fügen Sie AZURE_CLIENT_SECRET nicht hinzu; OIDC ersetzt es.

Namen GitHub-Speicher Purpose
AZURE_CLIENT_ID live-evaluation Umgebungs-Secret Client-ID der Microsoft Entra-Anwendung oder der verwalteten Identität.
AZURE_TENANT_ID live-evaluation Umgebungsgeheimniswert Microsoft Entra-Mandanten-ID
AZURE_SUBSCRIPTION_ID live-evaluation Geheimer Umgebungsschlüssel Abonnement, das die dedizierte Ressourcengruppe enthält.
AZURE_AI_PROJECT_ENDPOINT live-evaluation Secret der Umgebung Von der Auswertungserweiterung verwendeter Foundry-Projektendpunkt.
AZURE_LOCATION Umgebungsvariable live-evaluation Azure Region für die azd Umgebung.
AZURE_RESOURCE_GROUP Umgebungsvariable live-evaluation Dedizierte Ressourcengruppe, die für Abstimmungsmetadaten verwendet wird.
AZD_EVAL_LIVE_PR_GATE Repository-Variable Legen Sie den genauen Wert true fest, um den Liveauftrag zu aktivieren.

Bleiben Sie AZD_CONFIG_DIR unter RUNNER_TEMP, und authentifizieren Sie nicht interaktiv:

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

Referenz: Azure Developer CLI-Referenz

Der Auftrag muss über id-token: write- und contents: read-Berechtigungen verfügen. Gate it so that only same-repository pull requests or a manual dispatch from the default branch can enter the protected environment. Pull Requests aus Forks müssen den Job überspringen, und der Workflow darf pull_request_target nicht verwenden.

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

Referenz: GitHub Actions Kontextreferenz

Legen Sie jede GitHub Action auf eine überprüfte vollständige Commit-SHA fest.

Bereitstellen einer inert-Infrastrukturvorlage bei azd up Bedarf

Wenn Sie ein reines Auswertungsprojekt mit azd up statt mit azd ai eval create abgleichen, stellt das Projekt keine Workloadressourcen bereit. Wenn azd up --no-prompt meldet, dass infra/main.bicep nicht gefunden oder kompiliert werden kann, fügen Sie diese Datei mit dieser inaktiven geschachtelten Bereitstellung hinzu:

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

Die innere Vorlage enthält keine Workload-Ressourcen. Die Markierung erstellt nur einen Azure Resource Manager Bereitstellungsdatensatz.

Weitere Informationen finden Sie unter Microsoft.Resources-Bereitstellungen.

Genaue Bewertung ausführen

Behalten Sie den Lebenszyklus in dieser Reihenfolge bei:

  1. Gleichen Sie die eingecheckte Evaluierungsdefinition ab. Führen Sie azd up --no-prompt aus, wenn das Projekt Infrastruktur bereitstellt. Führen Sie stattdessen azd ai eval create ci-f1-quality --no-prompt für ein reines Auswertungsprojekt aus. Mit diesem Befehl werden die deklarierten Datasets, Evaluatoren und Evaluierung ohne Bereitstellungsinfrastruktur registriert.
  2. Führen Sie azd ai eval run start --eval ci-f1-quality --no-prompt --no-wait -o json aus.
  3. Lesen Sie den Wert .run_id aus dem erfassten JSON, ohne den Wert in das Protokoll zu schreiben.
  4. Führen Sie azd ai eval run show <run-id> --eval ci-f1-quality --wait --fail-on pass-rate=0.8 --no-prompt -o json aus.
  5. Exportieren Sie genau diese Ausführung mit azd ai eval run output export <run-id> --eval ci-f1-quality --format json --output-file <runner-temp-file> --no-prompt.
  6. Überprüfen Sie den abgeschlossenen Status, die Aggregatanzahl, die exportierten Zeilen und die Allowlist-Nachweise vor dem Upload.

Erfassen Sie rohe Standardausgabe und Standardfehler in RUNNER_TEMP. Speichern Sie die Ausführungs-ID im Arbeitsspeicher oder in einer temporären Runner-Datei, und verwenden Sie sie nur als Positionsargument für die show- und output export-Befehle.

Verwenden Sie für jede Lebenszyklusphase einen separaten GitHub Actions Schritt. Drucken Sie bei Erfolg nur eine bereinigte Befehlszeile und eine Zusammenfassung, z. B. „Abgleich abgeschlossen“, „akzeptierter Lauf mit geschwärzter ID“, „endgültiger Status und Anzahl“, „Ergebnis der Prüfung“, „Anzahl exportierter Zeilen“ und „Vorschau der zulässigen Nachweise“.

Für --fail-on pass-rate=0.8 ist die Erfolgsquote die Anzahl bestandener Testfälle geteilt durch die Gesamtzahl der Testfälle. Fehlgeschlagene, fehlerhafte, übersprungene und anderweitig nicht erfolgreiche Zeilen werden auf den Lauf angerechnet. Ein gültiger abgeschlossener Durchlauf unter dem Schwellenwert ist ein Qualitätsverstoß. Die azd CLI fasst die Exit-Codes einer Erweiterung zusammen, sodass der Befehl mit Code 1 für eine Qualitätsverletzung und für einen Betriebsfehler beendet wird. Ein Qualitätsverstoß gibt den Gate-Grund und die Nachricht evaluation quality gate not met aus. Authentifizierung, Netzwerk, falsch formatierte oder unvollständige Ergebnisse und Exportinkonsistenzen sind Betriebsfehler.

Nur auf der Allowlist stehende Nachweise hochladen

Erstellen Sie ein neues Nachweisdokument aus dem überprüften Ergebnis, anstatt die rohe CLI- oder Dienstausgabe hochzuladen. Behalten Sie nur den aggregierten Status, die Anzahl und den Schwellenwert sowie die folgenden Felder für jedes überprüfte Beispiel bei: query, response, ground_truth, score und 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
    }
  ]
}

Überprüfen Sie vor dem Hochladen, ob das Artefaktverzeichnis nur die erwartete Nachweisdatei enthält. JWTs, Endpoints, Run-IDs, Anmeldeinformationen, Benutzerinfo, URL-Abfragezeichenfolgen oder rohe Authentifizierungs-, CLI- oder Service-Payloads niemals drucken oder hochladen. Bewahren Sie Rohdateien im temporären Speicher des Runners auf, schwärzen Sie erfasste Fehlerdiagnosen und löschen Sie die Dateien in einem always()- oder finally-Bereinigungspfad.

Gate überprüfen

Führen Sie den Workflow manuell aus dem Standardbranch aus, bevor Sie Pull-Request-Gating aktivieren. Bestätigen Sie Folgendes:

  1. Die OIDC-Authentifizierung gelingt ohne Client-Secret.
  2. Der Abgleichsschritt registriert die abgegebene Bewertung.
  3. Der asynchrone Start wird akzeptiert, ohne die Ausführungs-ID anzuzeigen.
  4. Der show Befehl meldet completed und erzwingt den 0.8 Passrate-Schwellenwert.
  5. Der Export enthält nur Zeilen aus dem exakten Lauf.
  6. Das hochgeladene Artefakt enthält nur das Schema der Allowlist-Nachweise.
  7. Raw temporäre Runner-Dateien werden bei Erfolg und Fehler gelöscht.

Beheben Sie Probleme mit dem Gate

Symptom Resolution
Microsoft Entra ID lehnt das föderierte Token ab. Vergleichen Sie die tatsächlichen issClaims auddes Tokens mit sub der Verbundanmeldeinformation. Gehen Sie nicht davon aus, dass ein Umgebungsobjekt vorhanden ist, und kopieren Sie nicht die IDs eines anderen Repositorys.
azd up meldet ein fehlendes Abonnement, einen Speicherort oder eine Ressourcengruppe. Konfigurieren Sie AZURE_SUBSCRIPTION_ID, AZURE_LOCATION und AZURE_RESOURCE_GROUP in der geschützten Umgebung und übergeben Sie sie an den Job.
azd up kann infra/main.bicep nicht finden oder kompilieren. Fügen Sie die in diesem Artikel beschriebene Inertinfrastrukturvorlage hinzu, oder gleichen Sie stattdessen ein Projekt nur zu Evaluierungszwecken mit azd ai eval create ab.
azd ai eval ist kein erkannter Befehl. Führen Sie den Befehl azd ext install azure.ai.evaluations aus, und führen Sie dann azd ext list aus, um zu bestätigen, dass die Erweiterung installiert ist. Das microsoft.foundry Paket enthält es nicht.
Der Abgleich gibt einen Autorisierungsfehler zurück. Weisen Sie den Foundry-Benutzer nur dem Foundry-Projekt zu, und verwenden Sie, wenn Sie azd up verwenden, Mitwirkender nur für die dedizierte Ressourcengruppe. Berücksichtigen Sie, dass es einige Zeit dauert, bis neue Rollenzuweisungen wirksam sind.
Der Befehl endet mit Code 1 und gibt evaluation quality gate not met aus. Behandeln Sie das Ergebnis als Qualitätsregression. Überprüfen Sie die bereinigten Anzahlwerte und die auf der Zulassungsliste stehenden Stichprobennachweise.
Der Befehl endet ohne diese Nachricht mit Code 1. Behandeln Sie den Vorgang als Betriebsfehler. Überprüfen Sie nur geschwärzte Diagnosedaten für Authentifizierungs-, Netzwerk-, fehlerhafte Ergebnis-, unvollständige Ausführungs- oder Exportfehler.
Eine Fork-Pullanforderung versucht, ein OIDC-Token anzufordern. Erfordern Sie eine Head-Prüfung im selben Repository, lassen Sie AZD_EVAL_LIVE_PR_GATE standardmäßig deaktiviert und verwenden Sie pull_request_target nicht.

Entfernen Sie nach der Überprüfung temporäre Testressourcen und Rollenzuweisungen, die Sie nicht mehr benötigen. Löschen Sie temporäre Verbundanmeldeinformationen, und behalten Sie die dedizierte Ressourcengruppe nur bei, wenn das Qualitätsgate sie weiterhin verwendet.

Verwandte Inhalte

  • Zuletzt aktualisiert um