Anleitung: Bewertung mit dem GenAI-Client im Vertex AI SDK durchführen

Wenn Sie ein Beispiel für die ersten Schritte sehen möchten: Bewertung mit dem Vertex AI SDK über GenAI Client durchführen, führen Sie das Notebook „Erste Schritte: Bewertung mit dem Vertex AI SDK über GenAI Client durchführen“ in einer der folgenden Umgebungen aus:

In Colab öffnen | In Colab Enterprise öffnen | In Vertex AI Workbench öffnen | Auf GitHub ansehen

Auf dieser Seite erfahren Sie, wie Sie Ihre generativen KI-Modelle und -Anwendungen für eine Reihe von Anwendungsfällen mit dem GenAI-Client im Vertex AI SDK bewerten.

Mit dem GenAI-Client im Vertex AI SDK für den Gen AI Evaluation Service können Sie die Leistung von Prompts, Foundation Models und komplexen KI-Agents anhand der relevantesten Kriterien messen. Sie können beliebig viele Kandidaten gleichzeitig bewerten, um Prompts zu optimieren, das beste Modell auszuwählen oder komplexe Agents zu iterieren.

Mit dem GenAI-Client im Vertex AI SDK haben Sie folgende Möglichkeiten:

• Sie können mehrere Modelle oder Konfigurationen in einem einzigen Lauf nebeneinander vergleichen und anhand von Gewinnratenberechnungen Entscheidungen treffen.

• Nutzen Sie die integrierte Unterstützung, um beliebte Drittanbietermodelle ohne komplexe Integrationen zu bewerten und zu vergleichen.

• Große Datasets lassen sich effizienter verarbeiten und umfangreiche Bewertungsaufgaben können mithilfe der asynchronen Batchbewertung ausgelagert werden.

End-to-End-Beispiel

Der GenAI-Client im Vertex AI SDK verwendet einen zweistufigen Workflow: Generieren von Modellantworten und Bewerten der Antworten. Das folgende End-to-End-Beispiel zeigt, wie der GenAI-Client im Vertex AI SDK funktioniert:

1. Installieren Sie das Vertex AI SDK für Python:

   pip install --upgrade google-cloud-aiplatform[evaluation]
   

2. Bewertungs-Dataset vorbereiten:

   import pandas as pd
   from vertexai import Client, types
   
   client = Client(project="your-project-id", location="us-central1")
   
   prompts_df = pd.DataFrame({"prompt": ["How does AI work?"]})
   

3. Führen Sie die Bewertung aus:

   # Evaluating a single model.
   eval_dataset = client.evals.run_inference(
       model="gemini-2.5-flash",
       src=prompts_df,
   )
   eval_result = client.evals.evaluate(
       dataset=eval_dataset,
       metrics=[types.RubricMetric.GENERAL_QUALITY]
   )
   eval_result.show()
   

4. Mehrere Kandidaten vergleichen:

   # Comparing multiple candidates.
   candidate_1 = client.evals.run_inference(
       model="gemini-2.0-flash", src=prompts_df
   )
   candidate_2 = client.evals.run_inference(
       model="gemini-2.5-flash", src=prompts_df
   )
   comparison_result = client.evals.evaluate(
       dataset=[candidate_1, candidate_2],
       metrics=[types.RubricMetric.GENERAL_QUALITY]
   )
   comparison_result.show()
   

Messwert definieren

Definieren Sie Ihre Messwerte entweder als LLM-basierten Messwert oder als berechnungsbasierten Messwert.

LLM-basierte Messwerte

LLM-basierte Messwerte verwenden ein Large Language Model (LLM) als „Richter“, um differenzierte Kriterien wie Stil oder Schreibqualität zu bewerten, die sich nur schwer mit Algorithmen messen lassen.

Verwaltete rubrikbasierte Messwerte verwenden

Der GenAI-Client im Vertex AI SDK bietet eine Vielzahl von sofort einsatzbereiten, modellbasierten Messwerten wie GENERAL_QUALITY, SAFETY und INSTRUCTION_FOLLOWING. Sie können über die RubricMetric-Klasse darauf zugreifen. Verwaltete auf Rubriken basierende Messwertdefinitionen werden bei Bedarf aus einer zentralen Bibliothek geladen, um für Konsistenz zwischen den Versionen von auf Rubriken basierenden Messwerten zu sorgen.

# Assumes 'eval_dataset' is an EvaluationDataset object created via run_inference()

eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.GENERAL_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
    ]
)

