이 페이지는 Cloud Translation API를 통해 번역되었습니다.

튜토리얼: Vertex AI SDK의 GenAI 클라이언트를 사용하여 평가 실행

이 페이지에서는 Vertex AI SDK의 GenAI 클라이언트를 사용하여 다양한 사용 사례에서 생성형 AI 모델과 애플리케이션을 평가하는 방법을 보여줍니다.

Vertex AI SDK for Gen AI Evaluation Service의 GenAI 클라이언트를 사용하면 프롬프트, 기반 모델, 복잡한 AI 에이전트의 성능을 가장 관련성 높은 기준에 따라 측정할 수 있습니다. 프롬프트를 미세 조정하거나, 최적의 모델을 선택하거나, 복잡한 에이전트를 반복하기 위해 한 번에 여러 후보를 평가할 수 있습니다.

Vertex AI SDK의 GenAI 클라이언트로 다음 작업을 할 수 있습니다.

승률 계산을 사용하여 결정을 내리면서 단일 실행에서 여러 모델 또는 구성을 나란히 비교합니다.
복잡한 통합 없이 내장 지원을 사용하여 인기 있는 서드 파티 모델을 평가하고 벤치마킹하세요.
비동기 일괄 평가를 사용하여 대규모 데이터 세트를 더 효율적으로 처리하고 대규모 평가 작업을 오프로드하세요.

엔드 투 엔드 예시

Vertex AI SDK의 GenAI 클라이언트는 모델 응답 생성과 응답 평가라는 2단계 워크플로를 사용합니다. 다음 엔드 투 엔드 예시에서는 Vertex AI SDK의 GenAI 클라이언트가 작동하는 방식을 보여줍니다.

Python용 Vertex AI SDK를 설치합니다.

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

평가 데이터 세트를 준비합니다.

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?"]})

평가를 실행합니다.

# 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()

여러 후보 비교:

# 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()

측정항목 정의

측정항목을 LLM 기반 측정항목 또는 계산 기반 측정항목으로 정의합니다.

LLM 기반 측정항목

LLM 기반 측정항목은 대규모 언어 모델 (LLM)을 '심사자'로 사용하여 알고리즘만으로는 측정하기 어려운 스타일이나 글쓰기 품질과 같은 미묘한 기준을 평가합니다.

관리형 루브릭 기반 측정항목 사용

Vertex AI SDK의 생성형 AI 클라이언트는 GENERAL_QUALITY, SAFETY, INSTRUCTION_FOLLOWING와 같은 다양한 즉시 사용 가능한 모델 기반 측정항목을 제공합니다. RubricMetric 클래스를 통해 이러한 값에 액세스할 수 있습니다. 관리 루브릭 기반 측정항목 정의는 루브릭 기반 측정항목 버전 간의 일관성을 유지하기 위해 중앙 집중식 라이브러리에서 필요에 따라 로드됩니다.

# 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,
    ]
)

여러 SDK 버전에서 일관된 결과를 만들려면 측정항목을 특정 버전에 고정하면 됩니다. 기본적으로 최신 버전이 사용됩니다.

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

LLM 측정항목 맞춤설정

특수한 기준이 필요한 사용 사례의 경우 LLMMetric 클래스를 인스턴스화하여 자체 LLM 기반 측정항목을 정의할 수 있습니다. 이렇게 하면 평가 프롬프트 템플릿, 심사 모델, 기타 매개변수를 완전히 제어할 수 있습니다.

MetricPromptBuilder 도우미 클래스를 사용하면 instruction, criteria, rating_scores를 별도로 정의하여 평가 모델의 구조화된 프롬프트 템플릿을 만들 수 있습니다.

# 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]
)

계산 기반 및 맞춤 함수 측정항목

계산 기반 측정항목은 모델의 출력을 정답이나 참조와 수학적으로 비교합니다. 기본 Metric 클래스를 사용하여 코드로 계산되는 이러한 측정항목은 exact_match, bleu, rouge_1과 같은 사전 정의된 계산 기반 알고리즘을 지원합니다. 계산 기반 측정항목을 사용하려면 측정항목 이름으로 Metric 클래스를 인스턴스화합니다. 이 측정항목을 사용하려면 데이터 세트에 비교를 위한 reference 열이 있어야 합니다.

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

맞춤 함수 측정항목 구현

완전한 제어를 위해 맞춤 Python 함수를 custom_function 매개변수에 전달하여 맞춤 평가 로직을 구현할 수도 있습니다. Vertex AI SDK의 생성형 AI 클라이언트는 데이터 세트의 각 행에 대해 이 함수를 실행합니다.

# 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]
)

평가 데이터 세트 준비

Vertex AI SDK의 생성형 AI 클라이언트는 여러 일반적인 데이터 형식을 자동으로 감지하고 처리합니다. 즉, run_inference로 새로운 대답을 생성하든 evaluate로 기존 대답을 평가하든 수동으로 변환하지 않고도 데이터를 그대로 사용할 수 있는 경우가 많습니다.

Vertex AI SDK의 GenAI 클라이언트는 다음 형식을 지원합니다.

Pandas DataFrame (플랫 형식)

간단한 평가의 경우 pandas.DataFrame를 사용할 수 있습니다. Vertex AI SDK의 GenAI 클라이언트는 prompt, response, reference와 같은 일반적인 열 이름을 찾습니다. 이 형식은 이전 버전과 완전히 호환됩니다.

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 일괄 예측 형식

