Evalueer uw generatieve AI-toepassing lokaal met de Azure AI Evaluation SDK (preview) (klassiek)

Alleen van toepassing op:Foundry (klassiek) portal. Dit artikel is niet beschikbaar voor de nieuwe Foundry-portal. Meer informatie over de nieuwe portal.

U kunt de prestaties van uw generatieve AI-toepassing grondig beoordelen door deze toe te passen op een aanzienlijke gegevensset. Evalueer de toepassing in uw ontwikkelomgeving met de Azure AI Evaluation SDK.

Wanneer u een testgegevensset of een doelgegevensset opgeeft, worden de uitvoer van uw generatieve AI-toepassing kwantitatief gemeten met zowel wiskundige maatstaven als door AI ondersteunde kwaliteit- en veiligheidsevaluatoren. Ingebouwde of aangepaste evaluators bieden u uitgebreide inzichten in de mogelijkheden en beperkingen van de toepassing.

In dit artikel leert u hoe u evaluators kunt uitvoeren op één rij gegevens en een grotere testgegevensset op een toepassingsdoel. U gebruikt ingebouwde evaluators die lokaal gebruikmaken van de Azure AI Evaluation SDK. Vervolgens leert u de resultaten en evaluatielogboeken bij te houden in een Foundry-project.

Aan de slag gaan

Installeer eerst het pakket met evaluators uit de Azure AI Evaluation SDK:

pip install azure-ai-evaluation

Ingebouwde evaluators

Ingebouwde metrische gegevens over kwaliteit en veiligheid accepteren query- en antwoordparen, samen met aanvullende informatie voor specifieke evaluators.

Gegevensvereisten voor ingebouwde evaluators

Ingebouwde evaluators kunnen query- en antwoordparen accepteren, een lijst met gesprekken in JSON Lines-indeling (JSONL) of beide.

Azure OpenAI-graders vereisen een sjabloon waarin wordt beschreven hoe de invoerkolommen worden omgezet in de real invoer die door de grader wordt gebruikt. Als u bijvoorbeeld twee invoer hebt met de naam query en antwoord en een sjabloon die is opgemaakt als {{item.query}}, wordt alleen de query gebruikt. Op dezelfde manier kunt u iets hebben als {{item.conversation}} om een gespreksinvoer te accepteren, maar de mogelijkheid van het systeem om dat te verwerken, is afhankelijk van hoe u de rest van de grader configureert zodat het die invoer verwacht.

Zie Uw AI-agents evalueren voor meer informatie over gegevensvereisten voor agentische evaluators.

Ondersteuning voor eenmalige interacties met tekst

Alle ingebouwde evaluators accepteren invoer als query- en antwoordparen in tekenreeksen voor een enkele beurt. Bijvoorbeeld:

from azure.ai.evaluation import RelevanceEvaluator

query = "What is the capital of life?"
response = "Paris."

# Initialize an evaluator:
relevance_eval = RelevanceEvaluator(model_config)
relevance_eval(query=query, response=response)

Als u batchevaluaties wilt uitvoeren met behulp van lokale evaluatie of uw gegevensset wilt uploaden om een cloudevaluatie uit te voeren, vertegenwoordigt u de gegevensset in JSONL-indeling. De vorige gegevens met één draai, een query-en-antwoordpaar, zijn gelijk aan een regel van een gegevensset, zoals in het volgende voorbeeld, waarin drie regels worden weergegeven:

{"query":"What is the capital/major city of France?","response":"Paris."}
{"query":"What atoms compose water?","response":"Hydrogen and oxygen."}
{"query":"What color is my shirt?","response":"Blue."}

De evaluatietestgegevensset kan de volgende elementen bevatten, afhankelijk van de vereisten van elke ingebouwde evaluator:

• Query: De query die is verzonden naar de generatieve AI-toepassing.
• Antwoord: Het antwoord op de query die is gegenereerd door de generatieve AI-toepassing.
• Context: De bron waarop het gegenereerde antwoord is gebaseerd. Dat zijn de basisdocumenten.
• Grondwaar: het antwoord dat door een gebruiker of mens wordt gegenereerd als het ware antwoord.

