Porta il tuo proprio modello al Servizio Agente Foundry

Il servizio Foundry Agent consente di connettersi e usare modelli ospitati dietro i gateway di intelligenza artificiale, come Gestione API di Azure o altri gateway di modelli di intelligenza artificiale gestiti non Azure. Questa funzionalità, denominata Bring Your Own Model, consente di mantenere il controllo sugli endpoint del modello durante l'uso delle funzionalità dell'agente Foundry.

Importante

Ai fini di questa documentazione, i modelli BYOM fanno riferimento a modelli di terze parti che vengono portati a Foundry e non includono Azure modelli diretti. Il servizio agenti di Foundry supporta la possibilità di usare un modello personalizzato (BYOM). Se si usa il servizio agente Foundry per interagire con i modelli BYOM, è possibile farlo a proprio rischio. I modelli BYOM sono considerati prodotti non Microsoft ai sensi delle condizioni del prodotto Microsoft e sono disciplinati dalle proprie condizioni di licenza.

Se si usa il servizio agente Foundry per interagire con i modelli BYOM, si è responsabili dell'implementazione di mitigazioni di intelligenza artificiale responsabili all'interno del servizio agente Foundry, ad esempio metaprompt, filtri di contenuto o altri sistemi di sicurezza.

Se si usa il servizio agente Foundry per interagire con i modelli BYOM, è necessario assicurarsi che l'uso del modello BYOM sia conforme ai requisiti di gestione dei dati. L'utente è responsabile della revisione di tutti i dati condivisi con i modelli BYOM e della comprensione delle procedure di terze parti per la conservazione e la posizione dei dati. È responsabilità dell'utente gestire se i dati verranno trasmessi all'esterno dei limiti di conformità e geografici Azure dell'organizzazione e eventuali implicazioni correlate quando si usano i modelli BYOM.

Questa funzionalità consente alle organizzazioni di:

  • Mantenere il controllo sugli endpoint del modello integrati nell'infrastruttura aziendale esistente.
  • Eseguire l'integrazione sicura con i gateway aziendali usando i criteri di sicurezza esistenti.
  • Creare agenti che usano modelli senza esporli pubblicamente.
  • Applicare i requisiti di conformità e governance all'accesso al modello di intelligenza artificiale.

Diagramma che mostra l'architettura del gateway di intelligenza artificiale con i flussi dal servizio Agent al gateway e dai modelli sottostanti.

In questo articolo si crea una connessione gateway all'endpoint del modello di intelligenza artificiale, si distribuisce un agente prompt che instrada le richieste attraverso il gateway e si verifica il flusso end-to-end.

Prerequisiti

Autorizzazioni necessarie

Sono necessarie le assegnazioni di ruolo seguenti:

Risorsa Ruolo obbligatorio
Progetto Foundry Utente di Azure AI o superiore
Gruppo di risorse (per la distribuzione della connessione) Collaboratore

Creare una connessione al modello

Usare il portale Foundry per creare una connessione al tuo modello.

È possibile scegliere modelli associati a una risorsa esistente di Gestione API di Azure o a un gateway di modelli di intelligenza artificiale non Azure. Usando questi passaggi, è possibile aggiungere diversi modelli che implementano l'API di completamento della chat OpenAI.

