チュートリアル:AI エンリッチメントを使用して "非構造化コンテンツ" に構造を追加するTutorial: Add structure to "unstructured content" with AI enrichment

非構造化テキストまたは画像のコンテンツがある場合、AI エンリッチメント パイプラインを使用すると、情報を抽出し、フルテキスト検索やナレッジ マイニングのシナリオに役立つ新しいコンテンツを作成することができます。If you have unstructured text or image content, an AI enrichment pipeline can help you extract information and create new content that is useful for full-text search or knowledge mining scenarios. パイプラインでは画像ファイル (JPG、PNG、TIFF) を処理できますが、このチュートリアルでは、ワードベースのコンテンツに焦点を当て、言語検出とテキスト分析を適用して、クエリ、ファセット、およびフィルターで利用できる新しいフィールドと情報を作成します。Although a pipeline can process image files (JPG, PNG, TIFF), this tutorial focuses on word-based content, applying language detection and text analytics to create new fields and information that you can leverage in queries, facets, and filters.

  • まずは、Azure Blob Storage で、PDF、MD、DOCX、PPTX などのドキュメント全体 (非構造化テキスト) から始める。Start with whole documents (unstructured text) such as PDF, MD, DOCX, and PPTX in Azure Blob storage.
  • テキストの抽出、言語の検出、エンティティの認識、キー フレーズの検出を行うパイプラインを定義する。Define a pipeline that extracts text, detects language, recognizes entities, and detects key phrases.
  • 出力 (生コンテンツと、パイプラインで生成された名前と値のペア) を格納するためのインデックスを定義する。Define an index to store the output (raw content, plus pipeline-generated name-value pairs).
  • 変換と分析を開始し、インデックスを作成して読み込むパイプラインを実行する。Execute the pipeline to start transformations and analysis, and to create and load the index.
  • フルテキスト検索と豊富なクエリ構文を使用して結果を探索する。Explore results using full text search and a rich query syntax.

このチュートリアルを完了するには、いくつかのサービスに加えて、REST API 呼び出しを行うための Postman デスクトップ アプリまたは別の Web テスト ツールが必要です。You'll need several services to complete this walkthrough, plus the Postman desktop app or another Web testing tool to make REST API calls.

Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。If you don't have an Azure subscription, open a free account before you begin.

ファイルをダウンロードするDownload files

  1. こちらの OneDrive フォルダーを開き、左上隅の [ダウンロード] をクリックして、コンピューターにファイルをコピーします。Open this OneDrive folder and on the top-left corner, click Download to copy the files to your computer.

  2. ZIP ファイルを右クリックし、 [すべて展開] を選択します。Right-click the zip file and select Extract All. さまざまな種類のファイルが 14 個あります。There are 14 files of various types. この演習では、7 個を使用します。You'll use 7 for this exercise.

1 - サービスを作成する1 - Create services

このチュートリアルでは、インデックス作成とクエリに Azure Cognitive Search を使用するほか、AI エンリッチメントには Cognitive Services を、データ提供には Azure Blob Storage を使用します。This walkthrough uses Azure Cognitive Search for indexing and queries, Cognitive Services for AI enrichment, and Azure Blob storage to provide the data. 可能である場合は、近接性と管理性を高めるために、3 つのサービスすべてを同じリージョンおよびリソース グループ内に作成します。If possible, create all three services in the same region and resource group for proximity and manageability. 実際には、Azure Storage アカウントは任意のリージョンに置くことができます。In practice, your Azure Storage account can be in any region.