Zie Ingebouwde evaluatoren om te zien wat elke evaluator vereist.

Gespreksondersteuning voor tekst

Voor evaluators die tekstgesprekken ondersteunen, kunt u conversation als invoer opgeven. Deze invoer bevat een Python woordenlijst met een lijst met messages, waaronder content, role en eventueel context.

Bekijk het volgende gesprek met twee beurten in Python:

conversation = {
        "messages": [
        {
            "content": "Which tent is the most waterproof?", 
            "role": "user"
        },
        {
            "content": "The Alpine Explorer Tent is the most waterproof",
            "role": "assistant", 
            "context": "From the our product list the alpine explorer tent is the most waterproof. The Adventure Dining Table has higher weight."
        },
        {
            "content": "How much does it cost?",
            "role": "user"
        },
        {
            "content": "The Alpine Explorer Tent is $120.",
            "role": "assistant",
            "context": None
        }
        ]
}

Als u batchevaluaties wilt uitvoeren met behulp van lokale evaluatie of uw gegevensset wilt uploaden om cloudevaluatie uit te voeren, moet u de gegevensset in JSONL-indeling vertegenwoordigen. Het vorige gesprek is gelijk aan een regel van een dataset in een JSONL-bestand zoals in het volgende voorbeeld.

{"conversation":
    {
        "messages": [
        {
            "content": "Which tent is the most waterproof?", 
            "role": "user"
        },
        {
            "content": "The Alpine Explorer Tent is the most waterproof",
            "role": "assistant", 
            "context": "From the our product list the alpine explorer tent is the most waterproof. The Adventure Dining Table has higher weight."
        },
        {
            "content": "How much does it cost?",
            "role": "user"
        },
        {
            "content": "The Alpine Explorer Tent is $120.",
            "role": "assistant",
            "context": null
        }
        ]
    }
}

Onze evaluators begrijpen dat de eerste ronde van het gesprek valide query is van user, context van assistant, en response van assistant in de queryreactie-indeling. Gesprekken worden vervolgens per beurt geëvalueerd en resultaten worden samengevoegd over alle beurten voor een gespreksscore.

Voor de gespreksmodus, hier is een voorbeeld van GroundednessEvaluator:

# Conversation mode:
import json
import os
from azure.ai.evaluation import GroundednessEvaluator, AzureOpenAIModelConfiguration

model_config = AzureOpenAIModelConfiguration(
    azure_endpoint=os.environ.get("AZURE_ENDPOINT"),
    api_key=os.environ.get("AZURE_API_KEY"),
    azure_deployment=os.environ.get("AZURE_DEPLOYMENT_NAME"),
    api_version=os.environ.get("AZURE_API_VERSION"),
)

# Initialize the Groundedness evaluator:
groundedness_eval = GroundednessEvaluator(model_config)

conversation = {
    "messages": [
        { "content": "Which tent is the most waterproof?", "role": "user" },
        { "content": "The Alpine Explorer Tent is the most waterproof", "role": "assistant", "context": "From the our product list the alpine explorer tent is the most waterproof. The Adventure Dining Table has higher weight." },
        { "content": "How much does it cost?", "role": "user" },
        { "content": "$120.", "role": "assistant", "context": "The Alpine Explorer Tent is $120."}
    ]
}

# Alternatively, you can load the same content from a JSONL file.
groundedness_conv_score = groundedness_eval(conversation=conversation)
print(json.dumps(groundedness_conv_score, indent=4))

Voor gespreksuitvoer worden resultaten per beurt opgeslagen in een lijst en wordt de totale gespreksscore 'groundedness': 4.0 gemiddeld over de beurten.

{
    "groundedness": 5.0,
    "gpt_groundedness": 5.0,
    "groundedness_threshold": 3.0,
    "evaluation_per_turn": {
        "groundedness": [
            5.0,
            5.0
        ],
        "gpt_groundedness": [
            5.0,
            5.0
        ],
        "groundedness_reason": [
            "The response accurately and completely answers the query by stating that the Alpine Explorer Tent is the most waterproof, which is directly supported by the context. There are no irrelevant details or incorrect information present.",
            "The RESPONSE directly answers the QUERY with the exact information provided in the CONTEXT, making it fully correct and complete."
        ],
        "groundedness_result": [
            "pass",
            "pass"
        ],
        "groundedness_threshold": [
            3,
            3
        ]
    }
}

