Azure OpenAI Embedded skill

La competenza Azure OpenAI Embedding si collega a un modello di embedding distribuito nel tuo progetto Azure OpenAI in Foundry Models o Microsoft Foundry per generare embedding durante l'indicizzazione. I tuoi dati vengono elaborati nella Geo dove il tuo modello è distribuito.

Il wizard Import data nel portale Azure utilizza la competenza Azure OpenAI Embedding per vettorializzare i contenuti. Puoi eseguire il wizard e rivedere il set di abilità generate per vedere come il wizard costruisce l'abilità per incorporare i modelli.

Prerequisiti

• Una risorsa Azure OpenAI in Foundry Models o Foundry.

  • La tua risorsa OpenAI Azure deve avere un sottodominio personalizzato, come https://<resource-name>.openai.azure.com. Puoi trovare questo endpoint nella pagina Keys e Endpoint nel portale Azure e usarlo per la proprietà resourceUri in questa abilità.

  • La risorsa madre del tuo progetto Foundry fornisce accesso a più endpoint, inclusi https://<resource-name>.openai.azure.com, https://<resource-name>.services.ai.azure.com, e https://<resource-name>.cognitiveservices.azure.com. Puoi trovare questi endpoint nella pagina Keys e Endpoint nel portale Azure e usarne uno qualsiasi per la proprietà resourceUri in questa abilità.

• Un modello di embedding Azure OpenAI distribuito sulla tua risorsa o progetto. Per i modelli supportati, consulta la sezione Parametri delle Abilità .

@odata.type

Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill

Limiti dei dati

La dimensione massima di un input testuale dovrebbe essere di 8.000 token. Se l'input supera il massimo consentito, il modello genera un errore di richiesta non valido. Per maggiori informazioni, consulta il concetto chiave tokens nella documentazione Azure OpenAI. Considera di usare la skill Text Split se hai bisogno di spargere dati.

Parametri della competenza

I parametri sono distinti dalla mazzela e minuscola.

Dimensioni supportate da modelName

Le dimensioni supportate per una competenza di Embedding Azure OpenAI dipendono dal modelName configurato.

Input delle competenze

Output delle competenze

Definizione di esempio

Consideriamo un record che ha i seguenti campi:

{
    "content": "Microsoft released Windows 10."
}

Allora la tua definizione di abilità potrebbe essere questa:

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://my-demo-openai-eastus.openai.azure.com/",
  "deploymentId": "my-text-embedding-ada-002-model",
  "modelName": "text-embedding-ada-002",
  "dimensions": 1536,
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

Output di esempio

Per il testo di input dato, viene prodotto un output di embedding vettorializzato.

{
  "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... 
        0.021276434883475304,
      ]
}

L'output risiede nella memoria. Per inviare questo output a un campo nell'indice di ricerca, devi definire un outputFieldMapping che mappa l'output di embedding vettorizato (che è un array) a un campo vettoriale. Assumendo che l'output delle skill risieda nel nodo di incorporamento del documento e che content_vector sia il campo nell'indice di ricerca, il outputFieldMapping nell'indicizzatore dovrebbe apparire come:

  "outputFieldMappings": [
    {
      "sourceFieldName": "/document/embedding/*",
      "targetFieldName": "content_vector"
    }
  ]

Procedure consigliate

Di seguito alcune best practice da considerare quando utilizzi questa competenza:

• Se stai raggiungendo il limite Azure di OpenAI TPM (Token per minuto), considera il quota limits advisory così da poter affrontare di conseguenza. Consulta la documentazione Azure OpenAI monitoring per maggiori informazioni sulle prestazioni della tua istanza Azure OpenAI.

• Il deployment del modello di embedding Azure OpenAI che usi per questa competenza dovrebbe idealmente essere separato da quello usato per altri casi d'uso, incluso il vettoriizzatore quer. Questo aiuta ogni deployment a essere adattato al proprio caso d'uso specifico, portando a prestazioni ottimizzate e a facilità l'identificazione del traffico proveniente dall'indicizzatore e dall'indice che incorpora le chiamate.

• La tua istanza OpenAI di Azure dovrebbe trovarsi nella stessa regione o almeno geograficamente vicina alla regione dove è ospitato il tuo servizio di ricerca AI. Questo riduce la latenza e migliora la velocità del trasferimento dati tra i servizi.

• Per evitare di riscontrare spesso codici di errore 429, è consigliabile implementare il bilanciamento del carico tramite Gestione API implementando un gateway davanti a più distribuzioni di modelli di incorporamento OpenAI Azure.

• Se hai un limite Azure predefinito di OpenAI TPM (Token per minuto) come pubblicato nella documentazione quotas e limiti, apri un caso di supporto con il team Azure AI Search, così da poter essere adattato di conseguenza. Questo aiuta il tuo processo di indicizzazione a non rallentare inutilmente dal limite predefinito del TPM documentato, se hai limiti più alti.

