ネイティブドキュメントの概要を使用する方法 (プレビュー)

2025-05-20

Von Bedeutung

Azure AI Language のパブリックプレビューリリースを使うと、開発中の機能に早期にアクセスできます。
機能、アプローチ、およびプロセスは、ユーザーからのフィードバックに基づいて、一般公開 (GA) の前に変更される可能性があります。

Azure AI Language は、自然言語処理 (NLP) 機能をテキストベースのデータに適用するクラウドベースのサービスです。ドキュメント要約は、自然言語処理を使って、ドキュメントの抽出要約 (特徴的な文の抽出) または抽象要約 (コンテキストによる単語の抽出) を生成します。 AbstractiveSummarization と ExtractiveSummarization どちらの API でも、ネイティブドキュメント処理がサポートされています。ネイティブドキュメントとは、Microsoft Word (docx) やポータブルドキュメントファイル (pdf) などの元のドキュメントを作成するために使われるファイル形式のことです。ネイティブドキュメントのサポートにより、Azure AI Language リソースの機能を使用する前に、テキストの前処理を行う必要がなくなります。ネイティブドキュメントサポート機能を使うと、HTTP POST 要求本文を使ってデータを送信し、HTTP GET 要求クエリ文字列を使って状態結果を取得することで、API 要求を非同期に送信できます。処理されたドキュメントは、Azure Blob Storage ターゲットコンテナーにあります。

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

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

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

入力ガイドライン

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

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

"ドキュメントサイズ"

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

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

それでは始めましょう。

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

注

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 アカウント内に、ソースとターゲットの各ファイル用のコンテナーを作成する必要があります。
- ソースのコンテナー。このコンテナーを使って、分析対象のネイティブファイルをアップロードします (必須)。
- ターゲットコンテナー。このコンテナーを使って、分析されたファイルを格納します (必須)。
単一サービスの言語リソース (マルチサービスの Azure AI Foundry リソースではありません):

次のように、Language リソースプロジェクトとインスタンスの詳細のフィールドに入力します。
1. [サブスクリプション]。使用できる Azure サブスクリプションのいずれかを選択します。
2. [リソースグループ]。新しいリソースグループを作成するか、同じライフサイクル、アクセス許可、ポリシーを共有する既存のリソースグループにリソースを追加することができます。
3. [リソースリージョン] . ご自身のビジネスまたはアプリケーションが特定のリージョンを必要としない限り、 [グローバル] を選択します。認証にシステム割り当てマネージド ID を使用する場合は、米国西部などの地理的リージョンを選択します。
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 には、書き込みと一覧表示のアクセス権が指定されている必要があります。

抽出要約 API では、自然言語処理手法を使用して、非構造化テキストドキュメント内の重要な文が検索されます。これらの文がまとめられて、ドキュメントの主要なアイデアが伝えられます。

抽出要約では、抽出された文と元のドキュメント内でのその位置と共に、システム応答の一部としてランクスコアが返されます。ランクスコアは、ドキュメントの主要なアイデアに対して文がどの程度関係していると判断されるのかの指標です。モデルでは、各文に対して 0 から 1 (両端を含む) のスコアが与えられ、要求ごとに最も高いスコアの文が返されます。たとえば、3 文の要約を要求した場合、サービスからはスコアが最も高い 3 つの文が返されます。

Azure AI Language にはキーフレーズ抽出というもう 1 つの機能があり、重要な情報を抽出できます。キーフレーズ抽出と抽出要約のどちらを決定する場合も、次の点に注意してください。

キーフレーズ抽出からは語句が返されるのに対し、抽出要約からは文が返されます。
抽出要約からは文と共にランクスコアが返され、要求ごとに上位ランクの文が返されます。
抽出要約では、次の位置情報も返されます。
- オフセット: 抽出された各文の開始位置。
- 長さ: 抽出された各文の長さ。

データの処理方法を決定する (省略可能)

データの送信

ドキュメントをテキストの文字列として API に送信します。要求が受信されると分析が実行されます。 API は非同期なので、API 要求を送信してから、結果を受信するまでに、遅延が発生する可能性があります。

この機能を使うと、API の結果は、応答で示される要求取り込み時刻から 24 時間利用できます。この時間が経過すると、結果は消去され、取得できなくなります。

テキストの要約結果を取得する

言語検出から結果を取得するときは、結果をアプリケーションにストリーミングしたり、ローカルシステム上のファイルに出力を保存したりできます。