Vertex AI 일괄 예측 작업의 출력을 직접 사용할 수 있습니다. 출력은 일반적으로 Cloud Storage에 저장된 JSONL 파일이며 각 줄에는 request 및 response 객체가 포함됩니다. Vertex AI SDK의 GenAI 클라이언트는 이 구조를 자동으로 파싱하여 다른 Vertex AI 서비스와의 통합을 제공합니다.

jsonl 파일의 단일 행 예:

{"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."}]}}]}}

그런 다음 일괄 작업에서 사전 생성된 응답을 직접 평가할 수 있습니다.

# 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 Chat Completion 형식

서드 파티 모델을 평가하거나 비교하기 위해 Vertex AI SDK의 GenAI 클라이언트는 OpenAI Chat Completion 형식을 지원합니다. 각 행이 OpenAI API 요청과 같이 구조화된 JSON 객체인 데이터 세트를 제공할 수 있습니다. Vertex AI SDK의 GenAI 클라이언트는 이 형식을 자동으로 감지합니다.

이 형식의 단일 행 예는 다음과 같습니다.

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

이 데이터를 사용하여 서드 파티 모델에서 응답을 생성하고 응답을 평가할 수 있습니다.

# 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()

평가 실행

Vertex AI SDK의 GenAI 클라이언트는 평가를 실행하기 위해 다음과 같은 클라이언트 기반 프로세스를 사용합니다.

run_inference(): 지정된 프롬프트 세트에 대해 모델에서 응답을 생성합니다.
evaluate(): 생성된 대답에 대한 측정항목을 계산합니다.

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()

단일 평가에서 여러 AI 모델 또는 시스템의 성능을 분석하려면 각 후보에 대한 대답을 생성하고 목록에서 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()

비동기 대규모 평가

대규모 데이터 세트의 경우 Vertex AI SDK의 GenAI 클라이언트는 비동기식 장기 실행 일괄 평가 메서드를 제공합니다. 이는 즉각적인 결과가 필요하지 않고 계산을 오프로드하려는 시나리오에 적합합니다.

batch_evaluate() 메서드는 진행 상황을 추적하기 위해 폴링할 수 있는 작업 객체를 반환합니다. 매개변수가 evaluate() 메서드와 호환됩니다.

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
)

서드 파티 모델 평가

Vertex AI SDK의 GenAI 클라이언트를 사용하여 모델 이름 문자열을 run_inference 메서드에 전달하여 OpenAI와 같은 제공업체의 모델을 평가하고 비교할 수 있습니다. Vertex AI SDK의 생성형 AI 클라이언트는 litellm 라이브러리를 사용하여 모델 API를 호출합니다.

필수 API 키를 환경 변수 (OPENAI_API_KEY)로 설정해야 합니다.

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()

시각화

Vertex AI SDK의 GenAI 클라이언트를 사용하면 Colab 또는 Jupyter 노트북과 같은 개발 환경 내에서 결과를 직접 시각화할 수 있습니다. EvaluationDataset 및 EvaluationResult 객체에서 사용할 수 있는 .show() 메서드는 분석을 위한 대화형 HTML 보고서를 렌더링합니다.

추론 결과 시각화

run_inference()로 응답을 생성한 후 결과 EvaluationDataset 객체에서 .show()을 호출하여 모델의 출력과 함께 원래 프롬프트 및 참조를 검사할 수 있습니다. 전체 평가를 실행하기 전에 빠른 품질 확인에 유용합니다.

# 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()

각 프롬프트, 해당 참조 (제공된 경우), 새로 생성된 대답이 표에 표시됩니다.

추론 결과 시각화

평가 보고서 시각화

EvaluationResult 객체에서 .show()를 호출하면 다음과 같은 두 가지 주요 섹션이 포함된 보고서가 표시됩니다.

요약 측정항목: 모든 측정항목의 집계된 뷰로, 전체 데이터 세트의 평균 점수와 표준 편차를 보여줍니다.
세부 결과: 케이스별 분석으로, 각 측정항목의 프롬프트, 참조, 후보 응답, 구체적인 점수 및 설명을 검사할 수 있습니다.

# 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()

평가 보고서

단일 후보자를 평가하는지 아니면 여러 후보자를 비교하는지에 따라 보고서 형식이 달라집니다. 후보자가 여러 명인 평가의 경우 보고서에 나란히 보기 기능이 제공되며 요약 표에 승률/무승부율 계산이 포함됩니다.

모든 보고서에서 원시 JSON 보기 섹션을 펼쳐 구조화된 프롬프트 또는 응답의 데이터를 검사할 수 있습니다.

자세한 비교

다음 단계

평가 빠른 시작 사용해 보기
평가 측정항목 정의

튜토리얼: Vertex AI SDK의 GenAI 클라이언트를 사용하여 평가 실행 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

엔드 투 엔드 예시

측정항목 정의

LLM 기반 측정항목

관리형 루브릭 기반 측정항목 사용

LLM 측정항목 맞춤설정

계산 기반 및 맞춤 함수 측정항목

맞춤 함수 측정항목 구현

평가 데이터 세트 준비

평가 실행

비동기 대규모 평가

서드 파티 모델 평가

시각화

추론 결과 시각화

평가 보고서 시각화

다음 단계

튜토리얼: Vertex AI SDK의 GenAI 클라이언트를 사용하여 평가 실행