Referência: Incorporações de Imagem | Estúdio de IA do Azure

Artigo
09/03/2024

Importante

Alguns dos recursos descritos nesse artigo podem estar disponíveis apenas na versão prévia. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Cria um vetor de incorporação que representa o par de imagem e texto inserido.

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

Parâmetros de URI

Nome	Em	Obrigatório	Type	Descrição
api-version	Consulta	True	string	A versão da API no formato "YYYY-MM-DD" ou "YYYYY-MM-DD-preview".

Cabeçalho da solicitação

Nome	Obrigatória	Type	Descrição
parâmetros extras		string	O comportamento da API quando os parâmetros extras são indicados no conteúdo. Usar `pass-through` faz com que a API passe o parâmetro para o modelo subjacente. Use esse valor quando quiser passar os parâmetros que você sabe que o modelo subjacente pode dar suporte. Usar `ignore` faz com que a API remova qualquer parâmetro sem suporte. Use esse valor quando precisar usar a mesma carga útil nos modelos diferentes, mas um dos parâmetros extras pode fazer com que um modelo apresente erro se não for compatível. Usar `error` faz com que a API rejeite qualquer parâmetro extra no conteúdo. Somente os parâmetros especificados nessa API podem ser indicados, caso contrário, será retornado um erro 400.
azureml-model-deployment		string	Nome da implantação para a qual você deseja rotear a solicitação. Compatível com pontos de extremidade que dão suporte a várias implantações.

Corpo da solicitação

Nome	Obrigatória	Type	Descrição
input	Verdadeiro	EmbeddingInput[]	Imagem da inserção a ser incorporada. Para incorporar várias inserções em uma única solicitação, repasse uma matriz. A inserção não deve exceder o máximo de tokens de entrada para o modelo.
dimensões		Número inteiro	O número de dimensões que as inserções de saída resultantes devem ter. Repassar um valor nulo fará com que o modelo use seu valor padrão. Isso retornará um erro 422 se o modelo não for compatível com o valor ou parâmetro.
encoding_format		EmbeddingEncodingFormat	O formato no qual as inserções devem ser retornadas. Base64, float, int8, uint8, binário ou ubinary. Isso retornará um erro 422 se o modelo não for compatível com o valor ou parâmetro.

Respostas

Nome	Tipo	Descrição
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 compatível com o 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 inclui conteúdo não processável O erro é retornado quando o conteúdo indicado é válido de acordo com essa especificação. No entanto, algumas das instruções indicadas no conteúdo não são compatíveis com o modelo subjacente. Use a seção `details` para entender o parâmetro ofensivo. Cabeçalhos x-ms-error-code: cadeia de caracteres
429 Excesso de Solicitações	TooManyRequestsError	Você atingiu o limite de taxa que lhe foi atribuído e sua solicitação vai precisar aguardar. Cabeçalhos x-ms-error-code: cadeia de caracteres
Outros códigos de status	ContentFilterError	Solicitação incorreta Cabeçalhos x-ms-error-code: cadeia de caracteres

Segurança

Autorização

O token com o prefixo Bearer:, por exemplo, Bearer abcde12345

Digite: apiKey
Em: cabeçalho

Token do AAD

Autenticação OAuth2 do Azure Active Directory

Digite: oauth2
Fluxo: aplicativo
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 da inserção

Solicitação de Exemplo

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
}

Resposta de exemplo

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 à API falha quando o prompt dispara um filtro de conteúdo conforme configurado. Modifique o prompt e tente novamente.
CreateEmbeddingResponse
CreateImageEmbeddingRequest
Detalhe
Inserção	Representa uma imagem gerada.
EmbeddingEncodingFormat	O formato no qual as inserções devem ser retornadas. Base64, float, int8, uint8, binário ou ubinary. Isso retornará um erro 422 se o modelo não for compatível com o valor ou parâmetro.
EmbeddingObject	O tipo de objeto, que é sempre de “inserção”.
EmbeddingInput	Representa uma imagem com texto opcional.
ListObject	O tipo de objeto, que é sempre "lista".
NotFoundError
TooManyRequestsError
UnauthorizedError
UnprocessableContentError	A solicitação inclui conteúdo não processável O erro é retornado quando o conteúdo indicado é válido de acordo com essa especificação. No entanto, algumas das instruções indicadas no conteúdo não são compatíveis com o modelo subjacente. Use a seção `details` para entender o parâmetro ofensivo.
Uso	As informações de uso da solicitação.

