azd CLI ile ajan değerlendirmelerini çalıştırın (önizleme)

Important

Bu makalede işaretlenen (önizleme) öğeler şu anda genel önizleme aşamasındadır. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve üretim iş yükleri için önerilmez. Bazı özellikler desteklenmeyebilir veya kısıtlı özelliklere sahip olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları.

Microsoft Foundry ile oluşturulan bir aracıya ölçülen kalite döngüsü eklemek için Azure Geliştirici CLI (azd) CLI değerlendirme deneyimini kullanın. Bu makale, azd içindeki barındırılan aracının yaşam döngüsüne odaklanır; burada değerlendirme varlıklarını oluşturur, sağlama işlemini yapar, dağıtır, başlatır, ilk değerlendirmeyi çalıştırır, çalıştırmayı gözden geçirir ve değerlendirme tarifini sonraki çalıştırmalarda yeniden kullanırsınız.

İstem tabanlı aracılar, Foundry projesinde aracı hedefleri olarak kullanılabilir olduğunda da değerlendirilebilir. Barındırılan aracı dağıtım adımları yalnızca barındırılan aracılar için geçerlidir.

Bu makale, azd ai agent eval generate ve azd ai agent eval run ile ilk aracı değerlendirmesinin nasıl çalıştırılacağını açıklar.

Prerequisites

  • Microsoft Foundry erişimi olan bir Azure aboneliği.
  • Azure Geliştirici CLI'sı (azd). Yükleme yönergeleri için bkz. Azure Developer CLI yükleme.
  • Uzantı azd ai agent , sürüm 0.1.40-preview veya üzeri yüklü (azd ext install azure.ai.agents). Uzantı yüklü değilse, başlangıç şablonunu başlatdığınızda veya çalıştırdığınızda azd ai agent uzantı otomatik olarak yüklenir. Yüklü sürümü doğrulamak için komutunu azd ext list çalıştırın ve yükseltmeniz gerekiyorsa çalıştırın azd ext upgrade azure.ai.agents . Yapay zeka aracısı uzantısı hakkında azd daha fazla bilgi edinmek için bkz. Microsoft Foundry aracı uzantısı.
  • Kimliği doğrulanmış azd bir oturum. Kimlik doğrulama durumunuzu denetlemek için komutunu çalıştırın azd auth status. Oturum açmadıysanız komutunu çalıştırın azd auth login.
  • Dökümhane kaynağındaki Foundry User rolü (eski adı Azure AI User). Daha fazla bilgi için bkz. Microsoft Foundry için rol tabanlı erişim denetimi.
  • Barındırılan aracılar için: Önceden oluşturulmuş bir Foundry projesi gerekli değildir. azd ai agent init ve azd provision gerekli kaynakları oluşturun.
  • İstem tabanlı aracılar için: Aracının zaten dağıtılıp değerlendirme hedefi olarak kullanılabilir olduğu mevcut bir Foundry projesi.
  • Aynı Foundry projesinde sohbet tamamlama işlemlerini destekleyen bir model dağıtımı.
  • İsteğe bağlı: Duman veri kümesi oluşturmak istemiyorsanız eval generate temsili örnekler içeren bir JSONL değerlendirme veri kümesi.

azd ajan değerlendirmeleri nasıl çalışır

Temel azd CLI değerlendirme deneyimi, barındırılan aracı yaşam döngüsüne yönelik olarak tasarlanmıştır:

azd ai agent init
azd provision
azd deploy
azd ai agent eval generate
azd ai agent eval run
azd ai agent eval update
# Optional, after the agent and eval recipe meet optimization prerequisites:
azd ai agent optimize

Değerlendirme akışı aşağıdaki bileşenleri ve komutları içerir.

