Hızlı Başlangıç: İlk barındırılan aracınızı dağıtma

Bu hızlı başlangıçta, Foundry modellerini çağıran ve Foundry Aracı Hizmeti'nde Foundry araçlarını kullanan kapsayıcılı bir yapay zeka aracısı dağıtacaksınız. Örnek aracı, soruları yanıtlamak için web araması ve isteğe bağlı olarak Model Bağlam Protokolü (MCP) araçlarını kullanır. Bu işlemin sonunda, Foundry playground aracılığıyla etkileşim kurabileceğiniz çalışır durumda bir barındırılan aracınız olur. Başlamak için tercih ettiğiniz dağıtım yöntemini seçin.

Not

Çalışma zamanı davranışı: Barındırılan aracılar ölçeği sıfıra indirme işlemi kullanır. Boşta bekleyen hesaplama, yaklaşık 15 dakikalık bir hareketsizlikten sonra kaynağı serbest bırakılır ve öngörülebilir soğuk başlangıçlarla sonraki istekte otomatik olarak geri yüklenir. Oturumlar durum bilgisi vardır; her oturumun kalıcı bir dosya sistemi vardır ve 30 güne kadar devam edebilir.

Bu hızlı başlangıçta şunları yapacaksınız:

  • Foundry araçlarıyla bir aracı örnek projesi ayarlama
  • Aracıyı yerel olarak test edin
  • Foundry Agent Servisine Dağıtma
  • Oyun alanında temsilcinizle etkileşim kurun
  • Kaynakları temizleme

Önkoşullar

Başlamadan önce şunları yapmanız gerekir:

Not

Barındırılan aracılar şu anda önizleme aşamasındadır.

Gerekli İzin

Barındırılan aracılar oluşturmak ve dağıtmak için proje kapsamında Foundry Project Manager’a ihtiyacınız vardır. Bu rol hem aracı oluşturmak için veri düzlemi izinlerini hem de Platform tarafından oluşturulan aracı kimliğine Foundry Kullanıcı rolünü atama özelliğini içerir. Aracı kimliğinin, çalışma zamanında modellere ve artefaktlara erişebilmesi için proje üzerinde Foundry User rolüne sahip olması gerekir.

Önemli

Foundry RBAC rolleri yakın zamanda yeniden adlandırıldı. Foundry User, Foundry Owner, Foundry Hesabı Sahibi ve Foundry Project Manager daha önce Azure Yapay Zeka Kullanıcısı, Azure Yapay Zeka Sahibi, Azure Yapay Zeka Hesabı Sahibi ve Azure Yapay Zeka Project Yöneticisi olarak adlandırıldı. Yeniden adlandırma kullanıma sunulmaya devam ederken bazı yerlerde önceki adları görmeye devam edebilirsiniz. Rol kimlikleri ve temel izinler yeniden adlandırma ile değiştirilmez.

azd veya VS Code uzantısını kullanıyorsanız araç, aşağıdakiler dahil olmak üzere çoğu RBAC atamasını otomatik olarak işler:

Foundry Project'nin yönetilen kimliğinin kullandığınız Azure Container Registry üzerinde ACR çekme rolüne sahip olduğundan emin olun. Sahip veya "Kullanıcı Erişimi Yöneticisi" erişimini tercih ediyorsanız azd/vscode aracı da sizin için bu atamayı yapabilir. platform tarafından oluşturulan ajan kimliği için Foundry kullanıcısı (çalışma zamanı modeli ve araçlara erişim)

1. Adım: Örnek projeyi ayarlama

Uyarı

Bu belge, yeni alt yapılarda kullanılan Hosted Agent’lar içindir ve azd ai agent versiyon 0.1.27-preview veya üzerini gerektirir. Azure Container Apps kullanan eski deneyim için lütfen 0.1.25-preview'ı kullanmaya devam edin.

