调用Azure Document Intelligence的begin_analyze_document方法时提示“Connection string is either blank or malformed”错误的技术咨询

我之前在使用Azure Document Intelligence SDK时也碰到过一模一样的错误，结合你贴的代码来看，这个问题大多出在客户端初始化的配置或者SDK版本上，下面是几个快速排查和解决的方向：

1. 先确认Endpoint和Key的正确性 #

• Endpoint检查：确保你的endpoint是Azure Document Intelligence服务的完整地址，不要额外添加旧版API路径（比如/formrecognizer/v2.1这类），正确格式就是https://<your-resource-name>.cognitiveservices.azure.com/（结尾的斜杠留不留都可以，但别加其他内容）。
• Key检查：你的代码里写的ANZ...CzH是隐藏了部分内容，实际使用时必须复制Azure门户“密钥和终结点”页面里的完整32位密钥，截断或输入错误都会导致连接验证失败。

2. 排查SDK版本与依赖 #

这个错误很常见于新旧SDK版本混用的情况：

• 先确保你安装的是最新版的Document Intelligence SDK，运行以下命令更新：

  pip install --upgrade azure-ai-documentintelligence azure-core
  

• 如果之前安装过旧版的Form Recognizer SDK（包名是azure-cognitiveservices-formrecognizer），建议先卸载它，因为旧版SDK和新版的客户端类不兼容，会导致内部配置解析出错：

  pip uninstall azure-cognitiveservices-formrecognizer -y
  pip install azure-ai-documentintelligence
  

  你代码里用的DocumentIntelligenceClient是新版SDK的类，必须搭配对应的包版本使用。

3. 检查环境变量冲突 #

如果你的运行环境（本地或Azure门户的代码环境）中设置了AZURE_COGNITIVE_SERVICES_CONNECTION_STRING环境变量，SDK会优先读取这个变量来初始化客户端。如果这个变量是空的，或者格式不对（正确格式是Endpoint=<your-endpoint>;Key=<your-key>），就会抛出这个错误。

• 解决方法：要么删除或修正这个环境变量，要么确保代码中显式指定的endpoint和credential能被SDK优先使用（新版SDK中显式传参的优先级高于环境变量）。

4. 确认服务资源类型正确 #

最后再确认你在Azure门户创建的是Azure AI Document Intelligence资源，不是其他认知服务（比如计算机视觉）。不同服务的Endpoint和密钥不通用，用错资源类型肯定会导致连接失败。

验证用的完整代码示例 #

你可以用下面的代码替换你的内容，确保密钥和Endpoint正确后测试：

from azure.ai.documentintelligence import DocumentIntelligenceClient
from azure.core.credentials import AzureKeyCredential
from azure.ai.documentintelligence.models import AnalyzeDocumentRequest

# 替换为你的真实Endpoint和完整密钥
endpoint = "https://di-myService.cognitiveservices.azure.com/"
key = "YOUR_FULL_32_CHARACTER_KEY_HERE"
formUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/sample-layout.pdf"

try:
    document_intelligence_client = DocumentIntelligenceClient(
        endpoint=endpoint, credential=AzureKeyCredential(key)
    )
    poller = document_intelligence_client.begin_analyze_document(
        "prebuilt-layout", AnalyzeDocumentRequest(url_source=formUrl)
    )
    result = poller.result()
    print("文档分析成功！")
    # 这里可以添加处理结果的代码
except Exception as e:
    print(f"错误详情: {str(e)}")

内容的提问来源于stack exchange，提问作者RT.