要約のために送信できるコンテンツの例を次に示します。このコンテンツは、Microsoft ブログ記事「統合 AI に対する包括的な表現」を使用して抽出されます。この記事は一例にすぎません。 API では、長い入力テキストを受け取ることができます。詳細については、データとサービスの制限に関する説明を参照してください。

「Microsoft では、より包括的な人間中心のアプローチを学習と理解に取り入れ、既存の手法を超えて AI を進めるという探求に取り組んでいます。私はAzure AIサービスの最高技術責任者として、この探求を現実のものにするために、素晴らしい科学者やエンジニアのチームと共に取り組んでいます。私の役割では、人間の認知の3つの特性、すなわち一言語のテキスト（X）、聴覚または視覚の感覚信号（Y）、および多言語（Z）の関係を独自の視点で見ることを楽しんでいます。 3つの要素が交わるところに、魔法があります。これを図1で示されているようにXYZコードと呼びます。これは、より強力なAIを生み出すための共同表現で、人間とより自然に話し、聞き、見て、理解することができます。私たちは、XYZ コードは、さまざまなモダリティと言語にまたがるクロスドメイン転移学習という長期的なビジョンを実現できると信じています。目標は、今日の人間のように、幅広い下流のAIタスクをサポートするための表現を共同で学習できる事前学習済みモデルを持つことです。過去 5 年間で、会話音声認識、機械翻訳、会話の質問への回答、機械読解、画像キャプションのベンチマークで人間のパフォーマンスを達成してきました。これらの5つのブレークスルーは、AIの能力の飛躍を生み出すという、より野心的な願望に向けて私たちに強い兆候を示しました。これは、人間が学んで理解する方法により近い、マルチセンサーおよび多言語学習の達成を目指しています。私は、外部のナレッジソースを基にした下流の AI タスクにおいて、XYZコードはこの願望を実現するための基礎的な構成要素であると考えています。

ドキュメント要約 API 要求は、要求を受信した時点で API バックエンド用のジョブを作成することで処理されます。ジョブが成功すると、API の出力が返されます。出力は 24 時間取得できます。この時間が過ぎると、出力は消去されます。多言語と絵文字のサポートにより、応答にはテキストオフセットが含まれる場合があります。詳細については、オフセットを処理する方法を参照してください。

前の例を使用すると、API は次の要約文を返す場合があります。

抽出要約:

「Microsoft では、学習と理解に対してより包括的で人間中心のアプローチを採用することで、既存の手法を超えて AI を進めるという探求に取り組んでいます」。
"私たちは、XYZ コードは、さまざまなモダリティと言語にまたがるクロスドメイン転移学習という長期的なビジョンを実現できると信じています。"
"目標は、さまざまなダウンストリーム AI タスクをサポートするために、現在人間が行っているのとほぼ同様の方法で、表現を共同で学習できる一連の事前トレーニング済みモデルを獲得することです。"

抽象要約:

マイクロソフトは、学習と理解に対してより全体的で人間中心のアプローチを取っています。私たちは、XYZ コードは、さまざまなモダリティと言語にまたがるクロスドメイン転移学習という長期的なビジョンを実現できると信じています。過去5年間で、さまざまな分野のベンチマークで人間のパフォーマンスを達成しました。

テキスト抽出の要約を試す

ドキュメントの抽出要約を使って、記事、論文、ドキュメントなどの要約を取得できます。例については、クイックスタートの記事をご覧ください。

sentenceCount パラメータを使って、返される文の数を指定できます。既定値は 3 です。範囲は 1 から 20 です。

また、sortby パラメーターを使うと、抽出された文が返されるときの順序を指定できます。値は Offset または Rank で、既定値は Offset です。

パラメーターの値	説明
順位	サービスによって決定された入力ドキュメントとの関連性に従って文を並べ替えます。
オフセット	入力ドキュメントで文が出現する元の順序を維持します。

テキストの抽象要約

次に示す例で、ドキュメントの抽象要約を開始できます。

テキストエディターに次のコマンドをコピーします。 BASH の例では、行連結文字として \ を使用します。ご利用のコンソールまたはターミナルで異なる行連結文字が使われている場合は、その文字を代わりに使ってください。

