Configurare un servizio di ricerca per connettersi usando un'identità gestita in Ricerca di intelligenza artificiale di Azure
Importante
L'assegnazione di identità gestita assegnata dall'utente è in anteprima pubblica in Condizioni per l'utilizzo supplementari. L'API REST di anteprima di gestione fornisce un'assegnazione di identità gestita assegnata dall'utente per Ricerca di intelligenza artificiale di Azure. Il supporto per un'identità gestita assegnata dal sistema è disponibile a livello generale.
È possibile usare Microsoft Entra ID e assegnazioni di ruolo per le connessioni in uscita da Ricerca di intelligenza artificiale di Azure alle risorse che forniscono dati, intelligenza artificiale applicata o vettorizzazione durante l'indicizzazione o le query.
Per usare i ruoli in una connessione in uscita, configurare innanzitutto il servizio di ricerca in modo da usare un'identità gestita assegnata dal sistema o assegnata dall'utente come principio di sicurezza per il servizio di ricerca in un tenant di Microsoft Entra. Dopo aver creato un'identità gestita, è possibile assegnare ruoli per l'accesso autorizzato. Le identità gestite e le assegnazioni di ruolo eliminano la necessità di passare segreti e credenziali in una stringa di connessione o in un codice.
Prerequisiti
Servizio di ricerca al livello Basic o superiore, in qualsiasi area.
Risorsa di Azure che accetta le richieste in ingresso da un'entità di sicurezza di Microsoft Entra con un'assegnazione di ruolo valida.
Scenari supportati
Azure AI Search può connettersi ad altre risorse di Azure con l'identità gestita assegnata dal sistema o assegnata dall'utente.
- La configurazione del servizio di ricerca di un'identità gestita assegnata dal sistema è disponibile a livello generale.
- La configurazione del servizio di ricerca di un'identità gestita assegnata dall'utente è disponibile in anteprima pubblica, in condizioni supplementari per l'utilizzo.
- L'utilizzo di un'identità gestita, assegnata dal sistema o dall'utente, è disponibile a livello generale. Ad esempio, se si vuole un'identità gestita assegnata dall'utente in una connessione all'origine dati dell'indicizzatore, un insieme di credenziali delle chiavi, una sessione di debug o una cache di arricchimento, è possibile usare una versione dell'API REST disponibile a livello generale per creare la connessione, presupponendo che la funzionalità in uso sia disponibile anche a livello generale.
Un'identità gestita dal sistema è indicata quando una stringa di connessione è l'ID risorsa univoco di un servizio o un'applicazione compatibile con Microsoft Entra ID. Un'identità gestita assegnata dall'utente viene specificata tramite una proprietà "identità".
Un servizio di ricerca usa Archiviazione di Azure come origine dati dell'indicizzatore e come sink di dati per le sessioni di debug, la memorizzazione nella cache di arricchimento e l'archivio conoscenze. Per le funzionalità di ricerca che esegue il writeback nell'archiviazione, l'identità gestita richiede un'assegnazione di ruolo collaboratore, come descritto nella sezione "Assegnare un ruolo".
| Scenario | System | Assegnata dall'utente |
|---|---|---|
| Connessioni dell'indicizzatore alle origini dati di Azure supportate 1 | Sì | Sì |
| Azure Key Vault per le chiavi gestite dal cliente | Sì | Sì |
| Sessioni di debug (ospitate in Archiviazione di Azure)1 | Sì | No |
| Cache di arricchimento (ospitata in Archiviazione di Azure) 1, 2 | Sì | Sì |
| Knowledge Store (ospitato in Archiviazione di Azure) 1 | Sì | Sì |
| Connessioni ad Azure OpenAI, Studio AI della piattaforma Azure e Funzioni di Azure tramite capacità/vettorizzatori 3 | Sì | Sì |
1 Per la connettività tra la ricerca e l'archiviazione, la configurazione di sicurezza di rete impone vincoli per il tipo di identità gestita che è possibile usare. È possibile usare solo un'identità gestita dal sistema per una connessione alla stessa area all'archiviazione tramite l'eccezione del servizio attendibile o la regola dell'istanza di risorsa. Per informazioni dettagliate, vedere Accesso a un account di archiviazione protetto dalla rete.
2 Il servizio di ricerca AI attualmente non è in grado di connettersi alle tabelle in un account di archiviazione con accesso con chiave condivisa disattivato.
3 Le connessioni ad Azure OpenAI, Studio AI della piattaforma Azure e Funzioni di Azure tramite capacità/vettorizzatori includono: capacità personalizzate, vettorizzatore personalizzato, capacità di incorporamento di Azure OpenAI, vettorizzatore di OpenAI di Azure, capacità AML e vettorizzatore del catalogo dei modelli di Studio AI della piattaforma Azure.
Creare un'identità gestita dal sistema
Quando si abilita un'identità gestita assegnata dal sistema, Microsoft Entra ID crea un'identità per il servizio di ricerca che può essere usata per eseguire l'autenticazione ad altri servizi di Azure all'interno dello stesso tenant. È quindi possibile usare questa identità nelle assegnazioni di ruolo per accedere a dati e modelli.
Un'identità gestita assegnata dal sistema è univoca per il servizio di ricerca e associata al servizio per la sua durata. Un servizio di ricerca può avere una sola identità gestita assegnata dal sistema.
Accedere al portale di Azure e trovare il servizio di ricerca.
In Impostazioni selezionare Identità.
Nella scheda Assegnato dal sistema, in Stato, selezionare Sì.
Seleziona Salva.
Dopo aver salvato le impostazioni, la pagina viene aggiornata per visualizzare un identificatore di oggetto assegnato al servizio di ricerca.
Creare un'identità gestita assegnata dall'utente
Importante
Parte di questo scenario è disponibile in anteprima pubblica in Condizioni supplementari per l'utilizzo. L'API REST di anteprima di gestione fornisce la configurazione dell'identità gestita assegnata dall'utente per Ricerca di intelligenza artificiale di Azure.
Un'identità gestita assegnata dall'utente è una risorsa in Azure. È possibile creare più identità gestite assegnate dall'utente se si vuole una maggiore granularità nelle assegnazioni di ruolo. Ad esempio, è possibile che si vogliano identità separate per applicazioni e scenari diversi.
I passaggi sono:
- Nella sottoscrizione di Azure creare un'identità gestita assegnata dall'utente.
- Nel servizio di ricerca aggiornare la definizione del servizio per abilitare l'identità gestita assegnata dall'utente (questo passaggio è in anteprima).
- In altri servizi di Azure a cui ci si vuole connettere, creare un'assegnazione di ruolo per l'identità.
- Nelle connessioni all'origine dati in Ricerca di intelligenza artificiale di Azure, ad esempio un'origine dati dell'indicizzatore, fare riferimento all'identità gestita dall'utente nei dettagli della connessione. Questo passaggio è disponibile a livello generale se il supporto per la funzionalità è disponibile a livello generale.
È possibile definire l'ambito di un'identità gestita assegnata dall'utente a sottoscrizioni, gruppi di risorse o tipi di risorse.
L'associazione di un'identità gestita assegnata dall'utente è supportata nel portale di Azure, nelle versioni di anteprima delle API REST di gestione e nei pacchetti beta SDK che forniscono la funzionalità.
Accedere al portale di Azure
Selezionare Crea una risorsa.
Nella barra di ricerca "Servizi di ricerca e marketplace" cercare "Identità gestita assegnata dall'utente" e quindi selezionare Crea.
Selezionare la sottoscrizione, il gruppo di risorse e l'area. Assegnare all'identità un nome descrittivo.
Selezionare Crea e attendere il completamento della distribuzione della risorsa.
Prima di poter usare l'identità, sono necessari alcuni minuti.
Nella pagina del servizio di ricerca, in Impostazioni, selezionare Identità.
Nella scheda Assegnata dall'utente selezionare Aggiungi.
Scegliere la sottoscrizione e quindi selezionare la risorsa gestita assegnata dall'utente creata nel passaggio precedente.
Assegnare un ruolo
Dopo aver ottenuto un'identità gestita, assegnare ruoli che determinano le autorizzazioni del servizio di ricerca per la risorsa di Azure.
Le autorizzazioni di lettura sono necessarie per le connessioni dati dell'indicizzatore e per l'accesso a una chiave gestita dal cliente in Azure Key Vault.
Le autorizzazioni di scrittura sono necessarie per le funzionalità di arricchimento tramite intelligenza artificiale che usano Archiviazione di Azure per ospitare i dati delle sessioni di debug, la memorizzazione nella cache di arricchimento e l'archiviazione del contenuto a lungo termine in un archivio conoscenze.
I passaggi seguenti illustrano il flusso di lavoro dell'assegnazione di ruolo. Questo esempio è relativo ad Azure OpenAI. Per altre risorse di Azure, vedere Connettersi ad Archiviazione di Azure, Connettersi ad Azure Cosmos DB o Connettersi ad Azure SQL.
Accedere al portale di Azure con l'account Azure e passare alla risorsa Azure OpenAI.
Selezionare Controllo di accesso dal menu a sinistra.
Selezionare Aggiungi e quindi selezionare Aggiungi un'assegnazione di ruolo.
In Ruoli della funzione processo selezionare Servizi cognitivi Utente OpenAI e quindi selezionare Avanti.
In Membri, selezionare Identità gestita e quindi selezionare Membri.
Filtrare in base alla sottoscrizione e al tipo di risorsa (servizi di ricerca) e quindi selezionare l'identità gestita del servizio di ricerca.
Seleziona Rivedi + assegna.
Esempi di stringhe di connessione
Dopo aver definito un'identità gestita per il servizio di ricerca e assegnato un'assegnazione di ruolo, è possibile modificare le connessioni in uscita per usare l'ID risorsa univoco dell'altra risorsa di Azure. Ecco alcuni esempi di stringhe di connessione per vari scenari.
È possibile usare le versioni dell'API REST disponibili a livello generale e i pacchetti di Azure SDK per queste connessioni.
Suggerimento
È possibile creare la maggior parte di questi oggetti nel portale di Azure, specificando un'identità gestita assegnata dal sistema o dall'utente e quindi visualizzare la definizione JSON per ottenere la stringa di connessione.
Un'origine dati dell'indicizzatore include una proprietà "credenziali" che determina la modalità di connessione all'origine dati. L'esempio seguente mostra una stringa di connessione che specifica l'ID risorsa univoco di un account di archiviazione.
Microsoft Entra ID autentica la richiesta usando l'identità gestita dal sistema del servizio di ricerca. Si noti che la stringa di connessione non include un contenitore. In una definizione di origine dati, un nome del contenitore viene specificato nella proprietà "contenitore" (non visualizzata), non nella stringa di connessione.
"credentials": {
"connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}
Una richiesta di ricerca ad Archiviazione di Azure può essere effettuata anche con un'identità gestita assegnata dall'utente. L'identità utente del servizio di ricerca viene specificata nella proprietà "identità".
"credentials": {
"connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
},
. . .
"identity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
}
Una definizione dell'archivio conoscenze include una stringa di connessione ad Archiviazione di Azure. La stringa di connessione è l'ID risorsa univoco dell'account di archiviazione. Si noti che la stringa non include contenitori o tabelle nel percorso. Queste sono definite nella definizione di proiezione incorporata, non nella stringa di connessione.
"knowledgeStore": {
"storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}
Un indicizzatore crea, usa e memorizza il contenitore usato per gli arricchimenti memorizzati nella cache. Non è necessario includere il contenitore nella stringa di connessione della cache. È possibile trovare l'ID oggetto nella pagina Identità del servizio di ricerca nel portale.
"cache": {
"enableReprocessing": true,
"storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}
Una sessione di debug viene eseguita nel portale e accetta una stringa di connessione all'avvio della sessione. È possibile incollare una stringa simile all'esempio seguente.
"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",
Una competenza personalizzata è destinata all'endpoint di una funzione di Azure o di un'app che ospita codice personalizzato. L'endpoint viene specificato nella definizione della competenza personalizzata. La presenza di "authResourceId" indica al servizio di ricerca di connettersi usando un'identità gestita, passando l'ID applicazione della funzione o dell'app di destinazione nella proprietà.
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "A custom skill that can identify positions of different phrases in the source text",
"uri": "https://contoso.count-things.com",
"authResourceId": "<Azure-AD-registered-application-ID>",
"batchSize": 4,
"context": "/document",
"inputs": [ ... ],
"outputs": [ ...]
}
Competenza di incorporamento di Azure OpenAI e vettore OpenAI di Azure:
Una competenza e un vettore di incorporamento di Azure OpenAI nella ricerca di intelligenza artificiale hanno come destinazione l'endpoint di un servizio Azure OpenAI che ospita un modello di incorporamento. L'endpoint viene specificato nella definizione della competenza di incorporamento di Azure OpenAI e/o nella definizione del vettore OpenAI di Azure. L'identità gestita dal sistema viene usata se configurata e se "apikey" e "authIdentity" sono vuoti. La proprietà "authIdentity" viene usata solo per l'identità gestita assegnata dall'utente.
Esempio di identità gestita dal sistema:
{
"@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
"description": "Connects a deployed embedding model.",
"resourceUri": "https://url.openai.azure.com/",
"deploymentId": "text-embedding-ada-002",
"modelName": "text-embedding-ada-002",
"inputs": [
{
"name": "text",
"source": "/document/content"
}
],
"outputs": [
{
"name": "embedding"
}
]
}
"vectorizers": [
{
"name": "my_azure_open_ai_vectorizer",
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "https://url.openai.azure.com",
"deploymentId": "text-embedding-ada-002",
"modelName": "text-embedding-ada-002"
}
}
]
Esempio di identità gestita assegnata dall'utente:
{
"@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
"description": "Connects a deployed embedding model.",
"resourceUri": "https://url.openai.azure.com/",
"deploymentId": "text-embedding-ada-002",
"modelName": "text-embedding-ada-002",
"inputs": [
{
"name": "text",
"source": "/document/content"
}
],
"outputs": [
{
"name": "embedding"
}
],
"authIdentity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
}
}
"vectorizers": [
{
"name": "my_azure_open_ai_vectorizer",
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "https://url.openai.azure.com",
"deploymentId": "text-embedding-ada-002",
"modelName": "text-embedding-ada-002"
"authIdentity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
}
}
}
]
Verificare l'accesso al firewall
Se la risorsa di Azure si trova dietro un firewall, assicurarsi che sia presente una regola in ingresso che ammette le richieste dal servizio di ricerca.
Per le connessioni della stessa area ad Archiviazione BLOB di Azure o Azure Data Lake Storage Gen2, usare un'identità gestita dal sistema e l'eccezione del servizio attendibile. Facoltativamente, è possibile configurare una regola di istanza della risorsa per ammettere le richieste.
Per tutte le altre risorse e connessioni, configurare una regola del firewall IP che ammette le richieste dalla ricerca. Per dettagli, vedere Accesso dell'indicizzatore al contenuto protetto dalle funzionalità di sicurezza di rete di Azure.