1. 项目概述与核心价值最近在帮一个客户做企业级AI应用落地他们想基于Azure OpenAI服务快速搭建一个内部使用的ChatGPT风格应用同时要求具备企业级的身份认证、日志审计和对话数据持久化能力。在评估了几个方案后我们最终选择了微软官方开源的OpenAI at Scale项目作为基础。这个项目本质上是一个“样板间”它把在Azure上构建一个生产就绪的AI聊天应用所需的核心组件和最佳实践都打包好了让你能跳过从零开始的繁琐配置直接进入业务逻辑开发。简单来说这个项目提供了一个前后端分离的Web应用前端是React TypeScript构建的现代化聊天界面后端是Python Flask服务负责与Azure OpenAI API交互。它的核心价值不在于界面有多炫酷而在于它帮你解决了企业部署中最头疼的几个问题如何安全地集成Azure AD进行员工单点登录、如何将每次对话的请求和响应记录到数据库以便后续分析和审计、如何将应用日志统一收集到Azure Monitor进行监控和排错。对于想快速验证AI应用场景、或者需要为团队提供一个安全可控的AI工具平台的开发者来说这个项目是一个极佳的起点。2. 架构设计与核心组件解析2.1 整体架构拆解这个项目的架构非常清晰遵循了典型的云原生微服务设计思想但为了简化部署它将前后端整合在了一个Azure App Service中。我们来拆解一下它的核心组件和数据流。前端 (Frontend -app/frontend/):技术栈: React TypeScript Vite。核心职责: 提供用户交互界面包括聊天窗口、系统提示词设置、模型参数如温度、最大令牌数调整面板。关键模块:src/App.tsx: 应用主入口管理聊天状态和消息列表。src/components/ChatInterface.tsx: 核心聊天组件处理用户输入和消息渲染。src/auth/: 目录下包含Azure AD身份验证的配置和逻辑使用azure/msal-browser库实现前端无密码PKCE授权码流这是目前SPA应用最推荐的安全认证方式。src/api/: 封装了与后端Flask API通信的客户端函数。后端 (Backend -app/backend/):技术栈: Python Flask openaiPython SDK。核心职责: 作为安全代理和业务逻辑处理中心。API路由 (app.py)提供/api/chat等端点接收前端请求。认证中间件验证前端传来的Azure AD访问令牌Access Token确保只有合法用户才能调用OpenAI API。这一步至关重要它防止了API密钥在前端暴露。OpenAI客户端使用官方SDK将经过验证的用户请求转发给Azure OpenAI服务并接收流式或非流式的响应。日志与持久化在收到OpenAI响应前后将结构化的对话数据用户ID、会话ID、消息、令牌使用量、时间戳写入Azure Cosmos DB。同时应用运行日志如错误、请求信息会输出到标准输出由Azure App Service捕获并发送到Log Analytics。Azure 服务集成:Azure OpenAI Service: 提供GPT模型如gpt-35-turbo, gpt-4的推理能力。项目通过后端的API密钥和终结点进行访问。Azure Active Directory (AAD): 提供企业级身份认证。前端应用注册为“单页应用程序(SPA)”用户登录后前端获取访问令牌并附加到发给后端的API请求头中。Azure Cosmos DB (Core SQL API): 用作对话日志的持久化存储。选择它是因为其无模式Schema-less的JSON文档模型非常适合存储多变的聊天数据且吞吐量和延迟表现优秀。项目中使用chat_session_id作为分区键这能将同一会话的所有消息高效地存储在一起。Azure Monitor (Log Analytics): 通过配置App Service的诊断设置将平台日志如访问日志、错误日志和应用的自定义日志自动导入到Log Analytics工作区便于使用KQLKusto Query Language进行统一查询和分析。Azure App Service: 作为托管平台运行Python Flask后端并托管静态前端文件通过npm run build生成。它简化了部署、缩放和SSL管理。注意安全设计考量。这个架构的一个关键设计是API密钥不暴露给前端。前端只持有AAD的应用ID用户登录后获得的是访问后端API的令牌。而后端持有访问Azure OpenAI的密钥。这样即使前端代码被查看攻击者也无法直接盗用OpenAI API密钥所有请求都必须经过已认证的后端代理。这是构建生产级AI应用必须遵循的安全准则。2.2 环境变量与配置管理项目的配置主要通过环境变量管理这符合十二要素应用的原则。理解每个变量的作用对部署和调试至关重要。前端环境变量 (app/frontend/.env):VITE_CLIENTID: Azure AD应用注册后获得的“应用程序(客户端)ID”。前端MSAL库用它来初始化认证请求。VITE_TENANTID: Azure AD的租户ID。可以是特定租户ID也可以是common多租户应用或organizations任何组织账户。后端环境变量 (app/backend/.env):AZURE_OPENAI_SERVICE: 你的Azure OpenAI服务终结点格式如https://your-resource-name.openai.azure.com/。OPENAI_API_KEY: Azure OpenAI服务的密钥之一key1或key2。这是最敏感的信息务必妥善保管。AZURE_OPENAI_CHATGPT_DEPLOYMENT: 你在Azure OpenAI服务中部署的模型名称例如gpt-35-turbo。注意这是你自定义的部署名不一定是模型原名。AZURE_COSMOSDB_ENDPOINT,AZURE_COSMOSDB_KEY,AZURE_COSMOSDB_DB: 用于连接Azure Cosmos DB。如果留空日志持久化功能将被禁用。实操心得环境变量管理。在本地开发时直接修改.env文件很方便。但绝对不要将包含真实密钥的.env文件提交到代码仓库。项目提供的.env.sample文件就是模板。在生产环境如Azure App Service中务必通过“应用程序设置”来配置这些变量或者集成Azure Key Vault来更安全地管理密钥。在App Service中这些设置会被自动注入为环境变量。3. 从零开始的完整部署实操3.1 前期准备与资源创建假设你有一个有效的Azure订阅非免费账户因为免费账户不支持某些服务我们开始一步步部署。第一步创建资源组资源组是Azure中管理相关资源的逻辑容器。建议将所有相关资源放在同一个资源组便于管理和清理。az group create --name openai-at-scale-rg --location eastus这里选择eastus区域你需要根据Azure OpenAI服务的可用区域来选择。可以通过az cognitiveservices list-listskus --kind OpenAI --location eastus查看某个区域支持的SKU。第二步创建Azure OpenAI服务与模型部署这是核心资源。我们将通过Azure CLI创建。# 设置变量方便后续命令复用 export SUBSCRIPTION_ID你的订阅ID export RESOURCE_GROUPopenai-at-scale-rg export LOCATIONeastus export AZURE_OPENAI_SERVICEmy-ai-service-$(openssl rand -hex 3) # 生成一个随机名称确保唯一性 export AZURE_OPENAI_CHATGPT_DEPLOYMENTgpt-35-turbo-deployment # 设置当前订阅 az account set --subscription $SUBSCRIPTION_ID # 创建OpenAI认知服务账户 az cognitiveservices account create \ --name $AZURE_OPENAI_SERVICE \ --kind OpenAI \ --sku S0 \ --resource-group $RESOURCE_GROUP \ --location $LOCATION \ --yes # 在创建的服务上部署一个gpt-3.5-turbo模型 az cognitiveservices account deployment create \ -g $RESOURCE_GROUP \ -n $AZURE_OPENAI_SERVICE \ --deployment-name $AZURE_OPENAI_CHATGPT_DEPLOYMENT \ --model-name gpt-35-turbo \ --model-version 0613 \ # 使用较新的版本号如0613而非示例中的0301 --model-format OpenAI \ --scale-settings-scale-type Standard创建完成后记下你的服务名称和部署名。你需要从Azure门户获取终结点和密钥。第三步注册Azure AD应用程序这是实现身份认证的关键。登录 Azure门户 进入“Azure Active Directory”。选择“应用注册” - “新注册”。名称输入一个易识别的名称如OpenAI Chat App。支持的账户类型根据你的需求选择例如“仅此组织目录中的账户”。重定向URI这是本地开发的关键。选择“单页应用程序(SPA)”并添加两条http://localhost:5173(Vite默认开发服务器端口)http://localhost:5000(Flask默认后端端口)点击“注册”。完成后在概览页面记录“应用程序(客户端) ID”和“目录(租户) ID”。第四步可选创建Azure Cosmos DB账户如果你需要持久化聊天记录请创建此资源。export COSMOS_ACCOUNT_NAMEcosmos-account-$(openssl rand -hex 3) export COSMOS_DB_NAMEchatdb # 创建Cosmos DB账户启用无服务器容量模式以节省成本适合初期 az cosmosdb create \ -n $COSMOS_ACCOUNT_NAME \ -g $RESOURCE_GROUP \ --locations regionName$LOCATION \ --capabilities EnableServerless # 创建数据库 az cosmosdb sql database create \ -a $COSMOS_ACCOUNT_NAME \ -g $RESOURCE_GROUP \ -n $COSMOS_DB_NAME # 创建容器即表分区键为 /chat_session_id az cosmosdb sql container create \ -a $COSMOS_ACCOUNT_NAME \ -g $RESOURCE_GROUP \ -d $COSMOS_DB_NAME \ -n chat_log \ -p /chat_session_id \ --throughput 400 # 或使用 --max-throughput 1000 启用自动缩放创建后在门户的“密钥”部分获取URI和主密钥。3.2 本地开发环境配置与运行克隆代码并配置环境变量git clone https://github.com/Azure/openai-at-scale.git cd openai-at-scale配置前端环境cd app/frontend cp .env.sample .env编辑新创建的.env文件填入你的AAD应用信息VITE_CLIENTID你的应用程序(客户端) ID VITE_TENANTID你的目录(租户) ID配置后端环境cd ../backend cp .env.sample .env编辑.env文件AZURE_OPENAI_SERVICEhttps://你的服务名.openai.azure.com/ OPENAI_API_KEY你的Azure OpenAI密钥 AZURE_OPENAI_CHATGPT_DEPLOYMENT你的模型部署名 # 如果启用了Cosmos DB取消注释并填写以下内容 AZURE_COSMOSDB_ENDPOINThttps://你的Cosmos账户名.documents.azure.com:443/ AZURE_COSMOSDB_KEY你的Cosmos主密钥 AZURE_COSMOSDB_DBchatdb启动后端服务# 确保在 app/backend 目录下 python -m venv .venv # Windows: .venv\Scripts\activate # Linux/Mac: source .venv/bin/activate pip install -r requirements.txt # 启动Flask开发服务器 flask run --debug --port 5000--debug模式支持热重载修改代码后会自动重启。启动前端开发服务器打开一个新的终端窗口# 在 app/frontend 目录下 npm install npm run devVite会启动一个本地开发服务器通常运行在http://localhost:5173。现在打开浏览器访问这个地址你应该能看到登录按钮和聊天界面了。注意事项CORS问题。在本地开发时前端(localhost:5173)向后端(localhost:5000)发请求会触发跨域问题。项目在后端app.py中已经通过flask_cors配置了CORS允许来自localhost:5173的请求。如果端口有变化需要相应修改后端的CORS配置。3.3 部署到Azure App Service本地测试无误后就可以部署到生产环境了。第一步构建前端生产包前端代码需要被构建成静态文件然后由Flask后端托管。# 在 app/frontend 目录下 npm run build这个命令会在app/frontend/dist目录下生成优化后的静态文件。项目配置了Flask将app/backend/static目录作为静态文件根目录因此需要将构建产物复制过去。# 在项目根目录执行 rm -rf app/backend/static # 清理旧的静态文件 cp -r app/frontend/dist/* app/backend/static/第二步更新AAD重定向URI在Azure门户中找到之前注册的AAD应用在“身份验证”页面添加一个新的重定向URI指向你将部署的Azure Web App的URL。例如https://你的webapp名称.azurewebsites.net。同时确保“隐式授权和混合流”下的“访问令牌”和“ID令牌”被勾选对于SPA是必要的。第三步使用Azure CLI部署到App Service这是最快捷的部署方式。az webapp up命令会智能地创建所需资源并部署代码。# 确保在 app/backend 目录下且已通过 az login 登录 az webapp up --runtime python:3.10 --sku B1 -g openai-at-scale-rg -n my-openai-chat-app-$(openssl rand -hex 3)这个命令会自动创建一个名为my-openai-chat-app-xxx的App Service如果不存在。自动创建一个S1定价层的App Service计划如果不存在。将当前目录app/backend的代码打包并部署上去。自动检测Python应用并配置Gunicorn作为生产服务器。第四步配置生产环境变量部署完成后我们需要在App Service中设置环境变量对应本地的.env文件。# 获取你的Web App名称和资源组名 export WEBAPP_NAME上一步创建的Web App名称 export RESOURCE_GROUPopenai-at-scale-rg # 设置应用设置环境变量 az webapp config appsettings set --name $WEBAPP_NAME -g $RESOURCE_GROUP --settings \ AZURE_OPENAI_SERVICEhttps://你的服务名.openai.azure.com/ \ OPENAI_API_KEY你的Azure OpenAI密钥 \ AZURE_OPENAI_CHATGPT_DEPLOYMENT你的模型部署名 \ AZURE_COSMOSDB_ENDPOINThttps://你的Cosmos账户名.documents.azure.com:443/ \ AZURE_COSMOSDB_KEY你的Cosmos主密钥 \ AZURE_COSMOSDB_DBchatdb \ SCM_DO_BUILD_DURING_DEPLOYMENTfalse # 因为我们已本地构建无需在服务器上再构建设置完成后App Service会自动重启以加载新配置。现在访问https://你的webapp名称.azurewebsites.net应用应该可以正常运行了。4. 高级配置与生产就绪化4.1 集成Azure Monitor日志收集将应用日志集中收集到Log Analytics对于监控和故障排查至关重要。创建Log Analytics工作区export WORKSPACE_NAMEmy-la-workspace az monitor log-analytics workspace create --name $WORKSPACE_NAME --resource-group $RESOURCE_GROUP --location $LOCATION为App Service启用诊断设置这步配置会将App Service的平台日志HTTP日志、应用日志等自动发送到上一步创建的工作区。export APP_SERVICE_NAME你的Web App名称 export DIAG_SETTING_NAMEappservice-to-la # 获取App Service和Log Analytics工作区的资源ID export WEBAPP_RESOURCE_ID$(az webapp show -g $RESOURCE_GROUP -n $APP_SERVICE_NAME --query id -o tsv) export WORKSPACE_RESOURCE_ID$(az monitor log-analytics workspace show -g $RESOURCE_GROUP --workspace-name $WORKSPACE_NAME --query id -o tsv) # 创建诊断设置 az monitor diagnostic-settings create \ --resource $WEBAPP_RESOURCE_ID \ --workspace $WORKSPACE_RESOURCE_ID \ -n $DIAG_SETTING_NAME \ --logs [{category: AppServiceAppLogs, enabled: true}, {category: AppServicePlatformLogs, enabled: true}, {category: AppServiceConsoleLogs, enabled: true}]配置完成后你可以在Azure门户中进入Log Analytics工作区使用KQL查询日志例如AppServiceConsoleLogs | where TimeGenerated ago(1h) | project TimeGenerated, ResultDescription, _ResourceId | order by TimeGenerated desc4.2 配置自定义应用日志与Cosmos DB持久化项目本身已经将聊天记录结构化为JSON写入Cosmos DB。你可以在后端的app.py中找到相关的日志记录代码通常是在处理完OpenAI响应后。数据结构通常包含id: 唯一标识符GUID。user_id: 从AAD令牌中解析出的用户标识。chat_session_id: 前端生成的会话ID用作分区键。messages: 完整的对话消息数组。model: 使用的模型名称。usage: 令牌使用情况prompt_tokens, completion_tokens, total_tokens。timestamp: 记录创建时间。为了在生产环境更好地追踪请求建议在后端增加更详细的日志记录例如使用Python的logging模块记录每个请求的请求ID、用户、处理时间、OpenAI调用状态等。这些日志可以通过打印到标准输出stdout被App Service捕获并经由诊断设置发送到Log Analytics。一个简单的日志增强示例 在app.py中初始化日志import logging import sys from flask import request import uuid logging.basicConfig( levellogging.INFO, format%(asctime)s - %(name)s - %(levelname)s - [%(request_id)s] - %(message)s, handlers[logging.StreamHandler(sys.stdout)] ) logger logging.getLogger(__name__) # 创建一个中间件为每个请求生成ID并附加到日志记录器 app.before_request def before_request(): request.id str(uuid.uuid4()) # 可以创建一个过滤器或使用logging的extra参数这里简化处理 # 实际更复杂的场景可以使用structlog或logging的上下文变量 app.route(/api/chat, methods[POST]) def chat(): user get_current_user() # 从令牌解析用户 logger.info(fChat request received from user: {user}, extra{request_id: request.id}) # ... 处理逻辑 try: response openai_client.chat.completions.create(...) logger.info(fOpenAI call successful. Usage: {response.usage}, extra{request_id: request.id}) except Exception as e: logger.error(fOpenAI call failed: {str(e)}, extra{request_id: request.id}) return jsonify({error: Internal server error}), 500 # ... 记录到Cosmos DB logger.info(fChat log persisted to Cosmos DB. Session: {session_id}, extra{request_id: request.id}) return jsonify(response_data)4.3 网络与安全加固对于企业级应用你可能需要考虑网络隔离和私有连接。将Azure OpenAI服务和Cosmos DB配置为仅允许特定虚拟网络VNet或私有终结点访问在Azure OpenAI服务和Cosmos DB的资源页面配置“网络”设置禁用公共访问仅允许从特定VNet或通过私有终结点访问。为App Service配置VNet集成使其能够与处于同一VNet或通过VNet对等互连的其他服务如OpenAI、Cosmos DB进行通信。为Azure OpenAI和Cosmos DB创建私有终结点并将其连接到App Service所在的VNet。使用Azure Key Vault管理密钥 在生产环境中不应将API密钥等机密信息直接放在App Service的应用设置中。应使用Azure Key Vault。创建一个Key Vault。将OPENAI_API_KEY和AZURE_COSMOSDB_KEY作为机密Secret存入Key Vault。为App Service分配一个托管身份Managed Identity。在Key Vault的访问策略中授予该托管身份读取机密的权限。在App Service的应用设置中使用Key Vault引用语法来获取密钥值例如Microsoft.KeyVault(SecretUrihttps://myvault.vault.azure.net/secrets/OpenAIKey/)5. 常见问题排查与性能调优5.1 部署与运行时问题问题1本地运行前端时登录后页面白屏或报CORS错误。排查打开浏览器开发者工具F12查看“网络(Network)”和“控制台(Console)”标签页。可能原因与解决后端服务未运行确保Flask后端 (flask run) 正在localhost:5000运行。CORS配置错误检查后端app.py中CORS的配置。确保它允许前端开发服务器的源如http://localhost:5173。可以临时设置为CORS(app, origins[*])进行测试但生产环境务必指定具体域名。AAD重定向URI不匹配确保在AAD应用注册中添加了精确的http://localhost:5173或你使用的端口作为重定向URI。问题2部署到Azure App Service后访问应用出现“内部服务器错误”或无法加载。排查进入App Service的“诊断并解决问题” - “应用服务日志流”查看实时日志。可能原因与解决环境变量未正确设置在App Service的“配置”-“应用程序设置”中仔细核对所有环境变量的名称和值是否正确特别是API密钥和终结点URL确保没有多余的空格。Python依赖安装失败检查requirements.txt文件是否在根目录app/backend并且所有依赖版本兼容。可以在“部署中心”查看部署日志。有时需要指定SCM_DO_BUILD_DURING_DEPLOYMENTtrue并提供一个startup.txt文件来正确安装依赖。静态文件路径错误确保执行了npm run build并将dist目录的内容复制到了app/backend/static目录。Flask默认从static目录提供静态文件。问题3聊天请求超时或响应缓慢。排查检查后端日志和Azure OpenAI服务的“指标”页面查看请求延迟和令牌使用情况。可能原因与解决模型部署层级的限制Azure OpenAI对不同层级的部署有TPM每分钟令牌数和RPM每分钟请求数限制。如果达到限制请求会被限制。可以在Azure门户中查看你部署的“配额与限制”考虑升级到更高层级。请求/响应体过大如果对话历史很长或系统提示词非常复杂会导致请求令牌数激增增加处理时间。考虑在客户端或服务端对历史对话进行摘要或截断。后端处理瓶颈如果使用了流式响应streaming确保后端正确地处理了流式数据并即时转发给前端。非流式响应则检查Flask应用的性能考虑增加App Service的实例规格或启用自动缩放。5.2 身份认证与数据持久化问题问题4用户无法登录提示“AADSTSxxxxx”错误。排查错误代码是关键。在浏览器开发者工具的“网络”选项卡中查看登录请求的响应。常见错误AADSTS50011: 重定向URI不匹配。确保AAD应用注册中的重定向URI与前端代码中配置的redirectUri通常在authConfig.ts中完全一致包括协议http/https、域名、端口和路径。AADSTS700016: 未找到应用程序。检查VITE_CLIENTID和VITE_TENANTID是否正确以及应用是否注册在指定的租户下。问题5聊天记录没有保存到Cosmos DB。排查首先检查后端日志看是否有连接Cosmos DB的错误。其次在Azure门户中进入Cosmos DB账户使用“数据资源管理器”查看chatdb数据库下的chat_log容器是否有新文档。可能原因连接字符串错误检查AZURE_COSMOSDB_ENDPOINT和AZURE_COSMOSDB_KEY。终结点末尾的/和端口443通常需要保留。数据库/容器名称不匹配确保AZURE_COSMOSDB_DB的值与你创建的数据库名称一致且代码中引用的容器名称是chat_log。代码逻辑未执行确认后端代码中在成功获取OpenAI响应后写Cosmos DB的逻辑被正确调用并且没有因为异常而被静默处理。添加更详细的日志有助于定位。5.3 成本优化与架构扩展建议成本控制Azure OpenAI密切关注令牌使用量。在应用界面中可以展示每次对话的令牌消耗培养用户的成本意识。对于内部工具可以设置每日或每用户的使用限额需要在应用逻辑层面实现。Azure Cosmos DB如果聊天日志量不大创建时可以选择“无服务器”容量模式它按实际请求和存储收费没有最低费用。如果选择“预配吞吐量”初期设置较低的RU/s如400并启用自动缩放。Azure App Service在开发测试阶段使用B1基本或S1标准等较低定价层。生产环境根据流量预估选择合适的层级并设置自动缩放规则在非高峰时段缩减实例以节省成本。Azure MonitorLog Analytics的数据引入和保留会产生费用。可以为工作区配置每日引入上限和合适的数据保留策略例如将详细日志保留30天之后只保留聚合数据或存档到更便宜的存储。架构扩展引入缓存对于频繁使用的系统提示词或常见的用户问答对可以考虑使用Azure Cache for Redis进行缓存减少对OpenAI的调用和响应延迟。异步处理与队列如果应用需要处理大量并发或长时间运行的对话任务如生成长文档可以考虑将聊天请求放入消息队列如Azure Service Bus由后台工作进程异步处理并通过WebSocket或长轮询通知前端结果。这能提升前端响应速度避免HTTP请求超时。前端与后端分离部署当前项目将前端静态文件托管在后端Flask中。对于大型应用可以考虑将前端React单独部署到Azure Static Web Apps或Blob Storage CDN后端API部署到App Service或Azure Functions。这样能实现更好的独立缩放和性能优化。API管理如果计划对外提供API或进行更精细的流量控制、监控和版本管理可以在前端和后端之间引入Azure API Management。这个项目作为一个起点已经涵盖了企业级AI应用的核心要素。在实际使用中你会根据具体的业务需求、安全合规要求和性能目标在这些基础上进行迭代和扩展。最关键的是理解其架构思想安全的代理模式、模块化的云服务集成以及配置驱动的部署方式这能让你在Azure上构建更复杂、更健壮的AI应用时游刃有余。