Referência: Inserções | IA do Azure Foundry

Importante

Os itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. 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 inserção que representa o texto de entrada.

POST /embeddings?api-version=2024-05-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 drop 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
modelo		string	O nome do modelo. Esse parâmetro será ignorado se o ponto de extremidade atender apenas a um modelo.
input	Verdadeiro	string[]	Texto de entrada para inserir, codificado como uma cadeia de caracteres ou matriz de tokens. Para inserir várias entradas em uma única solicitação, passe uma matriz de cadeias de caracteres ou matriz de matrizes de token.
dimensões		Número inteiro	O número de dimensões que as inserções de saída resultantes devem ter. Retornará um erro 422 se o modelo não der suporte ao valor ou ao parâmetro.
encoding_format		EmbeddingEncodingFormat	O formato no qual as inserções devem ser retornadas. Base64, float, int8, uint8, binário ou ubinary. Retornará um erro 422 se o modelo não der suporte ao valor ou ao parâmetro.
input_type		EmbeddingInputType	O tipo da entrada. text, query ou document. Retornará um erro 422 se o modelo não der suporte ao valor ou ao 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 contém conteúdo não processável 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 Bearer: prefix; por exemplo, Bearer abcde12345

Tipo: apiKey In: cabeçalho

Token do AAD

Autenticação OAuth2 do Azure Active Directory

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

Exemplos

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

Solicitação de Exemplo

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

{
  "input": [
    "This is a very good text"
  ],
  "input_type": "text",
  "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": "BERT",
  "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.
CreateEmbeddingRequest	Solicitação para criar inserções.
CreateEmbeddingResponse	Resposta de uma solicitação de inserções.
Detalhe	Detalhes dos erros.
Inserção	Representa o objeto de inserção gerado.
EmbeddingEncodingFormat	O formato no qual as inserções devem ser retornadas. Base64, float, int8, uint8, binário ou ubinary. Retornará um erro 422 se o modelo não der suporte ao valor ou ao parâmetro.
EmbeddingInputType	O tipo da entrada. text, query ou document. Retornará um erro 422 se o modelo não der suporte ao valor ou ao parâmetro.
EmbeddingObject	O tipo de objeto, que é sempre de “inserção”.
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 não existe ou é inválida.
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.

CreateEmbeddingRequest

Solicitação para criar inserções.

Nome	Obrigatória	Type	Descrição
input	Verdadeiro	string[]	Texto de entrada para inserir, codificado como uma cadeia de caracteres ou matriz de tokens. Para inserir várias entradas em uma única solicitação, passe uma matriz de cadeias de caracteres ou matriz de matrizes de token.
dimensões		Número inteiro	O número de dimensões que as inserções de saída resultantes devem ter. Retornará um erro 422 se o modelo não der suporte ao valor ou ao parâmetro.
encoding_format		EmbeddingEncodingFormat	O formato no qual as inserções devem ser retornadas. Base64, float, int8, uint8, binário ou ubinary. Retornará um erro 422 se o modelo não der suporte ao valor ou ao parâmetro.
input_type		EmbeddingInputType	O tipo da entrada. text, query ou document. Retornará um erro 422 se o modelo não der suporte ao valor ou ao parâmetro.

CreateEmbeddingResponse

Resposta de uma solicitação de inserções.

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.

Detalhe

Detalhes do erro UnprocessableContentError.

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

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

EmbeddingInputType

O tipo da entrada. text, query ou document. Retornará um erro 422 se o modelo não der suporte ao valor ou ao parâmetro.

Nome	Tipo	Descrição
documento	string	Indica que a entrada representa um documento armazenado em um banco de dados vetorial.
consulta	string	Indica que a entrada representa uma consulta de pesquisa para localizar os documentos mais relevantes em seu banco de dados vetorial.
text	string	Indica que a entrada é uma entrada de texto geral.

EmbeddingObject

Nome	Tipo	Descrição
inserção	string

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