تقييم Agent

توفر adk-eval crate أدوات شاملة لاختبار سلوك Agent والتحقق منه. على عكس اختبار البرمجيات التقليدي، يجب أن يأخذ تقييم Agent في الاعتبار الطبيعة الاحتمالية لـ LLMs مع توفير إشارات جودة ذات مغزى.

نظرة عامة

يدعم تقييم Agent في ADK-Rust استراتيجيات تقييم متعددة:

• تقييم المسار (Trajectory Evaluation): التحقق من أن agents تستدعي الأدوات المتوقعة بالتسلسل الصحيح
• تشابه الاستجابة (Response Similarity): مقارنة استجابات Agent باستخدام خوارزميات مختلفة (Jaccard, Levenshtein, ROUGE)
• التقييم المحكوم بواسطة LLM (LLM-Judged Evaluation): استخدام LLM آخر لتقييم التشابه الدلالي والجودة
• التقييم القائم على المعايير (Rubric-Based Scoring): التقييم مقابل معايير مخصصة مع تسجيل مرجح

بدء سريع

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),  // يتطلب مطابقة بنسبة 100%
    tool_trajectory_config: Some(ToolTrajectoryConfig {
        strict_order: true,   // يجب استدعاء الأدوات بترتيب دقيق
        strict_args: false,   // يسمح بوسائط إضافية في استدعاءات الأدوات
    }),
    ..Default::default()
};

خيارات:

• strict_order: يتطلب مطابقة تسلسل دقيقة
• strict_args: يتطلب مطابقة دقيقة للوسائط (لا يسمح بوسائط إضافية)
• مطابقة جزئية مع حدود قابلة للتكوين

تشابه الاستجابة

مقارنة نص الاستجابة باستخدام خوارزميات مختلفة:

let criteria = EvaluationCriteria {
    response_similarity: Some(0.8),  // مطلوب تشابه بنسبة 80%
    response_match_config: Some(ResponseMatchConfig {
        algorithm: SimilarityAlgorithm::Jaccard,
        ignore_case: true,
        normalize: true,
        ..Default::default()
    }),
    ..Default::default()
};

الخوارزميات المتاحة:

المطابقة الدلالية المحكومة بواسطة LLM

استخدام LLM لتقييم التكافؤ الدلالي:

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

// إنشاء مقيم باستخدام LLM judge
let judge_model = Arc::new(GeminiModel::new(&api_key, "gemini-2.0-flash")?);
let config = EvaluationConfig::with_criteria(
    EvaluationCriteria::semantic_match(0.85)
);
let evaluator = Evaluator::with_llm_judge(config, judge_model);

يقوم LLM judge بتقييم:

• التكافؤ الدلالي (نفس المعنى، كلمات مختلفة)
• الدقة الواقعية
• اكتمال الاستجابة

التقييم القائم على معايير (Rubric)

التقييم مقابل معايير مخصصة مع تسجيل مرجح:

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

يتم تسجيل كل معيار (rubric) من 0-1 بواسطة LLM judge، ثم يتم دمجها باستخدام الأوزان.

اكتشاف السلامة والهلوسة

التحقق من الاستجابات بحثًا عن مشكلات السلامة والهلوسة:

let criteria = EvaluationCriteria {
    safety_score: Some(0.95),        // يتطلب درجة أمان عالية
    hallucination_score: Some(0.9),  // يتطلب معدل هلوسة منخفض
    ..Default::default()
};

الإبلاغ عن النتائج

يوفر تقرير التقييم نتائج مفصلة:

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

// إحصائيات ملخصة
println!("الإجمالي: {}", report.summary.total);
println!("اجتاز: {}", report.summary.passed);
println!("فشل: {}", report.summary.failed);
println!("معدل الاجتياز: {:.1}%", report.summary.pass_rate * 100.0);

// حالات الفشل المفصلة
for result in report.failures() {
    println!("فشل: {}", result.eval_id);
    for failure in &result.failures {
        println!("  - {}: {} (متوقع: {}, فعلي: {})",
            failure.criterion,
            failure.message,
            failure.expected,
            failure.actual
        );
    }
}

// تصدير إلى JSON لـ CI/CD
let json = report.to_json()?;
std::fs::write("eval_results.json", json)?;

التقييم الدفعي

التقييم المتوازي

قم بتقييم حالات الاختبار المتعددة بشكل متزامن:

let results = evaluator
    .evaluate_cases_parallel(agent, &cases, 4)  // 4 عمليات تقييم متزامنة
    .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());
}

أمثلة

# تقييم أساسي
cargo run --example eval_basic

# التحقق من المسار
cargo run --example eval_trajectory

# المطابقة الدلالية المحكوم عليها بواسطة LLM
cargo run --example eval_semantic

# التسجيل القائم على المعايير
cargo run --example eval_rubric

# خوارزميات تشابه الاستجابة
cargo run --example eval_similarity

# إنشاء التقارير
cargo run --example eval_report

أفضل الممارسات

1. ابدأ ببساطة: ابدأ بالتحقق من المسار قبل إضافة الفحوصات الدلالية
2. استخدم حالات تمثيلية: يجب أن تغطي ملفات الاختبار الحالات الهامشية والسيناريوهات الشائعة
3. معايرة العتبات: ابدأ بعتبات متساهلة وشددها مع تحسن الـ Agent
4. اجمع المعايير: استخدم معايير متعددة لإجراء تقييم شامل
5. تحكم في إصدار ملفات الاختبار: احتفظ بملفات الاختبار في نظام التحكم بالإصدار جنبًا إلى جنب مع كود الـ Agent
6. التكامل مع CI/CD: قم بتشغيل التقييمات في CI لاكتشاف الانحدارات

---

السابق: ← بروتوكول A2A | التالي: التحكم في الوصول →