Hugging Face Login CLI: Il tuo accesso ai modelli AI
A cura di Jake Morrison, appassionato di automazione AI
Il mondo dell’AI si muove velocemente e accedere a modelli potenti è fondamentale per rimanere competitivi. Hugging Face è emerso come un hub centrale per il machine learning, offrendo un vasto repository di modelli pre-addestrati, dataset e strumenti. Sebbene la loro interfaccia web sia eccellente, per molti sviluppatori AI e appassionati di automazione, interagire con Hugging Face direttamente dalla console dei comandi (CLI) è essenziale. Questo articolo ti guiderà attraverso i passaggi pratici per utilizzare il login CLI di Hugging Face, rendendo i tuoi flussi di lavoro AI più fluidi ed efficienti.
Perché usare il Hugging Face Login CLI?
Per automazione, scripting e operazioni lato server, la CLI è il re. Quando stai distribuendo modelli in produzione, eseguendo lavori di addestramento su server remoti o integrando modelli di Hugging Face in pipeline complesse, fare affidamento su un browser web non è pratico. Il login CLI di Hugging Face fornisce un modo sicuro e programmatico per autenticare i tuoi script e le tue applicazioni, concedendo loro accesso a modelli privati, dataset e funzionalità API.
Pensa a questi scenari:
* **Distribuzione automatizzata dei modelli:** La tua pipeline CI/CD ha bisogno di inviare un modello finemente addestrato al tuo repository privato di Hugging Face.
* **Inferenza batch:** Stai eseguendo uno script che elabora migliaia di input utilizzando un modello specifico di Hugging Face, e quel 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 tramite script:** Vuoi scrivere uno script per scaricare automaticamente l’ultima versione di un modello per lo sviluppo locale.
In tutti questi casi, il login CLI di Hugging Face è lo strumento di cui hai bisogno.
Requisiti: Cosa ti serve prima di iniziare
Prima di esplorare i comandi, assicurati di avere quanto segue configurato:
* **Python installato:** Le librerie di Hugging Face sono basate su Python. Ti servirà Python 3.7 o più recente.
* **Gestore pacchetti `pip`:** Questo di solito viene fornito con Python.
* **Account Hugging Face:** Hai bisogno di un account su huggingface.co. Se non hai un account, registrati gratuitamente.
* **Connessione a Internet:** Per connetterti a Hugging Face.
Passo 1: Installa la libreria `huggingface_hub`
Il fulcro dell’interazione con Hugging Face da Python e dalla CLI è la libreria `huggingface_hub`. Se non ce l’hai installata, apri il tuo terminale o prompt dei comandi ed esegui:
“`bash
pip install huggingface_hub
“`
Questo comando scarica e installa i componenti necessari. È buona pratica farlo all’interno di un ambiente virtuale per mantenere isolate le dipendenze del tuo progetto.
“`bash
# Esempio di utilizzo di 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 usare il login CLI di Hugging Face.
Passo 2: Genera il tuo token di accesso Hugging Face
Il login CLI di Hugging Face non utilizza direttamente il tuo nome utente e la tua password per l’autenticazione. Invece, si basa su token API (noto anche come token di accesso o token di autenticazione). Questi token sono sicuri, revocabili e ti permettono di concedere autorizzazioni specifiche.
1. **Accedi a Hugging Face:** Vai su huggingface.co e accedi con il tuo account.
2. **Naviga nelle Impostazioni:** Clicca sulla tua foto 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,” “Token del Mio Server”). Questo ti aiuterà a ricordarne l’uso.
* **Ruolo:** Questo è cruciale.
* **`read`:** Consente di scaricare modelli e dataset pubblici, e leggere informazioni. Questo è spesso sufficiente per gli script di inferenza.
* **`write`:** Consente di caricare modelli, dataset e spazi, oltre ad avere permessi `read`. Scegli questo se i tuoi script necessitano di caricare contenuti.
* **`admin`:** Controllo completo. Usa con cautela.
* Per la maggior parte dei compiti 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 un altro.
Conserva questo token in modo sicuro. Trattalo come una password. Non codificarlo direttamente nei repository pubblici o condividerlo inutilmente.
Passo 3: Utilizzare il login CLI di Hugging Face
Ora che hai il tuo token, puoi usare il login CLI di 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, la CLI ti chiederà di incollare il tuo token:
“`
_| _| _| _| _|_|_| _|_|_| _|_|_| _| _|
_|_| _|_| _| _| _| _| _| _| _| _|_| _|
_|_|_|_| _|_|_| _| _| _| _| _| _| _| _| _|_|
_| _| _| _| _| _| _| _| _| _| _|
_| _| _|_| _|_| _|_|_| _|_|_| _|_|_| _| _|
Per ulteriori informazioni su come ottenere un token, vai su https://huggingface.co/docs/hub/security-tokens
Token:
“`
Incolla qui il tuo token di accesso copiato e premi Invio.
Se l’operazione ha successo, vedrai un messaggio simile a:
“`
Il token è stato salvato in /home/youruser/.cache/huggingface/token
Accesso riuscito
“`
Questo messaggio conferma che il tuo token è stato salvato in un file di cache locale. Il login CLI di Hugging Face memorizza questo token in modo sicuro nella directory home dell’utente (ad esempio, `~/.cache/huggingface/token` su Linux/macOS, o `C:\Users\YourUser\.cache\huggingface\token` su Windows). Le operazioni successive che utilizzano `huggingface_hub` nel tuo ambiente utilizzeranno automaticamente questo token memorizzato per l’autenticazione.
Verificare il tuo accesso
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 modo più comune per autenticarsi in sessioni interattive e per lo sviluppo, ci sono altri metodi utili per scenari specifici.
1. Utilizzo di variabili d’ambiente
Per ambienti non interattivi come pipeline CI/CD, contenitori 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 effimero.
Imposta la variabile d’ambiente `HF_TOKEN` prima di eseguire il tuo script Python o 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 del login CLI di Hugging Face controllano automaticamente la variabile d’ambiente `HF_TOKEN` se non si trova alcun token nella cache locale.
2. Passare il token direttamente in Python
Se hai bisogno di un controllo molto dettagliato o stai operando in un ambiente in cui impostare variabili d’ambiente o utilizzare il login CLI non è fattibile, puoi passare il token direttamente alle funzioni di `huggingface_hub` nel tuo codice Python.
“`python
from huggingface_hub import HfApi
# ATTENZIONE: Evita di inserire direttamente i token nel codice di produzione.
# Usa variabili d’ambiente o un sistema di gestione delle configurazioni sicuro invece.
token = “hf_YOUR_ACTUAL_TOKEN_HERE”
api = HfApi(token=token)
# Esempio: Elenca i tuoi modelli privati
private_models = api.list_models(author=”your_username”, private=True)
for model in private_models:
print(model.modelId)
# Esempio: Scarica 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 nelle chiamate `from_pretrained`. Questo indica esplicitamente alle funzioni quale token utilizzare per quella specifica operazione.
Utilizzi comuni dopo il login CLI di Hugging Face
Una volta autenticato con il login CLI di Hugging Face, sblocchi una gamma di capacità potenti.
Scaricare modelli e dataset privati
Se hai modelli o dataset privati su Hugging Face, o se hai bisogno di accedere a modelli riservati che richiedono l’accettazione di termini, l’autenticazione è obbligatoria.
“`python
from transformers import AutoModelForSequenceClassification, AutoTokenizer
# Supponendo che tu abbia già eseguito ‘huggingface-cli login’ o impostato HF_TOKEN
model_name = “your_org/your_private_model” # O un modello gated come meta-llama/Llama-2-7b-hf
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)
print(f”Caricamento di {model_name} avvenuto con successo”)
“`
La funzione `from_pretrained` prenderà automaticamente il token salvato dal CLI di accesso di Hugging Face.
Caricamento di Modelli e Dataset
Se il tuo flusso di lavoro prevede il fine-tuning dei modelli e poi la loro pubblicazione su Hugging Face, avrai bisogno di un token con permessi di `scrittura`.
“`python
from transformers import AutoModelForSequenceClassification, AutoTokenizer
from datasets import Dataset
# Supponendo che tu abbia fine-tunato un modello e abbia un tokenizer
# model = your_fine_tuned_model
# tokenizer = your_tokenizer
# Definisci il tuo repository ID (ad esempio, “your_username/your_new_model”)
repo_id = “your_username/my-finetuned-model”
# Pubblica il modello e il tokenizer
model.push_to_hub(repo_id)
tokenizer.push_to_hub(repo_id)
print(f”Modello e tokenizer pubblicati in {repo_id}”)
# Esempio per dataset
# my_dataset = Dataset.from_dict({“text”: [“hello”, “world”]})
# my_dataset.push_to_hub(“your_username/my-new-dataset”)
“`
I metodi `push_to_hub` utilizzeranno anche il token fornito dal CLI di accesso di Hugging Face.
Gestire i Tuoi Token
Periodicamente, potresti dover gestire i tuoi token di accesso.
* **Revoca Token:** Se un token è compromesso o non è più necessario, vai nelle impostazioni “Token di Accesso” di Hugging Face e cancellalo. Questo invalida immediatamente il token.
* **Elenco Token:** Dal CLI, non puoi elencare *tutti* i tuoi token dal tuo account, ma puoi vedere quale token è attualmente attivo nel tuo ambiente usando `huggingface-cli whoami`.
Risoluzione di Problemi Comuni
A volte le cose non vanno come previsto. Ecco alcuni problemi comuni e le loro soluzioni quando si utilizza il CLI di accesso di Hugging Face.
* **”Token non valido” o “Errore di autenticazione”:**
* **Errori di battitura:** Controlla che tu abbia copiato e incollato correttamente il token. Non ci devono essere spazi o caratteri extra.
* **Token scaduto:** Sebbene i token di Hugging Face di solito non scadano 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 eseguire? Ad esempio, un token `read` non può pubblicare modelli.
* **”Comando non trovato: huggingface-cli”:**
* **Installazione:** Assicurati che `huggingface_hub` sia installato (`pip install huggingface_hub`).
* **PATH:** Controlla che la directory dei tuoi script Python sia nel PATH del tuo sistema. Se sei in un ambiente virtuale, attivalo.
* **”Login riuscito” ma si verificano ancora errori:**
* **Ambientazioni Diverse:** Stai eseguendo il tuo script nello *stesso* ambiente dove hai eseguito `huggingface-cli login`? Se cambi ambienti virtuali o sessioni SSH, il token potrebbe non essere automaticamente riconosciuto.
* **Precedenza delle Variabili Ambientali:** Se stai anche impostando `HF_TOKEN` come variabile ambientale, quella potrebbe avere la precedenza sul token memorizzato.
* **Corruzione della Cache:** In rari casi, il file della cache del token potrebbe diventare corrotto. Puoi provare a eliminare il file (`~/.cache/huggingface/token`) ed eseguire nuovamente `huggingface-cli login`.
* **Problemi di Proxy:** Se sei dietro un proxy aziendale, potresti dover configurare le impostazioni del proxy per `pip` e eventualmente per `huggingface_hub` se sta riscontrando problemi di connessione. Questo di solito avviene tramite variabili ambientali come `HTTP_PROXY` e `HTTPS_PROXY`.
Pratiche di Sicurezza Consigliate per il CLI di Accesso di Hugging Face
* **Minima Privilegi:** Crea sempre token con i permessi minimi necessari (`read` vs. `write`).
* **Nominare i Token:** Dai ai tuoi token nomi descrittivi in modo da sapere a cosa servono.
* **Ruota i Token:** Per applicazioni critiche, considera di ruotare i tuoi token periodicamente.
* **Variabili Ambientali per la Produzione:** Non scrivere mai i token nel tuo codice, specialmente in produzione. Usa variabili ambientali (`HF_TOKEN`) o un sistema di gestione dei segreti.
* **Store Sicuro:** Il CLI di accesso di Hugging Face memorizza il token nella directory della cache del tuo utente. Assicurati che questa directory sia protetta da normali permessi del file system.
* **Evita Root:** Non eseguire `huggingface-cli login` come utente root a meno che non sia assolutamente necessario, e comprendi le implicazioni di sicurezza.
Conclusione
Il CLI di accesso di Hugging Face è uno strumento fondamentale per chiunque desideri integrare modelli e dataset di Hugging Face nei propri flussi di lavoro automatizzati. Comprendendo come generare token API, usare il comando `huggingface-cli login` e utilizzare metodi alternativi di autenticazione come le variabili ambientali, puoi semplificare i tuoi processi di sviluppo e distribuzione dell’AI. Abbraccia il CLI per la sua efficienza e potenza, e sblocca il pieno 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 di accesso (che generi sul sito di Hugging Face) e poi salva questo token in modo sicuro in un file di cache locale. Questo consente ai tuoi script Python e ad altre operazioni di `huggingface_hub` di accedere a modelli, dataset privati o di eseguire azioni come pubblicare modelli senza dover reinserire il tuo token ogni volta.
Q2: Dove posso ottenere il token necessario per `huggingface-cli login`?
Puoi generare il token dalle impostazioni del tuo account Hugging Face. Accedi a huggingface.co, vai su “Impostazioni”, poi naviga a “Token di Accesso.” Clicca su “Nuovo token,” dai un nome, seleziona il ruolo appropriato (ad esempio, `read` o `write`) e generalo. Ricorda di copiare il token immediatamente poiché viene mostrato solo una volta.
Q3: E se non voglio usare `huggingface-cli login`? Posso comunque autenticarmi?
Sì, hai un paio di alternative. Per ambienti non interattivi come pipeline CI/CD o contenitori Docker, puoi impostare la variabile ambientale `HF_TOKEN` con il tuo token di accesso. La libreria `huggingface_hub` la riconoscerà automaticamente. In alternativa, puoi passare direttamente l’argomento `token` alle funzioni di `huggingface_hub` (ad esempio, `HfApi(token=”your_token”)` o `AutoTokenizer.from_pretrained(…, token=”your_token”)`) nel tuo codice Python, anche se in generale ciò è meno raccomandato per motivi di sicurezza in produzione.
Q4: Il mio `huggingface-cli login` ha funzionato, ma il mio script non riesce ancora ad accedere a un modello privato. Cosa c’è di sbagliato?
Ci sono alcune possibilità. Prima di tutto, assicurati che il token utilizzato abbia i permessi corretti (ad esempio, un ruolo `read` per il download). In secondo luogo, verifica che il tuo script sia in esecuzione nello *stesso* ambiente (ad esempio, nello stesso ambiente virtuale o sessione utente) in cui hai eseguito `huggingface-cli login`. Se stai anche impostando la variabile ambientale `HF_TOKEN`, potrebbe sovrascrivere il token memorizzato, quindi controlla il suo valore. Infine, controlla attentamente l’ID del repository del modello per assicurarti che sia corretto e che il tuo account abbia accesso a esso.
🕒 Published: