Kaynak koddan barındırılan aracı dağıtma

Bu makalede, bir kapsayıcı görüntüsü oluşturmadan veya göndermeden Python veya .NET kaynak kodundan Foundry Agent Service'te Hosted aracısı nasıl dağıtılacağı gösterilmektedir. Kodunuzun bir .zip sürümünü (ve isteğe bağlı olarak bağımlılıklarınızı) yüklersiniz; Agent Service ise bunu olduğu gibi çalıştırır veya bağımlılıklarınızı sizin için bulutta derler.

Tip

Çoğu senaryo için Azure Developer CLI (azd) veya VS Code için Foundry Toolkit ile dağıtın. Bu araçlar sizin için zor işi yapar: kaynağınızı paketler, yükler, active durumunu düzenli olarak denetler ve rol tabanlı erişim denetimini otomatik olarak yapılandırır. Başlamak için Hızlı Başlangıç: İlk barındırılan aracınızı dağıtma kılavuzunu izleyin ve dağıtım yöntemi sorulduğunda Kod (veya Kaynak Kodu (ZIP Yükleme)) seçeneğini belirleyin.

Kendi uygulamalarınızda Python SDK veya .NET SDK'sından veya özel araçlar, dil-bağımsız otomasyon veya mevcut sürekli teslim sistemleriyle tümleştirme için doğrudan REST API üzerinden program aracılığıyla kaynak kod aracıları dağıtmanız gerektiğinde bu makaledeki SDK ve REST yordamlarını kullanın. Bu makalede aşağıdaki görevleri tamamlaacaksınız:

  • Bir bağımlılık çözümleme modu seçin ve kaynağınızı paketle.
  • Aracı oluşturun, active öğesine ulaşmasını bekleyin ve çağırın.
  • Dağıtılan aracı için günlükleri güncelleme, sürümünü görüntüleme, indirme ve akışını izleme.

Çalışma zamanı görüntüsünün tam denetimine ihtiyacınız varsa veya zaten çalışan bir Dockerfile'ınız varsa kapsayıcı tabanlı yolu kullanın: Barındırılan aracı dağıtma.

Kaynak kodu paketlemek ve dağıtmak için GitHub Copilot gibi bir kodlama aracısı kullanırsanız, Microsoft Döküm Becerisi projenizi hazırlamaya ve gerekli azd, SDK veya REST adımlarını izlemenize yardımcı olabilir.

Prerequisites

  • pip kaynağınızı yerel olarak paketlemek için Python 3.13 veya sonraki bir sürümünü kullanarak.

  • azure-ai-projects sürümü 2.2.0 veya sonraki ve azure-identity paketleri.

    pip install "azure-ai-projects>=2.2.0" azure-identity

Desteklenen çalışma zamanları

Aracı code_configuration.runtime tanımındaki alan aşağıdaki değerleri kabul eder. Zip'inizdeki ikili dosyalarla eşleşen çalışma zamanını (Python için Linux x86_64 tekerlekleri) veya .NET için TargetFramework çıkışınızın dotnet publish seçin.

Dil Çalışma zamanı değerleri
Python python_3_13, python_3_14
.NET dotnet_10

Dil sürümü destek ilkesi

Aracı Hizmet çalışma zamanı, her code_configuration.runtime değeri için platform tarafından oluşturulmuş kapsayıcı görüntüsünü içerir. Dağıtılan aracılarınızın tam olarak desteklenmesi için Foundry, barındırılan aracı dili desteğini her dil için kullanım süresi sonu desteğiyle uyumlu hale getirir. Destek, dil sürümünün topluluk destek sonu tarihinde sona erer. Microsoft, platform kısıtlamaları (örneğin altta yatan taban görüntü) gerektiriyorsa bir code_configuration.runtime değerini daha erken kullanımdan kaldırabilir.

Yukarı yönlü destek bitiş takvimleri için bkz:

Kullanımdan kaldırma aşaması

Dil kullanım süresi sonu tarihinden sonra, kullanımdan kaldırılan çalışma zamanı değerini kullanan barındırılan aracıları oluşturmaya, güncelleştirmeye ve çalıştırmaya devam edebilirsiniz. Ancak bu aracılar, code_configuration.runtime için geçerli bir değer ayarlayıp desteklenen bir çalışma zamanına yükseltip yeniden dağıtana kadar destekten, yeni özelliklerden veya güvenlik yamalarından yararlanamaz.

Gerekli izinler

