はじめに

組織内に貯まっている大量な構造化・非構造化データから、新たな価値を見出すためのフルマネージド全文検索サービスである Azure Cognitive Search では、カスタムスキルを使って自分で開発したプログラムをインデクサーの処理に組み込むことができます。今回は Azure Functions に Python で作ったカスタムスキルをデプロイして Azure Cognitive Search のインデクサーからコールできるように実装します。

目次

1. カスタムスキルについて
2. アーキテクチャ
3. カスタムスキルの解説
4. インデクサーから送信されるデータ構造
5. カスタムスキルのデプロイ
6. 環境変数のセット
7. インデクサーの実行
8. 参考記事

カスタムスキルについて

Azure Cognitive Search では、カスタムスキルという機能を使って、インデクサーが検索したドキュメントの中身のデータを外部 Web API に飛ばして、さまざまなエンリッチメント処理をすることができます。詳しくは、「Azure Cognitive Search のカスタムスキルを作成しよう」を参照してください。

アーキテクチャ

今回は以下の図のようなアーキテクチャを考えます。

今回のサンプルでは、シンプルに画像データを外部 Web API に送信し、Read API v3.2 を使って OCR 読み取り結果を返すという処理にしています。このサンプルコードをベースにご自分が行いたい処理に書き換えることができます。ちなみに、Azure Cognitive Search の組み込みスキルを使うこともできますが、Azure Cognitive Services 側の更新がすぐに適用されるという訳ではないため、最新のエンドポイント/モデルを使って、パラメータも細かく指定して API をコールしたい場合に対応できます。

カスタムスキルの解説

スキルセット定義に従ってインデクサーから画像データを受け取り、Cognitive Services の Read API v3.2 をコールして結果を取得し、インデクサーに返却するサンプルコードを Github にアップしました。

Read API v3.2 では、読み取り結果取得までに 2 段階の API コール（非同期的）が必要となったため、コードに結果取得のループを入れています。

インデクサーから送信されるデータ構造

このデータ構造を正しく理解してパースしないと入力でハマります。

{
    "values": [
        {
            "recordId": "record1",
            "data": { 
                "image": {
                    "$type": "file",
                    "url": "https://xxx.jpg",
                    "data": "/9j/4AAQS..."
                }
            }
        }
    ]
}

