Azure OpenAI Embedding スキル

Azure OpenAI Embeddingスキルは、Azure OpenAI in Foundry ModelsリソースやMicrosoft Foundryプロジェクトに展開された埋め込みモデルに接続し、インデックス作成時に埋め込みを生成します。 データはモデルがデプロイされる Geo で処理されます。

AzureポータルのImport dataウィザードは、Azure OpenAIの組み込みスキルを使ってコンテンツをベクトル化しています。 ウィザードを起動して生成されたスキルセットを確認し、ウィザードがどのようにモデル埋め込みのスキルを構築しているかを確認できます。

前提条件

• Azure OpenAIのFoundry ModelsリソースまたはFoundry project。

  • Azure OpenAIリソースにはcustom subdomain、例えばhttps://<resource-name>.openai.azure.comが必要です。 このエンドポイントはAzureポータルのKeys and Endpointページで見つけられ、このスキルの resourceUriプロパティに使えます。

  • Foundryプロジェクトの 親リソース は、 https://<resource-name>.openai.azure.com、 https://<resource-name>.services.ai.azure.com、 https://<resource-name>.cognitiveservices.azure.comを含む複数のエンドポイントへのアクセスを提供します。 これらのエンドポイントはAzureポータルのKeysとEndpointページで見つけられ、このスキルのresourceUriプロパティに使うことができます。

• リソースやプロジェクトにデプロイされたAzure OpenAI埋め込みモデル。 サポートされているモデルについては、 スキルパラメータ のセクションをご覧ください。

@odata.type

Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill

データ制限

テキスト入力の最大サイズは8,000トークンであるべきです。 入力が許容される最大値を超えると、モデルは無効な要求エラーを投げます。 詳細については、Azure OpenAIドキュメントのtokensキーコンセプトをご覧ください。 データチャンクが必要なら Text Split スキルを使うことを検討してください。

スキル パラメーター

パラメータは大文字・小文字を区別します。

サポート寸法 modelName

Azure OpenAI組み込みスキルのサポート寸法は、設定されているmodelNameに依存します。

スキルの入力

スキルの出力

サンプル定義

以下のフィールドを持つレコードを考えます。

{
    "content": "Microsoft released Windows 10."
}

それなら、あなたのスキル定義はこんな感じになるかもしれません:

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://my-demo-openai-eastus.openai.azure.com/",
  "deploymentId": "my-text-embedding-ada-002-model",
  "modelName": "text-embedding-ada-002",
  "dimensions": 1536,
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

サンプル出力

与えられた入力テキストに対して、ベクトル化された埋め込み出力が生成されます。

{
  "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... 
        0.021276434883475304,
      ]
}

出力はメモリ上にあります。 この出力を検索インデックス内のフィールドに送るには、ベクトル化された埋め込み出力(配列)をベクトルフィールドにマッピングするoutputFieldMappingを定義する必要があります。 スキル出力がドキュメントの 埋め込み ノードにあり、 content_vector が検索インデックスのフィールドであると仮定すると、インデクサー内のoutputFieldMappingは次のようになります。

  "outputFieldMappings": [
    {
      "sourceFieldName": "/document/embedding/*",
      "targetFieldName": "content_vector"
    }
  ]

ベスト プラクティス

このスキルを活用する際に考慮すべきベストプラクティスは以下の通りです。

• もしAzure OpenAIのTPM(トークン数/分)の上限に達しているなら、quota limits advisoryを考慮して対応できるようにしてください。 Azure OpenAIインスタンスのパフォーマンスについては、Azure OpenAIモニタリングドキュメントを参照してください。

• このスキルで使うOpenAI埋め込みモデルの展開は、理想的にはquery vectorizerなど他のユースケースで使う展開とは別にすべきです。Azure これにより、各デプロイメントは特定のユースケースに合わせてカスタマイズされ、パフォーマンスの最適化やインデクサーおよびインデックス埋め込みコールからのトラフィックの識別が容易になります。

• Azure OpenAIのインスタンスは、AI検索サービスがホストされている地域と同じ地域、あるいは地理的に近い場所にあるべきです。 これにより遅延が減少し、サービス間のデータ転送速度が向上します。

• 多くの場合、429 個のエラー コードが発生しないようにするには、複数の Azure OpenAI 埋め込みモデルデプロイの前にゲートウェイを実装することで、API Management による負荷分散を実装することを検討してください。