Barındırılan bir aracıyı dağıtabilmek için proje kapsamında Foundry Project Manager rolüne sahip olmanız gerekir. Bu rol, aracı oluşturmak ve güncelleştirmek için veri düzlemi izinlerinin yanı sıra gerekirse platform tarafından oluşturulan aracı kimliği için rol atamaları oluşturma olanağı verir. İlgili izinlerin ayrıntılı dökümü için Barındırılan aracı izinleri başvuru bilgileri bölümüne bakın.

Important

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.

Aracınız, kullanıcı kimliğinizden ayrı olan, platformun atadığı bir yönetilen kimlik olarak çalışır. Bu kimlik, varsayılan olarak proje uç noktası ve oturum depolama alanı aracılığıyla model çıkarıma erişebilir. Dış kaynaklar için (örneğin, size ait Azure Depolama), RBAC rollerini aracının Microsoft Entra kimliğine manuel olarak atayın. Daha fazla bilgi için Varsayılanların ötesinde aracı erişimi konusuna bakın.

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

Her kaynak kod dağıtımı aynı sırayı izler: paketle -> oluştur veya güncelle ->active olana kadar sorgula -> çağır. Kaynak kodu yolunda, ajan tanımında code_configuration kullanılır. Görüntü tabanlı yol bunun yerine container_configuration kullanır. Bu iki seçenek tek bir sürümde birbirini dışlar.

İş akışınıza uygun yolu seçin. Emin değilseniz, Azure Geliştirici CLI veya VS Code ile başlayın; çoğu müşteri için önerilen yoldur.

Yol En iyi kullanım alanları Ambalaj
Azure Developer CLI veya VS Code Çoğu dağıtım; ilk dağıtımlar ve en hızlı iç döngüler dahil. Araçlar, ZIP dosyasını sizin için oluşturur ve yükler.
Python SDK'sı Python uygulamalarından veya otomasyon yoluyla programatik dağıtım. Zip'i oluşturursunuz; SDK bunu karşıya yükler.
.NET SDK .NET uygulamalardan veya otomasyondan programlı dağıtım. SDK sizin için bir klasör sıkıştırıyor.
JavaScript/TypeScript SDK'sı Node.js uygulamalarından veya otomasyon yoluyla dağıtım. Python veya .NET kaynak kodu dağıtılır; Node.js için barındırılan bir çalışma zamanı yoktur. Zip'i oluşturursunuz; SDK bunu karşıya yükler.
REST API Özel araçlar, dil-bağımsız otomasyon ve CD sistemleri. Zip'i oluşturur ve çok parçalı isteği gönderirsiniz.

Bağımlılıkların nasıl çözümleneceğini seçme

Başlamadan önce için code_configuration.dependency_resolutionbir değer seçin. Bu seçim, ZIP dosyasına ne koyduğunuzu etkiler.

Değer Behavior Şu durumlarda kullanın:
remote_build Aracı Hizmeti, requirements.txt (Python) bağımlılıklarını yükler veya sağlama sırasında proje dosyasını (.NET) geri yükler. Küçük bir yükleme boyutu ve en basit iç döngüyü istiyorsunuz. İlk kez kullananlar için önerilir.
bundled ZIP dosyası olduğu gibi çalıştırılır. Önceden oluşturulmuş Linux bağımlılıklarını packages/ (Python) veya dotnet publish çıkışında (.NET) gönderirsiniz. Yeniden üretilebilir derlemelere ihtiyacınız var, bağımlılıklarınız özel ya da yalnızca wheel paketlerinden oluşuyor veya projeniz sunucu tarafında sorunsuz biçimde geri yüklenmiyor.

Paketlenmiş mod için bkz. Yerel derleme komutları için zip'i el ile paketleme .

Özel sanal ağlar için güvenlik duvarı gereksinimleri

Projenizin güvenliğini özel bir sanal ağ ile sağlarsanız, dağıtımdan önce ağ ilkenizi aşağıdaki uç noktalara giden bağlantılara izin verecek şekilde güncelleştirin.

Tüm kaynak kod dağıtımları için dışa doğru erişim gerekir:

  • mcr.microsoft.com
  • *.login.microsoft.com

Ağ yapılandırması için bkz. Sanal ağda barındırılan aracı dağıtma.

Azure Geliştirici CLI veya VS Code kullanarak dağıtma

Azure Developer CLI (azd) ve VS Code için Foundry Toolkit, uçtan uca kaynak kodu dağıtım yaşam döngüsünü otomatikleştirir—kaynağınızı bir ZIP dosyası olarak paketler, SHA-256 değerini hesaplar, yükler, active durumunu düzenli olarak denetler ve rol tabanlı erişim kontrolünü sizin için yapılandırır. Bu araçlar çoğu müşteri için önerilen yoldur ve en hızlı iç döngü.