Per aggiungere una connessione del modello nel portale Foundry:

  1. Accedere a Microsoft Foundry.

  2. Selezionare Operare>Console amministrativa.

  3. Aprire la scheda Tutti i progetti .

  4. Nell'elenco dei progetti, trova il tuo progetto e seleziona il collegamento nella colonna Risorsa padre.

  5. Selezionare la scheda Modelli connessi all'amministratore e quindi selezionare Aggiungi. Screenshot dei modelli esterni nel portale Foundry.

    Verrà visualizzata la procedura guidata Aggiungi connessione modello .

  6. Nella pagina Connection Type selezionare Gestione API di Azure e quindi selezionare un nome di risorsa e una distribuzione del modello di Gestione API esistenti. Il modello deve implementare l'API di completamento della chat compatibile con OpenAI.

    Screenshot della selezione di una risorsa di Gestione API nel portale Foundry.

  7. Nella pagina Autenticazione selezionare un'opzione per l'autenticazione in Gestione API.

    Selezionare una chiave API , ad esempio una chiave di sottoscrizione di Gestione API o un'identità gestita , se ne è configurata una nel progetto Foundry.

    • Chiave API: immettere il valore della chiave nel campo specificato. Facoltativamente, specificare un nome di intestazione della chiave API da usare quando si passa la chiave API se il gateway richiede un'intestazione personalizzata.

    • Identità gestita: in Destinatari immettere il servizio di destinazione per il token di identità gestito, ad esempio https://cognitiveservices.azure.com/. Per la configurazione di Gestione API necessaria, vedere Configurare l'autenticazione dell'identità gestita per Gestione API.

  8. Nella pagina Configurazione modello configurare almeno una distribuzione del modello che verrà visualizzata in Foundry per l'uso con gli agenti.

    1. Selezionare + Aggiungi modello.
    2. Immettere un nome di distribuzione (usato nelle chiamate API) e il nome corrispondente e il nome visualizzato.
    3. Salvare la configurazione del modello.

    Ripetere i passaggi precedenti per aggiungere altri modelli alla connessione, se necessario.

  9. Nella pagina Avanzate eseguire facoltativamente la procedura seguente:

    1. Immettere una versione dell'API , se richiesta dalle distribuzioni del modello.
    2. Abilita l'impostazione Include il nome della distribuzione nel percorso URL se il gateway espone l'API di completamento della chat in un percorso stile Azure OpenAI che include il nome della distribuzione (ad esempio, /deployments/{deploymentName}/chat/completions). Lasciare disabilitata l'impostazione se il gateway usa un percorso di tipo OpenAI senza il nome della distribuzione ,ad esempio , /chat/completionse si basa su altri meccanismi di routing per indirizzare le richieste alla distribuzione del modello corretta.
    3. Cliccare + Aggiungi intestazione per aggiungere un'intestazione statica che va inclusa nelle richieste al gateway. Ripetere per aggiungere più intestazioni, se necessario.

  10. Selezionare Aggiungi.

Configurare l'autenticazione dell'identità gestita per API Management

Per configurare l'autenticazione Managed Identity in Gestione API, completare la configurazione seguente in Azure:

  1. Abilitare l'identità gestita nella risorsa del progetto Foundry.

    1. Nel portale Azure passare alla risorsa Foundry.

    2. Passare a Progetti> selezionare > del progetto.

    3. Abilitare una delle due operazioni seguenti:

      • Identità gestita assegnata dal sistema o
      • Identità gestita assegnata dall'utente.

    4. Per la convalida dei token in Gestione API, ottenere l'ID applicazione (client) dell'identità gestita.

      1. Per prima cosa, ottieni l'ID oggetto dalla configurazione dell'identità gestita nel tuo progetto.
      2. Cercare l'ID oggetto in Microsoft Entra ID applicazioni aziendali per individuare l'ID applicazione (client) corrispondente.

  2. Convalidare il token di identità gestito in Gestione API.

    Nei criteri in ingresso di Gestione API usare il criterio validate-azure-ad-token per applicare la convalida dei token per le richieste da Microsoft Foundry.

    • Impostare l'elemento audience sullo stesso valore configurato nel campo Gruppo di destinatari della connessione Foundry.
    • Configurare l'ID dell'app di identità gestita in client-application-ids.

    Esempio:

    <validate-azure-ad-token tenant-id="{{your-tenant-id}}" header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized">
   <client-application-ids>
      <application-id>{{managed-identity-client-id}}</application-id>
   </client-application-ids>
   <audiences>
      <audience>{{audience-configured-in-foundry-connection}}</audience>
   </audiences>
</validate-azure-ad-token>

La connessione viene creata e visualizzata nell'elenco nella scheda Modelli connessi all'amministratore .

Distribuzioni di modelli connessi con l'amministratore