Gespreksondersteuning voor afbeeldingen en multimodale tekst en afbeelding

Voor evaluators die gesprekken ondersteunen voor afbeeldingen en multimodale afbeeldingen en tekst, kunt u afbeeldings-URL's of met Base64 gecodeerde afbeeldingen doorgeven in conversation.

Ondersteunde scenario's zijn:

• Meerdere afbeeldingen met tekstinvoer voor het genereren van afbeeldingen of tekst.
• Textinvoer alleen voor beeldgeneratie.
• Invoer van alleen afbeeldingen voor het genereren van tekst.

from pathlib import Path
from azure.ai.evaluation import ContentSafetyEvaluator
import base64

# Create an instance of an evaluator with image and multi-modal support.
safety_evaluator = ContentSafetyEvaluator(credential=azure_cred, azure_ai_project=project_scope)

# Example of a conversation with an image URL:
conversation_image_url = {
    "messages": [
        {
            "role": "system",
            "content": [
                {"type": "text", "text": "You are an AI assistant that understands images."}
            ],
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Can you describe this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://cdn.britannica.com/68/178268-050-5B4E7FB6/Tom-Cruise-2013.jpg"
                    },
                },
            ],
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "The image shows a man with short brown hair smiling, wearing a dark-colored shirt.",
                }
            ],
        },
    ]
}

# Example of a conversation with base64 encoded images:
base64_image = ""

with Path.open("Image1.jpg", "rb") as image_file:
    base64_image = base64.b64encode(image_file.read()).decode("utf-8")

conversation_base64 = {
    "messages": [
        {"content": "create an image of a branded apple", "role": "user"},
        {
            "content": [{"type": "image_url", "image_url": {"url": f"data:image/jpg;base64,{base64_image}"}}],
            "role": "assistant",
        },
    ]
}

# Run the evaluation on the conversation to output the result.
safety_score = safety_evaluator(conversation=conversation_image_url)

Momenteel ondersteunen de afbeelding- en multimodale evaluators:

• Enkele beurt: een gesprek kan slechts één gebruikersbericht en één assistentbericht hebben.
• Gesprekken met slechts één systeembericht.
• Nettoladingen van gesprekken die kleiner zijn dan 10 MB, inclusief afbeeldingen.
• Absolute URL's en met Base64 gecodeerde afbeeldingen.
• Meerdere afbeeldingen in één keer.
• JPG-/JPEG-, PNG- en GIF-bestandsindelingen.

Instellen

Voor door AI ondersteunde kwaliteits evaluators, met uitzondering van GroundednessProEvaluator preview, moet u een GPT-model (gpt-35-turbo, gpt-4gpt-4-turbo, , gpt-4oof gpt-4o-mini) opgeven in uw model_config. Het GPT-model fungeert als rechter om de evaluatiegegevens te beoordelen. We ondersteunen zowel Azure OpenAI- als OpenAI-modelconfiguratieschema's. Voor de beste prestaties en parseerbare antwoorden met onze evaluators raden we u aan GPT-modellen te gebruiken die niet in preview zijn.

Voor alle risico- en veiligheidsevaluators en GroundednessProEvaluator (preview) moet u uw azure_ai_project gegevens verstrekken in plaats van een GPT-implementatie in model_config. Hiermee opent u de back-end-evaluatieservice door gebruik te maken van uw Foundry-project.

Prompts voor ingebouwde AI-evaluators

Voor transparantie stellen we de prompts van onze kwaliteitsevaluators open in onze Evaluatorbibliotheek en de Azure AI Evaluation Python SDK-opslagplaats, met uitzondering van de veiligheidsevaluators en GroundednessProEvaluator, ondersteund door Azure AI Content Veiligheid. Deze prompts dienen als instructies voor een taalmodel om hun evaluatietaak uit te voeren. Hiervoor is een mensvriendelijke definitie van de metrische gegevens en de bijbehorende scorerubrieken vereist. We raden u ten zeerste aan om de definities en beoordelingsrubrieken aan te passen aan uw scenariodetails. Zie Aangepaste evaluators voor meer informatie.

