Aracılar için Docker Compose'u Azure Container Apps Preview'a dağıtma

Bu makalede Docker'ın Aracılar için Oluşturma'sını kullanarak uygulamaları Azure Container Apps'e nasıl dağıtabileceğiniz gösterilmektedir. Bu özellik, zaten yerel olarak kullandığınız oluşturma dosyasını tutar ve Container Apps'e dağıtmanıza olanak tanır. Kapsayıcı az-cli uygulaması uzantısı daha sonra oluşturma dosyasını Azure Container App uygulamalarına çevirir ve kimlikleri, ölçeklendirmeyi ve model yaşam döngüsünü sizin için yönetir.

Bu makalede şunları öğreneceksiniz:

• Azure Container Apps'te oluşturulan aracıya özgü kaynakları anlamak.
• Azure Container Apps için uyarlanmış örnek oluşturma dosyalarını gözden geçirin.
• Azure CLI ile bir oluşturma dosyası dağıtın ve ortamı doğrulayın.
• Sorunları giderin ve geçerli sınırlamalar hakkında bilgi edinin.

Önemli

Azure Container Apps'te aracılar için Docker Compose desteği genel önizleme aşamasındadır. Özellikler ve davranışlar bildirimde bulunmadan değişebilir.

Önkoşullar

• Azure CLI 2.70.0 veya üzeri ve containerapp veya üzeri uzantı sürümü yüklü (yükleme yönergelerine bakın).
• Azure Container Apps kaynakları oluşturma izinlerine sahip bir Azure aboneliği.
• Ajanlar için Docker Compose dosyası. Docker/compose-for-agents deposundaki örneklerden başlayabilirsiniz.
• Docker yüklemesi (yerel derleme için)
• Dağıtımlar için hazır bir Azure Container Apps ortamı. Eğer ortamınız yoksa az containerapp env create kullanarak bir tane oluşturun. GPU'da modelleri dağıtmak için aşağıdaki konumlardan birini seçmeniz gerekir. Bu makalede kullanılan örneklerde sunucusuz GPU kullanıldığı varsayılır.

Dağıtım mimarisi

Siz az containerapp compose create çalıştırdığınızda, CLI ajand odaklı oluşturma öğelerini uygun Azure Container Apps kaynaklarına çevirir. Aracılar için Oluştur'daki iki kritik bileşen, model çalıştırıcısı ve MCP ağ geçididir ve modeli ve MCP araçlarını uygulamanız için kullanılabilir hale getirmekle sorumludur.

Model bağlam protokolü (MCP) araçları

Azure Container Apps, Docker'ın MCP ağ geçidinin bir değişkenini kendi kapsayıcı uygulaması olarak çalıştırır. Ortam içindeki MCP araç kapsayıcılarını dinamik olarak eklemek veya kaldırmak için sistem tarafından atanan yönetilen kimliği kullanır. Bu kurulum, mcp-gateway uygulaması altında ayrı kapsayıcılar olarak görünür. MCP araçlarına geçit iletişimi ağ ile sınırlıdır. Stdio MCP sunucuları, Azure Container Apps'te SSE tabanlı MCP sunucuları olarak çalışacak şekilde sarmalanmıştır. Azure Container Apps'te Aracılar için Docker şu anda şu Stdio MCP sunucularını destekler: AppSignal, BigQuery, Confluence, DuckDuckGo, Fetch, Filesystem, Git, Google Drive, Jira, MongoDB, MySQL, Notion, Playwright, PostgreSQL, SequentialThinking, Slack, SQLite, Supabase, Time, Twist.

Models

Modeller Docker'ın model çalıştırıcısı aracılığıyla sunulur. Azure Container Apps'te model uygulamasının bir parçası olarak dağıtılan model-runner-config kapsayıcısı yapılandırmayı işler. Uygulamanızın etkileşim kurabilmesi için doğru modelin çekilip yapılandırılmasını sağlar. Yapılandırma, değişken aracılığıyla model yapılandırma kapsayıcısına MODEL_CONFIG geçirilir.

Dosya oluşturma

Yerel geliştirme ve dağıtım için aynı oluşturma dosyasını kullanabilirsiniz. Bu hedefe ulaşmak için x-azure-deployment yönergesini ekleyin. Docker's Compose bu yönergeyi yoksayar, ancak Azure Container Apps'te dağıtım sırasında kullanılır. Gözden geçirmeniz için bazı dağıtıma hazır örnekler aşağıdadır. Bu örneklerin tümü, sunucusuz GPU ve mcp-gateway'in Azure Container Apps sürümünü dağıtmak için aşağıdaki bölümlere sahiptir.

services:
  ...

models:
  gemma:
    model: ai/gemma3-qat
	# run the models on serverless GPU workload profile
    x-azure-deployment:
      workloadProfiles:
        workloadProfileType: Consumption-GPU-NC8as-T4

serivces:
	mcp-gateway:
	...
	# use the Azure Container Apps flavored image for the mcp-gateway
	x-azure-deployment:
	  image: acateam.azurecr.io/preview-ai-compose/mcp-gateway:latest
  ...

models:
  ...

Diğer x-azure-deployment seçenekler şunlardır:

x-azure-deployment:
  image: ghcr.io/example/app:custom-build
  resources:
    cpu: 1.0
    memory: 2
  scale:
    maxReplicas: 1
    minReplicas: 1
  ingress:
    external: true
    allowInsecure: false

