返回

Azure AI 定制翻译器密钥无效/区域不匹配问题排查

Ai

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 服务的网络设置问题,特别是“允许访问”被禁用,并且使用了私有终结点连接。但问题是,创建工作区时只能填写密钥和区域,根本没地方配置私有终结点,这可咋整?

问题原因分析

这种情况,通常有以下几个可能的原因:

  1. 网络访问限制: Azure 资源可能配置了网络安全规则,阻止了从 Custom Translator 门户发起的连接。特别是使用了私有终结点,而 Custom Translator 门户又不在允许的访问范围内。
  2. 密钥或区域错误 (虽然你已经排除了): 即使复制粘贴,也可能因为某些不可见字符或空格导致错误。或者,密钥可能真的过期或被吊销了。
  3. 权限不足: 虽然提供了密钥,但该密钥对应的服务主体可能没有访问 Custom Translator 服务所需的权限。
  4. 资源提供程序未注册: 订阅可能没有注册 "Microsoft.CognitiveServices" 资源提供程序。
  5. 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 定制翻译器密钥无效或区域不匹配的问题。 如果做了什么操作后问题解决了, 欢迎反馈, 让遇到类似问题的同学能够更快地处理问题。