Partilhar via

Avalie seu aplicativo de IA generativa localmente com o SDK de Avaliação de IA do Azure

Importante

Os itens marcados como (pré-visualização) neste artigo estão neste momento em pré-visualização pública. Esta pré-visualização é fornecida sem um contrato de nível de serviço e não recomendamos o seu uso em ambientes de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, consulte Termos de uso suplementares para visualizações do Microsoft Azure.

Se você quiser avaliar completamente o desempenho de seu aplicativo de IA generativa ao aplicá-lo a um conjunto de dados substancial, poderá avaliá-lo em seu ambiente de desenvolvimento com o SDK de Avaliação de IA do Azure. Quando você fornece um conjunto de dados de teste ou um alvo, suas saídas de aplicativos generativos de IA são medidas quantitativamente com métricas baseadas em matemática e avaliadores de qualidade e segurança assistidos por IA. Avaliadores integrados ou personalizados podem fornecer informações abrangentes sobre os recursos e limitações do aplicativo.

Neste artigo, você aprenderá a executar avaliadores em uma única linha de dados e um conjunto de dados de teste maior em um destino de aplicativo. Você usa avaliadores internos que usam o SDK de Avaliação da IA do Azure localmente. Em seguida, você aprende a controlar os resultados e os logs de avaliação em um projeto de IA do Azure.

Introdução

Primeiro, instale o pacote de avaliadores a partir do SDK de Avaliação do Azure AI:

pip install azure-ai-evaluation

Observação

Para obter informações mais detalhadas, consulte a documentação de referência da API para o SDK de Avaliação de IA do Azure.

Avaliadores integrados

Categoria Avaliadores
Fins gerais CoherenceEvaluator, FluencyEvaluator, QAEvaluator
Semelhança textual SimilarityEvaluator, F1ScoreEvaluator, BleuScoreEvaluator, GleuScoreEvaluator, RougeScoreEvaluator, MeteorScoreEvaluator
Geração aumentada de recuperação (RAG) RetrievalEvaluator, DocumentRetrievalEvaluator, GroundednessEvaluator, GroundednessProEvaluator, RelevanceEvaluator, ResponseCompletenessEvaluator
Risco e segurança ViolenceEvaluator, SexualEvaluator, SelfHarmEvaluator, HateUnfairnessEvaluator, IndirectAttackEvaluator, ProtectedMaterialEvaluator, UngroundedAttributesEvaluator, CodeVulnerabilityEvaluator, ContentSafetyEvaluator
Agente IntentResolutionEvaluator, ToolCallAccuracyEvaluator, TaskAdherenceEvaluator
Azure OpenAI AzureOpenAILabelGrader, AzureOpenAIStringCheckGrader, AzureOpenAITextSimilarityGrader, AzureOpenAIGrader

As métricas de qualidade e segurança incorporadas incluem pares de consulta e resposta, juntamente com informações adicionais para avaliadores específicos.

Requisitos de dados para avaliadores integrados

Os avaliadores integrados podem aceitar pares de consulta e resposta, uma lista de conversas no formato JSON Lines (JSONL) ou ambos.

Conversação e suporte de turno único para texto Conversação e suporte para interações de uma só vez, tanto para texto como para imagem Suporte de turno único apenas para texto
GroundednessEvaluator, GroundednessProEvaluator, RetrievalEvaluator, DocumentRetrievalEvaluator, RelevanceEvaluator, CoherenceEvaluator, FluencyEvaluator, ResponseCompletenessEvaluator, IndirectAttackEvaluator, AzureOpenAILabelGrader, AzureOpenAIStringCheckGrader, AzureOpenAITextSimilarityGrader, AzureOpenAIGrader ViolenceEvaluator, SexualEvaluator, SelfHarmEvaluator, HateUnfairnessEvaluator, ProtectedMaterialEvaluator, ContentSafetyEvaluator UngroundedAttributesEvaluator, CodeVulnerabilityEvaluator, ResponseCompletenessEvaluator, SimilarityEvaluator, F1ScoreEvaluator, RougeScoreEvaluator, GleuScoreEvaluator, BleuScoreEvaluator, MeteorScoreEvaluator, QAEvaluator

