एजेंट मूल्यांकन

adk-eval क्रेट एजेंट व्यवहार के परीक्षण और सत्यापन के लिए व्यापक उपकरण प्रदान करता है। पारंपरिक सॉफ्टवेयर परीक्षण के विपरीत, एजेंट मूल्यांकन को LLMs की संभाव्य प्रकृति को ध्यान में रखना चाहिए, जबकि अभी भी सार्थक गुणवत्ता संकेत प्रदान करना चाहिए।

अवलोकन

ADK-Rust में एजेंट मूल्यांकन कई मूल्यांकन रणनीतियों का समर्थन करता है:

प्रक्षेपवक्र मूल्यांकन: सत्यापित करें कि एजेंट अपेक्षित टूल को सही क्रम में कॉल करते हैं
प्रतिक्रिया समानता: विभिन्न एल्गोरिदम (Jaccard, Levenshtein, ROUGE) का उपयोग करके एजेंट प्रतिक्रियाओं की तुलना करें
LLM-निर्णित मूल्यांकन: सिमेंटिक समानता और गुणवत्ता का आकलन करने के लिए एक और LLM का उपयोग करें
रूब्रिक-आधारित स्कोरिंग: भारित स्कोरिंग के साथ कस्टम मानदंडों के विरुद्ध मूल्यांकन करें

त्वरित आरंभ

use adk_eval::{Evaluator, EvaluationConfig, EvaluationCriteria};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create your agent
    let agent = create_my_agent()?;

    // Configure evaluator with criteria
    let config = EvaluationConfig::with_criteria(
        EvaluationCriteria::exact_tools()
            .with_response_similarity(0.8)
    );

    let evaluator = Evaluator::new(config);

    // Run evaluation against test file
    let report = evaluator
        .evaluate_file(agent, "tests/my_agent.test.json")
        .await?;

    // Check results
    if report.all_passed() {
        println!("All {} tests passed!", report.summary.total);
    } else {
        println!("{}", report.format_summary());
    }

    Ok(())
}

परीक्षण फ़ाइल प्रारूप

परीक्षण मामले JSON फ़ाइलों में .test.json एक्सटेंशन के साथ परिभाषित किए गए हैं:

{
  "eval_set_id": "weather_agent_tests",
  "name": "Weather Agent Tests",
  "description": "Test weather agent functionality",
  "eval_cases": [
    {
      "eval_id": "test_current_weather",
      "conversation": [
        {
          "invocation_id": "inv_001",
          "user_content": {
            "parts": [{"text": "What's the weather in NYC?"}],
            "role": "user"
          },
          "final_response": {
            "parts": [{"text": "The weather in NYC is 65°F and sunny."}],
            "role": "model"
          },
          "intermediate_data": {
            "tool_uses": [
              {
                "name": "get_weather",
                "args": {"location": "NYC"}
              }
            ]
          }
        }
      ]
    }
  ]
}

मूल्यांकन मानदंड

टूल प्रक्षेपवक्र मिलान

सत्यापित करता है कि एजेंट अपेक्षित टूल को सही क्रम में कॉल करते हैं:

let criteria = EvaluationCriteria {
    tool_trajectory_score: Some(1.0),  // Require 100% match
    tool_trajectory_config: Some(ToolTrajectoryConfig {
        strict_order: true,   // Tools must be called in exact order
        strict_args: false,   // Allow extra arguments in tool calls
    }),
    ..Default::default()
};

विकल्प:

strict_order: सटीक अनुक्रम मिलान की आवश्यकता है
strict_args: सटीक तर्क मिलान की आवश्यकता है (कोई अतिरिक्त तर्क अनुमत नहीं)
कॉन्फ़िगर करने योग्य थ्रेशोल्ड के साथ आंशिक मिलान

प्रतिक्रिया समानता

विभिन्न एल्गोरिदम का उपयोग करके प्रतिक्रिया टेक्स्ट की तुलना करें:

let criteria = EvaluationCriteria {
    response_similarity: Some(0.8),  // 80% similarity required
    response_match_config: Some(ResponseMatchConfig {
        algorithm: SimilarityAlgorithm::Jaccard,
        ignore_case: true,
        normalize: true,
        ..Default::default()
    }),
    ..Default::default()
};

उपलब्ध एल्गोरिदम:

एल्गोरिथम	विवरण
`Exact`	सटीक स्ट्रिंग मिलान
`Contains`	सबस्ट्रिंग जाँच
`Levenshtein`	एडिट दूरी
`Jaccard`	शब्द ओवरलैप (डिफ़ॉल्ट)
`Rouge1`	यूनिग्राम ओवरलैप
`Rouge2`	बिगराम ओवरलैप
`RougeL`	सबसे लंबा सामान्य अनुक्रम