Item Description
eval generate Bir aracı hedefi için yerel değerlendirme varlıkları oluşturur veya onarır.
eval.yaml Yerelde çalıştırılabilen değerlendirme yönergesi. Aracı hedefini, veri kümesi başvurularını, değerlendirici başvurularını ve oluşturma seçeneklerini kaydeder
Oluşturulan yerel yapıtlar Oluşturulan veri kümelerinin ve değerlendirici rubric'lerin düzenlenebilir yerel kopyaları. Yapılar, aracı klasörünün altında datasets/ ve evaluators/ içinde depolanır (örneğin, src/<agent-name>/datasets/ ve src/<agent-name>/evaluators/).
Kayıtlı hizmet yapıtları Değerlendirme çalıştırmalarında kullanılan Foundry veri kümesi ve değerlendirici sürümleri. Bunlar, oluşturulan varlıklar için doğruluk kaynağıdır.
eval run Değerlendirme tarifini seçili aracı hedefinde çalıştırır.
eval update Yerel veri kümesinden veya değerlendirici düzenlemelerinden yeni hizmet sürümlerini kaydeder ve onaydan sonra eval.yaml öğesini güncelleştirir.
eval list ve eval show Değerlendirme çalıştırmalarını ve sonuçlarını CLI’dan inceleyin.
optimize --config eval.yaml İsteğe bağlı olarak, aracı ve tarif iyileştirme önkoşullarını karşıladıktan sonra değerlendirme tarifinden iyileştirmeyi başlatır.

azd provision değerlendirme veri kümeleri, değerlendiriciler, paketler veya iyileştirme işleri oluşturmaz. Değerlendirme kurulumu dakikalar süren bir oluşturma çalışması içerebilir, bu nedenle açık ve yeniden denenebilir kalır.

Barındırılan ajanlar için ilk değerlendirme, dağıtıma alınmış ve çağrılabilir bir ajan hedefi gerektirir. İstem tabanlı aracılar için dağıtım adımı geçerli değildir; aracının Foundry projesinde zaten mevcut olması ve değerlendirme hedefi olarak kullanılabilir olması gerekir.

Barındırılan aracıyı oluşturun ve dağıtın

Henüz bir barındırılan aracı projeniz yoksa, azd ile bir proje başlatın:

azd ai agent init

Foundry kaynaklarını sağlayın ve aracıyı dağıtın:

azd provision
azd deploy

Dağıtım tamamlandıktan sonra aracının çağrılabilir olduğunu doğrulayın:

azd ai agent show

Değerlendirme varlıklarını başlatmadan önce barındırılan aracının dağıtılmış ve çağrılabilir durumda olması gerekir.

Başarılı bir dağıtımdan sonra CLI, değerlendirmeyi açık bir sonraki adım olarak önerir:

Set up an evaluation suite to measure quality and impact in one step with `azd ai agent eval generate`

İstem tabanlı aracıyı değerlendirmek için barındırılan aracı oluşturma ve dağıtım komutlarını atlayın. Foundry projesinde istem tabanlı aracı bulunduğunu ve değerlendirme hedefi olarak kullanılabilir olduğunu onayladıktan sonra sonraki bölüme geçin.

Note

Hedef tabanlı değerlendirme, barındırılan aracınızı doğrudan çağırır. Yanıtlar veya çağrılar protokolünü eşzamanlı, akışsız çalıştırmayla kullanan aracılarla çalışır. A2A veya Activity protokolünü ya da uzun süreli çalışma veya akış gibi diğer yürütme kalıplarını kullanan ajanları değerlendirmek için, bunun yerine ajanınızın oluşturduğu izleri değerlendirin. Bkz. İzleme değerlendirmesi.

Değerlendirme varlıklarını başlatın

azd çalışma alanından veya aracı proje klasöründen komutunu çalıştırın eval generate :

azd ai agent eval generate

Bayrak olmadan komut etkileşimli bir sihirbaz başlatır. Sihirbaz, azd ortamından aracının hedefini tespit eder, ardından hizmetin yararlı başlangıç değerlendirme verileri ve değerlendirme ölçütleri oluşturabilmesi için bir oluşturma talimatı ister.

Örnek etkileşimli çıkış:

