Azure AI Language でのネイティブドキュメントのサポート (プレビュー)

[アーティクル]
09/04/2024

重要

ネイティブドキュメントのサポートは、限定的なプレビューです。ネイティブドキュメントサポート機能へのアクセスを要求するには、「言語サービスのプレビューへのアクセスを申し込む」フォームに入力して送信してください。
Azure AI Language のパブリックプレビューリリースを使うと、開発中の機能に早期にアクセスできます。
機能、アプローチ、およびプロセスは、一般提供 (GA) の前に、ユーザーからのフィードバックに基づいて変更される可能性があります。

Azure AI Language は、自然言語処理 (NLP) 機能をテキストベースのデータに適用するクラウドベースのサービスです。ネイティブドキュメントサポート機能を使うと、HTTP POST 要求本文を使ってデータを送信し、HTTP GET 要求クエリ文字列を使って状態結果を取得することで、API 要求を非同期に送信できます。処理されたドキュメントは、Azure Blob Storage ターゲットコンテナーにあります。

ネイティブドキュメントとは、Microsoft Word (docx) やポータブルドキュメントファイル (pdf) などの元のドキュメントを作成するために使われるファイル形式のことです。ネイティブドキュメントのサポートにより、Azure AI Language リソースの機能を使用する前に、テキストの前処理を行う必要がなくなります。現在、ネイティブドキュメントのサポートは、次の機能で利用できます。

個人を特定できる情報 (PII)。 PII 検出機能を使用すると、非構造化テキストに含まれる機密情報を特定、分類、編集することができます。 PiiEntityRecognition API では、ネイティブドキュメント処理がサポートされています。
ドキュメント要約。ドキュメント要約は、自然言語処理を使って、ドキュメントの抽出要約 (特徴的な文の抽出) または抽象要約 (コンテキストによる単語の抽出) を生成します。 AbstractiveSummarization と ExtractiveSummarization どちらの API でも、ネイティブドキュメント処理がサポートされています。

サポートされるドキュメントの形式

アプリケーションでは、ネイティブファイル形式を使って、ネイティブドキュメントを作成または保存したり、開いたりします。現在、PII とドキュメント要約機能では、次のネイティブドキュメント形式がサポートされています。

ファイルの種類	[ファイル拡張子]	説明
テキスト	`.txt`	書式設定のないテキストドキュメント。
Adobe PDF	`.pdf`	移植可能なドキュメントファイル形式のドキュメント。
Microsoft Word	`.docx`	Microsoft Word 文書ファイル。

入力ガイドライン

"サポートされているファイル形式"

Type	サポートと制限事項
PDF	完全にスキャンされた PDF はサポートされていません。
画像内のテキスト	テキストが埋め込まれたデジタル画像はサポートされていません。
デジタルテーブル	スキャンされたドキュメント内のテーブルはサポートされていません。

"ドキュメントサイズ"

Attribute	入力制限
要求あたりのドキュメントの総数	≤ 20
要求あたりの合計コンテンツサイズ	≤ 1 MB

HTTP 要求にネイティブドキュメントを含める

それでは始めましょう。

このプロジェクトでは、cURL コマンドラインツールを使って REST API 呼び出しを行います。

Note

cURL パッケージは、ほとんどの Windows 10 と Windows 11、およびほとんどの macOS および Linux ディストリビューションにプレインストールされています。パッケージのバージョンは、次のコマンドを使用してチェックすることができます。Windows: curl.exe -V macOS: curl -V Linux: curl --version
cURL がインストールされていない場合は、お使いのプラットフォームに応じた次のインストールリンクをお使いください。
- Windows。
- Mac または Linux。
アクティブな Azure アカウント。アカウントがない場合は、無料アカウントを作成できます。
Azure Blob Storage アカウント。 Azure Blob Storage アカウント内に、ソースとターゲットの各ファイル用のコンテナーを作成する必要があります。
- ソースのコンテナー。このコンテナーを使って、分析対象のネイティブファイルをアップロードします (必須)。
- ターゲットのコンテナー。このコンテナーを使って、分析されたファイルを格納します (必須)。
単一サービスの Language リソース (マルチサービスの Azure AI サービスリソースではありません):

次のように、Language リソースプロジェクトとインスタンスの詳細のフィールドに入力します。
1. [サブスクリプション]。使用できる Azure サブスクリプションのいずれかを選択します。
2. [リソースグループ]。新しいリソースグループを作成するか、同じライフサイクル、アクセス許可、ポリシーを共有する既存のリソースグループにリソースを追加することができます。
3. [リソースリージョン] . ご自身のビジネスまたはアプリケーションが特定のリージョンを必要としない限り、 [グローバル] を選択します。認証にシステム割り当てマネージド ID (RBAC) を使う予定の場合は、米国西部などの地理的リージョンを選びます。
4. 名前。リソースに選んだ名前を入力します。選択した名前は Azure 内で一意である必要があります。
5. 価格レベル。 Free 価格レベル (Free F0) を使用してサービスを試用し、後から運用環境用の有料レベルにアップグレードすることができます。
6. [確認および作成] を選択します。
7. サービス条件を確認し、 [作成] を選択してリソースをデプロイします。
8. リソースが正常にデプロイされたら、[リソースに移動] を選びます。

