Azure AI Search エンリッチメント パイプラインの AML スキル

  • [アーティクル]

重要

このスキルはパブリック プレビュー段階にあり、追加利用規約の下で提供されます。 プレビューの REST API では、このスキルがサポートされています。

AML スキルを使用すると、カスタム Azure Machine Learning (AML) モデルを使用して AI エンリッチメントを拡張できます。 AML モデルがトレーニングされてデプロイされると、AML スキルによって AI エンリッチメントに統合されます。

組み込みスキルと同様に、AML スキルには入力と出力があります。 入力は、デプロイされた AML オンライン エンドポイントに JSON オブジェクトとして送信され、成功状態コードとともに JSON ペイロードを応答として出力します。 応答には、AML スキルによって指定された出力が含まれることが想定されます。 その他の応答はエラーと見なされ、エンリッチメントは実行されません。

Note

インデクサーは、AML オンライン エンドポイントから特定の標準 HTTP 状態コードが返された場合には、再試行を 2 回行います。 これらの HTTP 状態コードは次のとおりです。

  • 503 Service Unavailable
  • 429 Too Many Requests

前提条件

@odata.type

Microsoft.Skills.Custom.AmlSkill

スキルのパラメーター

パラメーターの大文字と小文字は区別されます。 どのパラメーターを使用するかは、AML オンライン エンドポイントが必要とする認証 (存在する場合) によって異なります

パラメーター名 説明
uri (キー認証の場合に必要) JSON ペイロードが送信される AML オンライン エンドポイントのスコアリング URI。 https URI スキームのみが許可されます。
key (キー認証の場合に必要) AML オンライン エンドポイントのキー。
resourceId (トークン認証の場合に必要)。 AML オンライン エンドポイントの Azure Resource Manager リソース ID。 subscriptions/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{workspace-name}/onlineendpoints/{endpoint_name} という形式にする必要があります。
region (トークン認証の場合は省略可能)。 AML オンライン エンドポイントがデプロイされるリージョン。
timeout (省略可能) 指定した場合は、API 呼び出しを行う http クライアントのタイムアウト値を示します。 XSD "dayTimeDuration" 値 (ISO 8601 期間値の制限されたサブセット) として書式設定する必要があります。 たとえば、60 秒の場合は PT60S とします。 設定しなかった場合は、既定値の 30 秒が選択されます。 タイムアウトは、最大で 230 秒、最小で 1 秒に設定できます。
degreeOfParallelism (省略可能) 指定した場合は、指定したエンドポイントに対してインデクサーが並列で行う呼び出しの数を示します。 要求負荷が高すぎてエンドポイントが失敗する場合は、この値を減らすことができます。 エンドポイントで詳細な要求を受け入れることができ、インデクサーのパフォーマンスを向上させる必要がある場合は、この値を増やすことができます。 設定しない場合は、既定値の 5 が使用されます。 degreeOfParallelism には、最大値として 10、最小値として 1 を設定できます。

使用するスキル パラメーター

必要な AML スキル パラメーターは、AML オンライン エンドポイントが使用する認証 (存在する場合) に応じて異なります。 AML オンライン エンドポイントでは、次の 2 つの認証オプションが提供されます。

  • キーベースの認証。 AML スキルからのスコアリング要求を認証するために、静的なキーが提供されます。
    • uri および key パラメーターを使用します。
  • トークンベースの認証。 AML オンライン エンドポイントは、トークン ベースの認証を使用してデプロイされます。 Azure AI Search Serviceの マネージド ID を有効にする必要があります。 その後、AML スキルは、サービスのマネージド ID を使用して、静的キーを必要とせず、AML オンライン エンドポイントに対して認証します。 ID は、所有者または共同作成者ロールに割り当てられる必要があります。
    • resourceId パラメーターを使用します。
    • 検索サービスが AML ワークスペースとは異なるリージョンにある場合は、 リージョン パラメータを使用して、AML オンライン エンドポイントがデプロイされたリージョンを設定します

スキルの入力

このスキルの "定義済みの" 入力はありません。 このスキルの実行時に既に利用可能な 1 つ以上のフィールドを入力として選択できます。そのため、AML オンライン エンドポイントに送信される JSON ペイロードには、さまざまなフィールドが存在することになります。

スキルの出力

このスキルの "定義済みの" 出力はありません。 AML オンライン エンドポイントが返す応答に応じて出力フィールドを追加し、JSON 応答からそれらを選択できるようにしてください。

定義例

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

入力の JSON 構造体のサンプル

この JSON 構造体は、AML オンライン エンドポイントに送信されるペイロードを表します。 構造体の最上位レベルのフィールドは、スキル定義の inputs セクションで指定された "names" に対応します。 これらのフィールドの値は、それらのフィールドの source からの値になります (これは、ドキュメント内のフィールドからの値になる可能性もありますし、他のスキルからの値になる可能性もあります)

{
  "text": "Este es un contrato en Inglés"
}

出力の JSON 構造体のサンプル

出力は、AML オンライン エンドポイントから返された応答に対応します。 AML オンライン エンドポイントは、JSON ペイロードのみを返す必要があります (Content-Type 応答ヘッダーを確認することで検証されます)。また、フィールドが output 内の "names" に一致するエンリッチメントで、値がエンリッチメントと見なされるオブジェクトである必要もあります。

{
    "detected_language_code": "es"
}

インライン整形のサンプルの定義

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "shapedText",
        "sourceContext": "/document",
        "inputs": [
            {
              "name": "content",
              "source": "/document/content"
            }
        ]
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

インライン整形の入力 JSON 構造体

{
  "shapedText": { "content": "Este es un contrato en Inglés" }
}

インライン整形のサンプル出力 JSON 構造体

{
    "detected_language_code": "es"
}

エラーになる場合

AML が利用できない場合や、成功以外の状態コードが送信された場合に加え、次の場合もエラーと見なされます。

  • AML オンライン エンドポイントからは成功の状態コードが返されたものの、応答ではそれが application/json でないと示されている場合、その応答は無効と見なされ、エンリッチメントは実行されません。
  • AML オンライン エンドポイントが有効な JSON を返す場合

AML オンライン エンドポイントが利用できないか、HTTP エラーが返された場合は、HTTP エラーに関する入手可能な詳細情報が含まれるわかりやすいエラーが、インデクサーの実行履歴に追加されます。

関連項目