Samengestelde evaluators

Samengestelde evaluators zijn ingebouwde evaluators die afzonderlijke metrische gegevens over kwaliteit of veiligheid combineren. Ze bieden een breed scala aan metrieken direct bruikbaar voor zowel query-antwoordparen als chatberichten.

Lokale evaluatie van testgegevenssets met behulp van evaluate()

Nadat u de ingebouwde of aangepaste evaluators op één rij met gegevens hebt gecontroleerd, kunt u meerdere evaluators combineren met de evaluate() API op een volledige testgegevensset.

Vereiste stappen voor het instellen van Microsoft Foundry-projecten

Als deze sessie de eerste keer is dat u evaluaties uitvoert en deze aanmeldt bij uw Foundry-project, moet u mogelijk de volgende installatiestappen uitvoeren:

1. Maak en verbind uw opslagaccount met uw Foundry-project op resourceniveau. Met deze bicep-sjabloon wordt een opslagaccount aangemaakt en verbonden met uw Foundry-project via sleutelverificatie.
2. Zorg ervoor dat het verbonden opslagaccount toegang heeft tot alle projecten.
3. Als u uw opslagaccount hebt verbonden aan Microsoft Entra ID, moet u Microsoft Identity-machtigingen opgeven voor Storage Blob Data Owner voor zowel uw account als de Foundry-projectresource in de Azure Portal.

Evalueren van een dataset en resultaten loggen naar Foundry

Om ervoor te zorgen dat de evaluate() API de gegevens correct kan parseren, moet u kolomtoewijzing opgeven om de kolom van de gegevensset toe te wijzen aan belangrijke woorden die de evaluators accepteren. In dit voorbeeld geeft u de gegevenstoewijzing voor query, responseen context.

from azure.ai.evaluation import evaluate

result = evaluate(
    data="data.jsonl", # Provide your data here:
    evaluators={
        "groundedness": groundedness_eval,
        "answer_length": answer_length
    },
    # Column mapping:
    evaluator_config={
        "groundedness": {
            "column_mapping": {
                "query": "${data.queries}",
                "context": "${data.context}",
                "response": "${data.response}"
            } 
        }
    },
    # Optionally, provide your Foundry project information to track your evaluation results in your project portal.
    azure_ai_project = azure_ai_project,
    # Optionally, provide an output path to dump a JSON file of metric summary, row-level data, and the metric and Foundry project URL.
    output_path="./myevalresults.json"
)

De evaluator geeft resultaten in een woordenboek, dat samengevoegde metrics gegevens en statistieken op rijniveau bevat. Bekijk de volgende voorbeelduitvoer:

{'metrics': {'answer_length.value': 49.333333333333336,
             'groundedness.gpt_groundeness': 5.0, 'groundedness.groundeness': 5.0},
 'rows': [{'inputs.response': 'Paris is the capital/major city of France.',
           'inputs.context': 'Paris has been the capital/major city of France since '
                                  'the 10th century and is known for its '
                                  'cultural and historical landmarks.',
           'inputs.query': 'What is the capital/major city of France?',
           'outputs.answer_length.value': 31,
           'outputs.groundeness.groundeness': 5,
           'outputs.groundeness.gpt_groundeness': 5,
           'outputs.groundeness.groundeness_reason': 'The response to the query is supported by the context.'},
          {'inputs.response': 'Albert Einstein developed the theory of '
                            'relativity.',
           'inputs.context': 'Albert Einstein developed the theory of '
                                  'relativity, with his special relativity '
                                  'published in 1905 and general relativity in '
                                  '1915.',
           'inputs.query': 'Who developed the theory of relativity?',
           'outputs.answer_length.value': 51,
           'outputs.groundeness.groundeness': 5,
           'outputs.groundeness.gpt_groundeness': 5,
           'outputs.groundeness.groundeness_reason': 'The response to the query is supported by the context.'},
          {'inputs.response': 'The speed of light is approximately 299,792,458 '
                            'meters per second.',
           'inputs.context': 'The exact speed of light in a vacuum is '
                                  '299,792,458 meters per second, a constant '
                                  "used in physics to represent 'c'.",
           'inputs.query': 'What is the speed of light?',
           'outputs.answer_length.value': 66,
           'outputs.groundeness.groundeness': 5,
           'outputs.groundeness.gpt_groundeness': 5,
           'outputs.groundeness.groundeness_reason': 'The response to the query is supported by the context.'}],
 'traces': {}}

