Avaliar conjuntos de dados de conversa com o SDK do Microsoft Foundry

Avalie conversas completas de conjuntos de dados no nível de turno ou conversa.

Pré-requisitos

Os exemplos usam o cliente SDK configurado em Configurar o cliente SDK.

Avaliar conjuntos de dados de conversa

Avalie conversas completas para avaliar a qualidade do agente em interações inteiras do usuário - não apenas respostas individuais. Use a avaliação no nível da conversa para identificar problemas de qualidade, como resolução incompleta de tarefas, frustração do usuário e regressões em chamadas de ferramentas que a avaliação no nível do rodada não detecta.

Por exemplo, considere um agente de suporte em que o usuário vai ficando frustrado ao longo de várias interações:

Turno 1 — Usuário: "Preciso redefinir minha senha." Agente: "Encontrei sua conta. Enviarei um link de redefinição."

Turno 2 — Usuário: "Não recebi o e-mail." Atendente: "Reenviei o link." Verifique o spam."

Turno 3 — Usuário: "Ainda nada. Você pode simplesmente redefini-lo diretamente?" Agente: "Enviei outro link de redefinição."

Um avaliador em nível de turno atribui pontuação apenas à última resposta — que é educada e adota uma ação —, por isso ela recebe uma boa pontuação. Um avaliador em nível de conversa, que classifica a satisfação do cliente ao longo de toda a conversa, sinaliza que o agente repetiu a mesma ação malsucedida três vezes sem tentar uma alternativa, sem resolver o problema do usuário.

A avaliação em nível de conversa difere da avaliação em nível de turno de várias maneiras:

Aspeto De nível de rodada Nível de conversa
Scope Pares de consulta-resposta individuais Conversas completas com múltiplas interações
Métricas Qualidade e segurança de cada resposta Resultados em nível de conversa e satisfação do usuário
Formato dos dados JSONL com campos query e response JSONL com matriz messages que contém a conversa completa
Caso de uso Testando respostas de modelo individual Testando experiências completas com agentes

Escolha o fluxo de trabalho de conversa que corresponde à fonte de dados:

Workflow Quando usar Tipo de fonte de dados
De conjunto de dados ou em linha Você tem rastros locais de conversa ou dados de teste jsonl com file_id ou file_content
Conversas publicadas Você deseja avaliar conversas específicas ou o tráfego de produção amostrado do Application Insights azure_ai_trace_data_source_preview por trace_source
Conversas simuladas Você deseja gerar conversas de teste sintéticas azure_ai_user_conversation_simulation

Escolher um nível de avaliação

O parâmetro evaluation_level da execução determina se os avaliadores avaliam turnos individuais ou conversas completas:

Valor Behavior
"turn" Os avaliadores pontuam cada turno de forma independente.
"conversation" Os avaliadores pontuam toda a conversa como um todo.
(omitido) Usa "turn" como padrão.

Importante

Compatibilidade do avaliador: cada avaliador dá suporte a níveis de avaliação específicos. Verifique o campo do supported_evaluation_levels avaliador nos níveis de avaliação.

  • Os avaliadores somente de turno (por exemplo, builtin.fluency, builtin.relevance) não são executados com evaluation_level="conversation". Se um avaliador não oferecer suporte à avaliação em nível de conversa, o serviço ignorará esse avaliador em vez de fazer a execução da avaliação falhar.

  • Avaliadores que dão suporte à avaliação em nível de conversa: Os seguintes avaliadores internos dão suporte à avaliação de nível de turno (turno único) e de conversa (várias voltas):

    • builtin.output_quality
    • builtin.tool_use_quality
    • builtin.deflection_rate
    • builtin.customer_satisfaction
    • builtin.task_completion
    • builtin.coherence
    • builtin.groundedness

    builtin.output_quality e builtin.tool_use_quality são avaliadores compostos, que avaliam várias dimensões de qualidade.

  • Para avaliação em nível de turno, todos os avaliadores internos, exceto builtin.document_retrieval e o obsoleto builtin.quality_grader, dão suporte ao formato de entrada messages. Os avaliadores do Azure OpenAI label_model, python_grader, text_similarity, score_model e string_check não dão suporte ao formato de entrada messages.

Erros comuns

Erro Cause Solução
O avaliador foi ignorado Usar evaluation_level="conversation" com um avaliador que não dá suporte à avaliação em nível de conversa Use um avaliador de nível de conversa ou altere para evaluation_level="turn" se você precisar desse avaliador

Preparar dados de conversa

Crie um arquivo JSONL em que cada linha contenha uma conversa completa no messages campo. Cada mensagem deve incluir um role (usuário, assistente ou sistema) e content. Para obter um exemplo completo, consulte os exemplos de avaliação de conversação no SDK.

 {"messages": [{"role": "user", "content": "What's my account balance?"}, {"role": "assistant", "content": "Your current balance is $1,234.56."}, {"role": "user", "content": "Thanks!"}, {"role": "assistant", "content": "You're welcome! Is there anything else?"}]}