Adım adım açıklamalı kılavuz için Hızlı Başlangıç: İlk barındırılan aracınızı dağıtma bölümüne bakın. Hızlı başlangıç kılavuzu sizden bir dağıtım yöntemi seçmenizi istediğinde Kod (veya Kaynak Kodu (ZIP yükleme)) seçin.

Kaynak kodu dağıtımı seçme

Etkileşimli olarak çalıştırdığınızda azd ai agent init , araç sizden bir dağıtım modu seçmenizi ister. Kapsayıcı görüntüsü oluşturmak yerine kaynaktan ZIP olarak dağıtım yapmak için kod'u seçin. Kod dağıtımı, Python ve .NET için barındırılan aracılar için varsayılan moddur. VS Code için Foundry Araç Seti de aynı şekilde sizden dağıtım yöntemini ister.

Kaynak kodu dağıtımını etkileşimsiz olarak seçmek için, örneğin bir CI/CD işlem hattında, --deploy-mode code parametresini belirtin. Bu mod, --runtime ve --entry-point gerektirir ve isteğe bağlı olarak --dep-resolution için remote_build (varsayılan) veya bundled değerini kabul eder:

azd ai agent init --no-prompt --project-id "<project-resource-id>" \
  --deploy-mode code --runtime python_3_13 --entry-point main.py

Başlatma işleminden sonra azd, kaynak kod dağıtım ayarlarını codeConfiguration içindeki azure.ai.agent hizmetinde bulunan azure.yaml alanına yazar:

services:
  my-agent:
    host: azure.ai.agent
    project: src/my-agent
    kind: hosted
    codeConfiguration:
      runtime: python_3_13
      entryPoint:
        - python
        - main.py
      dependencyResolution: remote_build

Sağlamak ve dağıtmak için komutunu çalıştırın azd up . --deploy-mode container ifadesini yalnızca bunun yerine bir kapsayıcı görüntüsü oluşturmak veya ona başvurmak istediğinizde kullanın.

Kendi uygulamanızdan program aracılığıyla dağıtmanız veya mevcut araçlarla tümleştirmeniz gerektiğinde aşağıdaki bölümlerdeki SDK veya REST yollarını kullanın.

Kaynak koddan dağıtım

Dilinizi veya arabiriminizi seçin. Her sekme aynı yaşam döngüsünü izler: aracıyı oluşturun, active değerine ulaşana kadar yoklayın, ardından aracıyı çağırın ve dağıtılan kodu indirin.

Kaynak kodu aracılarını kendi uygulamalarınızdan veya otomasyonunuzdan dağıtmak için Python SDK'sını kullanın. Zip'i kendiniz derleyip baytlarını ve SHA-256'sını SDK'ya geçirirsiniz; bu da bunu karşıya yükler ve REST API ile aynı oluşturma, yoklama, çağırma ve indirme işlemlerini kullanıma sunar. Kod dağıtımı için 2.2.0 veya sonraki bir sürüm gerekir azure-ai-projects .

ZIP dosyasını oluştur

Python SDK, oluşturduğunuz ZIP dosyasını yükler. Zip'i el ile paketleme bölümünde açıklanan düzen ve bağımlılık çözümleme kurallarını kullanın. Asgari remote_build paket, kök dizininde main.py ve requirements.txt bulunan düz bir ZIP arşividir.

Ajanı oluşturun

import hashlib
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    CodeConfiguration,
    HostedAgentDefinition,
    ProtocolVersionRecord,
)
from azure.identity import DefaultAzureCredential

# Format: "https://<account>.services.ai.azure.com/api/projects/<project>"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "my-code-agent"
ZIP_PATH = Path("agent-code.zip")

code_zip_bytes = ZIP_PATH.read_bytes()
code_zip_sha256 = hashlib.sha256(code_zip_bytes).hexdigest()

credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
)

created = project.agents.create_version_from_code(
    agent_name=AGENT_NAME,
    definition=HostedAgentDefinition(
        cpu="1",
        memory="2Gi",
        code_configuration=CodeConfiguration(
            runtime="python_3_13",
            entry_point=["python", "main.py"],
            dependency_resolution="remote_build",
        ),
        protocol_versions=[
            ProtocolVersionRecord(protocol="responses", version="2.0.0")
        ],
        environment_variables={"AZURE_AI_MODEL_DEPLOYMENT_NAME": "gpt-5.4-mini"},
    ),
    code=(ZIP_PATH.name, code_zip_bytes, "application/zip"),
    code_zip_sha256=code_zip_sha256,
    description="Hello-world code agent",
)
print(f"Created version: {created.version}")

