azure-search-openai-demo 容器化部署实战：在 Azure Container Apps 上运行 RAG 聊天应用-开发者社区

azure-search-openai-demo 容器化部署实战：在 Azure Container Apps 上运行 RAG 聊天应用

【免费下载链接】azure-search-openai-demoA sample app for the Retrieval-Augmented Generation pattern running in Azure, using Azure AI Search for retrieval and Azure OpenAI large language models to power ChatGPT-style and Q&A experiences.项目地址: https://gitcode.com/GitHub_Trending/az/azure-search-openai-demo

本篇指南聚焦 azure-search-openai-demo 项目的 Azure Container Apps 部署路径，完整讲解 azd（Azure Developer CLI）单 Host 限制下的azure.yaml配置切换、从登录到azd up的六步部署流程、DEPLOYMENT_TARGET与AZURE_CONTAINER_APPS_WORKLOAD_PROFILE两个关键环境变量的底层作用，以及工作负载配置文件的选型与私有端点支持现状。读完本文，你将能独立完成该 RAG 示例在 Container Apps 上的部署、按需切换回 App Service，并理解整套 Bicep 条件资源编排的工作原理。

azd 的单 Host 限制：为什么`azure.yaml`里只能有一个部署目标

Azure Container Apps 与 Azure App Service 是两种截然不同的托管形态，而azd在解析项目清单时存在一个已知限制：azure.yaml 文件中只能存在一个host选项。因此该仓库采用了"默认启用一种、另一种注释保留"的策略。

打开仓库根目录的 azure.yaml，可以看到 backend 服务的声明（第 8～17 行）：

services: backend: project: ./app/backend language: py # Please check docs/azure_container_apps.md for more information on how to deploy to Azure Container Apps host: containerapp docker: remoteBuild: true # Please check docs/azure_app_service.md for more information on how to deploy to Azure App Service # host: appservice

默认情况下host: containerapp生效，host: appservice被注释掉。如果你拿到的是旧版本仓库，或者希望改用 App Service，就需要在这两种 host 之间手动切换（对应操作见 docs/azure_app_service.md）。

值得留意的是，不同的 host 会触发不同的 azd hooks：appservice对应prepackagehook，而containerapp对应prebuildhook，两者的执行内容完全一致，都是在打包镜像前构建前端：

hooks: # This hook is called when App Service is the host prepackage: posix: shell: sh run: cd ../frontend;npm install;npm run build # This hook is called when Azure Container Apps is the host prebuild: posix: shell: sh run: cd ../frontend;npm install;npm run build

从源码结构看，这个设计保证了无论走哪条部署路径，前端都会先被编译成静态产物，再一并打进后端镜像（Dockerfile 中COPY ./ /app即包含构建完成的前端目录）。

部署到 Azure Container Apps 的完整步骤

1. 在 azure.yaml 中确认 host 为 containerapp

将 azure.yaml 中host: containerapp保持启用（取消注释），同时注释掉host: appservice。若此前是 App Service 部署，请务必完成这一步，否则 azd 会按错误的目标执行部署。

2. 登录 Azure 账号

azd auth login

该命令会弹出浏览器完成 Azure 身份认证，认证信息将被 azd 持久化使用。

3. 创建新的 azd 环境

azd env new

输入的名称将直接用作资源组名称。命令会在.azure目录下创建对应文件夹，并将其设为后续所有 azd 调用的活动环境。

4. 设置部署目标为 containerapps

azd env set DEPLOYMENT_TARGET containerapps

这一步虽然看似可选（因为默认值就是containerapps），但显式设置能确保环境变量被写入当前 azd 环境的.env文件，避免依赖默认值带来的不确定性。其背后的默认值定义在 infra/main.parameters.json：

"deploymentTarget": { "value": "${DEPLOYMENT_TARGET=containerapps}" }

5.（可选）按需定制部署

这是可以自由发挥的节点：通过设置其他 azd 环境变量，你可以选择复用现有 Azure 资源、启用可选功能（如认证 auth、视觉 vision 等），或部署到免费/低成本层级。

6. 预配资源并部署代码

azd up

该命令会完成三件事：预配 Azure 资源、将应用部署到这些资源上、并根据./data目录中的文件构建搜索索引（postprovisionhook 会依次执行 scripts/auth_update.sh 与 scripts/prepdocs.sh）。

重要成本提示：azd up创建的资源会立即产生费用，尤其是 AI Search 资源。即使你在命令完全执行完之前中断，这些资源仍可能持续计费。不使用时请运行azd down或手动删除资源，以避免不必要的支出。

深入 DEPLOYMENT_TARGET：Bicep 中的条件资源编排

DEPLOYMENT_TARGET并非只在 azd 层面生效，它会被注入 infra/main.bicep 的参数体系，进而决定整套 Bicep 模块的部署分支。核心逻辑如下：

