{"id":17,"date":"2026-07-11T16:07:40","date_gmt":"2026-07-11T16:07:40","guid":{"rendered":"https:\/\/www.carbonimario.com\/articoli\/?p=17"},"modified":"2026-08-16T15:13:08","modified_gmt":"2026-08-16T15:13:08","slug":"generatore-verifiche-insegnanti-api-claude","status":"publish","type":"post","link":"https:\/\/www.carbonimario.com\/articoli\/generatore-verifiche-insegnanti-api-claude\/","title":{"rendered":"Costruire un generatore di verifiche per insegnanti con l’API di Claude"},"content":{"rendered":"\n

Un docente che prepara una verifica strutturata \u2014 domande, soluzioni, punteggi, griglia di valutazione, magari in doppia fila per scoraggiare le copiature \u2014 ci mette comodamente un’ora. Il generatore di verifiche<\/a> che ho costruito la produce in una trentina di secondi, partendo anche dalla dispensa del docente stesso.<\/p>\n\n\n\n

In questo articolo racconto com’\u00e8 fatto dentro. Non \u00e8 un tutorial passo-passo: \u00e8 il resoconto delle decisioni tecniche, comprese quelle dettate dai vincoli \u2014 che come spesso accade sono state le pi\u00f9 istruttive.<\/p>\n\n\n\n

I vincoli<\/h2>\n\n\n\n

Il progetto doveva rispettare tre condizioni non negoziabili:<\/p>\n\n\n\n

    \n
  1. Gratuito e senza registrazione<\/strong> per i docenti. Quindi l’endpoint \u00e8 pubblico, e chiunque pu\u00f2 chiamarlo.<\/li>\n\n\n\n
  2. Hosting condiviso<\/strong>: niente Composer in deploy, niente processi persistenti, niente filesystem sopra la webroot, si carica via FTP.<\/li>\n\n\n\n
  3. Niente dati conservati<\/strong>: i materiali dei docenti non finiscono in un database, n\u00e9 nei log.<\/li>\n<\/ol>\n\n\n\n

    \u00c8 un servizio basato su un LLM che sta in piedi su un hosting condiviso, con i costi sotto controllo e la privacy garantita dall’architettura, \u00e8 un esercizio di progettazione.<\/p>\n\n\n\n

    L’architettura \u00e8 noiosa, di proposito<\/h2>\n\n\n\n

    Una singola pagina HTML (CSS e JavaScript inline, niente framework) e un endpoint PHP che fa da tramite verso la Messages API<\/a> di Anthropic. Tutto qui. Niente build, niente dipendenze da aggiornare, niente database.<\/p>\n\n\n\n

    Browser \u2500\u2500POST\u2500\u2500\u25b6 genera.php \u2500\u2500HTTPS\u2500\u2500\u25b6 api.anthropic.com\/v1\/messages\n   \u25c0\u2500\u2500JSON\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u25c0\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518<\/code><\/pre>\n\n\n\n
    Il PHP fa cinque cose: valida l’input, applica i limiti anti-abuso, costruisce il prompt, chiama l’API con cURL, restituisce il JSON al browser. Il rendering della verifica e l’esportazione in Word avvengono lato client<\/strong>.<\/p>\n\n\n\n
    La chiamata: PHP puro<\/h2>\n\n\n\n
    Su hosting condiviso senza Composer, la via pi\u00f9 semplice \u00e8 la chiamata HTTP diretta. La Messages API \u00e8 un singolo endpoint POST:<\/p>\n\n\n\n    
    "$payload = [\\n  'model'      => 'claude-sonnet-5',\\n  'max_tokens' => 6000,\\n  'system'     => $sistema,   \\\/\\\/ il \\"ruolo\\" fisso del modello\\n  'messages'   => [['role' => 'user', 'content' => $content]],\\n];\\n\\n$ch = curl_init('https:\\\/\\\/api.anthropic.com\\\/v1\\\/messages');\\ncurl_setopt_array($ch, [\\n  CURLOPT_RETURNTRANSFER => true,\\n  CURLOPT_POST           => true,\\n  CURLOPT_HTTPHEADER     => [\\n    'content-type: application\\\/json',\\n    'anthropic-version: 2023-06-01',\\n    'x-api-key: ' . ANTHROPIC_API_KEY,\\n  ],\\n  CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),\\n]);"<\/pre>\n<\/div>\n\n\n\n
    Il modello \u00e8 Claude Sonnet<\/strong>: per un compito strutturato come questo il rapporto qualit\u00e0\/prezzo \u00e8 il punto di equilibrio giusto \u2014 la qualit\u00e0 delle domande \u00e8 da modello grande, il costo resta da centesimi (ci torno).<\/p>\n\n\n\n
    La dispensa va dritta al modello<\/h2>\n\n\n\n
    La funzione pi\u00f9 utile per i docenti \u00e8 “basa le domande sulla mia dispensa”. Qui c’\u00e8 la prima decisione che sorprende chi se lo immagina: il PDF non viene parsato<\/strong>. La Messages API accetta documenti PDF come blocco di contenuto, codificati in base64:<\/p>\n\n\n\n    
    "$content = [];\\nif ($pdf_base64 !== null) {\\n  $content[] = [\\n    'type'   => 'document',\\n    'source' => [\\n      'type'       => 'base64',\\n      'media_type' => 'application\\\/pdf',\\n      'data'       => $pdf_base64,\\n    ],\\n  ];\\n}\\n$content[] = ['type' => 'text', 'text' => $compito];"<\/pre>\n<\/div>\n\n\n\n
    Il modello legge il PDF direttamente \u2014 testo, struttura e anche le pagine scansionate, perch\u00e9 lo elabora anche visivamente. Zero librerie di parsing, zero casi limite da gestire, e domande che rispettano il materiale meglio di qualunque estrazione testuale che avrei potuto scrivere io.<\/p>\n\n\n\n
    Per i DOCX invece un piccolo trucco che vale il prezzo del biglietto: un file Word \u00e8<\/strong> un archivio ZIP. Si apre con ZipArchive<\/code>, si estrae word\/document.xml<\/code>, si spogliano i tag e si passa il testo nel prompt:<\/p>\n\n\n\n    
    "$zip = new ZipArchive();\\n$zip->open($file['tmp_name']);\\n$xml = $zip->getFromName('word\\\/document.xml');\\n\\\/\\\/ strip dei tag XML \\u2192 testo pulito nel prompt"<\/pre>\n<\/div>\n\n\n\n
    Output strutturato: lo schema nel prompt<\/h2>\n\n\n\n
    La verifica deve arrivare al browser come dati, non come prosa: il frontend la impagina in vista studente e vista docente, calcola i punteggi, la esporta in Word. Quindi il prompt chiede esplicitamente un oggetto JSON secondo uno schema dichiarato \u2014 titolo, istruzioni, punteggio totale, criteri e un array di versioni (Fila A, Fila B, versione BES\/DSA) ciascuna con le sue domande tipizzate: scelta multipla, vero\/falso, aperta, esercizio.<\/p>\n\n\n\n
    E siccome i modelli a volte incorniciano il JSON nei backtick nonostante le istruzioni, il parsing \u00e8 difensivo:<\/p>\n\n\n\n    
    "$testo = preg_replace('\\\/^```(?:json)?\\\\s*\\\/', '', $testo);\\n$testo = preg_replace('\\\/\\\\s*```$\\\/', '', $testo);\\n$dati  = json_decode($testo, true);"<\/pre>\n<\/div>\n\n\n\n
    Nota per chi parte oggi: l’API ora supporta gli structured outputs<\/strong> nativi (output_config.format<\/code> con un JSON Schema), che garantiscono output valido senza questa ginnastica. \u00c8 il primo refactoring in lista.<\/p>\n\n\n\n
    Endpoint pubblico e rate limit<\/h2>\n\n\n\n
    Una generazione costa pochi centesimi (qualche migliaio di token in ingresso, di pi\u00f9 se c’\u00e8 un PDF corposo, e 2-4 mila in uscita). Il costo unitario non \u00e8 il problema. Il problema \u00e8 che un endpoint pubblico che spende soldi a ogni chiamata \u00e8 un invito a nozze<\/strong> per bot e burloni.<\/p>\n\n\n\n
    La difesa \u00e8 a due livelli, entrambi file-based (niente database):<\/p>\n\n\n\n