キーと言語サービスエンドポイントを取得する

Language サービスへの要求では、アクセスを認証するための読み取り専用キーとカスタムエンドポイントが必要です。

新しいリソースを作成した場合は、そのデプロイ後に [リソースに移動] を選びます。既存の Language サービスリソースがある場合は、リソースページに直接移動します。
左側のレールの [リソース管理] で、 [キーとエンドポイント] を選択します。
自分の key と language service instance endpoint をコピーしてコードサンプルに貼り付けて、Language サービスに対する要求の認証を行うことができます。 API 呼び出しを行うために必要なキーは 1 つだけです。

Azure Blob Storage コンテナーを作成する

Azure Blob Storage アカウント内に、ソースとターゲットのファイル用のコンテナーを作成します。

ソースのコンテナー。このコンテナーを使って、分析対象のネイティブファイルをアップロードします (必須)。
ターゲットのコンテナー。このコンテナーを使って、分析されたファイルを格納します (必須)。

認証

Language リソースが BLOB の作成、読み取り、削除を行えるよう、事前にストレージアカウントへのアクセスを許可しておく必要があります。ストレージデータへのアクセスを許可するには、主に 2 つの方法を使用できます。

Shared Access Signature (SAS) トークン。ユーザー委任 SAS トークンは、Microsoft Entra 資格情報で保護されます。 SAS トークンを使用すると、Azure ストレージアカウント内のリソースへ安全に委任アクセスができるようになります。
マネージド ID のロールベースのアクセス制御 (RBAC)。 Azure リソースのマネージド ID は、Microsoft Entra ID と、Azure 管理対象リソースに対する特定のアクセス許可を作成するサービスプリンシパルです。

このプロジェクトでは、クエリ文字列として追加される Shared Access Signature (SAS) トークンを使って、source location と target location の URL に対するアクセスの認証を行います。各トークンは、特定の BLOB (ファイル) に割り当てられます。

ストレージ URI と SAS トークンのスクリーンショット。

ソースのコンテナーまたは BLOB には、読み取りと一覧表示のアクセス権が指定されている必要があります。
ターゲットのコンテナーまたは BLOB には、書き込みと一覧表示のアクセス権が指定されている必要があります。

ヒント

ここでは 1 つのファイル (BLOB) を処理しているので、BLOB レベルで SAS アクセスを委任することをお勧めします。

要求ヘッダーとパラメーター

パラメーター	説明
`-X POST <endpoint>`	API にアクセスするための Language リソースエンドポイントを指定します。
`--header Content-Type: application/json`	JSON データを送信するためのコンテンツタイプ。
`--header "Ocp-Apim-Subscription-Key:<key>`	API にアクセスするための Language リソースキーを指定します。
`-data`	要求で渡すデータを含む JSON ファイル。

次の cURL コマンドは、BASH シェルから実行されます。これらのコマンドは、実際のリソース名、リソースキー、JSON の値に合わせて編集してください。 Personally Identifiable Information (PII) または Document Summarization コードサンプルプロジェクトを選んで、ネイティブドキュメントを分析してみてください。

個人を特定できる情報 (PII)
ドキュメント要約

PII サンプルドキュメント

このクイックスタートでは、ソースコンテナーにアップロードされたソースドキュメントが必要です。このプロジェクト用に、Microsoft Word サンプルドキュメントまたは Adobe PDF をダウンロードできます。ソース言語は英語です。

POST 要求を作成する

任意のエディターまたは IDE を使用して、native-document という名前のアプリ用の新しいディレクトリを作成します。
自分の native-document ディレクトリに、pii-detection.json という名前の新しい json ファイルを作成します。
次の個人を特定できる情報 (PII) の要求サンプルをコピーして、pii-detection.json ファイルに貼り付けます。 {your-source-container-SAS-URL} と {your-target-container-SAS-URL} を、Azure portal のストレージアカウントコンテナーインスタンスの値に置き換えます。

"要求のサンプル"

{
    "displayName": "Extracting Location & US Region",
    "analysisInput": {
        "documents": [
            {
                "language": "en-US",
                "id": "Output-excel-file",
                "source": {
                    "location": "{your-source-blob-with-SAS-URL}"
                },
                "target": {
                    "location": "{your-target-container-with-SAS-URL}"
                }
            } 
        ]
    },
    "tasks": [
        {
            "kind": "PiiEntityRecognition",
            "parameters":{
                "excludePiiCategories" : ["PersonType", "Category2", "Category3"],
                "redactionPolicy": "UseRedactionCharacterWithRefId" 
            }
        }
    ]
}

