Modelli Hugging Face in Microsoft Foundry (anteprima)

I modelli pubblicati da Hugging Face sono disponibili nel catalogo dei modelli di Foundry per la distribuzione in Microsoft Foundry. Nell'esperienza attuale di Foundry, questi modelli usano risorse di calcolo gestite.

In questo articolo scoprirai i modelli Hugging Face distribuibili, ne distribuirai uno con risorse di calcolo gestite e chiamerai l'endpoint dalla tua applicazione.

Nella sezione Individuazione modelli, usa il filtro Disponibile nel mio progetto per trovare i modelli Hugging Face che puoi distribuire nel progetto corrente. Per visualizzare tutti i modelli pubblicati da Hugging Face, imposta il filtro di disponibilità su Tutti i modelli. Se un modello non è attualmente disponibile in Foundry, nella scheda del modello viene visualizzato un pulsante Continua in Foundry (versione classica) in modo che sia possibile eseguire la distribuzione in Foundry (versione classica).

Usa i modelli Hugging Face in modo responsabile

I modelli originati da Hugging Face sono prodotti non Microsoft non testati o valutati da Microsoft. Prima di distribuire un modello, assicurarsi che sia appropriato per il caso d'uso specifico, inclusa la valutazione di eventuali considerazioni legali o di controllo di esportazione e l'esecuzione di valutazioni di rischio e sicurezza del modello. Informazioni sulle valutazioni di rischio e sicurezza di Foundry e sulle misure di sicurezza Hugging Face per i modelli offerti in Foundry.

Prerequisiti

