參考：內嵌 |Azure AI Foundry

發行項
09/03/2024

重要

本文中標示為 (預覽) 的項目目前處於公開預覽狀態。此預覽版本沒有服務等級協定，不建議將其用於生產工作負載。可能不支援特定功能，或可能已經限制功能。如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

建立代表輸入文字的內嵌向量。

POST /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	string[]	要內嵌的輸入文字，編碼為權杖字串或陣列。若要在單一要求中內嵌多個輸入，請傳遞字串陣列或權杖陣列的陣列。
尺寸		整數	產生的輸出內嵌應具有的維度數目。如果模型不支援值或參數，則傳回 422 錯誤。
encoding_format		EmbeddingEncodingFormat	用以傳回內嵌的格式。為 base64、float、int8、uint8、binary、ubinary 其中之一。如果模型不支援值或參數，則傳回 422 錯誤。
input_type		EmbeddingInputType	輸入的「類型」。 `text`、`query` 或 `document`。如果模型不支援值或參數，則傳回 422 錯誤。

回覆

名稱	類型	描述
200 OK	CreateEmbeddingResponse	確定
401 未經授權	UnauthorizedError	存取權杖遺漏或不正確標頭 x-ms-error-code：字串
404 找不到	NotFoundError	模型不支援模態。請查閱模型的文件，以查看有哪些路由可供使用。標頭 x-ms-error-code：字串
422 無法處理的實體	UnprocessableContentError	要求包含無法處理的內容標頭 x-ms-error-code：字串
429 要求太多	TooManyRequestsError	您已達到指派的速率限制，而且您的要求必須調整步調。標頭 x-ms-error-code：字串
其他狀態碼	ContentFilterError	錯誤要求標頭 x-ms-error-code：字串

安全性

授權

具有 Bearer: prefix 的權杖，例如 Bearer abcde12345

類型：apiKey 位於：標頭

AADToken

Azure Active Directory OAuth2 驗證

類型：oauth2 流程：應用程式 權杖 URL：https://login.microsoftonline.com/common/oauth2/v2.0/token

範例

建立代表輸入文字的內嵌向量

範例要求

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

{
  "input": [
    "This is a very good text"
  ],
  "input_type": "text",
  "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": "BERT",
  "usage": {
    "prompt_tokens": 15,
    "total_tokens": 15
  }
}

定義

名稱	描述
ContentFilterError	當提示如設定觸發內容篩選時，API 呼叫會失敗。修改提示，然後再試一次。
CreateEmbeddingRequest	建立內嵌的要求。
CreateEmbeddingResponse	來自內嵌要求的回應。
詳細資料	錯誤的詳細資料。
內嵌	表示產生的內嵌物件。
EmbeddingEncodingFormat	用以傳回內嵌的格式。為 base64、float、int8、uint8、binary、ubinary 其中之一。如果模型不支援值或參數，則傳回 422 錯誤。
EmbeddingInputType	輸入的「類型」。 `text`、`query` 或 `document`。如果模型不支援值或參數，則傳回 422 錯誤。
EmbeddingObject	物件類型，一律為「內嵌」。
ListObject	物件類型，一律為「清單」。
NotFoundError	路由對已部署的模型無效。
TooManyRequestsError	您已達到指派的速率限制，而且您的要求必須調整步調。
UnauthorizedError	驗證遺漏或不正確。
UnprocessableContentError	要求包含無法處理的內容。根據此規格指出的承載有效時，會傳回錯誤。不過，基礎模型不支援承載中所指示的一些指示。使用 `details` 區段來了解違規的參數。
使用方式	要求的使用方式資訊。

ContentFilterError

當提示如設定觸發內容篩選時，API 呼叫會失敗。修改提示，然後再試一次。

名稱	類型	描述
code	字串	錯誤碼。
error	字串	錯誤描述。
message	字串	錯誤訊息。
param	字串	觸發內容篩選的參數。
status	整數	HTTP 狀態碼。

CreateEmbeddingRequest

建立內嵌的要求。

名稱	必要	類型	描述
input	True	string[]	要內嵌的輸入文字，編碼為權杖字串或陣列。若要在單一要求中內嵌多個輸入，請傳遞字串陣列或權杖陣列的陣列。
尺寸		整數	產生的輸出內嵌應具有的維度數目。如果模型不支援值或參數，則傳回 422 錯誤。
encoding_format		EmbeddingEncodingFormat	用以傳回內嵌的格式。為 base64、float、int8、uint8、binary、ubinary 其中之一。如果模型不支援值或參數，則傳回 422 錯誤。
input_type		EmbeddingInputType	輸入的「類型」。 `text`、`query` 或 `document`。如果模型不支援值或參數，則傳回 422 錯誤。

CreateEmbeddingResponse

來自內嵌要求的回應。

名稱	類型	描述
data	Embedding[]	模型所產生的內嵌清單。
機型	字串	用來產生內嵌的模型名稱。
object	ListObject	物件類型，一律為「清單」。
用法	使用方式	要求的使用方式資訊。

詳細資料

UnprocessableContentError (部分機器翻譯) 錯誤的詳細資料。

名稱	類型	描述
loc	string[]	造成問題的參數
value	字串	傳遞至參數的值造成問題。

內嵌

表示產生的內嵌。

名稱	類型	描述
內嵌	[]	內嵌向量。向量長度取決於所使用的模型，而類型則取決於所使用的 `encoding_format`。
index	整數	內嵌清單中的內嵌索引。
object	EmbeddingObject	物件類型，一律為「內嵌」。

EmbeddingEncodingFormat

用以傳回內嵌的格式。為 base64、float、int8、uint8、binary、ubinary 其中之一。如果模型不支援值或參數，則傳回 422 錯誤。

名稱	類型	描述
base64	字串
binary	字串
float	字串
int8	字串
ubinary	字串
uint8	字串

EmbeddingInputType

輸入的「類型」。 text、query 或 document。如果模型不支援值或參數，則傳回 422 錯誤。

名稱	類型	描述
文件	字串	表示輸入代表儲存在向量資料庫中的文件。
query	字串	表示輸入代表搜尋查詢，以在向量資料庫中尋找最相關的文件。
text	字串	表示輸入是一般文字輸入。

EmbeddingObject

名稱	類型	描述
內嵌	字串

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_tokens	整數	提示所使用的權杖數目。
total_tokens	整數	要求所使用的權杖總數。

共用方式為