? Eval suite name: reservation-agent
? How would you like to provide the agent instruction?: Type inline
? Describe what this agent does and what scenarios to test: This agent handles restaurant reservations. Test booking, modification, cancellation, and policy enforcement.
? Include agent traces for evaluator generation?: No
? Select the model for evaluation and generation: gpt-4o (deployed)
? Max samples (between 15 and 1000): 100
  (–) Running  Evaluator generation  (evaluatorgen-reservation-agent-v3-abc12345)
  (–) Running  Dataset generation  (datagen-abc123456)
  (✓) Done  Evaluator generation  (20 seconds)
  (✓) Done  Dataset generation  (2m 9s)

Eval suite created
  Config:     src/reservation-agent/eval.yaml
  Dataset:    reservation-agent-dev-eval-seed (1.0)
              src/reservation-agent/datasets/reservation-agent-dev-eval-seed
  Evaluator:  builtin.task_adherence
  Evaluator:  reservation-agent-quality (1)
              src/reservation-agent/evaluators/reservation-agent-quality/rubric_dimensions.json

  Evaluator dimensions (4):
    Weight  Dimension
    ──────  ─────────
        10  booking_accuracy
         5  policy_enforcement
         6  cancellation_handling
         5  general_quality

  Portal:
    Dataset:   https://ai.azure.com/.../build/data/datasets/reservation-agent-dev-eval-seed/1.0
    Evaluator: https://ai.azure.com/.../build/evaluations/catalog/reservation-agent-quality/1

  Next steps:
    azd ai agent eval run
      Run the eval suite against your agent.
    azd ai agent eval update
      Edit the generated dataset or evaluator locally, then upload changes.

Komut dosyasıyla kullanım için, üretim girdilerini doğrudan iletin:

azd ai agent eval generate \
  --gen-instruction "This agent handles restaurant reservations. Test booking, modification, cancellation, and policy enforcement." \
  --eval-model gpt-4o \
  --max-samples 100

--out-file isteğe bağlıdır ve aracı proje kökünde varsayılan eval.yaml olarak ayarlanır. Yapılandırmayı farklı bir konuma yazmak için kullanın --out-file <path> .

Mevcut bir veri kümesini ve seçili değerlendiricileri kullanmak için:

azd ai agent eval generate \
  --dataset ./tests/support-golden.jsonl \
  --gen-instruction "Support quality, policy adherence, and escalation behavior" \
  --max-samples 50 \
  --evaluator builtin.intent_resolution \
  --evaluator support-quality \
  --out-file eval.yaml

./tests/support-golden.jsonl ifadesini kendi değerlendirme veri kümenizin yolu ile değiştirin.

Değer --dataset yerel bir dosyaya veya kayıtlı bir veri kümesi adına işaret edebilir. Birden çok yerleşik veya kayıtlı özel değerlendiriciyi eklemek için --evaluator öğesini yineleyin. Değerlendirici başvuruları şu biçimi kullanır: <source>.<name>

Oluşturmayı ertele --no-wait

Veri kümesinin veya değerlendiricinin oluşturulması çok uzun sürüyorsa, oluşturma görevlerini gönderip hemen çıkmak için --no-wait kullanın:

azd ai agent eval generate \
  --gen-instruction "..." \
  --no-wait

Bekleyen işlem kimlikleri öğesine eval.yamlyazılır. azd ai agent eval run komutunu daha sonra çalıştırdığınızda, değerlendirme çalışmasını başlatmadan önce bu işlemlere otomatik olarak devam eder.

İstem tabanlı aracı hedefi kullanma

İstem tabanlı bir aracı için değerlendirme varlıklarını başlatmışsanız, aynı değerlendirme tarifi akışını kullanabilirsiniz. Barındırılan aracı dağıtım adımı, istem tabanlı aracılar için gerekli değildir.

Değerlendirmeyi çalıştırmadan önce şunları onaylayın:

  • istem tabanlı aracı, Foundry projesinde bulunur.
  • Ajan, değerlendirme hedefi olarak kullanılabilir.
  • Proje uç noktasına ve aracı hedefine erişiminiz vardır.
  • eval.yaml istenen istem tabanlı aracıyı seçer.

Geçerli Foundry projesinde kullanılabilir aracıları listelemek için şunu çalıştırın:

azd ai agent list

Ardından, değerlendirmeyi çalıştırmak ve incelemek için aynı komutları kullanın:

