Diese Anleitung basiert auf der Hugging Face CLI ab Version 0.34.4. In dieser Version wird die alte Syntax huggingface-cli durch den neuen Befehl hf ersetzt. Ich habe diese Gedankenstütze erstellt, um eine kurze und übersichtliche Referenz zur Hugging Face CLI zu haben. Statt in der offiziellen Dokumentation suchen zu müssen, finde ich hier die wichtigsten Befehle, Beschreibungen und Beispiele auf einen Blick.
Was ist Hugging Face?
Hugging Face ist eine Plattform für maschinelles Lernen. Im Mittelpunkt steht der Hugging Face Hub, ein öffentlicher und privater Speicherort für KI-Modelle, Datensätze und Anwendungen (Spaces). Entwicklerinnen und Entwickler können dort Modelle teilen, herunterladen und weiterverwenden. Neben dem Hub bietet Hugging Face auch Bibliotheken wie transformers, datasets und diffusers, die den praktischen Einsatz von KI-Modellen erleichtern. Der Hub dient damit sowohl als Marktplatz als auch als Infrastruktur für gemeinschaftliche Entwicklung.
Was ist die Hugging Face CLI?
Die Hugging Face CLI ist ein Kommandozeilenwerkzeug, mit dem du direkt auf den Hugging Face Hub zugreifen kannst. Du steuerst damit Anmeldung, Download, Upload und Verwaltung von Repositories für Modelle, Datensätze und Spaces. Die CLI nutzt intern die Python-Bibliothek huggingface_hub. Alles, was du mit dieser Bibliothek tun kannst, lässt sich in vielen Fällen auch skriptfähig mit der CLI erledigen.
| hf-Befehl | Beschreibung | Anwendungsbeispiel |
|---|---|---|
| hf auth login | Anmeldung bei Hugging Face mit persönlichem Access Token. Der Befehl speichert das Token lokal im Cache und (optionalerweise) im Git-Credential-Manager. | – |
| hf auth whoami | Zeigt das aktuell angemeldete Konto an. | – |
| hf auth logout | Abmeldung. Entfernt das Token aus dem lokalen Speicher. | – |
| hf cache scan | Zeigt die Modelle, Datensätze usw., die lokal gecached sind, samt Größen, Dateianzahl und Pfaden. | – |
| hf cache delete | Bietet interaktiv (TUI) oder via Datei-Auswahl die Möglichkeit, gecachete Versionen zu löschen. | – |
| hf download | Lädt Dateien oder Repositories vom Hub herunter und speichert sie im lokalen Cache. | hf download meta-llama/Llama-3.1-8B-Instruct –local-dir ./llama3-8b |
| hf upload | hf upload lädt eine einzelne Datei in ein von dir angelegtes Repository auf dem Hugging Face Hub hoch. Dieses Repository gehört entweder deinem Benutzerkonto oder einer Organisation, in der du Mitglied bist. Du entscheidest, ob es öffentlich oder privat ist. Bricht der Upload ab, musst du die Datei erneut hochladen. hf upload ist gedacht für kleine, einzelne Dateien oder wenige Dateien. | Beispiel Repository: https://huggingface.co/<dein-username>/<my-repository-name> hf upload –repo-id [dein-username]/[mein-repository-name] [lokale-datei] [ziel-datei] z. B. hf upload –repo-id aaron/my-model ./config.json config.json |
| hf upload-large-folder | Upload ganzer Verzeichnisse; unterstützt das Wiederaufnehmen bei Abbruch. | hf upload-large-folder –repo-id [dein-username]/[mein-repository-name] [folder_path] z. B. hf upload-large-folder –repo-id aaron/my-model ./training_output |
| hf lfs-multipart-upload | Mit diesem Befehl lassen sich sehr große Dateien zuverlässig hochladen, zum Beispiel Modellgewichte oder Trainings-Checkpoints im zweistelligen Gigabyte-Bereich. Die Datei wird dabei lokal in kleinere Datenblöcke zerlegt. Jeder Block wird einzeln an das Hugging Face Repository auf dem Hub übertragen und dort automatisch wieder zu einer vollständigen Datei zusammengesetzt. Der Vorteil dieser Technik ist, dass ein abgebrochener Upload nicht von vorn beginnen muss. Bereits hochgeladene Blöcke bleiben im Repository erhalten. Beim erneuten Start prüft das Tool, welche Blöcke fehlen, und überträgt nur diese nach. Auf diese Weise lassen sich auch sehr große Dateien stabil und ohne unnötige Wiederholungen in ein Repository laden. | hf lfs-multipart-upload –repo-id [dein-username]/[mein-repository-name] [file_path] z. B. hf lfs-multipart-upload –repo-id aaron/my-model ./model.safetensors |
| hf lfs-enable-largefiles | Wenn du ein Repository mit Git und Git LFS auf dem Hugging Face Hub bearbeitest, liegen in deinem lokalen Ordner alle Dateien, auch die großen Modellgewichte. Beim Push unterscheidet Git: kleine Dateien wie eine config.json landen direkt in der Git-Historie, während große Dateien wie model.safetensors durch Git LFS ersetzt werden. In der Historie bleibt nur ein kleiner Zeiger, die eigentlichen Daten werden separat im LFS-Speicher von Hugging Face abgelegt. Beim Klonen oder mit hf download lädt der Client zuerst die Zeiger und anschließend die vollständigen Dateien aus diesem LFS-Speicher nach. GitHub funktioniert nach demselben Prinzip. Auch dort werden große Dateien über Git LFS ausgelagert. Standardmäßig liegt die Grenze bei 100 MB pro Datei. Alles darüber lässt sich nicht direkt pushen, weshalb Git LFS erforderlich ist. Hugging Face ist ähnlich aufgebaut, aber für große Modelle optimiert. Dateien im Bereich mehrerer Gigabyte sind dort üblich und Git LFS ist die vorgesehene Lösung. Der Befehl hf lfs-enable-largefiles richtet ein geklontes Hugging Face Repository so ein, dass große Dateien automatisch mit Git LFS verwaltet werden. Git LFS sorgt dafür, dass große Dateien nicht die Git-Historie aufblähen und verhindert damit fehlschlagende Pushes. Du brauchst diesen Befehl nur, wenn du tatsächlich mit Git im Repository arbeitest, also klonst, committest und pushst. Wenn du Dateien ausschließlich mit hf upload oder hf upload-large-folder hochlädst, ist er nicht erforderlich. | Im geklonten Repo: hf lfs-enable-largefiles |
| hf repo create | Erstellt ein neues Repository für Modell, Dataset, Space etc | hf repo create [dein-username]/[mein-repository-name] –type model z. B. hf repo create aaron/my-model –type model |
| hf repo-files | Zeigt die Struktur (Dateien) eines Repositories an | hf repo-files [dein-username]/[mein-repository-name] z. B. hf repo-files aaron/my-model |
| hf env | hf env gibt eine detaillierte Übersicht über deine lokale Arbeitsumgebung. Dazu gehören die installierte Version von huggingface_hub, Betriebssystem, Python-Version, verwendete Bibliotheken wie PyTorch oder TensorFlow sowie die Speicherorte von Cache und Tokens. Die Ausgabe ist vor allem für Diagnosezwecke gedacht, etwa wenn du ein Problem im Hugging Face GitHub-Repository meldest oder deine eigene Konfiguration prüfen wills | – |
| hf version | Zeigt die installierte Version von hf (also huggingface_hub) | – |
| hf jobs | Management von Jobs auf dem Hub: Skripte oder Docker-Container auf Hugging Face ausführen (zusätzlich zur CLI) | hf jobs run –flavor t4-small ubuntu nvidia-smi |