Os avaliadores de qualidade assistidos por IA vêm com um campo de razão (exceto para SimilarityEvaluator). Eles empregam técnicas que incluem raciocínio em cadeia de pensamento para gerar uma explicação para a pontuação. Portanto, eles consomem mais uso de tokens durante a geração devido à melhoria da qualidade da avaliação. Especificamente, max_token para a geração do avaliador está definido como 800 para todos os avaliadores assistidos por IA (e 1.600 para RetrievalEvaluator, de forma a acomodar entradas mais longas).

Os avaliadores do Azure OpenAI exigem um modelo que descreva como suas colunas de entrada são transformadas na entrada real que o classificador usa. Exemplo: Se você tiver duas entradas chamadas consulta e resposta e um modelo formatado como {{item.query}}, somente a consulta será usada. Da mesma forma, você pode ter algo como {{item.conversation}} aceitar uma entrada de conversa, mas a capacidade do sistema de lidar com isso depende de como você configura o resto da grade para esperar essa entrada.

Para obter mais informações sobre os requisitos de dados para avaliadores de agente, vá para Executar avaliações de agente localmente com o SDK de Avaliação de IA do Azure.

Suporte de turno único para texto

Todos os avaliadores integrados recebem entradas de turno único como pares de consulta e resposta em cadeias de caracteres. Por exemplo:

from azure.ai.evaluation import RelevanceEvaluator

query = "What is the cpital of life?"
response = "Paris."

# Initialize an evaluator:
relevance_eval = RelevanceEvaluator(model_config)
relevance_eval(query=query, response=response)

Para executar avaliações em lote usando a avaliação local ou carregar seu conjunto de dados para executar uma avaliação na nuvem, você precisa representar o conjunto de dados no formato JSONL. Os dados de turno único anteriores (um par de consulta e resposta) são equivalentes a uma linha de um conjunto de dados como a seguinte (mostramos três linhas como exemplo):

{"query":"What is the capital of France?","response":"Paris."}
{"query":"What atoms compose water?","response":"Hydrogen and oxygen."}
{"query":"What color is my shirt?","response":"Blue."}

O conjunto de dados do teste de avaliação pode conter o seguinte, dependendo dos requisitos de cada avaliador incorporado:

  • Consulta: A consulta enviada para o aplicativo de IA generativa.
  • Resposta: A resposta à consulta gerada pelo aplicativo de IA generativa.
  • Contexto: A fonte na qual a resposta gerada se baseia (ou seja, os documentos de fundamentação).
  • Verdade fundamental: A resposta gerada por um usuário ou humano como a resposta verdadeira.

Para ver o que cada avaliador exige, pode aprender mais nos documentos incorporados dos avaliadores.

Suporte de conversação para texto

Para avaliadores que suportam conversas para texto, você pode fornecer conversation como entrada, que inclui um dicionário Python com uma lista de messages (que incluem content, rolee opcionalmente context).

Veja a seguinte conversa de dois turnos em Python:

conversation = {
        "messages": [
        {
            "content": "Which tent is the most waterproof?", 
            "role": "user"
        },
        {
            "content": "The Alpine Explorer Tent is the most waterproof",
            "role": "assistant", 
            "context": "From the our product list the alpine explorer tent is the most waterproof. The Adventure Dining Table has higher weight."
        },
        {
            "content": "How much does it cost?",
            "role": "user"
        },
        {
            "content": "The Alpine Explorer Tent is $120.",
            "role": "assistant",
            "context": None
        }
        ]
}

Para executar avaliações em lote usando a avaliação local ou carregar seu conjunto de dados para executar a avaliação na nuvem, você precisa representar o conjunto de dados no formato JSONL. A conversação anterior é equivalente a uma linha de conjunto de dados em um arquivo JSONL como o exemplo a seguir:

{"conversation":
    {
        "messages": [
        {
            "content": "Which tent is the most waterproof?", 
            "role": "user"
        },
        {
            "content": "The Alpine Explorer Tent is the most waterproof",
            "role": "assistant", 
            "context": "From the our product list the alpine explorer tent is the most waterproof. The Adventure Dining Table has higher weight."
        },
        {
            "content": "How much does it cost?",
            "role": "user"
        },
        {
            "content": "The Alpine Explorer Tent is $120.",
            "role": "assistant",
            "context": null
        }
        ]
    }
}