azd ai agent eval run --config eval.yaml
azd ai agent eval show

eval.yaml dosyasını gözden geçirin

eval generate başarılı olduktan sonra, eval.yaml öğesini agent projesinin kök dizininde açın. Örneğin:

src/reservation-agent/eval.yaml

eval run komutunu bu dizinden çalıştırın veya yolu --config src/reservation-agent/eval.yaml ile açıkça belirtin. Dosya aracı hedefini, veri kümesi başvurularını, değerlendirici başvurularını ve oluşturma seçeneklerini tanımlar. Basitleştirilmiş bir şekil:

name: reservation-agent
agent:
  name: reservation-agent
  kind: hosted
  version: "3"
  config: .agent_configs\baseline\metadata.yaml
dataset_reference:
  name: reservation-agent-dev-eval-seed
  version: "1.0"
  local_uri: datasets\reservation-agent-dev-eval-seed
evaluators:
  - builtin.task_adherence
  - name: reservation-agent-quality
    version: "1"
    local_uri: evaluators\reservation-agent-quality\rubric_dimensions.json
options:
  eval_model: gpt-4o
max_samples: 100
  • eval.yaml, örneğin src/<agent-name>/eval.yaml, ajan proje kökünde bulunur.
  • Oluşturulan veri kümeleri datasets/ altında, oluşturulan değerlendirici değerlendirme ölçütleri ise aracı klasöründe evaluators/ altında bulunur.
  • local_uri içindeki eval.yaml yolları, aracı proje dizinine görelidir.
  • Tarafından local_uri başvurulan yerel dosyalar düzenlenebilir. Yerel değişiklikleri hizmette yeni bir sürüm olarak kaydetmek ve azd ai agent eval update içindeki sürümü artırmak için eval.yaml komutunu çalıştırın.
  • eval run, eval.yaml içinde sabitlenmiş kaydedilmiş sürümü kullanır. Yerel düzenlemeleri uygulamak için öncesinde eval updatekomutunu çalıştırıneval run.
  • Değerlendiriciler, yerleşik referanslar (örneğin, builtin.task_adherence) veya name, version ve local_uri ile oluşturulan özel değerlendiriciler olabilir.
  • Sürüm alanlarını sayısal görünseler bile dize olarak değerlendirin, böylece tarif YAML ayrıştırıcıları arasında kararlı kalır.

Değerlendirmeyi çalıştırma

Ajan proje klasöründe aşağıdakini çalıştırın:

azd ai agent eval run

Varsayılan olarak, argümansız eval run, eval.yaml öğesini aracı projesinin kök dizininde çözümler. Yapılandırma yolunu açıkça da geçirebilirsiniz:

azd ai agent eval run --config eval.yaml

eval generate --no-wait, bekleyen oluşturma işlemleri oluşturduysa eval run, değerlendirme çalıştırmasını başlatmadan önce bu işlemleri sürdürür. Yeni veri kümesi veya değerlendirici oluşturma işlerini sıfırdan başlatmaz.

Değerlendirme çalıştırmalarını inceleyin

Son değerlendirme çalıştırmalarını listele:

azd ai agent eval list

En son çalıştırmayı göster:

azd ai agent eval show

Hiçbir seçenek belirtilmediğinde, eval show varsayılan olarak en son değerlendirmeyi seçer ve çalıştırma kayıtlarını listeler.

Belirli bir çalıştırmanın ayrıntılarını göstermek için değerlendirme kimliğini bağımsız değişken olarak, çalıştırma kimliğini ise --eval-run-id ile iletin. Değerlendirme kimliğini azd ai agent eval list çıktısından ve çalıştırma kimliğini azd ai agent eval show <eval-id> çıktısından kopyalayın:

azd ai agent eval show <eval-id> --eval-run-id <run-id>

Yanıtlamak için çalıştırma çıktısını kullanın:

  • Hangi ajan sürümü değerlendirildi.
  • Hangi veri kümesi ve değerlendirici sürümleri çözümlendi.
  • Çalıştırmanın tamamlanmış, başarısız olmuş veya kısmen tamamlanmış olma durumu.
  • Hangi metriklerin veya değerlendirici puanlarının üretildiği.
  • Belirteç kullanımının veya değerlendirici günlüklerinin incelenmesi gerekip gerekmediği.

