部署FastAPI至AWS Lambda时Textract报UnsupportedDocumentException问题

架构老林

2026-8-11

解决AWS Lambda部署FastAPI+Textract的UnsupportedDocumentException报错

可能的原因

Lambda环境中文件字节流在传输/解析过程中损坏或被修改，与本地开发环境的字节内容不一致
FastAPI适配Lambda的工具（如mangum）版本存在问题，导致文件上传的字节解析异常

排查与解决步骤

验证字节流一致性
在extractImage函数中添加日志，打印接收的文件字节长度和前10个字节，对比本地和Lambda的日志：
```
def extractImage(form_image: bytes = File()):
    print(f"Bytes length: {len(form_image)}")
    print(f"First 10 bytes: {form_image[:10]}")
    # 原业务代码...
```
查看CloudWatch日志，如果Lambda中的字节长度或内容与本地差异较大，说明文件解析/传输环节存在问题。
检查mangum适配器版本
若使用mangum作为FastAPI到Lambda的适配工具，确保安装最新稳定版。旧版本可能存在multipart/form-data解析bug，导致文件字节异常。更新命令：
```
pip install --upgrade mangum
```

测试原始字节传递
临时修改代码，将文件字节保存到Lambda的/tmp目录后重新读取，再传递给Textract，验证是否为字节流本身的问题：

def extractImage(form_image: bytes = File()):
    # 临时保存文件
    with open("/tmp/test_image.png", "wb") as f:
        f.write(form_image)
    # 重新读取字节
    with open("/tmp/test_image.png", "rb") as f:
        img_bytes = f.read()
    response = textractclient.analyze_document(
        Document={"Bytes": img_bytes},
        FeatureTypes=["FORMS"],
    )
    # 原业务后续逻辑...

若此方式能正常运行，说明原始接收的字节流存在异常，需进一步排查上传解析环节。