Azure Geliştirici CLI aracı uzantısını yükleyin ve yeni bir Barındırılan aracı projesi başlatın.

  1. Azure Geliştirici CLI'sı için ai agent uzantısını yükleyin:

    azd ext install azure.ai.agents

    Uzantının yüklü olduğunu doğrulamak için şunu çalıştırın:

    azd ext list

  2. Boş bir dizinde yeni bir Hosted ajan projesi başlatın:

    azd ai agent init

    Etkileşimli akış, aşağıdaki yapılandırmada size yol gösterir:

    • Language — Python seçin.
    • Agent Template - 'Temel aracı (Yanıtlar, Aracı Çerçevesi, Python)' öğesini seçin
    • Model Yapılandırması - Foundry'de yeni bir model dağıtmak veya mevcut bir Foundry Projesi'nden mevcut bir modeli kullanmak için seçin.
    • Azure subscription — Dökümhane kaynaklarının oluşturulmasını istediğiniz aboneliği seçin.
    • Konum — kaynaklar için bir bölge seçin.
    • Model SKU'su — Bölgeniz ve aboneliğiniz için kullanılabilir SKU'yu seçin.
    • Dağıtım adı — Model dağıtımı için bir ad girin.
    • Kapsayıcı boyutu — CPU ve bellek ayırmayı seçin veya varsayılanları kabul edin.

    Önemli

    Araçlarla bir örnek seçtiyseniz ve MCP sunucusu kullanmıyorsanız, agent.yaml dosyasında aşağıdaki satırları yorum satırı haline getirin veya kaldırın.

    - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
  value: <CONNECTION_ID_PLACEHOLDER>

    Ipucu

    CI/CD işlem hattı veya SSH oturumu gibi etkileşimli olmayan bir ortamda çalışıyorsanız --no-prompt bayrağını azd ai agent init ile kullanın. Ayrıca, etkileşimli istemlere yanıt vermek yerine tüm gerekli değerleri komut satırı bayrakları olarak sağlamanız gerekir.

  3. Gerekli Azure kaynaklarını sağlayın:

    Not

    Kaynak sağlama için Azure aboneliğinizde Contributor erişiminiz olmalıdır.

    azd provision

    Bu komut birkaç dakika sürer ve aşağıdaki kaynakları oluşturur:

    Kaynak Amaç Maliyet
    Kaynak grubu İlgili tüm kaynakları aynı alanda düzenler Maliyet yok
    Model dağıtımı Aracı tarafından kullanılan model Bkz. Dökümhane fiyatlandırması
    Dökümhane projesi Ajanınızı barındırır ve yapay zeka özellikleri sağlar. Tüketim tabanlı; bkz. Dökümhane fiyatlandırması
    Azure Container Registry Aracı kapsayıcı görüntülerinizi depolar Temel katman; bkz. ACR fiyatlandırması
    Log Analytics Çalışma Alanı Tüm günlük verilerini tek bir yerde yönetme Doğrudan maliyet yoktur. Bkz. Log Analytics maliyet
    Application Insights Ajan performansı ve günlükleri izler Kullandıkça öde; bkz. Azure İzleyici pricing
    Yönetilen kimlik Azure hizmetlerinde aracınızın kimliğini doğrular Maliyet yok

    Ipucu

    Kaynakları silmek ve ücretlendirmeyi durdurmak için bu hızlı başlangıcı tamamladığınızda komutunu çalıştırın azd down .

2. Adım: Aracıyı yerel olarak test edin

Dağıtmadan önce ajanın yerel olarak çalıştığını doğrulayın.

  1. Aracıyı yerel olarak başlatın:

    azd ai agent run

    Bu komut ortamı otomatik olarak ayarlar, bağımlılıkları yükler ve aracıyı başlatır. Aracınızı başlatmak için startupCommand içinde tanımlanan azure.yaml kullanır.

    Not

    Önizleme paketleri kurulum sırasında pip bağımlılığı sürüm çakışması uyarıları üretebilir. Bu uyarılar bloklayıcı değildir; aracı bunlara rağmen doğru şekilde başlatır ve yanıt verir.

    Aracı başlatılamadığı takdirde şu yaygın sorunları kontrol edin:

    Hata Çözüm
    AuthenticationError veya DefaultAzureCredential hata Oturumunuzu yenilemek için önce azd auth logout ardından azd auth login komutunu çalıştırın.
    ResourceNotFound Uç nokta URL'lerinizin Foundry portalındaki değerlerle eşleştiğinden emin olun.
    DeploymentNotFound Build>Dağıtımlar'da dağıtım adını kontrol edin.
    Connection refused Başka hiçbir işlemin 8088 numaralı bağlantı noktasını kullanmadığından emin olun.

  2. Ayrı bir terminalde yerel aracıya bir test iletisi gönderin.

    Yanıtlar API'sini kullanan temsilciler için yük olarak bir karakter dizisi gönderebilirsiniz:

    azd ai agent invoke --local "What is Microsoft Foundry?"

    Çağırmalar API'sini kullanan aracılar için beklenen yükü kontrol edin README.md. Örnekler genellikle bir JSON yükü gerektirir, ancak belirli bir örnek için bu örneğin içindekileri README.md gözden geçirin:

    Aracıdan bir yanıt görmelisiniz.