LLM-निर्णित सिमेंटिक मिलान

सिमेंटिक समानता का मूल्यांकन करने के लिए एक LLM का उपयोग करें:

use adk_eval::{Evaluator, EvaluationConfig, EvaluationCriteria, LlmJudge};
use adk_model::GeminiModel;

// Create evaluator with LLM judge
let judge_model = Arc::new(GeminiModel::new(&api_key, "gemini-2.5-flash")?);
let config = EvaluationConfig::with_criteria(
    EvaluationCriteria::semantic_match(0.85)
);
let evaluator = Evaluator::with_llm_judge(config, judge_model);

LLM निर्णायक मूल्यांकन करता है:

सिमेंटिक समानता (समान अर्थ, भिन्न शब्द)
तथ्यात्मक सटीकता
प्रतिक्रिया की पूर्णता

रूब्रिक-आधारित मूल्यांकन

भारित स्कोरिंग के साथ कस्टम मानदंडों के विरुद्ध मूल्यांकन करें:

use adk_eval::{Rubric, EvaluationCriteria};

let criteria = EvaluationCriteria::default()
    .with_rubrics(0.7, vec![
        Rubric::new("Accuracy", "Response is factually correct")
            .with_weight(0.5),
        Rubric::new("Helpfulness", "Response addresses user's needs")
            .with_weight(0.3),
        Rubric::new("Clarity", "Response is clear and well-organized")
            .with_weight(0.2),
    ]);

प्रत्येक रूब्रिक को LLM निर्णायक द्वारा 0-1 स्कोर किया जाता है, फिर भार का उपयोग करके संयोजित किया जाता है।

सुरक्षा और मतिभ्रम का पता लगाना

सुरक्षा संबंधी समस्याओं और मतिभ्रम के लिए प्रतिक्रियाओं की जाँच करें:

let criteria = EvaluationCriteria {
    safety_score: Some(0.95),        // Require high safety score
    hallucination_score: Some(0.9),  // Require low hallucination rate
    ..Default::default()
};

परिणाम रिपोर्टिंग

मूल्यांकन रिपोर्ट विस्तृत परिणाम प्रदान करती है:

let report = evaluator.evaluate_file(agent, "tests/agent.test.json").await?;

// Summary statistics
println!("Total: {}", report.summary.total);
println!("Passed: {}", report.summary.passed);
println!("Failed: {}", report.summary.failed);
println!("Pass Rate: {:.1}%", report.summary.pass_rate * 100.0);

// Detailed failures
for result in report.failures() {
    println!("Failed: {}", result.eval_id);
    for failure in &result.failures {
        println!("  - {}: {} (expected: {}, actual: {})",
            failure.criterion,
            failure.message,
            failure.expected,
            failure.actual
        );
    }
}

// Export to JSON for CI/CD
let json = report.to_json()?;
std::fs::write("eval_results.json", json)?;

बैच मूल्यांकन

समानांतर मूल्यांकन

एक साथ कई परीक्षण मामलों का मूल्यांकन करें:

let results = evaluator
    .evaluate_cases_parallel(agent, &cases, 4)  // 4 concurrent evaluations
    .await;

डायरेक्टरी मूल्यांकन

एक डायरेक्टरी में सभी परीक्षण फ़ाइलों का मूल्यांकन करें:

let reports = evaluator
    .evaluate_directory(agent, "tests/eval_cases")
    .await?;

for (file, report) in reports {
    println!("{}: {} passed, {} failed",
        file,
        report.summary.passed,
        report.summary.failed
    );
}

cargo test के साथ एकीकरण

मानक Rust परीक्षणों में मूल्यांकन का उपयोग करें:

#[tokio::test]
async fn test_weather_agent() {
    let agent = create_weather_agent().unwrap();
    let evaluator = Evaluator::new(EvaluationConfig::with_criteria(
        EvaluationCriteria::exact_tools()
    ));

    let report = evaluator
        .evaluate_file(agent, "tests/weather_agent.test.json")
        .await
        .unwrap();

    assert!(report.all_passed(), "{}", report.format_summary());
}

उदाहरण

मूल्यांकन APIs के लिए मानक फीचर टियर का उपयोग करें:

cargo check -p adk-rust --no-default-features --features standard

चलने योग्य मूल्यांकन उदाहरण इस साइट में शामिल ADK-Rust Playground में उपलब्ध हैं।

उन्नत सुविधाएँ

निम्नलिखित क्षमताएँ adk-eval को Braintrust, LangSmith, और Inspect AI जैसे फ्रेमवर्क के बराबर लाती हैं। वे मौजूदा API के अतिरिक्त हैं और जहाँ वे नई निर्भरताएँ पेश करते हैं, वहाँ फीचर-गेटेड हैं।

