名称： azure-ai-evaluation-py
描述： |
Azure AI Evaluation SDK for Python。用于通过质量、安全性和自定义评估器来评估生成式 AI 应用程序。
触发词："azure-ai-evaluation", "evaluators", "GroundednessEvaluator", "evaluate", "AI quality metrics"。
package: azure-ai-evaluation

Azure AI Evaluation SDK for Python

使用内置和自定义评估器来评估生成式 AI 应用程序的性能。

安装

pip install azure-ai-evaluation

# 如需远程评估支持
pip install azure-ai-evaluation[remote]

环境变量

# 用于 AI 辅助评估器
AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com
AZURE_OPENAI_API_KEY=<your-api-key>
AZURE_OPENAI_DEPLOYMENT=gpt-4o-mini

# 用于 Foundry 项目集成
AIPROJECT_CONNECTION_STRING=<your-connection-string>

内置评估器

质量评估器 (AI 辅助)

from azure.ai.evaluation import (
    GroundednessEvaluator,
    RelevanceEvaluator,
    CoherenceEvaluator,
    FluencyEvaluator,
    SimilarityEvaluator,
    RetrievalEvaluator
)

# 使用 Azure OpenAI 模型配置进行初始化
model_config = {
    "azure_endpoint": os.environ["AZURE_OPENAI_ENDPOINT"],
    "api_key": os.environ["AZURE_OPENAI_API_KEY"],
    "azure_deployment": os.environ["AZURE_OPENAI_DEPLOYMENT"]
}

groundedness = GroundednessEvaluator(model_config)
relevance = RelevanceEvaluator(model_config)
coherence = CoherenceEvaluator(model_config)

质量评估器 (基于 NLP)

from azure.ai.evaluation import (
    F1ScoreEvaluator,
    RougeScoreEvaluator,
    BleuScoreEvaluator,
    GleuScoreEvaluator,
    MeteorScoreEvaluator
)

f1 = F1ScoreEvaluator()
rouge = RougeScoreEvaluator()
bleu = BleuScoreEvaluator()

安全评估器

from azure.ai.evaluation import (
    ViolenceEvaluator,
    SexualEvaluator,
    SelfHarmEvaluator,
    HateUnfairnessEvaluator,
    IndirectAttackEvaluator,
    ProtectedMaterialEvaluator
)

violence = ViolenceEvaluator(azure_ai_project=project_scope)
sexual = SexualEvaluator(azure_ai_project=project_scope)

单行评估

from azure.ai.evaluation import GroundednessEvaluator

groundedness = GroundednessEvaluator(model_config)

result = groundedness(
    query="什么是 Azure AI？",
    context="Azure AI 是微软的 AI 平台...",
    response="Azure AI 提供 AI 服务和工具。"
)

print(f"事实性得分: {result['groundedness']}")
print(f"理由: {result['groundedness_reason']}")

使用 evaluate() 进行批量评估

from azure.ai.evaluation import evaluate

result = evaluate(
    data="test_data.jsonl",
    evaluators={
        "groundedness": groundedness,
        "relevance": relevance,
        "coherence": coherence
    },
    evaluator_config={
        "default": {
            "column_mapping": {
                "query": "${data.query}",
                "context": "${data.context}",
                "response": "${data.response}"
            }
        }
    }
)

print(result["metrics"])

复合评估器

from azure.ai.evaluation import QAEvaluator, ContentSafetyEvaluator

# 在一个评估器中包含所有质量指标
qa_evaluator = QAEvaluator(model_config)

# 在一个评估器中包含所有安全指标
safety_evaluator = ContentSafetyEvaluator(azure_ai_project=project_scope)

result = evaluate(
    data="data.jsonl",
    evaluators={
        "qa": qa_evaluator,
        "content_safety": safety_evaluator
    }
)

评估应用程序目标

from azure.ai.evaluation import evaluate
from my_app import chat_app  # 你的应用程序

result = evaluate(
    data="queries.jsonl",
    target=chat_app,  # 可调用对象，接收查询并返回响应
    evaluators={
        "groundedness": groundedness
    },
    evaluator_config={
        "default": {
            "column_mapping": {
                "query": "${data.query}",
                "context": "${outputs.context}",
                "response": "${outputs.response}"
            }
        }
    }
)

自定义评估器

基于代码

from azure.ai.evaluation import evaluator

@evaluator
def word_count_evaluator(response: str) -> dict:
    return {"word_count": len(response.split())}

# 在 evaluate() 中使用
result = evaluate(
    data="data.jsonl",
    evaluators={"word_count": word_count_evaluator}
)

基于提示词

from azure.ai.evaluation import PromptChatTarget

class CustomEvaluator:
    def __init__(self, model_config):
        self.model = PromptChatTarget(model_config)

    def __call__(self, query: str, response: str) -> dict:
        prompt = f"为这个响应打分（1-5分）: 查询: {query}, 响应: {response}"
        result = self.model.send_prompt(prompt)
        return {"custom_score": int(result)}

记录到 Foundry 项目

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

project = AIProjectClient.from_connection_string(
    conn_str=os.environ["AIPROJECT_CONNECTION_STRING"],
    credential=DefaultAzureCredential()
)

result = evaluate(
    data="data.jsonl",
    evaluators={"groundedness": groundedness},
    azure_ai_project=project.scope  # 将结果记录到 Foundry
)

print(f"查看结果: {result['studio_url']}")

评估器参考

最佳实践

1. 使用复合评估器进行全面评估。
2. 正确映射列 — 列不匹配会导致静默失败。
3. 记录到 Foundry以便跟踪和跨运行比较。
4. 创建自定义评估器用于特定领域的指标。
5. 当有标准答案时，使用 NLP 评估器。
6. 安全评估器需要 Azure AI 项目作用域。
7. 批量评估比单行循环更高效。

参考文件