🧠

FunctionGemma: Function Calling su Gemma 3 270M

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

Inizia Subito

🎯 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