Azure Geliştirici CLI ile aracı geliştirme

Important

Bu makalede önizleme olarak işaretlenmiş öğeler şu anda önizleme aşamasındadır. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve Microsoft üretim iş yükleri için bunu önermez. 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ı.

Azure Developer CLI (azd ai agent) ve azd uzantısı, fikir aşamasından Microsoft Foundry'de üretime hazır bir aracı geliştirmeye kadar uzanan tek bir komut satırı iş akışı sunar. Kod tabanlı barındırılan aracılar ve bildirim temelli istem tabanlı ses aracıları geliştirebilirsiniz. Bu makalede geliştirici yolculuğu, aracı tanımlayan dosyalar ve yol boyunca karşılaştığınız temel kavramlar açıklanmaktadır.

Bu makale, Foundry portalı veya dil SDK'ları yerine terminal öncelikli, betik yazılabilir bir iş akışını tercih eden geliştiricilere yöneliktir.

Geliştirici yolculuğu

küçük azd ai bir prototip veya üretim aracısı oluşturmanız fark etmeksizin iş akışı aynı yaşam döngüsünü izler. Bir projeyi bir kez iskelelersiniz, ardından projeniz büyüdükçe komutları karıştırır ve eşleştirirsiniz.

Stage Ne yaparsınız? Daha fazla bilgi nereden edinilir?
Install azd ve Foundry uzantılarını yükleyin. Geliştirici ortamınızı ayarlama
İskele Bir şablondan veya mevcut kodunuzdan barındırılan bir aracı başlatın veya istem tabanlı bir ses aracısı oluşturun. Hızlı Başlangıç: Barındırılan aracı dağıtma veya Hızlı Başlangıç: İstem ses aracısı oluşturma
Tanımlamak azure.yaml içinde aracıyı, model dağıtım bağımlılıklarını, protokolleri, araçları ve ortamı yapılandırın. Barındırılan aracılar için azure.yaml’ı oluşturma
Develop Aracı mantığı yazın, araç kutusu kullanarak araçlar ekleyin ve yerel olarak test edin. Araç kutusuna genel bakış
Deploy Altyapıyı sağlayın ve Foundry'ye dağıtın. Barındırılan aracı dağıt
Çalıştırmak Günlükleri izleyin, sürümleri yönetin ve çalıştırmaları otomatikleştirin. Barındırılan aracıları yönetme
Evaluate Ajan kalitesini ölçün ve istemi iyileştirin. azd CLI ile aracı değerlendirmeleri çalıştırma

Aracı türleri

Uzantı, azd ai agent kod tabanlı ve bildirim temelli aracı türlerini destekler.

Türü Description Ne zaman kullanılır?
Barındırılan aracı Kodda derlediğiniz, Docker görüntüsü olarak paketlediğiniz ve Foundry'ye dağıtabileceğiniz kapsayıcılı bir uygulama. Özel mantık, çerçeve tümleştirmesi veya davranış üzerinde tam denetime ihtiyacınız vardır.
İstem ajanı Özel kod içermeyen yönergeler ve araç yapılandırmaları aracılığıyla tanımlanan bir aracı. Uygulama kodu yazmadan hızlı, yapılandırma temelli bir aracı istiyorsunuz.
İstem tabanlı ses aracısı Özel çalışma zamanı kodu olmadan yönetilen veya kendi kendine dağıtılan bir model kullanan bildirim temelli bir ses aracısı. Ses işlem hattı oluşturmadan ve barındırmadan gerçek zamanlı bir konuşma sesi deneyimi istiyorsunuz.
Yönetilen sarmalayıcı ile barındırılan ses aracısı Barındırılan bir hedef konuşma mantığını işlerken, ayrı bir ses hizmeti bunu conversationEngine üzerinden ona devreder. Ses deneyimini Voice Live işler. Barındırılan hedef ortamda konuşma tanıma ve konuşma sentezini gerçekleştirmeden özel aracı mantığına ihtiyaç duyuyorsunuz.

Barındırılan aracılar çalışma zamanı, çerçeve ve araç tümleştirmeleri üzerinde tam denetim sağlarken Foundry altyapı, ölçeklendirme ve oturum yönetimini işler.