• quotas and limitsドキュメントで公開されているOpenAI TPM(トークン/分)のデフォルトAzure上限を上回っている場合は、Azure AI 検索チームにsupportケースを開設し、適切に調整してください。 これにより、基準値が高い場合、ドキュメント化されたデフォルトのTPM制限によってインデックス作成のプロセスが不必要に遅くなるのを防ぐことができます。

• このスキルを使った例や実行例については、以下のリンクをご覧ください。

  • 統合ベクトル化(Python)
  • Integrated Vectorization (C#)
  • 積分ベクトル化(Java)

エラーと警告

マネージド ID 認証のセキュリティに関する考慮事項

Azure OpenAI Embedding スキルがマネージド ID 認証を使用する場合、Azure AI 検索は Foundry Tools 対象ユーザー (https://cognitiveservices.azure.com) のMicrosoft Entra アクセス トークンを取得し、resourceUriによって指定されたエンドポイントに送信された要求に含めます。 マネージド ID 認証は、 authIdentity が設定されている場合、または apiKey と authIdentity の両方が空で、サービスがシステム割り当て ID を使用する場合に適用されます。

resourceUriによって参照されるエンドポイントは、独自の Azure OpenAI または Foundry Tools リソースである必要があります。 サポートされているドメインは以下の通りです:

• openai.azure.com
• cognitiveservices.azure.com
• services.ai.azure.com

Azure API Management (APIM) エンドポイント (*.azure-api.net) もサポートされています。 APIM ホスト名は名前だけでは検証できないため、Azure AI 検索は、ドメインの照合ではなく、構成時にライブ接続チェックを使用してこれらのエンドポイントを検証します。 APIM エンドポイントとその背後にある Azure OpenAI または Foundry Tools リソースの間の関係を構成し、維持する責任があります。

Foundry Tools 対象ユーザーに対して発行されたマネージド ID トークンは、Foundry Tools または ID が承認されている OpenAI リソースAzureに対して有効です。 信頼されていないエンドポイントに送信すると、トークンが公開される可能性があります。

推奨セキュリティ プラクティス

セキュリティで保護されたデプロイを維持するには、次のプラクティスに従います。

• resourceUriは、自分が所有し、信頼するエンドポイントのみに設定します。 前に示した Foundry Tools ドメインを優先します。 APIM エンドポイントを使用する場合は、マネージド ID を有効にする前に、独自のリソースの前に置くことを確認します。 信頼できる見た目のホスト名は、所有権の証明ではありません。
• 検索サービスで使用されるマネージド ID に最小特権の原則を適用します。 Azure OpenAI Embedding スキルには、ターゲット リソースに対する Cognitive Services OpenAI ユーザー ロールのみが必要です。 より広範なロールの付与は避けてください。
• ネットワーク セキュリティ境界 (NSP) とプライベート エンドポイントまたは VNet 統合を使用して、検索サービスが到達できるエンドポイントと、ターゲット リソースが要求を受け入れるソースを制限します。
• APIM エンドポイントを使用する場合は、ゲートウェイが受信要求を検証し、目的のバックエンドにのみ転送することを確認します。 また、アクセス ポリシーも定期的に確認する必要があります。
• apiKeyよりもマネージド ID を優先します。 apiKeyを使用する場合は、安全に保存して回転させ、ソース管理に埋め込むことはありません。 サービスは、 apiKey と authIdentityの両方を設定する構成を拒否します。
• スキルセットの定義、マネージド ID ロールの割り当て、APIM 構成を定期的に確認して、 resourceUri 値、アクセス制御、ID アクセス許可が最新で適切であることを確認します。 確立された変更管理プロセスとセキュリティ レビュー プロセスを通じて、構成の変更を確認します。
• OpenAI と Foundry Tools Azureサインイン ログ、認証イベント、およびアクセス ログで、予期しないアクティビティまたは未承認のアクティビティを監視します。
• 不要になった未使用のスキル、エンドポイント、ロールの割り当て、API キーを削除します。

スキルセット構成へのアクセスを制限する

スキルセットを作成、変更、または実行できるユーザーは、ターゲット エンドポイント (resourceUri) とスキルで使用される認証構成の両方を制御します。 このスキルは Foundry Tools 対象ユーザーのマネージド ID トークンをそのエンドポイントに送信するため、これらのアクセス許可を信頼された管理者に制限し、マネージド ID 対応スキルを構成するときに、標準の変更管理およびセキュリティ レビュー プロセスに従います。

こちらも参照ください

• 組み込みスキル
• スキルセットの定義方法
• 出力場のマッピングの定義方法