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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 5.994s · 263.8MB
glibcpy 3.10–3.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.fixUpdate 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`.fixReview 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.fixVerify 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.fixUtilize 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.fixUpdate 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.fixUpgrade 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.
fixInstall 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.
fixRefer 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.
fixReplace '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).
fixPin 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`).
fixUpdate 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.