リファレンス: 画像埋め込み | Azure Machine Learning

[アーティクル]
09/04/2024

入力画像とテキストのペアを表す埋め込みベクトルを作成します。

POST /images/embeddings?api-version=2024-04-01-preview

URI パラメーター

名前	/	必須	タイプ	説明
api-version	query	○	string	"YYYY-MM-DD" または "YYYY-MM-DD-preview" 形式の API のバージョン。

要求ヘッダー

名前	Required	タイプ	説明
extra-parameters		string	ペイロードに追加のパラメーターが指定されている場合の API の動作。 `pass-through` を使用すると、この API は、基になるモデルにパラメーターを渡すことができます。この値は、基になるモデルがサポートできるとわかっているパラメーターを渡す場合に使用します。 `ignore` を使用すると、この API は、サポートされていないパラメーターを削除します。この値は、異なるモデル間で同じペイロードを使用する必要があり、モデルでサポートされていない場合にエラーになる可能性がある追加のパラメーターの 1 つを使用する場合に使用します。 `error` を使用すると、この API はペイロード内の追加のパラメーターを拒否します。この API で指定されたパラメーターのみを指定できます。それ以外の場合は 400 エラーが返されます。
azureml-model-deployment		string	要求のルーティング先のデプロイの名前。複数のデプロイをサポートするエンドポイントでサポートされます。

要求本文

名前	Required	タイプ	説明
input	True	EmbeddingInput[]	埋め込む入力画像。 1 つの要求に複数の入力を埋め込むには、配列を渡します。入力は、モデルの最大入力トークンを超えてはなりません。
dimensions		integer	結果として出力される埋め込みに必要なディメンションの数。 null を渡すと、モデルは既定値を使います。モデルが値またはパラメーターをサポートしていない場合は、422 エラーを返します。
encoding_format		EmbeddingEncodingFormat	埋め込みを返す形式。 base64、float、int8、uint8、binary、または ubinary のいずれか。モデルが値またはパラメーターをサポートしていない場合は、422 エラーを返します。

応答

名前	種類	説明
200 OK	CreateEmbeddingResponse	[OK]
401 権限がありません	UnauthorizedError	アクセストークンが見つからないか無効ですヘッダー x-ms-error-code: string
404 見つかりません	NotFoundError	モダリティがモデルによってサポートされていません。モデルのドキュメントを確認して、どのルートが利用可能であるかを確認します。ヘッダー x-ms-error-code: string
422 処理できなかったエンティティ	UnprocessableContentError	要求に処理できないコンテンツが含まれています。指定されたペイロードがこの仕様に従って有効な場合、エラーが返されます。ただし、ペイロードに示されている命令の一部は、基になるモデルではサポートされていません。 `details` セクションは、問題のあるパラメーターを理解するために使用します。ヘッダー x-ms-error-code: string
429 要求が多すぎます	TooManyRequestsError	割り当てられたレート制限に達したため、要求のペースを調整する必要があります。ヘッダー x-ms-error-code: string
その他の状態コード	ContentFilterError	Bad request ヘッダー x-ms-error-code: string

セキュリティ

承認

Bearer: というプレフィックスが付いたトークン (例: Bearer abcde12345)

種類: apiKey
入力: ヘッダー

AADToken

Azure Active Directory OAuth2 認証

種類: oauth2
フロー: アプリケーション
トークン URL: https://login.microsoftonline.com/common/oauth2/v2.0/token

例

入力テキストと画像を表す埋め込みベクトルを作成します

サンプル要求

POST /images/embeddings?api-version=2024-04-01-preview

{
  "input": [
    {
      "text": "A nice picture of a cat",
      "image": "data:image/jpeg;base64,iVBORw0KG..."
    }
  ],
  "encoding_format": "float",
  "dimensions": 1024
}

サンプル応答

状態コード:200

{
  "data": [
    {
      "index": 0,
      "object": "embedding",
      "embedding": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    }
  ],
  "object": "list",
  "model": "DINO",
  "usage": {
    "prompt_tokens": 15,
    "total_tokens": 15
  }
}

定義

名前	説明
ContentFilterError	プロンプトが構成どおりにコンテンツフィルターをトリガーすると、API 呼び出しは失敗します。プロンプトを変更して、もう一度やり直してください。
CreateEmbeddingResponse
CreateImageEmbeddingRequest
詳細
埋め込み	生成された画像を表します。
EmbeddingEncodingFormat	埋め込みを返す形式。 base64、float、int8、uint8、binary、または ubinary のいずれか。モデルが値またはパラメーターをサポートしていない場合は、422 エラーを返します。
EmbeddingObject	オブジェクトの種類。これは常に "embedding" です。
EmbeddingInput	画像と省略可能なテキストを表します。
ListObject	オブジェクトの種類。常に "list" です。
NotFoundError
TooManyRequestsError
UnauthorizedError
UnprocessableContentError	要求に処理できないコンテンツが含まれています。指定されたペイロードがこの仕様に従って有効な場合、エラーが返されます。ただし、ペイロードに示されている命令の一部は、基になるモデルではサポートされていません。 `details` セクションは、問題のあるパラメーターを理解するために使用します。
使用方法	要求の使用状況に関する情報。

