Registry / azure / azure-ai-evaluation

azure-ai-evaluation

JSON →
library1.17.0pypypi✓ verified 85d ago

The Azure AI Evaluation SDK for Python provides tools to quantitatively measure the performance of generative AI applications. It offers built-in and custom evaluators for mathematical, AI-assisted quality, and safety metrics, enabling comprehensive insights into application capabilities and limitations. This library is actively developed, with recent releases focusing on bug fixes and new features, maintaining a regular release cadence as part of the broader Azure SDK for Python.

pip install azure-ai-evaluation
INSTALL
IMPORT
SIG · AZURE-AI-EVALUATIO
A
azure-ai-evaluation
azurepythonv1.17.0
Install
19.3s avg
Import
5765ms
Disk
275MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.17.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 5.994s · 263.8MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 19.3s · import 5.536s · 257MB
275MB installed
● package 275MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

evaluate
from azure.ai.evaluation import evaluate
Main function to run evaluations.
RelevanceEvaluator
from azure.ai.evaluation import RelevanceEvaluator
Example of a built-in AI-assisted quality evaluator.
BleuScoreEvaluator
from azure.ai.evaluation import BleuScoreEvaluator
Example of a built-in NLP metric evaluator.
ViolenceEvaluator
from azure.ai.evaluation import ViolenceEvaluator
Example of a built-in risk and safety evaluator.

This quickstart demonstrates how to initialize a `RelevanceEvaluator` with Azure OpenAI model configuration using environment variables. It outlines how to prepare data for evaluation and mentions the `evaluate` function for batch processing, with optional integration for logging results to an Azure AI Project. Ensure your Azure OpenAI endpoint, API key, and deployment name are set as environment variables.

