Azure Geliştirici CLI'sı ile barındırılan aracı projesini başlatma

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ı.

Microsoft Foundry'ye bir yapay zeka aracısı derlemek, test etmek ve dağıtmak için gereken dosyalarla bir barındırılan aracı projesi iskelesi oluşturmak üzere azd ai agent init kullanın. Bu makalede, bir başlangıç noktası seçer ve projeyi bir şablondan, kendi kodunuzdan veya mevcut bir Dökümhane projesine karşı başlatırsınız.

GitHub Copilot gibi bir kodlama aracısı kullanıyorsanız, Microsoft Döküm Becerisi bir başlangıç şablonu seçmenize, projeyi iskelenize yüklemenize ve oluşturulan azd yapılandırmayı yorumlamanıza yardımcı olabilir.

Prerequisites

Başlangıç noktası seçme

Projeye başlamanın üç yolu vardır. Durumunuzla eşleşen yolu seçin.

Consideration Şablondan başlama Kendi kodunuzu getirin Mevcut projeyi bağlama
En iyi kullanım alanları Araç setini öğrenen yeni ajanlar. Foundry'de barındırmak istediğiniz mevcut aracı kodu. Bir Foundry projesinde zaten çalışan ajanlar.
Command azd ai agent init boş bir dizinde. azd ai agent init var olan kodu içeren bir dizinde. azd ai agent init, ardından mevcut bir proje seçin.
Ne elde edersiniz? Tam olarak yapılandırılmış bir proje: tek bir src/<agent-name>/, azure.yaml altında ajan kaynak kodu ve konteyner dağıtımı için bir Dockerfile. Altyapı varsayılan olarak Bicep’sizdir ve daha sonra dışarı alınabilir. Oluşturulmuş bir azure.yaml hizmet girdisi ve konteyner dağıtımı için kodunuzu saran bir Dockerfile. Altyapı, varsayılan olarak Bicep içermez ve daha sonra çıkarılabilir. azure.yaml Mevcut Dökümhane projenize kablolu bir bağlantı. Altyapı varsayılan olarak Bicep olmadan gelir ve daha sonra çıkarılabilir.
Kod değişiklikleri Yok. Çalıştırmaya hazır. Bir protokol bağdaştırıcısı gerekebilir. Yok.

Şablondan başlatma

Etkileşimli sihirbazı boş bir dizinde çalıştırın ve Şablondan yeni başlat'ı seçin:

azd ai agent init

Sihirbaz, aşağıdaki seçeneklerde size yol gösterir.

Uyarı Description
Aracı Şablonu Çerçeveye ve dile göre düzenlenmiş şablonlar arasından seçim yapın (Python veya .NET).
Azure aboneliği Foundry projesini bulmak veya oluşturmak için kullanılan abonelik.
Dökümhane projesi Mevcut bir projeyi seçin veya yeni bir proje oluşturun. Bir tane oluşturursanız, ayrıca bir bölge de seçersiniz.
Model dağıtımı Mevcut bir model dağıtımı seçin veya şablon varsayılanlarından bir tane oluşturulur.

Ajan adı şablondan alınır. CLI, azd adlı bir ortam oluşturur ve bunu seçtiğiniz Foundry projesindeki ayrıntılarla yapılandırır. Her şablon, ajan kaynak kodunu, bir Dockerfile ve azure.yaml projesi ile barındırılan ajan yapılandırması için birleşik proje bildirimi görevi gören bir azd dosyasını içerir.

azure.yaml URL'sinden başlatma

Belirli bir aracı örneğiniz varsa, -m öğesini örneğin azure.yaml konumuna yönlendirin. CLI, bu dosyayı proje bildirimi olarak benimser ve başvuruda bulunılan aracı kaynağını indirir.

azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml

Uyarı

Aracı bildirimleri (agent.manifest.yaml) ve tek başına aracı tanımları (agent.yaml) kullanım dışıdır. Foundry azd uzantılarından (azure.ai.agents 1.0.0-beta.1) itibaren, barındırılan aracıya ilişkin tüm yapılandırma tek bir azure.yaml içinde yer alır. Bkz. Barındırılan aracılar için azure.yaml dosyası yazma.

-m seçeneği hâlâ eski bir aracı manifestosu URL’sini kabul eder, ancak güncel örnekler birleşik bir azure.yaml yayımlar.

Model belirtme

Başlangıçta bir model seçin:

azd ai agent init --model gpt-4.1

Veya Foundry projenizde var olan bir model dağıtımını kullanabilirsiniz:

azd ai agent init --model-deployment my-deployment

Dağıtım modu seçme

Varsayılan olarak, azd ai agent init Python ve .NET projeleri için kod dağıtımı kullanır. Kod dağıtımı, kaynak kodunuzu ZIP paketi olarak yükler. Bunun yerine kapsayıcı tabanlı bir proje oluşturmak için --deploy-mode container belirtin:

azd ai agent init --deploy-mode container

Önceden oluşturulmuş bir kapsayıcı görüntüsünü dağıtmak için --image ve --agent-name belirtin. Bu seçenek şablon ve dil seçimi, kod iskelesi, Dockerfile oluşturma ve Azure Container Registry kurulumu atlar.

azd ai agent init --agent-name my-agent --image myregistry.azurecr.io/my-agent:v1

Şablonlara etkileşimsiz olarak göz atma

