CLI di accesso a Hugging Face: Il tuo ponte verso i modelli AI
Di Jake Morrison, appassionato di automazione AI
Il mondo dell’IA sta evolvendo rapidamente e l’accesso a modelli potenti è essenziale per rimanere all’avanguardia. Hugging Face è diventato un centro centrale per l’apprendimento automatico, offrendo un ampio repertorio di modelli pre-addestrati, dataset e strumenti. Anche se la loro interfaccia web è eccellente, per molti sviluppatori AI e appassionati di automazione, interagire con Hugging Face direttamente dall’interfaccia della riga di comando (CLI) è fondamentale. Questo articolo ti guiderà attraverso i passaggi pratici per utilizzare il CLI di accesso a Hugging Face, rendendo i tuoi flussi di lavoro IA più fluidi ed efficienti.
Perché usare il CLI di accesso a Hugging Face?
Per l’automazione, gli script e le operazioni lato server, il CLI è il re. Quando distribuisci modelli in produzione, esegui compiti di addestramento su server remoti o integri modelli Hugging Face in pipeline complesse, fare affidamento su un browser web non è pratico. Il CLI di accesso a Hugging Face fornisce un modo sicuro e programmabile per autenticare i tuoi script e le tue applicazioni, dando loro accesso a modelli privati, dataset e funzionalità dell’API.
Pensa a questi scenari:
* **Distribuzione automatizzata di modelli:** Il tuo pipeline CI/CD deve distribuire un modello fine-tuning nel tuo repository privato di Hugging Face.
* **Inferenza batch:** Stai eseguendo uno script che elabora migliaia di input utilizzando un modello Hugging Face specifico, e questo modello richiede autenticazione.
* **Addestramento su istanze cloud:** Il tuo script di addestramento su un’istanza AWS EC2 deve scaricare un dataset privato da Hugging Face prima di iniziare.
* **Download di modelli automatici:** Vuoi scrivere uno script per tirare automaticamente l’ultima versione di un modello per lo sviluppo locale.
In tutti questi casi, il CLI di accesso a Hugging Face è lo strumento di cui hai bisogno.
Prerequisiti: Cosa serve prima di iniziare
Prima di esplorare i comandi, assicurati di avere i seguenti elementi configurati:
* **Python installato:** Le librerie Hugging Face sono basate su Python. Avrai bisogno di Python 3.7 o più recente.
* **Gestore di pacchetti `pip`:** Questo di solito viene fornito con Python.
* **Account Hugging Face:** Hai bisogno di un account su huggingface.co. Se non ne hai uno, iscriviti gratuitamente.
* **Connessione a Internet:** Per connetterti a Hugging Face.
Passo 1: Installare la libreria `huggingface_hub`
Il cuore dell’interazione con Hugging Face da Python e il CLI è la libreria `huggingface_hub`. Se non l’hai installata, apri il tuo terminale o prompt dei comandi e esegui:
“`bash
pip install huggingface_hub
“`
Questo comando scarica e installa i componenti necessari. È consigliabile farlo in un ambiente virtuale per mantenere le dipendenze del progetto isolate.
“`bash
# Esempio utilizzando un ambiente virtuale
python -m venv .venv
source .venv/bin/activate # Su Windows: .venv\Scripts\activate
pip install huggingface_hub
“`
Una volta installato, sei pronto per utilizzare il CLI di accesso a Hugging Face.
Passo 2: Genera il tuo token di accesso Hugging Face
Il CLI di accesso a Hugging Face non utilizza direttamente il tuo nome utente e password abituali per l’autenticazione. Invece, si basa su token API (noti anche come token di accesso o token di autenticazione). Questi token sono sicuri, revocabili e ti consentono di fornire permessi specifici.
1. **Accedi a Hugging Face:** Vai su huggingface.co e accedi con il tuo account.
2. **Accedi alle impostazioni:** Clicca sulla tua foto del profilo nell’angolo in alto a destra, poi seleziona “Impostazioni.”
3. **Vai ai token di accesso:** Nel menu a sinistra, clicca su “Token di accesso.”
4. **Crea un nuovo token:** Clicca sul pulsante “Nuovo token”.
5. **Configura il tuo token:**
* **Nome:** Dai al tuo token un nome descrittivo (ad esempio, “Token di automazione CLI,” “Il mio token server”). Questo ti aiuterà a ricordare a cosa serve.
* **Ruolo:** Questo è cruciale.
* **`read`:** Consente di scaricare modelli e dataset pubblici, e di leggere informazioni. Questo è spesso sufficiente per script di inferenza.
* **`write`:** Consente di caricare modelli, dataset e spazi, oltre ai permessi `read`. Scegli questo se i tuoi script devono scaricare contenuti.
* **`admin`:** Controllo totale. Da usare con cautela.
* Per la maggior parte delle attività di automazione, `read` o `write` saranno sufficienti. Inizia con il ruolo meno permissivo necessario.
6. **Genera e copia:** Clicca su “Genera un token.” Hugging Face mostrerà il tuo nuovo token. **Copia immediatamente questo token!** Per motivi di sicurezza, verrà mostrato solo una volta. Se lo perdi, dovrai generarne uno nuovo.
Tieni questo token al sicuro. Trattalo come una password. Non hardcodarlo direttamente nei repository pubblici e non condividerlo inutilmente.
Passo 3: Usare il CLI di accesso a Hugging Face
Ora che hai il tuo token, puoi utilizzare il CLI di accesso a Hugging Face per autenticare il tuo ambiente. Apri il tuo terminale o prompt dei comandi.
Il comando principale per l’autenticazione è `huggingface-cli login`.
“`bash
huggingface-cli login
“`
Quando esegui questo comando, il CLI ti chiederà di incollare il tuo token:
“`
_| _| _| _| _|_|_| _|_|_| _|_|_| _| _|
_|_| _|_| _| _| _| _| _| _| _| _|_| _|
_|_|_|_| _|_|_| _| _| _| _| _| _| _| _| _|_|
_| _| _| _| _| _| _| _| _| _| _|
_| _| _|_| _|_| _|_|_| _|_|_| _|_|_| _| _|
Per ulteriori informazioni su come ottenere un token, visita https://huggingface.co/docs/hub/security-tokens
Token :
“`
Incolla qui il tuo token di accesso copiato e premi Invio.
Se ha successo, vedrai un messaggio come:
“`
Il token è stato salvato in /home/youruser/.cache/huggingface/token
Accesso riuscito
“`
Questo messaggio conferma che il tuo token è stato salvato in un file cache locale. Il CLI di accesso a Hugging Face memorizza questo token in modo sicuro nella directory personale del tuo utente (ad esempio, `~/.cache/huggingface/token` su Linux/macOS, o `C:\Users\YourUser\.cache\huggingface\token` su Windows). Le operazioni successive che utilizzeranno `huggingface_hub` nel tuo ambiente utilizzeranno automaticamente questo token memorizzato per l’autenticazione.
Verificare la tua connessione
Puoi verificare di essere connesso tentando di accedere a una risorsa riservata o semplicemente eseguendo:
“`bash
huggingface-cli whoami
“`
Questo comando mostrerà informazioni sull’utente associato al token attualmente connesso, confermando il tuo stato di autenticazione.
Metodi di autenticazione alternativi (oltre a `huggingface-cli login`)
Sebbene `huggingface-cli login` sia il metodo più comune per autenticarsi durante le sessioni interattive e di sviluppo, ci sono altri metodi utili per scenari specifici.
1. Utilizzo di variabili d’ambiente
Per ambienti non interattivi come pipeline CI/CD, container Docker o funzioni cloud, passare il token tramite una variabile d’ambiente è spesso preferibile. Questo evita di scrivere il token in un file nell’ambiente temporaneo.
Definisci la variabile d’ambiente `HF_TOKEN` prima di eseguire il tuo script Python o il tuo comando:
“`bash
export HF_TOKEN=”hf_YOUR_ACTUAL_TOKEN_HERE”
# Ora esegui il tuo script o qualsiasi comando huggingface_hub
python my_model_script.py
“`
Su Windows:
“`cmd
set HF_TOKEN=”hf_YOUR_ACTUAL_TOKEN_HERE”
python my_model_script.py
“`
La libreria `huggingface_hub` e i comandi CLI di accesso a Hugging Face controllano automaticamente la variabile d’ambiente `HF_TOKEN` se non viene trovato alcun token nella cache locale.
2. Passare il token direttamente in Python
Se hai bisogno di un controllo molto preciso o se operi in un ambiente dove definire variabili d’ambiente o utilizzare il login CLI non è realizzabile, puoi passare il token direttamente alle funzioni `huggingface_hub` nel tuo codice Python.
“`python
from huggingface_hub import HfApi
# AVVERTENZA: Evita di codificare i token direttamente nel codice di produzione.
# Utilizza invece variabili d’ambiente o un sistema di gestione della configurazione sicuro.
token = “hf_YOUR_ACTUAL_TOKEN_HERE”
api = HfApi(token=token)
# Esempio: Elencare i tuoi modelli privati
private_models = api.list_models(author=”your_username”, private=True)
for model in private_models:
print(model.modelId)
# Esempio: Scaricare un modello privato
from transformers import AutoModelForSequenceClassification, AutoTokenizer
model_name = “your_username/your_private_model”
tokenizer = AutoTokenizer.from_pretrained(model_name, token=token)
model = AutoModelForSequenceClassification.from_pretrained(model_name, token=token)
“`
Nota l’argomento `token=token` nel costruttore `HfApi` e le chiamate `from_pretrained`. Questo indica esplicitamente alle funzioni quale token utilizzare per questa specifica operazione.
Casi d’uso comuni dopo il CLI di accesso di Hugging Face
Una volta che ti sei autenticato con il CLI di accesso di Hugging Face, sblocchi una gamma di capacità potenti.
Download di modelli e set di dati privati
Se hai modelli o set di dati privati su Hugging Face, o se devi accedere a modelli ristretti che richiedono l’accettazione dei termini di utilizzo, l’autenticazione è obbligatoria.
“`python
from transformers import AutoModelForSequenceClassification, AutoTokenizer
# Supponiamo che tu abbia già eseguito ‘huggingface-cli login’ o impostato HF_TOKEN
model_name = “your_org/your_private_model” # O un modello ristretto come meta-llama/Llama-2-7b-hf
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)
print(f”Caricamento riuscito di {model_name}”)
“`
La funzione `from_pretrained` recupererà automaticamente il token memorizzato dal CLI di accesso di Hugging Face.
Download di modelli e set di dati
Se il tuo flusso di lavoro prevede di perfezionare modelli e poi inviarli su Hugging Face, avrai bisogno di un token con autorizzazioni `write`.
“`python
from transformers import AutoModelForSequenceClassification, AutoTokenizer
from datasets import Dataset
# Supponiamo che tu abbia affinato un modello e che tu abbia un tokenizer
# model = your_fine_tuned_model
# tokenizer = your_tokenizer
# Definisci l’ID del tuo deposito (ad esempio, “your_username/your_new_model”)
repo_id = “your_username/my-finetuned-model”
# Spingi il modello e il tokenizer
model.push_to_hub(repo_id)
tokenizer.push_to_hub(repo_id)
print(f”Modello e tokenizer inviati a {repo_id}”)
# Esempio per i set di dati
# my_dataset = Dataset.from_dict({“text”: [“hello”, “world”]})
# my_dataset.push_to_hub(“your_username/my-new-dataset”)
“`
Le metodologie `push_to_hub` utilizzeranno anche il token fornito dal CLI di accesso di Hugging Face.
Gestione dei tuoi token
Periodicamente, potrebbe essere necessario gestire i tuoi token d’accesso.
* **Revoca dei token:** Se un token è compromesso o non è più necessario, vai nelle impostazioni dei tuoi “Access Tokens” di Hugging Face e eliminalo. Questo invalida immediatamente il token.
* **Elenco dei token:** Dal CLI, non puoi elencare direttamente *tutti* i token del tuo account, ma puoi vedere quale token è attualmente attivo nel tuo ambiente utilizzando `huggingface-cli whoami`.
Risoluzione dei problemi comuni
A volte, le cose non vanno come previsto. Ecco alcuni problemi comuni e le loro soluzioni quando utilizzi il CLI di accesso di Hugging Face.
* **”Token non valido” o “Errore di autenticazione”:**
* **Errori di battitura:** Assicurati di aver copiado e incollato il token correttamente. Non ci sono spazi o caratteri aggiuntivi.
* **Token scaduto:** Anche se i token di Hugging Face non scadono generalmente per impostazione predefinita, assicurati che non sia stato revocato manualmente.
* **Ruolo errato:** Il ruolo del token (`read`, `write`) è sufficiente per l’operazione che stai cercando di effettuare? Ad esempio, un token `read` non può inviare modelli.
* **”Comando non trovato: huggingface-cli”:**
* **Installazione:** Assicurati che `huggingface_hub` sia installato (`pip install huggingface_hub`).
* **PATH:** Assicurati che la directory dei tuoi script Python sia nel PATH del tuo sistema. Se sei in un ambiente virtuale, attivalo.
* **”Accesso riuscito” ma ancora errori:**
* **Ambienti diversi:** Stai eseguendo il tuo script nello *stesso* ambiente in cui hai eseguito `huggingface-cli login`? Se cambi ambienti virtuali o sessioni SSH, il token potrebbe non essere recuperato automaticamente.
* **Precedenza delle variabili d’ambiente:** Se imposti anche `HF_TOKEN` come variabile d’ambiente, questo potrebbe sovrascrivere il token memorizzato.
* **Corruzione della cache:** In rari casi, il file di cache del token potrebbe essere corrotto. Puoi provare a eliminare il file (`~/.cache/huggingface/token`) e rilanciare `huggingface-cli login`.
* **Problemi di proxy:** Se sei dietro un proxy aziendale, potrebbe essere necessario configurare le impostazioni del proxy per `pip` e potenzialmente per `huggingface_hub` se ha problemi di connessione. Questo viene di solito effettuato tramite variabili d’ambiente come `HTTP_PROXY` e `HTTPS_PROXY`.
Migliori pratiche di sicurezza per il CLI di accesso di Hugging Face
* **Principio del minimo privilegio:** Crea sempre token con le autorizzazioni minime necessarie (`read` vs. `write`).
* **Nome dei token:** Dai nomi descrittivi ai tuoi token in modo da sapere a cosa servono.
* **Rotazione dei token:** Per applicazioni critiche, considera di ruotare i tuoi token periodicamente.
* **Variabili d’ambiente per la produzione:** Non codificare mai i token nel tuo codice, soprattutto in produzione. Utilizza variabili d’ambiente (`HF_TOKEN`) o un sistema di gestione dei segreti.
* **Archiviazione sicura:** Il CLI di accesso di Hugging Face memorizza il token nella directory di cache del tuo utente. Assicurati che questa directory sia protetta da permessi standard del file system.
* **Evita l’uso di root:** Non eseguire `huggingface-cli login` come utente root a meno che non sia assolutamente necessario, e comprendi le implicazioni in materia di sicurezza.
Conclusione
Il CLI di accesso di Hugging Face è uno strumento fondamentale per chiunque desideri integrare modelli e set di dati di Hugging Face nei propri flussi di lavoro automatizzati. Comprendendo come generare token API, utilizzare il comando `huggingface-cli login` e utilizzare metodi di autenticazione alternativi come le variabili d’ambiente, puoi semplificare i tuoi processi di sviluppo e distribuzione di IA. Adotta il CLI per la sua efficienza e potenza, e libera tutto il potenziale di Hugging Face nei tuoi progetti.
—
FAQ
Q1: A cosa serve il comando `huggingface-cli login`?
Il comando `huggingface-cli login` viene utilizzato per autenticare il tuo ambiente locale con Hugging Face Hub. Ti chiede un token d’accesso (che generi sul sito di Hugging Face) e poi memorizza in modo sicuro questo token in un file di cache locale. Questo consente ai tuoi script Python e alle altre operazioni di `huggingface_hub` di accedere a modelli privati, set di dati, o di effettuare azioni come inviare modelli senza dover reinserire il tuo token ogni volta.
Q2: Dove posso ottenere il token necessario per `huggingface-cli login`?
Generi il token dalle impostazioni del tuo account Hugging Face. Accedi a huggingface.co, vai nelle tue “Impostazioni,” poi naviga su “Access Tokens.” Clicca su “Nuovo token,” dagli un nome, seleziona il ruolo appropriato (ad esempio, `read` o `write`), e generalo. Non dimenticare di copiare il token immediatamente poiché viene visualizzato solo una volta.
Q3: Cosa fare se non voglio usare `huggingface-cli login`? Posso ancora autenticarmi?
Sì, hai alcune alternative. Per ambienti non interattivi come i pipeline CI/CD o i contenitori Docker, puoi definire la variabile d’ambiente `HF_TOKEN` con il tuo token d’accesso. La libreria `huggingface_hub` lo recupererà automaticamente. In alternativa, puoi passare l’argomento `token` direttamente alle funzioni `huggingface_hub` (ad esempio, `HfApi(token=”your_token”)` o `AutoTokenizer.from_pretrained(…, token=”your_token”)`) nel tuo codice Python, anche se generalmente ciò è meno raccomandato per motivi di sicurezza in produzione.
Q4: Il mio comando `huggingface-cli login` ha funzionato, ma il mio script non può ancora accedere a un modello privato. Cosa succede?
Ci sono diverse possibilità. Prima di tutto, assicurati che il token che hai utilizzato abbia le autorizzazioni corrette (ad esempio, un ruolo `read` per il download). In secondo luogo, controlla che il tuo script venga eseguito nello *stesso* ambiente (ad esempio, lo stesso ambiente virtuale o sessione utente) in cui hai eseguito `huggingface-cli login`. Se definisci anche la variabile d’ambiente `HF_TOKEN`, potrebbe sovrascrivere il token memorizzato nella cache, quindi controlla il suo valore. Infine, verifica l’ID del repository del modello per assicurarti che sia corretto e che il tuo account vi abbia accesso.
🕒 Published: