Jak uruchomić ocenę w GitHub Action (wersja zapoznawcza)

Ta akcja GitHub umożliwia ocenę w trybie offline agentów Microsoft Foundry w potokach ciągłej integracji i dostarczania. Usprawnia proces oceny w trybie offline, dzięki czemu można zidentyfikować potencjalne problemy i wprowadzić ulepszenia przed wydaniem aktualizacji do środowiska produkcyjnego.

Aby użyć tej akcji, podaj zestaw danych z zapytaniami testowymi i listą ewaluatorów. Ta akcja wywołuje agentów za pomocą zapytań, uruchamia oceny i generuje raport podsumowania.

Funkcje

• Agent Evaluation: Zautomatyzuj ocenę przedprodukcyjną agentów Microsoft Foundry w przepływie pracy CI/CD.
• Ewaluatorzy: użyj wszystkich ewaluatorów z katalogu ewaluatorów programu Foundry.
• Analiza statystyczna: Wyniki oceny obejmują interwały ufności i test dla istotności statystycznej, aby określić, czy zmiany są istotne, a nie z powodu losowych zmian.

Kategorie ewaluatorów

• Ocenianie agentów: Ocenianie procesów i systemowe ocenianie przepływów pracy agentów.
• Ewaluatorzy RAG: Oceniają procesy kompleksowe i wyszukiwania w systemach RAG.
• Ewaluatorzy ryzyka i bezpieczeństwa: analizują zagrożenia i problemy związane z bezpieczeństwem w odpowiedziach.
• Ewaluatory ogólnego przeznaczenia: Ocena jakości, taka jak spójność i płynność.
• Graderzy oparte na OpenAI: użyj graderów OpenAI, w tym sprawdzania ciągów, podobieństwa tekstu, modeli ocen/etykiet.
• Custom evaluators: Tworzenie własnych niestandardowych ewaluatorów przy użyciu kodu Python lub wzorców LLM jako wzoru sędziowskiego.

Wymagania wstępne

• Projekt. Aby dowiedzieć się więcej, zobacz Tworzenie projektu.
• Agent usługi Foundry.

Jak skonfigurować oceny agentów sztucznej inteligencji

Dane wejściowe do oceny agenta sztucznej inteligencji

Parametry

Plik danych

Plik danych wejściowych powinien być plikiem JSON o następującej strukturze:

Podstawowy przykładowy plik danych

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

Dodatkowe przykładowe pliki danych

Proces oceny agentów AI

Aby użyć akcji GitHub, dodaj akcję GitHub do przepływów pracy ciągłej integracji i wdrażania. Określ kryteria wyzwalacza, takie jak zatwierdzenie, i ścieżki plików, aby wyzwolić zautomatyzowane przepływy pracy.

W tym przykładzie pokazano, jak można uruchomić ocenę agenta sztucznej inteligencji podczas porównywania różnych agentów przy użyciu identyfikatorów agentów.

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

Wyniki oceny agentów sztucznej inteligencji

Wyniki oceny są wprowadzane do sekcji podsumowania dla każdego uruchomienia akcji oceny sztucznej inteligencji GitHub w Akcje na GitHubie. Raport przedstawia wyniki oceny dla każdej metryki, interwały ufności i — gdy ocenia się wielu agentów — porównanie statystyczne parami wskazujące, czy różnice są istotne, czy mieszczą się w granicach losowej wariacji.

Poniższy zrzut ekranu przedstawia przykładowy raport porównujący dwóch agentów.

Użyj rozszerzenia azd do oceny jako bramki jakości

Możesz użyć rozszerzenia ewaluacyjnego interfejsu wiersza polecenia Azure Developer CLI (azd), aby uruchomić zarejestrowaną ocenę i zablokować pull request, gdy jego wskaźnik zaliczenia jest poniżej progu. Ten przepływ pracy używa GitHub OpenID Connect (OIDC), dlatego nie przechowuje klucza tajnego klienta.

Przygotuj repozytorium

Przed skonfigurowaniem przepływu pracy upewnij się, że masz następujące elementy:

