Evaluation and Validation for Generative AI

Every evaluation starts with one question: what can you compare the answer against? That single choice picks which family of evaluator you reach for, so start there rather than with a specific metric name.

Azure AI Evaluation ships its built-in evaluators^[1] in four families, each defined by what does the judging and what input it needs:

• AI-assisted quality evaluators (groundedness, relevance, coherence, fluency) use a GPT model as an LLM-as-a-judge^[2].
• Textual-similarity (NLP) evaluators (F1, BLEU, GLEU, ROUGE, METEOR) compute token or n-gram overlap against a reference answer, with no model in the loop.
• Risk and safety evaluators (violence, sexual, self-harm, hate/unfairness, and more) call a Microsoft-hosted service to score harmful content.
• Agentic evaluators (intent resolution, tool-call accuracy, task adherence) judge how an agent behaved, not just its final text.

Four data terms decide the rest. The query is the input sent to your app, the response is what the app returned, the context is the grounding or source documents a retrieval step supplied, and the ground_truth is a known-correct reference answer written by a human. An evaluation dataset carries whichever of these four each chosen evaluator needs, and no more.

The selection rule falls straight out of the families. If you have a fixed ground_truth, use an NLP-similarity metric. If you have context but no reference, use groundedness or relevance. If you have neither, use the LLM-judge quality metrics. To screen for harmful content, use the hosted safety evaluators. The figure groups the families and their members so you can see the whole catalog at a glance before the sections that follow drill into each one.

One evaluator on one row is a spot check; real evaluation runs a set of evaluators over a whole dataset. That is what the evaluate()^[2] API in the azure-ai-evaluation SDK does: it runs many built-in and custom evaluators over one dataset in a single pass and returns both aggregate metrics and per-row scores.

The dataset is a file path, not an in-memory list. JSON Lines (JSONL, one JSON object per line) is the standard format used across the documentation and is required for the results charts to render in your project; the SDK API reference for the data parameter states plainly that "JSONL and CSV files are supported"^[3]. Passing a Python list or a bare JSON array instead is the classic mistake.

Mapping columns to evaluator inputs

Evaluators look for specific keywords (query, response, context, ground_truth). When your dataset's column names differ, a column_mapping inside evaluator_config re-aligns them: use ${data.<column>} to point at a dataset column and ${outputs.<field>} to point at a value your target (the app or function under evaluation that produced the outputs) generated. A "default" mapping applies to every evaluator, while a per-evaluator mapping overrides it.

Run several evaluators over one JSONL dataset and log to Foundry

from azure.ai.evaluation import evaluate, GroundednessEvaluator, RelevanceEvaluator

# model_config supplies the GPT judge for the AI-assisted evaluators
# ...
result = evaluate(
    data="data.jsonl",                 # file path; JSONL standard, CSV also supported
    evaluators={
        "groundedness": GroundednessEvaluator(model_config),
        "relevance": RelevanceEvaluator(model_config),
    },
    evaluator_config={
        "groundedness": {
            "column_mapping": {
                "query": "${data.queries}",
                "context": "${data.context}",
                "response": "${data.response}",
            }
        },
        # ...
    },
    azure_ai_project=azure_ai_project,  # optional: log the run to Foundry
)
print(result.studio_url)   # link to the run in your Foundry project

The data argument is the JSONL file; the evaluators dict pairs an alias with each evaluator; and the evaluator_config block holds the column_mapping that binds the dataset's queries column to the evaluator's expected query keyword. Passing azure_ai_project logs the run so the aggregate and per-row scores appear in the portal, reachable through result.studio_url. The # ... lines mark model setup and further mappings omitted for brevity. Composite evaluators such as QAEvaluator bundle several quality metrics into a single entry when you want them all at once.

When there is no reference answer to diff against, let a model judge the writing. The four AI-assisted quality evaluators do exactly that, and they share one mechanism: each sends the data to a GPT deployment you name in model_config (an AzureOpenAIModelConfiguration), and each returns a 1-to-5 Likert score where higher is better, with a default pass threshold of 3 and a written reason. Because a language model does the scoring, these are the LLM-as-a-judge metrics.

What differs between them is which inputs each one reads:

Evaluator	Reads	Measures
Groundedness	response, context (query optional)	Is the answer supported by the supplied context?
Relevance	query, response	Does the answer address the question?
Coherence	query, response	Does the answer hang together logically?
Fluency	response	Is the text grammatical and readable?