ContentFilterError

A chamada à API falha quando o prompt dispara um filtro de conteúdo conforme configurado. Modifique o prompt e tente novamente.

Nome	Tipo	Descrição
code	string	O código de erro.
error	string	A descrição do erro.
message	string	A mensagem de erro.
param	string	O parâmetro que disparou o filtro de conteúdo.
status	Número inteiro	O código de status HTTP.

CreateEmbeddingResponse

Nome	Tipo	Descrição
data	Embedding[]	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".
uso	Uso	As informações de uso da solicitação.

CreateImageEmbeddingRequest

Nome	Type	Valor padrão	Descrição
dimensões	Número inteiro		O número de dimensões que as inserções de saída resultantes devem ter. Repassar um valor nulo fará com que o modelo use seu valor padrão. Isso retornará um erro 422 se o modelo não for compatível com o valor ou parâmetro.
encoding_format	EmbeddingEncodingFormat	float	O formato no qual as inserções devem ser retornadas. Base64, float, int8, uint8, binário ou ubinary. Isso retornará um erro 422 se o modelo não for compatível com o valor ou parâmetro.
input	EmbeddingInput[]		Imagem da inserção a ser incorporada. Para incorporar várias inserções em uma única solicitação, repasse uma matriz. A inserção não deve exceder o máximo de tokens de entrada para o modelo.

Detalhe

Nome	Tipo	Descrição
loc	string[]	O parâmetro que está causando o problema
value	string	O valor repassado para o parâmetro que está causando problemas.

Inserção

Representa uma imagem gerada.

Nome	Tipo	Descrição
inserção	number[]	O vetor de inserção, que é uma lista de floats. O comprimento do vetor depende do modelo usado.
índice	Número inteiro	O índice da incorporação na lista de incorporações.
objeto	EmbeddingObject	O tipo de objeto, que é sempre de “inserção”.

EmbeddingEncodingFormat

O formato no qual as inserções devem ser retornadas. Base64, float, int8, uint8, binário ou ubinary. Isso retornará um erro 422 se o modelo não for compatível com o valor ou parâmetro.

Nome	Tipo	Descrição
base64	string
binary	string
float	string
int8	string
ubinary	string
uint8	string

EmbeddingObject

O tipo de objeto, que é sempre de “inserção”.

Nome	Tipo	Descrição
inserção	string

EmbeddingInput

Representa uma imagem com texto opcional.

Nome	Tipo	Descrição
imagem	string	A imagem de entrada codificada na cadeia de caracteres `base64` como uma URL de dados. Exemplo: `data:image/{format};base64,{data}`.
text	string	Opcional. A inserção de texto para alimentar o modelo (como DINO, CLIP). Isso retornará um erro 422 se o modelo não for compatível com o valor ou parâmetro.

ListObject

O tipo de objeto, que é sempre "lista".

Nome	Tipo	Description
lista	string

NotFoundError

Nome	Tipo	Descrição
error	string	A descrição do erro.
message	string	A mensagem de erro.
status	Número inteiro	O código de status HTTP.

TooManyRequestsError

Nome	Tipo	Descrição
error	string	A descrição do erro.
message	string	A mensagem de erro.
status	Número inteiro	O código de status HTTP.

UnauthorizedError

Nome	Tipo	Descrição
error	string	A descrição do erro.
message	string	A mensagem de erro.
status	Número inteiro	O código de status HTTP.

UnprocessableContentError

A solicitação inclui conteúdo não processável O erro é retornado quando o conteúdo indicado é válido de acordo com essa especificação. No entanto, algumas das instruções indicadas no conteúdo não são compatíveis com o modelo subjacente. Use a seção details para entender o parâmetro ofensivo.

Nome	Tipo	Descrição
code	string	O código de erro.
detalhes	Detalhe
error	string	A descrição do erro.
message	string	A mensagem de erro.
status	Número inteiro	O código de status HTTP.

Uso

As informações de uso da solicitação.

Nome	Tipo	Descrição
prompt_patches	Número inteiro	O número de patches de imagem usados pelo prompt de imagem.
prompt_tokens	Número inteiro	O número de tokens usados pelo prompt.
total_patches	Número inteiro	O número total de patches usados pela solicitação.
total_tokens	Número inteiro	O número total de tokens usados pela solicitação.

Compartilhar via