Azure Document Intelligence 调用时报连接字符串为空或格式错误

2026-11-04架构老王

结论

这段调用使用 endpoint 和 API key 认证，不需要额外提供 connection string。AzureKeyCredential(key) 接收资源的 API key，AnalyzeDocumentRequest(url_source=formUrl) 指定待分析文档的 URL。这两种用法与官方 Python SDK 示例一致。

仅凭 Connection string is either blank or malformed 这一句无法确定根因。需要先确认异常由哪一行、哪个组件抛出，再决定修改什么配置。现有材料没有完整 traceback，也没有说明“门户”具体指哪种运行环境，因此无法直接认定问题出在 Document Intelligence 的密钥、Storage 配置还是门户本身。

先检查凭据与 SDK

在对应 Azure Document Intelligence 资源的密钥和终结点页面核对：

endpoint 和 key 属于同一个资源。
key 是完整的 API key，没有混入引号、换行或其他配置内容。如果 ANZ...CzH 只是展示时脱敏，可以保留这种展示方式；实际运行时必须使用完整值。
endpoint 使用资源提供的完整地址。

在运行代码的同一个 Python 环境中检查包版本：

python -m pip show azure-ai-documentintelligence azure-core

确认导入的是 azure.ai.documentintelligence.DocumentIntelligenceClient，并参考与已安装版本对应的示例。不要仅凭这条错误升级或降级依赖。

用最小脚本定位失败阶段

下面的示例保留原有调用方式，补齐了导入，并标出客户端创建、提交请求和等待结果三个阶段。运行前，在当前运行环境中配置 DOCUMENTINTELLIGENCE_ENDPOINT 和 DOCUMENTINTELLIGENCE_API_KEY；这两个名称是示例约定的环境变量名。

import os
import traceback

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

stage = "读取配置"

try:
    endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"].strip()
    key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"].strip()

    if not endpoint or not key:
        raise ValueError("endpoint 和 API key 不能为空")

    form_url = (
        "https://raw.githubusercontent.com/Azure-Samples/"
        "cognitive-services-REST-api-samples/master/curl/"
        "form-recognizer/sample-layout.pdf"
    )

    stage = "创建客户端"
    with DocumentIntelligenceClient(
        endpoint=endpoint,
        credential=AzureKeyCredential(key),
    ) as client:
        stage = "提交分析请求"
        poller = client.begin_analyze_document(
            "prebuilt-layout",
            AnalyzeDocumentRequest(url_source=form_url),
        )

        stage = "等待分析结果"
        result = poller.result()
        print(result.content)

except Exception:
    print(f"失败阶段：{stage}")
    traceback.print_exc()
    raise

这里沿用通过第二个位置参数传入 AnalyzeDocumentRequest 的形式；官方布局分析示例也采用这一方式。该脚本用于复现和定位问题，尚未验证能否解决当前环境中的错误。

根据异常来源处理

查看 traceback 末尾的异常类型、抛错模块和调用位置。如果有 HTTP 响应，再检查状态码、服务错误码及错误详情。

在脚本启动前就失败：先检查门户的启动日志和运行环境配置，此时不能把错误归因于 begin_analyze_document。
在创建其他客户端时失败：如果堆栈指向某个 from_connection_string(...) 调用，应检查那个组件需要的连接字符串，不要把它填入 Document Intelligence 的 key。
提交请求时失败：结合响应详情检查终结点、认证、网络访问和文档 URL，避免只根据错误文案猜测。
在 poller.result() 时失败：检查轮询请求或分析任务返回的具体错误，不能仅凭这一行判断是连接字符串配置问题。

如果门户只显示简短错误，可以在本地或独立 Python 环境中运行相同的最小脚本，并对齐凭据、包版本和文档 URL。如果两边结果不同，需要进一步比较运行环境；这本身不能证明故障一定来自门户。

提交进一步排查信息时，请提供完整 traceback、SDK 版本、失败阶段及具体运行入口，并移除密钥和其他凭据。目前可以确认认证调用方式合理，具体根因仍需结合异常堆栈或服务响应判断。