3. Adım: Foundry Agent Service'e Dağıtma

1. Adımda altyapıyı önceden sağladığınızdan aracı kodunuzu Azure dağıtın:

azd deploy

Aracın kapsayıcısı uzaktan oluşturulduğundan, makinenizde Docker Desktop gerekli değildir.

Not

azd deploy komutu, aracının Aracı kimliğine Azure RBAC rolleri atar. Bu rol ataması, sağlama için gereken Katkıda Bulunan rolüne ek olarak aboneliğinizde Sahip veya Kullanıcı Erişimi Yöneticisi izinleri gerektirir.

Uyarı

Barındırılan aracınız dağıtımda olduğu sürece ücrete tabi olur. Testi tamamladıktan sonra kaynakları silmek ve ücretleri durdurmak için Kaynakları temizleme'yi tamamlayın.

Tamamlandığında, sonuç Aracı Oyun Alanı'na ve program aracılığıyla aracı çağırmak için son noktaya bir bağlantı gösterir.

Deploying services (azd deploy)

  (✓) Done: Deploying service af-agent-with-foundry-tools
  - Agent playground (portal): https://ai.azure.com/nextgen/.../build/agents/af-agent-with-foundry-tools/build?version=1 
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/af-agent-with-foundry-tools/versions/1

Önemli

VS Code'da Microsoft Foundry Toolkit uzantısının ve Foundry uzantısının prelease sürümünü kullandığınızdan emin olun.

VS Code uzantıları sayfanızda Foundry Toolkit uzantısı ve Foundry uzantısı'nı seçin ve yayın öncesi sürüme geçin.

1. Adım: Dökümhane projesi oluşturma

Yeni bir Microsoft Foundry Project kaynağı oluşturmak için VS Code'daki Microsoft Foundry Toolkit uzantısını kullanın.

  1. Komut Paleti'ni (Ctrl+Shift+P) açın ve Microsoft Foundry: Create Project öğesini seçin.

  2. Azure aboneliğinizi seçin.

  3. Yeni bir kaynak grubu oluşturun veya mevcut bir kaynak grubunu seçin.

  4. Dökümhane Projesi kaynağı için bir ad girin.

Proje oluşturma işlemi tamamlandıktan sonra sonraki adıma geçin ve bir model dağıtın.

2. Adım: Model dağıtımı

Bir modeli Foundry'ye dağıtmak için VS Code'daki Microsoft Foundry Toolkit uzantısını kullanın.

  1. Komut Paleti'ni (Ctrl+Shift+P) açın ve Microsoft Döküm: Model Kataloğunu Aç'i seçin.

  2. Model kataloğuna göz atın veya gpt-4.1 araması yapın ve Dağıt düğmesini seçin.

  3. Model dağıtımı sayfasında Microsoft Foundry'ye Dağıt düğmesini seçin.

Model başarıyla dağıtıldıktan sonra sonraki adıma geçin ve Barındırılan Aracı projesi oluşturun

3. Adım: Bir Barındırılan Aracı Projesi Oluşturun