Você também pode incluir definições de ferramentas e chamadas de ferramenta se o agente usar ferramentas:

{"messages": [{"role": "user", "content": "What is the capital/major city of France?"}, {"role": "assistant", "content": "Paris"}]}
{"messages": [{"role": "user", "content": "How do I reverse a string in Python?"}, {"role": "assistant", "content": "You can reverse a string in Python by using slicing: string[::-1]"}]}
{"messages": [{"role": "user", "content": "What are the main causes of climate change?"}, {"role": "assistant", "content": "The main causes of climate change are the increase in greenhouse gases in the atmosphere, primarily due to human activities such as burning fossil fuels and deforestation."}]}
{"messages": [{"role": "user", "content": "What's my account balance?"}, {"role": "assistant", "content": null, "tool_calls": [{"id": "call_abc123", "type": "function", "function": {"name": "get_account_balance", "arguments": "{\"account_id\": \"ACCT-7890\"}"}}]}, {"role": "tool", "tool_call_id": "call_abc123", "content": "{ \"balance\": 1234.56, \"currency\": \"USD\" }"}, {"role": "assistant", "content": "Your current balance is 1,234.56."}, {"role": "user", "content": "Thanks!"}, {"role": "assistant", "content": "You're welcome! Is there anything else?"}], "tool_definitions": [{"name": "get_account_balance", "description": "Retrieves the current balance for a customer account", "parameters": {"type": "object", "properties": {"account_id": {"type": "string"}}, "required": ["account_id"]}}]}
{"messages": [{"role": "user", "content": "Explain the theory of relativity in simple terms."}, {"role": "assistant", "content": "Einstein's theory of relativity shows that space and time are interconnected and relative to the observer's frame of reference."}]}
{"messages": [{"role": "user", "content": "What's the weather in Seattle?"}, {"role": "assistant", "content": null, "tool_calls": [{"id": "call_002", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\": \"Seattle, WA\"}"}}]}, {"role": "tool", "tool_call_id": "call_002", "content": "{ \"temperature\": 55, \"condition\": \"Cloudy\" }"}, {"role": "assistant", "content": "It's currently 55F and cloudy in Seattle."}], "tool_definitions": [{"name": "get_weather", "description": "Get the current weather for a location", "parameters": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}]}
{"messages": [{"role": "user", "content": "What is the tallest mountain in the world?"}, {"role": "assistant", "content": "Mount Everest is the tallest mountain in the world."}]}
{"messages": [{"role": "user", "content": "Is 4 x 2 = 16?"}, {"role": "assistant", "content": "No, 4 x 2 = 8."}]}
{"messages": [{"role": "user", "content": "What is the best Italian desert?"}, {"role": "assistant", "content": "Tiramisu is a popular Italian dessert."}]}
{"messages": [{"role": "user", "content": "What is the chemical formula for water?"}, {"role": "assistant", "content": "The chemical formula for water is H2O."}]}

Definir o esquema de dados e os avaliadores

Especifique o esquema para seus dados de conversa e selecione os avaliadores projetados para avaliação em nível de conversa. Mapeie messages para todos os avaliadores. Para avaliadores que avaliam o comportamento da ferramenta, também mapeie tool_definitions. Os avaliadores no nível da conversa avaliam toda a interação, em vez de cada turno individual.

pip install "azure-ai-projects>=2.2.0"
import os
from openai.types.eval_create_params import DataSourceConfigCustom
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    data_source_config = DataSourceConfigCustom(
        type="custom",
        item_schema={
            "type": "object",
            "properties": {
                "messages": {"type": "array"},
                "tool_definitions": {"type": "array"},
            },
            "required": ["messages"],
        },
        include_sample_schema=False,
    )

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="output_quality",
            evaluator_name="builtin.output_quality",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="tool_use_quality",
            evaluator_name="builtin.tool_use_quality",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="deflection_rate",
            evaluator_name="builtin.deflection_rate",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

Criar avaliação e executar

Baixe sample_data_multiturn_conversations.jsonl antes de executar o exemplo.

from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileID,
)

# Upload conversation data
data_id = project_client.datasets.upload_file(
    name="multiturn-conversation-data",
    version="1",
    file_path="./sample_data_multiturn_conversations.jsonl",
).id

# Create the evaluation
eval_object = openai_client.evals.create(
    name="Multi-turn Conversation Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run with evaluation_level set to "conversation"
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="multiturn-conversation-run",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileID(
            type="file_id",
            id=data_id,
        ),
    ),
    extra_body={"evaluation_level": "conversation"},
)

Para sondar a conclusão e interpretar os resultados, consulte Obter resultados de avaliação de nuvem.

Para obter um exemplo executável completo, consulte sample_multiturn_conversation_evaluation.py no GitHub.

Próximas Etapas