Azure Geliştirici CLI AI aracı uzantısıyla Microsoft Foundry'ye aracı dağıtma

Bu makalede, Microsoft Foundry'de aracı ayarlamak ve dağıtmak için Azure Geliştirici CLI (azd) yapay zeka aracısı uzantısını kullanmayı öğreneceksiniz. Uzantı, yerelden buluta tutarlı bir iş akışı için Foundry özelliklerini yaşam döngüsü komutları (azd, azd init) ile azd up birleştirerek terminal veya düzenleyicinizden aracıları iskelelemenize ve dağıtmanıza olanak tanır.

Temel özellikler

• Proje iskelesi: Tam kapsamlı aracı projelerini (altyapı, aracı tanımları, yapılandırma kod şablonları olarak) ayarlayın ve tekrarlamalara hızla başlayın.
• Bildirim temelli yapılandırma: Tutarlı ortamlar için bir azure.yaml dosyada hizmet, kaynak ve model dağıtımları tanımlayın.
• Birleşik sağlama ve dağıtım: Kapsayıcılar oluşturmak, görüntüleri göndermek, kaynak oluşturmak, modelleri dağıtmak ve aracıyı tek adımda yayımlamak için komutunu çalıştırın azd up .
• Agent tanım yönetimi: Kataloglardan, GitHub veya yerel yollardan aracı tanımlarını içeri aktarın; CLI gerekli parametreleri ortam değişkenleriyle eşler.
• Varsayılan olarak güvenli: Kimlik bilgilerini el ile işlemeden yönetilen kimlikleri ve temel güvenliği otomatik olarak ayarlayın.
• Ölçeklenebilir model sağlama: Model adlarını, sürümlerini ve kapasitesini belirtin; azd bunları ortamlar arasında tutarlı bir şekilde dağıtır.

Önkoşullar

