Pode usar o módulo de avaliação da IA gen do SDK da Vertex AI para Python para avaliar programaticamente os seus modelos de linguagem generativa e aplicações com a API do serviço de avaliação da IA gen. Esta página mostra como executar avaliações com o SDK do Vertex AI. Tenha em atenção que as avaliações em grande escala só estão disponíveis através da API REST.
Antes de começar
Instale o SDK da Vertex AI
Para instalar o módulo de avaliação de IA gen do SDK do Vertex AI para Python, execute o seguinte comando:
!pip install -q google-cloud-aiplatform[evaluation]
Para mais informações, consulte o artigo Instale o SDK Vertex AI para Python.
Autentique o SDK Vertex AI
Depois de instalar o SDK da Vertex AI para Python, tem de se autenticar. Os seguintes tópicos explicam como fazer a autenticação com o SDK da Vertex AI se estiver a trabalhar localmente e se estiver a trabalhar no Colaboratory:
Se estiver a desenvolver localmente, configure as credenciais predefinidas da aplicação (ADC) no seu ambiente local:
Instale a CLI do Google Cloud e, em seguida, inicialize-a executando o seguinte comando:
gcloud initCrie credenciais de autenticação local para a sua Conta Google:
gcloud auth application-default loginÉ apresentado um ecrã de início de sessão. Depois de iniciar sessão, as suas credenciais são armazenadas no ficheiro de credenciais local usado pelo ADC. Para mais informações, consulte o artigo Configure o ADC para um ambiente de desenvolvimento local.
Se estiver a trabalhar no Colaboratory, execute o seguinte comando numa célula do Colab para fazer a autenticação:
from google.colab import auth auth.authenticate_user()Este comando abre uma janela onde pode concluir a autenticação.
Compreender as contas de serviço
A conta de serviço é usada pelo serviço de avaliação de IA gen para obter previsões da API Gemini no Vertex AI para métricas de avaliação baseadas em modelos. Esta conta de serviço é aprovisionada automaticamente no primeiro pedido ao serviço de avaliação de IA gen.
| Nome | Descrição | Endereço de email | Função |
|---|---|---|---|
| Agente do serviço de avaliação rápida da Vertex AI | A conta de serviço usada para obter previsões para a avaliação baseada em modelos. | service-PROJECT_NUMBER@gcp-sa-vertex-eval.iam.gserviceaccount.com |
roles/aiplatform.rapidevalServiceAgent |
As autorizações associadas ao agente do serviço de avaliação rápida são:
| Função | Autorizações |
|---|---|
| Agente do serviço de avaliação rápida da Vertex AI (roles/aiplatform.rapidevalServiceAgent) | aiplatform.endpoints.predict |
Execute a sua avaliação
Use a classe EvalTask para executar avaliações para os seguintes exemplos de utilização:
Execute avaliações à escala (pré-visualização)
EvalTask turma
A classe EvalTask ajuda a avaliar modelos e aplicações com base em tarefas específicas. Para fazer comparações justas entre modelos generativos, normalmente, tem de avaliar repetidamente vários modelos e modelos de comandos em relação a um conjunto de dados de avaliação fixo usando métricas específicas. Também é importante avaliar várias métricas em simultâneo numa única execução de avaliação.
EvalTask também se integra com as experiências da Vertex AI para ajudar a monitorizar as configurações e os resultados de cada execução de avaliação. A Vertex AI Experiments ajuda a gerir e interpretar os resultados da avaliação, o que lhe permite tomar decisões informadas.
O exemplo seguinte demonstra como instanciar a classe EvalTask e executar uma avaliação:
from vertexai.evaluation import (
EvalTask,
PairwiseMetric,
PairwiseMetricPromptTemplate,
PointwiseMetric,
PointwiseMetricPromptTemplate,
MetricPromptTemplateExamples，
)
eval_task = EvalTask(
dataset=DATASET,
metrics=[METRIC_1, METRIC_2, METRIC_3],
experiment=EXPERIMENT_NAME,
)
eval_result = eval_task.evaluate(
model=MODEL,
prompt_template=PROMPT_TEMPLATE,
experiment_run=EXPERIMENT_RUN,
)
Execute a avaliação com métricas baseadas em modelos
Para métricas baseadas em modelos, use as classes PointwiseMetric e PairwiseMetric para definir métricas adaptadas aos seus critérios específicos. Execute avaliações através das seguintes opções:
Use exemplos de métricas baseadas em modelos
Pode usar diretamente a constante incorporada Metric Prompt Template Examples no SDK Vertex AI. Em alternativa, modifique-as e incorpore-as na interface de definição de métricas de forma livre.
Para ver a lista completa de exemplos de modelos de comandos de métricas que abrangem a maioria dos exemplos de utilização principais, consulte Modelos de comandos de métricas.
Consola
Quando executa avaliações num bloco de notas do Colab Enterprise, pode aceder aos modelos de comandos de métricas diretamente na Google Cloud consola.
Clique no link do seu notebook de serviço de avaliação de IA gen preferido.
O bloco de notas é aberto no GitHub. Clique em Abrir no Colab Enterprise. Se uma caixa de diálogo lhe pedir para ativar APIs, clique em Ativar.
Clique no ícone Avaliação de IA gen. na barra lateral. É aberto um painel Modelos de métricas pré-criados.
Selecione métricas Pointwise ou Pairwise.
Clique na métrica que quer usar, como Fluidez. É apresentado o exemplo de código para a métrica.
Clique em Copiar para copiar o exemplo de código. Opcionalmente, clique em Personalizar para alterar os campos predefinidos da métrica.
Cole o exemplo de código no seu notebook.
SDK Vertex AI
O exemplo do SDK do Vertex AI seguinte mostra como usar a classe MetricPromptTemplateExamples para definir as suas métricas:
# View all the available examples of model-based metrics
MetricPromptTemplateExamples.list_example_metric_names()
# Display the metric prompt template of a specific example metric
print(MetricPromptTemplateExamples.get_prompt_template('fluency'))
# Use the pre-defined model-based metrics directly
eval_task = EvalTask(
dataset=EVAL_DATASET,
metrics=[MetricPromptTemplateExamples.Pointwise.FLUENCY],
)
eval_result = eval_task.evaluate(
model=MODEL,
)
Use uma interface baseada em modelos com métricas
Personalize as suas métricas preenchendo campos como Criteria e Rating Rubrics com as classes PointwiseMetricPromptTemplate e PairwiseMetricPromptTemplate no SDK do Vertex AI. A determinados campos, como Instruction, é atribuído um valor predefinido se não fornecer uma entrada.
Opcionalmente, pode especificar input_variables, que é uma lista de campos de entrada usados pelo modelo de comando de métricas para gerar resultados de avaliação baseados em modelos. Por predefinição, a coluna response do modelo é incluída para métricas ao nível do ponto, e as colunas response e baseline_model_response do modelo candidato são incluídas para métricas aos pares.
Para mais informações, consulte a secção "Estruture um modelo de comando de métricas" em Modelos de comandos de métricas.
# Define a pointwise metric with two custom criteria
custom_text_quality = PointwiseMetric(
metric="custom_text_quality",
metric_prompt_template=PointwiseMetricPromptTemplate(
criteria={
"fluency": "Sentences flow smoothly and are easy to read, avoiding awkward phrasing or run-on sentences. Ideas and sentences connect logically, using transitions effectively where needed.",
"entertaining": "Short, amusing text that incorporates emojis, exclamations and questions to convey quick and spontaneous communication and diversion.",
},
rating_rubric={
"1": "The response performs well on both criteria.",
"0": "The response is somewhat aligned with both criteria",
"-1": "The response falls short on both criteria",
},
input_variables=["prompt"],
),
)
# Display the serialized metric prompt template
print(custom_text_quality.metric_prompt_template)
# Run evaluation using the custom_text_quality metric
eval_task = EvalTask(
dataset=EVAL_DATASET,
metrics=[custom_text_quality],
)
eval_result = eval_task.evaluate(
model=MODEL,
)
Use a interface do SDK de forma livre de métricas baseadas em modelos
Para ter mais flexibilidade na personalização do modelo de comando de métricas, pode definir uma métrica diretamente através da interface de forma livre, que aceita uma entrada de string direta.
# Define a pointwise multi-turn chat quality metric
pointwise_chat_quality_metric_prompt = """Evaluate the AI's contribution to a meaningful conversation, considering coherence, fluency, groundedness, and conciseness.
Review the chat history for context. Rate the response on a 1-5 scale, with explanations for each criterion and its overall impact.
# Conversation History
{history}
# Current User Prompt
{prompt}
# AI-generated Response
{response}
"""
freeform_multi_turn_chat_quality_metric = PointwiseMetric(
metric="multi_turn_chat_quality_metric",
metric_prompt_template=pointwise_chat_quality_metric_prompt,
)
# Run evaluation using the freeform_multi_turn_chat_quality_metric metric
eval_task = EvalTask(
dataset=EVAL_DATASET,
metrics=[freeform_multi_turn_chat_quality_metric],
)
eval_result = eval_task.evaluate(
model=MODEL,
)
Avalie um modelo de tradução
Para avaliar o seu modelo de tradução, pode especificar BLEU, MetricX ou COMET como métricas de avaliação quando usar o SDK do Vertex AI.
#Prepare the dataset for evaluation.
sources = [
"Dem Feuer konnte Einhalt geboten werden",
"Schulen und Kindergärten wurden eröffnet.",
]
responses = [
"The fire could be stopped",
"Schools and kindergartens were open",
]
references = [
"They were able to control the fire.",
"Schools and kindergartens opened",
]
eval_dataset = pd.DataFrame({
"source": sources,
"response": responses,
"reference": references,
})
# Set the metrics.
metrics = [
"bleu",
pointwise_metric.Comet(),
pointwise_metric.MetricX(),
]
eval_task = evaluation.EvalTask(
dataset=eval_dataset,
metrics=metrics,
)
eval_result = eval_task.evaluate()
Execute a avaliação com métricas baseadas em cálculos
Pode usar métricas baseadas em cálculos de forma autónoma ou em conjunto com métricas baseadas em modelos.
# Combine computation-based metrics "ROUGE" and "BLEU" with model-based metrics
eval_task = EvalTask(
dataset=EVAL_DATASET,
metrics=["rouge_l_sum", "bleu", custom_text_quality],
)
eval_result = eval_task.evaluate(
model=MODEL,
)
Execute avaliações em grande escala
Se tiver grandes conjuntos de dados de avaliação ou executar avaliações periodicamente num ambiente de produção, pode usar a EvaluateDataset API no serviço de avaliação de IA gen para executar avaliações em grande escala.
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
- PROJECT_NUMBER: o seu número do projeto.
- DATASET_URI: o caminho do Cloud Storage para um ficheiro JSONL
que contém instâncias de avaliação. Cada linha no ficheiro deve representar uma única instância, com
chaves correspondentes a campos de entrada definidos pelo utilizador no
metric_prompt_template(para métricas baseadas em modelos) ou parâmetros de entrada obrigatórios (para métricas baseadas em cálculos). Só pode especificar um ficheiro JSONL. O exemplo seguinte é uma linha para uma instância de avaliação ponto a ponto:{"response": "The Roman Senate was filled with exuberance due to Pompey's defeat in Asia."} - METRIC_SPEC: Uma ou mais
especificações de métricas que está a usar para
avaliação. Pode usar as seguintes especificações de métricas quando executar avaliações em grande escala:
"pointwise_metric_spec","pairwise_metric_spec","exact_match_spec","bleu_spec"e"rouge_spec". - METRIC_SPEC_FIELD_NAME: os campos obrigatórios para a especificação da métrica escolhida. Por exemplo,
"metric_prompt_template" - METRIC_SPEC_FIELD_CONTENT: o conteúdo do campo para a especificação da métrica escolhida. Por exemplo, pode usar o seguinte conteúdo do campo para uma avaliação ponto a ponto:
"Evaluate the fluency of this sentence: {response}. Give score from 0 to 1. 0 - not fluent at all. 1 - very fluent." - OUTPUT_BUCKET: o nome do contentor do Cloud Storage onde quer armazenar os resultados da avaliação.
Método HTTP e URL:
POST https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/evaluateDataset
Corpo JSON do pedido:
{
"dataset": {
"gcs_source": {
"uris": "DATASET_URI"
}
},
"metrics": [
{
METRIC_SPEC: {
METRIC_SPEC_FIELD_NAME: METRIC_SPEC_FIELD_CONTENT
}
}
],
"output_config": {
"gcs_destination": {
"output_uri_prefix": "OUTPUT_BUCKET"
}
}
}
Para enviar o seu pedido, escolha uma destas opções:
curl
Guarde o corpo do pedido num ficheiro com o nome request.json,
e execute o seguinte comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/evaluateDataset"
PowerShell
Guarde o corpo do pedido num ficheiro com o nome request.json,
e execute o seguinte comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/evaluateDataset" | Select-Object -Expand Content
Deve receber uma resposta JSON semelhante à seguinte.
Pode usar o OPERATION_ID que recebe na resposta para pedir o estado da avaliação:
curl -X GET \ -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/operations/OPERATION_ID"
Personalização de métricas adicionais
Se precisar de personalizar ainda mais as suas métricas, como escolher um modelo de juiz diferente para métricas baseadas em modelos ou definir uma nova métrica baseada em cálculos, pode usar a classe CustomMetric no SDK Vertex AI. Para mais detalhes, consulte os seguintes blocos de notas:
Execute a avaliação baseada em modelos com limites de taxa e quota aumentados
Um único pedido de avaliação para uma métrica baseada em modelos resulta em vários pedidos subjacentes à API Gemini no Vertex AI e consome quota para o modelo de juiz. Deve definir um limite de taxa de serviço de avaliação mais elevado nos seguintes exemplos de utilização:
Aumento do volume de dados: se estiver a processar significativamente mais dados com as métricas baseadas em modelos, pode atingir a quota predefinida de pedidos por minuto (RPM). O aumento da quota permite-lhe processar o volume maior sem degradação do desempenho nem interrupções.
Avaliação mais rápida: se a sua aplicação precisar de um tempo de processamento mais rápido para as avaliações, pode precisar de uma quota de RPM mais elevada. Isto é especialmente importante para aplicações sensíveis ao tempo ou com interações em tempo real, em que os atrasos na avaliação podem afetar a experiência do utilizador.
Tarefas de avaliação complexas: uma quota de RPM mais elevada garante que tem capacidade suficiente para processar avaliações que exigem muitos recursos para tarefas complexas ou grandes quantidades de texto.
Concorrência elevada de utilizadores: se prevê um grande número de utilizadores a pedirem simultaneamente avaliações baseadas em modelos e inferência de modelos no seu projeto, um limite de RPM do modelo mais elevado é crucial para evitar gargalos e manter a capacidade de resposta.
Se estiver a usar o modelo de juiz predefinido da versão gemini-2.0-flash ou modelos mais recentes, recomendamos que use o débito processado para gerir a sua quota.
Para modelos anteriores a gemini-2.0-flash, siga estas instruções para aumentar a quota de RPM do modelo de avaliação:
Na Google Cloud consola, aceda à página IAM e administração Quotas.
No campo Filtro, especifique a Dimensão (identificador do modelo) e a Métrica (identificador da quota para modelos Gemini):
base_model:gemini-2.0-flasheMetric:aiplatform.googleapis.com/generate_content_requests_per_minute_per_project_per_base_model.Para a quota que quer aumentar, clique no botão mais ações do menu .
No menu pendente, clique em Editar quota. É aberto o painel Alterações de quota.
Em Editar quota, introduza um novo valor de quota.
Clique em Enviar pedido.
Um pedido de aumento de quota (QIR) é confirmado por email e, normalmente, demora dois dias úteis a ser processado.
Para executar uma avaliação com uma nova quota, defina o parâmetro evaluation_service_qps da seguinte forma:
from vertexai.evaluation import EvalTask
# GEMINI_RPM is the requests per minute (RPM) quota for gemini-2.0-flash-001 in your region
# Evaluation Service QPS limit is equal to (gemini-2.0-flash-001 RPM / 60 sec / default number of samples)
CUSTOM_EVAL_SERVICE_QPS_LIMIT = GEMINI_RPM / 60 / 4
eval_task = EvalTask(
dataset=DATASET,
metrics=[METRIC_1, METRIC_2, METRIC_3],
)
eval_result = eval_task.evaluate(
evaluation_service_qps=CUSTOM_EVAL_SERVICE_QPS_LIMIT,
# Specify a retry_timeout limit for a more responsive evaluation run
# the default value is 600 (in seconds, or 10 minutes)
retry_timeout=RETRY_TIMEOUT,
)
Para mais informações sobre quotas e limites, consulte o artigo Quotas do serviço de avaliação de IA gen e a API do serviço de avaliação de IA gen.
O que se segue?
Encontre um modelo de métricas baseado em modelos.
Experimente um bloco de notas de exemplo de avaliação.