Aracıyı değiştirdikten sonra yeniden çalıştırın

Barındırılan bir aracıyı güncelleştirip yeniden dağıtdıktan sonra aynı değerlendirme tarifini yeniden çalıştırın:

azd deploy
azd ai agent eval run --config eval.yaml

İstem tabanlı aracılar için Foundry'de aracıyı güncelleştirin ve ardından aynı değerlendirme tarifini yeniden çalıştırın.

Aynı eval.yaml öğesini yeniden çalıştırmak, veri kümesi, değerlendirici ve eşik referanslarının aracıdaki değişiklikler arasında kararlı kalmasına yardımcı olur.

Değerlendirme varlıklarını güncelleştirme, sıfırlama veya onarma

Aracı değerlendirme akışı, eval.yaml öğesini yerel değerlendirme tarifi olarak kullanır. Yerel veri kümesi dosyalarını veya değerlendirici bölümlerini düzenlerken ve bu düzenlemeleri yeni hizmet sürümleri olarak kaydetmek istediğinizde kullanın azd ai agent eval update .

Değerlendirme çalıştırmasının kullandığı verileri güncelleştirmek için, değişiklik türüyle eşleşen yolu seçin:

Change Nasıl güncelleştirilir?
Eşikleri, değerlendirici referanslarını, çıkış ayarlarını veya diğer tarif alanlarını değiştirme eval.yaml öğesini düzenleyin, ardından azd ai agent eval run --config eval.yaml komutunu çalıştırın.
Farklı bir yerel veya kayıtlı veri kümesi kullanma eval.yaml içindeki veri kümesi referansını düzenleyin veya azd ai agent eval generate --dataset <path-or-name> --out-file eval.yaml öğesini yeniden çalıştırın.
Değerlendirici referansları ekle veya değiştir eval.yaml öğesini düzenleyin veya azd ai agent eval generate değerleriyle --evaluator öğesini yeniden çalıştırın.
Yerel düzenlemeleri oluşturulan bir veri kümesine veya değerlendirici puanlama anahtarına kaydetme azd ai agent eval update komutunu çalıştırın, algılanan değişiklikleri gözden geçirin ve eval.yaml içindeki sürüm başvurusu güncellemesini onaylayın.
Varsayılan olarak oluşturulan kurulumdan yeniden başlayın azd ai agent eval generate --reset-defaults'i çalıştırın.

Örneğin, agent klasörü altındaki evaluators/ altında oluşturulan değerlendirici değerlendirme ölçütlerini düzenledikten sonra şunu çalıştırın:

azd ai agent eval update
azd ai agent eval run --config eval.yaml

Update komutu yeni kayıtlı veri kümesi veya değerlendirici sürümleri oluşturur. Mevcut değerlendirme çalıştırmaları başlangıçta kullandıkları sürümlere bağlı kalır.

Zaten mevcut olduğunda eval.yaml , eval generate bunu algılar ve mevcut yapılandırmayı yazdırır:

Eval config already exists: src/reservation-agent/eval.yaml
  Dataset:    reservation-agent-dev-eval-seed (1.0)
              src/reservation-agent/datasets/reservation-agent-dev-eval-seed
  Evaluator:  builtin.task_adherence
  Evaluator:  reservation-agent-quality (1)
              src/reservation-agent/evaluators/reservation-agent-quality/rubric_dimensions.json

  To run the evaluation:
    azd ai agent eval run

  To update local edits as new versions:
    azd ai agent eval update

  To overwrite and regenerate:
    azd ai agent eval generate --reset-defaults

Yerel yapılandırmanın üzerine yazmak ve varsayılan değerlendirme varlıklarını yeniden oluşturmak için şunu çalıştırın:

azd ai agent eval generate --reset-defaults