• Per esempi e esempi di codice funzionanti che utilizzano questa abilità, consulta i seguenti link:

  • Vettorizzazione integrata (Python)
  • Vettorizzazione integrata (C#)
  • Vettorizzazione integrata (Java)

Errori e avvertenze

Considerazioni sulla sicurezza per l'autenticazione dell'identità gestita

Quando la competenza di incorporamento OpenAI Azure usa l'autenticazione dell'identità gestita, Azure AI Search ottiene un token di accesso Microsoft Entra per il gruppo di destinatari di Foundry Tools (https://cognitiveservices.azure.com) e lo include nelle richieste inviate all'endpoint specificato da resourceUri. L'autenticazione dell'identità gestita si applica quando authIdentity è impostata o quando apiKey e authIdentity sono vuoti e il servizio usa l'identità assegnata dal sistema.

L'endpoint a cui si resourceUri fa riferimento deve essere la propria Azure risorsa OpenAI o Foundry Tools. I domini supportati sono:

• openai.azure.com
• cognitiveservices.azure.com
• services.ai.azure.com

sono supportati anche gli endpoint Gestione API di Azure (*.azure-api.netGESTIONE API). Poiché un nome host di Gestione API non può essere verificato solo dal nome, Azure AI Search convalida questi endpoint con un controllo della connettività in tempo reale in fase di configurazione anziché in base alla corrispondenza del dominio. L'utente è responsabile della configurazione e della gestione della relazione tra l'endpoint di Gestione API e la risorsa OpenAI o Foundry Tools Azure sottostante.

Un token di identità gestito rilasciato per il gruppo di destinatari degli strumenti Foundry è valido per qualsiasi strumento foundry o Azure risorsa OpenAI su cui è autorizzata l'identità. L'invio a un endpoint non attendibile potrebbe esporre il token.

Procedure di sicurezza consigliate

Per mantenere una distribuzione sicura, seguire queste procedure:

• Impostare resourceUri solo sugli endpoint di cui si è proprietari e si è attendibili. Preferisce i domini degli strumenti foundry elencati in precedenza. Se si usa un endpoint di Gestione API, verificare che venga anteriore alla propria risorsa prima di abilitare l'identità gestita. Un nome host attendibile non è una prova di proprietà.
• Applicare il principio del privilegio minimo all'identità gestita usata dal servizio di ricerca. La competenza di incorporamento OpenAI Azure richiede solo il ruolo utente OpenAI di Servizi cognitivi nella risorsa di destinazione. Evitare di concedere ruoli più ampi.
• Usare Network Security Perimeter (NSP) e endpoint privati o integrazione rete virtuale per limitare gli endpoint che il servizio di ricerca può raggiungere e da quali origini la risorsa di destinazione accetta le richieste.
• Se si usa un endpoint di Gestione API, assicurarsi che il gateway convalida le richieste in ingresso e le inoltra solo al back-end previsto. È anche consigliabile esaminare periodicamente i criteri di accesso.
• Preferisce l'identità gestita rispetto a apiKey. Se si usa apiKey, archiviarlo e ruotarlo in modo sicuro e non incorporarlo nel controllo del codice sorgente. Il servizio rifiuta le configurazioni che impostano sia apiKey che authIdentity.
• Esaminare periodicamente le definizioni del set di competenze, le assegnazioni di ruolo dell'identità gestita e le configurazioni di Gestione API per verificare che resourceUri i valori, i controlli di accesso e le autorizzazioni di identità rimangano aggiornati e appropriati. Esaminare le modifiche alla configurazione tramite i processi di gestione delle modifiche e di revisione della sicurezza stabiliti.
• Monitorare Azure log di accesso di OpenAI e Foundry Tools, eventi di autenticazione e log di accesso per attività impreviste o non autorizzate.
• Rimuovere competenze, endpoint, assegnazioni di ruolo e chiavi API inutilizzate che non sono più necessarie.

Limitare l'accesso alla configurazione del set di competenze

Gli utenti che possono creare, modificare o eseguire set di competenze controllano sia l'endpoint di destinazione (resourceUri) che la configurazione di autenticazione usata dalla competenza. Poiché la competenza invia un token di identità gestito per il gruppo di destinatari degli strumenti foundry a tale endpoint, limitare queste autorizzazioni agli amministratori attendibili e seguire i processi standard di gestione delle modifiche e di revisione della sicurezza durante la configurazione delle competenze abilitate per l'identità gestita.

Vedere anche

• Competenze predefinite
• Come definire un set di competenze
• Come definire le mappature dei campi di uscita