AWS SDK for Python(Boto3)を使用してAmazon Comprehendを操作する

2018.03.22

Amazon Comprehend を AWS SDK for Python (Boto3)で使用する主要な4つの関数と、Topic Modelingで使用する関数のサンプルコードをご紹介します。

主要な4つの関数

  • DetectDominantLanguage
  • DetectEntities
  • DetectKeyPhrases
  • DetectSentiment

これらの関数は最大25のドキュメントをバッチ処理するBatch APIsも用意されています。

Topic Modelingで使用する関数

  • StartTopicsDetectionJob
  • DescribeTopicsDetectionJob
  • ListTopicsDetectionJobs

Sample Code

まずは、主要な4つの関数を使ってみます。

DetectDominantLanguage operation.

テキストに使用されている主要言語を検出します。 Amazon Comprehendは101の異なる言語を検出できます。

Execution result

{
    "Languages": [
        {
            "LanguageCode": "en",
            "Score": 0.9940536618232727
        }
    ],
    "ResponseMetadata": {
        "HTTPHeaders": {
            "connection": "keep-alive",
            "content-length": "64",
            "content-type": "application/x-amz-json-1.1",
            "date": "Thu, 22 Mar 2018 04:15:20 GMT",
            "x-amzn-requestid": "a29fda00-2d87-11e8-ad56-************"
        },
        "HTTPStatusCode": 200,
        "RequestId": "a29fda00-2d87-11e8-ad56-************",
        "RetryAttempts": 0
    }
}

DetectEntities operation.

テキストにあるの人物や場所などのエンティティを検出することができます。

Execution result

{
    "Entities": [
        {
            "BeginOffset": 0,
            "EndOffset": 6,
            "Score": 0.8670787215232849,
            "Text": "Amazon",
            "Type": "ORGANIZATION"
        },
        {
            "BeginOffset": 7,
            "EndOffset": 17,
            "Score": 1.0,
            "Text": "Comprehend",
            "Type": "COMMERCIAL_ITEM"
        }
    ],
    "ResponseMetadata": {
        "HTTPHeaders": {
            "connection": "keep-alive",
            "content-length": "201",
            "content-type": "application/x-amz-json-1.1",
            "date": "Thu, 22 Mar 2018 04:15:20 GMT",
            "x-amzn-requestid": "a2b84450-2d87-11e8-b3f9-************"
        },
        "HTTPStatusCode": 200,
        "RequestId": "a2b84450-2d87-11e8-b3f9-************",
        "RetryAttempts": 0
    }
}

DetectKeyPhrases operation.

テキストの内容を最もよく示すキーフレーズを検出します。

Execution result

{
    "KeyPhrases": [
        {
            "BeginOffset": 0,
            "EndOffset": 17,
            "Score": 0.9958747029304504,
            "Text": "Amazon Comprehend"
        },
        {
            "BeginOffset": 21,
            "EndOffset": 50,
            "Score": 0.9654422998428345,
            "Text": "a natural language processing"
        },
        {
            "BeginOffset": 52,
            "EndOffset": 55,
            "Score": 0.941932201385498,
            "Text": "NLP"
        },
        {
            "BeginOffset": 57,
            "EndOffset": 64,
            "Score": 0.9076098203659058,
            "Text": "service"
        },
        {
            "BeginOffset": 75,
            "EndOffset": 91,
            "Score": 0.872683584690094,
            "Text": "machine learning"
        },
        {
            "BeginOffset": 100,
            "EndOffset": 126,
            "Score": 0.9918361902236938,
            "Text": "insights and relationships"
        },
        {
            "BeginOffset": 130,
            "EndOffset": 134,
            "Score": 0.998969554901123,
            "Text": "text"
        }
    ],
    "ResponseMetadata": {
        "HTTPHeaders": {
            "connection": "keep-alive",
            "content-length": "615",
            "content-type": "application/x-amz-json-1.1",
            "date": "Thu, 22 Mar 2018 04:15:21 GMT",
            "x-amzn-requestid": "a2d409a7-2d87-11e8-a9a6-************"
        },
        "HTTPStatusCode": 200,
        "RequestId": "a2d409a7-2d87-11e8-a9a6-************",
        "RetryAttempts": 0
    }
}

DetectSentiment operation.

テキストの内容にある感情(positive, negative, mixed, or neutral)を検出します。