Çağırmalar protokolü için girdisini protocol_versions olarak ProtocolVersionRecord(protocol="invocations", version="2.0.0")ayarlayın. Çağırmalar (WebSocket) protokolü için kullanın ProtocolVersionRecord(protocol="invocations_ws", version="2.0.0"). bundled modu için dependency_resolution="bundled" olarak ayarlayın ve ZIP dosyasına önceden derlenmiş bağımlılıkları ekleyin. Daha fazla bilgi için bkz. Yerel olarak Linux bağımlılıkları oluşturma.

Etkin olup olmadığını denetle

import time

while True:
    version = project.agents.get_version(
        agent_name=AGENT_NAME, agent_version=created.version
    )
    status = version["status"]
    print(f"Status: {status}")
    if status == "active":
        break
    if status == "failed":
        raise RuntimeError(f"Provisioning failed: {version.get('error')}")
    time.sleep(5)

Durum değerlerinin tam listesi ve başarısızlık durumunda nesnesinin nasıl okunacağı için error bölümüne bakın.

Aracıyı çağırma

Sürüm active düzeyine ulaştıktan sonra, bir OpenAI istemcisini ajan uç noktasına bağlayın ve onu çağırın. Bu örnekte Yanıtlar protokolü kullanılır:

openai_client = project.get_openai_client(agent_name=AGENT_NAME)

response = openai_client.responses.create(input="Hello! What can you do?")
print(response.output_text)

Çağırmalar protokolü için, aracıyı çağırma bölümünde gösterildiği gibi çağırma uç noktasını doğrudan taşıyıcı belirteci ile çağırın.

Dağıtılan zip'i indirme

Zip’i indirip SHA-256 değerini yüklediğiniz değerle karşılaştırarak tam olarak neyin dağıtıldığını doğrulayın:

import hashlib
from pathlib import Path

out_path = Path(f"{AGENT_NAME}-{created.version}.zip")
sha = hashlib.sha256()
with open(out_path, "wb") as f:
    for chunk in project.agents.download_code(
        agent_name=AGENT_NAME, agent_version=created.version
    ):
        f.write(chunk)
        sha.update(chunk)

print(f"Downloaded {out_path} (matches upload: {sha.hexdigest() == code_zip_sha256})")

Tam bir çalıştırılabilir örnek için bkz. Python barındırılan aracı örnekleri.

Zip'i el ile paketleme

azd kullanıyorsanız, bu bölümü atlayın—azd ZIP dosyasını sizin için oluşturur. REST API kullanıyorsanız, paketlenmiş bağımlılık çözümlemesine geçerseniz veya karşıya yükleme içeriği üzerinde tam denetime ihtiyacınız varsa bunu okuyun.

ZIP dosyası kök dizinde düz yapıda olmalıdır; üst düzeyde sarmalayıcı bir klasör olmamalıdır.

Temsilcinizin diline ait sekmeyi seçin.

Python düzeni (uzak derleme modu)

Hizmet, bağımlılıkları bulutta requirements.txt konumundan yükler.

agent-code.zip
+-- main.py
+-- requirements.txt

Python düzeni (paketlenmiş mod)

packages/ içinde önceden derlenmiş Linux bağımlılıkları sunarsınız.

agent-code.zip
+-- main.py                    # entry point
+-- requirements.txt
+-- packages/                  # extracted modules (not raw .whl files)
    +-- azure/identity/__init__.py
    +-- requests/__init__.py

Yerel olarak Linux bağımlılıkları oluşturma (paketlenmiş, Python)

manylinux2014_x86_64’in Windows veya macOS üzerinden bile Linux wheel paketlerini indirebilmesi için pip platform etiketini kullanın.

Bash

pip install -r requirements.txt \
    --target packages/ \
    --platform manylinux2014_x86_64 \
    --python-version 3.13 \
    --implementation cp \
    --only-binary=:all:

zip -r agent-code.zip main.py requirements.txt packages/

PowerShell / Windows cmd

pip install -r requirements.txt --target packages --platform manylinux2014_x86_64 --python-version 3.13 --implementation cp --only-binary=:all:

tar -a -c -f agent-code.zip main.py requirements.txt packages

--only-binary=:all: tekerlekleri zorlar (kaynak derlemesi yoktur). --python-version, aracı tanımındaki runtime değeriyle eşleşmelidir.