--reset-defaults yerel eval.yaml değerin üzerine yazar ve varsayılan değerlendirme varlıklarını yeniden oluşturur. Mevcut hizmet kayıtlı veri kümesi ve değerlendirici sürümleri silinmez; sadece yerel tarif değiştirilir.

Yerel tarifi sessizce değiştiren uzak en son sürümlere güvenmeyin. Yerel eval.yaml , tarifin yeniden üretilebilirlik için kullandığı veri kümesi, değerlendirici veya paket sürümlerini kaydeder.

İsteğe bağlı: değerlendirme sinyalinden iyileştirmeyi başlatma

En az bir değerlendirme çalıştırması başarıyla tamamlandıktan sonra, aracı ve reçete optimize etme önkoşullarını karşılıyorsa eval.yaml öğesini aracı optimize etme için girdi olarak kullanabilirsiniz.

İyileştirmeye başlamadan önce şunları onaylayın:

  • Aracı hedefi optimizasyona hazır. Barındırılan aracılar için aracı dağıtılmıştır ve çağrılabilir.
  • eval.yaml hedeflenen aracıya, veri kümesine, değerlendirici sürümlerine ve eşiklere başvurur.
  • En az bir değerlendirme yürütmesi başarıyla tamamlandı.
  • Eniyileyici için gereken ajan hazırlığı tamamlandı. İyileştirici önkoşulları ve aracı hazırlama gereksinimleri için bkz. prompt Optimizer ile aracı istemlerini iyileştirme.

Ardından şunu çalıştırın:

azd ai agent optimize --config eval.yaml

optimize komutu aracı hedefini, veri kümesini, değerlendiricileri ve eşikleri adresinden eval.yamlokur. Bir optimizasyon işi gönderir, ancak kaynak değişikliklerini sessizce uygulamaz veya aday aracıyı yeniden dağıtıma almaz. Değişiklikleri uygulamadan önce iyileştirici çıktılarını gözden geçirin.

En iyi uygulamalar

  • Yalnızca aracı değerlendirme hedefi olarak kullanılabilir olduktan sonra çalıştırın azd ai agent eval generate . Barındırılan ajanlar için, ajanın dağıtılmış ve çağrılabilir olması gerekir.
  • Küçük bir veri kümesiyle veya altın veri kümenizin küçük bir alt kümesiyle başlayın.
  • Puanlara güvenmeden önce, oluşturulan veri setini ve değerlendirici inceleme artefaktlarını kontrol edin.
  • Oluşturulan veri kümesi veya değerlendirici dosyalarını düzenledikten sonra, değerlendirmeyi yeniden çalıştırmadan önce düzenlenen varlıkları kaydetmek için komutunu çalıştırın azd ai agent eval update .
  • Ekibinizin gözden geçirilebilir, yeniden üretilebilir bir değerlendirme tarifi isteyip istemediğini kontrol eval.yaml edin.
  • Ekibiniz bunları değerlendirme akışının bir parçası olarak gözden geçirip düzenliyorsa, ajan klasöründe datasets/ ve evaluators/ altındaki oluşturulmuş veri kümelerini ve değerlendirici değerlendirme ölçütlerini kaynak denetimine almayı göz önünde bulundurun.
  • Aracı değiştikten sonra aynı eval.yaml işlemi yeniden çalıştırın, böylece karşılaştırmalar aynı test tarifini kullanır.
  • Yalnızca yararlı bir temel değerlendirme sonucunuz olduğunda ve aracı iyileştirme için hazırlandıktan sonra kullanın azd ai agent optimize --config eval.yaml .

Sınırlamalar

  • Birincil komut akışı barındırılan aracılar ve dağıtım sonrası değerlendirme döngüsü için iyileştirilmiştir.
  • azd provision değerlendirme varlıkları oluşturmaz.
  • eval run, eval generate --no-wait içindeki bekleyen işlemleri sürdürme dışında yeni veri kümeleri veya değerlendiriciler oluşturmaz.
  • İlk değerlendirme yolu için tam paket yaşam döngüsü, zamanlanmış değerlendirme, sürekli değerlendirme, uyarılar ve karşılaştırma iş akışları gerekli değildir.

İlgili içerik

  • Last updated on