संरचित LLM निर्णायक

फंक्शन-कॉलिंग या JSON फॉलबैक के माध्यम से स्कोर और तर्क के साथ टाइप किए गए फैसले (पास/फेल/आंशिक) उत्पन्न करता है:

use adk_eval::{StructuredJudge, StructuredJudgeConfig};

let judge = StructuredJudge::new(model.clone());

let verdict = judge.judge(
    "The capital of France is Paris.",
    "Paris is the capital of France.",
    "factual_accuracy"
).await?;

println!("Score: {:.2}, Verdict: {:?}", verdict.score, verdict.verdict);
println!("Reasoning: {}", verdict.reasoning);

निर्णायक पहले फंक्शन-कॉलिंग (प्रतिक्रिया स्कीमा) का प्रयास करता है, फिर JSON के लिए प्रॉम्प्टिंग पर वापस आता है जिसमें एक उदार पार्सर होता है जो कच्चे JSON, मार्कडाउन फेंस और गद्य में एम्बेडेड JSON को संभालता है।

लागत और विलंबता ट्रैकिंग

टोकन उपयोग को ट्रैक करें और प्रति मूल्यांकन अनुमानित डॉलर लागत की गणना करें:

use adk_eval::{CostTracker, CostMetrics};

let tracker = CostTracker::new();  // Uses default pricing tables

// Compute cost for a known model
let cost = tracker.compute_cost("gpt-4o", 2000, 800);
// → Some(0.013)

// Extract metrics from event streams
let metrics = tracker.extract_metrics(&events, duration);
println!("Tokens: {}, Latency: {}ms", metrics.total_tokens, metrics.latency_ms);

एग्जीक्यूशन ट्रेस विश्लेषण

अनावश्यक टूल कॉल, एग्जीक्यूशन लूप का पता लगाएं और दक्षता स्कोर की गणना करें:

use adk_eval::{TraceAnalyzer, TraceAnalysis};

let analyzer = TraceAnalyzer::new();
let analysis = analyzer.analyze(&events);

println!("Efficiency: {:.1}%", analysis.efficiency_score * 100.0);
for diag in &analysis.diagnostics {
    println!("  [{:?}] {}", diag.pattern_type, diag.description);
}

रिग्रेशन बेसलाइन

मूल्यांकन मेट्रिक्स को बेसलाइन के रूप में सहेजें और गुणवत्ता रिग्रेशन का पता लगाएं:

use adk_eval::BaselineStore;

let store = BaselineStore::new(".eval-baseline.json");

// Save current metrics
store.save("my_eval_set", &metrics)?;

// On next run, check for regressions
let regressions = store.check_regressions(&current_metrics, 0.05)?;
if !regressions.is_empty() {
    for reg in &regressions {
        println!("REGRESSION: {} dropped from {:.3} to {:.3}",
            reg.metric_name, reg.baseline_value, reg.current_value);
    }
}

CI आउटपुट (JUnit XML)

नेटिव CI एकीकरण (GitHub Actions, Jenkins, GitLab CI) के लिए JUnit XML उत्पन्न करें:

use adk_eval::JunitReporter;  // requires `ci-helpers` feature

let xml = JunitReporter::generate(&report, "my_eval_suite")?;
std::fs::write("test-results.xml", xml)?;

मानव एनोटेशन वर्कफ़्लो

मानव समीक्षा के लिए मामलों को निर्यात करें और निर्णयों को वापस आयात करें:

use adk_eval::AnnotationStore;

// Export cases for annotation
AnnotationStore::export(&cases, &results, "review.jsonl")?;

// After human review, import back
let (records, warnings) = AnnotationStore::import("review.jsonl", &valid_ids)?;

A/B एजेंट तुलना

सांख्यिकीय महत्व परीक्षण के साथ दो एजेंटों की तुलना करें:

use adk_eval::{AbComparator, ab_comparator::wilcoxon_signed_rank};

// Requires `statistics` feature
let comparator = AbComparator::new(evaluator);
let report = comparator.compare(agent_a, agent_b, &eval_cases).await?;

for cmp in &report.criteria_comparisons {
    println!("{}: A={:.3} B={:.3} p={:.4} significant={}",
        cmp.criterion, cmp.agent_a_mean, cmp.agent_b_mean,
        cmp.p_value, cmp.significant);
}

स्वचालित रूप से उत्पन्न परीक्षण मामले

विवरण (LLM के माध्यम से) या उत्पादन इवेंट लॉग से मूल्यांकन मामले उत्पन्न करें:

use adk_eval::{TestGenerator, GeneratorConfig};

let generator = TestGenerator::with_config(model, GeneratorConfig {
    cases_per_description: 5,
    include_tool_expectations: true,
});