Execution result

{
    "ResponseMetadata": {
        "HTTPHeaders": {
            "connection": "keep-alive",
            "content-length": "161",
            "content-type": "application/x-amz-json-1.1",
            "date": "Thu, 22 Mar 2018 04:15:21 GMT",
            "x-amzn-requestid": "a2ebb00b-2d87-11e8-9c58-************"
        },
        "HTTPStatusCode": 200,
        "RequestId": "a2ebb00b-2d87-11e8-9c58-************",
        "RetryAttempts": 0
    },
    "Sentiment": "NEUTRAL",
    "SentimentScore": {
        "Mixed": 0.003294283989816904,
        "Negative": 0.01219215989112854,
        "Neutral": 0.7587229609489441,
        "Positive": 0.2257905900478363
    }
}

Topic Modeling

トピック検出ジョブを実行してみます。

Sample Code

StartTopicsDetectionJob

非同期でトピック検出ジョブをスタートします。 JobIdを取得して次のDescribeTopicDetectionJobでジョブの状態を確認できます。

InputFormatには2種類あります。

  • ONE_DOC_PER_FILE
    • 各ファイルに一つのドキュメントが含まれている場合
  • ONE_DOC_PER_LINE
    • 一つのファイル、ファイルの各行はドキュメントとみなされます。

DescribeTopicDetectionJob

トピック検出ジョブのステータスを取得します。 以下4つのステータスがあります。

  • JobStatus
    • SUBMITTED
    • IN_PROGRESS
    • COMPLETED
    • FAILED

サンプルコードではJobStatusがCOMPLETEDFAILEDでループを抜けるようにしました。

ListTopicsDetectionJobs

トピック検出ジョブのリストを取得します。

Execution result

job_id: 2733262c2747153ab8cb0b01********
job_status: SUBMITTED
job_status: IN_PROGRESS
[...]
job_status: COMPLETED
topics_detection_job_list: {
    "ResponseMetadata": {
        "HTTPHeaders": {
            "connection": "keep-alive",
            "content-length": "415",
            "content-type": "application/x-amz-json-1.1",
            "date": "Thu, 22 Mar 2018 04:27:59 GMT",
            "x-amzn-requestid": "669ffb28-2d89-11e8-82a0-************"
        },
        "HTTPStatusCode": 200,
        "RequestId": "669ffb28-2d89-11e8-82a0-************",
        "RetryAttempts": 0
    },
    "TopicsDetectionJobPropertiesList": [
        {
            "EndTime": {
                "$date": 1521692818930
            },
            "InputDataConfig": {
                "InputFormat": "ONE_DOC_PER_FILE",
                "S3Uri": "s3://your_input"
            },
            "JobId": "2733262c2747153ab8cb0b01********",
            "JobName": "Job4",
            "JobStatus": "COMPLETED",
            "NumberOfTopics": 10,
            "OutputDataConfig": {
                "S3Uri": "s3://your_output/**********-2733262c2747153ab8cb0b01********-1521692274392/output/output.tar.gz"
            },
            "SubmitTime": {
                "$date": 1521692274392
            }
        }
    ]
}

アウトプットファイルを確認

アウトプット先のs3バケットにファイルができていることを確認します。 ListTopicsDetectionJobsで確認が可能です。

  • OutputDataConfig
"OutputDataConfig": {
                "S3Uri": "s3://comprehend-output/************-23e550d3b1e792cf128931339a222d85-1521571329055/output/output.tar.gz"
            },
$ aws s3 cp s3://comprehend-output/************-23e550d3b1e792cf128931339a222d85-1521571329055/output/output.tar.gz .
$ tar -zxvf output.tar.gz
x topic-terms.csv
x doc-topics.csv
  • topic-terms.csv
    • コレクション内のトピックリストです。各トピックについて、デフォルトで、トピックの重み付けに従って上位の用語が含まれています。
  • doc-topics.csv
    • トピックに関連付けられたドキュメントとそのトピックに関連するドキュメントの割合を一覧表示します。

※正確な結果を得るにはそれぞれのtopic modeling jobで少なくとも1,000のドキュメントを使用する必要があります。

まとめ

Amazon Comprehendを利用するにあたりAPIを使うと思いますのでAWS SDK for Python (Boto3)を使った各関数のサンプルコードをご紹介しました。

参考URL