Vertex AI Gen AI 평가 서비스

vertex-eval 기능은 adk-eval와 Vertex AI Gen AI 평가 서비스를 연결합니다. 모델 기반 판단은 로컬 LLM 대신 서비스의 자동 평가기에서 실행되며, 도구 궤적은 서비스의 계산 기반 궤적 지표로 평가됩니다. 모든 호출은 projects.locations:evaluateInstances(v1beta1)에 대한 단일 POST 요청입니다.

설정

[dependencies]
adk-eval = { version = "2.1.0", features = ["vertex-eval"] }

인증에는 애플리케이션 기본 자격 증명(gcloud auth application-default login 또는 배포된 컨테이너의 워크로드 ID)이 사용됩니다. 호출자에게는 aiplatform.endpoints.predict 권한(roles/aiplatform.user)이 필요합니다.

서비스 기반 judge

VertexEvalJudge는 LlmJudge의 평가 인터페이스를 미러링합니다 — 동일한 메서드 이름과 동일한 결과 타입을 사용하므로 로컬 judge를 대상으로 작성된 코드에 그대로 사용할 수 있습니다:

use adk_eval::{VertexEvalClient, VertexEvalConfig, VertexEvalJudge};
use adk_eval::criteria::{Rubric, RubricConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = VertexEvalConfig::from_env()?;
    let judge = VertexEvalJudge::new(VertexEvalClient::new_with_adc(config)?);

    // Semantic equivalence (pointwiseMetricInput under the hood)
    let result = judge
        .semantic_match("The capital is Paris", "Paris is the capital of France", None)
        .await?;
    println!("score={} equivalent={}", result.score, result.equivalent);

    // Rubric-based quality, weight-normalized like LlmJudge
    let rubrics = RubricConfig {
        rubrics: vec![
            Rubric::new("Accuracy", "Response is factually correct").with_weight(2.0),
            Rubric::new("Clarity", "Response is easy to follow"),
        ],
    };
    let quality = judge.evaluate_rubrics("agent output", "task context", &rubrics).await?;
    println!("overall={}", quality.overall_score);

    // Safety and hallucination checks
    let safety = judge.evaluate_safety("agent output").await?;
    let hallucination = judge
        .detect_hallucinations("agent output", "provided context", Some("ground truth"))
        .await?;
    println!("safe={} grounded={}", safety.is_safe, hallucination.hallucination_free);
    Ok(())
}

LlmJudge과의 차이점은 서비스가 각 판정마다 하나의 {score, explanation} 쌍을 반환한다는 데서 비롯됩니다:

• 불리언 판정(equivalent, is_safe, hallucination_free)은 점수에서 도출됩니다 — 0.5 이상이면 통과로 간주합니다.
• issues에는 파싱된 목록 대신 서비스의 설명이 단일 항목으로 포함됩니다.

궤적 메트릭

VertexEvalClient::evaluate_trajectory는 adk-eval ToolUse 값을 와이어 Trajectory 형식(name → toolName, args → JSON-인코딩된 toolInput)에 매핑하고 점수를 반환합니다:

use adk_eval::{TrajectoryMetric, VertexEvalClient, VertexEvalConfig};
use adk_eval::schema::ToolUse;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = VertexEvalClient::new_with_adc(VertexEvalConfig::from_env()?)?;

    let predicted = vec![ToolUse::new("get_weather").with_args(json!({ "city": "Paris" }))];
    let reference = predicted.clone();

    let score = client
        .evaluate_trajectory(TrajectoryMetric::ExactMatch, &predicted, &reference)
        .await?;
    assert_eq!(score, 1.0);
    Ok(())
}

Judge 모델 구성

AutoraterConfig은 모델 기반 메트릭의 Judge 모델과 샘플링을 선택합니다. 서버는 계산 기반 메트릭에 대해서는 이를 무시합니다.

use adk_eval::{AutoraterConfig, VertexEvalClient, VertexEvalConfig};

fn build() -> adk_core::Result<VertexEvalClient> {
    let client = VertexEvalClient::new_with_adc(VertexEvalConfig::from_env()?)?
        .with_autorater_config(
            AutoraterConfig::new()
                .with_autorater_model(
                    "projects/p/locations/us-central1/publishers/google/models/gemini-3.7-flash",
                )
                .with_sampling_count(1),
        );
    Ok(client)
}

사용자 지정 메트릭

evaluate_pointwise은 모든 PointwiseMetricSpec을 허용합니다. metricPromptTemplate에는 인스턴스 객체에서 서버 측으로 렌더링되는 {placeholder} 변수가 포함됩니다.

use adk_eval::{PointwiseMetricSpec, VertexEvalClient, VertexEvalConfig};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = VertexEvalClient::new_with_adc(VertexEvalConfig::from_env()?)?;

    let spec = PointwiseMetricSpec::new(
        "Rate the politeness of the response from 0.0 to 1.0.\n\nResponse:\n{response}",
    );
    let result = client
        .evaluate_pointwise(&spec, &json!({ "response": "Thanks for asking!" }))
        .await?;
    println!("score={:?} explanation={:?}", result.score, result.explanation);
    Ok(())
}

evaluate_instances은 원시 이스케이프 해치입니다. 모든 EvaluateInstancesRequest 본문을 POST하고 원시 응답을 반환하므로, 서비스가 지원하는 다른 모든 메트릭(BLEU, ROUGE, 쌍별 메트릭, 도구 호출 메트릭)에 접근할 수 있습니다.

오류 처리

오류는 eval 구성 요소와 eval.vertex.* 코드(eval.vertex.rate_limited, eval.vertex.unauthorized, eval.vertex.invalid_response, ...)가 포함된 구조화된 AdkError 값입니다. VertexEvalJudge 메서드는 LlmJudge과 일치하는 crate의 EvalError::JudgeError를 반환합니다.

참고 항목

• 에이전트 평가 — 평가자, 기준 및 로컬 Judge
• Vertex AI Gen AI 평가 개요
• projects.locations.evaluateInstances REST 참조