Referência: Embeddings | Azure AI Foundry

Artigo
09/02/2024

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 o texto de entrada.

POST /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
modelo		string	O nome do modelo. Este parâmetro será ignorado se o ponto de extremidade servir apenas um modelo.
input	True	string[]	Insira texto para incorporar, codificado como uma cadeia de caracteres ou matriz de tokens. Para incorporar várias entradas em uma única solicitação, passe uma matriz de cadeias de caracteres ou matriz de matrizes de token.
dimensões		integer	O número de dimensões que as incorporações de saída resultantes devem ter. 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.
input_type		EmbeddingInputType	O tipo de entrada. Ou `text`, `query`ou `document`. 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 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 Bearer: prefix, por exemplo, Bearer abcde12345

Tipo: apiKey In: header

AADToken

Autenticação OAuth2 do Azure Ative Directory

Tipo: oauth2 Fluxo: URL do token do aplicativo:https://login.microsoftonline.com/common/oauth2/v2.0/token

Exemplos

Cria um vetor de incorporação que representa o texto de entrada

Pedido de Amostra

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

{
  "input": [
    "This is a very good text"
  ],
  "input_type": "text",
  "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": "BERT",
  "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.
CreateEmbeddingRequest	Pedido de criação de incorporações.
CreateEmbeddingResponse	Resposta de um pedido de incorporação.
Detalhe	Detalhes dos erros.
Incorporar	Representa o objeto de incorporação gerado.
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.
EmbeddingInputType	O tipo de entrada. Ou `text`, `query`ou `document`. Retorna um erro 422 se o modelo não suportar o valor ou parâmetro.
EmbeddingObject	O tipo de objeto, que está sempre "incorporando".
ListObject	O tipo de objeto, que é sempre "lista".
NotFoundError	A rota não é válida para o modelo implantado.
TooManyRequestsError	Você atingiu o limite de taxa atribuído e suas solicitações precisam ser aceleradas.
UnauthorizedError	A autenticação está ausente ou é inválida.
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.

CreateEmbeddingRequest

Pedido de criação de incorporações.

Nome	Obrigatório	Type	Description
input	True	string[]	Insira texto para incorporar, codificado como uma cadeia de caracteres ou matriz de tokens. Para incorporar várias entradas em uma única solicitação, passe uma matriz de cadeias de caracteres ou matriz de matrizes de token.
dimensões		integer	O número de dimensões que as incorporações de saída resultantes devem ter. 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.
input_type		EmbeddingInputType	O tipo de entrada. Ou `text`, `query`ou `document`. Retorna um erro 422 se o modelo não suportar o valor ou parâmetro.

CreateEmbeddingResponse

Resposta de um pedido de incorporação.

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.

Detalhe

Detalhes para o erro UnprocessableContentError .

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 a incorporação gerada.

Nome	Tipo	Description
incorporação	[]	O vetor de incorporação. O comprimento do vetor depende do modelo usado e o tipo depende do `encoding_format` usado.
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

EmbeddingInputType

O tipo de entrada. Ou text, queryou document. Retorna um erro 422 se o modelo não suportar o valor ou parâmetro.

Nome	Tipo	Description
documento	string	Indica que a entrada representa um documento armazenado em um banco de dados vetorial.
query	string	Indica que a entrada representa uma consulta de pesquisa para encontrar os documentos mais relevantes em seu banco de dados vetorial.
texto	string	Indica que a entrada é uma entrada de texto geral.

EmbeddingObject

Nome	Tipo	Description
incorporação	string

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_tokens	integer	O número de tokens usados pelo prompt.
total_tokens	integer	O número total de tokens usados pela solicitação.

Partilhar via