İskelet oluşturmadan önce kataloğu incelemek veya azd ai agent init öğesini bir betikten çalıştırmak için kataloğu listeleyin:

# Everything in the catalog
azd ai agent sample list

# Just the featured Python agent samples
azd ai agent sample list --featured-only --language python --type agent

# Full azd templates only, as JSON for scripting
azd ai agent sample list --type azd --output json

Her öğe, iskeletini oluşturmak istediğiniz dizine kopyalayıp çalıştırdığınız, çalıştırılmaya hazır bir initCommand içerir.

Tip

Bir örneği farklı bir Foundry aracısı kimliği altında yeniden kullandığınızda, üzerine yazılan adın örnek varsayılan adıyla aynı olmaması için --agent-name <new-name> değerini geçirin.azd ai agent initazure.yaml

Mevcut koddan başlatma

Mevcut Python veya .NET aracı kodunuz varsa kodunuzu içeren dizinin içinde komutunu çalıştırınazd ai agent init:

cd my-agent/
azd ai agent init

CLI, mevcut dosyaları algılar ve kodunuzun üzerine yazmadan bunların çevresinde bir azure.yaml hizmet girişi oluşturur. Kapsayıcı dağıtımı için bir Dockerfile daha ekler. Altyapı, daha sonra kod olarak altyapı biçiminde dışa aktarmadığınız sürece varsayılan olarak Bicep’siz kalır.

Aracı kodunuz barındırılan aracı çalışma zamanı sözleşmesini karşılamalıdır:

  • 8088 numaralı bağlantı noktasını dinleyin.
  • GET /readiness konumunda bir sağlık denetimi sunun.
  • Desteklenen protokollerden birini (responses veya invocations) işleyebilir.

Kodunuz bu protokollerden birini zaten desteklemiyorsa, Foundry protokolü ile ajanınızın mantığı arasında çeviri yapan hafif bir SDK sarmalayıcısı olan bir protokol bağdaştırıcısı ekleyin.

Var olan azd bir projeye aracı eklemek için projeyi init algılar ve var olan azure.yamlprojenize yeni bir hizmet girişi ekler. Bir alt dizin belirtmek için kullanın --src :

azd ai agent init --src src/my-agent

Mevcut bir Foundry projesine bağlanma

aracılığıyla azdmevcut bir Dökümhane projesini yönetmek için sihirbazı çalıştırın ve var olan bir projeye bağlanma seçeneğini belirleyin. Ayrıca projenin Azure kaynak kimliğini doğrudan sağlayarak etkileşimli seçimi atlayabilirsiniz:

azd ai agent init --project-id /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}

Proje kimliğini bulmak için Foundry portalını açın, Yönet>Proje ayrıntıları'na gidin ve Kaynak Kimliği değerini kopyalayın.

Warning

Mevcut bir projeyi --project-id ile başlattığınızda, araçlar yeni bir proje oluştururken gerçekleştirdiği otomatik rol atamalarını atlar. Gerekli rollerin zaten atandığından emin olun. Tam matris için bkz. Barındırılan aracı izinleri başvurusu.

Oluşturulanları gözden geçirme

Varsayılan olarak aşağıdaki init proje yapısını oluşturur. Yalnızca kapsayıcı dağıtımı için bir Dockerfile'a ihtiyacınız var:

.
|-- azure.yaml                  # Unified azd project and hosted agent configuration
|-- src/
|   \-- <agent-name>/
|       |-- Dockerfile          # Container build definition
|       \-- ...                 # Agent source code
|-- .azure/                     # Environment configuration
\-- infra/                      # Optional IaC, created when you pass --infra

Şablonlar ve örnekler, proje kök dizininde tek bir azure.yaml yayımlar. Init sırasında, azd bu dosyayı benimser veya oluşturur. Varsayılan olarak, altyapıyı çıkarmayı seçmediğiniz sürece Bicep veya Terraform dosyalarını korumanız gerekmez.

Terraform veya Bicep altyapısını seçin

Terraform ile altyapıyı yönetmek için projenizi başlatırken seçin:

azd ai agent init --infra=terraform

Altyapı ve dağıtım modu bağımsız seçeneklerdir. Terraform altyapılı kapsayıcı tabanlı bir ajan için şunu kullanın:

azd ai agent init --infra=terraform --deploy-mode container

Yeni bir proje için komut, Terraform dosyalarını infra/ altına yazar ve Terraform altyapı sağlayıcısını azure.yaml içinde yapılandırır. Mevcut bir altyapısı olan bir projede, Foundry altyapısı infra/foundry/ altında ayrı bir katman olarak oluşturulabilir. Sağlamadan önce oluşturulan yapılandırmayı gözden geçirin.

Bunun yerine Bicep'i seçmek için --infra veya kısa gösterimi olan --infra=bicep kullanın. --infra atlanması, varsayılan altyapısız iş akışını korur.

azd provision seçili altyapıyı uygular. azd deploy yine de barındırılan aracı sürümünü oluşturur; Terraform’un seçilmesi, aracı sürümünün yönetimini Terraform durumuna taşımaz.

Dosya yapısı ve özelleştirme için bkz. Barındırılan aracı altyapısı. Terraform'u bir işlem hattında kullanmadan önce Terraform CI/CD'yi ve uzak durumu yapılandırın.

İlgili içerik

  • Last updated on