スキルセット定義の入力ソースフィールドに /document/normalized_images/* と指定した場合、上記のようなデータがインデクサーから送信されます。Azure Cognitive Search が優れているのは、画像ファイルだけでなく、ドキュメント内の埋め込み画像についても抽出することができる点です。data 項目には画像データのバイナリが Base64 エンコードされて格納されているので、これをデコードして Python の バイナリストリームにロードしています。

カスタムスキルのデプロイ

ローカルに clone したコードを、Azure Functions にデプロイし、Web API として使えるようにするには、Visual Studio Code から Azure Functions for Visual Studio Code 拡張を使ってデプロイするのが便利です。

Azure Functions for Visual Studio Code 拡張は、Visual Studio Code の拡張機能から functions で検索し、上記の拡張をインストールします。

Functions 拡張をインストールした後は、上記のように Functions メニューから、ボタン一発でデプロイしたり新しい Functions を作成したりすることができます。

「Deploy to Functions App...」ボタンをクリックして、コマンドパレットから以下のように入力します。

1. + Create new Functions App in Azure... Advanced を選択
2. Functions 名を入力して Enter
3. Select a runtime stack で Python 3.6 を選択
4. + Create new resource group を選択
5. 任意のリソースグループ名を入力して Enter
6. Select a location for new resources でデプロイするリージョンを選択
7. Functions のホスティングプランを選択。Consumption で OK
8. + Create new storage account を選択
9. 任意のストレージアカウント名を入力して Enter
10. Application Insight は任意。今はスキップ。

すると自動的に自分のサブスクリプションメニュー配下に新しい Functions が作成されます。いったん作成してしまえば、次からの更新は非常に簡単になります。作成方法に関する詳しい Docs はこちら。

デプロイが完了すると、VS Code の右下に上図のような通知が表示されます。その後、Functions メニューから、作成した Functions 名を選択し、Functions->ReadAPi の順に選択し、右クリックメニューから「Copy Function Url」をクリックすれば、Web API のエンドポイント URL がクリップボードにコピーされます。この URL をスキルセット定義の uri項目に貼り付けます。

「Copy Function Url」をクリックすると [AzureFunctionEndpointUrl]/api/ReadAPI?code=[AzureFunctionDefaultHostKey] の形式で URL がコピーされます。

環境変数のセット

本サンプルをそのまま使用するには、Computer Vision リソースの API キーとエンドポイントを取得しておく必要があります。Azure Portal から Computer Vision サービスを開き、「キーとエンドポイント」からキーとエンドポイントをコピーします。これを Python コードからどのように使用するかというと、セキュリティ上の理由から直接コードに埋め込むことはしません。

        # get key and endpoint from Environment variable
        computerVisionKey = os.environ['COMPUTER_VISION_KEY']
        computerVisionEndpoint = os.environ['COMPUTER_VISION_ENDPOINT']

このように、COMPUTER_VISION_KEY と COMPUTER_VISION_ENDPOINT を環境変数からロードしています。この環境変数は、Azure Functions の「アプリケーションの設定」で定義した値を直接使用することができます。これによってキーの一括管理と保存時の暗号化が適用されます。

VS Code から設定するには、Functions メニューから、「Application Settings」を開き右クリックして「Add New Setting...」からセットすることができます。コマンドパレットからキー名を入力して Enter し、次に値を入力して Enter することで設定できます。Azure Portal から設定するには、Functions を開いて設定→構成を開けば登録できます。

スキルセット定義

Web API 側の設定が完了したので、Azure Cognitive Search 側のスキル定義を編集します。例ではこちらのハンズオンで作成したスキルセット定義をベースに考えます。

{
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "name": "ReadApiSkill",
    "description": "Reads characters from a document using the Read API 3.2.",
    "uri": "[AzureFunctionEndpointUrl]/api/AnalyzeForm?code=[AzureFunctionDefaultHostKey]",
    "context": "/document/normalized_images/*",
    "inputs": [
        {
            "name": "image",
            "source": "/document/normalized_images/*"
        }
    ],
    "outputs": [
        {
          "name": "ocrtext",
          "targetName": "ocrtext"
        }
    ]
}

まず、上記の uri 項目をさきほどコピーした Web API のエンドポイント URL で置き換えます。また、必要に応じて以下のパラメータを追加してパフォーマンスを調整してください。

• timeout: カスタムスキルのタイムアウト値。デフォルト 30 秒
• batchSize: 1コール当たりのデータレコード送信数。デフォルト 1000
• degreeOfParallelism: 並列コール数。デフォルト 5

下のコメント欄でも議論がありますが、カスタムスキルがコールしている API の処理に時間がかかる場合があるため、ひとまずタイムアウト値を最大の "timeout": "PT230S" とすることをお勧めします。

その後上記のカスタムスキル定義をスキルセット定義に追加しますが、すでにハンズオンでは組み込みの OCR スキルが定義されているので、以下の定義をすべて上の定義で置き換えます。

    {
      "@odata.type": "#Microsoft.Skills.Vision.OcrSkill",
      "name": "#5",
      "description": null,
      "context": "/document/normalized_images/*",
      "textExtractionAlgorithm": null,
      "lineEnding": "Space",
      "defaultLanguageCode": "ja",
      "detectOrientation": true,
      "inputs": [
        {
          "name": "image",
          "source": "/document/normalized_images/*"
        }
      ],
      "outputs": [
        {
          "name": "text",
          "targetName": "text"
        },
        {
          "name": "layoutText",
          "targetName": "layoutText"
        }
      ]
    }

その後にあるマージスキルの itemsToInsert を /document/normalized_images/*/text から /document/normalized_images/*/ocrtext に置換します。

   {
      "@odata.type": "#Microsoft.Skills.Text.MergeSkill",
      "name": "#4",
      "inputs": [
      ...
        {
          "name": "itemsToInsert",
          "source": "/document/normalized_images/*/ocrtext"
        },
      ...
   }

これでスキルセット定義の設定は完了です。

インデクサーの実行

Azure Cognitive Search のインデクサーを実行します。実行後、ステータスが「成功」と表示されれば完了です。

完了しましたら、インデックスの検索エクスプローラーからうまく検索できるかどうか確認します。
これで最新の Cognitive Services API をコールするカスタムスキルを実装することができました。

参考記事

Azure Cognitive Search を使って簡単ナレッジマイニングハンズオン（日本語対応）
Azure Cognitive Search のカスタムスキルを作成しよう
Azure Cognitive Search のデバッグセッションを使ってカスタムスキルを追加しよう