參考：影像內嵌 | Azure AI Studio
重要
本文中標示為 (預覽) 的項目目前處於公開預覽狀態。 此預覽版本沒有服務等級協定，不建議將其用於生產工作負載。 可能不支援特定功能，或可能已經限制功能。 如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。
建立內嵌向量，代表輸入影像和文字組。
POST /images/embeddings?api-version=2024-04-01-preview
URI 參數
| 名稱 | 位於 | 必要 | 類型 | 描述 |
|---|---|---|---|---|
| api-version | query | True | 字串 | 格式為 "YYYY-MM-DD" 或 "YYYY-MM-DD-preview" 的 API 版本。 |
要求標頭
| 名稱 | 必要 | 類型 | 描述 |
|---|---|---|---|
| extra-parameters | 字串 | 當承載中指出額外參數時，API 的行為。 使用 pass-through 讓 API 將參數傳遞至基礎模型。 當您想要傳遞您知道基礎模型可支援的參數時，請使用此值。 使用 ignore 可讓 API 卸除任何不支援的參數。 當您需要跨不同模型使用相同的承載時，請使用此值，但如果不支援，其中一個額外的參數可能會讓模型發生錯誤。 使用 error 可讓 API 拒絕承載中的任何額外參數。 只能指出此 API 中指定的參數，或傳回 400 錯誤。 |
|
| azureml-model-deployment | 字串 | 您想要將要求路由傳送至其中的部署名稱。 對支援多個部署的端點的支援。 |
要求本文
| 名稱 | 必要 | 類型 | 描述 |
|---|---|---|---|
| input | True | EmbeddingInput[] | 輸入要內嵌的影像。 若要在單一要求中內嵌多個輸入，請傳遞陣列。 輸入不得超過模型的最大輸入權杖。 |
| 尺寸 | 整數 | 產生的輸出內嵌應具有的維度數目。 傳遞 null 會導致模型使用其預設值。 如果模型不支援值或參數，則傳回 422 錯誤。 | |
| encoding_format | EmbeddingEncodingFormat | 用以傳回內嵌的格式。 為 base64、float、int8、uint8、binary、ubinary 其中之一。 如果模型不支援值或參數，則傳回 422 錯誤。 |
回覆
| 名稱 | 類型 | 描述 |
|---|---|---|
| 200 OK | CreateEmbeddingResponse | 確定 |
| 401 未經授權 | UnauthorizedError | 存取權杖遺漏或不正確 標頭 x-ms-error-code：字串 |
| 404 找不到 | NotFoundError | 模型不支援模態。 請查閱模型的文件，以查看有哪些路由可供使用。 標頭 x-ms-error-code：字串 |
| 422 無法處理的實體 | UnprocessableContentError | 要求包含無法處理的內容。 根據此規格指出的承載有效時，會傳回錯誤。 不過，基礎模型不支援承載中所指示的一些指示。 使用 details 區段來了解違規的參數。標頭 x-ms-error-code：字串 |
| 429 要求太多 | TooManyRequestsError | 您已達到指派的速率限制，而且您的要求必須調整步調。 標頭 x-ms-error-code：字串 |
| 其他狀態碼 | ContentFilterError | 錯誤要求 標頭 x-ms-error-code：字串 |
安全性
授權
具有 Bearer: 前置詞的權杖，例如 Bearer abcde12345
類型：apiKey
In：標頭
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 | 物件類型，一律為「內嵌」。 |
| EmbeddingInput | 表示具有選擇性文字的影像。 |
| ListObject | 物件類型，一律為「清單」。 |
| NotFoundError | |
| TooManyRequestsError | |
| UnauthorizedError | |
| UnprocessableContentError | 要求包含無法處理的內容。 根據此規格指出的承載有效時，會傳回錯誤。 不過，基礎模型不支援承載中所指示的一些指示。 使用 details 區段來了解違規的參數。 |
| 使用方式 | 要求的使用方式資訊。 |
ContentFilterError
當提示如設定觸發內容篩選時，API 呼叫會失敗。 修改提示，然後再試一次。
| 名稱 | 類型 | 描述 |
|---|---|---|
| code | 字串 | 錯誤碼。 |
| error | 字串 | 錯誤描述。 |
| message | 字串 | 錯誤訊息。 |
| param | 字串 | 觸發內容篩選的參數。 |
| status | 整數 | HTTP 狀態碼。 |
CreateEmbeddingResponse
| 名稱 | 類型 | 描述 |
|---|---|---|
| data | Embedding[] | 模型所產生的內嵌清單。 |
| 機型 | 字串 | 用來產生內嵌的模型名稱。 |
| object | ListObject | 物件類型，一律為「清單」。 |
| 用法 | 使用方式 | 要求的使用方式資訊。 |
CreateImageEmbeddingRequest
| 名稱 | 類型 | 預設值 | 說明 |
|---|---|---|---|
| 尺寸 | 整數 | 產生的輸出內嵌應具有的維度數目。 傳遞 null 會導致模型使用其預設值。 如果模型不支援值或參數，則傳回 422 錯誤。 | |
| encoding_format | EmbeddingEncodingFormat | float | 用以傳回內嵌的格式。 為 base64、float、int8、uint8、binary、ubinary 其中之一。 如果模型不支援值或參數，則傳回 422 錯誤。 |
| input | EmbeddingInput[] | 輸入要內嵌的影像。 若要在單一要求中內嵌多個輸入，請傳遞陣列。 輸入不得超過模型的最大輸入權杖。 |
詳細資料
| 名稱 | 類型 | 描述 |
|---|---|---|
| loc | string[] | 造成問題的參數 |
| value | 字串 | 傳遞至參數的值造成問題。 |
內嵌
表示產生的影像。
| 名稱 | 類型 | 描述 |
|---|---|---|
| 內嵌 | number[] | 內嵌向量，這是浮點數清單。 向量長度取決於所使用的模型。 |
| index | 整數 | 內嵌清單中的內嵌索引。 |
| object | EmbeddingObject | 物件類型，一律為「內嵌」。 |
EmbeddingEncodingFormat
用以傳回內嵌的格式。 為 base64、float、int8、uint8、binary、ubinary 其中之一。 如果模型不支援值或參數，則傳回 422 錯誤。
| 名稱 | 類型 | 描述 |
|---|---|---|
| base64 | 字串 | |
| binary | 字串 | |
| float | 字串 | |
| int8 | 字串 | |
| ubinary | 字串 | |
| uint8 | 字串 |
EmbeddingObject
物件類型，一律為「內嵌」。
| 名稱 | 類型 | 描述 |
|---|---|---|
| 內嵌 | 字串 |
EmbeddingInput
表示具有選擇性文字的影像。
| 名稱 | 類型 | 描述 |
|---|---|---|
| image | 字串 | 以 base64 字串編碼為資料 URL 的輸入影像。 範例：data:image/{format};base64,{data}。 |
| text | 字串 | 選擇性。 要饋送至模型的文字輸入 (例如 DINO、CLIP)。 如果模型不支援值或參數，則傳回 422 錯誤。 |
ListObject
物件類型，一律為「清單」。
| 名稱 | 類型 | 描述 |
|---|---|---|
| list | 字串 |
NotFoundError
| 名稱 | 類型 | 描述 |
|---|---|---|
| error | 字串 | 錯誤描述。 |
| message | 字串 | 錯誤訊息。 |
| status | 整數 | HTTP 狀態碼。 |
TooManyRequestsError
| 名稱 | 類型 | 描述 |
|---|---|---|
| error | 字串 | 錯誤描述。 |
| message | 字串 | 錯誤訊息。 |
| status | 整數 | HTTP 狀態碼。 |
UnauthorizedError
| 名稱 | 類型 | 描述 |
|---|---|---|
| error | 字串 | 錯誤描述。 |
| message | 字串 | 錯誤訊息。 |
| status | 整數 | HTTP 狀態碼。 |
UnprocessableContentError
要求包含無法處理的內容。 根據此規格指出的承載有效時，會傳回錯誤。 不過，基礎模型不支援承載中所指示的一些指示。 使用 details 區段來了解違規的參數。
| 名稱 | 類型 | 描述 |
|---|---|---|
| code | 字串 | 錯誤碼。 |
| detail | 詳細資料 | |
| error | 字串 | 錯誤描述。 |
| message | 字串 | 錯誤訊息。 |
| status | 整數 | HTTP 狀態碼。 |
使用方式
要求的使用方式資訊。
| 名稱 | 類型 | 描述 |
|---|---|---|
| prompt_patches | 整數 | 影像提示字元所使用的影像修補檔數目。 |
| prompt_tokens | 整數 | 提示所使用的權杖數目。 |
| total_patches | 整數 | 要求所使用的修補檔總數。 |
| total_tokens | 整數 | 要求所使用的權杖總數。 |