PHP中自定义Amazon Textract训练适配器失效问题求助

问题描述 #

在PHP中调用Amazon Textract时，配置了自定义训练的适配器，但仅QueriesConfig中的查询语句生效，训练的适配器未发挥作用。当前实现代码如下：

public function analyzeDocumentWithAdapter($imageBytes, $queries, $adapterId)
{
    // dd('Enviando solicitud a Textract con AdapterId:', ['AdapterId' => $adapterId]);

    $result = $this->textract->analyzeDocument([
        'Document' => [
            'Bytes' => $imageBytes,
        ],
        'FeatureTypes' => ['QUERIES'],
        'QueriesConfig' => [
            'Queries' => [
                ['Text' => 'What is the first name on the dpi?', 'Alias' => 'first_name'],
                ['Text' => 'What is the first last name on the dpi?', 'Alias' => 'first_last_name'],
                ['Text' => 'What is the second name on the dpi?', 'Alias' => 'second_name'],
                ['Text' => 'What is the date of birth?', 'Alias' => 'birth_date'],
                ['Text' => 'What is the second last name on the dpi?', 'Alias' => 'second_last_name'],
                ['Text' => 'What is the married last name?', 'Alias' => 'married_last_name'],
                ['Text' => 'What is the cui?', 'Alias' => 'cui'],
            ]
        ],
        'AdapterConfig' => [
            'Adapters' => [
                'AdapterId' => $adapterId, // ID del adaptador entrenado,
                'AdapterVersion' => '5',
            ]
            
        ],
    ]);

    return $result['Blocks'] ?? [];
}

排查与修复步骤 #

1. 修正AdapterConfig的结构错误 #

AWS Textract API要求AdapterConfig.Adapters是一个对象数组，而非单个键值对。当前代码中直接将适配器参数作为Adapters的值传入，导致API无法识别适配器配置。

修正后的AdapterConfig部分：

'AdapterConfig' => [
    'Adapters' => [
        [
            'AdapterId' => $adapterId,
            'AdapterVersion' => '5'
        ]
    ]
],

2. 确认适配器与FeatureTypes的兼容性 #

自定义适配器是针对特定FeatureTypes训练的，需确保调用时指定的FeatureTypes与训练适配器时选择的类型完全一致。如果适配器是针对FORMS或其他类型训练，仅指定QUERIES会导致适配器无法生效。

3. 验证适配器的有效性 #

• 确认AdapterId完全正确，无拼写或格式错误；
• 检查AdapterVersion是否为已发布的有效版本（不能是草稿或未完成训练的版本）；
• 登录AWS控制台，查看适配器状态是否为“已激活”。

4. 检查IAM权限配置 #

确保调用Textract的IAM角色拥有使用该适配器的权限，需在权限策略中添加对目标适配器的访问许可，示例策略片段：

{
    "Effect": "Allow",
    "Action": "textract:AnalyzeDocument",
    "Resource": [
        "arn:aws:textract:region:account-id:adapter/adapter-id"
    ]
}

5. 启用调试日志验证请求 #

取消代码中dd语句的注释，或添加AWS SDK的日志输出，确认请求中AdapterConfig参数是否正确传递到Textract服务端，排查参数是否在传输过程中被修改或丢失。

内容的提问来源于stack exchange，提问作者Juan Antonio Santiago