curl -i -X POST https://<your-language-resource-endpoint>/language/analyze-text/jobs?api-version=2023-04-01 \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: <your-language-resource-key>" \
-d \
' 
{
  "displayName": "Text Abstractive Summarization Task Example",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "en",
        "text": "At Microsoft, we have been on a quest to advance AI beyond existing techniques, by taking a more holistic, human-centric approach to learning and understanding. As Chief Technology Officer of Azure AI services, I have been working with a team of amazing scientists and engineers to turn this quest into a reality. In my role, I enjoy a unique perspective in viewing the relationship among three attributes of human cognition: monolingual text (X), audio or visual sensory signals, (Y) and multilingual (Z). At the intersection of all three, there's magic—what we call XYZ-code as illustrated in Figure 1—a joint representation to create more powerful AI that can speak, hear, see, and understand humans better. We believe XYZ-code enables us to fulfill our long-term vision: cross-___domain transfer learning, spanning modalities and languages. The goal is to have pretrained models that can jointly learn representations to support a broad range of downstream AI tasks, much in the way humans do today. Over the past five years, we have achieved human performance on benchmarks in conversational speech recognition, machine translation, conversational question answering, machine reading comprehension, and image captioning. These five breakthroughs provided us with strong signals toward our more ambitious aspiration to produce a leap in AI capabilities, achieving multi-sensory and multilingual learning that is closer in line with how humans learn and understand. I believe the joint XYZ-code is a foundational component of this aspiration, if grounded with external knowledge sources in the downstream AI tasks."
      }
    ]
  },
  "tasks": [
    {
      "kind": "AbstractiveSummarization",
      "taskName": "Text Abstractive Summarization Task 1",
    }
  ]
}
'

必要に応じて、コマンドに次の変更を加えます。
- your-language-resource-key 値をキーに置き換えます。
- 要求 URL (your-language-resource-endpoint) の最初の部分を独自のエンドポイント URL に置き換えます。
コマンドプロンプトウィンドウ (BASH など) を開きます。
テキストエディターからコマンドプロンプトウィンドウにコマンドを貼り付けて、コマンドを実行します。
operation-___location を応答ヘッダーから取得します。値は次の URL のようになります。

https://<your-language-resource-endpoint>/language/analyze-text/jobs/12345678-1234-1234-1234-12345678?api-version=2022-10-01-preview

要求の結果を取得するには、次の cURL コマンドを使用します。 <my-job-id> を、前の operation-___location 応答ヘッダーから受け取った数値 ID 値に必ず置き換えてください。

curl -X GET https://<your-language-resource-endpoint>/language/analyze-text/jobs/<my-job-id>?api-version=2022-10-01-preview \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: <your-language-resource-key>"

抽象テキスト要約の例の JSON 応答

{
    "jobId": "cd6418fe-db86-4350-aec1-f0d7c91442a6",
    "lastUpdateDateTime": "2022-09-08T16:45:14Z",
    "createdDateTime": "2022-09-08T16:44:53Z",
    "expirationDateTime": "2022-09-09T16:44:53Z",
    "status": "succeeded",
    "errors": [],
    "displayName": "Text Abstractive Summarization Task Example",
    "tasks": {
        "completed": 1,
        "failed": 0,
        "inProgress": 0,
        "total": 1,
        "items": [
            {
                "kind": "AbstractiveSummarizationLROResults",
                "taskName": "Text Abstractive Summarization Task 1",
                "lastUpdateDateTime": "2022-09-08T16:45:14.0717206Z",
                "status": "succeeded",
                "results": {
                    "documents": [
                        {
                            "summaries": [
                                {
                                    "text": "Microsoft is taking a more holistic, human-centric approach to AI. We've developed a joint representation to create more powerful AI that can speak, hear, see, and understand humans better. We've achieved human performance on benchmarks in conversational speech recognition, machine translation, ...... and image captions.",
                                    "contexts": [
                                        {
                                            "offset": 0,
                                            "length": 247
                                        }
                                    ]
                                }
                            ],
                            "id": "1"
                        }
                    ],
                    "errors": [],
                    "modelVersion": "latest"
                }
            }
        ]
    }
}

パラメーター	説明
`-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 コードサンプルプロジェクトを選んで、ネイティブドキュメントを分析してみてください。

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

このプロジェクトでは、ソースコンテナーにアップロードされたソースドキュメントが必要です。このクイックスタート用に、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 リソースインスタンスのエンドポイント値に置き換えます。

Von Bedeutung

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

PowerShell

 cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2024-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=2024-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=2024-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=2024-11-15-preview

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

Get 要求

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-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=2024-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": "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 サービスサブスクリプションをクリーンアップして削除したい場合は、リソースまたはリソースグループを削除することができます。リソースグループを削除すると、それに関連付けられた他のすべてのリソースも削除されます。

次のステップ

ドキュメントの概要