🧠

FunctionGemma: Function Calling su Gemma 3 270M

Collega linguaggio naturale ed esecuzione di API con un modello leggero, veloce e locale

🎯 Cos'è FunctionGemma?

FunctionGemma è una versione specializzata del modello Gemma 3 270M pensata per il function calling: traduce richieste in linguaggio naturale in azioni eseguibili su API definite.

✅ Quando usarla:

Hai un set di azioni/API ben definito
Vuoi comportamenti deterministici tramite fine-tuning
Preferisci latency istantanea e privacy locale
Costruisci sistemi composti con agenti su edge device

📦 Dove ottenerla:

Hugging Face: pesi open e modelli
Kaggle: notebook pronti
Vertex AI: hosting e deployment

📚 Programmare e Addestrare FunctionGemma

🚀 Setup ambiente

1 Dipendenze principali

Utilizza librerie standard per addestramento e deployment locale:

            pip install ` transformers ` datasets ` accelerate ` peft `
            bitsandbytes ` jsonschema ` pydantic
          

2 Definisci il tuo "API Surface"

Elenca le funzioni disponibili, con nome, descrizione e schema JSON degli argomenti.

            tools = [ { "name": "turn_on_light", "description": "Accende la luce
            in una stanza", "schema": { "type": "object", "properties": {"room":
            {"type": "string"}}, "required": ["room"] } }, { "name":
            "set_timer", "description": "Imposta un timer in minuti", "schema":
            { "type": "object", "properties": {"minutes": {"type": "integer",
            "minimum": 1}}, "required": ["minutes"] } } ]
          

3 Prepara il dataset di function calling

Genera esempi in formato JSONL con input utente e output strutturato della chiamata funzione.

            # Esempio di riga JSONL { "user": "Accendi la luce in cucina",
            "tools": tools, "expected_call": { "tool_name": "turn_on_light",
            "arguments": { "room": "cucina" } } } { "user": "Imposta un timer di
            5 minuti", "tools": tools, "expected_call": { "tool_name":
            "set_timer", "arguments": { "minutes": 5 } } }
          

4 Carica il modello base

Usa Gemma 3 270M come base e fine-tuna per il function calling.

            from transformers import AutoTokenizer, AutoModelForCausalLM
            model_id = "google/gemma-3-270m" # esempio tokenizer =
            AutoTokenizer.from_pretrained(model_id) model =
            AutoModelForCausalLM.from_pretrained(model_id)
          

5 Fine-tuning (LoRA/PEFT)

Applica un adattamento leggero per ottenere risposte strutturate e deterministiche.

            from peft import LoraConfig, get_peft_model lora = LoraConfig(r=8,
            lora_alpha=16, lora_dropout=0.05,
            target_modules=["q_proj","v_proj"]) model = get_peft_model(model,
            lora)
          

6 Obiettivo di training

Allena il modello a emettere JSON valido del tipo {"tool_name": ..., "arguments": {...}} dato user e tools.

            from datasets import load_dataset from transformers import Trainer,
            TrainingArguments ds = load_dataset("json", data_files={"train":
            "function_calls_train.jsonl", "validation":
            "function_calls_valid.jsonl"}) def format_example(example): prompt =
            ( "Seleziona una funzione e genera JSON.\n" f"Tools:
            {example['tools']}\n" f"Utente: {example['user']}\n" "Output: " )
            labels = str(example["expected_call"]) # come stringa JSON return
            {"input_text": prompt, "label_text": labels} train_ds =
            ds["train"].map(format_example) args =
            TrainingArguments(output_dir="./fg-out",
            per_device_train_batch_size=8, num_train_epochs=3, logging_steps=50)
            trainer = Trainer(model=model, args=args, train_dataset=train_ds)
            trainer.train()
          

7 Validazione e valutazione

Verifica validità JSON, match dello schema e accuratezza del mapping tool/argomenti.

8 Deployment

Distribuisci on-device con quantizzazione (bitsandbytes, INT4) o su Vertex AI. Notebook pronti anche su Kaggle.

💡 Esempio d'uso: eseguire funzioni locali

Il modello propone una chiamata funzione in JSON, l'app la valida e esegue la funzione corrispondente.

          import json # Funzioni reali def turn_on_light(room): return f"Luce
          accesa in {room}" def set_timer(minutes): return f"Timer impostato a
          {minutes} minuti" TOOLS = {"turn_on_light": turn_on_light,
          "set_timer": set_timer} # Output del modello (esempio) model_output =
          """ { "tool_name": "turn_on_light", "arguments": { "room": "cucina" }
          } """ call = json.loads(model_output) tool =
          TOOLS.get(call["tool_name"]) result = tool(**call["arguments"]) if
          tool else "Funzione non disponibile" print(result)
        

Utente: Puoi accendere la luce in cucina? → Modello: { "tool_name": "turn_on_light", "arguments": { "room": "cucina" } } → Esecuzione: Luce accesa in cucina

🛠️ Strumenti e best practice

🤗

Hugging Face

Pesi open, modelli e script di training.

📓

Kaggle

Notebook di esempio per fine-tuning rapido.

☁️

Vertex AI

Deployment gestito e scaling.

🧪

Validazione

JSON Schema e test unitari sui tool.

💡 Consigli pratici

Schema degli argomenti semplice e stabile
Dataset con variazioni linguistiche e sinonimi
Output solo JSON, senza testo extra
Fallback sicuro quando il tool non esiste

🔒 Attenzione

Non eseguire funzioni senza validazione dello schema
Evita prompt ambigui o tool sovrapposti
Gestisci permessi per azioni critiche

🚀 Risorse ufficiali

Approfondisci FunctionGemma e prova i demo.

Documentazione Hugging Face Kaggle