Wenn Sie für verschiedene SDK-Versionen einheitliche Ergebnisse erzielen möchten, können Sie einen Messwert an eine bestimmte Version anpinnen. Standardmäßig wird die neueste Version verwendet.

# Pin to a specific version of a pre-built metric
instruction_following_v1 = types.RubricMetric.INSTRUCTION_FOLLOWING(version='v1')

LLM-Messwerte anpassen

Für Anwendungsfälle, die spezielle Kriterien erfordern, können Sie einen eigenen LLM-basierten Messwert definieren, indem Sie die Klasse LLMMetric instanziieren. So haben Sie die vollständige Kontrolle über die Vorlage für den Bewertungs-Prompt, das Bewertungsmodell und andere Parameter.

Mit der Hilfsklasse MetricPromptBuilder wird eine strukturierte Prompt-Vorlage für das Judge-Modell erstellt, indem Sie instruction, criteria und rating_scores separat definieren.

# Define a custom metric to evaluate language simplicity
simplicity_metric = types.LLMMetric(
    name='language_simplicity',
    prompt_template=types.MetricPromptBuilder(
        instruction="Evaluate the story's simplicity for a 5-year-old.",
        criteria={
            "Vocabulary": "Uses simple words.",
            "Sentences": "Uses short sentences.",
        },
        rating_scores={
            "5": "Excellent: Very simple, ideal for a 5-year-old.",
            "4": "Good: Mostly simple, with minor complex parts.",
            "3": "Fair: Mix of simple and complex; may be challenging for a 5-year-old.",
            "2": "Poor: Largely too complex, with difficult words/sentences.",
            "1": "Very Poor: Very complex, unsuitable for a 5-year-old."
        }
    )
)
# Use the custom metric in an evaluation
eval_result = client.evals.evaluate(
    dataset=inference_results,
    metrics=[simplicity_metric]
)

Berechnungsbasierte Messwerte und Messwerte für benutzerdefinierte Funktionen

Berechnungsbasierte Messwerte vergleichen die Ausgabe eines Modells mathematisch mit einer Ground Truth oder einem Referenzwert. Diese Messwerte werden mit Code mithilfe der Basisklasse Metric berechnet und unterstützen vordefinierte berechnungsbasierte Algorithmen wie exact_match, bleu und rouge_1. Wenn Sie einen berechnungsbasierten Messwert verwenden möchten, instanziieren Sie die Klasse Metric mit dem Namen des Messwerts. Für den Messwert ist eine reference-Spalte in Ihrem Dataset für den Vergleich erforderlich.

eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.Metric(name='exact_match'),
        types.Metric(name='bleu'),
        types.Metric(name='rouge_1'),
    ]
)

Messwert für benutzerdefinierte Funktion implementieren

Sie können auch eine benutzerdefinierte Bewertungslogik implementieren, indem Sie eine benutzerdefinierte Python-Funktion an den Parameter custom_function übergeben. Der GenAI-Client im Vertex AI SDK führt diese Funktion für jede Zeile Ihres Datasets aus.

# Define a custom function to check for the presence of a keyword
def contains_keyword(instance: dict) -> dict:
    keyword = "magic"
    response_text = instance.get("response", "")
    score = 1.0 if keyword in response_text.lower() else 0.0
    return {"score": score}

keyword_metric = types.Metric(
    name="keyword_check",
    custom_function=contains_keyword
)


eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[keyword_metric]
)

Bereiten Sie das Bewertungs-Dataset vor.

Der GenAI-Client im Vertex AI SDK erkennt und verarbeitet automatisch mehrere gängige Datenformate. Das bedeutet, dass Sie Ihre Daten oft unverändert verwenden können, ohne manuelle Konvertierungen vornehmen zu müssen – unabhängig davon, ob Sie mit run_inference neue Antworten generieren oder mit evaluate vorhandene Antworten auswerten.

Der GenAI-Client im Vertex AI SDK unterstützt die folgenden Formate:

• Pandas-DataFrame (reduziertes Format)

  Für einfache Auswertungen können Sie ein pandas.DataFrame verwenden. Der GenAI-Client im Vertex AI SDK sucht nach gängigen Spaltennamen wie prompt, response und reference. Dieses Format ist vollständig abwärtskompatibel.

  import pandas as pd
  
  # Simple DataFrame with prompts and ground truth references
  prompts_df = pd.DataFrame({
      "prompt": [
          "What is the capital of France?",
          "Who wrote 'Hamlet'?",
      ],
      "reference": [
          "Paris",
          "William Shakespeare",
      ]
  })
  
  # Generate responses using the DataFrame as a source
  inference_results = client.evals.run_inference(
      model="gemini-2.5-flash",
      src=prompts_df
  )
  inference_results.show()
  

