Azure AI 定制翻译器密钥无效/区域不匹配问题排查
2025-03-16 08:00:09
Azure AI 定制翻译器密钥无效或区域不匹配问题排查
最近遇到一个 Azure AI 定制翻译器 (Custom Translator) 的问题,创建工作区时总是报错:密钥无效,或者与提供的区域不匹配。明明密钥和区域都是从 Azure 门户复制粘贴过来的,绝对正确,但就是不行,很让人头疼。
报错信息如下:
The key is either invalid or doesn't use the region provided. Please verify your key and region in the Azure portal then try again.
客户那边安全策略比较严格,很多东西都锁定了。初步怀疑是 AI Translator 服务的网络设置问题,特别是“允许访问”被禁用,并且使用了私有终结点连接。但问题是,创建工作区时只能填写密钥和区域,根本没地方配置私有终结点,这可咋整?
问题原因分析
这种情况,通常有以下几个可能的原因:
- 网络访问限制: Azure 资源可能配置了网络安全规则,阻止了从 Custom Translator 门户发起的连接。特别是使用了私有终结点,而 Custom Translator 门户又不在允许的访问范围内。
- 密钥或区域错误 (虽然你已经排除了): 即使复制粘贴,也可能因为某些不可见字符或空格导致错误。或者,密钥可能真的过期或被吊销了。
- 权限不足: 虽然提供了密钥,但该密钥对应的服务主体可能没有访问 Custom Translator 服务所需的权限。
- 资源提供程序未注册: 订阅可能没有注册 "Microsoft.CognitiveServices" 资源提供程序。
- Custom Translator 门户自身的暂时性问题: 尽管可能性较低, 但也可能发生这种情况。
解决方案
针对上述可能的原因,可以尝试以下解决方案:
1. 检查网络设置
这是最有可能的原因。既然怀疑是私有终结点的问题,就需要仔细检查 Azure 门户中的网络设置。
-
检查防火墙和虚拟网络设置:
- 在 Azure 门户中,找到你的 Translator 资源。
- 在左侧菜单中,点击 "Networking"。
- 查看 "Firewalls and virtual networks" 选项卡。
- 如果 “Allow access from” 设置为 “Disabled”,这就是问题的根源。 要解决,需要在 "Selected networks" 中添加规则允许Custom Translator访问。然而, 在Custom Translator这个使用场景中,直接从portal添加网络比较困难. 稍后会提供更可行的变通办法。
- 如果此处做了任何变更, 一定要点击"保存"。
-
检查私有终结点连接:
- 在 "Networking" 页面,点击 "Private endpoint connections" 选项卡。
- 确保连接状态是 "Approved"。如果不是,需要相应地批准或配置。
-
变通方法 (如果无法直接在 Portal 添加网络) :
可以使用 Azure CLI 或 PowerShell 临时开放 Translator 的访问权限,然后快速创建工作区,创建成功后再改回去。Azure CLI 示例 (临时更改网络规则):
# 替换以下占位符 RESOURCE_GROUP=<你的资源组名称> TRANSLATOR_NAME=<你的翻译器资源名称> # 将 "Allow access from" 设置为 "All networks" (临时) az cognitiveservices account update --name $TRANSLATOR_NAME --resource-group $RESOURCE_GROUP --network-acls "{defaultAction:'Allow',virtualNetworkRules:[],ipRules:[]}" # ... 在 Custom Translator 门户中创建工作区 ... # 将 "Allow access from" 恢复为 "Disabled" 或原来的设置(记得替换原来的设置值!) az cognitiveservices account update --name $TRANSLATOR_NAME --resource-group $RESOURCE_GROUP --network-acls "{defaultAction:'Deny',virtualNetworkRules:[{id:'<原虚拟网络规则ID>'}],ipRules:[{value:'<原IP规则>'}]}"
PowerShell 示例 (临时更改网络规则):
# 替换以下占位符 $ResourceGroupName = "<你的资源组名称>" $TranslatorName = "<你的翻译器资源名称>" # 将 "Allow access from" 设置为 "All networks" (临时) Update-AzCognitiveServicesAccount -ResourceGroupName $ResourceGroupName -Name $TranslatorName -NetworkRuleSet @{DefaultAction = "Allow"; VirtualNetworkRules = @(); IpRules = @()} # ... 在 Custom Translator 门户中创建工作区 ... # 将 "Allow access from" 恢复为 "Disabled" 或原来的设置 (记得替换原来的设置!) Update-AzCognitiveServicesAccount -ResourceGroupName $ResourceGroupName -Name $TranslatorName -NetworkRuleSet @{DefaultAction = "Deny"; VirtualNetworkRules = @(@{Id="<原来的 VirtualNetworkRules>"}); IpRules = @(@{Value="<原来的 IPRules>"})}
注意 : 上面的命令执行之后, 会立刻生效. 创建 workspace 操作最好要迅速。
2. 再次验证密钥和区域
虽然你已经确认过,但还是再检查一遍,排除任何人为失误。
- 密钥: 从 Azure 门户复制密钥时,确保没有复制到任何额外的空格或字符。最好手动选择复制,避免一些网页复制按钮可能带来的问题。
- 区域: 确认区域代码是否正确。例如,"East US" 的区域代码是 "eastus",而不是 "East US"。可以直接从Azure 门户中的"Keys and Endpoint"页面复制区域。
3. 检查权限
确认用于创建工作区的密钥具有足够的权限。
- 访问控制 (IAM):
- 在 Azure 门户中,找到你的 Translator 资源。
- 在左侧菜单中,点击 "Access control (IAM)"。
- 检查你的账号或服务主体是否具有 "Cognitive Services User" 或 "Contributor" 角色。如果没有, 让管理员进行分配.
4. 注册资源提供程序
确保你的 Azure 订阅已经注册了 "Microsoft.CognitiveServices" 资源提供程序。
-
查看已注册的资源提供程序:
# Azure CLI az provider list --query "[?namespace=='Microsoft.CognitiveServices'].{RegistrationState:registrationState}" --output table
# PowerShell Get-AzResourceProvider -ProviderNamespace Microsoft.CognitiveServices | Select-Object RegistrationState
-
注册资源提供程序(如果未注册):
# Azure CLI az provider register --namespace Microsoft.CognitiveServices
# PowerShell Register-AzResourceProvider -ProviderNamespace Microsoft.CognitiveServices
注册可能需要几分钟时间。
5. 清理浏览器缓存/尝试使用 InPrivate/Incognito 模式
虽然和网络设置无关, 但是清理一下浏览器的缓存, 或换个浏览器/隐身模式, 有时候也能解决莫名其妙的问题。Custom Translator Portal 也只是一个 Web 应用。
6. 检查 Azure 服务状态
如果上述所有都无效, 不排除是 Azure 自身服务有问题.
可以访问 Azure 状态页面 (Azure status page) 检查一下是否有相关的服务中断或问题报告。
进阶使用与安全建议
- 使用托管标识(Managed Identities): 尽可能避免使用 API 密钥, 转为使用托管标识进行身份验证, 这能提高安全性, 同时免去密钥管理的麻烦. 虽然本场景Custom Translator创建Workspace时候只能用Key, 但对于应用内其他地方与Azure资源交互的地方可以使用。
- 最小权限原则: 在分配角色时,始终遵循最小权限原则。只授予完成特定任务所需的最小权限。例如,如果只需要读取 Translator 资源的信息,就不要授予 "Contributor" 角色,而应该使用 "Cognitive Services User" 角色。
- 定期轮换密钥: 建议定期轮换 Translator 资源的密钥。 这可以降低密钥泄露的风险。
- 网络安全组 (NSG) 细粒度控制: 对于更加细致的网络访问控制,可以使用 NSG 规则精确地指定允许或阻止哪些流量。
通过以上步骤,希望能帮你解决 Azure AI 定制翻译器密钥无效或区域不匹配的问题。 如果做了什么操作后问题解决了, 欢迎反馈, 让遇到类似问题的同学能够更快地处理问题。