import os from azure.ai.evaluation import evaluate, RelevanceEvaluator # Ensure environment variables are set for Azure OpenAI # AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_KEY, AZURE_OPENAI_DEPLOYMENT model_config = { "azure_endpoint": os.environ.get("AZURE_OPENAI_ENDPOINT", ""), "api_key": os.environ.get("AZURE_OPENAI_KEY", ""), "azure_deployment": os.environ.get("AZURE_OPENAI_DEPLOYMENT", ""), } # Example for a simple AI-assisted quality evaluation relevance_evaluator = RelevanceEvaluator(model_config=model_config) # For a conversation/turn based evaluation # result = relevance_evaluator( # query="What is the capital of Japan?", # response="Tokyo is the capital of Japan." # ) # For evaluating a dataset data_for_evaluation = [ {"id": "1", "query": "What is the capital of France?", "response": "Paris.", "context": "France is a country in Europe. Its capital is Paris."}, {"id": "2", "query": "Who painted the Mona Lisa?", "response": "Leonardo da Vinci.", "context": "Leonardo da Vinci was an Italian polymath."} ] # You can use `evaluate` function for batch evaluation on a dataset # Ensure you have a configured Azure AI Project if logging results to AI Studio # azure_ai_project = { # "subscription_id": os.environ.get("AZURE_SUBSCRIPTION_ID", ""), # "resource_group_name": os.environ.get("AZURE_RESOURCE_GROUP", ""), # "project_name": os.environ.get("AZURE_AI_PROJECT_NAME", ""), # } # results = evaluate( # data=data_for_evaluation, # evaluators=[relevance_evaluator], # # azure_ai_project=azure_ai_project # Uncomment to log to AI Studio # ) print("Evaluators initialized. Ready for evaluation.")
Debug
Known issues
breakingEnvironment variable `PF_EVALS_BATCH_USE_ASYNC` was renamed to `AI_EVALS_BATCH_USE_ASYNC`. Input requirements for `RetrievalEvaluator`, `RelevanceEvaluator`, and `FluencyEvaluator` have changed.
fix
Update environment variable name and adjust inputs for the specified evaluators according to the latest SDK documentation.
affects: Potentially from v1.16.x or recent beta versions (e.g., 0.1.0b6153055 and earlier betas). Check changelog for precise version.
breakingA breaking change in the OpenAI Python package (e.g., removal of `eval_string_check_grader` in v1.78.0) can cause compatibility issues and silent failures (returning zero scores) with Azure AI Evaluation SDK's custom graders like `AzureOpenAIPythonGrader`.
fix
Review and update custom grader logic, ensuring correct function signatures (`def grade(sample, item): -> float`) and valid templating variables. Refer to the Azure AI Evaluation SDK troubleshooting guide for compatible OpenAI package versions or necessary adaptations.
affects: OpenAI Python package >= 1.78.0, affecting Azure AI Evaluation SDK versions depending on when the breaking change was introduced.
gotchaEvaluations can get stuck in 'Starting' or 'Running' state due to insufficient Azure OpenAI model capacity/quota, misconfigured authentication/permissions (e.g., missing 'Azure AI User' role for `DefaultAzureCredential`), incorrect dataset/mapping, or hitting rate limits.
fix
Verify Azure OpenAI deployment capacity, confirm `DefaultAzureCredential` is correctly set up with the 'Azure AI User' role on the Foundry project, validate dataset JSONL format and field mappings, and implement retry logic with exponential backoff for rate limit errors.
affects: All versions
gotchaEmbedding evaluation configuration directly within evaluation scripts can lead to 'configuration drift,' where different parts of the system measure metrics inconsistently, making historical comparisons unreliable.
fix
Utilize project-level resources for evaluators in Azure AI Foundry (v2 SDK), defining them once for reuse across multiple agents and datasets. This separates how quality is measured from what is being evaluated.
affects: All versions
deprecatedThe environment variable `PF_EVALS_BATCH_USE_ASYNC` was deprecated and renamed. The `[remote]` extra for installation has been removed as it's no longer needed when tracking results in Azure AI Studio.
fix
Update your code to use the new environment variable `AI_EVALS_BATCH_USE_ASYNC` and remove `[remote]` extra from installation commands.
affects: Recent versions leading up to 1.16.x and beyond.
breakingFixed Jinja2 Server-Side Template Injection (SSTI) vulnerability (CWE-1336) by replacing `jinja2.Template` with `jinja2.sandbox.SandboxedEnvironment` across all template rendering paths.
fix
Upgrade to version 1.16.5 or later to mitigate this security vulnerability.
affects: <=1.16.4
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure.ai.evaluation'
The 'azure-ai-evaluation' package is not installed in the Python environment.
fix
Install the package using pip: 'pip install azure-ai-evaluation'.
ImportError: cannot import name 'EvaluationClient' from 'azure.ai.evaluation'
The 'EvaluationClient' class does not exist in the 'azure.ai.evaluation' module.
fix
Refer to the official documentation to find the correct class or function to import for your use case.
Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead
The 'max_tokens' parameter is not supported by the specified model; it requires 'max_completion_tokens' instead.
fix
Replace 'max_tokens' with 'max_completion_tokens' in your code when configuring the model parameters.
ModuleNotFoundError: No module named 'openai'
This often occurs due to incompatible versions between the `azure-ai-evaluation` SDK and the `openai` Python package, especially after breaking changes in the `openai` library (e.g., version 1.78.0 and above).
fix
Pin the `openai` package to a compatible version, typically an older version (e.g., `openai<=1.77.0`) that is known to work with your `azure-ai-evaluation` SDK version. You may also need to update `azure-ai-evaluation` to its latest version to ensure compatibility with newer `openai` versions.
ImportError: cannot import name 'ViolenceMultimodalEvaluator'
Specific multimodal evaluator classes like `ViolenceMultimodalEvaluator` were removed or renamed in recent versions of the Azure AI Evaluation SDK (e.g., v1.3.0 and later) and replaced by generic counterparts (e.g., `ViolenceEvaluator`).
fix
Update your code to use the new generic evaluator names, such as `ViolenceEvaluator` instead of `ViolenceMultimodalEvaluator`.
Upgrade
Version history
1.17.0latest on PyPI · released Jun 4, 2026
Audit
Dependencies
python-dotenvoptionalCommonly used for managing environment variables in local development for Azure OpenAI credentials.
Azure AI Foundry Project or Azure OpenAIoptionalRequired for using AI-assisted evaluators and for tracking results in the Azure AI Studio.
Agent activity
39 hits · last 30 days
node
32
OpenAI (training)
1
Resources
azure-ai-evaluation — pip install azure-ai-evaluation · libregistry