• Gemini-Batchvorhersageformat

  Sie können die Ausgabe eines Vertex AI-Batchvorhersagejobs direkt verwenden. Dabei handelt es sich in der Regel um JSONL-Dateien, die in Cloud Storage gespeichert sind und in denen jede Zeile ein request- und ein response-Objekt enthält. Der GenAI-Client im Vertex AI SDK parst diese Struktur automatisch, um die Integration mit anderen Vertex AI-Diensten zu ermöglichen.

  Beispiel für eine einzelne Zeile in einer jsonl-Datei:

  {"request": {"contents": [{"role": "user", "parts": [{"text": "Why is the sky blue?"}]}]}, "response": {"candidates": [{"content": {"role": "model", "parts": [{"text": "The sky appears blue to the human eye as a result of a phenomenon known as Rayleigh scattering."}]}}]}}
  

  Sie können dann vorab generierte Antworten aus einem Batchjob direkt bewerten:

  # Cloud Storage path to your batch prediction output file
  batch_job_output_uri = "gs://path/to/your/batch_output.jsonl"
  
  # Evaluate the results directly from Cloud Storage
  eval_result = client.evals.evaluate(
      dataset=batch_job_output_uri,
      metrics=[
          types.RubricMetric.COHERENCE,
          types.RubricMetric.FLUENCY,
      ]
  )
  eval_result.show()
  

• OpenAI-Format für Chat Completion

  Für die Bewertung oder den Vergleich mit Drittanbietermodellen unterstützt der GenAI-Client im Vertex AI SDK das OpenAI-Chat-Completion-Format. Sie können ein Dataset bereitstellen, in dem jede Zeile ein JSON-Objekt ist, das wie eine OpenAI API-Anfrage strukturiert ist. Der GenAI-Client im Vertex AI SDK erkennt dieses Format automatisch.

  Beispiel für eine einzelne Zeile in diesem Format:

  {"request": {"messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What's the capital of France?"}], "model": "gpt-4o"}}
  

  Sie können diese Daten verwenden, um Antworten von einem Drittanbietermodell zu generieren und die Antworten zu bewerten:

  # Ensure your third-party API key is set
  # e.g., os.environ['OPENAI_API_KEY'] = 'Your API Key'
  
  openai_request_uri = "gs://path/to/your/openai_requests.jsonl"
  
  # Generate responses using a LiteLLM-supported model string
  openai_responses = client.evals.run_inference(
      model="gpt-4o",
      src=openai_request_uri,
  )
  
  # The resulting dataset can then be evaluated
  eval_result = client.evals.evaluate(
      dataset=openai_responses,
      metrics=[
          types.RubricMetric.GENERAL_QUALITY,
          types.RubricMetric.FLUENCY,
      ]
  )
  
  eval_result.show()
  

Bewertung ausführen

Der GenAI-Client im Vertex AI SDK verwendet den folgenden clientbasierten Prozess zum Ausführen von Bewertungen:

1. run_inference(): Generiert Antworten aus Ihrem Modell für eine bestimmte Gruppe von Prompts.

2. evaluate(): Berechnen Sie Messwerte für die generierten Antworten.

eval_dataset = client.evals.run_inference(
    model="gemini-2.5-flash",
src="gs://vertex-evaluation-llm-dataset-us-central1/genai_eval_sdk/test_prompts.jsonl",
)
eval_dataset.show()


eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.GENERAL_QUALITY,
        types.RubricMetric.QUESTION_ANSWERING_QUALITY,
        types.Metric(name='bleu'),
        types.Metric(name='rouge_1'),
    ]
)
eval_result.show()

Wenn Sie die Leistung mehrerer KI-Modelle oder ‑Systeme in einer einzigen Bewertung analysieren möchten, generieren Sie eine Antwort für jeden Kandidaten und übergeben Sie sie in einer Liste an die Methode evaluate():

inference_result_1 = client.evals.run_inference(
    model="gemini-2.0-flash",
    src=prompts_df,
)
inference_result_2 = client.evals.run_inference(
    model="gemini-2.5-flash",
    src=prompts_df,
)

# Compare the responses against each other
comparison_result = client.evals.evaluate(
    dataset=[inference_result_1, inference_result_2],
    metrics=[
        types.RubricMetric.TEXT_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
    ]
)

comparison_result.show()

Asynchrone und groß angelegte Auswertung

Für große Datasets bietet der GenAI-Client im Vertex AI SDK eine asynchrone, lang andauernde Batchbewertungsmethode. Das ist ideal für Szenarien, in denen Sie keine sofortigen Ergebnisse benötigen und die Berechnung auslagern möchten.