• Un progetto di Foundry.
• Le assegnazioni di ruolo seguenti nell'ambito dell'account Foundry:
  • Collaboratore di Servizi cognitivi (o Proprietario di Foundry / Proprietario dell'account Foundry) per creare, aggiornare ed eliminare distribuzioni di calcolo gestite.
  • Utente Foundry per chiamare la distribuzione con Microsoft Entra ID dal playground, tramite l'SDK o l'API REST. Per le definizioni dei ruoli, vedere Controllo degli accessi in base al ruolo in Foundry.
• Quota di calcolo gestito con GPU disponibile nella tua sottoscrizione di Azure per la famiglia di acceleratori selezionata. La quota di calcolo gestita di Foundry è separata dalla quota di macchine virtuali Azure e usa un percorso di richiesta diverso. Nel portale di Foundry passare a Gestisci>quota> dirichiesta dicalcolo gestitaper controllare l'allocazione > corrente o richiedere un aumento. Per indicazioni dettagliate, vedere Richiedere altre quote.

Distribuire un modello Hugging Face

Trovare e selezionare il modello

1. Nel portale Foundry, vai a Scopri nella barra di navigazione superiore, quindi seleziona Modelli nel riquadro sinistro.

2. Nel filtro Raccolte, seleziona Hugging Face per visualizzare i modelli disponibili pubblicati da Hugging Face.

3. Selezionare il filtro Disponibile nel Project per visualizzare solo i modelli attualmente disponibili nella project e nell'area.

4. Nel filtro Opzioni di distribuzioneselezionare Calcolo gestito per visualizzare solo i modelli disponibili per la distribuzione di calcolo gestita.

5. Selezionare un riquadro del modello per aprire la scheda dei dettagli del modello.

Configurare e distribuire

1. Nella scheda dei dettagli del modello selezionare Distribuisci. Questa azione apre il pannello di configurazione della distribuzione con selezioni predefinite.

2. Immettere un nome di distribuzione. È necessario un nome di distribuzione e non può contenere un punto (.). Usare solo caratteri alfanumerici, caratteri di sottolineatura e trattini e usare da 2 a 64 caratteri.

3. Selezionare il modello Distribuzione.

4. Selezionare il tipo di acceleratore che corrisponde ai requisiti di prestazioni e dimensioni del modello. Il portale prefiltra le opzioni disponibili per acceleratori compatibili.

5. Specificare il numero di istanze:

   • Usare 1 istanza per il test e lo sviluppo.
   • Usare 2 o più istanze per la produzione per garantire la disponibilità e gestire i picchi di traffico.

6. Seleziona Distribuisci. Il processo di distribuzione richiede in genere alcuni minuti. Al termine, il portale visualizza la pagina dei dettagli della distribuzione con:

   • URL dell'endpoint per richiamare il modello
   • Chiavi API per l'autenticazione
   • Stato e log della distribuzione

Eseguire la distribuzione con Python SDK (alternativa)

Se si preferisce l'automazione, usare l'SDK di gestione Python per creare la stessa distribuzione di calcolo gestita. Sostituisci i segnaposto con i valori del tuo abbonamento e del modello selezionato.

Per ottenere i valori di MODEL e TEMPLATE, aprire la scheda dei dettagli del modello e la procedura guidata di distribuzione nel portale di Foundry, quindi copiare gli ID completi degli asset del registro.

python -m pip install --upgrade azure-identity azure-mgmt-cognitiveservices openai

from azure.identity import DefaultAzureCredential
from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient

SUBSCRIPTION_ID = "<your-subscription-id>"
RESOURCE_GROUP = "<your-resource-group>"
ACCOUNT_NAME = "<your-foundry-account>"
DEPLOYMENT_NAME = "<your-deployment-name>"

MODEL = "azureml://registries/azure-huggingface/models/<model-id>/versions/<version>"
TEMPLATE = "azureml://registries/azure-huggingface/deploymenttemplates/<template-id>/labels/<label>"

client = CognitiveServicesManagementClient(
   DefaultAzureCredential(), SUBSCRIPTION_ID
)

deployment = client.managed_compute_deployments.begin_create_or_update(
   resource_group_name=RESOURCE_GROUP,
   account_name=ACCOUNT_NAME,
   deployment_name=DEPLOYMENT_NAME,
   resource={
      "sku": {"name": "GlobalManagedCompute", "capacity": 1},
      "properties": {
         "model": MODEL,
         "deploymentTemplate": TEMPLATE,
         "acceleratorType": "<accelerator-type>",
         "versionUpgradeOption": "OnceNewDefaultVersionAvailable",
      },
   },
).result()

print(f"State: {deployment.properties.provisioning_state}")
print(f"ID: {deployment.id}")

Verificare e usare la distribuzione

Al termine della distribuzione, convalidare l'endpoint prima di integrarlo nell'applicazione:

1. Verificare che lo stato della distribuzione sia Completato nella pagina dei dettagli della distribuzione.

2. Eseguire un'inferenza di test dalla pagina dei dettagli della distribuzione per verificare che il modello restituisca una risposta corretta per il tipo di attività.

3. Se la distribuzione non riesce, controllare i log di distribuzione. Verificare quindi la quota gpu e la disponibilità a livello di area per il modello e il tipo di acceleratore selezionati. La quota di calcolo gestita di Foundry è separata dalla quota di macchine virtuali Azure. Per i controlli delle quote e aumentare le richieste, vedere Richiedere altre quote.

Richiamare l'endpoint dall'applicazione

Dopo che la verifica è andata a buon fine, invoca la distribuzione tramite l'URL di base dell'endpoint unificato di Foundry:

https://<account>.services.ai.azure.com/openai/v1/

Nel corpo delle richieste, impostare il campo model sul nome della distribuzione, non sull'ID del modello.

Python OpenAI SDK con Microsoft Entra ID

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import OpenAI

ACCOUNT_NAME = "<your-foundry-account>"
DEPLOYMENT_NAME = "<your-deployment-name>"

token_provider = get_bearer_token_provider(
   DefaultAzureCredential(),
   "https://cognitiveservices.azure.com/.default",
)

client = OpenAI(
   base_url=f"https://{ACCOUNT_NAME}.services.ai.azure.com/openai/v1",
   api_key=token_provider,
)

response = client.chat.completions.create(
   model=DEPLOYMENT_NAME,
   messages=[{"role": "user", "content": "What is the capital of Nigeria?"}],
)

print(response.choices[0].message.content)

Python OpenAI SDK con chiave API

from azure.identity import DefaultAzureCredential
from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient
from openai import OpenAI

SUBSCRIPTION_ID = "<your-subscription-id>"
RESOURCE_GROUP = "<your-resource-group>"
ACCOUNT_NAME = "<your-foundry-account>"
DEPLOYMENT_NAME = "<your-deployment-name>"

mgmt = CognitiveServicesManagementClient(
   DefaultAzureCredential(), SUBSCRIPTION_ID
)
api_key = mgmt.accounts.list_keys(RESOURCE_GROUP, ACCOUNT_NAME).key1

client = OpenAI(
   base_url=f"https://{ACCOUNT_NAME}.services.ai.azure.com/openai/v1",
   api_key=api_key,
)

response = client.chat.completions.create(
   model=DEPLOYMENT_NAME,
   messages=[{"role": "user", "content": "What is the capital of Nigeria?"}],
)

print(response.choices[0].message.content)

Testare l'endpoint con cURL

Usare una richiesta cURL per convalidare la distribuzione all'esterno del portale. Sostituire l'URL dell'endpoint, la chiave API e il nome del modello con i valori di distribuzione.

curl -X POST "https://<your-foundry-account>.services.ai.azure.com/openai/v1/chat/completions" \
   -H "Content-Type: application/json" \
   -H "api-key: <your-api-key>" \
   -d '{
      "messages": [{"role": "user", "content": "What is the capital of Nigeria?"}],
      "temperature": 0.2,
      "max_tokens": 256,
      "model": "<your-deployment-name>"
   }'

