🧙 Maestro Yoda Cap. 21 · Open source e HuggingFace

Puntata 231

Puntata 231 — Pubblicare un modello su HF Hub

Livello: 🧙 Maestro Yoda · Capitolo 21 · Open source e HuggingFace

Hai un fine-tune che funziona bene. Adesso puoi tenertelo per te (legittimo), oppure pubblicarlo. Pubblicare bene su HuggingFace è una piccola arte: model card, license, eval, riproducibilità. La differenza tra “qualcuno lo userà” e “muore in 10 download” è quasi sempre nella cura della pagina, non dei pesi.

una vetrina di pasticceria con cento dolci. Solo tre hanno il cartellino completo (nome, ingredienti, scadenza, allergeni); gli altri sono anonimi. Una mano indica i tre con cartellino. Sotto: “non basta sfornare bene, bisogna anche etichettare bene”

Perché pubblicare?

Quattro motivazioni legittime:

  1. Portfolio: dimostri pubblicamente cosa sai fare. Per data scientist freelance vale come un PR su GitHub.
  2. Reciprocity: usi modelli open, ne pubblichi uno tuo. Sano.
  3. Community: altri estendono/migliorano il tuo, tu vinci.
  4. Distribution: serve il tuo modello via HF Inference o partner senza setup tuo.

Quattro motivi per non pubblicare:

  1. Contiene dati proprietari/sensibili (PII, segreto industriale).
  2. License del base model lo vieta (rare, ma controlla).
  3. Il modello fa peggio del base e non aggiunge valore.
  4. Non hai tempo/voglia di mantenerlo (issues, PR, model card aggiornate).

Il processo tecnico in 5 step

1) Account e token

  • Crea account su huggingface.co.
  • Settings → Access Tokens → crea un token con scope write.
  • Login da CLI: huggingface-cli login e incolla il token.

2) Creare il repo

Da web: “New Model” → namespace (user o org) + name (es. mio-username/llama-3-italian-legal-v1). Da CLI:

huggingface-cli repo create llama-3-italian-legal-v1 --type model

Naming convention sana: <base-model>-<dominio>-v<versione>. Esempi reali: mistralai/Mistral-7B-Instruct-v0.3, unsloth/Llama-3.2-3B-Instruct-bnb-4bit.

3) Push dei file

git clone https://huggingface.co/<user>/<repo>
cd <repo>
git lfs install
# copia config.json, tokenizer*, model.safetensors, generation_config.json, ecc.
git add .
git commit -m "Initial model upload"
git push

Oppure pythonic:

from huggingface_hub import HfApi
api = HfApi()
api.upload_folder(
    folder_path="path/al/modello",
    repo_id="<user>/<repo>",
    repo_type="model"
)

I file .safetensors vengono automaticamente in LFS.

4) Model card (README.md)

Vedi sezione dedicata sotto. Questo è il file critico.

5) (Opzionale) tag, license, gating

  • Aggiungi tag/license al frontmatter (sotto).
  • Se vuoi gated access: Settings → Gated repository → “manual” o “automatic” → utenti devono cliccare per accedere.

Anatomia di una model card che funziona

Frontmatter YAML (parsed da HF per filtri, leaderboard, integrazioni):

---
language: [it, en]
license: apache-2.0
library_name: transformers
base_model: meta-llama/Llama-3.1-8B-Instruct
datasets:
  - mio-username/legal-italian-sft
  - HuggingFaceH4/ultrachat_200k
pipeline_tag: text-generation
tags:
  - llama
  - italian
  - legal
  - lora
model-index:
  - name: llama-3-italian-legal-v1
    results:
      - task: { type: text-generation }
        dataset: { name: ItalianLegalQA, type: mio-username/ita-legal-qa }
        metrics:
          - { type: accuracy, value: 0.78 }
---

Body (sezioni minime obbligatorie de facto):

# llama-3-italian-legal-v1

Fine-tune di Llama-3.1-8B-Instruct su 12k esempi di Q&A legale italiano,
focalizzato su GDPR, Codice Civile, contrattualistica B2B.

## Uso