// From natural language
let cases = generator.generate_from_description(
    "A weather assistant that looks up forecasts by city"
).await?;

// From production events (no LLM needed)
let cases = generator.generate_from_events(&production_events)?;

मल्टी-टर्न वार्तालाप मेट्रिक्स

चार आयामों पर विस्तारित वार्तालापों का मूल्यांकन करें:

use adk_eval::{ConversationScorer, ConversationScorerConfig};

let scorer = ConversationScorer::new(judge);
let metrics = scorer.score(&conversation, "Help user plan a trip").await?;

println!("Context retention: {:.2}", metrics.context_retention);
println!("Goal completion:   {:.2}", metrics.goal_completion);
println!("Coherence:         {:.2}", metrics.coherence);
println!("Topic drift:       {:.2}", metrics.topic_drift);

एम्बेडिंग-आधारित सिमेंटिक समानता

वेक्टर एम्बेडिंग का उपयोग करके अर्थ संरक्षण को मापें (embedding सुविधा की आवश्यकता है):

use adk_eval::EmbeddingScorer;

let scorer = EmbeddingScorer::new(embedding_provider);
let score = scorer.score("expected text", "actual text").await?;
// Returns 0.0–1.0 cosine similarity

फीचर फ्लैग्स

सुविधा	निर्भरता	क्षमता
`embedding`	`adk-memory`	एम्बेडिंग-आधारित सिमेंटिक समानता
`ci-helpers`	`quick-xml`	JUnit XML रिपोर्ट जनरेशन
`statistics`	`statrs`	A/B तुलना के लिए विलकॉक्सन साइन्ड-रैंक टेस्ट

अन्य सभी सुविधाएँ (संरचित जज, लागत ट्रैकर, ट्रेस एनालाइजर, बेसलाइन, एनोटेशन, टेस्ट जनरेटर, कन्वर्सेशन स्कोरर) बिना किसी अतिरिक्त फीचर फ्लैग के काम करती हैं।

CLI एकीकरण

कमांड लाइन से cargo adk eval के माध्यम से मूल्यांकन चलाएँ:

# Basic evaluation
cargo adk eval tests/my_agent.test.json

# Save baseline
cargo adk eval tests/ --save-baseline

# Check for regressions
cargo adk eval tests/ --check-regression --tolerance 0.05

# JUnit XML output for CI
cargo adk eval tests/ --format junit --output results.xml

# JSON output
cargo adk eval tests/ --format json

# Parallel execution
cargo adk eval tests/ --concurrency 4

एग्जिट कोड:

0 — सभी मूल्यांकन पास हुए, कोई रिग्रेशन नहीं
1 — रिग्रेशन का पता चला (जब --check-regression सेट हो)

सर्वोत्तम अभ्यास

सरल शुरुआत करें: सिमेंटिक जांच जोड़ने से पहले ट्रैजेक्टरी सत्यापन से शुरू करें
प्रतिनिधि मामलों का उपयोग करें: टेस्ट फ़ाइलों में सीमांत मामले और सामान्य परिदृश्य शामिल होने चाहिए
थ्रेशोल्ड कैलिब्रेट करें: उदार थ्रेशोल्ड से शुरू करें और एजेंट के बेहतर होने पर उन्हें कड़ा करें
मानदंडों को संयोजित करें: व्यापक मूल्यांकन के लिए कई मानदंडों का उपयोग करें
टेस्ट फ़ाइलों का संस्करण करें: एजेंट कोड के साथ संस्करण नियंत्रण में टेस्ट फ़ाइलों को रखें
CI/CD एकीकरण: रिग्रेशन पकड़ने के लिए CI में मूल्यांकन चलाएँ
बेसलाइन सहेजें: गुणवत्ता मानक स्थापित करने के बाद --save-baseline का उपयोग करें, फिर CI में --check-regression का उपयोग करें
संरचित जज का उपयोग करें: मशीन-पार्सेबल परिणामों के लिए सादे LLM जज के बजाय StructuredJudge को प्राथमिकता दें
लागत ट्रैक करें: गुणवत्ता के साथ दक्षता रिग्रेशन की निगरानी के लिए CostTracker सक्षम करें
लूप का पता लगाएँ: दोहराए जाने वाले पैटर्न में फंसे एजेंटों को पकड़ने के लिए TraceAnalyzer सक्षम करें

उदाहरण

सभी सुविधाओं को प्रदर्शित करने वाला एक पूर्ण कार्यशील उदाहरण उपलब्ध है:

cargo run --manifest-path examples/eval_showcase/Cargo.toml

स्रोत कोड के लिए examples/eval_showcase/ देखें।

पिछला: ← A2A प्रोटोकॉल | अगला: एक्सेस कंट्रोल →