将适用于代理的 Docker Compose 部署到 Azure Container Apps 预览版

本文介绍如何使用 Docker 的 Compose for Agents 将应用程序部署到Azure Container Apps。 此功能保留本地使用的撰写文件，并允许将其部署到容器应用。 然后，az-cli 容器应用扩展将 Compose 文件转换为 Azure 容器应用，并为你管理标识、缩放和模型生命周期。

在本文中，您将学习：

先决条件

• 安装了 Azure CLI 2.70.0 或更高版本和 containerapp 扩展版本 1.2.0b5+ai.compose 或更高版本（请参阅安装说明）。
• 要有能够创建 Azure Container Apps 资源权限的 Azure 订阅。
• 用于代理文件的 Docker Compose。 可以从 docker/compose-for-agents 存储库中的示例开始。
• Docker 安装（适用于本地生成）
• Azure Container Apps环境可供部署使用。 如果你还没有环境，请用az containerapp env create创建一个。 本文中使用的示例假定使用无服务器 GPU。

部署体系结构

运行 az containerapp compose create 时，CLI 会将以代理为中心的配置元素转换为适当的 Azure Container Apps 资源。 Compose for Agents 中的两个关键组件是模型运行程序和 MCP 网关，负责使模型和 MCP 工具可供应用程序使用。

模型上下文协议 （MCP） 工具

Azure Container Apps以自己的容器应用的形式运行 Docker 的 MCP 网关变体。 它使用系统分配的托管标识动态添加或删除环境中的 MCP 工具容器。 此设置在 mcp 网关应用程序下显示为单独的容器。 MCP 工具的通信网关仅限于网络。 Stdio MCP 服务器被封装为在 Azure 容器应用上运行的 SSE 基 MCP 服务器。 Azure Container Apps上的 Docker for Agents 目前支持以下 Stdio MCP 服务器：AppSignal、BigQuery、Confluence、DuckDuckGo、Fetch、Filesystem、Git、Jira、MongoDB、MySQL、Notion、Playwright、PostgreSQL、顺序思维、Slack、SQLite、Supabase、Time、Twist。

模型

模型通过 Docker 的模型运行程序提供。 在 Azure 容器应用中，作为模型应用一部分部署的模型运行程序配置的容器负责处理配置。 它确保拉取并配置正确的模型，然后应用才能与之交互。 配置通过 MODEL_CONFIG 变量传递到模型配置容器。

撰写文件

可以将同一撰写文件用于本地开发和部署。 若要实现此目标，请添加 x-azure-deployment 指令。 Docker 的 Compose 将忽略此指令，但在部署Azure Container Apps期间会使用它。 下面是 一些可供你查看的现成部署示例 。 这些示例都包含适用于无服务器 GPU 和 Azure Container Apps 版本 mcp 网关部署的共同部分。

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.cn/preview-ai-compose/mcp-gateway:latest
  ...

models:
  ...

其他 x-azure-deployment 选项包括：

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

安装和使用情况

按照以下步骤设置环境，并使用现有的撰写文件部署应用程序。

安装 Compose for agents

在此阶段，此功能需要安装两个包。 安装后，这些包将提供说明的功能。 执行以下步骤：

# 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

使用 Compose 为代理商提供服务

从 此处准备的文件之一开始。 然后按照说明进行操作

# define the needed variables
export LOCATION=chinanorth2
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

卸载并恢复至原状

切换回容器应用扩展的稳定版本：

# 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

已知问题和故障排除

• 偶尔出现映像可用性延迟：有时本地生成的映像没有立即在平台上可用。 重新部署或重启应用程序以解决此问题。 错误如下所示：

  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.cn/preview-ai-compose/samples/spring-ai-app:latest": GET https:: MANIFEST_UNKNOWN: manifest tagged by "latest" is not found; map[Tag:latest]'
  

• 托管标识问题：重新部署时可能会看到此消息。 发生此错误的原因是身份被重新分配给mcp-gateway。 如果网关正常运行，请忽略该消息。

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

• 无法访问的网关 URL：确认网关主机名省略端口号，并与注入的MCP_GATEWAY_URL值匹配。 不要手动重新引入在部署中被移除的端口。

• MCP 网关工具：检查 mcp 网关应用是否部署了多个容器。 如果是这样，事情应该正常运行。

• 未预配的模型：查看应用中的model-runner-configmodels容器日志，以在拉取模型时检查身份验证问题。 通过运行 curl http://YOUR_MODELS_ENDPOINT/models拉取可用模型。

• 报告问题：请在官方容器应用程序的GitHub页面上报告扩展问题。

预览限制

• 每个 Compose 文件仅支持一个 SSE 基于的 MCP 封装器。
• 目前不支持数据卷和网络。
• 日志消息并不总是正确的。