```python
from transformers import pipeline
pipe = pipeline("text-generation", model="<user>/llama-3-italian-legal-v1")
out = pipe("Cos'è una DPIA?", max_new_tokens=300)

Performance

  • ItalianLegalQA accuracy: 78% (vs 64% base Llama-3.1-8B-Instruct).
  • MMLU-it: 61% (vs 63% base) — leggero regression normale post-FT.

Training

  • Base: meta-llama/Llama-3.1-8B-Instruct
  • Tecnica: LoRA r=32, alpha=64, target_modules tutti i proj
  • Dataset: 12,000 esempi (8,000 proprietari + 4,000 ultrachat)
  • Hardware: 1× A100 80GB, ~4 ore
  • Hyperparams: LR 2e-4, batch effettivo 32, 2 epoche
  • Framework: unsloth 2024.x + trl 0.11

Limitazioni

  • Tarato su diritto italiano: NON usare per altri ordinamenti.
  • Non sostituisce consulenza legale: solo supporto informativo.
  • Knowledge cutoff base: 2024-07; dataset di FT: 2025-09.
  • Soggetto a hallucination su norme post-2025-09.

License

Apache 2.0 sull’adapter LoRA. Per i pesi base, vale Llama Community License.

Citation

@misc{tua-citazione-2026, author = {Tuo Nome}, title = {llama-3-italian-legal-v1}, year = {2026}, url = {https://huggingface.co//llama-3-italian-legal-v1} }


---

## Cosa fa diventare popolare un modello

Empiricamente (osservazione sui top trending HF 2023-26):
- **Model card chiara** con esempi runnable copia-incollabili.
- **Benchmark numerici** (anche solo 1-2, ma chiari).
- **Demo Space** linkata in alto.
- **License permissive** (Apache 2.0 ≫ Llama Community per uptake).
- **GGUF** quantizzato pubblicato (o linkato da bartowski / mradermacher).
- **Comparison table** vs il base model (mostra il delta).
- **Niente bullshit**: limitazioni dichiarate onestamente.

Cosa **non** funziona:
- Model card vuota o "lorem ipsum".
- Benchmark inventati (la community li verifica e ti fa lo shame in Discussion).
- Naming ambiguo (es. `my-llama-final-v2-good`).
- Nessun esempio d'uso.

---

## Versioning e mantenimento

Tag git per release:
```bash
git tag v1.0.0 -m "First public release"
git push --tags

Utenti possono pinnare:

AutoModel.from_pretrained("<user>/<repo>", revision="v1.0.0")

Aggiornamenti:

  • Patch (bug fix, model card update): bump v1.0.1.
  • Minor (retraining su più dati, stesso obiettivo): v1.1.0.
  • Major (cambio architettura/base model): v2.0.0 in repo nuovo (per non rompere chi usa v1).

Convenzione: una nuova major version = un nuovo repo, non un branch.

Inference Endpoints e Spaces collegati

Una volta pubblicato, puoi:

Inference API (gratis, rate-limited)

Su modelli pubblici HF offre l’inference gratis con rate limit. Ottimo per demo.

Inference Endpoints (a pagamento)

Dedicati: tu prenoti la GPU, paghi l’ora, hai endpoint privato.

Space demo

Crea uno Space Gradio (vedi puntata 224) che usa il tuo modello via Inference API. Linklo in alto al model card. Massimizza la visibilità.

License e responsabilità

Se il tuo fine-tune deriva da un base model gated (Llama, Gemma):

  • I tuoi pesi sono opera derivata.
  • Eredità della license: per Llama Community License, anche il tuo fine-tune ne è soggetto.
  • Devi dichiarare base_model: nel frontmatter e citare la license originale.

Per essere a posto:

  • License chiara nel YAML.
  • Sezione “License” nel body che esplicita derivazione.
  • Disclaimer su limiti d’uso (specialmente per modelli legali/medici).

Cosa NON pubblicare mai

  • Modelli addestrati su dati personali identificabili (rischio GDPR — vedi puntata 198).
  • Modelli con segreti industriali nei training data.
  • Modelli che generano CSAM / contenuti illegali anche per “ricerca” (HF Trust & Safety ti banna immediatamente).
  • Modelli che violano TOS del base model (es. Claude o GPT API non permettono usare le loro risposte per addestrare modelli concorrenti).

Per quest’ultimo punto: nel 2024-25 c’è stato un dibattito acceso sulla legalità di training su output GPT-4. OpenAI ufficialmente lo vieta nei TOS. Pratica diffusa ma legalmente esposta.

Glossario lampo

  • Model card — README.md strutturato con metadata machine-readable (frontmatter YAML) + sezioni human-readable. Standard de facto.
  • base_model: — campo frontmatter che dichiara il modello da cui hai derivato. Alimenta grafi di derivazione su HF.
  • Gated repository — modello che richiede accettazione license + token per essere scaricato. Configurabile in Settings del repo.
  • Inference Endpoints — servizio HF per servire un modello su GPU dedicata. Pagamento on-demand (~$0.60-4/h).

Take-away

Pubblicare un modello su HF Hub è la parte facile (5 step, 10 minuti). Pubblicarlo bene richiede un’ora di model card scritta con cura, una demo Space, una license chiara, e benchmark onesti. È la differenza tra un repo che ottiene 10 download e uno che ne ottiene 100.000. La community premia chi documenta, non chi addestra meglio.

➡️ Prossima puntata: license pitfall — il labirinto Apache, MIT, OpenRAIL, Llama Community e altre trappole.