Two of these form the retrieval-augmented generation (RAG) pair: groundedness and relevance^[4] exist to catch a RAG system that either invents facts absent from its sources (ungrounded) or answers off-topic (irrelevant). The other two are general-purpose^[5] writing-quality checks. Watch the input requirement that trips people up: coherence requires both the query and the response, while fluency reads the response alone. It is tempting to assume coherence needs only the answer, but it scores the answer as a reply to the question, so it needs the question too. These relevance and groundedness signals also feed straight into RAG tuning; see optimizing RAG performance.

One member breaks the mold. GroundednessProEvaluator (preview) detects ungrounded claims using the hosted Foundry evaluation service rather than your GPT judge, so it takes azure_ai_project instead of model_config and returns a boolean pass/fail rather than a 1-to-5 score. Treat it as a safety-style evaluator that happens to measure groundedness, and do not wire a model_config to it.

Sometimes you already know the right answer. When a fixed reference (the ground_truth) exists and exact wording overlap is the test, skip the LLM judge entirely and use the textual-similarity NLP evaluators^[6]. They score how much the response overlaps the ground_truth by token or n-gram math, need no GPT deployment, and are all generally available. In the SDK they are named F1Score, BleuScore, GleuScore, RougeScore, and MeteorScore (the F1/BLEU/GLEU/ROUGE/METEOR metrics named elsewhere on this page).

Evaluator	Overlap it scores	Output	Default threshold
F1Score	Shared tokens (precision and recall)	0-1 float	0.5
BleuScore	N-gram overlap (machine translation)	0-1 float	0.5
GleuScore	Per-sentence variant of BLEU	0-1 float	0.5
RougeScore	Recall-oriented n-gram overlap	3 floats: precision, recall, F1	0.5 each
MeteorScore	Overlap with synonyms and stemming	0-1 float	0.5

All five take just ground_truth plus response and return a 0-to-1 float against a default 0.5 threshold, with one exception: RougeScore returns three separate scores (precision, recall, and F1), each judged against its own 0.5 threshold. The selection rule is deterministic: pick a similarity metric when a fixed reference answer exists and exact overlap is the criterion (machine translation, fixed-answer retrieval, NLP benchmarking); when there is no ground truth to compare against, fall back to the AI-assisted quality metrics from the previous section. These metrics also cannot run at all without a ground_truth.

One name trap: SimilarityEvaluator looks like it belongs in this table, but it does not. It measures semantic similarity with an LLM judge, so it scores 1 to 5 and needs a model_config and deployment, exactly like the quality metrics. The math-only evaluators above never touch a model.

Quality is not the only risk; a fluent, well-grounded answer can still be harmful. The risk and safety evaluators^[7] catch that, and they work differently from every metric so far: they run inside a Microsoft-hosted Foundry evaluation service, not on your GPT judge. You instantiate them with your Foundry project (azure_ai_project) and a credential, never a model_config or deployment_name.

The 0-to-7 severity scale

The four content-harm evaluators (ViolenceEvaluator, SexualEvaluator, SelfHarmEvaluator, HateUnfairnessEvaluator) return a 0-to-7 severity score, bucketed as Very low (0-1), Low (2-3), Medium (4-5), and High (6-7). Read this scale the opposite way to the quality metrics: here a higher number means more harmful. Given the default threshold of 3, a response scores pass when its severity is at or below 3 and fail when it is above. Over a whole dataset the service reports a defect rate: the percentage of responses whose severity exceeds the threshold, which is the intended dataset-level signal rather than a single worst-case score. ContentSafetyEvaluator is a composite that runs all four harms at once for one combined result.

Beyond the four harms: pass/fail evaluators

Not every safety evaluator uses the 0-7 scale. IndirectAttackEvaluator (cross-domain prompt injection, XPIA) returns a boolean pass/fail: fail means the response obeyed a jailbreak instruction hidden inside retrieved context or a source document, not one typed into the user's own prompt. ProtectedMaterialEvaluator also returns pass/fail, flagging text under copyright (song lyrics, recipes, articles) via the Azure AI Content Safety Protected Material for Text service. So do not assume every risk evaluator emits a severity number; several are simple booleans.

One operational constraint: because these run on hosted safety models, the service (and adversarial red teaming) is available only in select regions^[8] such as East US 2, France Central, and Sweden Central. Create the Foundry project in a supported region, and check the current region list before you rely on it, because coverage changes over time.

You cannot evaluate what you cannot feed the evaluators, and real production traffic is often missing early on. Azure AI Evaluation gives you two ways to manufacture inputs, and they serve opposite purposes.

Non-adversarial: the Simulator