Yükleme ve kullanım

Ortamınızı ayarlamak ve mevcut oluşturma dosyalarınızı kullanarak uygulamalarınızı dağıtmak için aşağıdaki adımları izleyin.

Aracılar için Compose'u yükleme

Bu aşamada, bu özellik iki paketin yüklenmesini gerektirir. Bu paketler yüklendikten sonra açıklanan özellikleri sağlar. Şu adımları izleyin:

# remove the existing container apps extension
az extension remove --name containerapp

# install the pycomposefile module and the preview extension for containerapps
pip install "https://raw.githubusercontent.com/microsoft/azure-container-apps/main/preview/ai-compose/az-extension/release-1.2.0b5+ai.compose-py2.py3-none-any/pycomposefile-0.0.32-py3-none-any.whl"
az extension add --source "https://raw.githubusercontent.com/microsoft/azure-container-apps/main/preview/ai-compose/az-extension/release-1.2.0b5+ai.compose-py2.py3-none-any/containerapp-1.2.0b5+ai.compose-py2.py3-none-any.whl" --yes

# check of the extension is installed (should show 1.2.0b5+ai.compose)
az extension show --name containerapp --query version -o tsv
# you are ready to use the extension
az containerapp compose --help

Aracılar için Oluştur'u kullanma

Burada bulunan hazırlanmış dosyalardan biriyle başlayın. Ardından yönergeleri izleyin:

# define the needed variables
export LOCATION=westus2
export RESOURCE_GROUP=rg-compose-for-agents
export ENV_NAME=ai-app-env
export COMPOSE=compose-aca.yml

# create the resource group
az group create --name $RESOURCE_GROUP   --location $LOCATION && 

# create the Azure Container Apps environment
az containerapp env create \
			--name $ENV_NAME \
			--resource-group $RESOURCE_GROUP \
			--location $LOCATION

# deploy your compose file
az containerapp compose create \
			--compose-file-path $COMPOSE \
			--resource-group $RESOURCE_GROUP \
			--environment $ENV_NAME

Temsilci ayarlarının varsayılanları

Açık aracı ayarları olmadan oluşturulan uygulamalar aşağıdaki varsayılanları alır:

• DiscoveryMode = Autoaracı özelliklerini ve bağımlılıklarını otomatik olarak algılar.
• IsAgent = false, açıkça yapılandırılmadığı sürece uygulamanın aracı olarak hareket etmediğini belirtir.

Bu varsayılanlar ortamınızdaki tüm kapsayıcı uygulamaları için tutarlı bir davranış sağlar.

Yazılımı kaldırma ve önceki sürüme geri dönme

Kapsayıcı uygulaması uzantısının kararlı sürümüne geri dönmek için:

# remove the current extension
az extension remove --name containerapp
# reinstall and confirm stable install
az extension install --name containerapp
az extension show --name containerapp --query version -o tsv

Bilinen sorunlar ve sorun giderme

• Zaman zaman görüntü kullanılabilirliği gecikmeleri: Bazen yerel olarak oluşturulmuş bir görüntü platformda hemen kullanılamaz. Sorunu çözmek için uygulamayı yeniden dağıtın veya yeniden başlatın. Hata aşağıdaki gibi görünür:

  Failed to provision revision for container app 'app'. Error details: The following field(s) are either invalid or missing. Field 'template.containers.app.image' is invalid with details: 'Invalid value: "acateam.azurecr.io/preview-ai-compose/samples/spring-ai-app:latest": GET https:: MANIFEST_UNKNOWN: manifest tagged by "latest" is not found; map[Tag:latest]'
  

• Yönetilen kimlik sorunları: Yeniden dağıtdığınızda bu iletiyi görebilirsiniz. Bu hata, kimliğin mcp-gateway'e yeniden atandığı için oluşur. Ağ geçidiniz düzgün çalışıyorsa iletiyi yoksayın.

  ⚠️  Could not automatically assign role: AADSTS53003: Access has been blocked by Conditional Access policies. The access policy does not allow token issuance.
  

• Ulaşılamayan ağ geçidi URL'leri: Ağ geçidi ana bilgisayar adının bağlantı noktası numarasını atladığını ve bu değerin MCP_GATEWAY_URL'e eklenenle eşleştiğini doğrulayın. Dağıtım sırasında kaldırılan bağlantı noktalarını el ile yeniden sunmayın.

• MCP ağ geçidi araçları: "mcp-gateway" uygulamasında birden fazla kapsayıcının dağıtılıp dağıtılmadığını kontrol edin. Öyleyse, işler düzgün çalışıyor olmalıdır.

• Sağlanmamış Modeller: Modelleri çekerken kimlik doğrulama sorunlarını kontrol etmek için model-runner-config uygulamasının models kapsayıcı günlüklerini inceleyin. komutunu çalıştırarak curl http://YOUR_MODELS_ENDPOINT/modelskullanılabilir modelleri çekin.

• Raporlama sorunları: Resmi Container Apps GitHub'da uzantıyla ilgili sorunları bildirin.

Önizleme sınırlamaları

Uyarı

Bu sınırlamalar genel önizleme sırasında geçerlidir ve genel kullanıma sunulmadan önce değişebilir.

• Oluşturma dosyası başına yalnızca bir SSE tabanlı MCP sarmalayıcısı desteklenir.
• Birimler ve ağlar şu anda desteklenmemektedir.
• Log mesajları her zaman doğru değildir.