Avaliar conjuntos de dados de conversa com o Microsoft Foundry SDK

Avalie conversas completas em conjuntos de dados ao nível do turno ou da conversa.

Pré-requisitos

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

Avaliar conjuntos de dados de conversação

Avalie conversas completas para avaliar a qualidade dos agentes em todas as interações com os utilizadores – não apenas nas respostas individuais. Utilize a avaliação ao nível da conversa para identificar problemas de qualidade, como a resolução incompleta de tarefas, a frustração do utilizador e regressões nas chamadas de ferramentas, que a avaliação ao nível de cada turno não deteta.

Por exemplo, considere um agente de suporte onde o utilizador fica frustrado ao longo de vários turnos:

Turno 1 — Utilizador: "Preciso de redefinir a minha palavra-passe." Agente: "Encontrei a tua conta. Vou enviar um link de reset."

Turno 2 — Utilizador: "Não recebi o email." Agente: "Reenviei o link. Por favor, verifique o spam."

Turno 3 — Utilizador: "Ainda nada. Podes simplesmente reiniciar diretamente?" Agente: "Enviei outro link de reset."

Um avaliador por turno só nota a última resposta – que é educada e toma ação – por isso a pontuação é boa. Um avaliador ao nível da conversa que avalia a satisfação do cliente ao longo da conversa sinaliza que o agente repetiu a mesma ação falhada três vezes sem tentar uma alternativa, deixando o problema do utilizador por resolver.

A avaliação ao nível da conversa difere da avaliação por turnos em vários aspetos:

Aspect Nível de curva Nível de conversa
Scope Pares individuais de consulta-resposta Conversas completas com múltiplas interações
Métricas Qualidade e segurança de cada resposta Resultados ao nível da conversa e satisfação do utilizador
Formato dos dados JSONL com os campos query e response JSONL com matriz messages que contém a conversa completa
Caso de utilização Testar respostas individuais de modelos Teste de experiências com agentes de ponta a ponta

Escolha o fluxo de trabalho de conversa que corresponda à sua fonte de dados:

Workflow Quando utilizar Tipo de fonte de dados
Do conjunto de dados ou em linha Tem registos de conversação locais ou dados de teste jsonl com file_id ou file_content
Conversas publicadas Quer avaliar conversas específicas ou tráfego de produção amostrado do Application Insights azure_ai_trace_data_source_preview com trace_source
Conversas simuladas Queres gerar conversas de teste sintéticas azure_ai_user_conversation_simulation

Escolha um nível de avaliação

O parâmetro evaluation_level na execução determina se os avaliadores avaliam interações individuais ou conversas completas:

valor Comportamento
"turn" Os avaliadores pontuam cada turno de forma independente.
"conversation" Os avaliadores avaliam toda a conversa como um todo.
(omitido) O valor padrão é "turn".

Importante

Compatibilidade do avaliador: Cada avaliador suporta níveis específicos de avaliação. Verifique o campo Avaliador supported_evaluation_levels em Níveis de Avaliação.

  • Avaliadores apenas de turno (por exemplo, builtin.fluency, builtin.relevance) não executam com evaluation_level="conversation". Se um avaliador não suportar a avaliação ao nível da conversa, o serviço ignora esse avaliador em vez de falhar a execução da avaliação.

  • Avaliadores que suportam a avaliação ao nível da conversa: Os seguintes avaliadores incorporados suportam tanto a avaliação por turnos (turno único) como a nível da conversa (múltiplos turnos):

    • 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 múltiplas dimensões de qualidade.

  • Para avaliação a nível de turnos, todos os avaliadores incorporados, exceto builtin.document_retrieval e o obsoleto builtin.quality_grader, suportam o formato de entrada messages. Os avaliadores label_modelOpenAI do Azure, python_grader, score_model, string_check e text_similarity não suportam o formato de entrada messages.

Erros comuns

Erro Cause Solução
O avaliador foi ignorado Usar evaluation_level="conversation" com um avaliador que não suporta avaliação ao nível da conversa Usa um avaliador ao nível da conversa, ou muda para evaluation_level="turn" se precisares desse avaliador

Preparar dados de conversa

Crie um ficheiro JSONL onde cada linha contenha uma conversa completa no messages campo. Cada mensagem deve incluir um role (utilizador, assistente ou sistema) e content. Para um exemplo completo, consulte os exemplos de avaliação de conversas 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?"}]}

Também pode incluir definições e chamadas de ferramentas se o seu 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."}]}

Defina o esquema de dados e os avaliadores

Especifique o esquema para os dados da sua conversa e selecione avaliadores concebidos para avaliação ao nível da conversa. Mapear messages a cada avaliador. Para avaliadores que avaliam o comportamento da ferramenta, também mapeie tool_definitions. Os avaliadores ao nível da conversa avaliam a interação como um todo, em vez de avaliarem turnos individuais.

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

Descarrega sample_data_multiturn_conversations.jsonl antes de executares a amostra.

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 verificar periodicamente a conclusão e interpretar os resultados, consulte Obter os resultados da avaliação na nuvem.

Para um exemplo completo que pode ser executado, consulte sample_multiturn_conversation_evaluation.py no GitHub.

Passos seguintes

  • Última atualização a