参数声明（infra/main.bicep）：deploymentTarget string = 'appservice'作为参数默认值，实际值由main.parameters.json注入；
派生资源名：deploymentTarget == 'containerapps'时才会生成 ACA 用户分配托管身份（acaIdentityName）、托管环境（acaManagedEnvironmentName）和容器注册表（containerRegistryName）的名称（infra/main.bicep）；
条件模块分支：App Service 计划与 backend 模块仅在deploymentTarget == 'appservice'时部署（infra/main.bicep 与 infra/main.bicep）；而 ACA 身份、容器应用环境、backend 容器应用及认证模块仅在deploymentTarget == 'containerapps'时部署（infra/main.bicep）；
统一出口：无论走哪条分支，最终都通过BACKEND_URI输出后端地址，前端与后端 API 的联调入口保持一致（infra/main.bicep）。

Container Apps 部署路径由三个模块协同完成（infra/main.bicep）：

模块文件	职责
infra/core/security/aca-identity.bicep	创建用户分配托管身份，供容器应用访问 Azure AI Search、存储等资源
infra/core/host/container-apps.bicep	预配 Container Apps 托管环境（managed environment）与 Azure 容器注册表（ACR）
infra/core/host/container-app-upsert.bicep	创建或更新 backend 容器应用本身，注入环境变量与镜像

其中 container-app-upsert.bicep 还提供了一套容器规格参数，默认值为 0.5 vCPU、1.0Gi 内存、最小 1 副本、最大 10 副本（infra/core/host/container-app-upsert.bicep）。后端镜像启动命令为 Gunicorn 绑定0.0.0.0:8000运行 FastAPI 应用（Dockerfile），因此容器应用的目标端口（targetPort）被配置为 80 并转发到容器内的 8000。

定制工作负载配置文件（Workload Profile）

Container Apps 支持两种计费与调度模型：Consumption（按量计费）与Dedicated（专用工作负载）。本项目的默认工作负载配置文件是Consumption，对应 infra/main.parameters.json：

"azureContainerAppsWorkloadProfile": { "value": "${AZURE_CONTAINER_APPS_WORKLOAD_PROFILE=Consumption}" }

如需改用 D4 等专用工作负载配置文件，在部署前执行：

azd env set AZURE_CONTAINER_APPS_WORKLOAD_PROFILE D4

可用的工作负载配置文件类型以 Bicep 中的@allowed约束为准（infra/core/host/container-apps.bicep），包括：

Consumption, D4, D8, D16, D32, E4, E8, E16, E32, NC24-A100, NC48-A100, NC96-A100

其中D系列为通用计算型、E系列为内存优化型、NC*系列为 GPU 加速型（A100）。请注意：专用工作负载配置文件与 Consumption 计划的计费模型不同，选用前务必核对 Azure Container Apps 的计费文档，避免产生预期外的成本。

从源码还可以看到一个易被忽略的细节：当托管环境启用私有入口（usePrivateIngress）且用户仍指定Consumption时，Bicep 会自动将生效的工作负载配置文件"升级"为D4（infra/core/host/container-apps-environment.bicep），因为私有入口要求至少一个非 Consumption 配置文件承载流量。该文件同时定义了工作负载数组：非私有入口场景仅保留Consumption，私有入口场景则额外挂载名为Warm的专用配置文件（infra/core/host/container-apps-environment.bicep）。

私有端点（Private endpoints）支持现状

需要特别提醒的是：Azure Container Apps 的私有端点（Private endpoints）功能目前仍处于私有预览阶段，本项目暂不支持。因此，如果你的部署场景强依赖 VNet 内的私有端点隔离，当前版本应优先考虑 App Service 部署路径（参见 docs/azure_app_service.md），或者关注 Azure Container Apps 官方功能的正式发布状态后再做迁移。

从 infra/main.bicep 可以看到，仓库其实已经为两条路径分别预留了私有端点连接变量（containerAppsPrivateEndpointConnection与appServicePrivateEndpointConnection），但 Container Apps 侧的支持落地仍受制于平台能力的发布节奏。

部署后的验证与运维建议

azd up成功完成后，可按下述思路验证与运维：

访问验证：通过azd env get-values查看BACKEND_URI输出，浏览器打开前端地址，确认 ChatGPT 式问答界面可正常与后端交互；
资源清理：验证完毕后及时执行azd down删除资源组及全部资源，防止 AI Search、容器环境等持续计费；
环境隔离：不同目标环境使用azd env new分别创建，DEPLOYMENT_TARGET、AZURE_CONTAINER_APPS_WORKLOAD_PROFILE等变量均按环境独立存储于.azure/<env>目录，切换环境不会互相污染；
Host 切换回滚：若需从 Container Apps 切回 App Service，反向操作即可——将 azure.yaml 中的host: containerapp注释掉、取消host: appservice注释，并执行azd env set DEPLOYMENT_TARGET appservice后重新azd up，其余步骤与本文完全对称。

小结

Azure Container Apps 是 azure-search-openai-demo 的默认部署目标，其部署链路由 azure.yaml 的host字段、DEPLOYMENT_TARGET环境变量与 infra/main.bicep 的条件模块共同驱动。掌握azd env set的变量注入方式与 Bicep 分支逻辑，即可在 Consumption/Dedicated 工作负载、Container Apps/App Service 之间自由切换，同时务必留意成本控制与私有端点暂不支持这两条边界条件。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

azure-search-openai-demo 容器化部署实战：在 Azure Container Apps 上运行 RAG 聊天应用