Azure Storage の使用を開始するStart with Azure Storage

  1. Azure portal にサインインし、 [+ リソースの作成] をクリックします。Sign in to the Azure portal and click + Create Resource.

  2. [ストレージ アカウント] を検索し、Microsoft のストレージ アカウント オファリングを選択します。Search for storage account and select Microsoft's Storage Account offering.

    ストレージ アカウントの作成Create Storage account

  3. [基本] タブでは、次の項目が必要です。In the Basics tab, the following items are required. それ以外のすべてのものには、既定値をそのまま使用します。Accept the defaults for everything else.

    • リソース グループResource group. 既存のものを選択するか、新しいものを作成します。ただし、すべてのサービスに同じグループを使用して、それらをまとめて管理できるようにします。Select an existing one or create a new one, but use the same group for all services so that you can manage them collectively.

    • ストレージ アカウント名Storage account name. 同じ種類のリソースが複数存在することになると考えられる場合は、名前を使用して、種類とリージョンを基に区別が付くようにします (たとえば、blobstoragewestus)。If you think you might have multiple resources of the same type, use the name to disambiguate by type and region, for example blobstoragewestus.

    • 場所Location. 可能であれば、Azure Cognitive Search と Cognitive Services に使用するのと同じ場所を選択します。If possible, choose the same location used for Azure Cognitive Search and Cognitive Services. 1 つの場所であれば、帯域幅の料金がかかりません。A single location voids bandwidth charges.

    • アカウントの種類Account Kind. 既定値の [StorageV2 (general purpose v2)](StorageV2 (汎用 v2)) を選択します。Choose the default, StorageV2 (general purpose v2).

  4. [確認および作成] をクリックしてサービスを作成します。Click Review + Create to create the service.

  5. 作成されたら、 [Go to the resource](リソースに移動) をクリックして [概要] ページを開きます。Once it's created, click Go to the resource to open the Overview page.

  6. [BLOB] サービスをクリックします。Click Blobs service.

  7. [+ コンテナー] をクリックしてコンテナーを作成し、cog-search-demo という名前を付けます。Click + Container to create a container and name it cog-search-demo.

  8. [cog-search-demo] を選択し、 [アップロード] をクリックして、ダウンロード ファイルを保存したフォルダーを開きます。Select cog-search-demo and then click Upload to open the folder where you saved the download files. 画像以外のすべてのファイルを選択します。Select all of the non-image files. 7 個のファイルがあるはずです。You should have 7 files. [OK] をクリックしてアップロードします。Click OK to upload.

    サンプル ファイルをアップロードするUpload sample files

  9. Azure Storage を終了する前に、Azure Cognitive Search で接続を作成できるように、接続文字列を取得します。Before you leave Azure Storage, get a connection string so that you can formulate a connection in Azure Cognitive Search.

    1. 自分のストレージ アカウント (例として blobstragewestus を使用しています) の [概要] ページに戻ります。Browse back to the Overview page of your storage account (we used blobstragewestus as an example).

    2. 左側のナビゲーション ウィンドウで、 [アクセス キー] を選択し、いずれかの接続文字列をコピーします。In the left navigation pane, select Access keys and copy one of the connection strings.

    接続文字列は、次の例のような URL です。The connection string is a URL similar to the following example:

    DefaultEndpointsProtocol=https;AccountName=cogsrchdemostorage;AccountKey=<your account key>;EndpointSuffix=core.windows.net
    
  10. メモ帳に接続文字列を保存します。Save the connection string to Notepad. これは、後でデータ ソース接続を設定するときに必要になります。You'll need it later when setting up the data source connection.

Cognitive ServicesCognitive Services

AI エンリッチメントは、自然言語と画像の処理のための Text Analytics や Computer Vision など、Cognitive Services によってサポートされています。AI enrichment is backed by Cognitive Services, including Text Analytics and Computer Vision for natural language and image processing. 実際のプロトタイプまたはプロジェクトを完成させることが目的であれば、この時点で (Azure Cognitive Search と同じリージョンに) Cognitive Services をプロビジョニングして、インデックス作成操作にアタッチできるようにします。If your objective was to complete an actual prototype or project, you would at this point provision Cognitive Services (in the same region as Azure Cognitive Search) so that you can attach it to indexing operations.

ただし、この演習では、Azure Cognitive Search がバックグラウンドで Cognitive Services に接続し、インデクサーの実行ごとに 20 個の無料トランザクションを提供できるため、リソースのプロビジョニングをスキップできます。For this exercise, however, you can skip resource provisioning because Azure Cognitive Search can connect to Cognitive Services behind the scenes and give you 20 free transactions per indexer run. このチュートリアルで使用するトランザクションは 7 個であるため、無料の割り当てで十分です。Since this tutorial uses 7 transactions, the free allocation is sufficient. より大規模なプロジェクトの場合は、従量課金制の S0 レベルで Cognitive Services をプロビジョニングすることを計画してください。For larger projects, plan on provisioning Cognitive Services at the pay-as-you-go S0 tier. 詳細については、Cognitive Services のアタッチに関するページを参照してください。For more information, see Attach Cognitive Services.

3 番目のコンポーネントは Azure Cognitive Search であり、ポータルで作成できます。The third component is Azure Cognitive Search, which you can create in the portal. このチュートリアルは Free レベルを使用して完了できます。You can use the Free tier to complete this walkthrough.

Azure Blob Storage と同様に、アクセス キーを収集してください。As with Azure Blob storage, take a moment to collect the access key. さらに、要求の構築を始めるときに、各要求の認証に使用されるエンドポイントと管理者 API キーを指定する必要があります。Further on, when you begin structuring requests, you will need to provide the endpoint and admin api-key used to authenticate each request.

  1. Azure portal にサインインし、自分の検索サービスの [概要] ページで、自分の検索サービスの名前を確認します。Sign in to the Azure portal, and in your search service Overview page, get the name of your search service. エンドポイント URL を見ることで、自分のサービス名を確かめることができます。You can confirm your service name by reviewing the endpoint URL. エンドポイント URL が https://mydemo.search.windows.net だったら、自分のサービス名は mydemo になります。If your endpoint URL were https://mydemo.search.windows.net, your service name would be mydemo.

  2. [設定] > [キー] で、サービスに対する完全な権限の管理キーを取得します。In Settings > Keys, get an admin key for full rights on the service. 管理キーをロールオーバーする必要がある場合に備えて、2 つの交換可能な管理キーがビジネス継続性のために提供されています。There are two interchangeable admin keys, provided for business continuity in case you need to roll one over. オブジェクトの追加、変更、および削除の要求には、主キーまたはセカンダリ キーのどちらかを使用できます。You can use either the primary or secondary key on requests for adding, modifying, and deleting objects.

    クエリ キーも入手します。Get the query key as well. 読み取り専用アクセスを使用してクエリ要求を発行することをお勧めします。It's a best practice to issue query requests with read-only access.