Una risposta con esito positivo restituisce HTTP 200 e include choices[0].message.content.

Come funzionano i modelli Hugging Face in Foundry

I modelli Hugging Face in Foundry usano il percorso di distribuzione di calcolo gestito, che crea un endpoint dedicato basato su GPU per l'inferenza.

Ad alto livello:

• Trovi i modelli Hugging Face nel catalogo dei modelli.
• È possibile filtrare in base ai modelli che possono essere distribuiti nel progetto corrente.
• Si distribuisce un modello supportato; Foundry effettua il provisioning di istanze di calcolo GPU dedicate ed espone un endpoint.
• Si invoca la distribuzione tramite l'endpoint utilizzando le tariffe di calcolo gestito di Foundry.

Il calcolo gestito offre istanze di calcolo GPU dedicate, accesso all'inferenza tramite endpoint e fatturazione tramite il modello tariffario di Managed Compute di Foundry Models. Per i dettagli attuali sulle tariffe e sulla fatturazione, consultare Prezzi di Foundry Models - Calcolo gestito.

Per i concetti relativi alla distribuzione, vedere Calcolo gestito in Microsoft Foundry.

Hosting dei dati e pesi del modello

Per i modelli Hugging Face disponibili tramite Foundry, i pesi del modello vengono archiviati in Azure. Questo comportamento è diverso da quello dei modelli pubblicati da Hugging Face in Foundry (classic) e Azure Machine Learning, nei quali i pesi del modello vengono scaricati da Hugging Face Hub al momento della distribuzione.

Scopri i modelli Hugging Face distribuibili

Nel catalogo dei modelli, usa i filtri dei modelli per limitare la ricerca ai modelli pubblicati da Hugging Face. Per visualizzare i modelli che puoi distribuire subito, attiva Disponibili nel progetto.

Quando si abilita questo filtro, il catalogo mostra solo i modelli attualmente distribuibili nel contesto del progetto selezionato. Un modello viene visualizzato in questa visualizzazione filtrata quando tutte le condizioni seguenti sono vere:

• Il modello si trova nel catalogo dei modelli Foundry.
• La sottoscrizione dispone di una quota di calcolo gestito con GPU disponibile per almeno un tipo di acceleratore compatibile.
• Il modello è disponibile nell'area Azure del progetto.

Se non viene visualizzato un modello previsto, verificare la copertura della quota e dell'area in Foundry prima di passare a Foundry (versione classica).

