部署至Azure后Document Intelligence无法正常工作的问题排查

ASP.NET Web应用在本地Mac OS系统可正常运行，但部署到Azure Linux Web App后调用Azure.AI.DocumentIntelligence服务时返回404错误。已确认API密钥和API端点配置正确，使用SDK版本为Azure.AI.DocumentIntelligence 1.0.0-beta.3。

相关代码：

async Task<AnalyzeDocumentResult> AnalyzeDocumentAsync(string filePath)
{
    var config = ((IConfigurationRoot)_config).GetRequiredSection("DocumentIntelligence").Get<DocumentIntelligenceConfig>();
    var credential = new AzureKeyCredential(config?.ApiKey ?? string.Empty);

    var options = new DocumentIntelligenceClientOptions(DocumentIntelligenceClientOptions.ServiceVersion.V2024_07_31_Preview);
    var client = new DocumentIntelligenceClient(new Uri(config?.EndPoint ?? string.Empty), credential, options);

    var file = new AnalyzeDocumentContent()
        {
            Base64Source = BinaryData.FromBytes(await File.ReadAllBytesAsync(filePath))
        };

    var operation = await client.AnalyzeDocumentAsync(WaitUntil.Completed, "prebuilt-layout", file.Content, outputContentFormat: ContentFormat.Markdown);

    if (!operation.HasValue)
    {
        _logger.LogError($"File doesn't have data: trackingCode: {trackingCode}");
        return new AnalyzeDocumentResult(false, file.FilePath, null);
    }
    if (!operation.HasCompleted)
    {
        _logger.LogError($"File doesn't completed: trackingCode: {trackingCode}");
        return new AnalyzeDocumentResult(false, file.FilePath, null);
    }
    await File.WriteAllTextAsync(file.FilePath.Replace(".pdf", ".md"), operation.Value.Content);
    return new AnalyzeDocumentResult(true, file.FilePath, operation.Value.Content);
}

部署后错误信息：

AnalyzeFileAsync -> Resource not found
Status: 404 (Not Found)
ErrorCode: 404

Content:
{"error":{"code":"404","message":"Resource not found"}}

Headers:
Date: Tue, 01 Oct 2024 20:43:28 GMT
Content-Length: 55
Content-Type: application/json

本地Mac与Azure Linux Web App的关键差异及可能的故障点：

• 端点URL格式兼容性：Linux环境下，若端点URL末尾缺少/，SDK拼接请求路径时会出现错误（例如将https://xxx.cognitiveservices.azure.com与documentintelligence/...直接拼接成无效路径）。本地Mac的SDK可能自动处理了URL路径补全，而Linux环境未兼容该逻辑。
• 环境配置隐形问题：尽管日志显示API密钥和端点正确，但Azure Linux Web App的配置值可能存在不可见字符、空格，或者配置读取时因环境差异出现截断，导致实际使用的端点不符合要求。
• 服务版本匹配问题：当前SDK使用V2024_07_31_Preview预览版本，需确认Azure Document Intelligence资源是否启用了该版本。本地可能访问到支持预览版的服务实例，而部署后的环境访问的实例未开启该版本。
• 文件读取权限与路径：Azure Linux Web App中文件路径格式（/与\差异）、文件读取权限与Mac不同，若文件未正确读取导致Base64Source为空，也可能触发服务端404错误。

代码修正（针对最可能的端点URL问题） #

async Task<AnalyzeDocumentResult> AnalyzeDocumentAsync(string filePath)
{
    var config = ((IConfigurationRoot)_config).GetRequiredSection("DocumentIntelligence").Get<DocumentIntelligenceConfig>();
    if (config == null || string.IsNullOrEmpty(config.ApiKey) || string.IsNullOrEmpty(config.EndPoint))
    {
        _logger.LogError("DocumentIntelligence configuration is missing");
        return new AnalyzeDocumentResult(false, filePath, null);
    }

    // 确保端点URL末尾带有斜杠，避免路径拼接错误
    var endpointUri = new Uri(config.EndPoint.EndsWith("/") ? config.EndPoint : $"{config.EndPoint}/");
    var credential = new AzureKeyCredential(config.ApiKey);

    var options = new DocumentIntelligenceClientOptions(DocumentIntelligenceClientOptions.ServiceVersion.V2024_07_31_Preview);
    var client = new DocumentIntelligenceClient(endpointUri, credential, options);

    byte[] fileBytes;
    try
    {
        fileBytes = await File.ReadAllBytesAsync(filePath);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, $"Failed to read file: {filePath}");
        return new AnalyzeDocumentResult(false, filePath, null);
    }

    var fileContent = new AnalyzeDocumentContent
    {
        Base64Source = BinaryData.FromBytes(fileBytes)
    };

    AnalyzeDocumentOperation operation;
    try
    {
        operation = await client.AnalyzeDocumentAsync(WaitUntil.Completed, "prebuilt-layout", fileContent.Content, outputContentFormat: ContentFormat.Markdown);
    }
    catch (RequestFailedException ex)
    {
        _logger.LogError(ex, $"AnalyzeDocument failed with status code {ex.Status}: {ex.Message}");
        return new AnalyzeDocumentResult(false, filePath, null);
    }

    if (!operation.HasValue || !operation.HasCompleted)
    {
        _logger.LogError($"File processing incomplete: trackingCode: {trackingCode}");
        return new AnalyzeDocumentResult(false, filePath, null);
    }

    try
    {
        var outputPath = filePath.Replace(".pdf", ".md");
        await File.WriteAllTextAsync(outputPath, operation.Value.Content);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, $"Failed to write output file: {filePath.Replace(".pdf", ".md")}");
        return new AnalyzeDocumentResult(false, filePath, operation.Value.Content);
    }

    return new AnalyzeDocumentResult(true, filePath, operation.Value.Content);
}

额外排查步骤 #

1. 在Azure Web App配置中，直接将端点URL修改为带末尾斜杠的格式，重新部署测试。
2. 开启SDK详细日志，查看实际发送的请求URL，确认是否与预期一致。
3. 验证Document Intelligence资源的区域是否支持V2024_07_31_Preview预览版本。

内容的提问来源于stack exchange，提问作者Imran Sh