サービス名、管理キー、クエリ キーの取得

すべての要求で、自分のサービスに送信される各要求のヘッダーに API キーが必要になります。All requests require an api-key in the header of every request sent to your service. 有効なキーにより、要求を送信するアプリケーションとそれを処理するサービスの間で、要求ごとに信頼が確立されます。A valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

2 - Postman を設定する2 - Set up Postman

Postman を開始し、HTTP 要求を設定します。Start Postman and set up an HTTP request. このツールに慣れていない場合は、Postman を使用して Azure Cognitive Search REST API を調べる方法に関するページを参照してください。If you are unfamiliar with this tool, see Explore Azure Cognitive Search REST APIs using Postman.

このチュートリアルで使用した要求メソッドは POSTPUTGET です。The request methods used in this tutorial are POST, PUT, and GET. これらのメソッドを使用して、検索サービスに対して 4 つの API 呼び出しを行い、データ ソース、スキルセット、インデックス、およびインデクサーを作成します。You'll use the methods to make four API calls to your search service: create a data source, a skillset, an index, and an indexer.

ヘッダーで "Content-type" を application/json に設定し、api-key に自分の Azure Cognitive Search サービスの管理者 API キーを設定します。In Headers, set "Content-type" to application/json and set api-key to the admin api-key of your Azure Cognitive Search service. ヘッダーを設定したら、この演習の各要求でそれらを使用できます。Once you set the headers, you can use them for every request in this exercise.

Postman の要求 URL とヘッダーPostman request URL and header

3 - パイプラインを作成する3 - Create the pipeline

Azure Cognitive Search では、AI 処理はインデックス作成 (またはデータ インジェスト) 中に行われます。In Azure Cognitive Search, AI processing occurs during indexing (or data ingestion). チュートリアルのこの部分では、データ ソース、インデックス定義、スキルセット、インデクサーという 4 つのオブジェクトを作成します。This part of the walkthrough creates four objects: data source, index definition, skillset, indexer.

手順 1:データ ソースを作成するStep 1: Create a data source

データ ソース オブジェクトは、ファイルが格納されている BLOB コンテナーへの接続文字列を提供します。A data source object provides the connection string to the Blob container containing the files.

  1. POST と次の URL を使用します。YOUR-SERVICE-NAME は、実際のサービス名に置き換えてください。Use POST and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service.

    https://[YOUR-SERVICE-NAME].search.windows.net/datasources?api-version=2019-05-06
    
  2. 要求の本文に次の JSON 定義をコピーします。connectionString は、自分のストレージ アカウントの実際の接続に置き換えてください。In request Body, copy the following JSON definition, replacing the connectionString with the actual connection of your storage account.

    コンテナー名も忘れずに編集してください。Remember to edit the container name as well. 前の手順でコンテナー名として推奨した名前は、"cog-search-demo" です。We suggested "cog-search-demo" for the container name in an earlier step.

    {
      "name" : "cog-search-demo-ds",
      "description" : "Demo files to demonstrate cognitive search capabilities.",
      "type" : "azureblob",
      "credentials" :
      { "connectionString" :
        "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=<YOUR-ACCOUNT-KEY>;"
      },
      "container" : { "name" : "<YOUR-BLOB-CONTAINER-NAME>" }
    }
    
  3. 要求を送信します。Send the request. 成功を確認する状態コード 201 が表示されるはずです。You should see a status code of 201 confirming success.

403 または 404 エラーが発生した場合は、要求の構造を確認してください。api-version=2019-05-06 はエンドポイント上にある必要があり、api-keyContent-Type の後のヘッダーにある必要があり、その値は Search サービスに対して有効である必要があります。If you got a 403 or 404 error, check the request construction: api-version=2019-05-06 should be on the endpoint, api-key should be in the Header after Content-Type, and its value must be valid for a search service. 構文が正しいことを確認するために、オンラインの JSON 検証ツールを使用して JSON ドキュメントを実行することができます。You might want to run the JSON document through an online JSON validator to make sure the syntax is correct.

手順 2:スキルセットを作成するStep 2: Create a skillset