• Azure Developer CLI (azd) yüklü (sürüm 1.21.3 veya üzeri) ve kimliği doğrulanmış azd auth login.
  • Uzantı azd ai agent yüklendi (azd extension 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.
• Kaynak grupları ve Microsoft Foundry kaynakları oluşturma iznine sahip bir Azure aboneliği.
• Gerekli işlemler için Azure CLI yüklendi.

Aracıyı ayarlama ve dağıtma

AI aracısı uzantısını kullanarak azd Microsoft Foundry'ye aracı sağlamak ve dağıtmak için aşağıdaki bölümleri tamamlayın.

Foundry şablonunu başlatma

1. Şablonla azd-ai-starter-basic yeni bir proje başlatın. Boş bir klasörde şunu çalıştırın:

   azd init -t Azure-Samples/azd-ai-starter-basic --location northcentralus
   

   Uyarı

   Barındırılmış aracılar şu anda yalnızca ABD'nin Orta Kuzey Azure bölgesiyle sınırlıdır. Microsoft Foundry belgelerinde barındırılan aracıların bölgesel kullanılabilirliği hakkında daha fazla bilgi edinin.

2. İstendiğinde, aracı projesi için bir ortam adı girin (örneğin, "my-analytics-agent").

   İşlem azd init :

   • Başlangıç şablonu dosyalarını projenize klonlar
   • < c0 /> (Altyapı Kodu dosyaları) ve < c1 /> klasörleriyle dizin yapısını oluşturur
   • Yapılandırma azure.yaml dosyası oluşturur
   • Ortama özgü değişkenlerin kurulumunu yapar .azure/<env>/.env

Temsilci tanımını başlat

Başlangıç şablonu proje yapısını sağlar, ancak belirli bir aracı tanımı eklemeniz gerekir. Aracı tanımları, aracınızın davranışını, araçlarını ve özelliklerini açıklar. Örnek tanımları Agent Framework deposunda bulabilirsiniz.

Kendi aracı tanımınızı veya katalogdaki bir aracıyı kullanın. azd ai agent init Komutunu kendi <agent-definition-url> değerinizle çalıştırın:

azd ai agent init -m <agent-definition-url>

Örneğin, basit bir hesap makinesi aracısı için aşağıdaki URL'yi kullanın:

azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/calculator-agent/agent.yaml

Komut azd ai agent init :

• Aracı tanımı YAML dosyasını projenizin src/ dizinine indirir
• Gereksinimlerini anlamak için aracı tanımını analiz eder
• İlgili azure.yaml hizmetler ve yapılandırmalarla güncelleştirmeler
• Aracı parametrelerini ortam değişkenleriyle eşler

Proje yapısını gözden geçirme

Başlatılan şablon şu anahtar dosyalarını içerir:

├── .azure/                 # Environment-specific settings (.env)
├── infra/                  # Bicep files for Azure infrastructure
├── src/                    # Agent definition and code
└── azure.yaml              # Project configuration

Ajent projesinin nasıl ayarlandığını görmek için azure.yaml öğesini açın.

requiredVersions:
    extensions:
        azure.ai.agents: latest
services:
    CalculatorAgent:
        project: src/CalculatorAgent
        host: azure.ai.agent
        language: docker
        docker:
            remoteBuild: true
        config:
            container:
                resources:
                    cpu: "1"
                    memory: 2Gi
                scale:
                    maxReplicas: 3
                    minReplicas: 1
            deployments:
                - model:
                    format: OpenAI
                    name: gpt-4o-mini
                    version: "2024-07-18"
                  name: gpt-4o-mini
                  sku:
                    capacity: 10
                    name: GlobalStandard
infra:
    provider: bicep
    path: ./infra
    module: main

Bu bildirim temelli yapılandırma, aracı hizmetinizi ve model dağıtımları da dahil olmak üzere ihtiyaç duyduğu Azure yapay zeka kaynaklarını tanımlar.

Ajanı sağlama ve dağıtma

Kaynakları ve aracıyı dağıtmak için komutunu çalıştırın azd up :

azd up

komutu azd up , altyapıdan canlı aracı uç noktasına dağıtım iş akışını düzenler:

• Provision altyapısı: Bicep dosyalarında tanımlanan Microsoft Foundry hesabını, projesini ve Azure kaynaklarını oluşturun. - Ön sağlama kancaları aracıları ve bağımlılıklarını, modellerini ve diğer kaynakları inceler, ardından ortam değişkenlerini doldurur, böylece Bicep şunları sağlar: - AI_PROJECT_DEPLOYMENTS (JSON): Dağıtılacak modellerin belirtimi. - AI_PROJECT_CONNECTIONS (JSON): Oluşturulacak bağlantıların belirtimi. - AI_PROJECT_DEPENDENT_RESOURCES (JSON): Bağımlı kaynakların belirtimi. - ENABLE_HOSTED_AGENTS (boole): Barındırılan aracıların sağlanması gerekip gerekmediği (ACR ve CapHost ile).
• Modelleri dağıtır: içinde azure.yaml belirtilen model dağıtımlarını sağlar (örneğin, yapılandırılan kapasiteye sahip GPT-4o-mini).
• Build ve kapsayıcıyı itin: Aracın özel kodu varsa, azd bunu bir kapsayıcı görüntüsüne paketler ve Azure Container Registry'ye kaydeder.
• Aracıyı yayımlama: Microsoft Foundry'de bir Aracı Uygulaması oluşturun ve aracıyı canlı, çağrılabilen bir hizmet olarak dağıtın.

Tamamlandığında azd up çıkışta Microsoft Foundry proje uç noktası, kaynak grup ve proje adları ile aracı uygulamaya ilişkin ayrıntılar gösterilir. Çıkış ayrıca Microsoft Foundry portalında aracı oyun alanına doğrudan bağlantı sağlar.

Uyarı

Yeni bir proje için sağlama ve dağıtım işleminin tamamlanması genellikle birkaç dakika sürer.

Kimlik ve güvenlik

azd kimlik bilgilerini el ile yönetmeniz gerekmemesi için güvenli erişim desenlerini otomatik olarak yapılandırıyor:

• Yönetilen kimlik: Aracınız, diğer Azure kaynaklarda kimlik doğrulaması yapmak için Foundry projesinin sistem tarafından atanan yönetilen kimliğini kullanır.
• Rol atamaları: azd Gerekli izinleri otomatik olarak verir (örneğin, aracınıza Döküm Araçları, depolama alanı veya veritabanlarına erişim verme).
• Endpoint security: Aracı uç noktaları varsayılan olarak Microsoft Entra ID (Azure AD) kimlik doğrulamasını kullanır, böylece aracınızı yalnızca yetkili kullanıcılar veya uygulamalar çağırabilir.

Bu güvenlik yapılandırmaları, kutudan çıkar çıkmaz çalışacak şekilde Azure'un en iyi yöntemlerini izler, böylece güvenli bir temelle başlamanızı sağlar.

Microsoft Foundry'de aracıyı test edin

1. Microsoft Foundry portalını açın.
2. Tarafından azd ayarlanan projeye gidin (proje adı çıktıda azd up görünür).
3. Dağıtılmış ajanınızı görmek için Ajanlar bölümünü açın.
4. Aracıyı oyun alanında başlatın ve "Yeteneklerinizi özetleyin" gibi bir test sorgusu gönderin.

Sohbet penceresinde temsilcinin yanıtını görürsünüz.

azd ile ajanları çalıştırma ve sorun giderme

Aracınızı dağıtdıktan sonra aşağıdaki komutları kullanarak azd aracıyı çağırın, geliştirin, izleyin ve yönetin.

Aracıyı çağırma

azd ai agent invoke'yi, dağıtılmış aracınızı uzaktan veya yerel olarak çağırmak için kullanın. Bu komut aracıya bir ileti gönderir ve yanıtını döndürür.

azd ai agent invoke --message "What is 12 multiplied by 8?"

Aracı yerel olarak çalıştır

Yerel bir geliştirme döngüsü başlatmak için kullanın azd ai agent run . Bu komut aracınızı yerel makinenizde çalıştırır, değişiklikleri hemen alır ve dosyanızda .azure/<environment-name>/.env tanımlanan uzak Azure kaynaklarına bağlanır.

azd ai agent run

Gerçek zamanlı günlükleri akışla aktarma

Canlı günlük çıkışını dağıtılan aracınızdan takip etmek için azd ai agent monitor'yi --follow bayrağı ile kullanın. Bu, aracı davranışını gözlemlemek ve sorunları gerçek zamanlı olarak tanılamak için yararlıdır.

azd ai agent monitor --follow

Ajan sağlığını ve durumunu kontrol etme

Ajanınızın geçerli sağlık durumu, dağıtım durumu ve uç nokta bilgilerini görüntülemek için azd ai agent show kullanın.

azd ai agent show

Tüm kaynakları yok etmek

Azure kaynaklarının azd up tarafından oluşturulan tüm sağlamadan kaldırmak için azd down kullanın. Bu işlem Microsoft Foundry hesabını, projesini, model dağıtımlarını, kapsayıcı kayıt defterini ve Bicep dosyalarınızda tanımlanan diğer tüm altyapıları kaldırır.

azd down

Uyarı

azd down sağlanan tüm kaynakları kalıcı olarak siler. Paylaşılan veya üretim ortamlarında bu komutu dikkatli kullanın.

Gelişmiş yapılandırma

Projelerinizi, varsayılan iş akışının ötesindeki gelişmiş gereksinimleri karşılayacak şekilde özelleştirebilirsiniz.

Model dağıtımlarını özelleştirme

Dosya, azure.yaml hangi modelleri dağıttığınızı denetlemenizi sağlar. Model eklemek veya değiştirmek için dosyayı düzenleyin:

services:
    CalculatorAgent:
        project: src/CalculatorAgent
        host: azure.ai.agent
        language: docker
        docker:
            remoteBuild: true
        config:
            container:
                resources:
                    cpu: "1"
                    memory: 2Gi
                scale:
                    maxReplicas: 3
                    minReplicas: 1
            deployments:
                - model:
                    format: OpenAI
                    name: gpt-4o-mini
                    version: "2024-07-18"
                  name: gpt-4o-mini
                  sku:
                    capacity: 10
                    name: GlobalStandard

Yeni modeli dağıtmak ve projenizi güncelleştirmek için komutunu çalıştırın azd up .

Bu örnek yapılandırma, aracınızın karmaşık mantık için daha büyük bir model ve basit sorgular için daha küçük bir model kullanabilmesi için birden çok model dağıtır.

Ortam değişkenlerini yönetme

azd tarafından ayarlanan veya kullanılan ortam değişkenleri:

Variable	Amaç
AZURE_SUBSCRIPTION_ID	Kaynaklar için hedef abonelik.
AZURE_RESOURCE_GROUP	Yapay zeka projesini barındıran kaynak grubu.
AZURE_LOCATION	Azure bölge (seçilen modelleri desteklemelidir).
AZURE_AI_ACCOUNT_NAME	Microsoft Foundry hesabı (hub).
AZURE_AI_PROJECT_NAME	Ajanı barındıran proje.
AZURE_AI_FOUNDRY_PROJECT_ENDPOINT	Aracı yönetimi ve çalışma zamanı çağrıları için uç nokta.

Bu değişkenler içinde .azure/<environment-name>/.envdepolanır. Bunları her ortam için özelleştirin (geliştirme, test ve üretim).

Birden çok ortam kullanma

azd birden çok adlandırılmış ortamı destekler, böylece birbirinizin ayarlarının üzerine yazmadan geliştirme, test ve üretim için ayrı yapılandırmalar koruyabilirsiniz.

ile azd env newyeni bir ortam oluşturun:

azd env new my-agent-prod

ile azd env selectmevcut ortamlar arasında geçiş yapma:

azd env select my-agent-dev

Her ortamın, yukarıdaki tabloda listelenen ortam değişkenlerini depolayan kendi .azure/<environment-name>/.env dosyası vardır. veya azd up çalıştırdığınızda azd provision, azd seçili durumdaki ortamı hedefler. Aynı aracı tanımını farklı Azure aboneliklerine veya bölgelerine dağıtmak için bu düzeni kullanın.

Örnek kullanım örnekleri ve senaryolar

Çeşitli aracı senaryolarını hızlandırmak için Microsoft Foundry ve yapay zeka aracısı uzantısını azd kullanın.

Konuşma yardımcıları oluşturma

Bağlamla soruları yanıtlayan ve iç verilere bağlanan aracılar oluşturun.

• A/B testi için varyantları dağıtma
• Yanıt zenginleştirme için Azure AI Search ekleme
• İş API'lerini özel araçlarla tümleştirme

Veri ve içgörü aracıları oluşturma

Özetleri, hesaplamaları ve görselleştirmeleri teslim edin.

• Azure SQL Database veya Cosmos DB'ye bağlanın.
• Hesaplama için kod yorumlayıcı araçlarını kullanma
• Daha büyük akıl yürütme modellerini daha düşük maliyetli modellerle karıştırma

Birden çok aracıyı koordine etme

Karmaşık iş akışları için uzmanları koordine edin.

• İstekleri yönlendirmek için bir koordinatör aracısı ekleyin.
• içinde azure.yamlilişkileri bildirimli olarak tanımlayın.
• Aracıları yüke göre bağımsız olarak ölçeklendirin.

Kurumsal dağıtımı standartlaştırma

Ekipler arasında tutarlılığı sağlayın.

• Yeniden kullanılabilir şemaları ve şablonları yayımlama
• Tutarlı güvenlik, uyumluluk ve izleme uygulama
• CI/CD'de azd provision ve azd deploy ile sağlama ve dağıtımı otomatikleştirin.

Ekosistemi keşfetme

• Örnek aracıları keşfedin: Agent Framework deposuna göz atarak .NET aracıları ve Python aracıları bulun ve bunları ile dağıtın.
• Topluluğa katıl: Azure Geliştirici CLI GitHub tartışmalarında deneyimlerini paylaşın ve sorular sorun.
• : Azure/azure-dev deposunda geri bildirim ve sorun veya özellik önerileri gönderin ve bunları ai-agent ile etiketleyin.
• Belgeleri gözden geçirin: Aracı geliştirmeyle ilgili kapsamlı kılavuzlar için Microsoft Foundry belgelerini ziyaret edin.

Ek kaynaklar

• Azure Developer CLI'yi yükle
• Azure Developer CLI belgeleri
• Microsoft Foundry belgeleri
• Agent Framework deposu (örnekler ve araçlar)
• Azure Developer CLI GitHub deposu
• Foundry başlangıç şablonu