ContentFilterError

プロンプトが構成どおりにコンテンツフィルターをトリガーすると、API 呼び出しは失敗します。プロンプトを変更して、もう一度やり直してください。

名前	種類	説明
code	string	エラーコード。
エラー	string	エラーの説明。
message	string	エラーメッセージ。
param	string	コンテンツフィルターをトリガーしたパラメーター。
status	integer	HTTP 状態コード。

CreateEmbeddingResponse

名前	種類	説明
data	Embedding[]	モデルによって生成された埋め込みの一覧。
モデル	string	埋め込みを生成するために使われるモデルの名前。
オブジェクト	ListObject	オブジェクトの種類。常に "list" です。
使用量	使用方法	要求の使用状況情報。

CreateImageEmbeddingRequest

名前	種類	既定値	説明
dimensions	integer		結果として出力される埋め込みに必要なディメンションの数。 null を渡すと、モデルは既定値を使います。モデルが値またはパラメーターをサポートしていない場合は、422 エラーを返します。
encoding_format	EmbeddingEncodingFormat	float	埋め込みを返す形式。 base64、float、int8、uint8、binary、または ubinary のいずれか。モデルが値またはパラメーターをサポートしていない場合は、422 エラーを返します。
input	EmbeddingInput[]		埋め込む入力画像。 1 つの要求に複数の入力を埋め込むには、配列を渡します。入力は、モデルの最大入力トークンを超えてはなりません。

詳細

名前	種類	説明
loc	string[]	問題の原因となっているパラメーター
値	string	問題の原因となっているパラメーターに渡される値。

埋め込み

生成された画像を表します。

名前	種類	説明
埋め込み	number[]	埋め込みベクター。浮動小数点数のリストです。ベクトルの長さは、使われるモデルによって異なります。
インデックス	integer	埋め込みリスト内の埋め込みのインデックス。
オブジェクト	EmbeddingObject	オブジェクトの種類。これは常に "embedding" です。

EmbeddingEncodingFormat

埋め込みを返す形式。 base64、float、int8、uint8、binary、または ubinary のいずれか。モデルが値またはパラメーターをサポートしていない場合は、422 エラーを返します。

名前	種類	説明
base64	string
binary	string
float	string
int8	string
ubinary	string
uint8	string

EmbeddingObject

オブジェクトの種類。これは常に "embedding" です。

名前	種類	説明
埋め込み	string

EmbeddingInput

画像と省略可能なテキストを表します。

名前	種類	内容
image	string	`base64` 文字列にデータ URL としてエンコードされた入力イメージ。例: `data:image/{format};base64,{data}`。
text	string	省略可能。モデルにフィードするテキスト入力 (DINO、CLIP など)。モデルが値またはパラメーターをサポートしていない場合は、422 エラーを返します。

ListObject

オブジェクトの種類。常に "list" です。

名前	種類	説明設定
list	string

NotFoundError

名前	種類	説明
エラー	string	エラーの説明。
message	string	エラーメッセージ。
status	integer	HTTP 状態コード。

TooManyRequestsError

名前	種類	説明
エラー	string	エラーの説明。
message	string	エラーメッセージ。
status	integer	HTTP 状態コード。

UnauthorizedError

名前	種類	説明
エラー	string	エラーの説明。
message	string	エラーメッセージ。
status	integer	HTTP 状態コード。

UnprocessableContentError

要求に処理できないコンテンツが含まれています。指定されたペイロードがこの仕様に従って有効な場合、エラーが返されます。ただし、ペイロードに示されている命令の一部は、基になるモデルではサポートされていません。 details セクションは、問題のあるパラメーターを理解するために使用します。

名前	種類	説明
code	string	エラーコード。
詳細	詳細
エラー	string	エラーの説明。
message	string	エラーメッセージ。
status	integer	HTTP 状態コード。

使用方法

要求の使用状況に関する情報。

名前	種類	説明
prompt_patches	integer	画像プロンプトで使われた画像パッチ数。
prompt_tokens	integer	プロンプトで使われたトークン数。
total_patches	integer	要求によって使われたパッチの合計数。
total_tokens	integer	要求によって使用されるトークンの合計数。

次の方法で共有