Avaliar alvos de modelo e agente com o SDK do Microsoft Foundry

Envie consultas de teste para modelos implantados, agentes de prompt ou agentes hospedados e avalie as respostas geradas em tempo de execução.

Pré-requisitos

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

Avaliar um alvo do modelo

Enviar consultas para um modelo implantado em runtime. Avalie as respostas usando a fonte de dados do tipo azure_ai_target_completions com um destino azure_ai_model. Seus dados de entrada contêm consultas. O modelo gera respostas, que você avalia.

Importante

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

Note

Você pode usar o roteador de modelo como o modelo de destino. O roteador de modelos é compatível apenas como destino de avaliação. Ele não pode ser selecionado como um modelo para qualquer outro recurso de avaliação.

Definir o modelo de mensagem e o destino

O input_messages modelo controla como as consultas são enviadas para o modelo. Use {{item.query}} para fazer referência a campos de seus dados de entrada. Especifique o modelo para 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}} em data_mapping para fazer referência à saída do modelo. Use {{item.field}} para fazer referência a campos de seus 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 obter um exemplo executável completo, consulte sample_model_evaluation.py no GitHub. Para sondar a conclusão e interpretar os resultados, consulte Obter resultados de avaliação de nuvem.

Dica

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

Avaliar um alvo de agente

Envie consultas a um agente do Foundry em tempo de execução e avalie as respostas usando o tipo de fonte de dados azure_ai_target_completions com um destino azure_ai_agent. Esse cenário é aplicável tanto para agentes de prompt quanto para agentes hospedados.

Importante

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

Dica

Os agentes hospedados que usam o protocolo de respostas funcionam com os mesmos exemplos de código mostrados aqui. Para agentes hospedados que usam o protocolo de invocações, o input_messages formato é diferente. Consulte o protocolo invocações do agente hospedado para obter detalhes.

Definir o modelo de mensagem e o destino

O input_messages modelo controla como as consultas são enviadas ao agente. Use {{item.query}} para fazer referência a campos de seus dados de entrada. Especifique o agente a ser avaliado 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 variáveis {{sample.*}} em data_mapping para fazer referência à saída do agente:

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

Dica

O query campo pode conter JSON estruturado, incluindo mensagens do sistema e histórico de conversas. Alguns avaliadores de agente, como task_adherence, usam esse contexto para pontuação mais precisa. Para obter detalhes sobre a formatação de consulta, 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 obter um exemplo executável completo, consulte sample_agent_evaluation.py no GitHub. Para sondar a conclusão e interpretar os resultados, consulte Obter resultados de avaliação de nuvem.

Protocolo de invocações de agente hospedado

Os agentes hospedados que usam o protocolo de invocações dão suporte ao mesmo azure_ai_agent tipo de destino, mas usam um formato de forma input_messageslivre. Em vez do formato de modelo estruturado, forneça um objeto JSON que é mapeado diretamente para o corpo da solicitação do /invocations agente. Use marcadores de posição {{item.*}} para substituir campos nos seus dados de entrada.

Se um agente hospedado der suporte aos protocolos de respostas e invocações, o serviço usará o protocolo de invocações como padrão.

Definir 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 utilizados na avaliação do agente de prompt. 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