Modelli supportati

Foundry supporta i modelli Hugging Face che soddisfano tutti i criteri seguenti:

• Deve avere il tag Transformers, Diffusers o Sentence-Transformers su Hugging Face Hub.
• Avere una licenza permissiva (ad esempio Apache 2.0, MIT o OpenRAIL-M) che consente l'uso commerciale e la ridistribuzione.
• Rendere disponibile un'attività supportata come chat-completion, image-to-text o embeddings.
• I pesi del modello sono nel formato Safetensors e il modello non richiede trust_remote_code.

Requisiti di sicurezza

Prima della distribuzione, tutti i modelli nella raccolta Hugging Face subiscono l'analisi della sicurezza obbligatoria:

• Analisi malware: Il processo analizza i modelli per identificare malware incorporato o file binari dannosi.
• Ispezione del codice: Il processo non consente modelli che richiedono trust_remote_code=True a meno che Hugging Face non li verifichi in modo esplicito o provengano da organizzazioni attendibili.
• Applicazione del formato sicuro: i pesi del modello devono essere in formato Safetensors per eliminare i rischi associati ai formati basati su pickle.
• Controlli di convalida: Il processo testa tutte le combinazioni di modelli, runtime e acceleratori per la conformità e le prestazioni dell'API prima della pubblicazione.

Per ulteriori dettagli, consulta la documentazione sulla sicurezza di Hugging Face.

Scegliere Foundry o Foundry (versione classica)

Usare la tabella seguente per determinare quale esperienza si adatta allo scenario:

Quando un modello non è disponibile in Foundry

Alcuni modelli pubblicati da Hugging Face potrebbero non essere attualmente disponibili in Foundry. In questo caso, nella scheda del modello viene visualizzato un pulsante Continua in Foundry (versione classica). Selezionarlo per aprire l'esperienza equivalente in Foundry (versione classica).

Foundry (classico) rimane l'opzione di riserva per i modelli pubblicati da Hugging Face che non sono disponibili nell'attuale esperienza di progetto di Foundry. Per altri dettagli sulle funzionalità di distribuzione di calcolo gestite nell'esperienza foundry corrente, vedere Calcolo gestito in Microsoft Foundry. È anche possibile richiedere un modello tramite Hugging Face nel portale di feedback di Microsoft Foundry.

Per comprendere le differenze tra le esperienze correnti e classiche, vedere Eseguire la migrazione dal portale di Foundry (versione classica).

FAQ

I modelli gated Hugging Face sono disponibili in Foundry?

No. I modelli Gated Hugging Face non sono disponibili in Foundry. I modelli gestiti richiedono l'autenticazione e l'approvazione dell'autore del modello prima dell'uso. Usare Foundry (versione classica) per il supporto dei modelli a controllo. Vedere Distribuire modelli da Hugging Face Hub al calcolo gestito (versione classica).

È possibile distribuire i modelli Hugging Face usando il calcolo della CPU con calcolo gestito?

Le distribuzioni di calcolo gestite per i modelli Hugging Face usano acceleratori GPU di livello aziendale. Se è necessario un percorso di distribuzione diverso, prendere in considerazione Foundry (versione classica).

Cosa devo fare se il modello desiderato non è disponibile in Foundry?

Vedere Quando un modello non è disponibile in Foundry.

Come è possibile trovare solo i modelli che sono ora distribuibili?

Nel catalogo dei modelli impostare il filtro Raccolte su Hugging Face, impostare Opzioni di distribuzione su Calcolo gestito e quindi abilitare il filtro Disponibile nel Project per visualizzare solo i modelli attualmente distribuibili nella project e nell'area.

Contenuti correlati

• Calcolo gestito in Microsoft Foundry
• Distribuire modelli con calcolo gestito (versione classica)
• Modelli di fonderia provenienti da partner e comunità
• Panoramica della distribuzione per i modelli di Microsoft Foundry
• Distribuire modelli da Hugging Face Hub al calcolo gestito (versione classica)
• Eseguire la migrazione dal portale Foundry (classico)