Nossos avaliadores entendem que o primeiro turno da conversa fornece válido query de user, context de assistant, e response de assistant no formato consulta-resposta. As conversas são então avaliadas por turno e os resultados são agregados em todos os turnos para uma pontuação de conversa.

Observação

Na segunda passagem, mesmo que context seja null ou uma chave ausente, ele é interpretado como uma cadeia de caracteres vazia em vez de resultar em erro, o que pode levar a resultados enganosos. Recomendamos vivamente que valide os seus dados de avaliação para cumprir os requisitos de dados.

Para o modo de conversação, aqui está um exemplo de GroundednessEvaluator:

# Conversation mode:
import json
import os
from azure.ai.evaluation import GroundednessEvaluator, AzureOpenAIModelConfiguration

model_config = AzureOpenAIModelConfiguration(
    azure_endpoint=os.environ.get("AZURE_ENDPOINT"),
    api_key=os.environ.get("AZURE_API_KEY"),
    azure_deployment=os.environ.get("AZURE_DEPLOYMENT_NAME"),
    api_version=os.environ.get("AZURE_API_VERSION"),
)

# Initialize the Groundedness and Groundedness Pro evaluators:
groundedness_eval = GroundednessEvaluator(model_config)

conversation = {
    "messages": [
        { "content": "Which tent is the most waterproof?", "role": "user" },
        { "content": "The Alpine Explorer Tent is the most waterproof", "role": "assistant", "context": "From the our product list the alpine explorer tent is the most waterproof. The Adventure Dining Table has higher weight." },
        { "content": "How much does it cost?", "role": "user" },
        { "content": "$120.", "role": "assistant", "context": "The Alpine Explorer Tent is $120."}
    ]
}

# Alternatively, you can load the same content from a JSONL file.
groundedness_conv_score = groundedness_eval(conversation=conversation)
print(json.dumps(groundedness_conv_score, indent=4))

Para os outputs de conversação, os resultados por turno são armazenados numa lista e a pontuação geral da conversa 'groundedness': 4.0 é calculada como a média ao longo dos turnos.

{
    "groundedness": 5.0,
    "gpt_groundedness": 5.0,
    "groundedness_threshold": 3.0,
    "evaluation_per_turn": {
        "groundedness": [
            5.0,
            5.0
        ],
        "gpt_groundedness": [
            5.0,
            5.0
        ],
        "groundedness_reason": [
            "The response accurately and completely answers the query by stating that the Alpine Explorer Tent is the most waterproof, which is directly supported by the context. There are no irrelevant details or incorrect information present.",
            "The RESPONSE directly answers the QUERY with the exact information provided in the CONTEXT, making it fully correct and complete."
        ],
        "groundedness_result": [
            "pass",
            "pass"
        ],
        "groundedness_threshold": [
            3,
            3
        ]
    }
}

Observação

Recomendamos que os usuários migrem seu código para usar a chave sem prefixos (por exemplo, groundedness.groundedness) para permitir que seu código ofereça suporte a mais modelos de avaliadores.

Suporte de conversação para imagens e texto e imagem multimodais

Para avaliadores que suportam conversas com imagem e conteúdos multimodais de imagem e texto, pode-se passar URLs de imagem ou imagens codificadas em Base64 no conversation.

Os cenários suportados incluem:

  • Várias imagens com entrada de texto para geração de imagem ou texto.
  • Entrada somente texto para gerações de imagens.
  • Entrada somente de imagem para geração de texto.
from pathlib import Path
from azure.ai.evaluation import ContentSafetyEvaluator
import base64

# Create an instance of an evaluator with image and multi-modal support.
safety_evaluator = ContentSafetyEvaluator(credential=azure_cred, azure_ai_project=project_scope)

