azure-search-openai-demo 部署故障排查完全指南8 类常见错误的原因分析与修复方案【免费下载链接】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 QA experiences.项目地址: https://gitcode.com/GitHub_Trending/az/azure-search-openai-demo导读azure-search-openai-demo是一个在 Azure 上运行检索增强生成RAG模式的开源示例项目使用 Azure AI Search 完成检索、以 Azure OpenAI 大语言模型驱动 ChatGPT 风格的问答体验。本文基于项目官方部署故障排查文档系统梳理azd up部署过程中最常见的 8 类错误——从区域/配额问题、资源软删除冲突到 Cosmos DB 分区键不可变、Cognitive Services 恢复标志等——逐一给出根因分析与可复现的修复命令。读完本文你将掌握完整部署生命周期中首次部署、重复部署、azd down后再部署、本地与 CI/CD 切换的排错方法并能结合仓库 Bicep 源码理解每条报错背后的实现机制。完整部署步骤请参考 README.md 的 Deploying 章节本文只聚焦部署过程中报错的定位与解决。一、排查前的基线认知部署流程与故障上下文所有故障都发生在azd up这条主链路上。在 README.md 中部署流程明确为azd up该命令会完成两件事预配 Azure 资源Provision以及把示例部署到这些资源并把./data目录中的文件构建成搜索索引Deploy。之后每次更新只需执行azd up详见 README.md 的 Deploying again 章节。理解这一流程的意义在于下文绝大多数错误都发生在预配阶段资源创建/角色分配/容器创建只有第 4 条CERTIFICATE_VERIFY_FAILED发生在构建索引阶段prepdocs.py运行期间。故障位置不同处理手段完全不同。二、资源创建类错误1. 区域不可用Azure OpenAI 未在该区域启用或模型未启用报错现象创建资源失败提示所在区域不支持 Azure OpenAI或该区域未启用你要使用的模型。根因Azure OpenAI 的资源与模型都有明确的区域可用性矩阵。例如文档明确举例East US 2未被启用时应改用East US等已启用区域同样即使区域整体可用你选择的特定模型也可能尚未在该区域上线。解决思路核对 Azure OpenAI 模型可用性矩阵官方维护按区域展示各模型是否可用修改部署参数中的区域配置后重新azd up注意项目内多个资源可以配置不同区域如 main.bicep 中 OpenAI 资源使用openAiLocation、搜索服务使用searchServiceLocation、Cosmos DB 使用cosmosDbLocation按需分别调整。2. 配额超限最常见的是每区域资源数量配额报错现象azd up预配阶段报配额不足Quota Exceeded。根因Azure OpenAI 对每个区域/每订阅的资源数量有配额限制重复部署多个实例最容易触发每区域资源数这一项。解决思路查阅 Azure OpenAI 配额与限制官方文档在 Azure 门户中申请提高配额或把部分资源迁移到配额更充裕的区域然后重新部署。三、重复部署冲突类错误3. same resource name not allowed忘记清理软删除资源报错现象重复部署时提示资源名冲突即使你已经删除了之前创建的资源。根因Azure 对删除的资源默认保留48 小时软删除soft delete期间同名资源无法重建。反复运行示例、每次azd down后又立即重部署最容易踩中这个坑。解决思路按官方指引执行资源清理purge彻底从软删除状态移除后再重试。清理入口Azure 门户中该资源的管理资源页或参考 官方 purge 操作文档门户与 CLI 两种方式。提示第 8 条中的RESTORE_COGNITIVE_SERVICES标志是恢复软删除资源的自动化方案与本节的手动 purge 互为补充详见后文。4. RoleAssignmentExistsHTTP 409本地开发与 CI/CD 切换导致报错现象在本地开发与CI/CD 流水线之间来回切换部署时报RoleAssignmentExists错误HTTP 409。根因角色分配Role Assignment的名称由principalId、roleDefinitionId等参数通过 GUID 哈希生成。当principalType在User本地与ServicePrincipalCI/CD之间变化时GUID 也随之变化但旧的角色分配仍残留在资源上于是新角色分配与旧记录冲突。从源码可以验证这一机制infra/main.bicep 中principalType的取值逻辑为empty(runningOnGh) empty(runningOnAdo) ? User : ServicePrincipal即本地直接运行azd时为User在 GitHub Actions / ADO 流水线中为ServicePrincipal角色分配模块 infra/core/security/role.bicep 使用guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)生成资源名principalType变化会改变生成结果从而产生冲突。解决思路当前模板已为每种principalType分别生成独立的角色分配因此直接再次运行azd up即可让新的分配按新 GUID 生效从而解决冲突。5. PropertyChangeNotAllowedCosmos DB 分区键不可变报错现象在旧版本模板基础上重新部署时报PropertyChangeNotAllowed错误指向 Cosmos DB 分区键。根因Cosmos DB 的分区键在容器创建后不可修改。旧模板部署的chat-history容器使用单一/userId分区键新模板改用chat-history-v2容器并升级为 MultiHash 多分区键/entra_oid/session_id。对已存在的容器尝试修改分区键会被平台拒绝。从 infra/main.bicep 的注释与实现可以完整看到这一约束与迁移路径// WARNING: Cosmos DB partition keys are immutable. If you originally deployed with the v1 container // (chat-history with a single /userId partition key), re-deploying with the v2 container schema // (chat-history-v2 with MultiHash /entra_oid /session_id) will fail with: // Document collection partition key cannot be changed.新容器的定义在 infra/main.bicep可以看到kind: MultiHash、分区键路径为/entra_oid与/session_id并针对/entra_oid、/session_id、/timestamp、/type建立了精确索引策略。容器名参数chatHistoryContainerName默认为chat-history-v2见 infra/main.bicep。解决方案二选一删除旧容器后重新部署在 Azure 门户 Cosmos DB Data Explorer 中删除chat-history-v2容器或使用 CLIaz cosmosdb sql container delete删除后重新azd up模板会用正确的 MultiHash 分区键方案重建容器。更换容器名通过azd env set把chatHistoryContainerName覆盖为新名称例如chat-history-v3让模板创建一个全新容器。注意事项方案 1 会丢失该容器中已有的聊天历史记录方案 2 不会动旧数据但会新增一个容器。这也是项目提供 scripts/cosmosdb_migration.py 迁移脚本其new_container即指向chat-history-v2见 cosmosdb_migration.py来帮助平滑迁移旧聊天记录的原因。Bicep 无法条件性跳过容器更新这是 ARM/Cosmos DB 平台层面的限制并非模板缺陷。四、运行与恢复类错误6. CERTIFICATE_VERIFY_FAILEDprepdocs.py 阶段 SSL 证书问题报错现象azd up过程中prepdocs.py脚本运行时抛出CERTIFICATE_VERIFY_FAILED。根因这是典型的本机 SSL 证书配置不正确导致的 Python SSL 校验失败与 Azure 资源本身无关。prepdocs.py位于 app/backend/prepdocs.py负责把./data中的文档解析、分块、向量化并写入 Azure AI Search 索引过程中需要与 Azure 服务建立 HTTPS 连接本机证书链不完整就会触发该校验错误。解决思路参考社区公认的解决方案如 StackOverflow 相关回答修复本机 SSL 证书安装例如更新系统 CA 证书库、为 Python 指定正确的证书路径或使用包含完整证书链的根证书。修复本机环境后重新执行部署。7. 部署后访问网站出现 404 Not Found报错现象azd up成功完成后浏览器访问网站却返回 404。根因最常见的场景是应用仍在启动中。容器化/托管环境首次冷启动需要拉取镜像、初始化依赖短时间内请求会落到尚未就绪的实例上。解决思路按顺序执行等待 10 分钟后重试——文档明确提示这可能是仍在启动若仍失败重新执行azd deploy再次等待如果部署目标是App Service且问题依旧查阅 appservice.md 排错指南其中覆盖了日志流、诊断、重新部署等 App Service 特有手段若日志无法定位问题可在项目仓库提交 Issue 反馈附上日志。从 appservice.md 的定位看它专门服务于 App Service 部署场景若你的目标是 Azure Container Apps应优先参考 azure_container_apps.md 中对应的部署与诊断说明。8. ConflictHTTP 409Cognitive Services 资源软删除导致报错现象azd down之后再次重新部署时报 HTTP 409Conflict指向 Cognitive Services 类资源。根因Azure 对 Cognitive Services 资源含 OpenAI、Document Intelligence、Vision、Speech 等执行48 天的软删除保留期保留期内同名资源无法重建。文档明确给出这个 48 天的数字这也是此类冲突与第 3 条48 小时保留的本质区别——两者保留期长度不同。解决方案启用RESTORE_COGNITIVE_SERVICES自动恢复标志。部署前设置azd env set RESTORE_COGNITIVE_SERVICES true azd up部署完成后务必改回false以避免影响后续部署azd env set RESTORE_COGNITIVE_SERVICES false这个环境变量的传递链路在仓库中有完整实现参数映射RESTORE_COGNITIVE_SERVICES环境变量被映射到 Bicep 参数restoreCognitiveServices默认值为false见 infra/main.parameters.json参数声明param restoreCognitiveServices bool false见 infra/main.bicep实际生效该参数被传递给 5 类 Cognitive Services 类资源的部署模块包括 FoundryAI Services账号infra/main.bicep、Document Intelligenceinfra/main.bicep、Visioninfra/main.bicep、Content Understandinginfra/main.bicep以及 Speechinfra/main.bicep——这些模块统一通过restore: restoreCognitiveServices把标志传递给底层 Cognitive Services 资源定义。备选方案不用标志改为手动 purge 软删除的资源Azure 门户或 Azure CLI然后不带标志重新部署。两种方式目标一致区别在于前者自动化、后者更可控。注意azd env set写入的是 azd 环境变量只对当前 azd 环境生效因此先 true 部署、后 false 再部署的操作顺序要严格遵循避免标志长期开启。五、故障速查表与最佳实践错误阶段根因首选解法区域/模型不可用预配区域未启用 Azure OpenAI 或模型查模型可用性矩阵换区域/模型配额超限预配每区域资源数配额查配额文档申请提额或换区域资源名冲突预配软删除保留 48 小时门户/CLI 执行 purge 后重试RoleAssignmentExists409预配本地/CI 切换导致 principalType 变化直接再次azd upPropertyChangeNotAllowed预配Cosmos DB 分区键不可变删除旧容器或换容器名重部署CERTIFICATE_VERIFY_FAILED索引构建本机 SSL 证书配置错误修复本机证书链访问 404部署后应用仍在启动等待 10 分钟必要时azd deployApp Service 见 appservice.mdCognitive ServicesConflict409重部署软删除保留 48 天azd env set RESTORE_COGNITIVE_SERVICES true后azd up再改回false部署排错的最佳实践总结区分资源类型看保留期普通资源软删除保留 48 小时Cognitive Services 类资源保留 48 天两者的清理手段不同善用环境变量而非手动改文件RESTORE_COGNITIVE_SERVICES、chatHistoryContainerName等都应通过azd env set覆盖保持模板文件不被改动便于后续同步上游更新理解部署的生命周期差异本地User与 CI/CDServicePrincipal之间切换属正常操作遇到角色分配冲突时重跑azd up即可升级模板前先看数据影响涉及 Cosmos DB 这类不可变配置时先评估旧容器数据必要时用 cosmosdb_migration.py 迁移保留部署日志404 等运行态问题最终要靠日志定位App Service 场景优先查阅 appservice.md 中的日志与诊断章节。相关文档导航部署总览与 azd 使用azd up/azd down/azd env set的完整生命周期App Service 排错指南部署目标是 App Service 时的深度诊断Azure Container Apps 部署ACA 场景的部署说明部署特性说明其中也包含 Cosmos DB MultiHash 迁移的警告与交叉引用本地开发指南本地运行的前提是已成功执行过azd up部署基础架构源码restoreCognitiveServices、MultiHash 分区键、principalType等实现细节的最终依据【免费下载链接】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 QA experiences.项目地址: https://gitcode.com/GitHub_Trending/az/azure-search-openai-demo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 azure-search-openai-demo 部署故障排查完全指南：8 类常见错误的原因分析与修复方案
azure-search-openai-demo 部署故障排查完全指南8 类常见错误的原因分析与修复方案【免费下载链接】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 QA experiences.项目地址: https://gitcode.com/GitHub_Trending/az/azure-search-openai-demo导读azure-search-openai-demo是一个在 Azure 上运行检索增强生成RAG模式的开源示例项目使用 Azure AI Search 完成检索、以 Azure OpenAI 大语言模型驱动 ChatGPT 风格的问答体验。本文基于项目官方部署故障排查文档系统梳理azd up部署过程中最常见的 8 类错误——从区域/配额问题、资源软删除冲突到 Cosmos DB 分区键不可变、Cognitive Services 恢复标志等——逐一给出根因分析与可复现的修复命令。读完本文你将掌握完整部署生命周期中首次部署、重复部署、azd down后再部署、本地与 CI/CD 切换的排错方法并能结合仓库 Bicep 源码理解每条报错背后的实现机制。完整部署步骤请参考 README.md 的 Deploying 章节本文只聚焦部署过程中报错的定位与解决。一、排查前的基线认知部署流程与故障上下文所有故障都发生在azd up这条主链路上。在 README.md 中部署流程明确为azd up该命令会完成两件事预配 Azure 资源Provision以及把示例部署到这些资源并把./data目录中的文件构建成搜索索引Deploy。之后每次更新只需执行azd up详见 README.md 的 Deploying again 章节。理解这一流程的意义在于下文绝大多数错误都发生在预配阶段资源创建/角色分配/容器创建只有第 4 条CERTIFICATE_VERIFY_FAILED发生在构建索引阶段prepdocs.py运行期间。故障位置不同处理手段完全不同。二、资源创建类错误1. 区域不可用Azure OpenAI 未在该区域启用或模型未启用报错现象创建资源失败提示所在区域不支持 Azure OpenAI或该区域未启用你要使用的模型。根因Azure OpenAI 的资源与模型都有明确的区域可用性矩阵。例如文档明确举例East US 2未被启用时应改用East US等已启用区域同样即使区域整体可用你选择的特定模型也可能尚未在该区域上线。解决思路核对 Azure OpenAI 模型可用性矩阵官方维护按区域展示各模型是否可用修改部署参数中的区域配置后重新azd up注意项目内多个资源可以配置不同区域如 main.bicep 中 OpenAI 资源使用openAiLocation、搜索服务使用searchServiceLocation、Cosmos DB 使用cosmosDbLocation按需分别调整。2. 配额超限最常见的是每区域资源数量配额报错现象azd up预配阶段报配额不足Quota Exceeded。根因Azure OpenAI 对每个区域/每订阅的资源数量有配额限制重复部署多个实例最容易触发每区域资源数这一项。解决思路查阅 Azure OpenAI 配额与限制官方文档在 Azure 门户中申请提高配额或把部分资源迁移到配额更充裕的区域然后重新部署。三、重复部署冲突类错误3. same resource name not allowed忘记清理软删除资源报错现象重复部署时提示资源名冲突即使你已经删除了之前创建的资源。根因Azure 对删除的资源默认保留48 小时软删除soft delete期间同名资源无法重建。反复运行示例、每次azd down后又立即重部署最容易踩中这个坑。解决思路按官方指引执行资源清理purge彻底从软删除状态移除后再重试。清理入口Azure 门户中该资源的管理资源页或参考 官方 purge 操作文档门户与 CLI 两种方式。提示第 8 条中的RESTORE_COGNITIVE_SERVICES标志是恢复软删除资源的自动化方案与本节的手动 purge 互为补充详见后文。4. RoleAssignmentExistsHTTP 409本地开发与 CI/CD 切换导致报错现象在本地开发与CI/CD 流水线之间来回切换部署时报RoleAssignmentExists错误HTTP 409。根因角色分配Role Assignment的名称由principalId、roleDefinitionId等参数通过 GUID 哈希生成。当principalType在User本地与ServicePrincipalCI/CD之间变化时GUID 也随之变化但旧的角色分配仍残留在资源上于是新角色分配与旧记录冲突。从源码可以验证这一机制infra/main.bicep 中principalType的取值逻辑为empty(runningOnGh) empty(runningOnAdo) ? User : ServicePrincipal即本地直接运行azd时为User在 GitHub Actions / ADO 流水线中为ServicePrincipal角色分配模块 infra/core/security/role.bicep 使用guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)生成资源名principalType变化会改变生成结果从而产生冲突。解决思路当前模板已为每种principalType分别生成独立的角色分配因此直接再次运行azd up即可让新的分配按新 GUID 生效从而解决冲突。5. PropertyChangeNotAllowedCosmos DB 分区键不可变报错现象在旧版本模板基础上重新部署时报PropertyChangeNotAllowed错误指向 Cosmos DB 分区键。根因Cosmos DB 的分区键在容器创建后不可修改。旧模板部署的chat-history容器使用单一/userId分区键新模板改用chat-history-v2容器并升级为 MultiHash 多分区键/entra_oid/session_id。对已存在的容器尝试修改分区键会被平台拒绝。从 infra/main.bicep 的注释与实现可以完整看到这一约束与迁移路径// WARNING: Cosmos DB partition keys are immutable. If you originally deployed with the v1 container // (chat-history with a single /userId partition key), re-deploying with the v2 container schema // (chat-history-v2 with MultiHash /entra_oid /session_id) will fail with: // Document collection partition key cannot be changed.新容器的定义在 infra/main.bicep可以看到kind: MultiHash、分区键路径为/entra_oid与/session_id并针对/entra_oid、/session_id、/timestamp、/type建立了精确索引策略。容器名参数chatHistoryContainerName默认为chat-history-v2见 infra/main.bicep。解决方案二选一删除旧容器后重新部署在 Azure 门户 Cosmos DB Data Explorer 中删除chat-history-v2容器或使用 CLIaz cosmosdb sql container delete删除后重新azd up模板会用正确的 MultiHash 分区键方案重建容器。更换容器名通过azd env set把chatHistoryContainerName覆盖为新名称例如chat-history-v3让模板创建一个全新容器。注意事项方案 1 会丢失该容器中已有的聊天历史记录方案 2 不会动旧数据但会新增一个容器。这也是项目提供 scripts/cosmosdb_migration.py 迁移脚本其new_container即指向chat-history-v2见 cosmosdb_migration.py来帮助平滑迁移旧聊天记录的原因。Bicep 无法条件性跳过容器更新这是 ARM/Cosmos DB 平台层面的限制并非模板缺陷。四、运行与恢复类错误6. CERTIFICATE_VERIFY_FAILEDprepdocs.py 阶段 SSL 证书问题报错现象azd up过程中prepdocs.py脚本运行时抛出CERTIFICATE_VERIFY_FAILED。根因这是典型的本机 SSL 证书配置不正确导致的 Python SSL 校验失败与 Azure 资源本身无关。prepdocs.py位于 app/backend/prepdocs.py负责把./data中的文档解析、分块、向量化并写入 Azure AI Search 索引过程中需要与 Azure 服务建立 HTTPS 连接本机证书链不完整就会触发该校验错误。解决思路参考社区公认的解决方案如 StackOverflow 相关回答修复本机 SSL 证书安装例如更新系统 CA 证书库、为 Python 指定正确的证书路径或使用包含完整证书链的根证书。修复本机环境后重新执行部署。7. 部署后访问网站出现 404 Not Found报错现象azd up成功完成后浏览器访问网站却返回 404。根因最常见的场景是应用仍在启动中。容器化/托管环境首次冷启动需要拉取镜像、初始化依赖短时间内请求会落到尚未就绪的实例上。解决思路按顺序执行等待 10 分钟后重试——文档明确提示这可能是仍在启动若仍失败重新执行azd deploy再次等待如果部署目标是App Service且问题依旧查阅 appservice.md 排错指南其中覆盖了日志流、诊断、重新部署等 App Service 特有手段若日志无法定位问题可在项目仓库提交 Issue 反馈附上日志。从 appservice.md 的定位看它专门服务于 App Service 部署场景若你的目标是 Azure Container Apps应优先参考 azure_container_apps.md 中对应的部署与诊断说明。8. ConflictHTTP 409Cognitive Services 资源软删除导致报错现象azd down之后再次重新部署时报 HTTP 409Conflict指向 Cognitive Services 类资源。根因Azure 对 Cognitive Services 资源含 OpenAI、Document Intelligence、Vision、Speech 等执行48 天的软删除保留期保留期内同名资源无法重建。文档明确给出这个 48 天的数字这也是此类冲突与第 3 条48 小时保留的本质区别——两者保留期长度不同。解决方案启用RESTORE_COGNITIVE_SERVICES自动恢复标志。部署前设置azd env set RESTORE_COGNITIVE_SERVICES true azd up部署完成后务必改回false以避免影响后续部署azd env set RESTORE_COGNITIVE_SERVICES false这个环境变量的传递链路在仓库中有完整实现参数映射RESTORE_COGNITIVE_SERVICES环境变量被映射到 Bicep 参数restoreCognitiveServices默认值为false见 infra/main.parameters.json参数声明param restoreCognitiveServices bool false见 infra/main.bicep实际生效该参数被传递给 5 类 Cognitive Services 类资源的部署模块包括 FoundryAI Services账号infra/main.bicep、Document Intelligenceinfra/main.bicep、Visioninfra/main.bicep、Content Understandinginfra/main.bicep以及 Speechinfra/main.bicep——这些模块统一通过restore: restoreCognitiveServices把标志传递给底层 Cognitive Services 资源定义。备选方案不用标志改为手动 purge 软删除的资源Azure 门户或 Azure CLI然后不带标志重新部署。两种方式目标一致区别在于前者自动化、后者更可控。注意azd env set写入的是 azd 环境变量只对当前 azd 环境生效因此先 true 部署、后 false 再部署的操作顺序要严格遵循避免标志长期开启。五、故障速查表与最佳实践错误阶段根因首选解法区域/模型不可用预配区域未启用 Azure OpenAI 或模型查模型可用性矩阵换区域/模型配额超限预配每区域资源数配额查配额文档申请提额或换区域资源名冲突预配软删除保留 48 小时门户/CLI 执行 purge 后重试RoleAssignmentExists409预配本地/CI 切换导致 principalType 变化直接再次azd upPropertyChangeNotAllowed预配Cosmos DB 分区键不可变删除旧容器或换容器名重部署CERTIFICATE_VERIFY_FAILED索引构建本机 SSL 证书配置错误修复本机证书链访问 404部署后应用仍在启动等待 10 分钟必要时azd deployApp Service 见 appservice.mdCognitive ServicesConflict409重部署软删除保留 48 天azd env set RESTORE_COGNITIVE_SERVICES true后azd up再改回false部署排错的最佳实践总结区分资源类型看保留期普通资源软删除保留 48 小时Cognitive Services 类资源保留 48 天两者的清理手段不同善用环境变量而非手动改文件RESTORE_COGNITIVE_SERVICES、chatHistoryContainerName等都应通过azd env set覆盖保持模板文件不被改动便于后续同步上游更新理解部署的生命周期差异本地User与 CI/CDServicePrincipal之间切换属正常操作遇到角色分配冲突时重跑azd up即可升级模板前先看数据影响涉及 Cosmos DB 这类不可变配置时先评估旧容器数据必要时用 cosmosdb_migration.py 迁移保留部署日志404 等运行态问题最终要靠日志定位App Service 场景优先查阅 appservice.md 中的日志与诊断章节。相关文档导航部署总览与 azd 使用azd up/azd down/azd env set的完整生命周期App Service 排错指南部署目标是 App Service 时的深度诊断Azure Container Apps 部署ACA 场景的部署说明部署特性说明其中也包含 Cosmos DB MultiHash 迁移的警告与交叉引用本地开发指南本地运行的前提是已成功执行过azd up部署基础架构源码restoreCognitiveServices、MultiHash 分区键、principalType等实现细节的最终依据【免费下载链接】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 QA experiences.项目地址: https://gitcode.com/GitHub_Trending/az/azure-search-openai-demo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考