Share via

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

  • [アーティクル]

重要

  • ネイティブ ドキュメントのサポートは、限定的なプレビューです。 ネイティブ ドキュメント サポート機能へのアクセスを要求するには、「言語サービスのプレビューへのアクセスを申し込む」フォームに入力して送信してください。

  • 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 がインストールされていない場合は、お使いのプラットフォームに応じた次のインストール リンクをお使いください。

  • アクティブな 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 サービスへの要求では、アクセスを認証するための読み取り専用キーとカスタム エンドポイントが必要です。

  1. 新しいリソースを作成した場合は、そのデプロイ後に [リソースに移動] を選びます。 既存の Language サービス リソースがある場合は、リソース ページに直接移動します。

  2. 左側のレールの [リソース管理] で、 [キーとエンドポイント] を選択します。

  3. 自分の 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 (ファイル) に割り当てられます。

Screenshot of a storage url with SAS token appended.

  • ソースのコンテナーまたは 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 サンプル ドキュメント

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

POST 要求を作成する

  1. 任意のエディターまたは IDE を使用して、native-document という名前のアプリ用の新しいディレクトリを作成します。

  2. 自分の native-document ディレクトリに、pii-detection.json という名前の新しい json ファイルを作成します。

  3. 次の個人を特定できる情報 (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 要求を実行する

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

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

  2. 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"

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

    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 要求を使って結果を取得できます。

Screenshot showing the operation-location value in the POST response.

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

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

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

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

  3. コマンドを実行する前に、次の変更を行います。

    • {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"
        }
      }
    ]
  }
}

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

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

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

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

次のステップ

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