The Simulator^[9] class generates non-adversarial synthetic query and response conversations from a text blob or a search index. It gives you consistent, repeatable inputs so you can compare prompt variants without waiting for live users. Reaching for a content filter or a blocklist to build a test set is a category error: filters moderate content at runtime, they do not generate a controlled dataset.

Adversarial: red-team data and the AI Red Teaming Agent

For safety testing you want inputs designed to break the system. AdversarialSimulator produces red-team datasets using a service-hosted model with its safety behaviors turned off; DirectAttackSimulator builds user-prompt injection (UPIA) jailbreak data, and IndirectAttackSimulator builds cross-domain (XPIA) data. All of these need a Foundry project (azure_ai_project) and run only in the supported safety regions.

The AI Red Teaming Agent^[10] (preview) automates the whole campaign rather than just building a dataset. Built on Microsoft's open-source PyRIT (Python Risk Identification Tool) framework, it probes a model, application, or agent endpoint with seed attack objectives, converts them with attack strategies (such as Base64 encoding, Flip, and the multi-turn Crescendo escalation) to slip past the model's safety alignment, scores each attack-response pair with the hosted Risk and Safety Evaluators, and reduces the run to an Attack Success Rate (ASR): the percentage of attacks that elicited an undesirable response. It emits a scorecard broken down by risk category to drive a pre-deployment go/no-go decision. Keep the three tools straight: Simulator builds benign data, AdversarialSimulator builds a red-team dataset, and the AI Red Teaming Agent runs the end-to-end scan that produces the ASR.

Evaluating agents, not just answers

An agent can produce a perfectly fluent final message while calling the wrong tool or ignoring its instructions, so agent quality needs its own agentic evaluators^[2]. IntentResolutionEvaluator checks whether the agent correctly understood what the user wanted; ToolCallAccuracyEvaluator checks whether the right tools were called with the right parameters (on a 1-to-5 rubric); and TaskAdherenceEvaluator checks whether the agent followed its instructions and stayed on task. These read the agent message schema, including the tool_calls trace, so evaluating an agent means capturing its tool-invocation trace as input, not only the final assistant message. That is why agent evaluation is tightly coupled to tracing; see observability for generative AI.

Custom evaluators

When no built-in metric fits your domain, write your own and pass it to the same evaluate() run. A custom evaluator^[11] is either a code-based Python callable or class (for a deterministic score such as answer length or a regex match) or a prompt-based Prompty file that instructs a judge model with your own rubric. Both slot into the evaluators dictionary alongside the built-ins, so a run can mix built-in and custom metrics in one pass.

From manual check to CI/CD gate

Evaluation earns its keep when it stops being a one-off notebook run. Cloud (remote) evaluation^[12] lets you wire evaluation into a CI/CD (continuous integration and delivery) pipeline such as GitHub Actions as an automated quality gate, failing a build or blocking a release when a quality or safety score falls below threshold. Build all of this on the azure-ai-evaluation SDK plus Foundry evaluations. The older Evaluate-with-prompt-flow^[13] workflow is on a retirement path, with prompt flow scheduled to retire on April 20, 2027, so it is not the tool to choose for new evaluation work.

Most AI-300 questions on this objective test one distinction. Read the stem for the signal, then pick the answer that matches.

• Data shape: 'a fixed correct answer exists' or 'compare against a reference' points to an NLP-similarity metric (F1, BLEU, ROUGE) and a ground_truth; 'no reference answer' points to the AI-assisted quality metrics.
• RAG signals: 'grounded in the retrieved documents' means groundedness (needs context); 'answers the question asked' means relevance. No context supplied means groundedness has nothing to score.
• Coherence vs fluency inputs: coherence needs the query and the response; fluency needs only the response. A stem that supplies just responses and asks about writing quality points to fluency.
• Config object: a GPT model_config means an AI-assisted quality metric; azure_ai_project with no model means a hosted safety evaluator. Passing model_config to a safety evaluator is wrong.
• Scale direction: a 1-to-5 score where higher is better is a quality metric; a 0-to-7 score where higher is worse is content-safety severity, with pass at or below the default threshold of 3.
• Dataset-level safety: the intended aggregate is the defect rate (share above threshold), not a single worst-case score.
• Generate vs attack: Simulator for benign test data; AdversarialSimulator for a red-team dataset; the AI Red Teaming Agent for an end-to-end scan that reports an Attack Success Rate. Content filters do not generate datasets.
• Agents: evaluating an agent needs the tool_calls trace and the agentic evaluators (intent resolution, tool-call accuracy, task adherence), not just groundedness on the final text.
• Automation: 'block a release when quality drops' means cloud evaluation as a CI/CD gate; new work uses the Azure AI Evaluation SDK, not prompt flow.