🧙 Maestro Yoda Cap. 21 · Open source e HuggingFace

Puntata 234

Puntata 234 — TEST: deploy di un mini-modello in uno Space gratis

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

Le 11 puntate precedenti sono teoria spiegata bene. Questo TEST è l’opposto: 30 minuti, due file, un git push, e hai un mini-prodotto AI pubblico, gratis, con URL condivisibile. Il punto del TEST non è “imparare”, è dimostrare a te stesso che lo stack open ti basta.

screenshot di un browser con uno Space HuggingFace in esecuzione. URL huggingface.co/spaces/tuonome/mini-test. UI Gradio con un input “Scrivi qui” e un output che dice “Ciao! Sono un mini-Llama che gira su una T4 gratis.” Sotto un orologio: “0$ di costo, 23 minuti di setup”

Cosa costruirai

Una demo chatbot Gradio che usa Qwen2.5-0.5B-Instruct (o equivalente piccolo) servito tramite HuggingFace Inference API gratis, hostato in uno Space pubblico con URL huggingface.co/spaces/<tuo-username>/mini-chat-italian.

Specs:

  • 2 file: app.py + requirements.txt (e un README.md per il frontmatter Space).
  • Tempo totale: 20-30 minuti dal primo git init alla URL live.
  • Costo: 0 €.
  • Hardware Space: CPU free tier (2 vCPU, 16 GB RAM). Il modello gira via Inference API, non sul container Space.

Step 0 — Prerequisiti

  • Account HuggingFace (huggingface.co).
  • Token utente con scope write: Settings → Access Tokens → “New token” → write.
  • Git installato + huggingface-cli (pip install huggingface_hub[cli]).
  • 30 minuti di tempo continuo.
huggingface-cli login   # incolla il token

Step 1 — Crea lo Space

Sul sito:

  1. Vai a huggingface.co/new-space.
  2. Owner: tuo username.
  3. Space name: mini-chat-italian (o quello che vuoi).
  4. SDK: Gradio.
  5. Hardware: CPU basic (free).
  6. Visibility: Public.
  7. Click “Create Space”.

HF crea un repo git inizializzato con file di esempio.

Step 2 — Clona localmente

git clone https://huggingface.co/spaces/<tuo-username>/mini-chat-italian
cd mini-chat-italian

Vedi 3 file: README.md, app.py (template), requirements.txt (vuoto o minimal).

Step 3 — app.py

Sovrascrivi con questo (~40 righe):

import os
import gradio as gr
from huggingface_hub import InferenceClient

MODEL_ID = "Qwen/Qwen2.5-0.5B-Instruct"
SYSTEM_PROMPT = (
    "Sei un assistente conversazionale in italiano. "
    "Rispondi in modo conciso, chiaro, leggermente ironico, "
    "ma sempre rigoroso sui fatti. Mai inventare date o numeri."
)

client = InferenceClient(model=MODEL_ID, token=os.environ.get("HF_TOKEN"))

def chat_fn(message, history):
    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
    for user_msg, ai_msg in history:
        messages.append({"role": "user", "content": user_msg})
        messages.append({"role": "assistant", "content": ai_msg})
    messages.append({"role": "user", "content": message})

    response = ""
    for chunk in client.chat_completion(
        messages=messages,
        max_tokens=512,
        temperature=0.7,
        stream=True,
    ):
        delta = chunk.choices[0].delta.content or ""
        response += delta
        yield response

demo = gr.ChatInterface(
    fn=chat_fn,
    title="Mini Chat Italian — powered by Qwen 0.5B",
    description="Demo del Capitolo 21 di **AI per Babbani**. "
                "Modello open, infra gratuita, italiano nativo.",
    examples=[
        "Spiegami in 3 frasi cos'è un Transformer.",
        "Scrivi un haiku sulla domenica delle Palme.",
        "Quali sono i 3 modi più rapidi per riscaldare la pasta avanzata?",
    ],
)

if __name__ == "__main__":
    demo.launch()

Punti chiave:

  • InferenceClient parla con l’Inference API gratuita di HF. Rate-limited ma sufficiente per demo.
  • HF_TOKEN letto da env var (settato nei Secrets dello Space, vedi step 5).
  • Streaming con yield response → tipico UX chatbot.
  • gr.ChatInterface = 1 riga per UI completa con history, examples, retry.

Step 4 — requirements.txt

gradio>=4.44.0
huggingface_hub>=0.26.0

(Versioni più nuove vanno bene; queste sono minimi testati.)

Step 5 — README.md (frontmatter Space)

---
title: Mini Chat Italian
emoji: 🤖
colorFrom: blue
colorTo: red
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
license: apache-2.0
---

# Mini Chat Italian