İstem tabanlı ses aracıları özel bir kapsayıcı gerektirmez. Kendi konteynerinizde özel bir konuşmadan konuşmaya veya ardışık ses işlem hattı çalıştırmanız gerekiyorsa, barındırılan bir aracıyla ses aracısı oluşturun ve invocations_ws protokolünü kullanın.

Voice Live sesi işlerken konuşma mantığını barındırılan metin aracısında tutmak için barındırılan ses sarmalayıcı iş akışını kullanın. Sarmalayıcı ve hedef, aynı azure.yaml projedeki ayrı hizmetlerdir. Bu akış, mevcut özel invocations_ws ses işlem hattı akışının yerini almaz.

Genel önizleme sesli CLI seçeneklerini kullanmadan önce, ses aracısı hızlı başlangıç önkoşullarında açıklandığı gibi yüklü uzantınızı denetleyin.

Yapılandırma dosyaları

Barındırılan aracı projesi, hem aracıyı hem de sağlama ve dağıtım modelini bildirmek için proje kökünde bir azure.yaml dosya kullanır. Dosya, her adlandırılmış hizmetin host, azure.ai.project, azure.ai.agent, azure.ai.connection, azure.ai.toolbox veya azure.ai.skill gibi bir azure.ai.routine değerine sahip olduğu bölünmüş hizmet modelini kullanır.

File Purpose Bunu kim koruyor?
azure.yaml Foundry projesini, model dağıtımlarını, barındırılan aracı hizmetini, bağımlılıkları, protokolleri, araçları, ortam değişkenlerini, kapsayıcı kaynaklarını ve dağıtım ayarlarını bildirir. Hizmette azure.ai.agent aracı kimliği, model, protokoller, araçlar ve ortam değerleri bulunur. Başlatma bunu oluşturur. Gerektiğinde özelleştirebilirsiniz.

azure.ai.agent hizmeti, barındırılan aracınızı satır içinde tanımlar ve proje, bağlantılar, araç kutuları, beceriler ve yordamlar gibi diğer hizmetlere başvurmak için uses: kullanır. Mevcut barındırılan aracı agent.yaml proje modelinde bağımsız agent.manifest.yaml veya azd dosyası yoktur.

İstem tabanlı bir ses aracısı için, azure.yaml modeli, model türünü ve aracı adını içeren kind: prompt-voicebildirim temelli aracı tanımını depolar. Barındırılan aracı kapsayıcı çalışma zamanı içermez. Yönergeleri, sesi, dönüş algılamayı, transkripsiyonu, ses çıkışını, araçları ve selamlamaları özelleştirmek için bkz. Ses aracısını yapılandırma.

Barındırılan bir ses sarmalayıcısı için conversationEngine.name, barındırılan hedefin hizmet adına atıfta bulunur. Sarmalayıcının uses bağımlılıkları dağıtımı sıralar ve conversationEngine.version varsayılan olarak geçerli ortam tarafından dağıtılan sürümü kullanır. Yapılandırma alanları için ses hizmeti başvurusuna bakın.

Değişken değiştirme

${VAR_NAME} ortama göre farklılık gösteren değerler için azure.yaml içinde azd kullanın. Yer tutucu, dağıtım veya çalışma zamanında .azure/<env>/.env içinden çözümlendiği için aynı azure.yaml geliştirme, test ve üretim gibi ortamlarda çalışır.

CLI'nın çalıştığı yer

Komutlar azd ai bir azd proje dizininin içinde ve dışında çalışır:

  • Bir azd projesinde, komutlar Foundry proje uç noktasını etkin azd ortamından belirler.
  • azd projesi dışında, etkin bağlamı azd ai project set <endpoint> ile bir kez ayarlayın veya --project-endpoint seçeneğini tek tek kaynak komutlarında (connection, toolbox, skill ya da routine) belirtin. Geri dönüş olarak ortam azd ai değişkenini FOUNDRY_PROJECT_ENDPOINT okur.
  • Proje içi ortam her zaman genel bağlamdan önceliklidir, bu nedenle dizinleri bir projeye değiştirmek, o projenin uç noktasındaki CLI'yı yeniden hedef alır.

Protocols

Protokol, Foundry ile aracı kapsayıcınız arasındaki HTTP sözleşmesini tanımlar. Aracınız 8088 numaralı bağlantı noktasını dinler ve protokolden bağımsız olarak bir sistem durumu yoklaması sunar.

