Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
La configurazione dell'agente standard usa risorse di Azure a tenant singolo gestite dal cliente per archiviare lo stato dell'agente e mantenere tutti i dati dell'agente sotto il controllo. Usare la configurazione standard quando è necessaria la sovranità dei dati completa, la conformità ai criteri di sicurezza aziendali o l'isolamento a livello di progetto.
In questa configurazione:
- Gli stati dell'agente (conversazioni, risposte) vengono archiviati nelle proprie risorse Azure.
- Si mantiene il controllo completo sulla residenza e l'accesso dei dati.
Suggerimento
Per una configurazione più semplice che usa risorse gestite da Microsoft, vedere Setup e scegliere l'opzione di configurazione dell'agente di base.
Prerequisiti
- Sottoscrizione Azure. Creane uno gratis.
- Un account Azure Cosmos DB per NoSQL. Per i requisiti di velocità effettiva, vedere Requisiti di velocità effettiva di Cosmos DB.
- Un account Archiviazione di Azure.
- Risorsa Foundry IQ (Azure AI Search).
- Risorsa Azure Key Vault per la gestione dei segreti.
- interfaccia della riga di comando di Azure versione 2.50 o successiva. Eseguire
az --versionper verificare. - Autorizzazioni per l'identità che esegue una distribuzione delle impostazioni di funzionalità. Oltre ad aver creato l'account e il progetto, questa identità deve disporre di Storage Blob Data Contributor nell'account di archiviazione e Cosmos DB Operator nell'account Cosmos DB. L'IQ di Foundry non richiede un ruolo chiamante. Vedere Configurare le impostazioni delle funzionalità dell'agente.
- Un modello compatibile con gli agenti distribuito, ad esempio gpt-4o.
Panoramica delle risorse
Importante
Le configurazioni standard richiedono l'uso di risorse Bring Your Own (BYO) in modo che tutti i dati dell'agente restino nel tenant Azure:
| Risorsa | Cosa archivia |
|---|---|
| Archiviazione di Azure (archiviazione di file BYO) | File caricati dagli sviluppatori e dagli utenti finali |
| Foundry IQ (ricerca BYO) | Archivi vettoriali creati dall'agente |
| Azure Cosmos DB (archiviazione thread BYO) | Messaggi, cronologia conversazioni e metadati dell'agente |
Tutti i dati elaborati dal servizio Foundry Agent vengono archiviati automaticamente inattivi in queste risorse, consentendo di soddisfare i requisiti di conformità e gli standard di sicurezza aziendali.
Requisiti di velocità effettiva di Cosmos DB
Il Azure Cosmos DB per NoSQL account deve avere un limite di velocità effettiva totale di almeno 3000 UR/s. Sono supportate sia la velocità effettiva con provisioning che le modalità serverless.
La configurazione Standard effettua il provisioning di cinque contenitori, ognuno dei quali richiede 1000 UR/sec:
| Contenitore | Scopo |
|---|---|
thread-message-store |
Conversazioni dell'utente finale |
system-thread-message-store |
Messaggi di sistema interni |
agent-entity-store |
Metadati dell'agente (istruzioni, strumenti, nome) |
agent-definitions-v1 |
Metadati dell'agente (istruzioni, strumenti, nome, versioni) |
run-state-v1 |
Messaggi interni e conversazioni dell'utente finale |
thread-message-store, system-thread-message-store, e agent-entity-store fanno parte dell'installazione standard di Foundry Agent Service (Classic).
Il servizio agente Foundry (Nuovo) usa agent-definitions-v1 e run-state-v1.
I contenitori meno recenti appartengono all'esperienza classica e non vengono usati dal nuovo runtime.
Avviso
Gli ambienti di runtime del servizio Foundry Agent Classic e New usano contenitori Cosmos DB diversi.
isolamento dei dati a livello progetto
L'installazione standard applica l'isolamento dei dati a livello di progetto per impostazione predefinita. Vengono forniti automaticamente due contenitori di archiviazione blob nel tuo account di archiviazione: uno per i file e uno per i dati di sistema temporanei (blocchi, incorporamenti). Viene effettuato il provisioning di tre contenitori nell'account Cosmos DB: uno per i thread utente, uno per i messaggi di sistema e uno per i dati di configurazione dell'agente, ad esempio istruzioni, strumenti e nomi. Questo comportamento predefinito riduce la complessità della configurazione, applicando comunque limiti di dati rigorosi tra i progetti.
Impostazioni delle funzionalità
Le impostazioni delle funzionalità sono proprietà dell'account Foundry e del progetto che dichiarano quali risorse di Azure ospitano lo stato dell'agente, i dati vettoriali e i file. Impostarli nell'account per stabilire le impostazioni predefinite per i progetti ed eseguire l'override di un singolo archivio in un progetto quando tale progetto necessita di una risorsa diversa.
Agent Service predispone l'infrastruttura sottostante necessaria e le connessioni alle tue risorse durante il processo di provisioning. Queste connessioni gestite da impostazioni di funzionalità non sono modificabili durante l'uso, quindi non è possibile modificarle o eliminarle direttamente. Non è anche possibile aggiornare le impostazioni delle funzionalità in un progetto esistente. Per modificare le risorse usate da un progetto, eliminare e ricreare il progetto con le impostazioni desiderate.
Per l'elenco completo delle impostazioni, le autorizzazioni e gli esempi di Bicep, vedere Configurare le impostazioni delle funzionalità dell'agente.
Eseguire l'approvvigionamento delle risorse passo dopo passo
Provisioning manuale
Seguire questa procedura per effettuare manualmente il provisioning di tutte le risorse necessarie per la configurazione dell'agente standard. Attendere circa 30-45 minuti per il processo di provisioning completo.
Fase 1: Creare risorse dipendenti
- Creare o riutilizzare le risorse seguenti. È possibile creare nuove risorse o passare l'ID risorsa di quelli esistenti:
- Account Azure Cosmos DB for NoSQL
- Account di archiviazione di Azure
- Risorsa Foundry IQ
- risorsa di Azure Key Vault (usata per la gestione di segreti e stringhe di connessione per l'infrastruttura dell'agente)
- [Facoltativa] Risorsa di applicazione Azure Insights
- [Facoltativo] Risorsa Fonderia esistente
Fase 2: Creare risorse e impostazioni delle funzionalità di Foundry
- Creare una risorsa Microsoft Foundry.
- Creare connessioni a livello di account:
- Creare una connessione account alla risorsa di Application Insights.
- Implementare gpt-4o o un altro modello compatibile con agenti.
- Imposta le impostazioni delle funzionalità nell'account, facendo riferimento agli ID delle risorse del tuo account Cosmos DB, del servizio Foundry IQ e dell'account di archiviazione.
- Creare un progetto. Il progetto eredita le impostazioni delle funzionalità dell'account, a meno che non si sovrascrivano quelle di un singolo negozio. Il servizio Agent effettua il provisioning dell'infrastruttura sottostante necessaria e delle connessioni alle risorse come parte di questo passaggio.
Fase 3: Assegnare ruoli di runtime all'identità gestita del progetto
L'identità gestita del progetto include sia l'identità gestita assegnata dal sistema (SMI) che l'identità gestita assegnata dall'utente (UMI). Questi ruoli regolano l'accesso di runtime per gli agenti in esecuzione. Sono separate dalle autorizzazioni di cui l'identità di distribuzione ha bisogno, e l'una non sostituisce l'altra.
- Assegnare l'identità gestita del progetto (per SMI) ai ruoli seguenti:
- Operatore Cosmos DB a livello di account per la risorsa Cosmos DB.
- Storage Account Contributor a livello di account per la risorsa account di archiviazione.
Fase 4: Assegnare autorizzazioni granulari per le risorse
- Assegnare l'identità gestita del progetto (sia SMI che UMI) ai ruoli seguenti negli ambiti delle risorse specificati:
-
Foundry IQ:
- Collaboratore ai dati dell'indice di ricerca
- Collaboratore servizio di ricerca
-
Contenitore Archiviazione BLOB di Azure:
<workspaceId>-azureml-blobstore- Collaboratore dei dati di Storage Blob
-
Contenitore di Archiviazione BLOB di Azure:
<workspaceId>-azureml-agent- Proprietario dei dati dei BLOB di archiviazione
-
Cosmos DB for NoSQL Database:
enterprise_memory- Contributore dati integrato di Cosmos DB
- Ambito: livello di database per coprire tutti i contenitori (non è necessaria alcuna assegnazione di ruolo specifica del contenitore).
-
Foundry IQ:
Fase 5: Concedere l'accesso per sviluppatori
Assegnare a tutti gli sviluppatori che devono creare o modificare agenti nel progetto il ruolo Foundry User a livello di progetto.
Importante
I ruoli di Controllo degli accessi in base al ruolo di Foundry sono stati recentemente rinominati. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager erano precedentemente denominati Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.
Usare un modello di Bicep
Usare una risorsa Azure OpenAI esistente, un account Archiviazione di Azure esistente, un account Azure Cosmos DB per NoSQL o la risorsa Foundry IQ specificando l'ID risorsa Azure Resource Manager completo (ARM) nel file del modello di agente standard.
Usare una risorsa OpenAI Azure esistente
Seguire la procedura descritta in Configurazione dell'ambiente per ottenere l'ID risorsa dell'account Foundry Tools.
Nel file modello di agente standard sostituire il segnaposto seguente:
existingAoaiResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{serviceName}
Usare un account di Archiviazione di Azure esistente per l'archiviazione file
Accedere al interfaccia della riga di comando di Azure e selezionare la sottoscrizione con l'account di archiviazione:
az loginEseguire il comando seguente per ottenere l'ID risorsa dell'account di archiviazione:
az storage account show --resource-group <your-resource-group> --name <your-storage-account> --query "id" --output tsvL'output si trova nel valore
aiStorageAccountResourceIDnecessario nel modello.Nel file modello di agente standard sostituire il segnaposto seguente:
aiStorageAccountResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}
Usare un account esistente di Azure Cosmos DB per NoSQL per l'archiviazione dei thread
Viene creato un Azure Cosmos DB per NoSQL account per ogni account Foundry. Per i requisiti di velocità effettiva e il ridimensionamento multiprogetto, vedere Requisiti di velocità effettiva di Cosmos DB.
Nota
La capacità RU/s insufficiente nell'account Cosmos DB provoca errori di provisioning durante la distribuzione.
Accedere al interfaccia della riga di comando di Azure e selezionare la sottoscrizione con l'account Cosmos DB:
az loginEseguire il comando seguente per ottenere l'ID risorsa dell'account Azure Cosmos DB:
az cosmosdb show --resource-group <your-resource-group> --name <your-cosmosdb-account> --query "id" --output tsvL'output si trova nel valore
cosmosDBResourceIdnecessario nel modello.Nel file modello di agente standard sostituire il segnaposto seguente:
cosmosDBResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{cosmosDbAccountName}
Usare una risorsa Foundry IQ esistente
Accedere al interfaccia della riga di comando di Azure e selezionare la sottoscrizione con la risorsa di ricerca:
az loginEseguire il comando seguente per ottenere l'ID risorsa IQ Foundry:
az search service show --resource-group <your-resource-group> --name <your-search-service> --query "id" --output tsvNel file modello di agente standard sostituire il segnaposto seguente:
aiSearchServiceResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}
Verificare la configurazione
Dopo aver completato il provisioning, verificare che la configurazione funzioni correttamente:
- Nel portale di Azure passare al progetto Foundry e verificare che tutte le connessioni (Storage, Cosmos DB e Foundry IQ) vengano visualizzate nelle impostazioni del progetto.
- Verificare che un get sul progetto restituisca le impostazioni di funzionalità previste, inclusi i valori ereditati dall'account.
- Verificare le assegnazioni di ruolo passando alla pagina Controllo di accesso (IAM) di ogni risorsa e confermando che l'identità gestita del progetto ha i ruoli previsti.
- Creare un agente di test per confermare la funzionalità end-to-end.
Risolvere i problemi comuni
| Sintomo | Causa | Risoluzione |
|---|---|---|
| Il provisioning non riesce con un errore di velocità effettiva di Cosmos DB | Velocità effettiva di Cosmos DB insufficiente | Verificare che l'account Cosmos DB abbia almeno 3000 UR/sec (1000 UR/sec per contenitore × 3 contenitori). Per più progetti, moltiplicare per il numero di progetti. |
403 Forbidden quando l'agente legge o scrive file |
Assegnazioni di ruolo di archiviazione mancanti | Verificare che l'identità gestita del progetto abbia il ruolo Collaboratore ai dati del BLOB di archiviazione nel contenitore <workspaceId>-azureml-blobstore e del ruolo Proprietario dei dati del BLOB di archiviazione nel contenitore <workspaceId>-azureml-agent. |
SearchIndexNotFound o 403 nelle operazioni di ricerca |
Ruoli di ricerca mancanti | Verificare che l'identità gestita del progetto disponga sia del Search Index Data Contributor che del Search Service Contributor nella risorsa Foundry IQ. |
AuthorizationFailed durante la creazione o la modifica degli agenti |
Ruolo utente mancante | Assegna il ruolo Foundry User allo sviluppatore a livello di progetto. |
| La distribuzione non riesce prima che venga effettuato il provisioning di qualsiasi risorsa | L'identità di distribuzione non dispone di un ruolo di provisioning | Verifica che al chiamante siano assegnati i ruoli Storage Blob Data Contributor e Cosmos DB Operator. Vedere Configurare le impostazioni delle funzionalità dell'agente. |