スキルセット オブジェクトは、コンテンツに適用される一連のエンリッチメント手順です。A skillset object is a set of enrichment steps applied to your content.

  1. PUT と次の URL を使用します。YOUR-SERVICE-NAME は、実際のサービス名に置き換えてください。Use PUT and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service.

    https://[YOUR-SERVICE-NAME].search.windows.net/skillsets/cog-search-demo-ss?api-version=2019-05-06
    
  2. 要求の本文に次の JSON 定義をコピーします。In request Body, copy the JSON definition below. このスキルセットは、次の組み込みスキルで構成されています。This skillset consists of the following built-in skills.

    スキルSkill 説明Description
    エンティティの認識Entity Recognition BLOB コンテナーのコンテンツから、人、組織、および場所の名前を抽出します。Extracts the names of people, organizations, and locations from content in the blob container.
    言語検出Language Detection コンテンツの言語を検出します。Detects the content's language.
    テキスト分割Text Split キー フレーズの抽出スキルを呼び出す前に、大きいコンテンツを小さいチャンクに分割します。Breaks large content into smaller chunks before calling the key phrase extraction skill. キー フレーズ抽出は、50,000 文字以下の入力を受け入れます。Key phrase extraction accepts inputs of 50,000 characters or less. いくつかのサンプル ファイルは、分割してこの制限内に収める必要があります。A few of the sample files need splitting up to fit within this limit.
    キー フレーズ抽出Key Phrase Extraction 上位のキー フレーズを抜き出します。Pulls out the top key phrases.

    各スキルは、ドキュメントのコンテンツで実行されます。Each skill executes on the content of the document. 処理中に、Azure Cognitive Search が各ドキュメントを解析して、さまざまなファイル形式からコンテンツを読み取ります。During processing, Azure Cognitive Search cracks each document to read content from different file formats. ソース ファイルから配信されたテキストが見つかると、ドキュメントごとに 1 つずつ、生成された content フィールドに配置されます。Found text originating in the source file is placed into a generated content field, one for each document. そのため、入力は "/document/content" になります。As such, the input becomes "/document/content".

    キー フレーズの抽出では、テキスト スプリッター スキルを使用して大きなファイルをページに分割するため、キー フレーズ抽出スキルのコンテキストは "/document/content" ではなく、"document/pages/*" (ドキュメント内の各ページ) になります。For key phrase extraction, because we use the text splitter skill to break larger files into pages, the context for the key phrase extraction skill is "document/pages/*" (for each page in the document) instead of "/document/content".

    {
      "description": "Extract entities, detect language and extract key-phrases",
      "skills":
      [
        {
          "@odata.type": "#Microsoft.Skills.Text.EntityRecognitionSkill",
          "categories": [ "Person", "Organization", "Location" ],
          "defaultLanguageCode": "en",
          "inputs": [
            { "name": "text", "source": "/document/content" }
          ],
          "outputs": [
            { "name": "persons", "targetName": "persons" },
            { "name": "organizations", "targetName": "organizations" },
            { "name": "locations", "targetName": "locations" }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
          "inputs": [
            { "name": "text", "source": "/document/content" }
          ],
          "outputs": [
            { "name": "languageCode", "targetName": "languageCode" }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
          "textSplitMode" : "pages",
          "maximumPageLength": 4000,
          "inputs": [
            { "name": "text", "source": "/document/content" },
            { "name": "languageCode", "source": "/document/languageCode" }
          ],
          "outputs": [
            { "name": "textItems", "targetName": "pages" }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
          "context": "/document/pages/*",
          "inputs": [
            { "name": "text", "source": "/document/pages/*" },
            { "name":"languageCode", "source": "/document/languageCode" }
          ],
          "outputs": [
            { "name": "keyPhrases", "targetName": "keyPhrases" }
          ]
        }
      ]
    }
    

    スキルセットのグラフィカル表示を以下に示します。A graphical representation of the skillset is shown below.

    スキルセットを理解するUnderstand a skillset

  3. 要求を送信します。Send the request. Postman によって、成功を確認する状態コード 201 が返されるはずです。Postman should return a status code of 201 confirming success.

注意

出力はインデックスにマップすることができ、ダウンストリーム スキルへの入力として、または言語コードと同様に両方として使用されます。Outputs can be mapped to an index, used as input to a downstream skill, or both as is the case with language code. インデックスでは、言語コードはフィルター処理に役立ちます。In the index, a language code is useful for filtering. 入力としての言語コードは、テキスト分析スキルによって、単語区切りに基づく言語学的規則を通知するために使用されます。As an input, language code is used by text analysis skills to inform the linguistic rules around word breaking. スキルセットの基礎の詳細については、スキルセットを定義する方法に関するページをご覧ください。For more information about skillset fundamentals, see How to define a skillset.

手順 3:インデックスを作成するStep 3: Create an index

インデックスは、Azure Cognitive Search の逆インデックスおよびその他の構成要素でコンテンツの物理的な表現を作成するために使用されるスキーマを提供します。An index provides the schema used to create the physical expression of your content in inverted indexes and other constructs in Azure Cognitive Search. インデックスの最大コンポーネントはフィールド コレクションであり、そこではデータ型と属性によって Azure Cognitive Search でのコンテンツと動作が決まります。The largest component of an index is the fields collection, where data type and attributes determine contents and behaviors in Azure Cognitive Search.

  1. PUT と次の URL を使用して、インデックスに名前を付けます。YOUR-SERVICE-NAME は、実際のサービス名に置き換えてください。Use PUT and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service, to name your index.

    https://[YOUR-SERVICE-NAME].search.windows.net/indexes/cog-search-demo-idx?api-version=2019-05-06
    
  2. 要求の本文に次の JSON 定義をコピーします。In request Body, copy the following JSON definition. content フィールドには、ドキュメント自体が格納されます。The content field stores the document itself. languageCodekeyPhrases、および organizations の追加フィールドは、スキルセットによって作成される新しい情報 (フィールドと値) を表します。Additional fields for languageCode, keyPhrases, and organizations represent new information (fields and values) created by the skillset.

    {
      "fields": [
        {
          "name": "id",
          "type": "Edm.String",
          "key": true,
          "searchable": true,
          "filterable": false,
          "facetable": false,
          "sortable": true
        },
        {
          "name": "metadata_storage_name",
          "type": "Edm.String",
          "searchable": false,
          "filterable": false,
          "facetable": false,
          "sortable": false
        },
        {
          "name": "content",
          "type": "Edm.String",
          "sortable": false,
          "searchable": true,
          "filterable": false,
          "facetable": false
        },
        {
          "name": "languageCode",
          "type": "Edm.String",
          "searchable": true,
          "filterable": false,
          "facetable": false
        },
        {
          "name": "keyPhrases",
          "type": "Collection(Edm.String)",
          "searchable": true,
          "filterable": false,
          "facetable": false
        },
        {
          "name": "persons",
          "type": "Collection(Edm.String)",
          "searchable": true,
          "sortable": false,
          "filterable": true,
          "facetable": true
        },
        {
          "name": "organizations",
          "type": "Collection(Edm.String)",
          "searchable": true,
          "sortable": false,
          "filterable": true,
          "facetable": true
        },
        {
          "name": "locations",
          "type": "Collection(Edm.String)",
          "searchable": true,
          "sortable": false,
          "filterable": true,
          "facetable": true
        }
      ]
    }
    
  3. 要求を送信します。Send the request. Postman によって、成功を確認する状態コード 201 が返されるはずです。Postman should return a status code of 201 confirming success.

手順 4:インデクサーの作成と実行Step 4: Create and run an indexer

インデクサーは、パイプラインを駆動するものです。An Indexer drives the pipeline. これまでに作成した 3 つのコンポーネント (データ ソース、スキルセット、インデックス) は、インデクサーへの入力です。The three components you have created thus far (data source, skillset, index) are inputs to an indexer. Azure Cognitive Search でのインデクサーの作成は、パイプライン全体の動作を引き起こすイベントです。Creating the indexer on Azure Cognitive Search is the event that puts the entire pipeline into motion.

  1. PUT と次の URL を使用して、インデクサーに名前を付けます。YOUR-SERVICE-NAME は、実際のサービス名に置き換えてください。Use PUT and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service, to name your indexer.

    https://[servicename].search.windows.net/indexers/cog-search-demo-idxr?api-version=2019-05-06
    
  2. 要求の本文に次の JSON 定義をコピーします。In request Body, copy the JSON definition below. フィールド マッピング要素に注目してください。これらのマッピングは、データ フローを定義するものであるため、重要です。Notice the field mapping elements; these mappings are important because they define the data flow.

    スキルセットの前に fieldMappings が処理されて、データ ソースからインデックス内のターゲット フィールドにコンテンツが送信されます。The fieldMappings are processed before the skillset, sending content from the data source to target fields in an index. フィールド マッピングを使用して、変更されていない既存のコンテンツをインデックスに送信します。You'll use field mappings to send existing, unmodified content to the index. フィールド名と型が両側で共通していれば、マッピングは必要ありません。If field names and types are the same at both ends, no mapping is required.

    outputFieldMappings はスキルによって作成されるフィールド用であるため、スキルセットの実行後に処理されます。The outputFieldMappings are for fields created by skills, and thus processed after the skillset has run. outputFieldMappings での sourceFieldNames への参照は、ドキュメント解析またはエンリッチメントによって作成されるまでは存在しません。The references to sourceFieldNames in outputFieldMappings don't exist until document cracking or enrichment creates them. targetFieldName はインデックス内のフィールドであり、インデックス スキーマで定義されています。The targetFieldName is a field in an index, defined in the index schema.

    {
      "name":"cog-search-demo-idxr",    
      "dataSourceName" : "cog-search-demo-ds",
      "targetIndexName" : "cog-search-demo-idx",
      "skillsetName" : "cog-search-demo-ss",
      "fieldMappings" : [
        {
          "sourceFieldName" : "metadata_storage_path",
          "targetFieldName" : "id",
          "mappingFunction" :
            { "name" : "base64Encode" }
        },
        {
          "sourceFieldName" : "metadata_storage_name",
          "targetFieldName" : "metadata_storage_name",
          "mappingFunction" :
            { "name" : "base64Encode" }
        },
        {
          "sourceFieldName" : "content",
          "targetFieldName" : "content"
        }
      ],
      "outputFieldMappings" :
      [
        {
          "sourceFieldName" : "/document/persons",
          "targetFieldName" : "persons"
        },
        {
          "sourceFieldName" : "/document/organizations",
          "targetFieldName" : "organizations"
        },
        {
          "sourceFieldName" : "/document/locations",
          "targetFieldName" : "locations"
        },
        {
          "sourceFieldName" : "/document/pages/*/keyPhrases/*",
          "targetFieldName" : "keyPhrases"
        },
        {
          "sourceFieldName": "/document/languageCode",
          "targetFieldName": "languageCode"
        }
      ],
      "parameters":
      {
        "maxFailedItems":-1,
        "maxFailedItemsPerBatch":-1,
        "configuration":
        {
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default",
          "firstLineContainsHeaders": false,
          "delimitedTextDelimiter": ","
        }
      }
    }
    
  3. 要求を送信します。Send the request. Postman によって、処理の成功を確認する状態コード 201 が返されるはずです。Postman should return a status code of 201 confirming successful processing.

    この手順は完了までに数分かかる予定です。Expect this step to take several minutes to complete. データ セットが小さい場合でも、分析スキルは計算を集中的に行います。Even though the data set is small, analytical skills are computation-intensive.

注意

インデクサーを作成すると、パイプラインが呼び出されます。Creating an indexer invokes the pipeline. データ、入力と出力のマッピング、または操作の順序に及ぶ問題がある場合は、この段階で現れます。If there are problems reaching the data, mapping inputs and outputs, or order of operations, they appear at this stage. コードまたはスクリプトに変更を加えてパイプラインを再実行するには、最初にオブジェクトを削除する必要がある場合があります。To re-run the pipeline with code or script changes, you might need to drop objects first. 詳細については、「リセットして再実行する」をご覧ください。For more information, see Reset and re-run.

インデクサーのパラメーターについてAbout indexer parameters

スクリプトで "maxFailedItems" を -1 に設定します。これにより、インデックス作成エンジンに、データのインポート中のエラーを無視するよう指示します。The script sets "maxFailedItems" to -1, which instructs the indexing engine to ignore errors during data import. デモのデータ ソースにはドキュメントがほとんどないため、これは許容できます。This is acceptable because there are so few documents in the demo data source. 大きいデータ ソースの場合は、この値を 0 より大きい値に設定します。For a larger data source, you would set the value to greater than 0.

"dataToExtract":"contentAndMetadata" ステートメントは、さまざまなファイル形式と、各ファイルに関連するメタデータからコンテンツを自動的に抽出するようにインデクサーに指示します。The "dataToExtract":"contentAndMetadata" statement tells the indexer to automatically extract the content from different file formats as well as metadata related to each file.

コンテンツが抽出されるときに、imageAction を設定して、データ ソース内にある画像からテキストを抽出することができます。When content is extracted, you can set imageAction to extract text from images found in the data source. "imageAction":"generateNormalizedImages" 構成は、OCR スキルおよびテキスト マージ スキルと組み合わされて、イメージからテキスト (たとえば、一時停止の道路標識から "stop" という単語) を抽出し、それをコンテンツ フィールドの一部として埋め込むよう、インデクサーに指示します。The "imageAction":"generateNormalizedImages" configuration, combined with the OCR Skill and Text Merge Skill, tells the indexer to extract text from the images (for example, the word "stop" from a traffic Stop sign), and embed it as part of the content field. この動作は、ドキュメントに埋め込まれているイメージ (PDF 内のイメージを考えてください) と、データ ソース内にあるイメージ (たとえば、JPG ファイル) の両方に適用されます。This behavior applies to both the images embedded in the documents (think of an image inside a PDF), as well as images found in the data source, for instance a JPG file.

4 - インデックス作成を監視する4 - Monitor indexing

インデックス作成とエンリッチメントは、インデクサー作成要求を送信するとすぐに開始されます。Indexing and enrichment commence as soon as you submit the Create Indexer request. 定義したコグニティブ スキルによっては、インデックス作成に時間がかかる場合があります。Depending on which cognitive skills you defined, indexing can take a while. インデクサーがまだ実行中かどうかを調べるには、次の要求を送信して、インデクサーの状態を確認します。To find out whether the indexer is still running, send the following request to check the indexer status.

  1. GET と次の URL を使用して、インデクサーに名前を付けます。YOUR-SERVICE-NAME は、実際のサービス名に置き換えてください。Use GET and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service, to name your indexer.

    https://[YOUR-SERVICE-NAME].search.windows.net/indexers/cog-search-demo-idxr/status?api-version=2019-05-06
    
  2. 応答を調べて、インデクサーが実行されているかどうかを確認するか、エラーと警告の情報を確認します。Review the response to learn whether the indexer is running, or to view error and warning information.

Free レベルを使用している場合は、次のメッセージが表示されます: "Could not extract content or metadata from your document.If you are using the Free tier, the following message is expected: `"Could not extract content or metadata from your document. Truncated extracted text to '32768' characters." (ドキュメントからコンテンツまたはメタデータを抽出できませんでした。抽出されたテキストが '32768' 文字に切り詰められました。)Truncated extracted text to '32768' characters". このメッセージが表示されるのは、Free レベルでの BLOB のインデックス作成には、文字の抽出に 32K の制限があるためです。This message appears because blob indexing on the Free tier has a32K limit on character extraction. より上位のレベルでは、このデータ セットに対してこのメッセージは表示されません。You won't see this message for this data set on higher tiers.

注意

警告は一部のシナリオで一般的であり、必ずしも問題を示すとは限りません。Warnings are common in some scenarios and do not always indicate a problem. たとえば、BLOB コンテナーに画像ファイルが含まれていて、パイプラインで画像を処理しない場合、画像が処理されなかったことを示す警告が表示されます。For example, if a blob container includes image files, and the pipeline doesn't handle images, you'll get a warning stating that images were not processed.

新しいフィールドと情報を作成したので、いくつかのクエリを実行して、コグニティブ検索の価値を理解しましょう。コグニティブ検索は、一般的な検索シナリオに関連しています。Now that you've created new fields and information, let's run some queries to understand the value of cognitive search as it relates to a typical search scenario.

ドキュメント全体が単一の content フィールドにパッケージ化されている BLOB コンテンツから始めたことを思い出してください。Recall that we started with blob content, where the entire document is packaged into a single content field. このフィールドを検索して、クエリに一致するものを見つけることができます。You can search this field and find matches to your queries.

  1. GET と次の URL を使用して、用語や語句の出現箇所を検索します。YOUR-SERVICE-NAME は、実際のサービス名に置き換えてください。これにより、content フィールドと、一致するドキュメントの数が返されます。Use GET and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service, to search for instances of a term or phrase, returning the content field and a count of the matching documents.

    https://[YOUR-SERVICE-NAME].search.windows.net/indexes/cog-search-demo-idx?search=*&$count=true&$select=content?api-version=2019-05-06
    

    このクエリでは、結果としてドキュメントのコンテンツが返されます。これは、コグニティブ検索パイプラインなしで BLOB インデクサーを使用した場合に取得されるのと同じ結果です。The results of this query return document contents, which is the same result you would get if used the blob indexer without the cognitive search pipeline. このフィールドは検索可能ですが、ファセット、フィルター、またはオートコンプリートを使用したいと思っても、動作しません。This field is searchable, but unworkable if you want to use facets, filters, or autocomplete.

    コンテンツ フィールドの出力Content field output

  2. 2 番目のクエリでは、パイプラインによって作成された新しいフィールドの一部 (persons、organizations、locations、languageCode) が返されます。For the second query, return some of the new fields created by the pipeline (persons, organizations, locations, languageCode). 簡潔にするために keyPhrases は省略していますが、それらの値を確認したい場合は含める必要があります。We're omitting keyPhrases for brevity, but you should include it if you want to see those values.

    https://mydemo.search.windows.net/indexes/cog-search-demo-idx/docs?search=*&$count=true&$select=metadata_storage_name,persons,organizations,locations,languageCode&api-version=2019-05-06
    

    $select ステートメントのフィールドには、Cognitive Services の自然言語処理機能によって作成された新しい情報が含まれています。The fields in the $select statement contain new information created from the natural language processing capabilities of Cognitive Services. 予想どおり、結果内のノイズやドキュメント間のバリエーションもいくらかあるものの、多くの場合、分析モデルによって正確な結果が生成されます。As you might expect, there is some noise in the results and variation across documents, but in many instances, the analytical models produce accurate results.

    次の図は、Satya Nadella が Microsoft で CEO に就任したときの公開書簡に対する結果を示しています。The following image shows results for Satya Nadella's open letter upon assuming the CEO role at Microsoft.

    パイプラインの出力Pipeline output

  3. これらのフィールドをどのように活用できるかを確認するには、ファセット パラメーターを追加して、場所ごとの一致するドキュメントの集計を返します。To see how you might take advantage of these fields, add a facet parameter to return an aggregation of matching documents by location.

    https://[YOUR-SERVICE-NAME].search.windows.net/indexes/cog-search-demo-idx/docs?search=*&facet=locations&api-version=2019-05-06
    

    この例では、場所ごとに 2 件または 3 件の一致があります。In this example, for each location, there are 2 or 3 matches.

    ファセットの出力Facet output

  4. この最後の例では、組織のコレクションにフィルターを適用します。それにより、NASDAQ に基づくフィルター条件に対して 2 件の一致が返されます。In this final example, apply a filter on the organizations collection, returning two matches for filter criteria based on NASDAQ.

    cog-search-demo-idx/docs?search=*&$filter=organizations/any(organizations: organizations eq 'NASDAQ')&$select=metadata_storage_name,organizations&$count=true&api-version=2019-05-06
    

これらのクエリは、コグニティブ検索によって作成された新しいフィールドでクエリ構文やフィルターを操作するいくつかの方法を示しています。その他のクエリの例については、Search Documents REST API の例単純構文クエリの例、および完全な Lucene クエリの例に関するページを参照してください。These queries illustrate a few of the ways you can work with query syntax and filters on new fields created by cognitive search.For more query examples, see Examples in Search Documents REST API, Simple syntax query examples, and Full Lucene query examples.

リセットして再実行するReset and rerun

パイプライン開発の初期の実験的な段階では、設計反復のための最も実用的なアプローチは、Azure Cognitive Search からオブジェクトを削除してリビルドできるようにすることです。In the early experimental stages of pipeline development, the most practical approach for design iterations is to delete the objects from Azure Cognitive Search and allow your code to rebuild them. リソース名は一意です。Resource names are unique. オブジェクトを削除すると、同じ名前を使用して再作成することができます。Deleting an object lets you recreate it using the same name.

新しい定義でドキュメントのインデックスを再作成するには、以下の操作を行います。To reindex your documents with the new definitions:

  1. インデクサー、インデックス、およびスキルセットを削除します。Delete the indexer, index, and skillset.
  2. オブジェクトを変更します。Modify objects.
  3. サービス上で再作成してパイプラインを実行します。Recreate on your service to run the pipeline.

ポータルを使用して、インデックス、インデクサー、およびスキルセットを削除できます。または、DELETE を使用し、各オブジェクトの URL を指定することもできます。You can use the portal to delete indexes, indexers, and skillsets, or use DELETE and provide URLs to each object. 次のコマンドは、インデクサーを削除します。The following command deletes an indexer.

DELETE https://[YOUR-SERVICE-NAME]].search.windows.net/indexers/cog-search-demo-idxr?api-version=2019-05-06

正常に削除されると、状態コード 204 が返されます。Status code 204 is returned on successful deletion.

コードが成熟したら、リビルド戦略を改善することもできます。As your code matures, you might want to refine a rebuild strategy. 詳細については、インデックスをリビルドする方法に関するページをご覧ください。For more information, see How to rebuild an index.

ここまでのポイントTakeaways

このチュートリアルでは、構成要素 (データ ソース、スキルセット、インデックス、およびインデクサー) の作成によってエンリッチされたインデックス作成パイプラインを作成するための、基本的な手順を示します。This tutorial demonstrates the basic steps for building an enriched indexing pipeline through the creation of component parts: a data source, skillset, index, and indexer.

組み込みのスキルについては、スキルセットの定義と、入力と出力を介したスキルの連結のしくみと共に説明しました。Built-in skills were introduced, along with skillset definition and the mechanics of chaining skills together through inputs and outputs. また、Azure Cognitive Search サービス上の検索可能なインデックスに対し、エンリッチされた値をパイプラインからルーティングするには、インデクサーの定義に outputFieldMappings が必要であることも学習しました。You also learned that outputFieldMappings in the indexer definition is required for routing enriched values from the pipeline into a searchable index on an Azure Cognitive Search service.

最後に、結果をテストし、今後の反復のためにシステムをリセットする方法について学習しました。Finally, you learned how to test results and reset the system for further iterations. インデックスに対するクエリを発行すると、エンリッチされたインデックス作成パイプラインによって作成された出力が返されることを学習しました。You learned that issuing queries against the index returns the output created by the enriched indexing pipeline.

リソースのクリーンアップClean up resources

チュートリアルの後に最も短時間でクリーンアップする方法は、Azure Cognitive Search サービスと Azure Blob service が含まれているリソース グループを削除することです。The fastest way to clean up after a tutorial is by deleting the resource group containing the Azure Cognitive Search service and Azure Blob service. 両方のサービスを同じグループに配置すると仮定した場合は、ここでリソース グループを削除すると、このチュートリアル用に作成したサービスと保存したコンテンツを含み、そのリソース グループ内のすべてのものが完全に削除されます。Assuming you put both services in the same group, delete the resource group now to permanently delete everything in it, including the services and any stored content that you created for this tutorial. Portal では、リソース グループ名は各サービスの [概要] ページに表示されます。In the portal, the resource group name is on the Overview page of each service.

次の手順Next steps

カスタム スキルを使ってパイプラインをカスタマイズまたは拡張します。Customize or extend the pipeline with custom skills. カスタム スキルを作成してスキルセットに追加すると、自分で作成したテキストまたは画像分析をオンボードできます。Creating a custom skill and adding it to a skillset allows you to onboard text or image analysis that you write yourself.