返回

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 定制翻译器密钥无效或区域不匹配的问题。 如果做了什么操作后问题解决了, 欢迎反馈, 让遇到类似问题的同学能够更快地处理问题。