Die batch_evaluate()-Methode gibt ein Vorgangsobjekt zurück, das Sie abfragen können, um den Fortschritt zu verfolgen. Die Parameter sind mit der Methode evaluate() kompatibel.

GCS_DEST_BUCKET = "gs://your-gcs-bucket/batch_eval_results/"

inference_result_saved = client.evals.run_inference(
    model="gemini-2.0-flash",
    src=prompts_df,
    config={'dest': GCS_DEST_BUCKET}
)
print(f"Eval dataset uploaded to: {inference_result_saved.gcs_source}")

batch_eval_job  = client.evals.batch_evaluate(
   dataset = inference_result_saved,
   metrics = [
        types.RubricMetric.TEXT_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
        types.RubricMetric.FLUENCY,
        types.Metric(name='bleu'),
    ],
   dest=GCS_DEST_BUCKET
)

Drittanbietermodelle bewerten

Sie können den GenAI-Client im Vertex AI SDK verwenden, um Modelle von Anbietern wie OpenAI zu bewerten und zu vergleichen. Dazu übergeben Sie den Modellnamenstring an die run_inference-Methode. Der GenAI-Client im Vertex AI SDK verwendet die litellm-Bibliothek, um die Modell-API aufzurufen.

Legen Sie den erforderlichen API-Schlüssel als Umgebungsvariable (OPENAI_API_KEY) fest:

import os

# Set your third-party model API key
os.environ['OPENAI_API_KEY'] = 'YOUR_OPENAI_API_KEY'

# Run inference on an OpenAI model
gpt_response = client.evals.run_inference(
    model='gpt-4o',
    src=prompt_df
)

# You can now evaluate the responses
eval_result = client.evals.evaluate(
    dataset=gpt_response,
    metrics=[types.RubricMetric.GENERAL_QUALITY]
)

eval_result.show()

Visualisierung

Mit dem GenAI-Client im Vertex AI SDK können Sie Ihre Ergebnisse direkt in Ihrer Entwicklungsumgebung visualisieren, z. B. in einem Colab- oder Jupyter-Notebook. Die .show()-Methode, die sowohl für EvaluationDataset- als auch für EvaluationResult-Objekte verfügbar ist, rendert einen interaktiven HTML-Bericht zur Analyse.

Inferenz-Ergebnisse visualisieren

Nachdem Sie mit run_inference() Antworten generiert haben, können Sie .show() für das resultierende EvaluationDataset-Objekt aufrufen, um die Ausgaben des Modells zusammen mit Ihren ursprünglichen Prompts und Referenzen zu prüfen. Das ist nützlich für eine schnelle Qualitätsprüfung, bevor Sie eine vollständige Bewertung durchführen.

# First, run inference to get an EvaluationDataset
gpt_response = client.evals.run_inference(
    model='gpt-4o',
    src=prompt_df
)

# Now, visualize the inference results
gpt_response.show()

In einer Tabelle werden die einzelnen Prompts, die entsprechenden Referenzen (falls angegeben) und die neu generierten Antworten angezeigt.

Bewertungsberichte visualisieren

Wenn Sie .show() für ein EvaluationResult-Objekt aufrufen, wird ein Bericht mit zwei Hauptabschnitten angezeigt:

• Zusammenfassende Messwerte: Eine aggregierte Ansicht aller Messwerte mit dem Durchschnittswert und der Standardabweichung für den gesamten Datensatz.

• Detaillierte Ergebnisse: Eine Aufschlüsselung nach Fall, mit der Sie den Prompt, die Referenz, die Antwort des Kandidaten sowie die spezifische Punktzahl und Erklärung für jeden Messwert prüfen können.

# First, run an evaluation on a single candidate
eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[types.RubricMetric.TEXT_QUALITY]
)

# Visualize the detailed evaluation report
eval_result.show()

Das Format des Berichts wird angepasst, je nachdem, ob Sie einen einzelnen Kandidaten bewerten oder mehrere Kandidaten vergleichen. Bei einer Auswertung mit mehreren Kandidaten enthält der Bericht eine nebeneinanderliegende Ansicht und in der Zusammenfassungstabelle sind Berechnungen der Gewinn-/Unentschiedenrate enthalten.

In allen Berichten können Sie den Abschnitt Roh-JSON ansehen maximieren, um die Daten für strukturierte Prompts oder Antworten zu prüfen.

Nächste Schritte

• Kurzanleitung zur Bewertung

• Bewertungsmesswerte definieren: