Riferimento: Incorporamenti | Studio AI della piattaforma Azure

Articolo
09/03/2024

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente disponibili in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Crea un vettore di incorporamento che rappresenta il testo di input.

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

Parametri dell'URI

Nome	Tra	Richiesto	Type	Descrizione
`api-version`	query	Vero	string	Versione dell'API nel formato "AAAA-MM-GG" o "AAAA-MM-GG-preview".

Intestazione richiesta

Nome	Obbligatorio	Type	Descrizione
parametri aggiuntivi		string	Il comportamento dell'API quando vengono indicati parametri extra nel payload. L'utilizzo di `pass-through` consente all'API di passare il parametro al modello sottostante. Usare questo valore quando si desidera passare i parametri che è noto che il modello sottostante possa supportare. L'utilizzo di `ignore` fa in modo che l'API elimini qualsiasi parametro non supportato. Usare questo valore quando è necessario usare lo stesso payload in modelli diversi, ma uno dei parametri extra può restituire un errore per un modello, se non supportato. L'utilizzo di `error` fa in modo che l'API rifiuti qualsiasi parametro extra nel payload. Possono essere indicati solo i parametri specificati in questa API. In caso contrario, verrà restituito un errore 400.
azureml-model-deployment		string	Nome della distribuzione a cui si desidera instradare la richiesta. Supportato per gli endpoint che supportano più distribuzioni.

Corpo della richiesta

Nome	Obbligatorio	Type	Descrizione
modello		string	Nome del modello. Questo parametro viene ignorato se l'endpoint viene usato per un solo modello.
input	Vero	string[]	Testo di input da incorporare, codificato come stringa o array di token. Per incorporare più input in una singola richiesta, passare un array di stringhe o una matrice di array di token.
dimensioni		integer	Numero di dimensioni che devono essere presenti negli incorporamenti di output risultanti. Restituisce un errore 422 se il modello non supporta il valore o il parametro.
encoding_format		EmbeddingEncodingFormat	Formato in cui restituire gli incorporamenti. Può essere base64, float, int8, uint8, binary o ubinary. Restituisce un errore 422 se il modello non supporta il valore o il parametro.
input_type		EmbeddingInputType	Il tipo dell'input. Deve essere `text`, `query` o `document`. Restituisce un errore 422 se il modello non supporta il valore o il parametro.

Risposte

Nome	Tipo	Descrizione
200 OK	CreateEmbeddingResponse	Ok
401 - Non autorizzato	UnauthorizedError	Token di accesso mancante o non valido Intestazioni x-ms-error-code: string
404 Not Found	NotFoundError	Modalità non supportata dal modello. Controllare la documentazione del modello per verificare quali route sono disponibili. Intestazioni x-ms-error-code: string
422 - Entità non elaborabile	UnprocessableContentError	La richiesta contiene contenuto non elaborabile Intestazioni x-ms-error-code: string
429 Troppe richieste	TooManyRequestsError	È stato raggiunto il limite di frequenza assegnato e la richiesta deve essere gestita. Intestazioni x-ms-error-code: string
Altri codici di stato	ContentFilterError	Richiesta non valida Intestazioni x-ms-error-code: string

Sicurezza

Autorizzazione

Token con Bearer: prefix, ad esempio Bearer abcde12345

Tipo: apiKey In: header

AADToken

Autenticazione OAuth2 di Azure Active Directory

Tipo: oauth2 Flusso: application URL token: https://login.microsoftonline.com/common/oauth2/v2.0/token

Esempi

Crea un vettore di incorporamento che rappresenta il testo di input

Richiesta di esempio

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

{
  "input": [
    "This is a very good text"
  ],
  "input_type": "text",
  "encoding_format": "float",
  "dimensions": 1024
}

Risposta di esempio

Codice di stato: 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
  }
}

Definizioni

Nome	Descrizione
ContentFilterError	La chiamata API ha esito negativo quando la richiesta attiva un filtro di contenuto come configurato. Modificare il prompt e riprovare.
CreateEmbeddingRequest	Richiesta di creazione di incorporamenti.
CreateEmbeddingResponse	Risposta da una richiesta di incorporamento.
Detail	Dettagli degli errori.
Incorporamento	Rappresenta l'oggetto di incorporamento generato.
EmbeddingEncodingFormat	Formato in cui restituire gli incorporamenti. Può essere base64, float, int8, uint8, binary o ubinary. Restituisce un errore 422 se il modello non supporta il valore o il parametro.
EmbeddingInputType	Il tipo dell'input. Deve essere `text`, `query` o `document`. Restituisce un errore 422 se il modello non supporta il valore o il parametro.
EmbeddingObject	Tipo di oggetto, che è sempre "embedding".
ListObject	Tipo di oggetto, che è sempre "list".
NotFoundError	Il percorso non è valido per il modello distribuito.
TooManyRequestsError	È stato raggiunto il limite di frequenza assegnato e le richieste devono essere gestite.
UnauthorizedError	Autenticazione mancante o non valida.
UnprocessableContentError	La richiesta presenta contenuti non elaborabili. L'errore viene restituito quando il payload indicato è valido in base a questa specifica. Tuttavia, alcune istruzioni indicate nel payload non sono supportate dal modello sottostante. Usare la sezione `details` per comprendere il parametro all'origine dell'errore.
Utilizzo	Informazioni sull'utilizzo relative alla richiesta.