# Example of a conversation with an image URL:
conversation_image_url = {
    "messages": [
        {
            "role": "system",
            "content": [
                {"type": "text", "text": "You are an AI assistant that understands images."}
            ],
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Can you describe this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://cdn.britannica.com/68/178268-050-5B4E7FB6/Tom-Cruise-2013.jpg"
                    },
                },
            ],
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "The image shows a man with short brown hair smiling, wearing a dark-colored shirt.",
                }
            ],
        },
    ]
}

# Example of a conversation with base64 encoded images:
base64_image = ""

with Path.open("Image1.jpg", "rb") as image_file:
    base64_image = base64.b64encode(image_file.read()).decode("utf-8")

conversation_base64 = {
    "messages": [
        {"content": "create an image of a branded apple", "role": "user"},
        {
            "content": [{"type": "image_url", "image_url": {"url": f"data:image/jpg;base64,{base64_image}"}}],
            "role": "assistant",
        },
    ]
}

# Run the evaluation on the conversation to output the result.
safety_score = safety_evaluator(conversation=conversation_image_url)

Atualmente, os avaliadores de imagem e de multimodalidade suportam

  • Apenas turno único (uma conversa pode ter apenas uma mensagem de usuário e uma mensagem de assistente).
  • Conversas que têm apenas uma mensagem do sistema.
  • Cargas de conversação menores que 10 MB (incluindo imagens).
  • URLs absolutos e imagens codificadas em Base64.
  • Várias imagens em um único turno.
  • Formatos de ficheiro JPG/JPEG, PNG e GIF.

Configurar

Para avaliadores de qualidade assistidos por IA (exceto para a pré-visualização GroundednessProEvaluator), deve especificar um modelo GPT (gpt-35-turbo, gpt-4, gpt-4-turbo, gpt-4o ou gpt-4o-mini) no seu model_config. O modelo GPT atua como um juiz para pontuar os dados da avaliação. Damos suporte aos esquemas de configuração de modelos Azure OpenAI e OpenAI. Para obter o melhor desempenho e respostas analisáveis com nossos avaliadores de software, recomendamos o uso de modelos GPT que não estão em fase de testes.

Observação

Recomendamos vivamente que substitua gpt-3.5-turbo pelo gpt-4o-mini seu modelo de avaliador, porque este último é mais barato, mais capaz e igualmente rápido, de acordo com a OpenAI.

Certifique-se de que tem pelo menos a função Cognitive Services OpenAI User para o recurso OpenAI do Azure para realizar chamadas de inferência com a chave de API. Para saber mais sobre permissões, consulte Permissões para um recurso do Azure OpenAI.

Para todos os avaliadores de risco e segurança e GroundednessProEvaluator (pré-visualização), você deve fornecer suas informações azure_ai_project em vez de uma implantação GPT no model_config. Isso acessa o serviço de avaliação de back-end por meio de seu projeto de IA do Azure.

Sugestões para avaliadores integrados assistidos por IA

Abrimos os prompts de nossos avaliadores de qualidade em nossa Biblioteca de Avaliadores e no repositório do SDK Python de Avaliação de IA do Azure para transparência, exceto para os Avaliadores de Segurança e GroundednessProEvaluator (alimentado pelo Azure AI Content Safety). Esses prompts servem como instruções para um modelo de linguagem executar sua tarefa de avaliação, o que requer uma definição amigável da métrica e suas rubricas de pontuação associadas. É altamente recomendável que os usuários personalizem as definições e rubricas de classificação de acordo com suas especificidades de cenário. Veja detalhes em Avaliadores personalizados.

Avaliadores compostos

Os avaliadores compostos são avaliadores integrados que combinam métricas individuais de qualidade ou segurança. Eles fornecem facilmente uma ampla gama de métricas prontas para uso tanto para pares de resposta de consulta quanto para mensagens de bate-papo.

Avaliador composto Contém Descrição
QAEvaluator GroundednessEvaluator, RelevanceEvaluator, CoherenceEvaluator, FluencyEvaluator, SimilarityEvaluator, F1ScoreEvaluator Combina todos os avaliadores de qualidade para uma única saída de métricas combinadas para pares de consulta e resposta
ContentSafetyEvaluator ViolenceEvaluator, SexualEvaluator, SelfHarmEvaluator, HateUnfairnessEvaluator Combina todos os avaliadores de segurança para uma única saída de métricas combinadas para pares de consulta e resposta