Yeni bir Barındırılan aracı projesinin iskelesini oluşturmak için VS Code'daki Microsoft Foundry Toolkit uzantısını kullanın.

  1. Komut Paleti'ni (Ctrl+Shift+P) açın ve Microsoft Foundry: Yeni Barındırılan Aracı oluştur'i seçin.

  2. Kullanmak istediğiniz Çerçeveyi seçin.

  3. Python veya C# olarak bir programlama dili seçin.

  4. Yanıtlar API'si veya Invoke API'si seçin.

  5. Kullanmak istediğiniz örnek kodu seçin.

  6. Proje dosyalarınızın kaydedilmesini istediğiniz klasörü seçin.

  7. Barındırılan aracı için bir ad girin.

Etkin çalışma alanı olarak yeni aracı proje klasörüyle yeni bir VS Code penceresi başlatılır.

4. Adım: Bağımlılıkları yükleme

Proje bağımlılıklarını yalıtmak için bir sanal ortam kullanmanız önerilir:

macOS/Linux:

python -m venv .venv
source .venv/bin/activate

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Bağımlılıkları Yükleme

Pip kullanarak gerekli Python bağımlılıklarını yükleyin:

pip install -r requirements.txt

Gerekli paketlerin listesi için requirement.txt bakın.

5. Adım: Aracıyı yerel olarak test edin

Dağıtmadan önce ajanınızı çalıştırın ve test edin.

Hata ayıklamayı başlatmak için VS Code'da F5 tuşuna basın. Alternatif olarak VS Code hata ayıklama menüsünü de kullanabilirsiniz:

  1. Çalıştır ve Hata Ayıkla görünümünü açın (Ctrl+Shift+D / Cmd+Shift+D)
  2. Açılan listeden "Yerel İş Akışı HTTP Sunucusunda Hata Ayıkla" seçeneğini belirleyin
  3. Yeşil Hata Ayıklamayı Başlat düğmesine tıklayın (veya F5 tuşuna basın)

Bu işlem şunları yapacak:

  1. Hata ayıklama etkinken HTTP sunucusunu başlatma
  2. Etkileşimli test için Foundry Toolkit Aracı Denetçisi'ni açın
  3. Kesme noktaları ayarlamanıza ve iş akışını incelemenize olanak tanır

2. Seçenek: Terminalde Çalıştır

HTTP sunucusu olarak çalıştır (varsayılan):

python main.py

Bu işlem, Barındırılan aracıyı http://localhost:8088/ üzerinde yerel olarak başlatır.

PowerShell (Windows):