Demo del Capitolo 21 di [AI per Babbani](https://aiperbabbani.it).
Mostra come servire un piccolo modello open (Qwen 2.5 0.5B Instruct)
tramite Gradio + HF Inference API, hostato su Space gratis.

## Stack
- Modello: `Qwen/Qwen2.5-0.5B-Instruct` (Apache 2.0)
- UI: Gradio 4.x
- Inference: HuggingFace Inference API
- Hardware: CPU basic (free tier)

Step 6 — Settare il Secret HF_TOKEN

Senza token, l’Inference API ha quota più bassa. Con il tuo personal token, hai la quota piena del tuo account.

Nel sito dello Space:

  1. Tab Settings dello Space.
  2. Sezione Variables and secrets.
  3. New secret: name HF_TOKEN, value il tuo token (lo stesso usato per huggingface-cli login).
  4. Save. Lo Space si riavvia.

Il codice legge os.environ.get("HF_TOKEN") e lo passa al client.

Step 7 — Push

git add app.py requirements.txt README.md
git commit -m "Initial Mini Chat Italian"
git push

Lo Space rileva il push, builda l’immagine Docker, installa requirements, avvia app.py. Tempo build tipico: 60-180 secondi.

Stato del build visibile su https://huggingface.co/spaces/<tuo-username>/mini-chat-italian nella tab Logs.

Se vedi “Running”:

  • Apri l’URL principale dello Space.
  • Vedi l’interfaccia Gradio.
  • Scrivi una domanda. Vedi lo streaming della risposta.

Step 8 — Condividi e itera

Hai una URL pubblica: condividila ai colleghi, agli amici, sul tuo CV.

Iterazioni veloci

Modifichi app.py localmente, git push, lo Space si ribuilda automaticamente. ~60 secondi di downtime.

Cosa puoi migliorare

  1. Cambia modello con uno più capace: meta-llama/Llama-3.2-3B-Instruct (gated, accetta la license prima), mistralai/Mistral-7B-Instruct-v0.3, Qwen/Qwen2.5-7B-Instruct. Solo 1 riga: MODEL_ID = "...".
  2. Aggiungi RAG su un PDF tuo: vedi puntata 246 (TEST agente RAG).
  3. Persistent chat memory in un DB SQLite locale dentro lo Space.
  4. Più voice/tones con dropdown system prompt.
  5. Upgrade a ZeroGPU (free per quota): permette modelli più grandi con GPU on-demand. Aggiungi sdk: gradio + tag zero-gpu nel README e installa spaces.

Errori comuni (e fix)

a) “Model not found” o 404

Verifica MODEL_ID esatto. Se gated (Llama, Gemma), accetta la license sul sito HF (huggingface.co/<modello>) prima.

b) Streaming non funziona

Verifica gradio>=4.0 e che la funzione usi yield (generator), non return.

c) Build fails con “module not found”

Versioni nel requirements.txt mancanti o incompatibili. Apri Logs, leggi l’errore esatto, aggiusta.

d) “Rate limit exceeded”

Hai esaurito la quota free senza token. Setta HF_TOKEN nei Secrets (Step 6).

e) Risposta vuota

Modello non instruction-tuned (es. base model). Usa *-Instruct o *-Chat versions.

f) Build lento (>5 min)

Normale alla prima build (deps pip da installare). Le successive sono cached.

Bonus: aggiungere un endpoint API

Gradio espone già un’API REST auto-generata. Visita <space-url>/?view=api per la doc.

Chiamabile via Python:

from gradio_client import Client
client = Client("<tuo-username>/mini-chat-italian")
result = client.predict(
    message="Ciao", history=[], api_name="/chat"
)
print(result)

Significa: il tuo Space è anche un mini-backend AI, gratis. Puoi usarlo da uno script Python, un bot Telegram, un’app Next.js.

Cosa hai dimostrato

Completando questo TEST hai dimostrato a te stesso che:

  1. Servire un modello open è banale (40 righe Python).
  2. HF Inference API + Spaces ti danno hosting gratis per demo serie.
  3. Lo stack open scala da 0 € a milioni di richieste cambiando solo il backend (Inference Endpoints, vLLM, ecc.) senza riscrivere il client.
  4. Il “vendor lock-in” è una scelta, non un destino: puoi cambiare modello con una riga.

Per chi viene dal mondo “uso solo le API di OpenAI”: è il momento “ma allora era possibile da sempre”. Sì, era possibile da sempre. Adesso è anche facile.

Diploma del Capitolo 21

Se hai completato:

  • Hai scaricato/usato modelli da HF Hub (puntate 223-225).
  • Capito la differenza open weight vs open source (226).
  • Quantizzato un modello (227).
  • Eseguito un modello locale con Ollama/LM Studio/vLLM (228).
  • Misurato latenza/throughput (229).
  • Fine-tunato un open model (230 + ripasso 222).
  • Pubblicato un modello su HF Hub (231).
  • Scelto la license giusta (232).
  • Composto uno stack end-to-end (233).
  • Deployato uno Space pubblico (234).

Hai il toolkit completo per costruire prodotti AI senza alcuna dipendenza da API closed. È la libertà operativa più sottovalutata del 2026.

Glossario lampo

  • InferenceClient — client Python ufficiale di HF per chiamare l’Inference API (managed) o Inference Endpoints (dedicati). Supporta tutti i task: chat, embeddings, image, audio.
  • Space Secrets — variabili d’ambiente cifrate visibili solo al runtime dello Space. Tipico uso: API token.
  • ZeroGPU — feature HF che alloca on-demand GPU H200 per Space, condivisa fra utenti. Free tier ha quota giornaliera; utile per modelli più grandi.
  • gradio_client — SDK Python che permette di chiamare uno Space Gradio come API REST programmaticamente.

Take-away

Hai appena messo online una piccola applicazione AI usando solo strumenti open, gratis, in mezz’ora. Niente carte di credito, niente fatture, niente lock-in. La barriera tecnica all’AI è scesa a un punto in cui chi non costruisce qualcosa nel 2026 sceglie deliberatamente di non farlo. Il prossimo Capitolo (22) ti porta dal modello solitario all’agente che usa tool, esegue codice, fa retrieval — il livello successivo.

➡️ Prossima puntata: cos’è un agente AI — perception-action loop e tool use (apre Capitolo 22).