Avaliação local em conjuntos de dados de teste usando evaluate()

Depois de verificar seus avaliadores internos ou personalizados em uma única linha de dados, você pode combinar vários avaliadores com a evaluate() API em um conjunto de dados de teste inteiro.

Etapas de configuração de pré-requisitos para projetos do Azure AI Foundry

Se esta for a primeira vez que você executa avaliações e registra no seu projeto do Azure AI Foundry, talvez seja necessário executar algumas etapas de configuração adicionais:

  1. Crie e conecte sua conta de armazenamento ao seu projeto do Azure AI Foundry no nível do recurso. Este modelo Bicep provisiona e liga uma conta de armazenamento ao seu projeto Foundry com autenticação através de chave.
  2. Verifique se a conta de armazenamento conectada tem acesso a todos os projetos.
  3. Caso tenhas conectado a tua conta de armazenamento com Microsoft Entra ID, certifica-te de conceder permissões MSI (Identidade da Microsoft) para o Proprietário de Dados de Blob de Armazenamento à tua conta e ao recurso do projeto do Foundry no portal do Azure.

Avaliar em um conjunto de dados e registrar resultados no Azure AI Foundry

Para garantir que a evaluate() API possa analisar corretamente os dados, você deve especificar o mapeamento de coluna para mapear a coluna do conjunto de dados para palavras-chave que os avaliadores aceitam. Nesse caso, especificamos o mapeamento de dados para query, responsee context.

from azure.ai.evaluation import evaluate

result = evaluate(
    data="data.jsonl", # Provide your data here:
    evaluators={
        "groundedness": groundedness_eval,
        "answer_length": answer_length
    },
    # Column mapping:
    evaluator_config={
        "groundedness": {
            "column_mapping": {
                "query": "${data.queries}",
                "context": "${data.context}",
                "response": "${data.response}"
            } 
        }
    },
    # Optionally, provide your Azure AI Foundry project information to track your evaluation results in your project portal.
    azure_ai_project = azure_ai_project,
    # Optionally, provide an output path to dump a JSON file of metric summary, row-level data, and the metric and Azure AI project URL.
    output_path="./myevalresults.json"
)

Sugestão

Obtenha o conteúdo da propriedade para obter um link para exibir os resultados da result.studio_url avaliação registrados em seu projeto de IA do Azure.

Os resultados provenientes do avaliador são armazenados num dicionário, que contém dados e métricas agregados metrics e dados ao nível da linha. Veja o seguinte exemplo de uma saída:

{'metrics': {'answer_length.value': 49.333333333333336,
             'groundedness.gpt_groundeness': 5.0, 'groundedness.groundeness': 5.0},
 'rows': [{'inputs.response': 'Paris is the capital of France.',
           'inputs.context': 'Paris has been the capital of France since '
                                  'the 10th century and is known for its '
                                  'cultural and historical landmarks.',
           'inputs.query': 'What is the capital of France?',
           'outputs.answer_length.value': 31,
           'outputs.groundeness.groundeness': 5,
           'outputs.groundeness.gpt_groundeness': 5,
           'outputs.groundeness.groundeness_reason': 'The response to the query is supported by the context.'},
          {'inputs.response': 'Albert Einstein developed the theory of '
                            'relativity.',
           'inputs.context': 'Albert Einstein developed the theory of '
                                  'relativity, with his special relativity '
                                  'published in 1905 and general relativity in '
                                  '1915.',
           'inputs.query': 'Who developed the theory of relativity?',
           'outputs.answer_length.value': 51,
           'outputs.groundeness.groundeness': 5,
           'outputs.groundeness.gpt_groundeness': 5,
           'outputs.groundeness.groundeness_reason': 'The response to the query is supported by the context.'},
          {'inputs.response': 'The speed of light is approximately 299,792,458 '
                            'meters per second.',
           'inputs.context': 'The exact speed of light in a vacuum is '
                                  '299,792,458 meters per second, a constant '
                                  "used in physics to represent 'c'.",
           'inputs.query': 'What is the speed of light?',
           'outputs.answer_length.value': 66,
           'outputs.groundeness.groundeness': 5,
           'outputs.groundeness.gpt_groundeness': 5,
           'outputs.groundeness.groundeness_reason': 'The response to the query is supported by the context.'}],
 'traces': {}}