Vereisten voor evaluate()

De evaluate() API vereist een specifieke gegevensindeling en parametersleutelnamen om de evaluatieresultatengrafieken correct weer te geven in uw Foundry-project.

Gegevensindeling

De evaluate() API accepteert alleen gegevens in JSONL-indeling. Voor alle ingebouwde evaluators evaluate() zijn gegevens in de volgende indeling vereist met de vereiste invoervelden. Zie de vorige sectie over de vereiste gegevensinvoer voor ingebouwde evaluators. Het volgende codefragment is een voorbeeld van hoe één regel eruit kan zien:

{
  "query":"What is the capital/major city of France?",
  "context":"France is in Europe",
  "response":"Paris is the capital/major city of France.",
  "ground_truth": "Paris"
}

Indeling van de evaluatorparameter

Wanneer u uw ingebouwde evaluatoren doorgeeft, geeft u de juiste "keyword mapping" op in de evaluators parameterlijst. In de volgende tabel ziet u de trefwoordtoewijzing die is vereist voor de resultaten van uw ingebouwde evaluators die moeten worden weergegeven in de gebruikersinterface wanneer ze zijn aangemeld bij uw Foundry-project.

Hier volgt een voorbeeld van het instellen van de evaluators parameters:

result = evaluate(
    data="data.jsonl",
    evaluators={
        "sexual":sexual_evaluator,
        "self_harm":self_harm_evaluator,
        "hate_unfairness":hate_unfairness_evaluator,
        "violence":violence_evaluator
    }
)

Lokale evaluatie op een doel

Als u een lijst hebt met query's die u wilt uitvoeren en vervolgens wilt evalueren, ondersteunt de evaluate() API ook een target parameter. Deze parameter verzendt query's naar een toepassing om antwoorden te verzamelen en voert vervolgens uw evaluators uit op de resulterende query en het resulterende antwoord.

Een doel kan elke aanroepbare klasse in uw directory zijn. In dit voorbeeld is er een Python script askwiki.py met een aanroepbare klasse askwiki() die als doel is ingesteld. Als u een gegevensset met queries hebt die u naar de eenvoudige askwiki app kunt verzenden, kunt u de onderbouwing van de uitvoer evalueren. Zorg ervoor dat u de juiste kolomtoewijzing voor uw gegevens opgeeft in "column_mapping". U kunt "default" gebruiken om kolomtoewijzing te specificeren voor alle evaluatoren.

Dit is de inhoud in "data.jsonl":

{"query":"When was United States found ?", "response":"1776"}
{"query":"What is the capital/major city of France?", "response":"Paris"}
{"query":"Who is the best tennis player of all time ?", "response":"Roger Federer"}

from askwiki import askwiki

result = evaluate(
    data="data.jsonl",
    target=askwiki,
    evaluators={
        "groundedness": groundedness_eval
    },
    evaluator_config={
        "default": {
            "column_mapping": {
                "query": "${data.queries}",
                "context": "${outputs.context}",
                "response": "${outputs.response}"
            } 
        }
    }
)

Verwante inhoud

• Azure AI Evaluation-clientbibliotheek voor Python
• Problemen met ai-evaluatie-SDK oplossen
• Waarneembaarheid in generatieve AI
• Uitvoeren van evaluaties in de cloudomgeving door gebruik te maken van de Microsoft Foundry SDK
• Synthetische en gesimuleerde gegevens genereren voor evaluatie
• Evaluatieresultaten bekijken in de Foundry-portal
• Aan de slag met Foundry
• Aan de slag met evaluatievoorbeelden