Foundry distribuisce automaticamente i modelli aggiunti tramite una connessione, in modo da poterli usare nei progetti.

  • Ogni modello aggiunto nella procedura guidata di connessione corrisponde a una distribuzione in Foundry.

  • È possibile selezionare una distribuzione connessa all'amministratore durante la configurazione del modello di un agente. Foundry instrada in modo automatico le richieste dagli agenti a queste implementazioni tramite il gateway connesso.

Creare una connessione al modello

Usare il interfaccia della riga di comando di Azure per creare una connessione ai modelli dietro il gateway di intelligenza artificiale.

Il servizio agent supporta due tipi di connessione: connessioni di Gestione API e connessioni gateway modello .

Scegliere il tipo di connessione corrispondente al gateway:

Tipo di connessione Usare quando Valore categoria
Gestione API Si usano già Gestione API di Azure per il routing del modello e si vogliono impostazioni predefinite di Gestione API intelligenti. ApiManagement
Gateway modello Si usa OpenAI, MuleSoft o un gateway personalizzato ed è necessaria l'individuazione di modelli statici o dinamici. ModelGateway

Per informazioni dettagliate sulle specifiche di connessione, vedere gli esempi connection in GitHub.

Distribuire la connessione

  1. Clonare o scaricare il repository degli esempi Foundry e individuare il modello Bicep per il tipo di connessione in infrastructure/infrastructure-setup-bicep/01-connections/. La directory contiene file Bicep separati e file di parametri per le connessioni di Gestione API e Gateway modello.

  2. Distribuire la connessione eseguendo az deployment group create con il gruppo di risorse, il file del modello Bicep e il file dei parametri corrispondente. Prima della distribuzione, sostituire i valori segnaposto nel file dei parametri con l'URL dell'endpoint del gateway e le credenziali. Per informazioni di riferimento sul comando completo, vedere az deployment group create.

    Suggerimento

    Un'implementazione riuscita restituisce provisioningState: Succeeded nell'output del comando.

  3. Verificare la connessione nel portale foundry. Passare al portale Foundry e selezionare il progetto. Passare a Risorse connesse nelle impostazioni del progetto. La nuova connessione viene visualizzata con lo stato Attivo e l'URL dell'endpoint del gateway specificato.

Creare un agente di prompt con la connessione al modello

Dopo aver creato la connessione, creare ed eseguire un agente prompt che usa i modelli dietro il gateway. La differenza principale rispetto a un agente standard è il formato del nome della distribuzione del modello: <connection-name>/<model-name>.

  1. Impostare le variabili di ambiente seguenti:

    Variabile Valore Esempio
    FOUNDRY_PROJECT_ENDPOINT URL dell'endpoint del progetto https://<your-ai-services-account>.services.ai.azure.com/api/projects/<project-name>
    FOUNDRY_MODEL_DEPLOYMENT_NAME <connection-name>/<model-name> my-apim-connection/gpt-4o

  2. Inizializza un AIProjectClient con il tuo endpoint e DefaultAzureCredential, quindi chiama agents.create_version() con un PromptAgentDefinition. Impostare il parametro model al valore FOUNDRY_MODEL_DEPLOYMENT_NAME.

    Una chiamata riuscita restituisce un oggetto agente con i relativi idcampi , namee version popolati.

  3. Ottenere il client OpenAI con project.get_openai_client(), creare una conversazione con conversations.create()e inviare una richiesta con responses.create(). Passa il riferimento dell'agente in extra_body come {"agent_reference": {"name": agent.name, "type": "agent_reference"}}.

    Una risposta con esito positivo restituisce il testo di risposta del modello, confermando che l'agente sta eseguendo il routing tramite il gateway.

    Nota

    Se la risposta ha esito negativo con un model not found errore, verificare che il FOUNDRY_MODEL_DEPLOYMENT_NAME valore usi il formato <connection-name>/<model-name>.

  4. Al termine del test, eseguire la pulizia eliminando la conversazione e la versione dell'agente.

Per un esempio funzionante completo, vedere gli esempi agent SDK in GitHub. Per informazioni dettagliate sull'API, vedere AIProjectClient e PromptAgentDefinition.

Verificare la distribuzione