$body = @{
   input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under `$200 per night"
    stream = $false
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"

Bash/curl (Linux/macOS):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'

Aracı, ölçütlerinizle eşleşen uygun otelleri aramak için get_available_hotels aracını kullanacaktır.

6. Adım: Foundry Ajans Servisine Dağıtma

Ajanınızı doğrudan VS Code'dan dağıtın.

  1. Komut Paleti'ni (Ctrl+Shift+P) açın ve Microsoft Foundry: Barındırılan Aracı dağıtma'i seçin.

  2. "Varsayılan ACR" seçeneğini belirleyin

  3. Barındırılan Aracı kapsayıcısı için CPU ve Bellek yapılandırmasını seçin.

Soldaki simgeyi seçerek Microsoft Foundry Toolkit gezginine geçin. Aracı, dağıtım tamamlandıktan sonra Barındırılan Aracılar (Önizleme) ağaç görünümü kenar çubuğunda görünür.

Ajanınızı doğrulayın ve test edin

Dağıtım tamamlandıktan sonra aracınızın çalıştığını doğrulayın.

Agent durumunu kontrol et

Ajanın çalıştığını onaylamak için durumunu denetleyin.

  1. Barındırılan Aracılar (Önizleme) ağaç görünümünden Barındırılan aracınızı seçin.

  2. Az önce dağıtılan aracıyı seçin

Durum, Ayrıntı sayfasında Kapsayıcı Ayrıntıları bölümü altında gösterilir.

VS Code kullanarak oyun alanında test edin

MICROSOFT Foundry Toolkit for VS Code, temsilcinizle sohbet etmek ve etkileşime geçmek için tümleşik bir oyun alanı içerir.

  1. Barındırılan Aracılar (Önizleme) ağaç görünümünden Barındırılan aracınızı seçin.

  2. Playground seçeneğini seçin, bir ileti yazın ve aracınızı test etmek için gönderin.

Aracı durumunu doğrulama

Dağıtılan aracınızın durumunu denetleyin:

azd ai agent show

Çıktıyı tablo biçiminde görüntülemek için:

azd ai agent show --output table

Projenizde birden çok aracı hizmeti varsa, aracı adını konumsal bağımsız değişken olarak belirtin:

azd ai agent show [agent-name]

Ipucu

[agent-name] bölümünün altındaki dosyada azure.yaml bulabilirsinizservices:.

Dağıtılan ajanı test edin

Önceden kullanılan aynı invoke komutunu kullanarak, ancak --local bayrağı olmadan dağıtılan aracınıza bir test iletisi gönderin.

Yanıtlar API'sini kullanan temsilciler için yük olarak bir karakter dizisi gönderebilirsiniz:

azd ai agent invoke "Hello"

Birkaç saniye sonra aracıdan bir yanıt görmeniz gerekir.

Aracı günlüklerini görüntüle

Ajanınızın canlı günlüklerini izleyin.

# Fetch recent container console logs
azd ai agent monitor

# Fetch the last N lines of console logs
azd ai agent monitor --tail 20

# Fetch system event logs (container start and stop events)
azd ai agent monitor --type system

# Stream session logs in real time
azd ai agent monitor --session <session-id> --follow

Projenizde birden çok aracı hizmeti varsa, aracı adını konumsal bağımsız değişken olarak belirtin:

azd ai agent monitor [agent-name] --follow

Not

Platform, aracı kapsayıcınıza otomatik olarak bir Application Insights bağlantı dizesini ortam değişkeni olarak ekler ve OpenTelemetry izlemesini varsayılan olarak etkinleştirir. Dağıtılmış izlemeleri, istekleri ve bağımlılıkları görüntülemek için, Azure portalında kurulum sırasında sağlanan Application Insights kaynağını açın ve InvestigateTransaction search veya Performance. Canlı konsol günlükleri için kullanın azd ai agent monitor .

Foundry oyun alanında test edin

Foundry portalında ajana gidin.

  1. Foundry portalını açın ve Azure hesabınızla oturum açın.

  2. Son projeler listesinden projenizi seçin veya bulmak için Tüm projeler'i seçin.

  3. Sol gezinti bölmesinde Oluştur'a seçerek menüyü genişletin ve ardından Aracılar'ı seçin.

  4. Ajanlar listesinde kurduğunuz ajanı bulun (kurulumdaki ajan adıyla eşleşir).

  5. Ayrıntılar sayfasını açmak için aracı adını seçin, ardından üst araç çubuğunda Oyun alanında aç'ı seçin.

  6. Sohbet arabiriminde"Microsoft Dökümhane nedir?" gibi bir test iletisi yazın ve Enter tuşlarına basın.

  7. Aracın, web arama sonuçlarından elde edilen bilgilerle yanıt verdiğini doğrulayın. Aracı dış kaynakları sorgularken yanıt birkaç saniye sürebilir.

Ipucu

Oyun alanı yüklenmiyorsa veya aracı yanıt vermiyorsa, yukarıda açıklanan Kapsayıcı Ayrıntıları sayfasını kullanarak aracının durumunu Started kontrol ettiğinizden emin olun.

Kaynakları temizleme

Ücretlerden kaçınmak için, işiniz bittiğinde kaynakları silin.

Uyarı

Bu komut Dökümhane projesi, model dağıtımları, Container Registry, Application Insights ve Barındırılan aracınız dahil olmak üzere kaynak grubundaki tüm Azure kaynaklarını kalıcı olarak siler. Bu eylem geri alınamaz. Başka kaynaklar içeren mevcut bir kaynak grubu kullanıyorsanız dikkatli olun; azd down yalnızca bu hızlı başlangıç tarafından oluşturulan kaynakları değil gruptaki her şeyi kaldırır.

Silinecekleri önizlemek için komutunu çalıştırın down :

azd down

Tamamlandığında, azd silinecek tüm kaynakları gösterir ve onaylamanızı ister. yes Devam etmek için seçin veya no iptal edin.

Temizleme işlemi yaklaşık 2-5 dakika sürer.

Uyarı

Kaynakların silinmesi, Foundry projesi, Container Registry, Application Insights ve Barındırılan aracınız dahil olmak üzere bu hızlı başlangıçta oluşturulan tüm Azure kaynaklarını kalıcı olarak kaldırır. Bu eylem geri alınamaz.

Kaynaklarınızı silmek için Azure portalını açın, kaynak grubunuza gidin ve tüm kapsanan kaynaklarla birlikte silin.

Kaynakların silindiğini doğrulamak için Azure portalını açın, kaynak grubunuz gidin ve kaynakların artık görünmediğini onaylayın. Kaynak grubu boşsa, grubu da silebilirsiniz.

Sorun giderme

Sorunlarla karşılaşırsanız yaygın sorunlar için şu çözümleri deneyin:

Sorunu Çözüm
SubscriptionNotRegistered Hata Sağlayıcıları kaydetme: az provider register --namespace Microsoft.CognitiveServices
AuthorizationFailed sağlama sırasında Aboneliğinizde veya kaynak grubunuzda Katkıda Bulunan rolü isteyin.
Ajan yerel olarak başlamıyor Ortam değişkenlerinin ayarlandığını ve kimlik bilgilerini yenilemek için çalıştırıldığından az login emin olun.
AcrPullUnauthorized Hata Kapsayıcı kayıt defterinde projenin yönetilen kimliğine AcrPull rolü verin.

Barındırılan aracı dağıtımında yer alan tüm izinler ve rol atamaları hakkında kapsamlı ayrıntılar için bkz. Barındırılan aracı izinleri başvurusu.

Sorunu Çözüm
azd ai agent init Başarısız 1.24.0+ sürümünü doğrulamak için komutunu çalıştırın azd version . winget upgrade Microsoft.Azd (Windows) veya brew upgrade azd (macOS) ile güncelleştirin. Aracı uzantısının azd ext list ile yüklendiğini doğrulayın. uzantınızın azd ext upgrade azure.ai.agents sürüm 0.1.27-preview veya daha yeni bir sürüm olduğundan emin olun.

Ajanınızın kapsayıcı günlüklerini görüntüleyin

Sorunları gidermek için kapsayıcının konsolunu ve sistem günlüklerini de kontrol edebilirsiniz.

  1. Barındırılan Aracılar (Önizleme) ağaç görünümünden Barındırılan aracınızı seçin.

  2. Barındırılan temsilcinizin "Playground" sekmesini seçin

  3. Oturum ayrıntılarındaki "Günlükler" bölümünü seçin.

Ajanınızın oturum dosyalarını görüntüleyin

ADC tabanlı aracınızın giriş dizininde depolanan tüm dosyaları görüntüleyebilirsiniz

  1. Barındırılan Aracılar (Önizleme) ağaç görünümünden Barındırılan aracınızı seçin.

  2. Barındırılan temsilcinizin "Playground" sekmesini seçin

  3. Oturum ayrıntılarındaki "dosyalar" bölümünü seçin.

Geçerli klasör içinde dosyaları indirebilir, yükleyebilir ve klasörler oluşturabilirsiniz. Bir klasöre tıklamak o klasöre girmenizi sağlarken, üst gezinme çubuğuna tıklamak önceki klasöre dönmenizi sağlar.

Sorunu Çözüm
Uzantı bulunamadı VS Code Marketplace'tan Microsoft Foundry Toolkit for VS Code uzantısını yükleyin.

Öğrendiklerin

Bu hızlı başlangıçta şunları yapacaksınız:

  • Foundry araçlarıyla (web araması ve MCP) barındırılan aracı örneği oluşturma
  • Ajanı yerel olarak test etti
  • Foundry Aracı Servisine Dağıtıldı
  • Foundry oyun alanında ajanınızı doğruladınız

Sonraki adımlar

Artık ilk Barındırılan aracınızı dağıttığınıza göre şunları nasıl yapacağınızı öğrenin:

Barındırılan aracı yaşam döngüsünü yönetme

Ajanınızı ek yeteneklerle özelleştirin.

Araç kataloğu makalesinde kullanılabilir araçların tam listesini görebilirsiniz.

İlgili içerik

  • Last updated on