ソース location 値は、ソースコンテナーの SAS URL ではなく、ソースドキュメント (BLOB) の SAS URL です。
redactionPolicy に指定できる値は、UseRedactionCharacterWithRefId (既定値) または UseEntityTypeName です。詳細については、PiiTask パラメーターに関する記事を "参照してください"。

POST 要求を実行する

POST 要求の暫定的な構造を次に示します。

   POST {your-language-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview

POST 要求を実行する前に、{your-language-resource-endpoint} と {your-key} を Azure portal の Language サービスインスタンスの値に置き換えます。

重要

終わったらコードからキーを削除し、公開しないよう注意してください。運用環境では、Azure Key Vault などの資格情報を格納してアクセスする安全な方法を使用します。詳しくは、「Azure AI サービスのセキュリティ」をご覧ください。

PowerShell
```
   cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"
```
コマンドプロンプトまたはターミナル
```
   curl -v -X POST "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"
```

応答のサンプルを次に示します。

HTTP/1.1 202 Accepted
Content-Length: 0
operation-location: https://{your-language-resource-endpoint}/language/analyze-documents/jobs/f1cc29ff-9738-42ea-afa5-98d2d3cabf94?api-version=2023-11-15-preview
apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
x-ms-region: West US 2
Date: Thu, 25 Jan 2024 15:12:32 GMT

POST 応答 (jobId)

読み取り専用の Operation-Location ヘッダーを含む 202 (成功) 応答を受け取ります。このヘッダーの値に含まれる jobId のクエリを実行して、非同期操作の状態を取得し、GET 要求を使って結果を取得できます。

POST 応答の操作場所の値を示すスクリーンショット。

分析結果を取得する (GET 要求)

POST 要求が成功したら、POST 要求で返された operation-location ヘッダーをポーリングして、処理されたデータを表示します。

GET 要求の暫定的な構造を次に示します。

  GET {your-language-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview

コマンドを実行する前に、次の変更を行います。
- {jobId} を、POST 応答の Operation-Location ヘッダーに置き換えます。
- {your-language-resource-endpoint} と {your-key} を、Azure portal の Language サービスインスタンスの値に置き換えます。

要求を取得

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" -i -X GET --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

    curl -v -X GET "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

結果の確認

JSON 出力で 200 (成功) 応答を受け取ります。 status フィールドは、操作の結果を示します。操作が完了していない場合、status の値は "running" または "notStarted" であり、手動またはスクリプトを使って、API をもう一度呼び出す必要があります。呼び出しの間隔は 1 秒以上あけることをお勧めします。

サンプル応答

{
  "jobId": "f1cc29ff-9738-42ea-afa5-98d2d3cabf94",
  "lastUpdatedDateTime": "2024-01-24T13:17:58Z",
  "createdDateTime": "2024-01-24T13:17:47Z",
  "expirationDateTime": "2024-01-25T13:17:47Z",
  "status": "succeeded",
  "errors": [],
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "PiiEntityRecognitionLROResults",
        "lastUpdateDateTime": "2024-01-24T13:17:58.33934Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "doc_0",
              "source": {
                "kind": "AzureBlob",
                "location": "https://myaccount.blob.core.windows.net/sample-input/input.pdf"
              },
              "targets": [
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.result.json"
                },
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.docx"
                }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2023-09-01"
        }
      }
    ]
  }
}

要約のサンプルドキュメント

このプロジェクトでは、ソースコンテナーにアップロードされたソースドキュメントが必要です。このクイックスタート用に、Microsoft Word サンプルドキュメントまたは Adobe PDF をダウンロードできます。ソース言語は英語です。

POST 要求を作成する

任意のエディターまたは IDE を使用して、native-document という名前のアプリ用の新しいディレクトリを作成します。
自分の native-document ディレクトリに、document-summarization.json という名前の新しい json ファイルを作成します。
ドキュメント要約の要求サンプルをコピーして、document-summarization.json ファイルに貼り付けます。 {your-source-container-SAS-URL} と {your-target-container-SAS-URL} を、Azure portal のストレージアカウントコンテナーインスタンスの値に置き換えます。

"要求のサンプル"

{
"tasks": [
  {
    "kind": "ExtractiveSummarization",
    "parameters": {
      "sentenceCount": 6
    }
  }
],
"analysisInput": {
  "documents": [
    {
      "source": {
        "location": "{your-source-blob-SAS-URL}"
      },
      "targets": {
        "location": "{your-target-container-SAS-URL}"
      }
    }
  ]
}
}

