Referência: Image Embeddings | Azure AI Foundry
Importante
Os itens marcados (visualização) neste artigo estão atualmente em visualização pública. Essa visualização é fornecida sem um contrato de nível de serviço e não a recomendamos para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.
Cria um vetor de incorporação que representa a imagem de entrada e o par de texto.
POST /images/embeddings?api-version=2024-04-01-preview
Parâmetros do URI
| Nome | Em | Necessário | Type | Description |
|---|---|---|---|---|
| api-version | query | True | string | A versão da API no formato "AAAA-MM-DD" ou "AAAA-MM-DD-visualização". |
Cabeçalho do Pedido
| Nome | Obrigatório | Type | Description |
|---|---|---|---|
| extra-parâmetros | string | O comportamento da API quando parâmetros extras são indicados na carga útil. O uso pass-through faz com que a API passe o parâmetro para o modelo subjacente. Use esse valor quando quiser passar parâmetros que você sabe que o modelo subjacente pode suportar. O uso ignore faz com que a API elimine qualquer parâmetro não suportado. Use esse valor quando precisar usar a mesma carga em modelos diferentes, mas um dos parâmetros extras pode fazer com que um modelo cometa erro se não for suportado. O uso error faz com que a API rejeite qualquer parâmetro extra na carga útil. Somente os parâmetros especificados nesta API podem ser indicados, ou um erro 400 é retornado. |
|
| azureml-model-deployment | string | Nome da implantação para a qual você deseja rotear a solicitação. Suporte para endpoints que suportam várias implantações. |
Corpo do Pedido
| Nome | Obrigatório | Type | Description |
|---|---|---|---|
| input | True | EmbeddingInput[] | Imagem de entrada para incorporar. Para incorporar várias entradas em uma única solicitação, passe uma matriz. A entrada não deve exceder os tokens de entrada máximos para o modelo. |
| dimensões | integer | O número de dimensões que as incorporações de saída resultantes devem ter. Passar null faz com que o modelo use seu valor padrão. Retorna um erro 422 se o modelo não suportar o valor ou parâmetro. | |
| encoding_format | EmbeddingEncodingFormat | O formato para retornar as incorporações. Base64, float, int8, uint8, binário ou ubinário. Retorna um erro 422 se o modelo não suportar o valor ou parâmetro. |
Respostas
| Nome | Tipo | Description |
|---|---|---|
| 200 OK | CreateEmbeddingResponse | OK |
| 401 Não Autorizado | UnauthorizedError | O token de acesso está ausente ou é inválido Cabeçalhos x-ms-error-code: cadeia de caracteres |
| 404 Não Encontrado | NotFoundError | Modalidade não suportada pelo modelo. Verifique a documentação do modelo para ver quais rotas estão disponíveis. Cabeçalhos x-ms-error-code: cadeia de caracteres |
| 422 Entidade não processável | UnprocessableContentError | A solicitação contém conteúdo não processável. O erro é devolvido quando a carga útil indicada é válida de acordo com esta especificação. No entanto, algumas das instruções indicadas na carga útil não são suportadas pelo modelo subjacente. Use a details seção para entender o parâmetro ofensivo.Cabeçalhos x-ms-error-code: cadeia de caracteres |
| Demasiados Pedidos 429 | TooManyRequestsError | Você atingiu o limite de taxa atribuído e sua solicitação precisa ser cadenciada. Cabeçalhos x-ms-error-code: cadeia de caracteres |
| Outros códigos de status | ContentFilterError | Solicitação inválida Cabeçalhos x-ms-error-code: cadeia de caracteres |
Segurança
Autorização
O token com o prefixo Bearer: , por exemplo, Bearer abcde12345
Tipo: apiKey
Em: cabeçalho
AADToken
Autenticação OAuth2 do Azure Ative Directory
Tipo: oauth2
Fluxo: aplicação
URL do token: https://login.microsoftonline.com/common/oauth2/v2.0/token
Exemplos
Cria um vetor de incorporação que representa o texto e a imagem de entrada
Pedido de Amostra
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
}
Pedido de Resposta
Código de status: 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
}
}
Definições
| Nome | Descrição |
|---|---|
| ContentFilterError | A chamada de API falha quando o prompt aciona um filtro de conteúdo conforme configurado. Modifique o prompt e tente novamente. |
| CreateEmbeddingResponse | |
| CreateImageEmbeddingRequest | |
| Detalhe | |
| Incorporar | Representa uma imagem gerada. |
| EmbeddingEncodingFormat | O formato para retornar as incorporações. Base64, float, int8, uint8, binário ou ubinário. Retorna um erro 422 se o modelo não suportar o valor ou parâmetro. |
| EmbeddingObject | O tipo de objeto, que está sempre "incorporando". |
| EmbeddingInput | Representa uma imagem com texto opcional. |
| ListObject | O tipo de objeto, que é sempre "lista". |
| NotFoundError | |
| TooManyRequestsError | |
| UnauthorizedError | |
| UnprocessableContentError | A solicitação contém conteúdo não processável. O erro é devolvido quando a carga útil indicada é válida de acordo com esta especificação. No entanto, algumas das instruções indicadas na carga útil não são suportadas pelo modelo subjacente. Use a details seção para entender o parâmetro ofensivo. |
| Utilização | As informações de uso da solicitação. |
ContentFilterError
A chamada de API falha quando o prompt aciona um filtro de conteúdo conforme configurado. Modifique o prompt e tente novamente.
| Nome | Tipo | Description |
|---|---|---|
| code | string | O código de erro. |
| error | string | A descrição do erro. |
| mensagem | string | A mensagem de erro. |
| param | string | O parâmetro que acionou o filtro de conteúdo. |
| status | integer | O código de status HTTP. |
CreateEmbeddingResponse
| Nome | Tipo | Description |
|---|---|---|
| dados | Incorporação[] | A lista de incorporações geradas pelo modelo. |
| modelo | string | O nome do modelo usado para gerar a incorporação. |
| objeto | ListObject | O tipo de objeto, que é sempre "lista". |
| ativa | Utilização | As informações de uso da solicitação. |
CreateImageEmbeddingRequest
| Nome | Type | Valor Predefinido | Description |
|---|---|---|---|
| dimensões | integer | O número de dimensões que as incorporações de saída resultantes devem ter. Passar null faz com que o modelo use seu valor padrão. Retorna um erro 422 se o modelo não suportar o valor ou parâmetro. | |
| encoding_format | EmbeddingEncodingFormat | flutuante | O formato para retornar as incorporações. Base64, float, int8, uint8, binário ou ubinário. Retorna um erro 422 se o modelo não suportar o valor ou parâmetro. |
| input | EmbeddingInput[] | Imagem de entrada para incorporar. Para incorporar várias entradas em uma única solicitação, passe uma matriz. A entrada não deve exceder os tokens de entrada máximos para o modelo. |
Detalhe
| Nome | Tipo | Description |
|---|---|---|
| loc | string[] | O parâmetro que causa o problema |
| valor | string | O valor passado para o parâmetro causando problemas. |
Incorporar
Representa uma imagem gerada.
| Nome | Tipo | Description |
|---|---|---|
| incorporação | número[] | O vetor de incorporação, que é uma lista de flutuadores. O comprimento do vetor depende do modelo utilizado. |
| index | integer | O índice da incorporação na lista de incorporações. |
| objeto | EmbeddingObject | O tipo de objeto, que está sempre "incorporando". |
EmbeddingEncodingFormat
O formato para retornar as incorporações. Base64, float, int8, uint8, binário ou ubinário. Retorna um erro 422 se o modelo não suportar o valor ou parâmetro.
| Nome | Tipo | Description |
|---|---|---|
| base64 | string | |
| binário | string | |
| flutuante | string | |
| int8 | string | |
| Ubinário | string | |
| UINT8 | string |
EmbeddingObject
O tipo de objeto, que está sempre "incorporando".
| Nome | Tipo | Description |
|---|---|---|
| incorporação | string |
EmbeddingInput
Representa uma imagem com texto opcional.
| Nome | Tipo | Descrição |
|---|---|---|
| image | string | A imagem de entrada codificada em base64 string como uma URL de dados. Exemplo: data:image/{format};base64,{data}. |
| texto | string | Opcional. A entrada de texto para alimentar o modelo (como DINO, CLIP). Retorna um erro 422 se o modelo não suportar o valor ou parâmetro. |
ListObject
O tipo de objeto, que é sempre "lista".
| Nome | Tipo | Description |
|---|---|---|
| list | string |
NotFoundError
| Nome | Tipo | Description |
|---|---|---|
| error | string | A descrição do erro. |
| mensagem | string | A mensagem de erro. |
| status | integer | O código de status HTTP. |
TooManyRequestsError
| Nome | Tipo | Description |
|---|---|---|
| error | string | A descrição do erro. |
| mensagem | string | A mensagem de erro. |
| status | integer | O código de status HTTP. |
UnauthorizedError
| Nome | Tipo | Description |
|---|---|---|
| error | string | A descrição do erro. |
| mensagem | string | A mensagem de erro. |
| status | integer | O código de status HTTP. |
UnprocessableContentError
A solicitação contém conteúdo não processável. O erro é devolvido quando a carga útil indicada é válida de acordo com esta especificação. No entanto, algumas das instruções indicadas na carga útil não são suportadas pelo modelo subjacente. Use a details seção para entender o parâmetro ofensivo.
| Nome | Tipo | Description |
|---|---|---|
| code | string | O código de erro. |
| detalhe | Detalhe | |
| error | string | A descrição do erro. |
| mensagem | string | A mensagem de erro. |
| status | integer | O código de status HTTP. |
Utilização
As informações de uso da solicitação.
| Nome | Tipo | Description |
|---|---|---|
| prompt_patches | integer | O número de patches de imagem usados pelo prompt de imagem. |
| prompt_tokens | integer | O número de tokens usados pelo prompt. |
| total_patches | integer | O número total de patches usados pela solicitação. |
| total_tokens | integer | O número total de tokens usados pela solicitação. |