• Subskrypcja Azure i projekt Foundry zawierający cel oceny.
• Dostęp administratora do konfigurowania zmiennych, sekretów, środowisk i reguł ochrony w GitHub Actions.
• Zatwierdzona definicja oceny i deterministyczny zestaw danych do oceny.
• Wymagane jest narzędzie Azure Developer CLI (azd) w wersji 1.33.0 lub nowszej, którego wymaga rozszerzenie ewaluacyjne. Aby uzyskać instrukcje dotyczące instalacji, zobacz Install the Azure Developer CLI (Instalowanie interfejsu wiersza polecenia dewelopera Azure
• Rozszerzenie azure.ai.evaluations, które udostępnia polecenia oceny. Pakiet Foundry azd (microsoft.foundry) nie zawiera go.

azure.ai.evaluations Zainstaluj rozszerzenie i sprawdź, czy polecenia oceny są dostępne. W przepływie pracy uruchom te same polecenia w kroku po zainstalowaniu programu azd. Aby uzyskać więcej informacji na temat rozszerzeń Foundry, zobacz Zainstaluj rozszerzenia Foundry dla Azure Developer CLI.

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

Konfigurowanie GitHub OIDC i zasady najmniejszych uprawnień

Utwórz aplikację Microsoft Entra lub tożsamość zarządzaną przypisaną przez użytkownika i dodaj poświadczenie tożsamości federacyjnej dla tokenu wystawionego dla przepływu pracy. Użyj następujących stałych wartości:

Repozytorium w organizacji lub przedsiębiorstwie używającym niestandardowego niezmiennego podmiotu może mieć podmiot o takim kształcie:

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

Dokumentacja referencyjna: Dokumentacja referencyjna OpenID Connect

Nie kopiuj identyfikatorów właściciela ani repozytorium z innego repozytorium. Zażądaj tokenu w przepływie pracy, zdekoduj jego ładunek bez drukowania tokenu i sprawdź tylko atrybuty iss, aud i sub. Skonfiguruj poświadczenie federacyjne, aby dokładnie pasowało do rzeczywistych claimów. Standardowy subject zadania w GitHubie, które korzysta ze środowiska, może mieć inną postać, a organizacja lub przedsiębiorstwo może dostosować claim „subject”.

Aby uzyskać informacje na temat konfiguracji tożsamości obciążenia roboczego Microsoft Entra, zobacz Uwierzytelnianie w Azure z GitHub Actions za pomocą protokołu OpenID Connect.

Przypisz tożsamości tylko te role:

• Użytkownik usługi Foundry na poziomie projektu Foundry.
• Współtwórca w zakresie dedykowanej grupy zasobów, jeśli uzgadniasz z azd up.

Rola grupy zasobów jest wymagana podczas uzgadniania z azd up, ponieważ azd up rejestruje wdrożenie Azure Resource Manager podczas aprowizowania. Nie przypisuj Współautor w zakresie subskrypcji.

Chroń i konfiguruj środowisko na żywo

Utwórz chronione środowisko GitHub o nazwie live-evaluation. Dodaj wymaganych recenzentów i ogranicz gałęzie wdrażania odpowiednio dla repozytorium. Aby uzyskać więcej informacji, zobacz Zarządzanie środowiskami do wdrażania.

Zapisz wartości przepływu pracy w następujący sposób. Nie dodawaj AZURE_CLIENT_SECRET; Funkcja OIDC zastępuje ją.

Zachowaj RUNNER_TEMP pod AZD_CONFIG_DIR i uwierzytelnij nieinteraktywnie:

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

Dokumentacja referencyjna: dokumentacja interfejsu wiersza polecenia dewelopera Azure

Zadanie musi mieć uprawnienia contents: read i id-token: write. Brama tak, aby tylko żądania ściągnięcia w tym samym repozytorium lub ręczne wysyłanie z gałęzi domyślnej mogły wejść do chronionego środowiska. Żądania pull request z forków muszą pomijać to zadanie, a workflow nie może używać 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

Dokumentacja: dokumentacja kontekstów GitHub Actions

Przypnij każdą akcję GitHub do zweryfikowanego pełnego zatwierdzenia SHA.

Podaj szablon infrastruktury inertnej, gdy azd up tego wymaga

Jeśli uzgodnisz projekt przeznaczony wyłącznie do oceny z elementem azd up zamiast azd ai eval create, projekt nie aprowizuje zasobów obciążenia roboczego. Jeśli azd up --no-prompt zgłasza, że nie może znaleźć ani skompilować pliku infra/main.bicep, dodaj ten plik za pomocą tego nieaktywnego zagnieżdżonego wdrożenia:

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

Szablon wewnętrzny nie zawiera żadnych zasobów obciążeń. Znacznik tworzy tylko rekord wdrożenia Azure Resource Manager.

Aby uzyskać więcej informacji, zobacz wdrożenia Microsoft.Resources.

Uruchom dokładną ocenę

Zachowaj cykl życia w następującej kolejności:

1. Uzgodnij zatwierdzoną definicję oceny. Uruchom polecenie azd up --no-prompt, gdy projekt udostępnia infrastrukturę. W przypadku projektu tylko do oceny uruchom polecenie azd ai eval create ci-f1-quality --no-prompt . To polecenie rejestruje zadeklarowane zestawy danych, ewaluatory i ewaluację bez aprowizowania infrastruktury.
2. Uruchom azd ai eval run start --eval ci-f1-quality --no-prompt --no-wait -o json.
3. Odczyt .run_id z przechwyconego kodu JSON bez zapisywania wartości w dzienniku.
4. Uruchom azd ai eval run show <run-id> --eval ci-f1-quality --wait --fail-on pass-rate=0.8 --no-prompt -o json.
5. Wyeksportuj dokładnie ten przebieg za pomocą polecenia azd ai eval run output export <run-id> --eval ci-f1-quality --format json --output-file <runner-temp-file> --no-prompt.
6. Przed przesłaniem sprawdź status ukończenia, zagregowane liczby, wyeksportowane wiersze i dowody z listy dozwolonych.

Przechwyć surowe standardowe wyjście i standardowy błąd w pliku RUNNER_TEMP. Zapisz identyfikator przebiegu w pamięci lub pliku tymczasowym modułu uruchamiającego i użyj go tylko jako argumentu pozycyjnego dla poleceń show i output export.

Dla każdej fazy cyklu życia należy użyć oddzielnego kroku GitHub Actions. Po powodzeniu wyświetl tylko oczyszczony wiersz polecenia i podsumowanie, takie jak ukończono uzgadnianie, zaakceptowano uruchomienie z ukrytym identyfikatorem, końcowy stan i liczby, wynik bramy, wyeksportowaną liczbę wierszy oraz podgląd dowodów z listy dozwolonych.

W przypadku parametru --fail-on pass-rate=0.8 współczynnik zaliczenia to liczba zaliczonych przypadków testowych podzielona przez łączną liczbę przypadków testowych. Nieudane, błędne, pominięte i inne niezaliczone wiersze są wliczane do przebiegu. Prawidłowo ukończone uruchomienie poniżej progu stanowi naruszenie standardów jakości. Interfejs azd wiersza polecenia łączy kody zakończenia rozszerzenia, więc polecenie kończy działanie z kodem 1 w przypadku naruszenia jakości i awarii operacyjnej. Naruszenie jakości wyświetla przyczynę bramki jakości i komunikat evaluation quality gate not met. Problemy z uwierzytelnianiem, problemy z siecią, nieprawidłowe lub niekompletne wyniki oraz niespójności eksportu to błędy operacyjne.

Prześlij tylko dowody z listy dozwolonych

Utwórz nowy dokument dowodowy na podstawie zweryfikowanego wyniku zamiast przekazywania nieprzetworzonych danych wyjściowych interfejsu wiersza polecenia lub usługi. Zachowaj tylko stan zbiorczy, liczby i próg oraz te pola dla każdej przejrzanej próbki: query, response, ground_truth, score i 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
    }
  ]
}