POST 要求を実行する

POST 要求を実行する前に、{your-language-resource-endpoint} と {your-key} を、Azure portal の Language リソースインスタンスのエンドポイント値に置き換えます。

重要

終わったらコードからキーを削除し、公開しないよう注意してください。運用環境では、Azure Key Vault などの資格情報を格納してアクセスする安全な方法を使用します。詳しくは、「Azure AI サービスのセキュリティ」をご覧ください。

PowerShell

 cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-summarization.json"

コマンドプロンプトまたはターミナル

curl -v -X POST "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-summarization.json"

応答のサンプルを次に示します。

HTTP/1.1 202 Accepted
Content-Length: 0
operation-location: https://{your-language-resource-endpoint}/language/analyze-documents/jobs/f1cc29ff-9738-42ea-afa5-98d2d3cabf94?api-version=2023-11-15-preview
apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
x-ms-region: West US 2
Date: Thu, 25 Jan 2024 15:12:32 GMT

POST 応答 (jobId)

読み取り専用の Operation-Location ヘッダーを含む 202 (成功) 応答を受け取ります。このヘッダーの値に含まれる jobId のクエリを実行して、非同期操作の状態を取得し、GET 要求を使って結果を取得できます。

POST 応答の操作場所の値を示すスクリーンショット。

分析結果を取得する (GET 要求)

POST 要求が成功したら、POST 要求で返された operation-location ヘッダーをポーリングして、処理されたデータを表示します。

GET 要求の構造を次に示します。

GET {cognitive-service-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview

コマンドを実行する前に、次の変更を行います。
- {jobId} を、POST 応答の Operation-Location ヘッダーに置き換えます。
- {your-language-resource-endpoint} と {your-key} を、Azure portal の Language サービスインスタンスの値に置き換えます。

要求を取得

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" -i -X GET --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

    curl -v -X GET "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

結果の確認

サンプル応答

{
  "jobId": "f1cc29ff-9738-42ea-afa5-98d2d3cabf94",
  "lastUpdatedDateTime": "2024-01-24T13:17:58Z",
  "createdDateTime": "2024-01-24T13:17:47Z",
  "expirationDateTime": "2024-01-25T13:17:47Z",
  "status": "succeeded",
  "errors": [],
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "ExtractiveSummarizationLROResults",
        "lastUpdateDateTime": "2024-01-24T13:17:58.33934Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "doc_0",
              "source": {
                "kind": "AzureBlob",
                "location": "https://myaccount.blob.core.windows.net/sample-input/input.pdf"
              },
              "targets": [
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/ExtractiveSummarization-0001/input.result.json"
                }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2023-02-01-preview"
        }
      }
    ]
  }
}

"正常に完了した場合":

分析されたドキュメントはターゲットコンテナーにあります。
成功した POST メソッドから 202 Accepted 応答コードが返され、バッチ要求によってサービスが作成されたことが示されます。
POST 要求では、後続の GET 要求で使う値を提供する Operation-Location を含む応答ヘッダーも返されます。

リソースをクリーンアップする

Azure AI サービスサブスクリプションをクリーンアップして削除したい場合は、リソースまたはリソースグループを削除することができます。リソースグループを削除すると、それに関連付けられている他のリソースも削除されます。

次のステップ

PII 検出の概要ドキュメント要約の概要

次の方法で共有

Azure AI Language でのネイティブドキュメントのサポート (プレビュー)

サポートされるドキュメントの形式

入力ガイドライン

HTTP 要求にネイティブドキュメントを含める

キーと言語サービスエンドポイントを取得する

Azure Blob Storage コンテナーを作成する

認証

要求ヘッダーとパラメーター

PII サンプルドキュメント

POST 要求を作成する

POST 要求を実行する

POST 応答 (jobId)

分析結果を取得する (GET 要求)

要求を取得

結果の確認

サンプル応答

要約のサンプルドキュメント

POST 要求を作成する

POST 要求を実行する

POST 応答 (jobId)

分析結果を取得する (GET 要求)

要求を取得

結果の確認

サンプル応答

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure AI Language でのネイティブ ドキュメントのサポート (プレビュー)

サポートされるドキュメントの形式

入力ガイドライン

HTTP 要求にネイティブ ドキュメントを含める

キーと言語サービス エンドポイントを取得する

Azure Blob Storage コンテナーを作成する

認証

要求ヘッダーとパラメーター

PII サンプル ドキュメント

POST 要求を作成する

POST 要求を実行する

POST 応答 (jobId)

分析結果を取得する (GET 要求)

要求を取得

結果の確認

サンプル応答

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

Azure AI Language でのネイティブドキュメントのサポート (プレビュー)

HTTP 要求にネイティブドキュメントを含める

キーと言語サービスエンドポイントを取得する

PII サンプルドキュメント