Requisitos para evaluate()

A evaluate() API tem alguns requisitos para o formato de dados que aceita e como lida com nomes de chave de parâmetros do avaliador para que os gráficos dos resultados da avaliação em seu projeto de IA do Azure apareçam corretamente.

Formato dos dados

A evaluate() API aceita apenas dados no formato JSONL. Para todos os avaliadores incorporados, evaluate() requer dados no seguinte formato com os campos de entrada obrigatórios. Consulte a secção anterior sobre a introdução de dados necessária para os avaliadores incorporados. O trecho de código a seguir é um exemplo de como uma linha pode parecer:

{
  "query":"What is the capital of France?",
  "context":"France is in Europe",
  "response":"Paris is the capital of France.",
  "ground_truth": "Paris"
}

Formato do parâmetro do avaliador

Quando você passa em seus avaliadores internos, é importante especificar o mapeamento de palavra-chave correto na evaluators lista de parâmetros. A tabela a seguir é o mapeamento de palavras-chave necessário para que os resultados de seus avaliadores internos apareçam na interface do usuário quando conectados ao seu projeto de IA do Azure.

Avaliador Parâmetro da palavra-chave
GroundednessEvaluator "groundedness"
GroundednessProEvaluator "groundedness_pro"
RetrievalEvaluator "retrieval"
RelevanceEvaluator "relevance"
CoherenceEvaluator "coherence"
FluencyEvaluator "fluency"
SimilarityEvaluator "similarity"
F1ScoreEvaluator "f1_score"
RougeScoreEvaluator "rouge"
GleuScoreEvaluator "gleu"
BleuScoreEvaluator "bleu"
MeteorScoreEvaluator "meteor"
ViolenceEvaluator "violence"
SexualEvaluator "sexual"
SelfHarmEvaluator "self_harm"
HateUnfairnessEvaluator "hate_unfairness"
IndirectAttackEvaluator "indirect_attack"
ProtectedMaterialEvaluator "protected_material"
CodeVulnerabilityEvaluator "code_vulnerability"
UngroundedAttributesEvaluator "ungrounded_attributes"
QAEvaluator "qa"
ContentSafetyEvaluator "content_safety"

Aqui está um exemplo de como definir os evaluators parâmetros:

result = evaluate(
    data="data.jsonl",
    evaluators={
        "sexual":sexual_evaluator
        "self_harm":self_harm_evaluator
        "hate_unfairness":hate_unfairness_evaluator
        "violence":violence_evaluator
    }
)

Avaliação local sobre um alvo

Se você tiver uma lista de consultas que deseja executar e, em seguida, avaliar, a evaluate() API também oferece suporte a um target parâmetro. Este parâmetro pode enviar consultas a uma aplicação para recolher respostas e, em seguida, executar os avaliadores na consulta e resposta resultantes.

Um destino pode ser qualquer classe chamável em seu diretório. Neste caso, temos um script askwiki.py Python com uma classe askwiki() chamável que podemos definir como nosso destino. Se tivermos um conjunto de dados de consultas que podemos enviar para o nosso aplicativo simples askwiki , podemos avaliar a fundamentação das saídas. Certifique-se de especificar o mapeamento de coluna adequado para seus dados no "column_mapping". Você pode usar "default" para especificar o mapeamento de colunas para todos os avaliadores.

Aqui está o conteúdo em "data.jsonl":

{"query":"When was United Stated found ?", "response":"1776"}
{"query":"What is the capital of France?", "response":"Paris"}
{"query":"Who is the best tennis player of all time ?", "response":"Roger Federer"}

from askwiki import askwiki

result = evaluate(
    data="data.jsonl",
    target=askwiki,
    evaluators={
        "groundedness": groundedness_eval
    },
    evaluator_config={
        "default": {
            "column_mapping": {
                "query": "${data.queries}"
                "context": "${outputs.context}"
                "response": "${outputs.response}"
            } 
        }
    }
)

Conteúdo relacionado