ContentFilterError

La chiamata API ha esito negativo quando la richiesta attiva un filtro di contenuto come configurato. Modificare il prompt e riprovare.

Nome	Tipo	Descrizione
codice	string	Codice errore.
Errore	string	Descrizione dell'errore.
messaggio	string	Messaggio di errore.
param	string	Il parametro che ha attivato il filtro contenuto.
stato	integer	Codice di stato HTTP.

CreateEmbeddingRequest

Richiesta di creazione di incorporamenti.

Nome	Obbligatorio	Type	Descrizione
input	Vero	string[]	Testo di input da incorporare, codificato come stringa o array di token. Per incorporare più input in una singola richiesta, passare un array di stringhe o una matrice di array di token.
dimensioni		integer	Numero di dimensioni che devono essere presenti negli incorporamenti di output risultanti. Restituisce un errore 422 se il modello non supporta il valore o il parametro.
encoding_format		EmbeddingEncodingFormat	Formato in cui restituire gli incorporamenti. Può essere base64, float, int8, uint8, binary o ubinary. Restituisce un errore 422 se il modello non supporta il valore o il parametro.
input_type		EmbeddingInputType	Il tipo dell'input. Deve essere `text`, `query` o `document`. Restituisce un errore 422 se il modello non supporta il valore o il parametro.

CreateEmbeddingResponse

Risposta da una richiesta di incorporamento.

Nome	Tipo	Descrizione
data	Embedding[]	Elenco degli incorporamenti generati dal modello.
modello	string	Nome del modello usato per generare l'incorporamento.
oggetto	ListObject	Tipo di oggetto, che è sempre "list".
attivamente	Utilizzo	Informazioni sull'utilizzo relative alla richiesta.

Dettagli

Dettagli dell'errore UnprocessableContentError.

Nome	Tipo	Descrizione
loc	string[]	Parametro che causa il problema
value	string	Valore passato al parametro che causa problemi.

Incorporamento

Rappresenta l'oggetto di incorporamento generato.

Nome	Tipo	Descrizione
embedding	[]	Il vettore di incorporamento. La lunghezza del vettore dipende dal modello usato, mentre il tipo dipende dall'elemento `encoding_format` usato.
index	integer	Indice dell'incorporamento nell'elenco di incorporamenti.
oggetto	EmbeddingObject	Tipo di oggetto, che è sempre "embedding".

EmbeddingEncodingFormat

Formato in cui restituire gli incorporamenti. Può essere base64, float, int8, uint8, binary o ubinary. Restituisce un errore 422 se il modello non supporta il valore o il parametro.

Nome	Tipo	Descrizione
base64	string
binary	string
float	string
int8	string
ubinary	string
uint8	string

EmbeddingInputType

Il tipo dell'input. Deve essere text, query o document. Restituisce un errore 422 se il modello non supporta il valore o il parametro.

Nome	Tipo	Descrizione
document	string	Indica che l'input rappresenta un documento memorizzato in un database vettoriale.
query	string	Indica che l'input rappresenta query di ricerca per trovare i documenti più pertinenti nel database vettoriale.
Testo	string	Indica che l'input è un input di testo generale.

EmbeddingObject

Nome	Tipo	Descrizione
embedding	string

ListObject

Il tipo di oggetto, che è sempre "elenco".

Nome	Tipo	Descrizione
list	string

NotFoundError

Nome	Tipo	Descrizione
Errore	string	Descrizione dell'errore.
messaggio	string	Messaggio di errore.
stato	integer	Codice di stato HTTP.

TooManyRequestsError

Nome	Tipo	Descrizione
Errore	string	Descrizione dell'errore.
messaggio	string	Messaggio di errore.
stato	integer	Codice di stato HTTP.

UnauthorizedError

Nome	Tipo	Descrizione
Errore	string	Descrizione dell'errore.
messaggio	string	Messaggio di errore.
stato	integer	Codice di stato HTTP.

UnprocessableContentError

La richiesta presenta contenuti non elaborabili. L'errore viene restituito quando il payload indicato è valido in base a questa specifica. Tuttavia, alcune istruzioni indicate nel payload non sono supportate dal modello sottostante. Usare la sezione details per comprendere il parametro all'origine dell'errore.

Nome	Tipo	Descrizione
codice	string	Codice errore.
detail	Detail
Errore	string	Descrizione dell'errore.
messaggio	string	Messaggio di errore.
stato	integer	Codice di stato HTTP.

Utilizzo

Informazioni sull'utilizzo relative alla richiesta.

Nome	Tipo	Descrizione
prompt_tokens	integer	Numero di token usati dalla richiesta.
total_tokens	integer	Numero totale di token usati dalla richiesta.

Condividi tramite