Protocol API stili Ne zaman kullanılır?
responses OpenAI Yanıtları API'si (POST /responses) OpenAI API ekosistemiyle uyumlu standart seçim.
invocations Özel JSON sözleşmesi (POST /invocations) İstek ve yanıt yükleri üzerinde tam denetime ihtiyacınız olduğunda.

Tam belirtim için bkz. Barındırılan aracı çalışma zamanı sözleşmesi.

Bu protokol ayarları barındırılan aracı kapsayıcıları için geçerlidir. İstem tabanlı sesli ajanlar, barındırılan bir ajan protokolünü yapılandırmaz.

azd ai agent invoke , istem tabanlı ses aracıları veya barındırılan ses sarmalayıcıları için sesli konuşmalar uygulamaz. CLI davranışı ve test kılavuzu için bkz . Ses aracısı sınırlamaları.

Oturumlar ve konuşmalar

Concept Description
Session Tek bir aracı etkileşimi için yalıtılmış bir yürütme ortamı. Her oturum, kendine ayrılmış kaynaklarla kendi yalıtılmış ortamında çalışır.
Konuşma Oturum içindeki bir ileti dizisi. Foundry, konuşma geçmişini yönetir ve bunu istekler arasında sürdürebilir.

Oturumlar bir session_idtarafından tanımlanır. çalıştırdığınızda azd ai agent invoke, Foundry varsayılan olarak son çağrınızdaki oturumu yeniden kullanır. Yeniden başlamak için --new-session kullanın veya belirli bir oturumu hedeflemek için --session-id <id> kullanın.

Dökümhane projesindeki kaynaklar

Foundry projesi aracılardan daha fazlasını barındırıyor. Ayrıca, aracıların çalışma zamanında başvurduğu paylaşılan kaynakları da barındırır. CLI, her birini ayrılmış bir komut grubu aracılığıyla yönetir.

Resource Bu nedir Ile yönetilir
Connection Foundry projesini MCP sunucusu, Azure Yapay Zeka Arama veya Bing ile Topraklama gibi bir dış kaynağa bağlar. azd ai connection Komutlar
Araç Kutusu Aracıların çalışma zamanında kullandığı adlandırılmış bir araç koleksiyonu. azd ai toolbox Komutlar
Beceri Projedeki aracılar arasında paylaşılan yeniden kullanılabilir davranış yönergeleri. azd ai skill Komutlar
Rutin Tetikleyici ve aracı çağıran bir eylem. azd ai routine Komutlar

Bu kaynaklar aynı projedeki geliştiriciler ve aracılar arasında paylaşılır. Her komut grubu standart create, , updatedelete, , showve list fiillerini kullanıma sunar.

Ajanı değerlendirin ve iyileştirin

Aracı çalıştırıldıktan sonra ilgili iki iş akışı, kalitesini ölçmenize ve geliştirmenize yardımcı olur:

  • Değerlendirme aracınızı bir veri kümesinde çalıştırır, yanıtları bir veya daha fazla değerlendiriciyle puanlar ve toplam kalite sinyali raporlar. Bunu azd ai agent eval ile yönetirsiniz.
  • Optimizasyon, değerlendirme sinyalini yükseltmek için aracınızın istemini yinelemeli olarak yeniden yazar. Nesnel işlevi olarak bir değerlendirme kullanır ve gözden geçirip kabul ettiğiniz bir aday istemi oluşturur. Bunu azd ai agent optimize ile yönetirsiniz.

Ayrıntılar için bkz. Azd CLI ile aracı değerlendirmelerini çalıştırma ve Aracı istemlerini iyileştirme.

Dağıtım yaşam döngüsü

Tam geliştirici döngüsü kısa bir komut dizisi halinde yoğunlaşır. Bir kez iskele yapın, ardından projeniz büyüdükçe doğrudan komutları kullanın.

Yönetilen ses aracısı yaklaşımı için bkz. Hızlı başlangıç: İstem ses aracısı oluşturma.

# Scaffold a project from a template or your existing code
azd ai agent init

# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"

# Provision infrastructure and deploy the agent
azd up

# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent

# Evaluate quality
azd ai agent eval generate
azd ai agent eval run

# Tear down all Azure resources
azd down

İlgili içerik

  • Last updated on