Przed przesłaniem sprawdź, czy katalog artefaktów zawiera tylko oczekiwany plik potwierdzający. Nigdy nie drukuj ani nie przesyłaj tokenów JWT, endpointów, identyfikatorów uruchomień, poświadczeń, informacji o użytkowniku, ciągów zapytania adresu URL ani surowych danych uwierzytelniających, CLI lub payloadów usługi. Zachowaj nieprzetworzone pliki w magazynie tymczasowym modułu uruchamiającego, zanonimizuj zarejestrowane dane diagnostyczne awarii i usuń pliki w ścieżce oczyszczania always() lub finally.

Zweryfikuj bramę

Uruchom przepływ pracy ręcznie w domyślnej gałęzi przed włączeniem weryfikacji żądań ściągnięcia. Potwierdź, że:

1. Uwierzytelnianie OIDC powodzi się bez klucza tajnego klienta.
2. Krok uzgadniania rejestruje zatwierdzoną ocenę.
3. Rozpoczęcie asynchroniczne jest akceptowane bez wyświetlania ID uruchomienia.
4. Polecenie show raportuje completed i wymusza próg 0.8 współczynnika zaliczenia.
5. Eksport zawiera tylko wiersze z tego konkretnego uruchomienia.
6. Przesłany artefakt zawiera tylko schemat dowodów z listy dozwolonych.
7. Surowe pliki tymczasowe programu uruchamiającego są usuwane po powodzeniu i niepowodzeniu.

Rozwiąż problemy z bramą

Po weryfikacji usuń jednorazowe zasoby testowe i przypisania ról, których już nie potrzebujesz. Usuń tymczasowe poświadczenia federacyjne i zachowaj dedykowaną grupę zasobów tylko wtedy, gdy brama jakości będzie nadal jej używać.

Powiązana zawartość

• Ocena w Azure DevOps
• Przeprowadzanie ocen agentów za pomocą narzędzia wiersza polecenia azd
• Instalowanie rozszerzeń interfejsu wiersza polecenia dewelopera Azure Developer Foundry
• Jak ocenić generowanie modeli i aplikacji sztucznej inteligencji za pomocą Microsoft Foundry
• Jak wyświetlić wyniki oceny w portalu Foundry