Warning

session_creation_failed veya ModuleNotFoundError neden olan yaygın paketleme hataları:

  • Kaynağı bir klasör içine alma (kök dizinde my-agent/main.py yerine main.py).
  • Ayıklanan modüller yerine .whl içinde ham packages/ dosyaların dahil edilmesi.
  • Linux çalışma zamanı için Windows ikili dosyalarını (.pyd, .dll) paketleme.

Limits

Limit Değer
En büyük ZIP boyutu (çok parçalı yükleme) 250 MB

Desteklenen cpu ve memory birleşimleri için bkz. Korumalı alan boyutları.

Troubleshooting

Belirti Olası neden Düzelt
401 Unauthorized Eksik veya yanlış kapsam belirteci --resource https://ai.azure.com ile bir belirteç alın.
403 Forbidden Çağıran kullanıcının projede Rol Tabanlı Erişim Denetimi bulunmuyor. Proje düzeyinde Foundry Agent Consumer (yalnızca çağırma için) veya Foundry User (aynı zamanda geliştirme için) atayın.
409 conflict Oluşturulduğunda (Agent '<name>' already exists) Ajan adı zaten var Güncelleştir 'i (POST /agents/{name}) kullanın veya yeni bir ad seçin.
400 bad_request (CPU and Memory must be specified as a valid resource tier) oluşturma veya güncelleme sırasında cpu / memory desteklenen katmanlardan biri değildir cpu arasından geçerli bir çift seçerek memory ve değerlerini buna ayarlayın.
400 bad_request (Agent version is still being provisioned) çağrısında Yeni bir sürümün dağıtımı sürüyor ve aktif sürüm yerine geçiriliyor status olana kadar sürümü yoklayın, ardından yeniden deneyin.
424 session_not_ready çağırma sırasında Kapsayıcı başlatıldı ancak /readiness zaman aşımı süresi içinde HTTP 200 döndürmedi Günlükleri :logstream ile akış olarak izleyin, hazırlık yoklamasını veya başlangıç hatasını düzeltin, yeniden dağıtım yapın.
409 conflict DELETE aracısında (Agent has active sessions) Açık oturumlar silme işlemini engeller Oturumların boşta kalmasını bekleyin veya oturumları kademeli olarak silmek için &force=true ekleyin.
Sürüm creating içinde takılı kaldı (>10 dk, uzak yapı) Sunucu derlemesi başarısız oldu veya çözümlenemedi requirements.txt dependency_resolution: bundled öğesine geçin ve yerel olarak ön derleme yapın.
Özel bir sanal ağda dağıtım başarısız oluyor Gerekli çıkış uç noktaları güvenlik duvarı tarafından engelleniyor Özel sanal ağlar için Güvenlik duvarı gereksinimleri'nde uç noktalara izin verin ve yeniden dağıtın.
Sürüm failed sürümüne geçer. Hatalı zip düzeni, söz dizimi hatası veya (remote_build) geri yükleme/derleme hatası Önce sürümün error nesnesini okuyun; error.code hatayı sınıflandırır ve error.message temel geri yükleme veya derleme hata satırını (Python için pip, .NET için NuGet) ve bir sorun giderme bağlantısı içerir. Klasör yapısını doğrulayın. :logstream öğesini yalnızca kapsayıcı başlatıldıktan sonra kullanın.
ModuleNotFoundError çalışma zamanında packages/ eksik, ham .whl dosyaları içeriyor veya Windows ikili dosyaları var pip install --target packages/ --platform manylinux2014_x86_64 --only-binary=:all: ile yeniden derleyin.
409 AgentNotCodeBased indirme sırasında Ajan görüntü tabanlıdır Kapsayıcı tabanlı dağıtım belgesini kullanın.

Kaynakları temizle

Projeyi Quickstart bölümünden azd ile oluşturduysanız, oluşturulan ortamın tamamını kaldırmak için proje kök dizininde azd down komutunu çalıştırın.

SDK veya REST API ile dağıtılan bir aracıyı silmek için aşağıdaki eşleşen yolu kullanın.

# Delete one version
project.agents.delete_version(agent_name=AGENT_NAME, agent_version=created.version)

# Delete the agent and all its versions
project.agents.delete(agent_name=AGENT_NAME)

Warning

Bir aracı silindiğinde tüm sürümleri kaldırılır ve etkin oturumlar sonlanır. Bu eylem geri alınamaz.

Sonraki Adımlar

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

İlgili içerik

  • Last updated on