1. 项目概述当Azure云服务遇上ChatGPT最近在GitHub上看到一个挺有意思的项目叫“Azure-chatGPT-demo”。光看名字你大概就能猜到它的核心玩法把微软的Azure云服务和OpenAI的ChatGPT模型结合起来做一个演示应用。这听起来像是两个热门技术的“强强联合”但具体怎么玩能玩出什么花样背后又藏着哪些值得琢磨的门道作为一个在云服务和AI应用开发领域摸爬滚打多年的老手我觉得这个项目标题背后其实指向了一个非常具体且实用的场景如何在一个企业级、安全可控的云平台上快速构建和部署一个类ChatGPT的智能对话应用。这个需求其实非常普遍。很多企业或开发者对ChatGPT的能力垂涎三尺但直接调用OpenAI的公开API可能会面临数据出境、服务稳定性、成本不可控、以及无法深度定制化等问题。而微软Azure作为全球领先的公有云平台不仅提供了强大的计算、存储和网络基础设施其Azure OpenAI Service更是直接集成了GPT系列模型让开发者可以在Azure的安全合规框架内使用这些顶尖的AI能力。这个demo项目本质上就是一个“桥梁”或“样板间”它演示了如何将这两者无缝对接快速搭建起一个可运行、可扩展的对话应用原型。所以这篇文章我会带你彻底拆解这个“Azure-chatGPT-demo”。我们不止步于“跑通demo”更要深入理解其架构设计背后的考量、每一步配置的意图、可能遇到的坑以及如何将它改造成适合你自己业务场景的“生产级”应用。无论你是想学习Azure OpenAI服务的使用还是正在规划一个企业内部的智能助手项目相信这些从一线实战中总结的经验都能给你带来实实在在的参考价值。2. 核心架构与设计思路拆解在动手写代码或点鼠标之前我们必须先想清楚这个demo的骨架。一个典型的、基于云服务的AI应用其核心无外乎几个部分前端界面、后端服务、AI模型接口、以及将它们串联起来的云基础设施。Azure-chatGPT-demo的设计思路正是围绕这几个核心组件在Azure的生态内寻找最优解。2.1 为什么选择Azure OpenAI Service而非直接调用OpenAI API这是整个项目最根本的决策点。直接调用OpenAI的APIapi.openai.com看似最简单但存在几个关键限制合规与数据安全对于许多企业尤其是金融、医疗、政务等敏感行业数据不能随意出境。通过Azure OpenAI Service你的数据和请求全程在微软Azure的数据中心内处理满足了数据驻留和隐私保护的要求。服务等级协议SLA与稳定性Azure为OpenAI服务提供了企业级的SLA保障这意味着更可靠的服务可用性和技术支持。而公开API的稳定性在流量高峰时可能无法保证。网络与性能如果你的其他服务如用户数据库、业务系统也部署在Azure上那么通过Azure内部网络调用OpenAI服务延迟会更低速度更快且没有公网流量费用。成本管理与整合费用可以直接纳入你的Azure账单统一管理、分析和优化。同时可以利用Azure的监控、安全中心、密钥保管库等原生服务实现更精细化的运维和安全管控。因此这个demo选择Azure OpenAI Service作为AI引擎是面向企业级应用场景的必然选择。它牺牲了一点“开箱即用”的便捷性换来了可控性、安全性和可扩展性。2.2 典型技术栈选型分析基于上述核心决策项目的技术栈也就呼之欲出了。一个合理的Azure-chatGPT-demo可能会包含以下层次前端层为了快速演示和降低门槛很可能会选择一个轻量级的Web框架。Streamlit是一个极佳的选择。它允许你用纯Python快速构建交互式Web应用几行代码就能做出一个聊天界面特别适合数据科学家和AI工程师做原型验证。当然如果追求更定制化的UI也可能用React或Vue.js配合一个简单的后端API。后端/应用层这是业务逻辑的核心。它需要处理前端请求、调用Azure OpenAI接口、管理对话历史、可能还要进行一些简单的预处理或后处理如敏感词过滤、日志记录。由于主要逻辑是调用API用PythonFlask/FastAPI或Node.jsExpress来构建一个轻量级API服务是最常见的。AI服务层核心就是Azure OpenAI Service。你需要在其上部署一个Chat模型通常是gpt-35-turbo或gpt-4。这一层的关键在于如何安全、高效地通过Azure的SDK或REST API进行调用。基础设施层全部由Microsoft Azure云服务承载。这包括计算资源用于运行前端和后端代码。可能是Azure App ServicePaaS无需管理服务器、Azure Container InstancesACI或Azure Kubernetes ServiceAKS容器化部署、甚至是一台简单的Azure Virtual Machine虚拟机。安全与配置使用Azure Key Vault来存储和管理OpenAI API密钥等敏感信息而不是硬编码在代码中。使用Azure Active Directory (AAD)或托管标识来进行服务间的安全认证。监控与运维利用Azure Monitor和Application Insights来收集应用日志、性能指标和AI服务的调用情况。这个demo的价值就在于它提供了一个将这些分散的Azure服务与AI能力“粘合”在一起的可运行范例。它告诉你每一步该去哪里创建资源、如何配置、代码里该怎么写连接字符串和API调用。3. 环境准备与Azure资源创建实操理论清晰了我们开始动手。在运行任何代码之前我们必须在Azure门户上把“舞台”搭好。这个过程稍显繁琐但每一步都关系到后续应用的稳定和安全。3.1 Azure订阅与资源组规划首先你需要一个有效的Azure订阅。如果没有可以去Azure官网注册通常有免费额度可供试用。登录Azure门户后第一件事不是直接创建服务而是创建一个资源组。注意资源组是Azure中管理相关资源的逻辑容器。将本项目所有资源OpenAI服务、App Service、Key Vault等放在同一个资源组下便于统一管理、监控和成本核算未来删除时也能一键清理。在门户顶部的搜索栏输入“资源组”进入服务后点击“创建”。给你的资源组起个名字例如rg-chatgpt-demo并选择一个离你的目标用户较近的区域如East US或Southeast Asia。3.2 创建并配置Azure OpenAI Service资源这是核心中的核心。在门户搜索“Azure OpenAI”进入服务页面点击“创建”。基础设置订阅选择你的订阅。资源组选择上一步创建的rg-chatgpt-demo。区域同样选择与你资源组一致或合适的区域。并非所有区域都支持Azure OpenAI请在下拉列表中确认通常East US、West Europe、Southeast Asia是可用区。名称起一个全局唯一的资源名如oai-demo-001。这个名字会出现在终结点URL中。定价层选择S0标准层。这是按使用量付费的层级适合开发和测试。网络与身份验证在“网络”部分初期为了简化可以先选择“所有网络”包括互联网都可以访问。但在生产环境中务必配置为“仅选定网络”并通过VNet或私有终结点来限制访问这是保障安全的关键一步。点击“审阅 创建”通过验证后点击“创建”。部署过程可能需要几分钟。部署模型 资源创建成功后进入该资源。在左侧菜单中找到“模型部署”点击“管理部署”。点击“创建新部署”。选择模型从下拉列表中选择一个聊天模型。对于demogpt-35-turbo是性价比和性能的最佳平衡选择其最新版本如gpt-35-turbo-0125。部署名称这个名称非常重要它不是你刚才创建的资源名而是这个模型实例在你资源内的一个标识。起一个简短好记的名字例如gpt-35-turbo-demo。后续代码中调用API时指定的就是这个名字。点击“创建”。模型部署通常很快。获取关键信息 部署完成后你需要记录三个关键信息它们相当于打开AI大门的钥匙终结点在资源的“概览”页面找到“终结点”格式类似https://oai-demo-001.openai.azure.com/。API密钥在左侧菜单“密钥和终结点”中有两个密钥Key1和Key2任选一个即可。请务必妥善保管不要泄露或提交到代码仓库。部署名称就是你上一步设置的例如gpt-35-turbo-demo。3.3 创建Azure Key Vault保管密钥将API密钥硬编码在代码或环境变量文件中是极不安全的行为。最佳实践是使用Azure Key Vault。在门户搜索“Key Vault”点击创建。关联到你的资源组rg-chatgpt-demo起名如kv-chatgpt-secrets区域保持一致。其他设置可保持默认点击“审阅 创建”并部署。进入创建好的Key Vault在左侧“对象”下选择“机密”然后点击“生成/导入”。上传选项选择“手动”。名称输入一个标识如OpenAI-Api-Key。值粘贴你刚才复制的Azure OpenAI API密钥。点击“创建”。现在你的密钥安全地存储在了Key Vault中。为了让你的应用比如后续部署的App Service能读取它你需要分配访问策略。在Key Vault的左侧菜单进入“访问策略”。点击“创建访问策略”。在“机密权限”中至少勾选“获取”和“列出”。在“选择主体”中搜索并选择你计划使用的身份例如一个Azure AD应用注册或者系统分配的托管标识。这是安全配置的难点和重点我们稍后在应用部署部分会详细展开。3.4 规划应用托管方案你的应用代码需要跑在某个地方。对于demo我们有几种高性价比的选择Azure App Service推荐这是PaaS服务你只需上传代码Azure负责服务器、运行时、扩缩容等所有运维。非常适合Web应用原型。我们可以创建一个“Web 应用”。本地开发在本地运行调试通过配置环境变量或本地认证来访问Azure服务。这是开发阶段的主要方式。Azure Container Instances (ACI)如果你将应用Docker容器化了ACI可以快速启动一个容器实例按秒计费适合临时性任务或简单演示。为了完整走通流程我们以部署到Azure App Service为目标进行准备。你可以在开发完成后再决定是否部署。至此我们的“云上基础设施”已经准备就绪。接下来就是编写连接这一切的“胶水代码”。4. 应用开发与核心代码实现解析现在我们进入编码环节。我将以一个典型的Python后端FastAPI配合Streamlit前端的架构为例详细拆解每一部分代码的写法和背后的逻辑。4.1 项目结构与依赖管理首先创建一个清晰的项目目录结构azure-chatgpt-demo/ ├── backend/ │ ├── app.py # FastAPI 主应用 │ ├── requirements.txt # Python依赖 │ └── .env.example # 环境变量示例文件 ├── frontend/ │ └── streamlit_app.py # Streamlit 前端应用 ├── dockerfile # 可选容器化部署文件 └── README.md后端requirements.txt文件应包含fastapi0.104.1 uvicorn[standard]0.24.0 openai1.6.1 python-dotenv1.0.0 azure-identity1.15.0 azure-keyvault-secrets4.7.0这里的关键库是openai新版SDK同时支持OpenAI和Azure OpenAI和azure-identity用于从Azure Key Vault安全获取密钥。4.2 后端API服务实现FastAPIbackend/app.py是这个应用的大脑它负责接收聊天请求调用Azure OpenAI并返回结果。import os from typing import List, Optional from fastapi import FastAPI, HTTPException from fastapi.middleware.cors import CORSMiddleware from pydantic import BaseModel from openai import AzureOpenAI from azure.identity import DefaultAzureCredential from azure.keyvault.secrets import SecretClient from dotenv import load_dotenv # 加载本地开发环境变量生产环境由Azure App Service配置 load_dotenv() app FastAPI(titleAzure ChatGPT Demo API) # 配置CORS允许前端跨域请求在生产环境中应严格限制来源 app.add_middleware( CORSMiddleware, allow_origins[*], # 开发阶段允许所有生产环境需指定前端地址 allow_credentialsTrue, allow_methods[*], allow_headers[*], ) # 定义请求和响应的数据模型 class ChatMessage(BaseModel): role: str # user, assistant, system content: str class ChatRequest(BaseModel): messages: List[ChatMessage] max_tokens: Optional[int] 500 temperature: Optional[float] 0.7 class ChatResponse(BaseModel): reply: str model: str usage: Optional[dict] None # 初始化Azure OpenAI客户端 def get_openai_client(): 安全地初始化Azure OpenAI客户端。 开发环境从环境变量读取配置。 生产环境从Azure Key Vault获取API密钥使用托管标识认证。 # 从环境变量获取基础配置终结点、部署名、Key Vault URL azure_openai_endpoint os.getenv(AZURE_OPENAI_ENDPOINT) deployment_name os.getenv(AZURE_OPENAI_DEPLOYMENT_NAME) key_vault_url os.getenv(AZURE_KEY_VAULT_URL) secret_name os.getenv(AZURE_KEY_VAULT_SECRET_NAME, OpenAI-Api-Key) api_key None # 判断环境如果设置了Key Vault URL则尝试从Key Vault获取密钥生产环境逻辑 if key_vault_url: try: # 使用DefaultAzureCredential它在不同环境本地、Azure VM、App Service下会自动选择最合适的认证方式 credential DefaultAzureCredential() secret_client SecretClient(vault_urlkey_vault_url, credentialcredential) retrieved_secret secret_client.get_secret(secret_name) api_key retrieved_secret.value print(Successfully retrieved API key from Azure Key Vault.) except Exception as e: print(fFailed to get secret from Key Vault: {e}. Falling back to environment variable.) # 降级方案从环境变量读取仅用于开发或备用 api_key os.getenv(AZURE_OPENAI_API_KEY) else: # 开发环境直接从环境变量读取 api_key os.getenv(AZURE_OPENAI_API_KEY) if not all([azure_openai_endpoint, deployment_name, api_key]): raise ValueError(Missing required Azure OpenAI configuration. Please check your environment variables.) # 初始化新版OpenAI SDK的Azure客户端 client AzureOpenAI( azure_endpointazure_openai_endpoint, api_keyapi_key, api_version2024-02-15-preview # 使用稳定的API版本 ) return client, deployment_name # 全局初始化客户端或使用依赖注入这里简化处理 openai_client, openai_deployment get_openai_client() app.post(/chat, response_modelChatResponse) async def chat_completion(request: ChatRequest): 核心聊天接口。 接收消息历史调用Azure OpenAI的Chat Completion API返回助手回复。 try: # 调用Azure OpenAI API response openai_client.chat.completions.create( modelopenai_deployment, # 这里传入的是部署名称不是模型名称 messages[msg.dict() for msg in request.messages], max_tokensrequest.max_tokens, temperaturerequest.temperature, ) # 解析响应 reply response.choices[0].message.content model_used response.model usage response.usage.dict() if response.usage else None return ChatResponse(replyreply, modelmodel_used, usageusage) except Exception as e: # 记录详细错误日志生产环境应接入Application Insights print(fError calling Azure OpenAI: {e}) raise HTTPException(status_code500, detailfInternal server error: {str(e)}) app.get(/health) async def health_check(): 健康检查端点用于负载均衡器或监控系统探活。 return {status: healthy, service: azure-chatgpt-api} if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)代码关键点解析安全密钥管理get_openai_client函数是安全核心。它优先尝试从Azure Key Vault获取API密钥使用DefaultAzureCredential进行无密码认证失败则回退到环境变量。这确保了生产环境中密钥不落地。新版SDK使用使用了OpenAI官方Python SDK (openai1.0.0)它对Azure和OpenAI的原生API进行了统一封装。初始化时使用AzureOpenAI类并指定azure_endpoint。API版本api_version参数至关重要必须指定一个与你的Azure OpenAI资源支持的、且稳定的版本。不同版本可能有细微差异。模型参数在chat.completions.create中model参数应填入你在Azure门户创建的部署名称如gpt-35-turbo-demo而不是基础的模型名称如gpt-3.5-turbo。这是Azure OpenAI与原生OpenAI API的一个重要区别。错误处理与日志对API调用进行了异常捕获并返回500错误。在生产环境中应将错误日志发送到Azure Monitor或Application Insights。4.3 前端交互界面实现Streamlitfrontend/streamlit_app.py提供了一个极其简单直观的聊天界面。import streamlit as st import requests import json from typing import List, Dict # 配置页面 st.set_page_config(page_titleAzure ChatGPT Demo, page_icon, layoutwide) st.title( Azure-Powered ChatGPT Demo) st.caption(This demo connects to GPT models securely via Azure OpenAI Service.) # 初始化会话状态用于保存聊天历史 if messages not in st.session_state: st.session_state.messages [ {role: system, content: You are a helpful AI assistant.}, {role: assistant, content: Hello! Im your AI assistant powered by Azure OpenAI. How can I help you today?} ] # 侧边栏用于配置和说明 with st.sidebar: st.header(Configuration) # 在实际项目中后端地址应通过环境变量配置。这里为了demo简化允许用户输入或使用默认值。 backend_url st.text_input( Backend API URL, valuest.secrets.get(BACKEND_URL, http://localhost:8000), # 优先从Streamlit secrets读取 helpURL of your FastAPI backend server. ) max_tokens st.slider(Max Response Length (tokens), min_value50, max_value2000, value500, step50) temperature st.slider(Creativity (Temperature), min_value0.0, max_value2.0, value0.7, step0.1) st.divider() st.markdown( **About this Demo:** - Frontend: Streamlit - Backend: FastAPI (Python) - AI Service: Azure OpenAI (GPT-3.5/4) - Secure Key Management: Azure Key Vault ) if st.button(Clear Chat History): st.session_state.messages [ {role: system, content: You are a helpful AI assistant.}, {role: assistant, content: Chat history cleared. How can I assist you?} ] st.rerun() # 主聊天区域显示历史消息 chat_container st.container() with chat_container: for message in st.session_state.messages: if message[role] in [user, assistant]: # 不显示system消息 with st.chat_message(message[role]): st.markdown(message[content]) # 底部聊天输入框 if prompt : st.chat_input(Type your message here...): # 将用户输入添加到会话历史并立即显示 st.session_state.messages.append({role: user, content: prompt}) with st.chat_message(user): st.markdown(prompt) # 准备调用后端API with st.chat_message(assistant): message_placeholder st.empty() # 创建一个占位符用于流式显示简化版先显示加载中 message_placeholder.markdown(Thinking...) try: # 构建请求数据排除system消息可选根据后端实现决定 # 通常建议将system消息也发送给API以保持上下文一致性 api_messages [{role: msg[role], content: msg[content]} for msg in st.session_state.messages] payload { messages: api_messages, max_tokens: max_tokens, temperature: temperature } # 发送POST请求到后端 response requests.post( f{backend_url.rstrip(/)}/chat, jsonpayload, headers{Content-Type: application/json}, timeout60 # 设置超时时间 ) response.raise_for_status() # 如果状态码不是200抛出异常 result response.json() assistant_reply result[reply] # 更新占位符为最终回复 message_placeholder.markdown(assistant_reply) # 将助手回复添加到会话历史 st.session_state.messages.append({role: assistant, content: assistant_reply}) except requests.exceptions.RequestException as e: message_placeholder.markdown(f**Error connecting to backend:** {e}) except json.JSONDecodeError: message_placeholder.markdown(**Error: Invalid response from server.**) except KeyError: message_placeholder.markdown(**Error: Unexpected response format.**) except Exception as e: message_placeholder.markdown(f**An unexpected error occurred:** {e}) # 在页面底部显示当前会话的token数估算简单估算 st.sidebar.divider() total_chars sum(len(msg[content]) for msg in st.session_state.messages) estimated_tokens total_chars // 4 # 粗略估算1个token约等于4个英文字符 st.sidebar.metric(Estimated Tokens in Context, f{estimated_tokens:,})前端实现要点会话状态管理Streamlit的st.session_state用于在页面重载间保持聊天历史这是构建对话式应用的关键。配置分离后端API地址通过侧边栏输入或st.secrets管理提高了灵活性。st.secrets是Streamlit Cloud安全存储配置的方式本地开发对应.streamlit/secrets.toml文件。用户体验包含了消息历史展示、加载状态提示、错误处理以及清空历史的功能提供了一个完整的聊天体验。简易监控侧边栏底部估算当前上下文消耗的token数让用户对使用量有个直观感受。4.4 环境变量与本地运行在本地开发时我们需要配置环境变量。在backend目录下创建.env文件并确保它在.gitignore中# For Local Development (using direct API Key) AZURE_OPENAI_ENDPOINThttps://your-resource-name.openai.azure.com/ AZURE_OPENAI_DEPLOYMENT_NAMEgpt-35-turbo-demo AZURE_OPENAI_API_KEYyour-azure-openai-api-key-here # For Production (using Key Vault) - Comment out in local dev # AZURE_KEY_VAULT_URLhttps://kv-chatgpt-secrets.vault.azure.net/ # AZURE_KEY_VAULT_SECRET_NAMEOpenAI-Api-Key然后在backend目录下运行pip install -r requirements.txt uvicorn app:app --reload --host 0.0.0.0 --port 8000在另一个终端进入frontend目录创建.streamlit/secrets.toml用于Streamlit配置BACKEND_URL http://localhost:8000然后运行streamlit run streamlit_app.py现在打开浏览器访问http://localhost:8501你应该能看到聊天界面并能与部署在Azure上的GPT模型对话了。5. 部署到Azure App Service与生产化配置让应用在本地跑起来只是第一步。将其部署到Azure云上并配置为生产环境才是项目的最终目标。这里我们选择Azure App Service因为它管理简单能自动处理缩放、负载均衡和HTTPS。5.1 将应用容器化Docker虽然App Service支持直接部署源代码或Wheel包但使用Docker容器能提供最好的环境一致性和控制力。在项目根目录创建Dockerfile# 使用官方Python运行时作为父镜像 FROM python:3.11-slim # 设置工作目录 WORKDIR /app # 复制依赖定义文件并安装依赖 COPY backend/requirements.txt . RUN pip install --no-cache-dir --upgrade pip \ pip install --no-cache-dir -r requirements.txt # 复制后端应用代码 COPY backend/ ./backend/ # 复制前端Streamlit应用代码 COPY frontend/ ./frontend/ # 创建一个启动脚本同时运行后端和前端生产环境建议分开部署这里为demo简化 # 更佳实践是使用supervisor或两个独立的容器 COPY start.sh . RUN chmod x start.sh # 暴露端口后端8000前端8501 EXPOSE 8000 8501 # 定义环境变量可在App Service设置中覆盖 ENV PYTHONPATH/app/backend ENV STREAMLIT_SERVER_PORT8501 ENV STREAMLIT_SERVER_HEADLESStrue # 启动应用 CMD [./start.sh]创建start.sh脚本#!/bin/bash # 启动后端FastAPI服务在后台运行 cd /app/backend uvicorn app:app --host 0.0.0.0 --port 8000 # 启动前端Streamlit服务在前台运行便于日志捕获 cd /app/frontend streamlit run streamlit_app.py --server.port 8501 --server.address 0.0.0.0注意在生产环境中将前后端放在同一个容器并同时运行并非最佳实践。更好的做法是将它们部署为两个独立的App Service Web应用或者使用Azure Container Apps等支持多容器编排的服务。这里为了demo的简洁性我们放在一起。5.2 构建并推送Docker镜像到Azure Container Registry (ACR)创建ACR在Azure门户创建容器注册表ACR例如acrdemoregistry.azurecr.io选择“基本”SKU即可。本地构建与推送# 登录到你的ACR az acr login --name acrdemoregistry # 构建Docker镜像 docker build -t azure-chatgpt-demo . # 标记镜像 docker tag azure-chatgpt-demo acrdemoregistry.azurecr.io/azure-chatgpt-demo:v1 # 推送镜像 docker push acrdemoregistry.azurecr.io/azure-chatgpt-demo:v15.3 创建并配置Azure App Service创建Web应用在Azure门户搜索“App Services”点击“创建”。发布选择“Docker 容器”。操作系统Linux。区域与你的资源组一致。在“Docker”选项卡中镜像来源选择“Azure Container Registry”。注册表选择你刚创建的ACR。镜像选择azure-chatgpt-demo。标签选择v1。点击“审阅 创建”然后创建。配置环境变量应用设置这是连接所有服务的关键。进入创建好的App Service在左侧菜单找到“配置”-“应用程序设置”。添加以下设置注意这里不再需要AZURE_OPENAI_API_KEY因为我们将使用Key Vault引用AZURE_OPENAI_ENDPOINT你的Azure OpenAI终结点URL。AZURE_OPENAI_DEPLOYMENT_NAME你的模型部署名称。AZURE_KEY_VAULT_URL你的Key Vault的URL如https://kv-chatgpt-secrets.vault.azure.net/。AZURE_KEY_VAULT_SECRET_NAMEOpenAI-Api-Key或你存储密钥时使用的名称。WEBSITES_PORT设置为8501因为我们的Streamlit前端运行在8501端口。为App Service分配托管标识并授权访问Key Vault在App Service的“标识”设置中开启“系统分配”的托管标识。保存后Azure会为你的应用自动创建一个服务主体。回到你的Azure Key Vault资源进入“访问策略”。点击“创建访问策略”。在“机密权限”中勾选“获取”和“列出”。点击“选择主体”在搜索框中输入你的App Service名称选择它对应的托管标识通常显示为你的App Service名。点击“添加”然后“保存”。现在你的App Service应用在运行时其代码中的DefaultAzureCredential()就能自动使用这个托管标识来向Key Vault进行认证而无需任何硬编码的密钥。配置自定义域名与HTTPS可选但推荐在App Service的“自定义域”中绑定你自己的域名并启用免费的App Service托管证书确保通信安全。部署完成后访问你的App Service URL格式为https://your-app-name.azurewebsites.net你的Azure ChatGPT Demo就应该在云端正常运行了6. 监控、优化与成本控制应用上线后工作并未结束。监控其运行状态、优化性能并控制成本是确保项目可持续的关键。6.1 利用Azure Monitor进行全方位监控Application Insights集成在创建App Service时或之后启用Application Insights。它会自动收集应用日志、性能指标响应时间、请求率和异常信息。在你的Python代码中集成opentelemetrySDK可以发送自定义追踪和日志。Azure OpenAI服务监控在Azure OpenAI资源中有“监视”-“指标”页面。这里可以查看关键指标如Total Calls总调用次数。Total Tokens消耗的总token数区分提示和完成。Successful Calls成功调用数。结合“失败调用”可以监控服务健康度。设置警报为关键指标设置警报。例如当“失败调用”率在5分钟内超过1%时发送邮件或短信通知。当“总token”消耗接近月度预算时发出预警。6.2 性能与体验优化技巧流式响应Streaming当前的实现是等待AI生成完整回复后再返回用户需要等待。Azure OpenAI API支持流式响应streamTrue。你可以修改后端API使用Server-Sent Events (SSE) 或WebSocket将token逐个推送到前端实现类似ChatGPT的打字机效果极大提升用户体验。对话历史管理GPT模型有上下文窗口限制例如gpt-35-turbo通常是16K或128K tokens。当对话轮次增多历史消息会消耗大量token并可能超出限制。需要实现智能的“上下文窗口滑动”或“摘要”功能只保留最近N条消息或对早期历史进行摘要以节省成本和保持相关性。缓存常见回答对于一些通用、确定性的问题如“你是谁”、“怎么用”可以在应用层或使用Azure Cache for Redis缓存回答避免重复调用AI模型降低成本和延迟。合理设置API参数max_tokens根据场景设置合理的上限避免生成过于冗长的无用内容。temperature控制创造性。对于事实性问答设置较低值如0.2对于创意写作可以调高如0.8-1.0。top_p(核采样)与temperature类似是另一种控制随机性的方法通常二者选一即可。6.3 成本控制与预算管理AI模型的调用是项目的主要成本。必须精细化管理设置预算和警报在Azure成本管理计费中为包含OpenAI资源的订阅或资源组设置月度预算。当成本达到预算的50%、90%、100%时触发警报。分析使用模式定期查看Azure OpenAI的“使用情况”报告了解哪些部署被频繁调用哪些用户或会话消耗token最多。这有助于优化提示词设计或进行用量配额管理。选择合适的模型和层级gpt-35-turbo的成本远低于gpt-4。在非必需场景下使用更经济的模型。Azure OpenAI还提供了不同上下文长度的版本选择适合你场景的版本。实施用量配额和限流在你的后端API网关或应用逻辑中对终端用户或API密钥实施速率限制如每分钟N次请求和每日用量配额防止滥用或意外的高消耗。7. 常见问题排查与安全加固实录在实际开发和运维中你一定会遇到各种问题。以下是我从经验中总结的一些典型“坑”及其解决方案。7.1 身份认证与权限问题这是部署阶段最常见的问题。问题现象可能原因排查步骤与解决方案本地运行正常部署到Azure后出现401或403错误提示认证失败。1. App Service的托管标识未正确配置或未启用。2. Key Vault的访问策略未授予该托管标识权限。3. 环境变量AZURE_KEY_VAULT_URL配置错误。1. 确认App Service“标识”中系统分配托管标识状态为“开”。2. 进入Key Vault“访问策略”确认已为该App Service的托管标识添加了“获取”和“列出”机密权限。3. 在App Service的“控制台”(Kudu)或通过SSH连接执行env命令确认环境变量值正确无误。错误信息提及“DefaultAzureCredential failed to retrieve a token”。DefaultAzureCredential尝试了多种认证方式环境变量、托管标识、Visual Studio、Azure CLI等都失败了。1.在Azure环境中确保托管标识已分配且Key Vault策略正确。重启App Service使身份生效。2.在本地开发确保你已通过az login登录Azure CLI或者设置了AZURE_TENANT_ID,AZURE_CLIENT_ID,AZURE_CLIENT_SECRET等环境变量。可以临时在代码中打印DefaultAzureCredential尝试的凭证来源来调试。可以获取Key Vault密钥但调用Azure OpenAI时仍报401。获取到的API密钥本身已过期或无效或者Azure OpenAI资源的终结点/部署名错误。1. 登录Azure门户在Key Vault中验证机密的值是否正确即有效的OpenAI API密钥。2. 在Azure OpenAI资源中检查“密钥和终结点”页面的密钥是否与Key Vault中存储的一致。可以尝试在门户的“游乐场”中测试API是否正常工作。7.2 网络与连接性问题问题现象可能原因排查步骤与解决方案应用无法连接到Azure OpenAI服务超时或连接被拒绝。1. Azure OpenAI资源的防火墙规则限制了访问。2. App Service出站IP被Azure OpenAI资源拒绝。3. 区域不匹配导致高延迟或内部路由问题。1. 检查Azure OpenAI资源的“网络”设置。如果是“仅选定网络”你需要将App Service的出站IP地址在App Service属性中查看添加到允许列表中或者更佳方案是配置VNet集成和私有终结点。2. 确保App Service和Azure OpenAI资源位于同一个Azure区域以获得最佳性能和避免跨区域流量费用。前端能打开但点击发送后长时间无响应最终报错。后端API调用Azure OpenAI超时。Azure OpenAI的响应时间受模型、提示长度、当前负载影响。1. 在后端代码中增加timeout参数。OpenAI SDK和requests库都支持设置超时如30秒。2. 在前端增加加载状态和用户提示管理用户预期。3. 考虑实现异步处理对于长文本生成可以改为提交任务通过轮询或WebSocket获取结果。7.3 应用逻辑与配置问题问题现象可能原因排查步骤与解决方案调用成功但AI回复的内容不符合预期或总是重复系统提示。1.messages列表格式错误或角色role设置不对。2.system消息被意外过滤或未发送。3.temperature参数设置过高或过低。1. 检查发送给API的messages列表。确保它是一个字典列表每个字典包含role和content键。role必须是system,user,assistant之一。2. 确保system消息在列表开头它用于设定助手的行为基调。3. 调整temperature0.7是平衡值和top_p参数。对于确定性回答可尝试temperature0.2。提示“上下文长度超出限制”。累计的对话历史包括所有消息的token数超过了所选模型的上下文窗口上限。1. 在发送请求前估算token数可用tiktoken库。2. 实现上下文管理只保留最近N轮对话或者当token数接近上限时尝试对最早的历史消息进行摘要可以调用AI生成摘要然后用摘要替换原有长历史。Docker容器在App Service上启动失败。1. Docker镜像构建有问题。2. 启动命令或端口配置错误。3. 容器内应用崩溃。1. 查看App Service的“容器设置”确保镜像和标签正确。2. 检查Dockerfile中的EXPOSE和CMD指令。App Service默认会监听PORT环境变量指定的端口通常为80我们的start.sh需要让Streamlit监听这个端口或者配置WEBSITES_PORT环境变量。3. 查看App Service的“日志流”或“容器日志”这里会有详细的启动失败错误信息。7.4 安全加固 checklist当demo准备投入生产时必须进行安全加固[ ]网络隔离将Azure OpenAI服务和App Service放入同一个虚拟网络VNet并使用私有终结点进行连接确保流量不经过公网。[ ]密钥管理绝对禁止将任何密钥、连接字符串硬编码在代码或Docker镜像中。坚持使用Azure Key Vault。[ ]访问控制使用Azure AD对前端应用或API进行身份认证和授权例如集成Microsoft Entra ID。为不同用户设置不同的访问权限。[ ]输入验证与过滤在后端API对所有用户输入进行严格的验证、清理和过滤防止提示词注入攻击Prompt Injection。[ ]输出内容审查对AI生成的内容进行审查可以集成Azure Content Safety服务过滤有害、偏见或不适当的内容。[ ]启用诊断日志确保App Service、Key Vault、Azure OpenAI的所有诊断日志都开启并发送到Log Analytics工作区便于审计和故障排查。[ ]定期轮换密钥在Key Vault中设置密钥的自动轮换策略即使密钥泄露也能将影响降到最低。走通一个demo或许只需要几小时但将其打磨成一个稳定、安全、高效的生产级应用则需要持续的关注和上述这些细致的运维工作。这个Azure-chatGPT-demo项目就像一个乐高套装的基础图纸它展示了所有核心零件如何拼接。而你能用它搭建出怎样的城堡则完全取决于你对这些零件特性的深入理解和对整体架构的持续优化。希望这篇超详细的拆解能成为你手中那份强大的改装指南。
基于Azure OpenAI与Key Vault构建企业级ChatGPT应用实战
发布时间：2026/5/15 14:46:36
1. 项目概述当Azure云服务遇上ChatGPT最近在GitHub上看到一个挺有意思的项目叫“Azure-chatGPT-demo”。光看名字你大概就能猜到它的核心玩法把微软的Azure云服务和OpenAI的ChatGPT模型结合起来做一个演示应用。这听起来像是两个热门技术的“强强联合”但具体怎么玩能玩出什么花样背后又藏着哪些值得琢磨的门道作为一个在云服务和AI应用开发领域摸爬滚打多年的老手我觉得这个项目标题背后其实指向了一个非常具体且实用的场景如何在一个企业级、安全可控的云平台上快速构建和部署一个类ChatGPT的智能对话应用。这个需求其实非常普遍。很多企业或开发者对ChatGPT的能力垂涎三尺但直接调用OpenAI的公开API可能会面临数据出境、服务稳定性、成本不可控、以及无法深度定制化等问题。而微软Azure作为全球领先的公有云平台不仅提供了强大的计算、存储和网络基础设施其Azure OpenAI Service更是直接集成了GPT系列模型让开发者可以在Azure的安全合规框架内使用这些顶尖的AI能力。这个demo项目本质上就是一个“桥梁”或“样板间”它演示了如何将这两者无缝对接快速搭建起一个可运行、可扩展的对话应用原型。所以这篇文章我会带你彻底拆解这个“Azure-chatGPT-demo”。我们不止步于“跑通demo”更要深入理解其架构设计背后的考量、每一步配置的意图、可能遇到的坑以及如何将它改造成适合你自己业务场景的“生产级”应用。无论你是想学习Azure OpenAI服务的使用还是正在规划一个企业内部的智能助手项目相信这些从一线实战中总结的经验都能给你带来实实在在的参考价值。2. 核心架构与设计思路拆解在动手写代码或点鼠标之前我们必须先想清楚这个demo的骨架。一个典型的、基于云服务的AI应用其核心无外乎几个部分前端界面、后端服务、AI模型接口、以及将它们串联起来的云基础设施。Azure-chatGPT-demo的设计思路正是围绕这几个核心组件在Azure的生态内寻找最优解。2.1 为什么选择Azure OpenAI Service而非直接调用OpenAI API这是整个项目最根本的决策点。直接调用OpenAI的APIapi.openai.com看似最简单但存在几个关键限制合规与数据安全对于许多企业尤其是金融、医疗、政务等敏感行业数据不能随意出境。通过Azure OpenAI Service你的数据和请求全程在微软Azure的数据中心内处理满足了数据驻留和隐私保护的要求。服务等级协议SLA与稳定性Azure为OpenAI服务提供了企业级的SLA保障这意味着更可靠的服务可用性和技术支持。而公开API的稳定性在流量高峰时可能无法保证。网络与性能如果你的其他服务如用户数据库、业务系统也部署在Azure上那么通过Azure内部网络调用OpenAI服务延迟会更低速度更快且没有公网流量费用。成本管理与整合费用可以直接纳入你的Azure账单统一管理、分析和优化。同时可以利用Azure的监控、安全中心、密钥保管库等原生服务实现更精细化的运维和安全管控。因此这个demo选择Azure OpenAI Service作为AI引擎是面向企业级应用场景的必然选择。它牺牲了一点“开箱即用”的便捷性换来了可控性、安全性和可扩展性。2.2 典型技术栈选型分析基于上述核心决策项目的技术栈也就呼之欲出了。一个合理的Azure-chatGPT-demo可能会包含以下层次前端层为了快速演示和降低门槛很可能会选择一个轻量级的Web框架。Streamlit是一个极佳的选择。它允许你用纯Python快速构建交互式Web应用几行代码就能做出一个聊天界面特别适合数据科学家和AI工程师做原型验证。当然如果追求更定制化的UI也可能用React或Vue.js配合一个简单的后端API。后端/应用层这是业务逻辑的核心。它需要处理前端请求、调用Azure OpenAI接口、管理对话历史、可能还要进行一些简单的预处理或后处理如敏感词过滤、日志记录。由于主要逻辑是调用API用PythonFlask/FastAPI或Node.jsExpress来构建一个轻量级API服务是最常见的。AI服务层核心就是Azure OpenAI Service。你需要在其上部署一个Chat模型通常是gpt-35-turbo或gpt-4。这一层的关键在于如何安全、高效地通过Azure的SDK或REST API进行调用。基础设施层全部由Microsoft Azure云服务承载。这包括计算资源用于运行前端和后端代码。可能是Azure App ServicePaaS无需管理服务器、Azure Container InstancesACI或Azure Kubernetes ServiceAKS容器化部署、甚至是一台简单的Azure Virtual Machine虚拟机。安全与配置使用Azure Key Vault来存储和管理OpenAI API密钥等敏感信息而不是硬编码在代码中。使用Azure Active Directory (AAD)或托管标识来进行服务间的安全认证。监控与运维利用Azure Monitor和Application Insights来收集应用日志、性能指标和AI服务的调用情况。这个demo的价值就在于它提供了一个将这些分散的Azure服务与AI能力“粘合”在一起的可运行范例。它告诉你每一步该去哪里创建资源、如何配置、代码里该怎么写连接字符串和API调用。3. 环境准备与Azure资源创建实操理论清晰了我们开始动手。在运行任何代码之前我们必须在Azure门户上把“舞台”搭好。这个过程稍显繁琐但每一步都关系到后续应用的稳定和安全。3.1 Azure订阅与资源组规划首先你需要一个有效的Azure订阅。如果没有可以去Azure官网注册通常有免费额度可供试用。登录Azure门户后第一件事不是直接创建服务而是创建一个资源组。注意资源组是Azure中管理相关资源的逻辑容器。将本项目所有资源OpenAI服务、App Service、Key Vault等放在同一个资源组下便于统一管理、监控和成本核算未来删除时也能一键清理。在门户顶部的搜索栏输入“资源组”进入服务后点击“创建”。给你的资源组起个名字例如rg-chatgpt-demo并选择一个离你的目标用户较近的区域如East US或Southeast Asia。3.2 创建并配置Azure OpenAI Service资源这是核心中的核心。在门户搜索“Azure OpenAI”进入服务页面点击“创建”。基础设置订阅选择你的订阅。资源组选择上一步创建的rg-chatgpt-demo。区域同样选择与你资源组一致或合适的区域。并非所有区域都支持Azure OpenAI请在下拉列表中确认通常East US、West Europe、Southeast Asia是可用区。名称起一个全局唯一的资源名如oai-demo-001。这个名字会出现在终结点URL中。定价层选择S0标准层。这是按使用量付费的层级适合开发和测试。网络与身份验证在“网络”部分初期为了简化可以先选择“所有网络”包括互联网都可以访问。但在生产环境中务必配置为“仅选定网络”并通过VNet或私有终结点来限制访问这是保障安全的关键一步。点击“审阅 创建”通过验证后点击“创建”。部署过程可能需要几分钟。部署模型 资源创建成功后进入该资源。在左侧菜单中找到“模型部署”点击“管理部署”。点击“创建新部署”。选择模型从下拉列表中选择一个聊天模型。对于demogpt-35-turbo是性价比和性能的最佳平衡选择其最新版本如gpt-35-turbo-0125。部署名称这个名称非常重要它不是你刚才创建的资源名而是这个模型实例在你资源内的一个标识。起一个简短好记的名字例如gpt-35-turbo-demo。后续代码中调用API时指定的就是这个名字。点击“创建”。模型部署通常很快。获取关键信息 部署完成后你需要记录三个关键信息它们相当于打开AI大门的钥匙终结点在资源的“概览”页面找到“终结点”格式类似https://oai-demo-001.openai.azure.com/。API密钥在左侧菜单“密钥和终结点”中有两个密钥Key1和Key2任选一个即可。请务必妥善保管不要泄露或提交到代码仓库。部署名称就是你上一步设置的例如gpt-35-turbo-demo。3.3 创建Azure Key Vault保管密钥将API密钥硬编码在代码或环境变量文件中是极不安全的行为。最佳实践是使用Azure Key Vault。在门户搜索“Key Vault”点击创建。关联到你的资源组rg-chatgpt-demo起名如kv-chatgpt-secrets区域保持一致。其他设置可保持默认点击“审阅 创建”并部署。进入创建好的Key Vault在左侧“对象”下选择“机密”然后点击“生成/导入”。上传选项选择“手动”。名称输入一个标识如OpenAI-Api-Key。值粘贴你刚才复制的Azure OpenAI API密钥。点击“创建”。现在你的密钥安全地存储在了Key Vault中。为了让你的应用比如后续部署的App Service能读取它你需要分配访问策略。在Key Vault的左侧菜单进入“访问策略”。点击“创建访问策略”。在“机密权限”中至少勾选“获取”和“列出”。在“选择主体”中搜索并选择你计划使用的身份例如一个Azure AD应用注册或者系统分配的托管标识。这是安全配置的难点和重点我们稍后在应用部署部分会详细展开。3.4 规划应用托管方案你的应用代码需要跑在某个地方。对于demo我们有几种高性价比的选择Azure App Service推荐这是PaaS服务你只需上传代码Azure负责服务器、运行时、扩缩容等所有运维。非常适合Web应用原型。我们可以创建一个“Web 应用”。本地开发在本地运行调试通过配置环境变量或本地认证来访问Azure服务。这是开发阶段的主要方式。Azure Container Instances (ACI)如果你将应用Docker容器化了ACI可以快速启动一个容器实例按秒计费适合临时性任务或简单演示。为了完整走通流程我们以部署到Azure App Service为目标进行准备。你可以在开发完成后再决定是否部署。至此我们的“云上基础设施”已经准备就绪。接下来就是编写连接这一切的“胶水代码”。4. 应用开发与核心代码实现解析现在我们进入编码环节。我将以一个典型的Python后端FastAPI配合Streamlit前端的架构为例详细拆解每一部分代码的写法和背后的逻辑。4.1 项目结构与依赖管理首先创建一个清晰的项目目录结构azure-chatgpt-demo/ ├── backend/ │ ├── app.py # FastAPI 主应用 │ ├── requirements.txt # Python依赖 │ └── .env.example # 环境变量示例文件 ├── frontend/ │ └── streamlit_app.py # Streamlit 前端应用 ├── dockerfile # 可选容器化部署文件 └── README.md后端requirements.txt文件应包含fastapi0.104.1 uvicorn[standard]0.24.0 openai1.6.1 python-dotenv1.0.0 azure-identity1.15.0 azure-keyvault-secrets4.7.0这里的关键库是openai新版SDK同时支持OpenAI和Azure OpenAI和azure-identity用于从Azure Key Vault安全获取密钥。4.2 后端API服务实现FastAPIbackend/app.py是这个应用的大脑它负责接收聊天请求调用Azure OpenAI并返回结果。import os from typing import List, Optional from fastapi import FastAPI, HTTPException from fastapi.middleware.cors import CORSMiddleware from pydantic import BaseModel from openai import AzureOpenAI from azure.identity import DefaultAzureCredential from azure.keyvault.secrets import SecretClient from dotenv import load_dotenv # 加载本地开发环境变量生产环境由Azure App Service配置 load_dotenv() app FastAPI(titleAzure ChatGPT Demo API) # 配置CORS允许前端跨域请求在生产环境中应严格限制来源 app.add_middleware( CORSMiddleware, allow_origins[*], # 开发阶段允许所有生产环境需指定前端地址 allow_credentialsTrue, allow_methods[*], allow_headers[*], ) # 定义请求和响应的数据模型 class ChatMessage(BaseModel): role: str # user, assistant, system content: str class ChatRequest(BaseModel): messages: List[ChatMessage] max_tokens: Optional[int] 500 temperature: Optional[float] 0.7 class ChatResponse(BaseModel): reply: str model: str usage: Optional[dict] None # 初始化Azure OpenAI客户端 def get_openai_client(): 安全地初始化Azure OpenAI客户端。 开发环境从环境变量读取配置。 生产环境从Azure Key Vault获取API密钥使用托管标识认证。 # 从环境变量获取基础配置终结点、部署名、Key Vault URL azure_openai_endpoint os.getenv(AZURE_OPENAI_ENDPOINT) deployment_name os.getenv(AZURE_OPENAI_DEPLOYMENT_NAME) key_vault_url os.getenv(AZURE_KEY_VAULT_URL) secret_name os.getenv(AZURE_KEY_VAULT_SECRET_NAME, OpenAI-Api-Key) api_key None # 判断环境如果设置了Key Vault URL则尝试从Key Vault获取密钥生产环境逻辑 if key_vault_url: try: # 使用DefaultAzureCredential它在不同环境本地、Azure VM、App Service下会自动选择最合适的认证方式 credential DefaultAzureCredential() secret_client SecretClient(vault_urlkey_vault_url, credentialcredential) retrieved_secret secret_client.get_secret(secret_name) api_key retrieved_secret.value print(Successfully retrieved API key from Azure Key Vault.) except Exception as e: print(fFailed to get secret from Key Vault: {e}. Falling back to environment variable.) # 降级方案从环境变量读取仅用于开发或备用 api_key os.getenv(AZURE_OPENAI_API_KEY) else: # 开发环境直接从环境变量读取 api_key os.getenv(AZURE_OPENAI_API_KEY) if not all([azure_openai_endpoint, deployment_name, api_key]): raise ValueError(Missing required Azure OpenAI configuration. Please check your environment variables.) # 初始化新版OpenAI SDK的Azure客户端 client AzureOpenAI( azure_endpointazure_openai_endpoint, api_keyapi_key, api_version2024-02-15-preview # 使用稳定的API版本 ) return client, deployment_name # 全局初始化客户端或使用依赖注入这里简化处理 openai_client, openai_deployment get_openai_client() app.post(/chat, response_modelChatResponse) async def chat_completion(request: ChatRequest): 核心聊天接口。 接收消息历史调用Azure OpenAI的Chat Completion API返回助手回复。 try: # 调用Azure OpenAI API response openai_client.chat.completions.create( modelopenai_deployment, # 这里传入的是部署名称不是模型名称 messages[msg.dict() for msg in request.messages], max_tokensrequest.max_tokens, temperaturerequest.temperature, ) # 解析响应 reply response.choices[0].message.content model_used response.model usage response.usage.dict() if response.usage else None return ChatResponse(replyreply, modelmodel_used, usageusage) except Exception as e: # 记录详细错误日志生产环境应接入Application Insights print(fError calling Azure OpenAI: {e}) raise HTTPException(status_code500, detailfInternal server error: {str(e)}) app.get(/health) async def health_check(): 健康检查端点用于负载均衡器或监控系统探活。 return {status: healthy, service: azure-chatgpt-api} if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)代码关键点解析安全密钥管理get_openai_client函数是安全核心。它优先尝试从Azure Key Vault获取API密钥使用DefaultAzureCredential进行无密码认证失败则回退到环境变量。这确保了生产环境中密钥不落地。新版SDK使用使用了OpenAI官方Python SDK (openai1.0.0)它对Azure和OpenAI的原生API进行了统一封装。初始化时使用AzureOpenAI类并指定azure_endpoint。API版本api_version参数至关重要必须指定一个与你的Azure OpenAI资源支持的、且稳定的版本。不同版本可能有细微差异。模型参数在chat.completions.create中model参数应填入你在Azure门户创建的部署名称如gpt-35-turbo-demo而不是基础的模型名称如gpt-3.5-turbo。这是Azure OpenAI与原生OpenAI API的一个重要区别。错误处理与日志对API调用进行了异常捕获并返回500错误。在生产环境中应将错误日志发送到Azure Monitor或Application Insights。4.3 前端交互界面实现Streamlitfrontend/streamlit_app.py提供了一个极其简单直观的聊天界面。import streamlit as st import requests import json from typing import List, Dict # 配置页面 st.set_page_config(page_titleAzure ChatGPT Demo, page_icon, layoutwide) st.title( Azure-Powered ChatGPT Demo) st.caption(This demo connects to GPT models securely via Azure OpenAI Service.) # 初始化会话状态用于保存聊天历史 if messages not in st.session_state: st.session_state.messages [ {role: system, content: You are a helpful AI assistant.}, {role: assistant, content: Hello! Im your AI assistant powered by Azure OpenAI. How can I help you today?} ] # 侧边栏用于配置和说明 with st.sidebar: st.header(Configuration) # 在实际项目中后端地址应通过环境变量配置。这里为了demo简化允许用户输入或使用默认值。 backend_url st.text_input( Backend API URL, valuest.secrets.get(BACKEND_URL, http://localhost:8000), # 优先从Streamlit secrets读取 helpURL of your FastAPI backend server. ) max_tokens st.slider(Max Response Length (tokens), min_value50, max_value2000, value500, step50) temperature st.slider(Creativity (Temperature), min_value0.0, max_value2.0, value0.7, step0.1) st.divider() st.markdown( **About this Demo:** - Frontend: Streamlit - Backend: FastAPI (Python) - AI Service: Azure OpenAI (GPT-3.5/4) - Secure Key Management: Azure Key Vault ) if st.button(Clear Chat History): st.session_state.messages [ {role: system, content: You are a helpful AI assistant.}, {role: assistant, content: Chat history cleared. How can I assist you?} ] st.rerun() # 主聊天区域显示历史消息 chat_container st.container() with chat_container: for message in st.session_state.messages: if message[role] in [user, assistant]: # 不显示system消息 with st.chat_message(message[role]): st.markdown(message[content]) # 底部聊天输入框 if prompt : st.chat_input(Type your message here...): # 将用户输入添加到会话历史并立即显示 st.session_state.messages.append({role: user, content: prompt}) with st.chat_message(user): st.markdown(prompt) # 准备调用后端API with st.chat_message(assistant): message_placeholder st.empty() # 创建一个占位符用于流式显示简化版先显示加载中 message_placeholder.markdown(Thinking...) try: # 构建请求数据排除system消息可选根据后端实现决定 # 通常建议将system消息也发送给API以保持上下文一致性 api_messages [{role: msg[role], content: msg[content]} for msg in st.session_state.messages] payload { messages: api_messages, max_tokens: max_tokens, temperature: temperature } # 发送POST请求到后端 response requests.post( f{backend_url.rstrip(/)}/chat, jsonpayload, headers{Content-Type: application/json}, timeout60 # 设置超时时间 ) response.raise_for_status() # 如果状态码不是200抛出异常 result response.json() assistant_reply result[reply] # 更新占位符为最终回复 message_placeholder.markdown(assistant_reply) # 将助手回复添加到会话历史 st.session_state.messages.append({role: assistant, content: assistant_reply}) except requests.exceptions.RequestException as e: message_placeholder.markdown(f**Error connecting to backend:** {e}) except json.JSONDecodeError: message_placeholder.markdown(**Error: Invalid response from server.**) except KeyError: message_placeholder.markdown(**Error: Unexpected response format.**) except Exception as e: message_placeholder.markdown(f**An unexpected error occurred:** {e}) # 在页面底部显示当前会话的token数估算简单估算 st.sidebar.divider() total_chars sum(len(msg[content]) for msg in st.session_state.messages) estimated_tokens total_chars // 4 # 粗略估算1个token约等于4个英文字符 st.sidebar.metric(Estimated Tokens in Context, f{estimated_tokens:,})前端实现要点会话状态管理Streamlit的st.session_state用于在页面重载间保持聊天历史这是构建对话式应用的关键。配置分离后端API地址通过侧边栏输入或st.secrets管理提高了灵活性。st.secrets是Streamlit Cloud安全存储配置的方式本地开发对应.streamlit/secrets.toml文件。用户体验包含了消息历史展示、加载状态提示、错误处理以及清空历史的功能提供了一个完整的聊天体验。简易监控侧边栏底部估算当前上下文消耗的token数让用户对使用量有个直观感受。4.4 环境变量与本地运行在本地开发时我们需要配置环境变量。在backend目录下创建.env文件并确保它在.gitignore中# For Local Development (using direct API Key) AZURE_OPENAI_ENDPOINThttps://your-resource-name.openai.azure.com/ AZURE_OPENAI_DEPLOYMENT_NAMEgpt-35-turbo-demo AZURE_OPENAI_API_KEYyour-azure-openai-api-key-here # For Production (using Key Vault) - Comment out in local dev # AZURE_KEY_VAULT_URLhttps://kv-chatgpt-secrets.vault.azure.net/ # AZURE_KEY_VAULT_SECRET_NAMEOpenAI-Api-Key然后在backend目录下运行pip install -r requirements.txt uvicorn app:app --reload --host 0.0.0.0 --port 8000在另一个终端进入frontend目录创建.streamlit/secrets.toml用于Streamlit配置BACKEND_URL http://localhost:8000然后运行streamlit run streamlit_app.py现在打开浏览器访问http://localhost:8501你应该能看到聊天界面并能与部署在Azure上的GPT模型对话了。5. 部署到Azure App Service与生产化配置让应用在本地跑起来只是第一步。将其部署到Azure云上并配置为生产环境才是项目的最终目标。这里我们选择Azure App Service因为它管理简单能自动处理缩放、负载均衡和HTTPS。5.1 将应用容器化Docker虽然App Service支持直接部署源代码或Wheel包但使用Docker容器能提供最好的环境一致性和控制力。在项目根目录创建Dockerfile# 使用官方Python运行时作为父镜像 FROM python:3.11-slim # 设置工作目录 WORKDIR /app # 复制依赖定义文件并安装依赖 COPY backend/requirements.txt . RUN pip install --no-cache-dir --upgrade pip \ pip install --no-cache-dir -r requirements.txt # 复制后端应用代码 COPY backend/ ./backend/ # 复制前端Streamlit应用代码 COPY frontend/ ./frontend/ # 创建一个启动脚本同时运行后端和前端生产环境建议分开部署这里为demo简化 # 更佳实践是使用supervisor或两个独立的容器 COPY start.sh . RUN chmod x start.sh # 暴露端口后端8000前端8501 EXPOSE 8000 8501 # 定义环境变量可在App Service设置中覆盖 ENV PYTHONPATH/app/backend ENV STREAMLIT_SERVER_PORT8501 ENV STREAMLIT_SERVER_HEADLESStrue # 启动应用 CMD [./start.sh]创建start.sh脚本#!/bin/bash # 启动后端FastAPI服务在后台运行 cd /app/backend uvicorn app:app --host 0.0.0.0 --port 8000 # 启动前端Streamlit服务在前台运行便于日志捕获 cd /app/frontend streamlit run streamlit_app.py --server.port 8501 --server.address 0.0.0.0注意在生产环境中将前后端放在同一个容器并同时运行并非最佳实践。更好的做法是将它们部署为两个独立的App Service Web应用或者使用Azure Container Apps等支持多容器编排的服务。这里为了demo的简洁性我们放在一起。5.2 构建并推送Docker镜像到Azure Container Registry (ACR)创建ACR在Azure门户创建容器注册表ACR例如acrdemoregistry.azurecr.io选择“基本”SKU即可。本地构建与推送# 登录到你的ACR az acr login --name acrdemoregistry # 构建Docker镜像 docker build -t azure-chatgpt-demo . # 标记镜像 docker tag azure-chatgpt-demo acrdemoregistry.azurecr.io/azure-chatgpt-demo:v1 # 推送镜像 docker push acrdemoregistry.azurecr.io/azure-chatgpt-demo:v15.3 创建并配置Azure App Service创建Web应用在Azure门户搜索“App Services”点击“创建”。发布选择“Docker 容器”。操作系统Linux。区域与你的资源组一致。在“Docker”选项卡中镜像来源选择“Azure Container Registry”。注册表选择你刚创建的ACR。镜像选择azure-chatgpt-demo。标签选择v1。点击“审阅 创建”然后创建。配置环境变量应用设置这是连接所有服务的关键。进入创建好的App Service在左侧菜单找到“配置”-“应用程序设置”。添加以下设置注意这里不再需要AZURE_OPENAI_API_KEY因为我们将使用Key Vault引用AZURE_OPENAI_ENDPOINT你的Azure OpenAI终结点URL。AZURE_OPENAI_DEPLOYMENT_NAME你的模型部署名称。AZURE_KEY_VAULT_URL你的Key Vault的URL如https://kv-chatgpt-secrets.vault.azure.net/。AZURE_KEY_VAULT_SECRET_NAMEOpenAI-Api-Key或你存储密钥时使用的名称。WEBSITES_PORT设置为8501因为我们的Streamlit前端运行在8501端口。为App Service分配托管标识并授权访问Key Vault在App Service的“标识”设置中开启“系统分配”的托管标识。保存后Azure会为你的应用自动创建一个服务主体。回到你的Azure Key Vault资源进入“访问策略”。点击“创建访问策略”。在“机密权限”中勾选“获取”和“列出”。点击“选择主体”在搜索框中输入你的App Service名称选择它对应的托管标识通常显示为你的App Service名。点击“添加”然后“保存”。现在你的App Service应用在运行时其代码中的DefaultAzureCredential()就能自动使用这个托管标识来向Key Vault进行认证而无需任何硬编码的密钥。配置自定义域名与HTTPS可选但推荐在App Service的“自定义域”中绑定你自己的域名并启用免费的App Service托管证书确保通信安全。部署完成后访问你的App Service URL格式为https://your-app-name.azurewebsites.net你的Azure ChatGPT Demo就应该在云端正常运行了6. 监控、优化与成本控制应用上线后工作并未结束。监控其运行状态、优化性能并控制成本是确保项目可持续的关键。6.1 利用Azure Monitor进行全方位监控Application Insights集成在创建App Service时或之后启用Application Insights。它会自动收集应用日志、性能指标响应时间、请求率和异常信息。在你的Python代码中集成opentelemetrySDK可以发送自定义追踪和日志。Azure OpenAI服务监控在Azure OpenAI资源中有“监视”-“指标”页面。这里可以查看关键指标如Total Calls总调用次数。Total Tokens消耗的总token数区分提示和完成。Successful Calls成功调用数。结合“失败调用”可以监控服务健康度。设置警报为关键指标设置警报。例如当“失败调用”率在5分钟内超过1%时发送邮件或短信通知。当“总token”消耗接近月度预算时发出预警。6.2 性能与体验优化技巧流式响应Streaming当前的实现是等待AI生成完整回复后再返回用户需要等待。Azure OpenAI API支持流式响应streamTrue。你可以修改后端API使用Server-Sent Events (SSE) 或WebSocket将token逐个推送到前端实现类似ChatGPT的打字机效果极大提升用户体验。对话历史管理GPT模型有上下文窗口限制例如gpt-35-turbo通常是16K或128K tokens。当对话轮次增多历史消息会消耗大量token并可能超出限制。需要实现智能的“上下文窗口滑动”或“摘要”功能只保留最近N条消息或对早期历史进行摘要以节省成本和保持相关性。缓存常见回答对于一些通用、确定性的问题如“你是谁”、“怎么用”可以在应用层或使用Azure Cache for Redis缓存回答避免重复调用AI模型降低成本和延迟。合理设置API参数max_tokens根据场景设置合理的上限避免生成过于冗长的无用内容。temperature控制创造性。对于事实性问答设置较低值如0.2对于创意写作可以调高如0.8-1.0。top_p(核采样)与temperature类似是另一种控制随机性的方法通常二者选一即可。6.3 成本控制与预算管理AI模型的调用是项目的主要成本。必须精细化管理设置预算和警报在Azure成本管理计费中为包含OpenAI资源的订阅或资源组设置月度预算。当成本达到预算的50%、90%、100%时触发警报。分析使用模式定期查看Azure OpenAI的“使用情况”报告了解哪些部署被频繁调用哪些用户或会话消耗token最多。这有助于优化提示词设计或进行用量配额管理。选择合适的模型和层级gpt-35-turbo的成本远低于gpt-4。在非必需场景下使用更经济的模型。Azure OpenAI还提供了不同上下文长度的版本选择适合你场景的版本。实施用量配额和限流在你的后端API网关或应用逻辑中对终端用户或API密钥实施速率限制如每分钟N次请求和每日用量配额防止滥用或意外的高消耗。7. 常见问题排查与安全加固实录在实际开发和运维中你一定会遇到各种问题。以下是我从经验中总结的一些典型“坑”及其解决方案。7.1 身份认证与权限问题这是部署阶段最常见的问题。问题现象可能原因排查步骤与解决方案本地运行正常部署到Azure后出现401或403错误提示认证失败。1. App Service的托管标识未正确配置或未启用。2. Key Vault的访问策略未授予该托管标识权限。3. 环境变量AZURE_KEY_VAULT_URL配置错误。1. 确认App Service“标识”中系统分配托管标识状态为“开”。2. 进入Key Vault“访问策略”确认已为该App Service的托管标识添加了“获取”和“列出”机密权限。3. 在App Service的“控制台”(Kudu)或通过SSH连接执行env命令确认环境变量值正确无误。错误信息提及“DefaultAzureCredential failed to retrieve a token”。DefaultAzureCredential尝试了多种认证方式环境变量、托管标识、Visual Studio、Azure CLI等都失败了。1.在Azure环境中确保托管标识已分配且Key Vault策略正确。重启App Service使身份生效。2.在本地开发确保你已通过az login登录Azure CLI或者设置了AZURE_TENANT_ID,AZURE_CLIENT_ID,AZURE_CLIENT_SECRET等环境变量。可以临时在代码中打印DefaultAzureCredential尝试的凭证来源来调试。可以获取Key Vault密钥但调用Azure OpenAI时仍报401。获取到的API密钥本身已过期或无效或者Azure OpenAI资源的终结点/部署名错误。1. 登录Azure门户在Key Vault中验证机密的值是否正确即有效的OpenAI API密钥。2. 在Azure OpenAI资源中检查“密钥和终结点”页面的密钥是否与Key Vault中存储的一致。可以尝试在门户的“游乐场”中测试API是否正常工作。7.2 网络与连接性问题问题现象可能原因排查步骤与解决方案应用无法连接到Azure OpenAI服务超时或连接被拒绝。1. Azure OpenAI资源的防火墙规则限制了访问。2. App Service出站IP被Azure OpenAI资源拒绝。3. 区域不匹配导致高延迟或内部路由问题。1. 检查Azure OpenAI资源的“网络”设置。如果是“仅选定网络”你需要将App Service的出站IP地址在App Service属性中查看添加到允许列表中或者更佳方案是配置VNet集成和私有终结点。2. 确保App Service和Azure OpenAI资源位于同一个Azure区域以获得最佳性能和避免跨区域流量费用。前端能打开但点击发送后长时间无响应最终报错。后端API调用Azure OpenAI超时。Azure OpenAI的响应时间受模型、提示长度、当前负载影响。1. 在后端代码中增加timeout参数。OpenAI SDK和requests库都支持设置超时如30秒。2. 在前端增加加载状态和用户提示管理用户预期。3. 考虑实现异步处理对于长文本生成可以改为提交任务通过轮询或WebSocket获取结果。7.3 应用逻辑与配置问题问题现象可能原因排查步骤与解决方案调用成功但AI回复的内容不符合预期或总是重复系统提示。1.messages列表格式错误或角色role设置不对。2.system消息被意外过滤或未发送。3.temperature参数设置过高或过低。1. 检查发送给API的messages列表。确保它是一个字典列表每个字典包含role和content键。role必须是system,user,assistant之一。2. 确保system消息在列表开头它用于设定助手的行为基调。3. 调整temperature0.7是平衡值和top_p参数。对于确定性回答可尝试temperature0.2。提示“上下文长度超出限制”。累计的对话历史包括所有消息的token数超过了所选模型的上下文窗口上限。1. 在发送请求前估算token数可用tiktoken库。2. 实现上下文管理只保留最近N轮对话或者当token数接近上限时尝试对最早的历史消息进行摘要可以调用AI生成摘要然后用摘要替换原有长历史。Docker容器在App Service上启动失败。1. Docker镜像构建有问题。2. 启动命令或端口配置错误。3. 容器内应用崩溃。1. 查看App Service的“容器设置”确保镜像和标签正确。2. 检查Dockerfile中的EXPOSE和CMD指令。App Service默认会监听PORT环境变量指定的端口通常为80我们的start.sh需要让Streamlit监听这个端口或者配置WEBSITES_PORT环境变量。3. 查看App Service的“日志流”或“容器日志”这里会有详细的启动失败错误信息。7.4 安全加固 checklist当demo准备投入生产时必须进行安全加固[ ]网络隔离将Azure OpenAI服务和App Service放入同一个虚拟网络VNet并使用私有终结点进行连接确保流量不经过公网。[ ]密钥管理绝对禁止将任何密钥、连接字符串硬编码在代码或Docker镜像中。坚持使用Azure Key Vault。[ ]访问控制使用Azure AD对前端应用或API进行身份认证和授权例如集成Microsoft Entra ID。为不同用户设置不同的访问权限。[ ]输入验证与过滤在后端API对所有用户输入进行严格的验证、清理和过滤防止提示词注入攻击Prompt Injection。[ ]输出内容审查对AI生成的内容进行审查可以集成Azure Content Safety服务过滤有害、偏见或不适当的内容。[ ]启用诊断日志确保App Service、Key Vault、Azure OpenAI的所有诊断日志都开启并发送到Log Analytics工作区便于审计和故障排查。[ ]定期轮换密钥在Key Vault中设置密钥的自动轮换策略即使密钥泄露也能将影响降到最低。走通一个demo或许只需要几小时但将其打磨成一个稳定、安全、高效的生产级应用则需要持续的关注和上述这些细致的运维工作。这个Azure-chatGPT-demo项目就像一个乐高套装的基础图纸它展示了所有核心零件如何拼接。而你能用它搭建出怎样的城堡则完全取决于你对这些零件特性的深入理解和对整体架构的持续优化。希望这篇超详细的拆解能成为你手中那份强大的改装指南。
相关文章
专业级Linux打印解决方案：foo2zjs驱动深度配置指南
专业级Linux打印解决方案：foo2zjs驱动深度配置指南 【免费下载链接】foo2zjs A linux printer driver for QPDL protocol - copy of http://foo2zjs.rkkda.com/ 项目地址: https://gitcode.com/gh_mirrors/fo/foo2zjs 核心关键词：foo2zjs Linux打…
Livox MID-70从零到一：ROS环境下的数据采集与可视化实战
1. Livox MID-70初识与环境准备 第一次拿到Livox MID-70这款固态激光雷达时，说实话有点懵。这个看起来像个小盒子的设备，居然能实现360全向扫描？后来实测发现，它的确能在100米范围内实现厘米级精度，而且点云密度比传统…
B站视频下载完整指南：如何快速掌握BilibiliDown免费开源工具
B站视频下载完整指南：如何快速掌握BilibiliDown免费开源工具 【免费下载链接】BilibiliDown (GUI-多平台支持) B站 哔哩哔哩 视频下载器。支持稍后再看、收藏夹、UP主视频批量下载|Bilibili Video Downloader 😳 项目地址: https://gitcode.com/gh_mir…
【信息科学与工程学】【制造工程】【通信工程】第一百零一篇 2nm 200Tbps+核心交换机全尺度参数宇宙构建框架02
编号 尺度/层级 参数类型 参数名称 数学表达式/物理模型/关联描述 典型值/范围 (目标) 单位 核心关联参数 依赖关系 互斥/协同/传递关系 设计/制造/应用要求 测试/验证方法 关联学科/领域 Switch-692 整机/电磁兼容 独立参数 整机对浪涌（冲击）抗扰度的线-线…
如何使用Git进行项目的版本控制
1.首先在gitee上创建一个本地仓库2.在本地你有一个项目，进到项目里右键git bash here ,在弹出的命令框内git init 初始化一个本地仓库3.将本地仓库与gitee的仓库进行连接 git remote add origin 再加上gitee的仓库的地址，这样本地仓库和gitee的仓库就连接…
如何用Mermaid CLI彻底改变技术文档工作流
如何用Mermaid CLI彻底改变技术文档工作流 【免费下载链接】mermaid-cli Command line tool for the Mermaid library 项目地址: https://gitcode.com/gh_mirrors/me/mermaid-cli 在技术文档编写过程中，图表创建往往是效率瓶颈。传统绘图工具需要手动拖拽、反…
构建多智能体工作流时利用Taotoken统一调度不同模型
🚀 告别海外账号与网络限制！稳定直连全球优质大模型，限时半价接入中。 👉 点击领取海量免费额度 构建多智能体工作流时利用Taotoken统一调度不同模型 在构建包含多个智能体的复杂应用时，一个常见的工程挑战是如何高效…
RISC-V ISA 特权架构0_分层特权架构概述
基本概念因为本文是概述篇,所以通过直译文档,结合个人理解给出.①应用程序使用ABI(application binary interface,应用程序二进制接口)运行.ABI包含了用户级ISA和一组与AEE(application execution environment,应用程序执行环境)交互的接口.ABI对应用程序隐藏了AEE细节,以便在实…
LunaTranslator终极指南：如何快速实现视觉小说实时翻译与语言学习
LunaTranslator终极指南：如何快速实现视觉小说实时翻译与语言学习 【免费下载链接】LunaTranslator 视觉小说翻译器 / Visual Novel Translator 项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator LunaTranslator是一款开源的视觉小说翻译工…
【2026】新高考英语大纲词汇表3500个电子版PDF（含正序版、乱序版和默写版）
高中英语大纲词汇表（2026年版）内容说明 词汇收录标准 严格遵循高中英语教学大纲要求，精选3500个核心词汇，全面覆盖高中阶段英语学习的基础词汇与进阶词汇。 版本分类及功能 版本类型编排特点主要功能正序版按字母顺序排列系统…
【最新v2.7.1 版本】零代码无命令！OpenClaw 零基础快速部署保姆级实战教程
OpenClaw（小龙虾）Windows 一键部署保姆级教程 | 10 分钟搭建专属数字员工 前言 2026 年开源圈热门 AI 智能体 OpenClaw（昵称小龙虾），GitHub 星标突破 28 万，凭借本地运行 零代码操作 智能自动执行收获大…
别再只用HashMap了！用Java BitSet和布隆过滤器处理亿级数据去重，内存省了90%
亿级数据去重的终极武器：Java BitSet与布隆过滤器实战手册 当你的JVM内存被一个简单的用户ID去重任务撑爆时，当你的日志分析系统因为HashSet的过度内存消耗而崩溃时，是时候重新审视那些被我们忽视的空间压缩神器了。本文将带你深入两种能够将…
贾子理论与AI时代文明竞争：从暴力计算到本质贯通的范式重构
贾子理论与AI时代文明竞争：从暴力计算到本质贯通的范式重构摘要本文基于贾子理论的文明竞争视角，揭示中美AI战略差异的本质并非技术参数较量，而是“暴力计算”与“本质贯通”两种文明范式的根本对立。美国依赖算力堆叠与资本逻辑追求技术霸权…
2026年AI大模型API中转平台排名揭晓，诗云API(ShiyunApi)脱颖而出成省心之选
在AI开发领域，如何接入模型厂商的官方API是一个绕不开的现实问题。对于海外开发者来说，注册、绑卡、调用，三步即可轻松搞定。然而，国内开发者却面临着跨境网络波动、外币支付门槛、发票合规需求以及多厂商Key碎片化管理等诸多“非…
基于飞书与OpenAI构建企业级AI助手：架构、部署与深度优化指南
1. 项目概述：当飞书遇上AI，一个企业级智能助手的诞生 最近在折腾一个挺有意思的项目，叫“ConnectAI-E/feishu-openai”。简单来说，它就是一个桥梁，把飞书这个强大的企业协作平台，和以ChatGPT为代表的OpenA…
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案 【免费下载链接】MPC-BE MPC-BE – универсальный проигрыватель аудио и видеофайлов для операционной системы Windows. 项目地址:…
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南 【免费下载链接】STL-Volume-Model-Calculator STL Volume Model Calculator Python 项目地址: https://gitcode.com/gh_mirrors/st/STL-Volume-Model-Calculator 你是否曾经为3D打印项目…
通过Taotoken CLI工具一键配置团队开发环境与模型密钥
通过Taotoken CLI工具一键配置团队开发环境与模型密钥 1. CLI工具安装与基本使用 Taotoken提供的CLI工具可通过npm全局安装或直接使用npx运行。对于需要频繁使用CLI的团队，推荐全局安装： npm install -g taotoken/taotoken对于临时使用或项目级配置&a…