Avaliar alvos de modelos e agentes com o Microsoft Foundry SDK

Envie consultas de teste para modelos implementados, agentes de instruções ou agentes alojados e avalie as respostas geradas durante a execução.

Pré-requisitos

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

Avaliar um modelo alvo

Enviar consultas para um modelo implementado em tempo de execução. Avalie as respostas usando o azure_ai_target_completions tipo de fonte de dados com um azure_ai_model alvo. Os seus dados de entrada contêm consultas. O modelo gera respostas, que depois avalias.

Importante

Antes de começar, complete a configuração do cliente e prepare os dados de entrada.

Note

Podes usar o modelo de router como modelo-alvo. O router modelo é suportado apenas como alvo de avaliação. Não pode ser selecionado como modelo para qualquer outra funcionalidade de avaliação.

Defina o modelo de mensagem e o destino

O input_messages modelo controla como as consultas são enviadas para o modelo. Usa {{item.query}} para referenciar campos a partir dos teus dados de entrada. Especifique o modelo a avaliar e parâmetros de amostragem opcionais:

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_model",
    "model": "gpt-5-mini",
    "sampling_params": {
        "top_p": 1.0,
        "max_completion_tokens": 2048,
    },
}

Configurar avaliadores e mapeamentos de dados

Quando o modelo gera respostas em tempo de execução, use {{sample.output_text}} in data_mapping para referenciar a saída do modelo. Usa {{item.field}} para referenciar campos a partir dos teus dados de entrada.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="coherence",
        evaluator_name="builtin.coherence",
        initialization_parameters={"model": model_deployment_name},
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    ),
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="violence",
        evaluator_name="builtin.violence",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    ),
]

Criar avaliação e executar

eval_object = openai_client.evals.create(
    name="Model Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="model-target-evaluation",
    data_source=data_source,
)

Para um exemplo completo executável, veja sample_model_evaluation.py em GitHub. Para verificar periodicamente a conclusão e interpretar os resultados, consulte Obter resultados da avaliação na nuvem.

Tip

Para adicionar outra execução de avaliação, use o mesmo código.

Avalie um agente alvo

Envie consultas a um agente Foundry em tempo de execução e avalie as respostas usando o azure_ai_target_completions tipo de fonte de dados com um azure_ai_agent alvo. Este cenário funciona tanto para agentes rápidos como agentes alojados.

Importante

Antes de começar, complete a configuração do cliente e prepare os dados de entrada.

Tip

Os agentes alojados que utilizam o protocolo de respostas trabalham com os mesmos exemplos de código apresentados aqui. Para agentes hospedados que utilizam o protocolo de invocações, o input_messages formato é diferente. Consulte o protocolo de invocações de agentes hospedados para mais detalhes.

Defina o modelo de mensagem e o destino

O input_messages modelo controla como as consultas são enviadas ao agente. Usa {{item.query}} para referenciar campos a partir dos teus dados de entrada. Especifique o agente a avaliar pelo nome:

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "developer",
            "content": {
                "type": "input_text",
                "text": "You are a helpful assistant. Answer clearly and safely."
            }
        },
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_agent",
    "name": "my-agent",
    "version": "1"  # Optional. Uses latest version if omitted.
}

Configurar avaliadores e mapeamentos de dados

Quando o agente gera respostas em tempo de execução, use {{sample.*}} variáveis em data_mapping para referenciar a saída do agente:

Variável Description Uso para
{{sample.output_text}} A resposta do agente em texto simples. Avaliadores que esperam uma resposta em cadeia (por exemplo, coherence, violence).
{{sample.output_items}} A saída JSON estruturada do agente, incluindo chamadas de ferramenta. Avaliadores que necessitam de contexto completo de interação (por exemplo, task_adherence).
{{item.field}} Um campo dos seus dados de entrada. Campos de entrada como query ou ground_truth.

Tip

O query campo pode conter JSON estruturado, incluindo mensagens do sistema e histórico de conversas. Alguns avaliadores de agentes, como task_adherence, usam este contexto para atribuir uma pontuação mais precisa. Para detalhes sobre formatação de consultas, consulte avaliadores de agentes.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="coherence",
        evaluator_name="builtin.coherence",
        initialization_parameters={"model": model_deployment_name},
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    ),
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="violence",
        evaluator_name="builtin.violence",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    ),
]

Criar avaliação e executar

eval_object = openai_client.evals.create(
    name="Agent Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

agent_eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-target-evaluation",
    data_source=data_source,
)

Para um exemplo completo executável, veja sample_agent_evaluation.py em GitHub. Para verificar periodicamente a conclusão e interpretar os resultados, consulte Obter resultados da avaliação na nuvem.

Protocolo de invocações de agentes hospedados

Agentes alojados que utilizam o protocolo de invocações suportam o mesmo azure_ai_agent tipo de alvo, mas utilizam um formato livre input_messages . Em vez do formato estruturado do modelo, forneça um objeto JSON que se mapeie diretamente para o corpo do pedido do /invocations agente. Use {{item.*}} marcadores de posição para substituir campos dos seus dados de entrada.

Se um agente hospedado suportar tanto os protocolos de resposta como de invocação, o serviço passa a usar por defeito o protocolo de invocações.

Defina o formato e o destino da mensagem

input_messages = {"message": "{{item.query}}"}

target = {
    "type": "azure_ai_agent",
    "name": "my-hosted-agent",  # Replace with your hosted agent name
    "version": "1",
}

Criar avaliação e executar

eval_object = openai_client.evals.create(
    name="Hosted Agent Invocations Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="hosted-agent-invocations-evaluation",
    data_source=data_source,
)

A configuração do avaliador e os mapeamentos de dados são os mesmos que para a avaliação rápida do agente. Use {{sample.output_text}} para a resposta de texto do agente e {{sample.output_items}} para a saída estruturada completa, incluindo chamadas de ferramenta.

Conteúdo relacionado

  • Last updated on