
azure 管理平面 api(如模型部署)不支持 api 密钥认证,仅接受 azure ad 身份验证方式(服务主体、托管标识或 azure cli 登录态),因此无法用 endpoint key 替代短期访问令牌。
azure 管理平面 api(如模型部署)不支持 api 密钥认证,仅接受 azure ad 身份验证方式(服务主体、托管标识或 azure cli 登录态),因此无法用 endpoint key 替代短期访问令牌。
在 Azure AI Services(原 Azure OpenAI)中部署微调模型,本质是资源管理操作——即通过 Azure Resource Manager(ARM)创建或更新 Microsoft.CognitiveServices/accounts/deployments 资源。这类操作属于 management plane(控制平面),严格遵循 Azure RBAC 和 OAuth 2.0 认证机制,不接受任何基于 API key 的身份验证(包括你在门户中看到的“Key1/Key2”或终结点密钥)。这些密钥仅用于 data plane(数据平面)调用,例如向已部署的模型发送 /chat/completions 请求。
✅ 正确且生产就绪的身份验证方式有以下三种(均基于 Azure AD):
-
托管标识(Managed Identity)(推荐用于云环境)
若部署脚本运行在 Azure VM、App Service、Function App 或 Azure Container Apps 中,可启用系统分配或用户分配的托管标识,并为其授予Cognitive Services Contributor或自定义 RBAC 角色(作用域为你的 Cognitive Services 资源组或资源)。Python 示例:from azure.identity import ManagedIdentityCredential from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient credential = ManagedIdentityCredential() client = CognitiveServicesManagementClient( credential=credential, subscription_id="YOUR_SUBSCRIPTION_ID" ) deployment_params = { "sku": {"name": "Standard", "capacity": 1}, "properties": { "model": { "format": "OpenAI", "name": "gpt-4o-mini-2024-07-18.ft-abc123def456", "version": "1" } } } client.deployments.begin_create_or_update( resource_group_name="my-rg", account_name="my-openai-account", deployment_name="ft-gpt4o-mini-prod", parameters=deployment_params ).result() -
服务主体(Service Principal)+ Client Secret/Certificate(推荐用于 CI/CD 或本地自动化)
创建服务主体、分配角色、保存client_id、client_secret和tenant_id,然后使用ClientSecretCredential:from azure.identity import ClientSecretCredential from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient credential = ClientSecretCredential( tenant_id="YOUR_TENANT_ID", client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET" ) client = CognitiveServicesManagementClient(credential, "YOUR_SUBSCRIPTION_ID") # 后续调用同上 -
Azure CLI 登录态(DefaultAzureCredential)(适合开发与调试)
运行az login后,DefaultAzureCredential会自动链式尝试 CLI 凭据(无需硬编码 token):from azure.identity import DefaultAzureCredential from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient credential = DefaultAzureCredential() client = CognitiveServicesManagementClient(credential, "YOUR_SUBSCRIPTION_ID")
⚠️ 注意事项:
- ❌ 不要尝试将门户中的
Key1或endpoint + key用于管理 API —— 它们仅适用于https://类 data plane 接口;.openai.azure.com/openai/deployments/... - ✅ 微调模型部署成功后,其 data plane 终结点才真正可用,此时你可安全使用
API key + endpoint发起推理请求; - ? 始终遵循最小权限原则:服务主体或托管标识只需
Microsoft.CognitiveServices/accounts/deployments/*权限,避免授予Owner级别权限; - ? 所有示例依赖
azure-mgmt-cognitiveservices>=23.0.0b1(对应 2024-10-01 API 版本)和azure-identity包,请确保已安装:pip install azure-mgmt-cognitiveservices azure-identity
总结:不存在“用 endpoint key 部署模型”的技术路径——这不是限制,而是 Azure 安全架构的设计原则。管理操作必须通过 Azure AD 强身份认证,而数据操作才允许轻量级密钥认证。选择托管标识或服务主体,即可彻底规避短期 token 刷新问题,实现稳定、可审计、符合企业合规要求的自动化部署。