Dopo aver distribuito l'agente, assicurati che la pipeline completa funzioni correttamente:

  1. Controllare lo stato della connessione : nel portale Foundry passare a Risorse connesse nelle impostazioni del progetto. Verificare che la connessione mostri lo stato Attivo . Se lo stato è Inattivo, controllare l'URL e le credenziali dell'endpoint del gateway.

  2. Invia una richiesta di test : usare l'SDK per creare una conversazione e inviare una richiesta come descritto nella sezione precedente. Una risposta con esito positivo restituisce il testo di risposta del modello, confermando che l'agente può raggiungere il modello tramite il gateway.

  3. Esaminare i log del gateway : verificare che le richieste vengano indirizzate correttamente. Per la gestione delle API, controllare le analitiche di Gestione API nel portale di Azure. Per altri gateway, esaminare la registrazione delle richieste del proprio gateway. Verranno visualizzate le richieste in ingresso dall'endpoint del servizio agent.

Suggerimento

Se un passaggio non riesce, vedere la sezione Risolvere i problemi comuni per i passaggi di risoluzione.

Dettagli del tipo di connessione

Questa sezione fornisce informazioni di riferimento su ogni tipo di connessione e sulle relative opzioni di configurazione.

Connessione alla Gestione delle API

Le connessioni di Gestione API offrono impostazioni predefinite intelligenti e seguono le convenzioni standard di Gestione API:

Impostazione Valore predefinito
Elencare l'endpoint di distribuzione /deployments
Ottenere l'endpoint di distribuzione /deployments/{deploymentName}
Fornitore AzureOpenAI

Priorità di configurazione:

  1. Valori di metadati espliciti (priorità più alta).
  2. Impostazioni predefinite standard di gestione API (fallback).

Metodi di autenticazione:

  • Chiave API : autenticazione della chiave di sottoscrizione standard.
  • Microsoft Entra ID - Enterprise Identity Integration.

Connessione modello gateway

Le connessioni gateway modello forniscono un'interfaccia unificata per la connessione a vari provider di modelli di intelligenza artificiale. Queste connessioni supportano sia l'individuazione di modelli statici che dinamici:

  • Individuazione statica: i modelli sono predefiniti nei metadati di connessione. Ideale per le distribuzioni fisse e gli elenchi di modelli approvati dall'organizzazione.
  • Individuazione dinamica : i modelli vengono individuati in fase di esecuzione usando gli endpoint API. Ideale per la modifica frequente di distribuzioni e cataloghi gestiti dal provider.

I tipi di autenticazione supportati sono chiave API e OAuth 2.0. Le chiavi API vengono archiviate in modo sicuro e a cui viene fatto riferimento tramite il sistema di credenziali.

Risolvere i problemi comuni

Problema Risoluzione
La connessione mostra lo stato inattivo Verificare che l'URL dell'endpoint del gateway sia raggiungibile e che le credenziali di autenticazione siano valide.
Agent restituisce un model not found errore Verificare che il FOUNDRY_MODEL_DEPLOYMENT_NAME valore usi il formato corretto: <connection-name>/<model-name>.
Errori di timeout del gateway Verificare che gli endpoint del gateway siano accessibili dalla rete del servizio Agent Service. Per le reti private, vedere le linee guida per l'isolamento della rete nella sezione Limitazioni.
Errori di autenticazione Per Gestione API, verificare la chiave di sottoscrizione. Per Gateway modello, verificare la chiave API o la configurazione di OAuth 2.0.

Configurazioni supportate

  • Solo gli agenti prompt nell'Agent SDK supportano questa funzionalità.
  • Strumenti dell'agente supportati: Interprete del codice, Funzioni, Ricerca file, OpenAPI, IQ foundry, SharePoint grounding, Fabric Data Agent, MCP e Automazione browser.
  • Configurazioni di rete supportate:
    • La rete pubblica è supportata sia per Gestione API che per i gateway self-hosted.
    • Per l'isolamento completo della rete:
      • Gestione API come gateway di intelligenza artificiale: Distribuire Foundry e Gestione API insieme usando questo modello di GitHub.
      • Gateway self-hosted: assicurarsi che gli endpoint del gateway siano accessibili all'interno della rete virtuale utilizzata dal servizio Agente.

Contenuto correlato

  • Last updated on