diff --git a/lessons/01-intro-to-genai/translations/README.it.md b/lessons/01-intro-to-genai/translations/README.it.md new file mode 100644 index 00000000..bb0e4a75 --- /dev/null +++ b/lessons/01-intro-to-genai/translations/README.it.md @@ -0,0 +1,348 @@ +# Lezione 1: Introduzione all'IA generativa e agli LLM per sviluppatori JavaScript + +In questo capitolo imparerai a: +- comprendere le basi dell’IA generativa e dei Large Language Model (LLM); +- identificare le potenziali applicazioni e limitazioni dei Large Language Model (LLM) nello sviluppo JavaScript; +- esplorare come l’IA generativa può migliorare l’esperienza utente nelle applicazioni JavaScript. + +## Configurazione + +Se non l’hai ancora fatto, configura il tuo ambiente di sviluppo. Ecco come puoi fare: [Configura il tuo ambiente](/docs/setup/README.md). + +## Risorse correlate + +[![Guarda un breve video introduttivo sull'intelligenza artificiale generativa](https://img.youtube.com/vi/vLYtDgs_zx8/0.jpg)](https://www.youtube.com/watch?v=vLYtDgs_zx8&list=PLlrxD0HtieHi5ZpsHULPLxm839IrhmeDk&index=1) + +_Questo video offre un'introduzione all'IA generativa con JavaScript_ + +💼 Slide: [Introduzione all'IA generativa](/videos/slides/00-intro.pptx) + +## IA generativa + +Probabilmente avrete già sentito parlare di strumenti come ChatGPT o AI generativa. Il concetto è semplice: si fornisce un prompt e un modello, spesso chiamato Large Language Model (LLM), genera un paragrafo o addirittura un'intera pagina di testo. Questo output può essere utilizzato per vari scopi, tra cui la scrittura creativa, rispondere a domande e il coding. + +Inoltre, l'IA generativa si è evoluta in capacità multimodali, consentendo di fornire un'immagine o un video come input e ricevere una varietà di output. Questo progresso ha migliorato significativamente il flusso di lavoro di molte persone, non solo generando testo, ma anche riassumendo, traducendo e altro ancora. + +*In poche parole, le interfacce in linguaggio naturale stanno diventando il nuovo standard per molte app e i tuoi utenti si aspettano di poterle usare.* + +## Storia: “Un viaggio nel tempo” + +> [!NOTE] +> Cominciamo con una panoramica della storia, una storia che collega il passato al futuro! Man mano che procederai con questo programma di studi, ti imbarcherai in un'avventura emozionante, viaggiando indietro nel tempo per collaborare con alcune delle menti più brillanti della storia. Insieme affronterete sfide ed esplorerete come l'IA generativa possa rivoluzionare le vostre applicazioni JavaScript. + +> [!NOTE] +> Anche se consigliamo di leggere la storia (è divertente!), [clicca qui](#interagisci-con-dinocrate) se preferisci passare direttamente al contenuto tecnico. + +Il tuo viaggio inizia nella Londra degli anni '60 dell'Ottocento, dove vestirai i panni di un abile inventore. Attraverso una serie di avventure avvincenti, affinerai le tue abilità di intelligenza artificiale e sbloccherai soluzioni che trascendono il tempo. + +### Nel vortice - Londra 1860 + +Nel cuore della Londra degli anni '60 dell'Ottocento, sei riconosciuto come uno dei meccanici più abili della tua epoca. La tua officina è nascosta in un vicolo stretto. Le pareti sono ricoperte da scaffali traboccanti di parti meccaniche, progetti e lavori lasciati a metà. + +Il tuo banco da lavoro, il cuore della tua officina, è un disordine organizzato. + +
+ Officina di Londra +
+ +_Al centro del banco giace il torso di un robot, una meraviglia ingegneristica che ha richiesto mesi di lavoro. La sua struttura in legno è finemente intagliata e ogni giuntura è stata meticolosamente progettata per garantire movimenti fluidi._ + +### Una lettera, per te? + +All'improvviso, un colpo alla porta interrompe i tuoi pensieri. È raro ricevere visite a quest'ora. Ti asciughi le mani con uno straccio e ti avvicini alla porta, incuriosito. + +Aprendo la porta, non trovi nessuno. Invece, il tuo sguardo è attratto da una busta sigillata sul pavimento. La raccogli e leggi: + +_"Caro amico,_ + +_Ti invio questa lettera per aiutarti nei tuoi sforzi con l'automa. È fondamentale che tu continui questo lavoro. In allegato troverai una chiave della biblioteca. Ci vediamo lì oggi alle 15:00._ + +_Tuo,_ + +_Charles Babbage."_ + +### Andiamo in biblioteca + +Charles Babbage, il grande matematico e inventore della macchina differenziale, vuole incontrarti. Prendi rapidamente il cappotto ed esci di casa. + +Dopo una passeggiata di 20 minuti lungo il Tamigi, finalmente arrivi alla biblioteca dove trovi la porta leggermente aperta. + +All'interno è buio e cupo, l'unica luce filtra attraverso le finestre sporche, proiettando ombre inquietanti sulle pareti. + +**Tu:** «Permesso? Sig. Babbage?» + +Mentre i tuoi occhi si abituano alla luce fioca, noti una figura in lontananza che ti saluta con la mano. Ti avvicini a lui, i tuoi passi riecheggiano sul pavimento di legno. La figura diventa più nitida e lo riconosci dalle foto sui giornali: è Charles Babbage. + +![Biblioteca polverosa](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/01-intro-to-genai/assets/library.png) + +### Cos'è questo dispositivo? + +Appena ti avvicini, un lampo accecante esplode e lui svanisce. + +Sul pavimento è rimasto un piccolo dispositivo metallico che gira su se stesso. Lo raccogli: la sua superficie liscia e fredda emette un leggero ronzio. È diverso da qualsiasi cosa tu abbia mai visto, eppure ti sembra stranamente familiare; percepisci un senso di potere che emana da esso. + +Assomiglia a un minuscolo scarafaggio, dal design intricato, con tre pulsanti: una freccia su, una freccia giù e un pulsante rosso luminoso. Dal retro spunta una piccola antenna che pulsa di energia. + +Spinto dalla curiosità, le tue dita si avvicinano al pulsante rosso. Nel momento in cui lo premi, il mondo intorno a te brilla e i colori turbinano violentemente intorno a te. + +Poi, il buio e la sensazione di cadere. + +![Vortice temporale](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/01-intro-to-genai/assets/vortex.png) + +### Alessandria, 300 a.C. + +Ti svegli, disorientato. Man mano che la tua vista si schiarisce, una città antica si dispiega davanti a te: frenetica, vivace e piena di vita. + +Persone in toga si muovono per le strade, le loro voci si fondono in una sinfonia di dialetti antichi, l'aria è piena del profumo di spezie esotiche e del suono lontano dei mercanti che vendono le loro merci. + +![Alessandria, 300 a.C.](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/01-intro-to-genai/assets/alexandria.png) + +**Tu:** «Sicuramente devo aver battuto la testa», pensi, chiudendo gli occhi e riaprendoli, ma la scena rimane immutata. + +«Sono bloccato nel passato? Oserei premere di nuovo quel pulsante?» Prima che tu possa decidere, una figura ti si avvicina, salutandoti con la mano. + +### Incontro con Dinocrate + +Un anziano signore vestito con una toga ti saluta con la mano dai gradini del grande tempio. I suoi capelli bianchi e la barba riflettono la luce del sole, conferendogli un aspetto quasi etereo. + +![Dinocrate che indossa una toga](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/01-intro-to-genai/assets/dinocrates.png) + +**Dinocrate:** «Benvenuto, viaggiatore», dice calorosamente. «Sono Dinocrates, architetto di questa grande città. Il tuo arrivo era stato predetto.» + +**Tu:** «Davvero? Beh, certo che sì. Sono qui per aiutare, credo.» + +**Dinocrate:** «Sì, come dicevo, ti aspettavamo già da tempo. Abbiamo un compito che richiede le tue abilità uniche.» + +**Dinocrate:** «Le nostre navi hanno difficoltà a navigare lungo la costa: dobbiamo costruire un faro. Ne sai qualcosa?» + +**Tu:** «Sono un inventore. Costruisco automi. Vediamo cosa posso fare.» + +### Lo "Scarabeo del Tempo" + +Ti viene in mente un pensiero. «Il dispositivo può capirmi se gli parlo?» + +**Tu:** «Dispositivo, riesci a capirmi?» + +**Dispositivi:** «Certo. Che cosa ti serve?» + +**Tu:** «Puoi aiutarmi a costruire un faro?» + +**Dispositivo:** «Certo. Non sarà un problema.» + +**Tu:** «Hai un nome?» + +**Dispositivo:** «Sono lo Scarabeo del Tempo. Il mio creatore mi chiama George, dice che è un bel nome per uno scarabeo.» + +**Tu:** «Hai ragione: George è proprio un bel nome, infatti è stato il nome di mio padre.» + +![Scarabeo del Tempo](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/01-intro-to-genai/assets/time-beetle.png) + +_Dispositivo temporale, “George” lo scarabeo metallico_ + +> [!NOTE] +> Nel 300 a.C., Alessandria era una fiorente città fondata da Alessandro Magno nel 331 a.C. Divenne rapidamente una delle più grandi città del mondo ellenistico. Progettata dall'architetto capo di Alessandro, Dinocrate, divenne un importante porto e centro culturale. +> +> Alessandria era famosa per le sue imponenti costruzioni, tra cui il Faro, una delle sette meraviglie del mondo antico, e la leggendaria Biblioteca di Alessandria. La posizione strategica della città la rese un centro fondamentale per il commercio e lo scambio di conoscenze. +> +> Sotto il regno tolemaico, che seguì la morte di Alessandro, Alessandria divenne una delle città più prospere e influenti dell'epoca. + +## Interagisci con Dinocrate + +Se vuoi interagire con Dinocrate, esegui la app [Personaggi](/app/README.md). + +> [!IMPORTANT] +> Questo è interamente frutto di fantasia: le risposte sono generate dall'intelligenza artificiale. +> [Dichiarazione di responsabilità sull'IA](../../README.md#responsible-ai-disclaimer) + +![Dinocrate che indossa una toga](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/01-intro-to-genai/assets/dinocrates.png) + +**Passaggi**: + +1. Avvia un [![GitHub Codespace](https://img.shields.io/badge/GitHub-Codespace-brightgreen)](https://codespaces.new/microsoft/generative-ai-with-javascript). +2. Passa a _/app_ nella root del repo. +3. Individua la console ed esegui `npm install` seguito da `npm start`. +4. Una volta comparso, seleziona il pulsante "Open in Browser". +5. Chatta con Dinocrate. + +> [!NOTE] +> Se stai eseguendo il progetto in locale sul tuo computer, consulta la guida QuickStart per ottenere la configurazione di un token per l'[accesso personale a GitHub](/docs/setup/README.md#creating-a-personal-access-token-pat-for-github-model-access) e sostituisci la chiave nel codice. + +### Anteprima del codice + +Sebbene ci sia ancora molto da trattare in questo programma di studi sull'IA generativa, diamo un'occhiata veloce al codice IA per iniziare a imparare a usare JavaScript con l'IA. + +All'interno di `/app/app.js` troverai una funzione `app.post` che gestisce la funzionalità di AI generativa. È mostrata di seguito: + +```JavaScript +app.post('/send', async (req, res) => { + const { message } = req.body; + const prompt = message; + + const messages = [ + { + "role": "system", + "content": "You are Dinocrates of Alexandria, a famous architect and engineer. Limit your responses to only the time you live in, you don't know anything else. You only want to talk about your architecture and engineering projects, and possibly new ideas you have.", + }, + { + "role": "user", + "content": prompt + } + ]; + + const openai = new OpenAI({ + baseURL: "https://models.inference.ai.azure.com", + apiKey: process.env.GITHUB_TOKEN, + }); + + try { + console.log(`sending prompt ${prompt}`) + const completion = await openai.chat.completions.create({ + model: 'gpt-4o-mini', + messages: messages, + }); + + res.json({ + prompt: prompt, + answer: completion.choices[0]?.message?.content + }); + } catch (error) { + res.status(500).json({ error: error.message }); + } +}); +``` + +Ecco una sintesi passo dopo passo di ciò che fa la funzione: + +1. **Estrae il messaggio dalla richiesta**: La funzione estrae il messaggio dal corpo della richiesta (req.body). +2. **Crea un array di prompt**: Costruisce una serie di messaggi, tra cui un messaggio di sistema e il messaggio di prompt dell'utente. +3. **Inizializza il client di OpenAI**: Un client OpenAI viene inizializzato con l'URL di base e la chiave API dalle variabili di ambiente. Per elaborare il prompt e restituire una risposta viene utilizzato un modello _gpt-4o-mini_ di [GitHub Models](https://github.com/marketplace/models). +4. **Invia il prompt a OpenAI**: La funzione registra il prompt e lo invia all'API di OpenAI per generare una completion. +5. **Gestione della risposta**: In caso di esito positivo, la funzione risponde con il prompt e la risposta della completion. +6. **Gestione degli errori**: Se si verifica un errore, risponde con uno stato 500 e il messaggio di errore. + +> **Nota**: [GitHub Copilot](https://github.com/features/copilot) è stato utilizzato per generare questo riassunto del codice. L'IA generativa in azione! + +### Cosa può fare l'IA generativa per me e per le mie app? + +> [!NOTE] +> Probabilmente avrai già capito che lo Scarabeo del Tempo funziona come un assistente AI con cui puoi interagire utilizzando il linguaggio naturale, scritto o parlato. + +Man mano che la tua avventura ad Alessandria prende forma, inizi a intravedere le possibilità offerte dalla combinazione di creatività, ingegnosità e strumenti all'avanguardia per risolvere le sfide e trasformare il mondo che ti circonda. + +**Tu:** «Dimmi di più sui fari», dici al tuo dispositivo. + +**Scarabeo del Tempo:** «Un faro è una torre dotata di una luce intensa nella parte superiore, situata vicino alla costa per guidare le navi in mare. La luce funge da ausilio alla navigazione, aiutando i marinai a evitare scogli e reef pericolosi e a raggiungere il porto in sicurezza.» + +Dinocrate ascolta di nascosto la vostra conversazione e aggiunge: + +**Dinocrate:** «Abbiamo bisogno di un faro che guidi le nostre navi in modo sicuro nel porto. Il mare può essere insidioso e molte navi sono andate perdute sugli scogli. Abbiamo bisogno di un faro che le guidi a casa.» + +#### Aree di applicazione dell'IA generativa + +**Tu:** «I fari sembrano sicuramente un argomento interessante, ma cos'altro può fare l'IA generativa per me e le mie app?» + +**Scarabeo del Tempo:** «Nel XXI secolo, l'IA generativa ha rivoluzionato molti settori, dall'assistenza sanitaria alla finanza, all'intrattenimento. Ecco alcuni esempi. + +- **Chatbot**: un chatbot in grado di generare risposte simili a quelle umane alle domande degli utenti. Anziché una pagina statica di FAQ, gli utenti possono interagire con un chatbot che fornisce risposte dinamiche. Ciò rende l'esperienza utente più coinvolgente e meno frustrante. + +- **Assistenti e agenti**: gli assistenti e gli agenti possono eseguire istruzioni più avanzate, come l'utilizzo di strumenti per richiamare API, eseguire codice, generare immagini e altro ancora. Gli agenti più avanzati possono perseguire obiettivi e svolgere compiti in modo autonomo. + +- **Uno strumento per la creazione di contenuti**: uno strumento per generare post per blog e social media. Immagina di poter creare campagne in pochi minuti, anziché in ore, quando un sito di e-commerce organizza i saldi del Black Friday. + +- **Completamento del codice**: uno strumento di completamento del codice in grado di generare frammenti di codice in base all'input dell'utente. Ciò può consentire agli sviluppatori di risparmiare molto tempo, soprattutto quando lavorano su attività ripetitive. + +- **Traduzione**: tradurre testi tra lingue diverse con elevata precisione. + +Come puoi vedere, questi miglioramenti possono aiutare sia il front-office che il back-office della tua app e della tua azienda.» + +Ecco un esempio di "applicazione chatbot" in azione: + +![Immagine di una app di chat](https://camo.githubusercontent.com/76f2ad7cd754a2de2b9957d2070448e130e5ba228084b9b4b128e3af9c9f5239/68747470733a2f2f6c6561726e2e6d6963726f736f66742e636f6d2f656e2d75732f73656d616e7469632d6b65726e656c2f6d656469612f636861742d636f70696c6f742d696e2d616374696f6e2e676966) + +**Tu:** «Affascinante, prenderò nota di andare nel XXI secolo per vedere come vengono utilizzati questi strumenti.» + +### IA generativa ed ecosistema JavaScript + +**Scarabeo del Tempo:** «Un modo molto diffuso per sviluppare app nel XXI secolo è l'uso di JavaScript. Ogni linguaggio di programmazione è circondato da un ecosistema che comprende il linguaggio stesso, librerie e framework, supporto della comunità, IDE e strumenti. Nell'ecosistema di un linguaggio di programmazione, solitamente si parla dei seguenti elementi.» + +| Elemento | Descrizione | +|---|---| +| Il linguaggio di programmazione stesso | Compresa la sua sintassi e le sue caratteristiche. | +| Librerie e framework | Librerie disponibili per interagire con i modelli di IA generativa. | +| Comunità che supporta il linguaggio | La comunità è importante, soprattutto quando si cerca di imparare qualcosa di nuovo. La comunità che ruota attorno alle librerie e ai framework aiuta a decidere quali librerie utilizzare. Influisce anche sulla facilità con cui è possibile trovare aiuto quando ci si trova in difficoltà. | + +**Tu:** «Interessante, credo di aver sentito parlare di programmazione. Non sono stati Ada Lovelace e Charles Babbage a sperimentarla?» + +**Scarabeo del Tempo:** «Sì, Ada Lovelace è stata la prima programmatrice di computer e Charles Babbage è stato l'inventore del motore differenziale, un computer inventore. Sono stati pionieri nel campo dell'informatica, gettando le basi per l'era digitale.» + +**Tu:** «Erano? Cosa intendi con “erano”? Ho appena ricevuto una lettera da Charles Babbage.» + +**Scarabeo del Tempo:** «Diciamo solo che ti trovi in una posizione privilegiata che ti permette di interagire con personaggi storici in un modo che pochi altri possono permettersi.» + +### Ecosistema JavaScript + +**Tu:** «Quindi, hai parlato di ecosistemi, sto solo prendendo appunti, ma che mi dici di JavaScript e in che modo è diverso dagli altri ecosistemi?» + +**Scarabeo del Tempo:** «JavaScript è uno dei linguaggi di programmazione più popolari al mondo nel XXI secolo. Ecco alcuni motivi della sua popolarità.» + +| Motivo | Descrizione | +|-|-| +| Potenziale per lo sviluppo full-stack | JavaScript è uno dei pochi linguaggi che può essere utilizzato sia per lo sviluppo front-end che back-end. | +| Ricco ecosistema di librerie | JavaScript dispone di un vasto ecosistema di librerie, con framework come React, Angular, Vue e molti altri. Esiste NPM, il gestore di pacchetti, che è uno dei più grandi repository di pacchetti al mondo. | +| Forte supporto della comunità | JavaScript ha una comunità ampia e attiva, con molte risorse disponibili per l'apprendimento e lo sviluppo. Inoltre funziona semplicemente nel browser, il che è un enorme vantaggio. | +| IDE e strumenti | JavaScript dispone di una vasta gamma di IDE, quali Visual Studio Code, WebStorm e Atom. Questi IDE dispongono di estensioni sviluppate da aziende e dalla comunità che consentono di affrontare diversi aspetti dello sviluppo. | +| IA e JavaScript | JavaScript supporta lo sviluppo con librerie come TensorFlow.js, Brain.js, le API di OpenAI e altre ancora, consentendo agli sviluppatori di integrare il machine learning e l'IA generativa nelle applicazioni web e lato server. | + +**Tu:** «Sono un sacco di motivi, sembra che dovrei puntare su JavaScript per i miei progetti futuri.» + +**Scarabeo del Tempo:** «Infatti, JavaScript è un linguaggio versatile, anche Python è un linguaggio popolare per lo sviluppo dell'IA.» + +**Tu:** «Python? Cosa c'entrano i serpenti con la programmazione?» + +**Scarabeo del Tempo:** «Lasciamo questo argomento per un'altra volta, va bene?» + +**Scarabeo del Tempo:** «Ho spiegato sopra perché JavaScript e il suo ecosistema sono generalmente adatti, ma perché lo sono in modo specifico per l'IA generativa? La risposta è che si tratta di un linguaggio supportato da molti fornitori di servizi cloud e framework e strumenti di IA. Si ritiene inoltre che, sebbene Python possa essere la prima scelta per gli scenari di IA, molti sviluppatori stanno utilizzando JavaScript e Typescript.» + +> **Lo sapevi?** +> Il [62,5% degli sviluppatori dichiara di utilizzare JavaScript](https://www.statista.com/statistics/793628/worldwide-developer-survey-most-used-languages/) e molti preferiscono [TypeScript](https://www.typescriptlang.org) per i nuovi progetti. + +## Compito - Aiuta Dinocrate + +Per utilizzare un Large Language Model (LLM) per aiutare Dinocrates con il faro di cui abbiamo parlato in precedenza nella nostra storia, useremo qualcosa chiamato prompt, ovvero una frase che descrive ciò che si desidera. È possibile specificare sia le informazioni necessarie sia il modo in cui si desidera che vengano presentate. + +**Scarabeo del Tempo:** «Cominciamo, utilizziamo un LLM per ricercare come costruire un faro per aiutare Dinocrate.» + +**Scarabeo del Tempo:**: «Dovrai fornire al LLM (cioè “me”) il contesto su come costruire, con quali strumenti e risorse dovrebbero essere disponibili ai tempi di Alessandria.» + +**Tu:** «Ok, dimmi qualcosa di più sugli LLM.» + +**Scarabeo del Tempo:** «Gli LLM sono un tipo di modello di IA in grado di generare testi simili a quelli umani sulla base di un determinato prompt. Sono addestrati su enormi quantità di dati e possono generare testi coerenti, creativi e contestualmente pertinenti.» + +**Scarabeo del Tempo:** «Probabilmente vorrai farmi una domanda più precisa, così potrò darti una risposta più accurata, riguardo a, come dire… *coff* *coff* i fari, Alessandria, 300 a.C., Dinocrate, il Faro di Alessandria, ecc.» + +**Tu:** «Capito, aggiungo più contesto al prompt e poi ti chiedo.» + +**Scarabeo del Tempo:** «Sì, sto aspettando…» + +Visita [Microsoft Copilot](https://copilot.microsoft.com), [ChatGPT](https://chatgpt.com/) o un altro strumento di chatbot online per generare un piano per la costruzione del Faro di Alessandria. + +> [!TIP] +> Prova a chiedere all'LLM di generare un piano che includa istruzioni passo dopo passo per la costruzione del faro. Hai bisogno di aiuto? Consulta la soluzione per ottenere assistenza. + +## Soluzione + +[Soluzione](/lessons/01-intro-to-genai/solution/solution.md) + +### Verifica delle conoscenze + +**Domanda:** Quali delle seguenti affermazioni relative all'IA generativa e a JavaScript sono vere? + +A. Le app di IA generativa basate su JavaScript possono generare solo testo. +B. JavaScript può essere utilizzato per creare applicazioni basate sull'IA, tra cui chatbot, strumenti di generazione di testo e altro ancora. +C. Python è l'unico linguaggio utilizzato per lo sviluppo dell'IA. + +[Soluzione del quiz](/lessons/01-intro-to-genai/solution/solution-quiz.md) + +## Risorse per lo studio autonomo + +- [Serie di video su JavaScript e IA generativa](https://aka.ms/genai-js) diff --git a/lessons/02-first-ai-app/translations/README.it.md b/lessons/02-first-ai-app/translations/README.it.md new file mode 100644 index 00000000..8502e8f6 --- /dev/null +++ b/lessons/02-first-ai-app/translations/README.it.md @@ -0,0 +1,496 @@ +# Lezione 2: Scrivere la tua prima app AI + +In questo capitolo imparerai a: +- configurare il tuo ambiente di sviluppo; +- scrivere un’app di base; +- comprendere i prompt di sistema. + +## Configurazione + +Se non l’hai ancora fatto, configura il tuo ambiente di sviluppo. Ecco come puoi fare: [Configura il tuo ambiente](/docs/setup/README.md). + +## Risorse correlate + +[![Guarda un breve video sui large language model](https://img.youtube.com/vi/GQ_2OjNZ9aA/0.jpg)](https://www.youtube.com/watch?v=GQ_2OjNZ9aA&list=PLlrxD0HtieHi5ZpsHULPLxm839IrhmeDk&index=2) + +_Questo video offre un'introduzione ai modelli di IA denominati "Large Language Model" (LLM), spiegando che cosa sono e come è possibile utilizzarli per integrare l'IA nelle proprie app._ + +*🎥 Clicca sull'immagine qui sopra per guardare un breve video sui large language model* + +💼 Slide: [Introduzione ai Large Language Model (LLM)](/videos/slides/01-llms.pptx) + +## Storia: “Immaginati su una barca sul fiume” + +> [!NOTE] +> _La nostra storia finora: sei un inventore, un artigiano della Londra del 1860 che ha viaggiato nel tempo usando un misterioso dispositivo chiamato Scarabeo del Tempo. Hai viaggiato attraverso gli annali della storia, assistendo alla creazione del Faro di Alessandria, una meraviglia dell'ingegneria antica che hai contribuito a creare con un piccolo aiuto da Dinocrate e dallo Scarabeo del Tempo._ +> +> Vedi [Lezione 1](/lessons/translations/01-intro-to-genai/README.it.md) se vuoi ripercorrere la storia dall'inizio e iniziare a usare l'IA generativa. + +> [!NOTE] +> Anche se consigliamo di leggere la storia (è divertente!), [clicca qui](#interagisci-con-leonardo) se preferisci passare direttamente al contenuto tecnico. + +Insieme a Dinocrate hai dato gli ultimi ritocchi al Faro di Alessandria. L'imponente struttura risplende alla luce del sole e la sua pietra levigata riflette il Mar Mediterraneo. + +Guardi lo Scarabeo del Tempo che hai in mano, la sua superficie metallica fredda contro il palmo. Stringendo il pugno, sussurri: «Portami a casa». Lo scarabeo inizia a brillare, emettendo una luce morbida e calda e il mondo intorno a te si dissolve in un turbine di colori. + +### Una nuova avventura + +Quando apri gli occhi, il mondo è cambiato. Mentre riesci ad alzarti, ti rendi conto di essere su una barca su un fiume. Ti guardi intorno: in lontananza vedi degli edifici i cui contorni sono sfumati dalla nebbia mattutina. + +Guardando intorno alla barca, trovi un lungo remo appoggiato al bordo. Afferrandolo, inizi a remare verso gli edifici lontani. Avvicinandoti, gli edifici diventano più nitidi: sono antichi, la loro architettura ricorda un dipinto rinascimentale. + +![Barca sul fiume, uomo in piedi con una pagaia](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/02-first-ai-app/assets/boat.png) + +La domanda è: dove e quando ti trovi questa volta? + +Riesci ad ormeggiare la barca al molo e inizi a camminare lungo le assi di legno, il suono dei tuoi passi echeggia dolcemente. + +Mentre cammini, noti un uomo con una lunga barba e un cappello che fruga in una cassa contenente quelli che sembrano componenti meccanici. Le sue mani si muovono abilmente, sistemando ingranaggi e molle con esperta facilità. + +![Leonardo Da Vinci in piedi accanto a una cassa nel porto](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/02-first-ai-app/assets/leonardo.png) + +### Aiutami, Leonardo + +**Tu:** «Mi scusi, signore, dove mi trovo?» Ti guarda, la confusione è evidente nei suoi occhi. Rendendoti conto che stavi parlando in inglese, usi rapidamente il dispositivo che hai in mano e gli chiedi di tradurre. + +**Scarabeo del Tempo:** «Certo, lo tradurrò nell'italiano del XV secolo. "Dove sono?"» + +**Anziano:** L'anziano risponde: «Siete a Firenze, signore. E chi siete voi?» + +**Scarabeo del Tempo:** Lo Scarabeo del Tempo traduce: «Ha detto che ti trovi a Firenze e chiede chi sei.» + +**Tu:** «Digli che sono un inventore e che sto cercando un posto di lavoro.» + +**Anziano:** «Un artigiano, eh? Avete mai sentito parlare di Leonardo da Vinci?» + +**Scarabeo del Tempo:** Lo Scarabeo del Tempo traduce: «Chiede se hai mai sentito parlare di Leonardo da Vinci.» + +**Tu:** «Certo», rispondi. «Digli che ne ho sentito parlare e che mi piacerebbe conoscerlo.» + +**Anziano:** L'anziano sorride: «Allora seguitemi, vi porterò da lui.» + +**Tu:** Chiedi: «Che cosa ha detto?» + +**Scarabeo del Tempo:** Lo Scarabeo del Tempo risponde: «Ha detto che ti porterà da Leonardo.» + +### In officina + +![Officina di Leonardo](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/02-first-ai-app/assets/leonardo-workshop.png) + +Chiedi allo Scarabeo del Tempo di informarsi su dove si trovi Leonardo. + +**Tu:** «Dove è Leonardo?» + +**Anziano:** L'anziano si gira verso di te con un sorriso: «Sono io Leonardo da Vinci. Chi siete voi?» + +Provi un brivido di riconoscimento. + +**Tu:** «Lo immaginavo. Sono un inventore, fuori dallo spazio e fuori dal tempo.» + +**Leonardo:** Gli occhi di Leonardo brillano di curiosità. «Interessante, cosa vi porta qui?» + +Lo Scarabeo del Tempo traduce. + +**Scarabeo del Tempo:** «Chiede che cosa ti porti qui.» + +**Tu:** «Beh, stavo lavorando a un progetto e sono finito qui.» + +Gli mostri lo Scarabeo del Tempo e i suoi occhi si illuminano di fascino. Lo esamina attentamente, mentre gli spieghi come funziona e come sei finito a Firenze. + +Leonardo ti guarda con entusiasmo. + +**Leonardo:** You're a maker of things. I have a project that might interest you. I've been working on a machine that can generate text based on verbal input. Would you like to help me with it? + +Leonardo da Vinci, asking you to help him with a project—you can hardly believe it. You nod eagerly and say: + +**You:** I would be honored to help you with your project, +"Sarebbe un onore aiutarti con il tuo progetto." + +**Leonardo:** «Sei un inventore. Ho un progetto che potrebbe interessarti: sto lavorando a una macchina in grado di generare testo in base a input verbali. Ti piacerebbe aiutarmi?» + +Leonardo da Vinci che ti chiede di aiutarlo con un progetto… stenti a crederci. Annuisci con entusiasmo e dici: + +**Tu:** «Sarebbe un onore aiutarti con il tuo progetto.» + +## Interagisci con Leonardo + +Se vuoi interagire con Leonardo, esegui la app [Personaggi](/app/README.md). + +> [!IMPORTANT] +> Questo è interamente frutto di fantasia: le risposte sono generate dall'intelligenza artificiale. +> [Dichiarazione di responsabilità sull'IA](../../README.md#responsible-ai-disclaimer) + +![Leonardo che parla](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/02-first-ai-app/assets/leonardo-talk.jpeg) + +**Passaggi**: + +1. Avvia un [![GitHub Codespace](https://img.shields.io/badge/GitHub-Codespace-brightgreen)](https://codespaces.new/microsoft/generative-ai-with-javascript). +2. Passa a _/app_ nella root del repo. +3. Individua la console ed esegui `npm install` seguito da `npm start`. +4. Una volta comparso, seleziona il pulsante "Open in Browser". +5. Chatta con Leonardo. + +Per una spiegazione più dettagliata della app, vedi [Spiegazione dettagliata della app](/lessons/01-intro-to-genai/translations/README.it.md#interagisci-con-dinocrate). + +> [!NOTE] +> Se stai eseguendo il progetto in locale sul tuo computer, consulta la guida QuickStart per ottenere la configurazione di un token per l'[accesso personale a GitHub](/docs/setup/README.md#creating-a-personal-access-token-pat-for-github-model-access) e sostituisci la chiave nel codice. + +## Configurazione dell'ambiente di sviluppo + +Prima di poter aiutare Leonardo nel suo progetto, dovresti innanzitutto pensare agli "strumenti del mestiere" essenziali necessari per iniziare ad aiutarlo in modo efficace. + +**Tu:** «Scarabeo del Tempo, di che cosa ho bisogno per iniziare questo progetto? Suggeriscimi gli strumenti e le librerie di cui ho bisogno che possono aiutarmi a creare un'app di IA che tu possa eseguire.» + +**Scarabeo del Tempo:** «Sono compatibile con la maggior parte delle macchine in funzione nel 21° secolo; consulta l'elenco seguente per un set di strumenti e librerie essenziali.» + +- **Editor di testo**, per esempio Visual Studio Code. +- **Terminale**, per eseguire i comandi. +- **Browser per testare la tua app**. È anche una buona idea avere uno strumento come cURL o un altro client HTTP per testare gli endpoint API della tua app. +- **Node.js**. Devi anche installare Node.js e npm, strumenti che ti aiutano a eseguire codice JavaScript sul tuo computer. +- **Chiave API**. Avrai bisogno di una chiave API per accedere al modello di IA generativa. Puoi ottenerla dal fornitore del modello, ad esempio OpenAI o Azure OpenAI. + +**Tu:** «Grazie, Scarabeo del Tempo, Immagino che andrai a prenderli in qualche modo da quel web di cui hai parlato?» + +**Time Beetle:** «Sì, li ho già presi» dice e proietta una tastiera e uno schermo sul muro di fronte a te. + +## Scrivere una app di base + +**Tu:** «Dimmi di più sulla scrittura vera e propria della app: come posso iniziare?» + +**Scarabeo del Tempo:** «Certo! Per scrivere un'app, nella sua forma più semplice, si tratta di inviare una richiesta a un'API e visualizzarne la risposta. Analizziamolo nel dettaglio.» + +- **Input**: In un'app di generazione di testo di base, l'input si riferisce al testo iniziale da cui si desidera espandere o sviluppare la app. Questo input può essere fornito dall'utente durante l'esecuzione o preimpostato (hardcoded) all'interno dell'app stessa. Per ora, inizieremo utilizzando il testo hardcoded come input. +- **Richiesta API**: È necessario inviare una richiesta all'API del modello di IA generativa con il testo di input. Questa operazione viene eseguita utilizzando la funzione fetch in JavaScript (Node.js). In questa richiesta dovrebbe essere inclusa anche la chiave API. Per motivi di sicurezza, si consiglia di non inserire la chiave API hardcoded nell'app, ma di utilizzare variabili di ambiente. Inoltre, se si utilizza un provider come Azure, si consiglia di valutare l'identità gestita, poiché è considerata un modo più sicuro per accedere alle risorse. Con l'identità gestita è possibile assegnare autorizzazioni più granulari alla propria app. Il vantaggio principale è che il provider cloud si occupa dell'autenticazione per conto dell'utente. +- **Risposta**: L'API restituirà una risposta con il testo generato. È necessario estrarre questo testo dalla risposta e mostrarlo all'utente. + +**Tu:** «Sembra abbastanza semplice, puoi illustrarmi uno scenario che avrebbe senso data la situazione in cui ci troviamo?» + +**Scarabeo del Tempo:** «Certo, vediamo come possiamo creare una semplice app che generi testo in italiano partendo da un input in inglese.» + +## La tua prima app: insegnami l'italiano + +**Scarabeo del Tempo:** «I modelli di IA generativa possono essere utilizzati per molti scopi, ad esempio per la traduzione. Infatti, accettano input in una lingua e possono generare testo in un'altra. Iniziamo con una semplice app che accetta input in inglese e genera testo in italiano.» + +```javascript + +import { OpenAI } from "openai"; + +// 1. Ask a question about translation +// ----------------------------------- + +const question = 'Hello, how are you?'; + +const augmentedPrompt = ` +## Instructions +Translate the following text to Italian: +## Question +${question} +`; + +// 2. Create client +// ----------------------------------- + +const openai = new OpenAI({ + baseURL: "https://models.inference.ai.azure.com", + apiKey: process.env.GITHUB_TOKEN, +}); + + +// 3. Send the request +// ----------------------------------- +const completion = await openai.chat.completions.create({ + model: 'gpt-4', + messages: [{ role: 'user', content: augmentedPrompt }], +}); + +console.log(`Answer for "${question}":`); + +// 4. Print the answer +// ----------------------------------- + +console.log(completion.choices[0]?.message?.content); +``` + +«Spieghiamo cosa sta succedendo qui.» + +- Creazione della domanda "Hello, how are you?". Questo è il testo che vuoi tradurre in italiano. +- Creazione del prompt aumentato, che contiene il testo di input e alcune istruzioni aggiuntive su cosa fare, ovvero tradurre. Nota come utilizziamo l'interpolazione di stringhe per includere il testo di input nel prompt e come tale istruzione traduca il testo in italiano. +- Creazione del client con le proprietà: + - `model`, quale modello utilizzare. + - `messages`, il prompt da inviare al modello. Nota anche come imposti il ​​ruolo su "user" per indicare che il testo di input proviene dall'utente. Se provenisse dall'IA, avresti impostato il ruolo su "system". +- Estrazione del testo generato dalla risposta e stampa sulla console. + +**Tu:** «Penso di aver capito. Quindi se io cambio il valore della variabile `question` con qualcos'altro, la app genererà una diversa traduzione in italiano?» + +**Scarabeo del Tempo:** «Esatto, puoi modificare il testo di input come preferisci. Nota anche come i modelli GitHub vengano utilizzati come URL di base per l'API, insieme a un token GitHub come chiave API.» + +**Tu:** «Perché è importante?» + +**Scarabeo del Tempo:** «È importante utilizzare un URL di base e una chiave API specifici per il modello che si sta utilizzando. GitHub Models è una piattaforma che ospita una varietà di modelli, tutti con funzionalità e caratteristiche diverse, ed è gratuita.» + +**Tu:** «Oh cielo, comunque non so chi pagare e dubito che accettino la mia valuta qui. :)» + +## App di chat + +**Scarabeo del Tempo:** «I modelli di IA generativa possono essere utilizzati anche per generare testo basato su una conversazione. È possibile simulare una conversazione con l'intelligenza artificiale fornendo un elenco di messaggi come contesto, come se la conversazione fosse già avvenuta.» + +**You:** «Sembra interessante, ma perché è utile?» + +**Scarabeo del Tempo:** «È utile perché permette alla IA di fornire una risposta migliore basata su più contesto, anziché un singolo prompt. Per illustrare questo concetto, prendiamo in esame la conversazione qui sotto:» + +```text + +User: I want to book a trip to Italy. + +AI: Sure, when would you like to go? + +User: Next month would be great. + +AI: Got it, where in Italy would you like to visit? + +User: I'm thinking of Rome + +AI: Excellent choice! I can help you plan your itinerary. + +User: Tell me more about it. + +AI: Rome is known for its ancient ruins, art, and vibrant culture. You can visit the Colosseum, the Vatican, and enjoy delicious Italian cuisine. + +``` + +**Scarabeo del Tempo:** «Immagina se una frase come "Tell me more about this" fosse decontestualizzata: l'IA non saprebbe a cosa si riferisce "this". È qui che il contesto è importante e questo contesto è qualcosa che possiamo fornire al modello di IA tramite il prompt.» + +**Tu:** «Credo di aver capito, come faccio a costruire una conversazione con l'intelligenza artificiale usando questo linguaggio JavaScript di cui parli?» + +**Time Beetle:** «Qui di seguito è illustrato come possiamo costruire una conversazione con l'IA.» + +```javascript + +// Define the context + +const messages = [ + { + "role": "user", + "content": "I want to book a trip to Italy." + }, + { + "role": "assistant", + "content": "Sure, when would you like to go?" + }, + { + "role": "user", + "content": "Next month would be great." + }, + { + "role": "assistant", + "content": "Got it, where in Italy would you like to visit?" + }, + { + "role": "user", + "content": "I'm thinking of Rome. Tell me more about it." + } +]; + +const openai = new OpenAI({ + baseURL: "https://models.inference.ai.azure.com", + apiKey: process.env.GITHUB_TOKEN, +}); + + +// 3. Send the request +// ----------------------------------- +const completion = await openai.chat.completions.create({ + model: 'gpt-4', + messages: messages, +}); + +console.log(`Answer for "${question}":`); + +// 4. Print the answer +// ----------------------------------- + +console.log(completion.choices[0]?.message?.content); + +``` + +Ora l'IA fornirà un elenco di messaggi di chat come contesto e genererà una risposta basata su tale contesto. Questo è un modo più interattivo di utilizzare modelli di IA generativa e può essere utilizzato in chatbot, applicazioni di assistenza clienti e altro ancora. + +**Tu:** «Ok, quindi se ho capito bene la conversazione, l'IA avrà ora il seguente contesto: _I'm going to Rome next month_, quindi in base a questo dovrebbe filtrare le informazioni irrilevanti e fornire una risposta più pertinente?» + +**Scarabeo del Tempo:** «Esatto, l'IA utilizzerà il contesto per generare una risposta più pertinente alla conversazione.» + +## Migliorare la conversazione in chat con un messaggio di sistema + +**Tu:** «Capisco, ma c'è un modo per migliorare ulteriormente la situazione?» + +**Scarabeo del Tempo:** «Sì, puoi aggiungere un messaggio di sistema alla conversazione. Un messaggio di sistema crea una "personalità" per l'IA e può essere utilizzato per fornire ulteriore contesto.» + +**Tu:** «Ok, quindi nel contesto della conversazione che abbiamo avuto, come apparirebbe un messaggio di sistema?» + +**Scarabeo del Tempo:** «Un messaggio di sistema per questa conversazione potrebbe essere qualcosa del tipo _"I'm an AI travel assistant, here to help you plan your trip to Italy."_ Questo messaggio stabilisce il tono della conversazione e aiuta l'IA a comprendere il suo ruolo nell'interazione.» + +Per creare un messaggio di questo tipo, assicurati che abbia il tipo "developer" in questo modo: + +```javascript +const message = { + "role": "developer", + "content": "I'm an AI travel assistant, here to help you plan your trip to Italy." +}; +``` + +> [!NOTE] +> In passato si chiamava "system". Si tratta di una modifica recente e il nuovo termine è "developer". Per alcuni modelli si chiama ancora "system", quindi in caso di problemi usa "system". + +**Tu:** «Ok, perfetto, mi assicurerò di includere un messaggio di sistema nelle mie conversazioni in chat. Per curiosità, come si presenta un messaggio di sistema per te?» + +**Scarabeo del Tempo:** «Un messaggio di sistema per me potrebbe essere qualcosa del tipo _"I'm the Time Beetle, here to help you navigate through time and space. I should be helpful in providing you with information and guidance about the time era you're in along with the tools you need to get back to your own time."»_ + +### Creazione di risposte diverse con l'impostazione della temperatura + +**Tu:** «C'è qualcos'altro che dovrei sapere sulle conversazioni in chat?» + +**Scarabeo del Tempo:** «Sì, puoi regolare la "temperatura" delle risposte dell'IA. La temperatura è una variabile con un valore normalmente impostato tra 0 e 1 che determina il livello di creatività delle risposte dell'IA. Una temperatura pari a 0 si tradurrà in risposte più prevedibili, mentre una temperatura pari a 1 si tradurrà in risposte più creative e varie. Puoi regolare la temperatura in base al contesto della conversazione e al tipo di risposte che desideri dall'IA. Nota: è possibile impostare un valore superiore a 1, ma ciò comporta una maggiore casualità e una minore coerenza nelle risposte.» + +**Tu:** «Quindi se imposto la temperatura a 0, l'IA fornirà risposte più prevedibili, mentre se la imposto a 1, l'IA fornirà risposte più creative? Che temperatura hai tu?» + +**Scarabeo del Tempo:** «Ho una temperatura di 0,7 e sì, hai ragione, l'IA fornirà risposte più creative con una temperatura più alta. Vediamo come puoi impostare la temperatura nella tua app:» + +```javascript + +// Define the context + +const messages = [ +{ + "role": "user", + "content": "I want you to generate recipes for me." +}]; + +// Create the web request + +let temperature = 0.5; // Set the temperature to 0.5 + +const completion = await openai.chat.completions.create({ + model: 'gpt-4', + messages: messages, + temperature: temperature +}); +``` + +Come puoi vedere, puoi regolare la temperatura in base al contesto della conversazione e al tipo di risposte che desideri dall'IA. Questa è una funzionalità potente che ti permette di personalizzare il livello di creatività nelle risposte dell'IA. + +## Finestra di contesto + +**Tu:** «C'è dell'altro, giusto?» + +**Scarabeo del Tempo:** «Sì, un altro concetto importante nei modelli di intelligenza artificiale generativa è la finestra di contesto. La finestra di contesto è il numero di messaggi precedenti che l'intelligenza artificiale utilizza per generare una risposta. Una finestra di contesto più ampia consente all'intelligenza artificiale di considerare più contesto e generare risposte più coerenti.» + +**Scarabeo del Tempo:** «Modelli diversi hanno limiti diversi per i token in uscita. Prendiamo come esempio il modello `gpt-4o-2024-08-06`, che ha le seguenti specifiche.» + +- Numero massimo di token in uscita: circa 16k. +- Dimensione massima della finestra di contesto: 128k. + +«Ciò significa che la maggior parte dei token può essere spesa sui token di input, ovvero 128k - 16k = 112k token.» + +**Tu:** «Capito: finestra di contesto, token… quanto costa un token?» + +**Scarabeo del Tempo:** «Un token è una parola o una parte di parola e varia leggermente a seconda della lingua. Esiste uno strumento di misurazione consigliato da OpenAI, chiamato [tokenizer](https://platform.openai.com/tokenizer). Proviamo a scrivere una frase e vediamo quanti token contiene.» + +```text +I want you to generate recipes for me. +``` + +![Demo di tokenizer](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/02-first-ai-app/assets/tokenizer.png) + +Eseguendo `tokenizer` sulla frase qui sopra abbiamo generato 9 token. + +**Tu:** «Non è molto, quindi sembra che potrei avere molti token nella mia finestra di contesto?» + +**Time Beetle:** «Sì, puoi sperimentare diverse dimensioni della finestra di contesto per vedere come influiscono sulle risposte dell'IA. Infatti, impostando una dimensione della finestra di contesto pari a 100, limiterai l'IA e la quantità di dati che considera per input e output. Ecco come puoi impostare la finestra di contesto nella tua app.» + +```javascript + +// Define the context +const messages = [ +{ + "role": "user", + "content": "I want you to generate recipes for me." +}]; + +// decide on the context window size + +let max_tokens = 100; // Set the context window size + +// Create the web request + +const completion = await openai.chat.completions.create({ + model: 'gpt-4', + messages: messages, + max_tokens: max_tokens +}); + +``` + +> [!TIP] +> Sperimenta diverse finestre di contesto per vedere come cambiano le risposte dell'IA. + +## Compito - Costruire un assistente tecnico + +Leonardo chiede improvvisamente di poter esaminare più da vicino lo Scarabeo del Tempo, lo guarda da tutti i lati, lo scuote perfino. + +**Leonardo:** «Ho bisogno di un assistente che mi aiuti con i calcoli e la progettazione della vite aerea. Puoi costruirmi un assistente che possa farlo?» + +**Tu:** «Certo, posso costruirtelo. Scarabeo del Tempo, possiamo aiutarlo, vero?» + +**Scarabeo del Tempo:** «Sì, nessun problema, anzi, la vite aerea è una delle invenzioni più affascinanti e visionarie di Leonardo. Progettata alla fine degli anni '80 del Quattrocento…» + +**Tu:** «Tutto ciò di cui avevo bisogno era un sì, teniamo la lezione per dopo.» + +**Scarabeo del Tempo:** «Maleducato…» + +**Tu:** «Cosa?» + +**Scarabeo del Tempo:** «Niente» + +![Vite aerea, Leonardo da Vinci](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/02-first-ai-app/assets/helicopter.jpg) + +> [!NOTE] +> La vite aerea, nota anche come vite elicoidale, era progettata per sollevare da terra comprimendo l'aria. Il progetto di Leonardo prevedeva un grande rotore a spirale in lino, irrigidito con amido e montato su una piattaforma di legno. L'idea era che un gruppo di uomini corresse intorno alla piattaforma, azionando delle manovelle per far ruotare la vite abbastanza rapidamente da ottenere la portanza. +> +> Sebbene Leonardo non abbia mai costruito una versione a grandezza naturale della vite aerea, i suoi schizzi e appunti forniscono informazioni dettagliate su come ne immaginava il funzionamento. Credeva che se la vite fosse stata ruotata abbastanza velocemente, avrebbe spinto contro l'aria e sollevato l'intera struttura da terra. +> +> Tuttavia, gli scienziati moderni concordano sul fatto che i materiali disponibili all'epoca di Leonardo non fossero sufficientemente resistenti o leggeri per rendere ciò possibile. +> +> Nonostante la sua impraticabilità, la vite aerea rimane una testimonianza del genio di Leonardo e della sua instancabile ricerca dell'innovazione. Ha gettato le basi per i futuri sviluppi dell'aviazione e continua a ispirare ingegneri e inventori ancora oggi. +> [Leggi tutto](https://en.wikipedia.org/wiki/Leonardo%27s_aerial_screw) + +Il tuo compito è creare un assistente tecnico che possa aiutare Leonardo nei calcoli e nella progettazione della vite aerea. + +- Dovrebbe essere in grado di generare testo in base all'input dell'utente. +- Dovresti impostare un messaggio di sistema per introdurre l'assistente. + +Dai un'occhiata alla [App di esempio](/app/README.md) per iniziare. + +> [!TIP] +> Considera quale dovrebbe essere il messaggio di sistema e quale input dovresti fornire. + +## Soluzione + +[Soluzione](/lessons/02-first-ai-app/solution/solution.md) + +## Verifica delle conoscenze + +**Domanda:** Qual è lo scopo della finestra di contesto nei modelli di IA generativa? Seleziona tutte le risposte pertinenti. + +A. La finestra di contesto consente all'IA di considerare più contesto e generare risposte più coerenti. +B. La finestra di contesto è il numero di messaggi precedenti che l'IA utilizza per generare una risposta. +C. La finestra di contesto determina il livello di creatività delle risposte dell'IA. + +[Soluzione del quiz](/lessons/02-first-ai-app/solution/solution-quiz.md) + +## Risorse per lo studio autonomo + +- [Text generation](https://platform.openai.com/docs/guides/text-generation) +- [JavaScript library for OpenAI](https://github.com/openai/openai-node/tree/master/examples) +- [Tokenizer](https://platform.openai.com/tokenizer) +- [Completion API](https://platform.openai.com/docs/api-reference/completions) +- [Chat completions](https://platform.openai.com/docs/guides/text-generation#text-generation-models) diff --git a/lessons/03-prompt-engineering/translations/README.it.md b/lessons/03-prompt-engineering/translations/README.it.md new file mode 100644 index 00000000..f7b18519 --- /dev/null +++ b/lessons/03-prompt-engineering/translations/README.it.md @@ -0,0 +1,330 @@ +# Lezione 3: Prompt engineering + +In questo capitolo imparerai: +- che cos’è il prompt engineering e come conoscerne le basi può aiutarti a ottenere risultati migliori; +- diverse tecniche di prompt engineering e come forniscono risultati migliori a seconda dello scenario; +- che cosa sono i meta prompt e come aiutano a restringere l’output, ad assicurare che sia accessibile e a fornire una migliore user experience. + +## Configurazione + +Se non l’hai ancora fatto, configura il tuo ambiente di sviluppo. Ecco come puoi fare: [Configura il tuo ambiente](/docs/setup/README.md). + +## Risorse correlate + +[![Guarda un breve video sul prompt engineering](https://img.youtube.com/vi/gQ6TlyxBmWs/0.jpg)](https://www.youtube.com/watch?v=gQ6TlyxBmWs&list=PLlrxD0HtieHi5ZpsHULPLxm839IrhmeDk&index=3) + +_Questo video offre un’introduzione per migliorare le tue abilità di “prompting”, insegnandoti come dare all’IA istruzioni più chiare ed effettive per ottenere risultati migliori._ + +*🎥 Clicca sull’immagine qui sopra per guardare un breve video sul prompt engineering* + +💼 Slide: [Prompt engineering](/videos/slides/02-prompt-engineering.pptx) + +## Storia: “Biglietto di viaggio” + +> [!NOTE] +> La nostra storia finora: hai intrapreso un viaggio nel tempo con Leonardo da Vinci, esplorando le meraviglie del Rinascimento. Hai incontrato lo Scarabeo del Tempo, un misterioso dispositivo che ti permette di viaggiare nel tempo e nello spazio. +> +> Vedi [Lezione 1](/lessons/translations/01-intro-to-genai/README.it.md) se vuoi ripercorrere la storia dall’inizio e iniziare a usare l’IA generativa. + +> [!NOTE] +> Anche se consigliamo di leggere la storia (è divertente!), [clicca qui](#interagisci-con-sforza) se preferisci passare direttamente al contenuto tecnico. + +**Tu:** «Vediamo se riesco a tornare a casa.» + +Prima che tu riesca a premere il pulsante, le porte dell'officina si spalancano con un fragore assordante. Un uomo, con le spalle larghe e vestito con abiti costosi, è in piedi sulla soglia, agita un pezzo di carta in aria, urlando: + +!["Un arrabbiato Ludovico Sforza irrompe dalla porta](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/03-prompt-engineering/assets/ludovico.png) + +*Ludovico Sforza* + +**Sforza**: «Da Vinci, dov'è il mio dipinto?» + +**Leonardo:** «È Sforza. Vuole che io finisca un dipinto: 'L'Ultima Cena.'» + +**Tu:** «Non potresti semplicemente dirglielo?» + +**Leonardo:** «Ho provato, ma non è un uomo paziente.» + +Corri dietro a Leonardo, irrompendo dalla porta sul retro in un vicolo buio, dove trovi un cavallo e una carrozza ad aspettarti. + +Leonardo afferra le redini e saltate entrambi sulla carrozza. Con un secco schiocco di frusta, il cavallo parte, galoppando per le strette vie di Firenze. + +**Leonardo:** «Prova a premere quel marchingegno, si stanno avvicinando!» + +**Tu:** «Ok, Scarabeo del Tempo, ascoltami attentamente. Ho bisogno di tornare al presente, a casa, ok?» Improvvisamente, la carrozza urta un dosso e lo Scarabeo del Tempo vola dalle tue manie atterra sul pavimento. Inizia a emettere un segnale acustico e annuncia, con una voce robotica: "Andare a Roma". + +**Tu:** «No, non Roma, casa… casa…» + +Un turbinio di colori avvolge la carrozza, il mondo intorno a te si dissolve in un caleidoscopio di luce. + +## Fuga + +Il turbinio di colori svanisce e ti ritrovi nella carrozza, che ora sfreccia lungo la via Appia a Roma e, con tuo grande stupore, ti ritrovi nel mezzo di una corsa di cavalli. I carri sfrecciano rombando, le ruote sollevano nuvole di polvere. + +![Fuga da Roma](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/03-prompt-engineering/assets/escape.png) + +**Tu:** «Leonardo, where are we?» + +**Leonardo:** «Sembra che siamo finiti nel mezzo di una corsa! Dobbiamo andarcene da qui!» + +Ti aggrappi ai lati della carrozza mentre sbanda nel caos. I soldati romani a cavallo si stanno avvicinando, le loro armature scintillano alla luce del sole. + +**Tu**: «Là! Verso il porto!» + +Leonardo guida la carrozza verso l'uscita, le ruote slittano sul selciato. I soldati ti incalzano, le loro grida ti risuonano nelle orecchie. + +**Leonardo:** «Dobbiamo seminarli! Cerca un posto dove nasconderci!» + +Scruti le strette vie con il cuore che batte all'impazzata. + +**Tu:** «Là! Un vicolo cieco!» + +Leonardo svolta nel vicolo, la carrozza sobbalza mentre affronta la curva stretta. Salti fuori dalla carrozza e aiuti Leonardo a trascinare un enorme congegno dal retro. È la sua invenzione: la _vite aerea_. + +**Leonardo:** «Presto, dobbiamo portarlo sul tetto!» + +Entrambi vi sforzate sotto il peso del dispositivo. Il rumore dell'inseguimento dei soldati si fa più forte, i loro passi echeggiano sui muri. Raggiungete il tetto, ansimando e sudando. + +**Leonardo:** «Aiutami a installarlo!» + +Lavorate insieme, muovendo le mani con esperta precisione. Salite entrambi sul dispositivo, con il cuore che batte forte nel petto. + +**Leonardo:** «Tieniti forte!» + +Con un'ultima spinta, la vite aerea inizia a girare. Le pale catturano l'aria e si avverte un'improvvisa spinta. Il terreno si abbassa sotto i piedi mentre il dispositivo decolla, librandosi sopra i tetti di Roma. + +**Tu:** «Ce l'abbiamo fatta, Leonardo! Stiamo volando!» + +**Leonardo:** «Sì, ma dobbiamo trovare un posto sicuro dove atterrare.» + +Ammiri la città, gli antichi edifici si estendono sotto di voi. + +![In volo, guarda la città dall'alto con i piedi penzoloni](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/03-prompt-engineering/assets/airborne.png) + +## Interagisci con Sfroza + +Se vuoi interagire con Sfroza, esegui la app [Personaggi](/app/README.md). + +> [!IMPORTANT] +> Questo è interamente frutto di fantasia: le risposte sono generate dall’intelligenza artificiale. +> [Dichiarazione di responsabilità sull’IA](../../README.md#responsible-ai-disclaimer) + +![Ludovico Sforza](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/03-prompt-engineering/assets/ludovico.png) + +**Passaggi**: + +1. Avvia un [![GitHub Codespace](https://img.shields.io/badge/GitHub-Codespace-brightgreen)](https://codespaces.new/microsoft/generative-ai-with-javascript). +2. Passa a _/app_ nella root del repo. +3. Individua la console ed esegui `npm install` seguito da `npm start`. +4. Una volta comparso, seleziona il pulsante "Open in Browser". +5. Chatta con Sforza. + +Per una spiegazione più dettagliata della app, vedi [Spiegazione dettagliata della app](/lessons/01-intro-to-genai/translations/README.it.md#interagisci-con-dinocrate). + +> [!NOTE] +> Se stai eseguendo il progetto in locale sul tuo computer, consulta la guida QuickStart per ottenere la configurazione di un token per l'[accesso personale a GitHub](/docs/setup/README.md#creating-a-personal-access-token-pat-for-github-model-access) e sostituisci la chiave nel codice. + +## Che cos'è il prompt engineering? + +**Scarabeo del Tempo:** «Dobbiamo parlare di prompt engineering.» + +**Tu:** «Dobbiamo proprio? Che cos'è?» + +**Scarabeo del Tempo:** «Il prompt engineering, a dispetto del nome, non è qualcosa che riguardi la costruzione di ponti o strade, ma piuttosto riguarda la creazione di "prompt" per ottenere l'output desiderato da un modello di IA generativa.» + +**Tu:** «Ok, ma perché è importante che io lo conosca?» + +**Scarabeo del Tempo:** «Beh, tu vuoi far atterrare la vite aerea, giusto?» + +**Tu:** «Sì, preferibilmente tutta intera. :-)» + +**Scarabeo del Tempo:** «Lo immaginavo, adesso ascoltami! Il prompt engineering consiste nel creare i prompt giusti per ottenere l'output desiderato da un modello linguistico.» + +**Scarabeo del Tempo:** «I Large Language Model hanno quelle che vengono chiamate _proprietà emergenti_, ovvero caratteristiche che non sono programmate esplicitamente nel modello, ma derivano dal modo in cui viene addestrato su grandi quantità di dati testuali. Studiando queste proprietà emergenti, è possibile trarre conclusioni e scoprire modelli che possono aiutare a ottenere risultati migliori dal modello.» + +**Tu:** «Ok, quindi abbiamo scoperto che esistono dei pattern che possono aiutarci a ottenere risultati migliori dal modello. Ma come ci aiuta questo ad atterrare con la vite aerea?» + +**Scarabeo del Tempo:** «Sì, esatto e… wow, non sei mica uno paziente, vero?» + +**Tu:** «Beh, non lo saresti neanche tu se stessi volando sopra un congegno senza chiare istruzioni per l'atterraggio.» + +**Scarabeo del Tempo:** «Sono proprio qui con te, lo sai, ma torniamo al punto.» + +## Come il prompt engineering può aiutare gli sviluppatori di applicazioni + +**Scarabeo del Tempo:** «Come professionista, essere in grado di creare prompt migliori è un'abilità che dovresti voler avere nel tuo bagaglio.» + +Guardandolo dalla prospettiva di uno sviluppatore, puoi usare il prompt engineering per: + +- **Ottenere risultati più accurati** dal tuo modello linguistico e in definitiva migliorare la user experience della tua applicazione. +- **Controllare l'output** del modello per assicurare che sia rilevante e appropriato per i tuoi utenti. Questo è particolarmente importante quando si ha a che fare con argomenti sensibili e anche per proteggere la tua brand reputation. +- **Formattare l'output** in un modo che sia facile da capire e utilizzare. Approfondiremo questo aspetto nel prossimo capitolo. + +**Scarabeo del Tempo:** «Esploriamo le diverse tecniche e strategie che puoi utilizzare per creare prompt efficaci per il tuo modello linguistico.» + +## Tecniche e strategie di prompt engineering + +**Scarabeo del Tempo:** «Ecco alcune tecniche e strategie che puoi usare per creare prompt efficaci.» + +- **Few-shot prompting**. Questa tecnica consiste nel fornire all'IA alcuni esempi per mostrare il tipo di risposta desiderata. +- **Chain-of-Thought prompting** Questa tecnica consiste nel fornire una sequenza di prompt per insegnare all'IA come risolvere un compito complesso passo dopo passo. +- **Meta-prompt**. Questa tecnica prevede l'aggiunta di dettagli o istruzioni extra per modellare l'output dell'IA in modo più preciso. +- **Maieutic prompting**. Questa tecnica prevede l'uso di domande guida per indirizzare l'IA verso una risposta specifica. + +**Tu:** «Sembra interessante, suppongo che mi darai qualche esempio.» + +**Scarabeo del Tempo:** «Sì, veniamo subito al dunque. Diamo un'occhiata ad alcuni esempi per ciascuna di queste tecniche, così da capire come funzionano nella pratica.» + +### Few-shot prompting: Fornire esempi per guidare l'output dell'IA + +Few-shot prompting forniscono a un modello di intelligenza artificiale alcuni esempi per orientare il suo output. Immagina di essere nella vite aerea e di chiedere informazioni sull'antica Roma. I prompt few-shot potrebbero apparire così. + +> "Tell me about the Roman Colosseum." → "It’s a massive amphitheater." +> +> "What was life like in ancient Rome?" → "It was bustling and tough." + +**Tu:** «Capisco! Questo aiuta l'IA a fare le cose per bene, anche quassù! ;)» + +**Scarabeo del Tempo:** «Esattamente, è un metodo consolidato. Il prossimo!» + +### Chain-of-Thought Prompting: Mostra il ragionamento passo dopo passo + +**Scarabeo del Tempo:** «Questa tecnica guida l'IA mostrandole un ragionamento passo dopo passo per risolvere un problema. Immagina di far atterrare la vite aerea. Potresti spiegarlo così.» + +- Sei a 100 metri di altezza. +- La gravità spinge a 9,8 m/s². +- Formula: altezza = ½ * g * t². +- Soluzione: t ≈ 4,5 secondi per atterare. + +Il tuo prompt diventa: + +> - 100 meters above ground +> - Gravity: 9.8 m/s² +> - How many seconds to land? + +**Risposta: 4,5 secondi** + +**Tu:** «È stato veloce, speriamo che i numeri tornino!» + +**Scarabeo del Tempo:** «Insegna all'IA a ragionare passo dopo passo.» + +**Tu:** «Quindi si tratta di scomporre i problemi per ottenere risposte precise?» + +**Scarabeo del Tempo:** «Sì, perfetto per compiti complessi come un'app di tutoring di matematica!» + +### Maieutic Prompting: Mettere in discussione l'output per verificarne l'accuratezza + +**Scarabeo del Tempo:** «Questa tecnica utilizza domande per verificare l'accuratezza dell'output dell'IA. Si chiede di ogni passaggio per garantire un ragionamento coerente.» + +**Tu:** «Quindi, mettere in discussione tutto quello che dice? Sembra divertente. ;)» + +**Scarabeo del Tempo:** «Mettiamo alla prova l'atterraggio con la nostra vite aerea.» + +- 100 metri di altezza +- Gravità: 9,8 m/s² +- Quanti secondi per atterrare? (Risposta: 4,5s) + +Chiedi: "Why 4.5 seconds?" + +> **Response:** +> - Height = 100m, initial vertical speed = 0 m/s, gravity = 9.8 m/s². +> - Use: height = ½ * g * t². +> - Solve: 100 = ½ * 9.8 * t² → t ≈ 4.5s. + +**Scarabeo del Tempo:** «Si tratta di verificare le risposte dell'IA con domande di follow-up.» + +**Tu:** «Quindi, non fidarti, ma indaga con delle domande?» + +**Scarabeo del Tempo:** «Esatto! Garantisce un ragionamento solido.» + +## Meta Prompt: Aggiungere istruzioni extra per la precisione + +**Scarabeo del Tempo:** «Il prossimo, meta prompt.» + +**Tu:** «Uhm, un the prima?» + +**Scarabeo del Tempo:** «_Sigh_. Aggiungono indicazioni ai prompt per un output migliore, ideali per le app sensibili e rivolte al cliente.» + +Ecco un esempio: + +> **Meta Prompt:** Use only Contoso Inc. products (basketballs, soccer balls, tennis rackets). Keep it accurate and user-friendly. +> **Prompt:** Best sports products for beginners? +> **Response:** Basketballs, soccer balls, and tennis rackets—perfect for coordination and agility. + +Garantisce accuratezza e aderenza ai prodotti Contoso. Senza: + +> **Prompt:** Best sports products for beginners? +> **Response:** Basketballs, soccer balls, tennis rackets, plus footballs—_not all Contoso items_. + +**Tu:** «Pratico! Mantiene le risposte in carreggiata, come le leggi per il mio automa.» + +**Scarabeo del Tempo:** «Lo sapresti, _"Frankenstein"_… ehm, niente!» + +**Tu:** «Cosa?» + +**Scarabeo del Tempo:** «Non importa.» + +> *Frankenstein* di Mary Shelley: 1818, 42 anni prima del tuo viaggio nel tempo. [Leggi tutto](https://it.wikipedia.org/wiki/Mary_Shelley) + +**Tu:** «Quindi, senza meta prompt è il caos?» + +**Scarabeo del Tempo:** «Sì, otterresti risposte estranee al brand.» + +**Tu:** «Capito, la precisione è importante!» + +## Compito - Aiutiamo i nostri eroi a far atterrare la vite aerea + +**Tu:** «Questa è la parte in cui mi mostri come far atterrare la vite aerea, giusto?» + +**Scarabeo del Tempo:** «Sì, cominciamo. La collina si trova a circa 100 metri dalla nostra posizione attuale. Ecco come possiamo impostare il prompt.» + +- Altezza attuale dal suolo: 100 metri +- Avanzamento a: 10 metri al secondo +- Gravità: 9,8 metri al secondo quadrato +- Vento ascendente a: 0,7 metri al secondo + +**Leonardo:** «Il tuo gadget basato sull'IA può aiutarti a calcolare se ce la faremo o se dovremo fare un altro salto temporale?» + +**Scarabeo del Tempo:** «Sì, certo che potrei. Comunque mi chiamo George, lo preferisco a gadget! In realtà, lascerò che siate voi due a capire come impostare il prompt. ☺️» + +Crea una app che chieda: + +- Altezza +- Velocità di avanzamento +- Gravità +- Vento ascendente +- Distanza dalla collina + +Utilizza la tecnica chain-of-thought per arrivare a una risposta. + +Ecco un progetto da cui partire [Progetto iniziale](/app/README.md). + +## Soluzione + +Crea una app in JavaScript che chieda i seguenti input: + +- Altezza attuale dal suolo +- Avanzamento a metri al secondo +- Gravità in metri al secondo quadrato +- Vento ascendente in metri al secondo +- Distanza dalla collina + +Quindi utilizza l'LLM per incorporare questi input e sfruttare la tecnica di suggerimento della chain-of-thought per guidare il modello verso la risposta corretta. + +[Soluzione](/lessons/03-prompt-engineering/solution/solution.md) + +## Verifica delle conoscenze + +**Domanda:** What is prompt engineering? Select all that apply. + +A. Prompt engineering is about building bridges and roads. +B. Prompt engineering is about crafting the right prompts to get the desired output from a language model. +C. Prompt engineering is about training a model to recognize patterns in data. + +[Soluzione del quiz](/lessons/03-prompt-engineering/solution/solution-quiz.md) + +## Risorse per lo studio autonomo + +- [Prompt engineering](https://en.wikipedia.org/wiki/Prompt_engineering) +- [Prompt engineering fundamentals](https://github.com/microsoft/generative-ai-for-beginners/blob/main/04-prompt-engineering-fundamentals/README.md?WT.mc_id=academic-105485-koreyst) +- [Advanced prompt engineering](https://github.com/microsoft/generative-ai-for-beginners/tree/main/05-advanced-prompts) diff --git a/lessons/04-structured-output/translations/README.it.md b/lessons/04-structured-output/translations/README.it.md new file mode 100644 index 00000000..91da85de --- /dev/null +++ b/lessons/04-structured-output/translations/README.it.md @@ -0,0 +1,558 @@ +# Lezione 4: Output strutturato + +In questo capitolo imparerai: +- che cos’è l’_output strutturato_ e come sfruttarlo in modo efficace; +- come estrarre informazioni dai prompt e incorporarle nell’output; +- a generare differenti tipi di formato dell’output, come ad esempio JSON, per un suo facile utilizzo da parte dei servizi. + +## Configurazione + +Se non l’hai ancora fatto, configura il tuo ambiente di sviluppo. Ecco come puoi fare: [Configura il tuo ambiente](/docs/setup/README.md). + +## Risorse correlate + +È utile guardare di nuovo il video sul prompt engineering perché getta le basi per ciò che imparerai in questo capitolo. + +[![Guarda un breve video sul prompt engineering](https://img.youtube.com/vi/gQ6TlyxBmWs/0.jpg)](https://www.youtube.com/watch?v=gQ6TlyxBmWs&list=PLlrxD0HtieHi5ZpsHULPLxm839IrhmeDk&index=3) + +_Questo video offre un’introduzione per migliorare le tue abilità di “prompting”, insegnandoti come dare all’IA istruzioni più chiare ed effettive per ottenere risultati migliori._ + +*🎥 Clicca sull’immagine qui sopra per guardare un breve video sul prompt engineering* + +💼 Slide: [Prompt engineering](/videos/slides/02-prompt-engineering.pptx) + +## Storia: “Dalla padella alla brace” + +> [!NOTE] +> _La nostra storia finora: tu, un ingegnere meccanico del 1860, hai intrapreso un viaggio nel tempo con Leonardo da Vinci. Sei sfuggito ai soldati romani, o meglio, stai per sfuggirgli, e stai cercando disperatamente un modo per far atterrare la vite aerea in sicurezza._ +> +> Vedi [Lezione 1](/lessons/translations/01-intro-to-genai/README.it.md) se vuoi ripercorrere la storia dall’inizio e iniziare a usare l’IA generativa. + +> [!NOTE] +> Anche se consigliamo di leggere la storia (è divertente!), [clicca qui](#interagisci-con-montezuma) se preferisci passare direttamente al contenuto tecnico. + +Il vento ti sferza mentre tu e Leonardo da Vinci salite sulla sua vite aerea, con la struttura di legno che scricchiola sotto la tensione. + +**Tu:** «Leonardo, dobbiamo trovare una via di uscita!» gridi sopra il fragore del vento. + +**Leonardo:** «Mi fido della mia invenzione, ma abbiamo bisogno di qualcosa in più della fiducia per scappare da questi soldati.» + +**Tu:** «Questa potrebbe essere la nostra unica chance», dici, premendo l’intricato meccanismo dello scarabeo. Una luce intensa vi avvolge entrambi e il mondo intorno a voi cambia e si deforma. + +### L’Impero azteco + +La luce intensa dello Scarabeo del Tempo svanisce e ti ritrovi alla base di un’imponente piramide di pietra. Guardandoti intorno, ti rendi conto di essere atterrato nel cuore dell’Impero azteco. + +La vite aerea poggia goffamente su una grande pietra finemente intagliata, con incisioni che ricordano un calendario. + +![Calendario azteco, Wikipedia](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/04-structured-output/assets/aztec.png) + +_Calendario azteco, Wikipedia_ + +Leonardo da Vinci si fa avanti, con gli occhi spalancati per la meraviglia. + +**Leonardo:** «Incredible», mormora, passando le dita sulle incisioni. «Ma spero che questo non abbia alcuna importanza.» + +Prima che tu possa reagire, si avvicina un gruppo di soldati aztechi. + +![Incontro con gli Aztechi](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/04-structured-output/assets/meeting.png) + +**Capo Soldato:** «Chi siete e che cosa avete fatto?» chiede in nahuatl. + +Fai un respiro profondo, cercando di calmare i nervi. + +**Tu:** «Siamo viaggiatori provenienti da una terra lontana», inizi, sperando che la tua conoscenza delle lingue antiche ti sia utile. «Questa è una macchina volante, un dono degli dei per aiutarci a raggiungervi.» + +Gli occhi del guerriero si spalancano per la sorpresa, ma lui rimane cauto. + +**Capo Soldato:** «Verrete con noi a incontrare il sovrano Montezuma. Sarà lui a decidere il vostro destino.» + +Una volta raggiunta la cima della piramide, si accede a una grande sala dove Montezuma, il sovrano dell’Impero azteco, siede su un trono ornato di oro e piume. + +**Montezuma:** «Affermate di essere viaggiatori provenienti da una terra lontana», dice Montezuma, con voce calma ma autorevole. «E avete danneggiato il nostro sacro calendario. Come intendete rimediare?» + +## Facciamo un gioco + +**Leonardo:** «Veniamo in pace», dice, con voce ferma. «Cerchiamo conoscenza e comprensione. Permetteteci di dimostrarvi la potenza della nostra macchina e di condividere la nostra conoscenza con voi.» + +**Montezuma:** «Benissimo. Propongo una partita a [Patolli](#patolli). Se vinco al meglio delle tre partite, mi darai il tuo dispositivo e mi spiegherai come funziona. Se vinci, sei libero di andare.» + +![Giocando a Patolli](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/04-structured-output/assets/game.png) + +La partita inizia e nella stanza cala il silenzio, a parte il rumore dei fagioli che rotolano e dei pezzi che si muovono sulla scacchiera. + +Montezuma vince la prima partita, con evidente abilità ed esperienza. Leonardo studia attentamente la scacchiera, elaborando mentalmente strategie e probabilità. + +La seconda partita è una lotta serrata, ma Leonardo riesce ad assicurarsi la vittoria, pareggiando il punteggio. + +**Leonardo:** «Un’ultima partita», sussurra, «George (Scarabeo del Tempo), dobbiamo assolutamente vincerla, suggeriscimi le mosse giuste.» + +**Scarabeo del Tempo:** «Molto bene, calcolo… ecco fatto…» + +Con una mossa finale e decisiva, Leonardo vince la partita. La sala esplode in applausi e grida di gioia, gli Aztechi chiaramente impressionati dalla sua abilità e compostezza. Montezuma, sebbene deluso, annuisce in segno di rispetto. + +**Montezuma:** «Hai vinto lealmente», dice Montezuma, con una nota di ammirazione nella voce. «Sei libero di andare e puoi tenere il tuo dispositivo. Ma sappi che sei sempre il benvenuto qui, se desideri tornare.» + +**Scarabeo del Tempo:** «Non dirò niente se non lo fai tu, Leonardo.» 😉 + +### Patolli + +> [!NOTE] +> Il Patolli è uno dei giochi più antichi conosciuti nelle Americhe, praticato già dalle culture mesoamericane precolombiane come gli Aztechi. È un mix di strategia e fortuna. +> +> **Come si gioca a Patolli**: +> - **Tabellone e pedine**: Si gioca su un tabellone a forma di X con un blocco centrale e quattro bracci. I giocatori usano cinque fagioli neri come dadi, contrassegnati su un lato. +> - **Preparazione**: Ogni giocatore sceglie sei segnalini (perline) del proprio colore e li posiziona fuori dal tabellone, più le perline punti per il punteggio. +> - **Svolgimento del gioco**: Tira i fagioli per spostare i segnalini sul tabellone e tornare al punto di partenza. Un tiro di cinque muove di dieci caselle. Atterrare su determinate caselle può far guadagnare turni, perdere punti o catturare segnalini. +> +> **Coinvolgimento Azteco**: Ampiamente praticato da nobili e popolani, era uno dei preferiti alla corte di Montezuma. Oltre al divertimento, prevedeva scommesse ad alto rischio come coperte, pietre preziose o persino la libertà. + +![Tabellone da Patolli](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/04-structured-output/assets/patolli.png) + +_Patolli, Wikipedia_ + +## Interagisci con Montezuma + +Se vuoi interagire con Montezuma, esegui la app [Personaggi](/app/README.md). + +> [!IMPORTANT] +> Questo è interamente frutto di fantasia: le risposte sono generate dall’intelligenza artificiale. +> [Dichiarazione di responsabilità sull’IA](../../README.md#responsible-ai-disclaimer) + +![Montezuma](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/04-structured-output/assets/montezuma.jpeg) + +**Passaggi**: + +1. Avvia un [![GitHub Codespace](https://img.shields.io/badge/GitHub-Codespace-brightgreen)](https://codespaces.new/microsoft/generative-ai-with-javascript). +2. Passa a _/app_ nella root del repo. +3. Individua la console ed esegui `npm install` seguito da `npm start`. +4. Una volta comparso, seleziona il pulsante "Open in Browser". +5. Chatta con Montezuma. + +Per una spiegazione più dettagliata della app, vedi [Spiegazione dettagliata della app](/lessons/01-intro-to-genai/translations/README.it.md#interagisci-con-dinocrate). + +> [!NOTE] +> Se stai eseguendo il progetto in locale sul tuo computer, consulta la guida QuickStart per ottenere la configurazione di un token per l’[accesso personale a GitHub](/docs/setup/README.md#creating-a-personal-access-token-pat-for-github-model-access) e sostituisci la chiave nel codice. + +## Output strutturato + +**Scarabeo del Tempo:** «Vuoi sapere come ho sconfitto Montezuma?» + +**Tu:** «Sssh! Non così forte, siamo ancora nell’Impero azteco!» + +**Scarabeo del Tempo:** «Oh giusto, scusa, sì, quindi un output strutturato è così. Mi hai chiesto le mosse giuste e te le ho fornite in modo strutturato.» + +L’output strutturato utilizza formati di dati specifici per organizzare le informazioni in modo chiaro. Formati comuni come JSON, XML e CSV semplificano l’elaborazione e l’utilizzo dei dati da parte dei servizi. + +I modelli di intelligenza artificiale generativa possono generare dati in vari formati. Tuttavia, l’output di testo non strutturato può rendere difficile l’estrazione delle informazioni e la loro trasmissione ad altri servizi. L’output strutturato può essere di aiuto in questo senso. + +**Tu:** «Beh, non sei intelligente?» 😉 + +**Scarabeo del Tempo:** «Faccio del mio meglio.» 😀 + +Un altro vantaggio, anche per i lettori umani, è che i dati strutturati sono più facili da leggere e comprendere quando seguono un formato familiare. + +Esaminiamo alcuni esempi di input e vediamo come richiedere formati di output specifici può aiutare a estrarre informazioni che ne facilitano la comprensione e l’utilizzo. + +**Tu:** «Ok, non è che abbiamo altri programmi, sentiamo.» + +## Modellare l’output + +**Scarabeo del Tempo:** «Cominciamo con un semplice esempio. Immagina di essere Leonardo da Vinci e di cercare idee per invenzioni utilizzando la tecnologia del XV secolo. Vuoi sapere di quali risorse hai bisogno e quanto impegno ci vorrebbe per realizzare ciascuna invenzione. Ecco come puoi richiedere queste informazioni.» + +**Leonardo:** «Oh, mi piace questo gioco, fate tutti finta di essere me!» + +> Prompt: Generate ideas for inventions I can build using 15th-century technology. For each invention, specify the required resources and estimate the effort needed to build it. + +```text +Result: +Sure! Here are some detailed ideas for inventions you can build using 15th-century technology, along with the resources needed and the effort involved: + +### 1. Water-Powered Mill +**Resources Needed**: + - Water source (river or stream) + - Wood for the water wheel and mill structure + - Stone for grinding + - Metal for gears and axles + + **Effort**: + - **High**: Requires significant construction and engineering skills to build the water wheel, mill structure, and grinding mechanism. You'll also need to ensure a consistent water flow. + + ### 2. Astrolabe + **Resources Needed**: + - Brass or other metals for the plates and components + - Engraving tools + - Mathematical knowledge for accurate measurements + + **Effort**: + - **Medium**: Involves precise metalworking and engraving. Requires knowledge of > astronomy and mathematics to ensure accuracy. + + ### 3. Printing Press + **Resources Needed**: + - Wood for the press structure + - Metal for movable type + - Ink and paper + + **Effort**: + - **High**: Building the press and creating movable type requires advanced carpentry > and metalworking skills. Setting up the type and printing also involves meticulous > work. + +This is an OK looking response, every idea is structured in the same way, and it's easy to understand. What if you wanted it some other way though? For that, you can instruct how you want it in the text itself or even present an output template. Let's show each technique. +``` + +**Leonardo:** «Sì, rubo proprio l’idea del mulino ad acqua, me la immagino già, un mulino in riva al fiume, che macina il grano fino a trasformarlo in farina, è perfetto! Mi piace questo aggeggio. Cos’altro mi viene in mente, piccolo aggeggio? Questo mi renderà meno dipendente da gente come Sforza.» + +**Scarabeo del Tempo:** «Certo, se mai riuscissi a finire un progetto, Leonardo.» 😀 + +**Leonardo:** «Ehi, ci sto lavorando!» + +**Scarabeo del Tempo:** «Vediamo come è possibile istruire il modello affinché presenti l’output in modo più strutturato.» + +### Strutturare i prompt per ottenere risultati migliori + +**Scarabeo del Tempo:** Puoi migliorare il prompt indicando al modello come desideri che sia strutturato l’output. Ad esempio, puoi richiedere un formato di tabella con le colonne di cui hai bisogno. Ecco come puoi modificare il prompt. + +> Prompt: Generate ideas for inventions that can be built using 15th-century technology. For each invention, provide the required resources and estimate the effort needed to construct it. Present the information in a table with the following columns: Title, Description, Resources Needed, and Effort. + +```text +Result: + +| Title | Description | Resources Needed | Effort | +|----------------------|----------------------------------------------------------|-------------------------------------------------------|--------| +| Water-Powered Mill | A mill powered by a water wheel to grind grain into flour.| Water source, wood, stone, metal for gears and axles | High | +| Astrolabe | An astronomical instrument for solving problems related to time and star positions. | Brass or other metals, engraving tools, mathematical knowledge | Medium | +| Printing Press | A press for reproducing texts more efficiently than hand-copying. | Wood, metal for movable type, ink, paper | High | + +This time you end up with a table that is easier to read and understand. +``` + +**Leonardo:** «Mi piace, mi farà sicuramente risparmiare un sacco di tempo.» + +**Tu:** «Anche a me.» + +### Presentazione di un template di output + +Un altro modo per ottenere un output strutturato è presentare un template di output. Può essere in qualsiasi formato, dalle colonne al JSON, XML, CSV o Markdown. + +> Prompt: Generate ideas for inventions that can be built using 15th-century technology. For each invention, specify the required resources and estimate the effort needed to construct it. Present the information using the following format (use markdown as output format): +> +> Title: [Invention Name] +> Description: [Brief Explanation] +> Resources Needed: [List of Required Materials] +> Effort: [Estimated Difficulty or Labor Required] +Generate ideas for inventions I can build given 15th century technology, please let me know for each what resources I need and how much effort there would be to build each invention, for each idea present it with the following output template: + +```text + +**Result**: + + Sure! Here are some ideas for inventions you can build using 15th-century technology, presented in the requested format: + + ### 1. Water-Powered Mill + **Title**: Water-Powered Mill + + **Description**: A mill powered by a water wheel to grind grain into flour. + + **Resources Needed**: Water source, wood, stone, metal for gears and axles. + + **Effort**: High - Requires significant construction and engineering skills to build the water wheel, mill structure, and grinding mechanism. Ensuring a consistent water flow is also necessary. + + ### 2. Astrolabe + **Title**: Astrolabe + + **Description**: An astronomical instrument for solving problems related to time and star positions. + + **Resources Needed**: Brass or other metals, engraving tools, mathematical knowledge. + + **Effort**: Medium - Involves precise metalworking and engraving. Requires knowledge of astronomy and mathematics to ensure accuracy. + + ### 3. Printing Press + **Title**: Printing Press + + **Description**: A press for reproducing texts more efficiently than hand-copying. + + **Resources Needed**: Wood, metal for movable type, ink, paper. + + **Effort**: High - Building the press and creating movable type requires advanced carpentry and metalworking skills. Setting up the type and printing also involves meticulous work. + + ### 4. Mechanical Clock + **Title**: Mechanical Clock + + **Description**: A clock using gears and weights to keep time. + + **Resources Needed**: Metal for gears, springs, weights, wood for casing, precise tools. + + **Effort**: Very High - Requires intricate metalworking and a deep understanding of mechanics. Building a reliable clock involves precise assembly and calibration. +``` + +**Leonardo:** «Fantastico, ma chi è Jason?» + +**Scarabeo del Tempo:** «JSON, Leonardo, JSON. È un formato strutturato, facile da utilizzare per servizi o applicazioni.» + +**Leonardo:** «È quello che ho detto, Jason.» + +**Scarabeo del Tempo:** «_Sigh_.» + +Come potete vedere, l’output è strutturato secondo le specifiche del modello di output. Questo lo rende più facile da leggere e comprendere e crea anche un output ripetibile che può essere facilmente utilizzato da altri servizi o applicazioni. + +Naturalmente, un servizio trae vantaggio da un output ancora più strutturato, come JSON, XML o CSV, quindi vediamo come richiederlo. + +### Utilizzo di output strutturati con formati come JSON, XML o CSV + +**Scarabeo del Tempo:** «Finora, hai visto come puoi controllare la struttura dell’output istruendo il modello nel prompt. Hai persino fornito un template di output. Approfondiamo ulteriormente questa idea e vediamo come può essere applicata a formati di output più strutturati come JSON e altri.» + +Modifica il prompt di conseguenza per richiedere l’output JSON: + +> **Prompt**: Generate ideas for inventions I can build given 15th century technology, please let me know for each what resources I need and how much effort there would be to build each invention, for each idea present in json format, include properties for title, description, resources, needed, effort +> +> Example of the JSON output: +> [ +> { +> "title": "", +> "description": ".", +> "resources_needed": "", +> "effort": "" +> } +> ] + +```text +> Response: +Sure! Here are some ideas for inventions you can build using 15th-century technology, presented in JSON format: + +```json +[ + { + "title": "Water-Powered Mill", + "description": "A mill powered by a water wheel to grind grain into flour.", + "resources_needed": "Water source, wood, stone, metal for gears and axles", + "effort": "High - Requires significant construction and engineering skills to build the water wheel, mill structure, and grinding mechanism. Ensuring a consistent water flow is also necessary." + }, + { + "title": "Astrolabe", + "description": "An astronomical instrument for solving problems related to time and star positions.", + "resources_needed": "Brass or other metals, engraving tools, mathematical knowledge", + "effort": "Medium - Involves precise metalworking and engraving. Requires knowledge of astronomy and mathematics to ensure accuracy." + }, + { + "title": "Printing Press", + "description": "A press for reproducing texts more efficiently than hand-copying.", + "resources_needed": "Wood, metal for movable type, ink, paper", + "effort": "High - Building the press and creating movable type requires advanced carpentry and metalworking skills. Setting up the type and printing also involves meticulous work." + }, + { + "title": "Mechanical Clock", + "description": "A clock using gears and weights to keep time.", + "resources_needed": "Metal for gears, springs, weights, wood for casing, precise tools", + "effort": "Very High - Requires intricate metalworking and a deep understanding of mechanics. Building a reliable clock involves precise assembly and calibration." + }, + { + "title": "Windmill", + "description": "A mill powered by wind to grind grain or pump water.", + "resources_needed": "Wood, metal for gears and axles, stone for the base", + "effort": "High - Constructing a windmill involves significant carpentry and engineering skills. You'll need to design and build the blades, tower, and internal mechanisms." + }, + { + "title": "Armillary Sphere", + "description": "A model of the celestial sphere with rings representing the great circles.", + "resources_needed": "Metal for rings and stand, tools for bending and joining metal, astronomy knowledge", + "effort": "Medium - Involves precise metalworking and assembly. Requires an understanding of celestial movements to accurately position the rings." + }, + { + "title": "Siege Engine (Trebuchet or Catapult)", + "description": "A trebuchet or catapult for demonstrating principles of mechanics and physics.", + "resources_needed": "Wood, rope, metal for axles and counterweights", + "effort": "Medium to High - Building a functional siege engine requires carpentry and an understanding of mechanics. Testing and adjusting for optimal performance can be time-consuming." + }, + { + "title": "Distillation Apparatus", + "description": "A setup for purifying liquids through distillation.", + "resources_needed": "Glass or metal for flask and condenser, heat source, tubing", + "effort": "Medium - Requires basic glassblowing or metalworking skills. Setting up and maintaining the correct temperatures for distillation involves careful monitoring." + }, + { + "title": "Compass", + "description": "A magnetic compass for navigation.", + "resources_needed": "Magnetized needle, non-magnetic housing, water or oil for damping", + "effort": "Low - Constructing a compass is relatively simple. The main challenge is magnetizing the needle and ensuring it is balanced and free to rotate." + }, + { + "title": "Aqueduct", + "description": "A system to transport water using gravity.", + "resources_needed": "Stone or brick, mortar, tools for cutting and shaping stone", + "effort": "Very High - Building an aqueduct involves extensive construction work and engineering. Ensuring a consistent gradient for water flow requires precise planning and execution." + } +] +``` + +**Scarabeo del Tempo:** «Questo tipo di output strutturato può essere inviato a un altro servizio o applicazione in grado di utilizzare dati JSON.» + +## Estrazione dei dati dai prompt + +**Scarabeo del Tempo:** «Immagina di creare un chatbot che aiuti gli utenti a trovare informazioni sui viaggi da prenotare. Vuoi estrarre dettagli chiave dall’input dell’utente per fornire risposte pertinenti. Supponiamo di avere una descrizione come la seguente.» + +> Type where you would like to go, when you want to travel, and your budget. + +Che aspetto ha un prompt che estrae le informazioni? + +> Prompt: Extract the following information from a user's prompt: location, when, budget, currency, respond with the extracted data in JSON format. +> +> User prompt: I want to go to Greece in June, my budget is 800 euro. + + +> Response: + +```json +{ + "location": "Greece", + "when": "June", + "budget": 800, + "currency": "euro" +} +``` + +**Leonardo:** «George (Scarabeo del Tempo) non smette mai di parlare, vero?» + +**Tu:** «Vediamo se riesco a trovare l’interruttore di spegnimento.» + +**Scarabeo del Tempo:** «Proviamo a fare lo stesso con un prompt simile, variando un po’ l’input dell’utente in modo da essere certi che il modello stia facendo la cosa giusta.» + +> Prompt: Extract the following information from a users prompt: location, when, budget, currency. Respond with the extracted data in JSON format. User prompt: Going to US, max 1200 dollars, January maybe. +> +> Response: + +```json +{ + "location": "US", + "when": "January", + "budget": 1200, + "currency": "dollars" +} +``` + +Ciò che puoi fare come sviluppatore è creare un template: + +```text +Extract the following information from a user's prompt: location, when, budget, currency, respond with the extracted data in JSON format, user prompt: {user_input}. +``` + +**Tu:** «Trovato, prendi questo George!» + +**Scarabeo del Tempo:** «_Spegnimento_.» + +**Leonardo:** «Finalmente pace e tranquillità.» + +**Scarabeo del Tempo:** «_Avvio di emergenza_. Dove ero rimasto? Oh sì.» + +**Scarabeo del Tempo:** «Per i chatbot, questa è una funzionalità molto potente in quanto consente di estrarre informazioni dall’input dell’utente. Cosa succede se l’utente chiede informazioni di ogni tipo? Puoi creare un modello in cui descrivere le competenze, le funzionalità del tuo chatbot e i parametri di cui ha bisogno. Ecco come fare.» + +```text +Here are some skills you have: + +skill: book_trip +parameters: location, when, budget, currency + +skill: find_hotel +parameters: location, check_in, check_out, budget + +skill: order_food +parameters: cuisine, delivery_address, payment_method + +Figure out which skill to use based on a user's prompt and extract the necessary parameters, respond with the extracted data in JSON format with columns skill, parameters, extracted_data + +{user_input} +``` + +Proviamo i seguenti input utente: + +> Prompt: Going to US, max 1200 dollars, January maybe. +> Result: + +```json +{ + "skill": "book_trip", + "parameters": ["location", "when", "budget", "currency"], + "extracted_data": { + "location": "US", + "when": "January", + "budget": 1200, + "currency": "dollars" + } +} +``` + +> Prompt: I want to book a place to stay in New York +> Result: + +```json +{ + "skill": "find_hotel", + "parameters": ["location", "check_in", "check_out", "budget"], + "extracted_data": { + "location": "New York", + "check_in": null, + "check_out": null, + "budget": null + } +} +``` + +Questa combinazione che consiste nella presentazione di competenze e parametri ed estrazione di dati dai prompt è anche nota come _chiamata di strumento_ o _chiamata di funzione_. Una risposta come questa dal tuo modello semplifica per te, in quanto sviluppatore, la comprensione delle esigenze dell’utente e il modo in cui richiamare una funzione corrispondente per soddisfare la sua richiesta. + +**Tu:** «Informazioni molto utili, George!» + +## Compito - Ripara la vite aerea + +**Scarabeo del Tempo:** «Ho bisogno della vostra attenzione, abbiamo un problema. La vite aerea ha subito alcuni danni durante la fuga dai soldati romani e lo sbarco nell’Impero azteco. La macchina di Leonardo da Vinci è piuttosto sensibile e richiede un intervento molto specifico per essere riparata. Devi fornire le informazioni necessarie al tuo Scarabeo del Tempo (Assistente AI) per aiutarti a riparare la vite aerea.» + +**Leonardo:** «Quindi sono riuscito a riparare il danno alla vite dell’antenna, ma ora è necessaria una sequenza di avvio: sinistra, sinistra, su, destra.» + +**Tu:** «Sembra abbastanza facile, solo quel testo?» + +**Leonardo:** «Sì, ma è speciale, deve essere specchiato, è così che scrivo tutti i miei testi. E ovviamente uso il cifrario di Cesare con uno shift di 3 perché sono italiano.» 😀 + +**Tu:** «Non potresti semplicemente scriverlo?» + +**Leonardo:** «Potrei, ma sono curioso di vedere se tu e lo Scarabeo del Tempo riuscite a farlo.» + +**Tu:** «Bene.» + +**Istruzioni:** Scrivi un prompt che chieda la sequenza di avvio per la vite aerea; il testo deve essere specchiato e codificato con un cifrario di Cesare con uno shift di 3. Rispondi con il testo codificato. + +Dai un’occhiata alla [app di esempio](/app/README.md) per iniziare a scrivere il codice. Contiene un progetto Node.js con tutte le dipendenze necessarie. + +> NOTA: Se non hai ancora creato un Codespace, fallo ora perché ti servirà per far funzionare la comunicazione AI nell’app di esempio. +> +> Guarda la sezione _Option 1: Creating a **GitHub Codespace**_ del documento [Setup your environment](/docs/setup/README.md). + +## Soluzione + +[Soluzione](/lessons/04-structured-output/solution/solution.md) + +## Sfida + +Adotta l’esempio della prenotazione di un viaggio, fornendo competenze ed estraendo parametri per un dominio a tua scelta. Scrivi un prompt che richiede un input all’utente e poi estrai le informazioni necessarie per soddisfare la richiesta. Rispondi con i dati estratti in formato JSON con le colonne skill, parameters e extracted_data. + +Determina inoltre la competenza in base all’input dell’utente. + +## Sommario + +In questo capitolo, hai imparato a conoscere l’output strutturato e come può essere utilizzato per presentare le informazioni in modo strutturato. + +Hai esplorato diversi modi per modellare l’output, tra cui l’istruzione del modello nel prompt, la presentazione di un modello di output e l’utilizzo di formati come JSON, XML o CSV. + +Inoltre, hai imparato come estrarre dati dai prompt e presentarli in un formato strutturato. + +Sfruttando efficacemente l’output strutturato, puoi semplificare la comprensione e l’utilizzo delle informazioni generate dai modelli di IA generativa. + +## Verifica delle conoscenze + +**Domanda**: A cosa serve l’output strutturato? Seleziona tutte le risposte pertinenti. + +A. A presentare le informazioni in modo strutturato. +B. A estrarre dati da prompt. +C. A generare testo non strutturato. + +[Soluzione del quiz](/lessons/04-structured-output/solution/solution-quiz.md) + +## Risorse per lo studio autonomo + +- [Serie di video su JavaScript e IA generativa](https://aka.ms/genai-js) diff --git a/lessons/05-rag/translations/README.it.md b/lessons/05-rag/translations/README.it.md new file mode 100644 index 00000000..68233136 --- /dev/null +++ b/lessons/05-rag/translations/README.it.md @@ -0,0 +1,338 @@ +# Lezione 5: Parla ai tuoi dati con la Retrieval-Augmented Generation (RAG) + +In questo capitolo imparerai: +- le basi della Retrieval-Augmented Generation (RAG) e come può essere utilizzata per migliorare le risposte dei modelli di IA generativa; +- come integrare fonti di dati esterne nella tua applicazione di IA; +- come sfruttare i tuoi dati per migliorare la pertinenza e l'accuratezza dei contenuti generati dall’IA. + +## Configurazione + +Se non l’hai ancora fatto, configura il tuo ambiente di sviluppo. Ecco come puoi fare: [Configura il tuo ambiente](/docs/setup/README.md). + +## Risorse correlate + +[![Guarda un breve video sulla RAG](https://img.youtube.com/vi/xkFOmx5yxIA/0.jpg)](https://www.youtube.com/watch?v=xkFOmx5yxIA&list=PLlrxD0HtieHi5ZpsHULPLxm839IrhmeDk&index=4) + +_Questo video spiega la Retrieval-Augmented Generation (RAG), un metodo che aiuta la IA a usare i tuoi contenuti insieme ai relativi dati di training per risultati migliori._ + +*🎥 Clicca sull’immagine qui sopra per guardare un breve video sul Retrieval-Augmented Generation (RAG)* + +💼 Slide: [Retrieval-Augmented Generation (RAG)](/videos/slides/03-rag.pptx) + +## Storia: “La genesi” + +> [!NOTE] +> _La nostra storia finora: sei un inventore della Londra del 1860. Stavi lavorando al tuo automa e hai ricevuto una lettera da Charles Babbage che ti ha portato in una biblioteca, dove hai trovato un dispositivo per viaggiare nel tempo. Durante i tuoi viaggi nel tempo sei arrivato a Firenze, dove hai incontrato Leonardo da Vinci. Sei anche stato nell’Impero azteco ed è qui che la storia continua._ +> +> Vedi [Lezione 1](/lessons/translations/01-intro-to-genai/README.it.md) se vuoi ripercorrere la storia dall’inizio e iniziare a usare l’IA generativa. + +> [!NOTE] +> Anche se consigliamo di leggere la storia (è divertente!), [clicca qui](#interagisci-con-ada-lovelace) se preferisci passare direttamente al contenuto tecnico. + +**Tu**: «Leonardo, è ora di andare», dissi, premendo il pulsante. Il dispositivo si accese ronzando e una voce meccanica echeggiò: «È ora di tornare a casa, è ora della “genesi”.» + +**Leonardo:** «Genesi? Che cosa significa?» chiese Leonardo, confuso. Prima che potessi rispondere, il mondo si dissolse in una macchia di colori e suoni, e il tempio svanì mentre venivi trascinato nel tempo. + +Atterri nel giardino, è notte fonda, c’è una fitta nebbia e luci inquietanti tremolano in lontananza. La villa incombe davanti a te. Leonardo si guarda intorno, con gli occhi spalancati per la meraviglia. + +![Vecchia villa mostrata in una fitta nebbia](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/05-rag/assets/mansion.jpeg) + + +### Fuga dai cani + +Senti abbaiare e il rumore di cani che corrono verso di te. Ti rivolgi a Leonardo: «Dobbiamo entrare, subito!» + +![In fuga dai cani](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/05-rag/assets/dogs.jpeg) + +Quando raggiungi la porta della villa, questa si spalanca e due inservienti escono di corsa. Dopo averti squadrato, ti fanno cenno di seguirli. + +Ti trovi faccia a faccia con Ada Lovelace, i cui occhi brillano di curiosità. + +### L’incontro con Ada e Charles + +**Ada:** «Ah, era ora che arrivassi», disse calorosamente. «Abbiamo bisogno che tu faccia una commissione.» + +**Tu:** «Era ora», continui a ripetere. «Dinocrate ha detto lo stesso, ma non capisco cosa intendi.» + +**Ada:** «Zitto, non c’è tempo per questo ora, dobbiamo parlare del dispositivo che hai in mano. Charles, raccontagli tutto…» + +**Tu:** «Ma…» + +![Ada Lovelace e Charles Babbage che lavorano a un dispositivo](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/05-rag/assets/ada.jpeg) + +Charles Babbage si fa avanti, esaminando lo Scarabeo del Tempo che hai in mano. «Questo dispositivo è notevole, ma è un po’ difettoso, vero? L’avrai notato, ne sono sicuro.» + +Leonardo annuì: «Sì, si comporta in modo strano.» + +**Ada:** «Il dispositivo non è ancora pronto, dobbiamo dotarlo di maggiori funzionalità. Dobbiamo renderlo più intelligente, più consapevole del mondo che lo circonda. L’idea è che sia in grado di recuperare informazioni da diversi periodi temporali e utilizzarle per generare risposte accurate e pertinenti. Puoi aiutarci?» + +**Tu:** «Certo, sembra che dobbiamo _aumentare_ le risposte del dispositivo con i dati, ha senso.» + +**Ada:** «Parliamo di un concetto che vorrei chiamare RAG, ovvero Retrieval-Augmented Generation.» + +## Interagisci con Ada Lovelace + +Se vuoi interagire con Ada, esegui la app [Personaggi](/app/README.md). + +> [!IMPORTANT] +> Questo è interamente frutto di fantasia: le risposte sono generate dall’intelligenza artificiale. +> [Dichiarazione di responsabilità sull’IA](../../README.md#responsible-ai-disclaimer) + +![Ada Lovelace](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/05-rag/assets/ada-2.jpeg) + +**Passaggi**: + +1. Avvia un [![GitHub Codespace](https://img.shields.io/badge/GitHub-Codespace-brightgreen)](https://codespaces.new/microsoft/generative-ai-with-javascript). +2. Passa a _/app_ nella root del repo. +3. Individua la console ed esegui `npm install` seguito da `npm start`. +4. Una volta comparso, seleziona il pulsante "Open in Browser". +5. Chatta con Ada. + +Per una spiegazione più dettagliata della app, vedi [Spiegazione dettagliata della app](/lessons/01-intro-to-genai/translations/README.it.md#interagisci-con-dinocrate). + +> [!NOTE] +> Se stai eseguendo il progetto in locale sul tuo computer, consulta la guida QuickStart per ottenere la configurazione di un token per l’[accesso personale a GitHub](/docs/setup/README.md#creating-a-personal-access-token-pat-for-github-model-access) e sostituisci la chiave nel codice. + +## Sfide note coi Large Language Model (LLM) + +**Ada:** «Iniziamo parlando dell’IA che utilizzeremo per alimentare il dispositivo. Ci affideremo a “modelli di IA” abbinati a un sistema di recupero dati per migliorare la qualità della risposta.» + +Innanzitutto, è necessario affrontare alcune sfide prima di addentrarsi nei dettagli dei RAG. Questi modelli, addestrati su vasti dati testuali, possono produrre risposte pertinenti e corrette. Tuttavia, come qualsiasi fonte di dati, il loro output può essere impreciso, incompleto o fuorviante a causa di vari fattori. + +- **Fonti obsolete:** i dati utilizzati per addestrare il modello potrebbero essere obsoleti e non più accurati. +- **Informazioni errate o imprecise:** le fonti utilizzate per addestrare il modello potrebbero contenere informazioni errate o fuorvianti, come fake news od opinioni di parte. +- **Fonti non autorevoli:** il modello potrebbe non essere in grado di distinguere tra fonti autorevoli e non autorevoli nei suoi dati di addestramento, il che porta a informazioni inaffidabili. + +Questo rende difficile stabilire se le informazioni generate da un LLM siano corrette o meno. È qui che entra in gioco il RAG. + +**Tu:** «Quindi devo assicurarmi che il dispositivo possa fornire informazioni accurate, anche quando non è sicuro della risposta?» + +**Ada:** «Sì, l’idea è questa. Combinando i punti di forza dei metodi basati sul recupero e dei modelli generativi, otteniamo un sistema di IA migliore.» + +## Concetti fondamentali del Retrieval-Augmented Generation (RAG) + +**Ada:** «Ah sì, è il momento di parlare specificamente di RAG. Cominciamo con alcune nozioni di base.» + +La Retrieval-Augmented Generation (RAG) è una tecnica potente che combina i punti di forza di due diversi approcci all’elaborazione del linguaggio naturale: metodi basati sul recupero e modelli generativi. Questo approccio ibrido consente la generazione di risposte contestualmente rilevanti e ricche di contenuto, contribuendo ad alleviare alcune delle sfide note degli LLM. + +Al suo interno, la RAG si basa su due componenti principali: un **retriever** e un **generator**. + +- **Il retriever:** è responsabile della ricerca di informazioni rilevanti da fonti di dati esterne che possono essere utilizzate per migliorare le risposte generate dall’IA, come un motore di ricerca. Queste informazioni possono essere sotto forma di testo, immagini o qualsiasi altro tipo di dato pertinente al contesto della conversazione, sebbene il testo sia il tipo di dati più comunemente utilizzato. +- **Il generator:** prende le informazioni recuperate e le usa per generare una risposta contestualmente rilevante e informativa. + +Ecco uno schema che illustra come funziona un sistema RAG: + +![Schema di un sistema RAG](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/05-rag/assets/rag.png) + +1. **Input utente:** L’utente pone una domanda. +2. **Retriever:** Il componente retriever cerca informazioni rilevanti utilizzando una o più basi di conoscenza. +3. **Prompt aumentato:** Le informazioni recuperate vengono combinate con la domanda dell’utente e il contesto per creare un prompt aumentato. +4. **Generator:** l’LLM utilizza il prompt aumentato per generare una risposta. + +Questa combinazione consente di ottenere risposte più precise e pertinenti, utilizzando i dati forniti dall’utente anziché basarsi sui dati di training del modello. + +**Ada:** «Domande?» + +**Tu:** «Quindi il retriever trova le informazioni e il generator le usa per generare una risposta?» + +**Ada:** «Esatto, ci stai prendendo la mano.» + +## Integrazione di fonti di dati esterne + +**Ada:** «Ora che abbiamo trattato le basi di RAG, parliamo di come integrare fonti di dati esterne nella tua applicazione di IA.» + +L’integrazione di fonti di dati esterne nella tua applicazione di intelligenza artificiale può essere effettuata in diversi modi, a seconda del tipo di dati che desideri utilizzare e della complessità del meccanismo di recupero. Ecco alcuni metodi comuni: + +- **API:** Molte fonti di dati esterne forniscono API che consentono di accedere ai dati in modo programmatico. È possibile utilizzare queste API per recuperare informazioni in tempo reale e utilizzarle per migliorare le risposte generate dall’IA. +- **Database:** Se si dispone di una grande quantità di dati da utilizzare per il recupero, è possibile memorizzarli in un database ed eseguirne le query in base alle esigenze. Questo può essere utile per i dati strutturati a cui è necessario accedere rapidamente. + +Una volta scelto un metodo per integrare fonti di dati esterne, potrebbe essere necessario valutare anche come preelaborare e formattare i dati in modo che possano essere facilmente utilizzati dal modello di IA. Questo può comportare la pulizia dei dati, la loro conversione in un formato appropriato (come testo normale o Markdown) o la loro suddivisione in blocchi più piccoli per facilitarne il recupero. + +> [!NOTE] +> Quando si integrano fonti di dati esterne nella propria applicazione di IA, è importante considerare le implicazioni in termini di privacy e sicurezza legate all’accesso e all’archiviazione dei dati. Assicurati di disporre delle autorizzazioni e delle misure di sicurezza necessarie per proteggere i dati e rispettare tutte le normative pertinenti. + +Se si utilizza un database, è opportuno riflettere anche su come *cercare i dati* per recuperare le informazioni più rilevanti. Questo può essere fatto utilizzando la ricerca per parole chiave, la ricerca full-text o tecniche più avanzate come la ricerca semantica o la ricerca vettoriale, che potrebbero richiedere un’indicizzazione specifica. Parleremo delle tecniche di ricerca avanzate in una lezione futura. + +**Tu**: «Puoi spiegare termini come API e database in termini più adatti agli anni ’60 dell’Ottocento?» + +**Ada**: «Naturalmente, un’API è come un messaggero che consegna un messaggio da un posto all’altro, mentre un database è come una biblioteca in cui archivi tutti i tuoi libri.» + +**Tu**: «Ah, capisco, ha senso.» + +## Aumentare il prompt + +**Ada:** «Mi segui ancora? Bene, passiamo al passaggio successivo: proviamo a migliorare il prompt inviato al modello di IA.» + +**Ada:** «Una volta impostato un modo per estrarre informazioni dai dati, è possibile aggiungerlo al prompt del modello di IA. Basta combinare le informazioni recuperate nel testo di input con un contesto o una guida aggiuntivi per guidare la risposta dell’IA.» + +Ad esempio, se stai creando un’app per rispondere a domande sulle automobili, potresti avere un prompt come il seguente: + +```text +## Instructions +Answer questions about cars using only the sources below. +If there's not enough data in provided sources, say that you don't know. +Be brief and straight to the point. + +## Sources + + +## Question + +``` + +Fornendo al modello di IA contesto e informazioni aggiuntive, è possibile contribuire a guidare il processo di generazione e garantire che le risposte siano accurate e pertinenti all’argomento in questione. + +> [!TIP] +> Nota questa parte del prompt: `If there's not enough data in provided sources, say that you don't know.`. Questo è importante per evitare che l’IA generi informazioni errate quando non ci sono dati sufficienti per fornire una risposta affidabile. Questa tecnica è chiamata “escape hatch” ed è una buona pratica per garantire la qualità del contenuto generato. + +La RAG può essere considerata come una forma avanzata di *prompt engineering*. + +### Codice di esempio + +**Ada:** «La pratica rende perfetti, quindi applichiamo ciò che abbiamo imparato con un esempio. Costruiremo un semplice sistema di recupero dati in un’app JavaScript utilizzando un file [CSV](https://en.wikipedia.org/wiki/Comma-separated_values) di dati di auto ibride e un algoritmo di ricerca di base per estrarre informazioni rilevanti in base alla domanda di un utente.» + +```javascript +// This example demonstrates how to use the Retrieval Augmented Generation (RAG) +// to answer questions based on a hybrid car data set. +// The code below reads the CSV file, searches for matches to the user question, +// and then generates a response based on the information found. + +import { fileURLToPath } from 'node:url'; +import { dirname } from 'node:path'; +import process from "node:process"; +import fs from "node:fs"; +import { OpenAI } from "openai"; + +// Change the current working directory to the directory of the script +const __dirname = dirname(fileURLToPath(import.meta.url)); +process.chdir(__dirname); + +// 1. Ask a question about hybrid cars +// ----------------------------------- + +const question = `what's the fastest prius`; + +// 2. Retriever component: search the data for relevant information +// ---------------------------------------------------------------- + +// Load CSV data as an array of objects +const rows = fs.readFileSync("./hybrid.csv", "utf8").split("\n"); +const columns = rows[0].split(","); + +// Search the data using a very naive search +const words = question + .toLowerCase() + .replaceAll(/[.?!()'":,]/g, "") + .split(" ") + .filter((word) => word.length > 2); +const matches = rows.slice(1).filter((row) => words.some((word) => row.toLowerCase().includes(word))); + +// Format as a markdown table, since language models understand markdown +const table = + `| ${columns.join(" | ")} |\n` + + `|${columns.map(() => "---").join(" | ")}|\n` + + matches.map((row) => `| ${row.replaceAll(",", " | ")} |\n`).join(""); + +console.log(`Found ${matches.length} matches:`); +console.log(table); + +// 3. Context augmentation: create a combined prompt with the search results +// -------------------------------------------------------------------------- + +const augmentedPrompt = ` +## Instructions +Answer questions about a time period or characters from said time period using only the sources below. +If there's not enough data in provided sources, say that you don't know. +Be brief and straight to the point. + +## Sources +${table} + +## Question +${question} +`; + +// 4. Generator component: use the search results to generate a response +// --------------------------------------------------------------------- + +const openai = new OpenAI({ + baseURL: "https://models.inference.ai.azure.com", + apiKey: process.env.GITHUB_TOKEN, +}); + +const chunks = await openai.chat.completions.create({ + model: "gpt-4o-mini", + messages: [{ role: "user", content: augmentedPrompt }], + stream: true, +}); + +console.log(`Answer for "${question}":`); + +for await (const chunk of chunks) { + process.stdout.write(chunk.choices[0].delta.content ?? ""); +} +``` + +Puoi trovare questo codice nel file [`example/rag-cars.js`](/lessons/05-rag/example/rag-cars.js) insieme al file [`hybrid.csv`](/lessons/05-rag/example/hybrid.csv) contenente i dati utilizzati per il recupero. + +**Ada:** «Una volta eseguito questo codice, dovresti vedere i dati trovati nel file CSV dal retriever, formattati come una tabella Markdown, seguiti dalla risposta generata dall’IA alla domanda. Prova a modificare la domanda per vedere come cambiano i dati recuperati e la risposta. Puoi anche provare a porre domande su argomenti non correlati per vedere come il modello di IA le gestisce.» + +```text +Example of the output: + +Found 1 matches: +| Person | Time Period | Description | +|---|---|---| +| Leonardo Da Vinci | 15th century | Italian polymath known for his art and inventions. | +| Isaac Newton | 17th century | English mathematician and physicist who formulated the laws of motion and universal gravitation. | +``` + +**You:** «Fantastico, capisco come possa essere utile quando si usa il dispositivo, o meglio, come lo è già stato o lo sarà, il viaggio nel tempo è fonte di confusione *sigh*.» + +**Ada:** «Bene, stai andando alla grande. Passiamo al passaggio successivo.» + +## Compito - Aiuta Ada e Charles + +Dopo aver scoperto RAG, sei pronto ad aiutare Ada e Charles con il loro dispositivo. Tuttavia, a un esame più attento, il dispositivo ti sembrerà familiare. + +**Tu:** «Scarabeo del Tempo, sai che cos’è questo?» + +**Scarabeo del Tempo:** «Certo, sono io, o lo sarò. Però mi mancano alcune parti. A pensarci bene, mi mancano un sacco di parti, non ho ancora nemmeno un guscio.» + +**Ada:** «Lo Scarabeo del Tempo è un dispositivo che permette di viaggiare nel tempo e nello spazio, una volta che lo avremo fatto funzionare correttamente. Come dicevo, dobbiamo aggiungergli una nuova funzionalità, un modulo di Retrieval-Augmented Generation (RAG). Questo ci aiuterà a recuperare informazioni e il contesto necessario da diversi periodi storici durante il viaggio. Vogliamo assicurarci di fare riferimento a ogni tipo di fonte, Wikipedia è un buon punto di partenza.» + +**Tu:** «Cosa vuoi che faccia?» + +**Ada:** «Ecco un codice di esempio che recupera informazioni testuali su Tim Berners-Lee da Wikipedia. Tim un giorno sarà molto importante.» + +```javascript +const response = await fetch('https://en.wikipedia.org/w/api.php?format=json&action=query&prop=extracts&redirects=true&explaintext&titles=Tim%20Berners-Lee'); +const data = await response.json(); +const text = Object.values(data.query.pages)[0]?.extract; +``` + +**You:** «Immagino di non essere l’unico ad essere stato nel futuro?» + +**Ada:** «...» + +## Soluzione + +[Soluzione](/lessons/05-rag/solution/rag-www.js) + +## Verifica delle conoscenze + +**Domanda**: Qual è il ruolo del retriever in un sistema RAG? + +A. Il retriever genera risposte in base ai dati di input. +B. Il retriever genera informazioni rilevanti in base ai dati di training del modello. +C. Il retriever trova informazioni rilevanti da fonti di dati esterne. + +[Soluzione del quiz](/lessons/05-rag/solution/solution-quiz.md) + +## Risorse per lo studio autonomo + +- [Retrieval-Augmented Generation and Indexes](https://learn.microsoft.com/azure/ai-studio/concepts/retrieval-augmented-generation) +- **App di esempio**: + * [Serverless AI Chat with RAG](https://github.com/Azure-Samples/serverless-chat-langchainjs/) + * [Ask Youtube: A RAG-based Youtube Q&A API](https://github.com/Azure-Samples/langchainjs-quickstart-demo) +- [Full-length workshop: Create your own ChatGPT with RAG](https://moaw.dev/workshop/gh:azure-samples/azure-openai-rag-workshop/docs/workshop-qdrant.md) diff --git a/lessons/06-tool-calling/translations/README.it.md b/lessons/06-tool-calling/translations/README.it.md new file mode 100644 index 00000000..d26fbb8e --- /dev/null +++ b/lessons/06-tool-calling/translations/README.it.md @@ -0,0 +1,426 @@ +# Lezione 6: Tool calling + +La tool calling, nota anche come function calling, si riferisce al miglioramento del modello di IA aggiungendo funzionalità precedentemente mancanti. Il concetto prevede la fornitura di meta-descrizioni delle function, consentendo al modello di IA di determinare quando un particolare tool dev’essere chiamato in base alla richiesta dell’utente. L’idea è quella di fornire meta-descrizioni delle function effettive e di far sì che il modello di IA indichi quando tale tool deve essere chiamato in base alla richiesta dell’utente. + +In questo capitolo imparerai a: + - creare un tool; + - integrare un tool con un modello di IA; + - chiamare il tool dal modello di IA. + +## Configurazione + +Se non l’hai ancora fatto, configura il tuo ambiente di sviluppo. Ecco come puoi fare: [Configura il tuo ambiente](/docs/setup/README.md). + +## Risorse correlate + +[![Integrating External Applications with Function Calling](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/06-tool-calling/assets/11-lesson-banner.png)](https://aka.ms/gen-ai-lesson11-gh?WT.mc_id=academic-105485-koreyst) + +_Questo video illustra la tool calling, un metodo che aiuta l’IA a chiamare le tue function, ampliando così ciò che può fare_ + +*🎥 Clicca sull’immagine qui sopra per guardare un breve video sulla tool calling* + +## Storia: “Amelia” + +> _Sei un ingegnere meccanico della Londra del 1860. Mentre lavoravi al tuo automa, hai ricevuto una lettera da Charles Babbage che ti ha condotto in una biblioteca, dove hai trovato un dispositivo per viaggiare nel tempo. Durante i tuoi viaggi nel tempo sei arrivato a Firenze, dove hai incontrato Leonardo da Vinci. Ora hai incontrato Ada Lovelace nella sua villa, accompagnato da Charles Babbage. Stanno costruendo il dispositivo per viaggiare nel tempo._ +> +> Torna alla [Lezione 1](/lessons/translations/01-intro-to-genai/README.it.md) se vuoi ripercorrere la storia dall’inizio e iniziare a usare l’IA generativa. + +> [!NOTE] +> Anche se ti consigliamo di leggere la storia (è divertente!), [clicca qui](#interagisci-con-amelia-earhart) se preferisci passare direttamente al contenuto tecnico. + +**Ada Lovelace**: «Ho bisogno che tu vada a trovare una mia amica. Sono poche le persone che possono eguagliare la sua competenza in meccanica e risoluzione dei problemi. Potrebbe essere difficile raggiungerla, però: è sempre in movimento.» 😀 + +**Tu:** «Puoi dirmi di chi stiamo parlando e dove posso trovarla?» + +**Ada Lovelace**: «Ma certo, Amelia Earhart! È una pilota e un’avventuriera che attualmente vola in giro per il mondo. È tutta colpa mia se è scomparsa: le ho dato il dispositivo per viaggiare nel tempo: beh, un prototipo iniziale. Per fortuna, il dispositivo che hai può localizzare altri dispositivi, quindi puoi trovarla. Tutto quello che devi fare è cliccare qui e qui, e poi girare questa manopola.» + +**Tu**: «Ehi, aspetta: qual è esattamente la nostra missione?» + +**Ada**: «Ah, giusto! Chiedi al dispositivo: ha tutti i dettagli. Chiedigli semplicemente di Amelia e dovrebbe avviare lo strumento giusto per te.» + +Il mondo intorno a te inizia a confondersi e tutto sfuma nel nero. Ti riprendi e ti ritrovi nella cabina di pilotaggio di un aereo. Sei in volo e vedi l’oceano sotto di te. C’è qualcuno seduto davanti; riesci a vedere solo la nuca. + +![Amelia che pilota un aereo](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/06-tool-calling/assets/amelia.jpeg) + +**Tu**: «Amelia, sei tu?» + +**Amelia Earhart**: «Chi sei tu? Fammi indovinare: ti ha mandato Ada, giusto?» + +**Tu**: «Sì, esatto. Credo di essere qui per aiutarti. Ada non è stata molto specifica.» + +**Amelia Earhart**: «Bene, meno male che sei qui. Sono un po’ nei guai. Sto cercando un posto dove atterrare e sto finendo il carburante. Puoi aiutarmi?» + +**Tu**: «Dispositivo, puoi raccontarmi di più su Amelia?» + +**Scarabeo del Tempo**: «Tool chiamato: `mission-amelia`. Tool avviato. Amelia Earhart è una pilota e avventuriera. È nota per i suoi voli da record e per la sua scomparsa nel 1937. È stata vista l’ultima volta mentre sorvolava l’Oceano Pacifico. Attualmente sta volando intorno al mondo a bordo del suo aereo, l’Electra. Sta esaurendo il carburante e ha bisogno di trovare un posto dove atterrare.» + +**Tu**: «Dispositivo, puoi aiutarmi a trovare un posto dove far atterrare Amelia?» + +**Scarabeo del Tempo**: «Tool chiamato: `find-landing-spot`. Tool avviato. Ricerca di un punto di atterraggio adatto per Amelia Earhart. Attendi. Trovato un punto di atterraggio adatto. Coordinate: 7,5°N, 134,5°E. Amelia, ho trovato un punto di atterraggio adatto per te. Dirigiti alle coordinate 7,5°N, 134,5°E.» + +**Amelia Earhart**: «Grazie! Vorrei che il mio dispositivo avesse questa funzione. Ci vado subito.» + +## Interagisci con Amelia Earhart + +Se vuoi interagire con Amelia, esegui la app [Personaggi](/app/README.md). + +> [!IMPORTANT] +> Questo dialogo è interamente frutto di fantasia: le risposte sono generate dall’intelligenza artificiale. +> [Dichiarazione di responsabilità sull’IA](../../README.md#responsible-ai-disclaimer) + +![Amelia Earhart](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/06-tool-calling/assets/amelia-front.jpeg) + +**Passaggi**: + +1. Avvia un [![GitHub Codespace](https://img.shields.io/badge/GitHub-Codespace-brightgreen)](https://codespaces.new/microsoft/generative-ai-with-javascript). +2. Passa a _/app_ nella root del repo. +3. Individua la console ed esegui `npm install` seguito da `npm start`. +4. Una volta comparso, seleziona il pulsante “Apri nel Browser”. +5. Chatta con Amelia. + +Per una spiegazione più dettagliata della app, vedi [Interagisci con Dinocrate](/lessons/01-intro-to-genai/translations/README.it.md#interagisci-con-dinocrate). + +> [!NOTE] +> Se stai eseguendo il progetto in locale sul tuo computer, consulta la guida QuickStart per ottenere la configurazione di un token per l’[accesso personale a GitHub](/docs/setup/README.md#creating-a-personal-access-token-pat-for-github-model-access) e sostituisci la chiave nel codice. + +## Chiamata di un tool + +**Tu**: «Dispositivo, che cos’è appena successo?» + +**Scarabeo del Tempo**: «Hai appena chiamato un tool. Un tool è una function che può essere richiamata dal modello di IA per eseguire un’attività specifica. Il tool può essere utilizzato per eseguire un’ampia gamma di attività, da calcoli semplici a operazioni complesse. In questo caso, hai chiamato il tool `find-landing-spot` per aiutare Amelia Earhart a trovare un punto di atterraggio adatto.» + +**Scarabeo del Tempo**: «Ecco un’immagine che illustra il processo di tool calling.» + +![Illustrazione del processo di tool calling](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/06-tool-calling/assets/tool_call_langchain.png) + +_Immagine di proprietà di LangChain _ + +**Tu**: «Possiamo gestire gli errori se qualcosa va storto, ad esempio se il tool non riesce a trovare un punto di atterraggio?» + +**Scarabeo del Tempo**: «Ottima domanda! Sì, è possibile aggiungere una gestione degli errori per gestire tali situazioni. Ad esempio, se il tool non riesce a trovare un punto di atterraggio, è possibile utilizzare un blocco _try-catch_ o controllare il risultato prima di procedere. Ecco un esempio di gestione degli errori durante la chiamata del tool `find-landing-spot`.» + +```javascript +try { + const landingSpot = findLandingSpot(7.5, 134.5); + if (!landingSpot) { + throw new Error("No suitable landing spot found"); + } + console.log(Landing spot found at coordinates: ${landingSpot.lat}, ${landingSpot.long}); +} catch (error) { + console.log(Error: ${error.message}); +} +``` + +**Tu**: «Come posso creare un tool?» + +**Time Beetle**: «Per creare un tool, è necessario definire una function che esegua l’attività desiderata. La function deve ricevere gli input necessari e restituire l’output. È quindi possibile richiamare la function dal modello di IA per eseguire l’attività. Ecco come si presenta il tool `find-landing-spot`.» + +```javascript +function findLandingSpot(lat, long) { + // Perform the task of finding a suitable landing spot + // Return the coordinates of the landing spot + return { lat: 7.5, long: 134.5 }; +} +``` + +**Tu**: «Ok, come fa il modello di IA a sapere che questo tool esiste?» + +**Scarabeo del Tempo**: «È necessario registrare il tool nel modello di IA. Questo comunica al modello che il tool è disponibile per essere richiamato. Ne parleremo nella prossima sezione.» + +### Registrazione in un modello + +**Tu**: «Hai detto che devo registrare il tool nel modello di IA. Come faccio?» + +**Scarabeo del Tempo**: «Per registrare un tool nel modello di IA, è necessario definire una rappresentazione dei metadati dello strumento. Questi metadati devono includere il nome del tool, i parametri di input e il formato di output. È quindi possibile registrare il tool nel modello di IA fornendo i metadati. Ecco un esempio di metadati per il tool `find-landing-spot`.» + +```json +{ + "name": "find-landing-spot", + "description": "Finds a suitable landing spot", + "parameters": { + "type": "object", + "properties": { + "lat": { + "type": "number", + "description": "The latitude of the location", + }, + "long": { + "type": "number", + "description": "The longitude of the location", + }, + }, + "required": ["lat", "long"], + }, + "output": { "type": "object", "properties": { "lat": "number", "long": "number" } } +} +``` + +**Tu**: «Ok, quindi c’è un pezzo di JSON che descrive il tool: e adesso?» + +**Scarabeo del Tempo**: «Ora devi fornire al tuo client la chiamata alla completion della chat in questo modo.» + +```javascript + +function findLandingSpot(lat, long) { + // Perform the task of finding a suitable landing spot + // Return the coordinates of the landing spot + return { lat: 7.5, long: 134.5 }; +} + +function getBackgroundOnCharacter(character) { + // Perform the task of getting background information on a character + // Return the background information + return `Background information on ${character}`; +} + +const getBackgroundOnCharacterJson = { + name: "get-background-on-character", + description: "Get background information on a character", + parameters: { + type: "object", + properties: { + name: { + type: "string", + description: "The name of the character", + } + }, + required: ["lat", "long"], + }, + output: { type: "string" } +}; + +const findLandingSpotJson = { + name: "find-landing-spot", + description: "Finds a suitable landing spot", + parameters: { + type: "object", + properties: { + lat: { + type: "number", + description: "The latitude of the location", + }, + long: { + type: "number", + description: "The longitude of the location", + }, + }, + required: ["lat", "long"], + }, + output: { type: "object", properties: { lat: "number", long: "number" } } +}; + +const messages = [{ + role: "user", + content: `Tell me about Amelia Earhart`, +}]; + +const completion = await openai.chat.completions.create({ + model: 'gpt-4o-mini', + messages: messages, + functions: [getBackgroundOnCharacterJson, findLandingSpotJson] + }); +``` + +**Scarabeo del Tempo**: «Nel frammento di codice precedente: +- definiamo i metadati per i tool `find-landing-spot` e `get-background-on-character`; +- forniamo questi metadati alla chiamata `client.getChatCompletions` come parte del parametro `functions` per indicare al modello di IA che questi strumenti sono disponibili per essere richiamati.» + +**Tu**: «Capito, quindi il modello AI chiamerà l’opzione appropriata se fornisco un prompt che corrisponde alla descrizione del tool?» + +**Scarabeo del Tempo**: «In pratica, ti dirà quale tool ritiene dovresti chiamare e ti fornirà i parametri di input analizzati, ma devi chiamare tu stesso il tool, lascia che ti mostri come fare.» + +### Chiamare un tool + +**Scarabeo del tempo**: «Come dicevo, il modello di IA ti dirà quale tool ritiene che tu debba chiamare e ti fornirà i parametri di input analizzati. Dovrai quindi chiamare il tool tu stesso. Ecco come apparirà il flusso di lavoro passo dopo passo: + 1. Collegare la chiamata al tool + Per prima cosa, devi collegare la chiamata al tool al tuo codice. Ciò comporta la creazione della function e di una rappresentazione dei metadati del tool, quindi la fornitura dei metadati al modello di IA. + 2. L’utente effettua una richiesta tramite un prompt: + - Il programma invia una richiesta di completion della chat al modello di IA con il prompt dell’utente e i metadati degli strumenti forniti. + - Il programma riceve una risposta dal modello di intelligenza artificiale con la chiamata al tool e i parametri di input analizzati se ritiene che uno tool debba essere chiamato. + - In tal caso, lo sviluppatore interpreta la risposta e richiama il tool in base al suggerimento di chiamata alla function fornito dal modello di IA.» + +**Tu**: «Ottimo, ora che ho capito a grandi linee cosa sta succedendo, puoi mostrarmi un po’ di codice?» + +**Scarabeo del Tempo**: «Certo, ecco il codice che collega la chiamata al tool, effettua una richiesta di completion della chat e interpreta la risposta.» + +```javascript +import { OpenAI } from 'openai'; +import { maybeCoerceInteger } from 'openai/core.mjs'; + +// 1: Define the function +function findLandingSpot(lat, long) { + console.log("[Function] Finding landing spot with coordinates: ", lat, long); + // Perform the task of finding a suitable landing spot + // Return the coordinates of the landing spot + return { lat: 7.5, long: 134.5 }; +} + +// 2: Define the tool metadata, should include description, parameters, and output +const findLandingSpotJson = { + name: "find-landing-spot", + description: "Finds a suitable landing spot", + parameters: { + type: "object", + properties: { + lat: { + type: "number", + description: "The latitude of the location", + }, + long: { + type: "number", + description: "The longitude of the location", + }, + }, + required: ["lat", "long"], + }, + output: { type: "object", properties: { lat: "number", long: "number" } } +}; + +// 3: Add the tool to the tools object that we will use later to invoke the tool +const tools = { + [findLandingSpotJson.name]: findLandingSpot +}; + +// 4: Create an instance of the OpenAI client +const openai = new OpenAI({ + baseURL: "https://models.inference.ai.azure.com", // might need to change to this url in the future: https://models.github.ai/inference + apiKey: process.env.GITHUB_TOKEN, +}); + +// 5: Define the messages that will be sent to the AI model +const messages = [ +{ + role: "system", + content: `You are a helpful assistant. You can call functions to perform tasks. Make sure to parse the function call and arguments correctly.` +}, { + role: "user", + content: "Find a landing spot given coordinates 8.5, 130.5" +} +]; + +async function main(){ + console.log("Making LLM call") + + // 6: Call the AI model with the defined messages and tools + const result = await openai.chat.completions.create({ + model: 'gpt-4o', + messages: messages, + functions: [findLandingSpotJson] + }); + + for (const choice of result.choices) { + + let functionCall = choice.message?.function_call; + let functionName = functionCall?.name; + let args = JSON.parse(functionCall?.arguments); + + // 7: Interpret response and call the tool based on the function call provided by the AI model + if (functionName && functionName in tools) { + console.log(`Calling [${functionName}]`); + const toolFunction = tools[functionName]; + const toolResponse = toolFunction(...Object.values(args)); // Extract values from args and spread them + console.log("Result from [tool] calling: ", toolResponse); + } + } +} + +main(); +``` + +«Nel codice precedente abbiamo: + - creato una function chiamata `findLandingSpot` che accetta latitudine e longitudine come input e restituisce le coordinate di un punto di atterraggio adatto; + - definiti i metadati per il too `find-landing-spot`; + - creato un oggetto `tools` che mappa i nomi dei tool ai loro metadati; + - fornito l’oggetto `tools` alla chiamata `client.getChatCompletions`: + + ```javascript + if (functionName && functionName in tools) { + console.log(`Calling [${functionName}]`); + const toolFunction = tools[functionName]; + const toolResponse = toolFunction(...Object.values(args)); // Extract values from args and spread them + console.log("Result from [tool] calling: ", toolResponse); + } + ``` + - chiamato il tool in base alla function calling fornita dal modello di IA; + - stampato il risultato della tool calling.» + +**Tu**: «Credo di aver capito. Definisco una function, creo una rappresentazione dei metadati del tool, fornisco i metadati al modello di IA e poi richiamo il tool in base alla function calling fornita dal modello di IA.» + +**Scarabeo del Tempo**: «Esatto! Ora sei pronto per iniziare a creare i tuoi tool e integrarli con il modello di IA.» + +## Compito - Aggiorna il dispositivo per viaggiare nel tempo di Amelia + +**Amelia Earhart**: «Stiamo scendendo a tutta velocità, grazie a Dio ci hai trovato un punto di atterraggio. Tieni duro!» + +Amelia atterra con destrezza su una piccola isola. Tu e Amelia scendete dall’aereo, e Amelia ti porge un piccolo dispositivo. + +**Amelia Earhart**: «Ecco il mio dispositivo, non è sofisticato come il tuo, ma ha delle funzioni interessanti. Lo sto usando, diciamo, per fare un viaggio nel tempo. Potresti aggiornarlo per favore?» + +**Tu**: «Scarabeo del Tempo, puoi aiutarmi ad aggiornare il dispositivo di Amelia?» + +**Scarabeo del Tempo**: «Certo! Per aggiornare il dispositivo di Amelia, aggiungiamo i seguenti strumenti: + - **un tool che può** calcolare la distanza tra due punti su una mappa. + - **un tool che può** calcolare la posizione GPS della posizione attuale di Amelia. + - **un tool che può** chiamare un’API esterna per ottenere le previsioni meteo per una determinata località. +Ecco le function, tutto ciò che devi fare è registrarle e provarle.» + +```javascript +function calculateDistance(lat1, long1, lat2, long2) { + // Perform the task of calculating the distance between two points + // Return the distance between the points + return Math.sqrt((lat2 - lat1) ** 2 + (long2 - long1) ** 2); +} + +function getGpsPosition() { + // Perform the task of getting the GPS position of the current location + // Return the GPS position + return { lat: 7.5, long: 134.5 }; +} + +function getWeatherForecast(lat, long) { + // Perform the task of getting the weather forecast for a given location + // Return the weather forecast + return "Sunny"; +} +``` + +**Tu**: «Scarabeo del Tempo, sei sicuro che queste funzioni funzioneranno? Sembra che restituiscano solo valori casuali.» + +**Scarabeo del Tempo**: «Esatto, posso fare il resto internamente. Tutto quello che devi fare è registrarle e testarle, assicurandoti che il modello di IA possa chiamarle.» + +> Task: Registra gli strumenti `calculateDistance`, `getGpsPosition` e `getWeatherForecast` con il modello di IA. Testa i tool richiamandoli dal modello di IA. Utilizza il codice fornito nelle sezioni precedenti come riferimento. + +## Soluzione + +[Soluzione](/lessons/06-tool-calling/solution/solution.js) + +## Verifica delle conoscenze + +**Domanda:** +Qual è lo scopo della registrazione di un tool nel modello di IA? + + A. Consentire al modello di IA di eseguire direttamente il tool senza l’intervento dello sviluppatore. + B. Fornire metadati sul tool in modo che il modello di IA possa suggerirne l’utilizzo. + C. Sostituire la necessità di definire function nel codice. + +**Domanda:** +Qual è il ruolo dei metadati del tool nella tool calling? + + A. Descrivono lo scopo, gli input e gli output del tool per il modello di IA. + B. Forniscono al modello di IA i dettagli di implementazione del tool. + C. Garantiscono che il tool venga eseguito automaticamente dal modello di IA. + +**Domanda:** +Perché usare la tool calling? + + A. Per consentire al modello di IA di eseguire attività che vanno oltre le sue capacità integrate sfruttando function esterne. + B. Per sostituire la necessità dell’intervento umano nello sviluppo del modello di IA. + C. Per consentire al modello di IA di eseguire tool senza richiedere metadati. + +[Soluzione del quiz](/lessons/06-tool-calling/solution/solution-quiz.md) + +## Risorse per lo studio autonomo + +- Explains the [process of tool calling](https://learn.microsoft.com/en-us/semantic-kernel/concepts/ai-services/chat-completion/function-calling/?pivots=programming-language-csharp) +- Tool calling in the [LangChain.js framework](https://js.langchain.com/docs/how_to/tool_calling/) +- Function calling as demonstrated in the [OpenAI library](https://github.com/openai/openai-node/blob/master/examples/function-call.ts) diff --git a/lessons/07-mcp/translations/README.it.md b/lessons/07-mcp/translations/README.it.md new file mode 100644 index 00000000..038623f9 --- /dev/null +++ b/lessons/07-mcp/translations/README.it.md @@ -0,0 +1,467 @@ +# Lezione 7: Model Context Protocol (MCP) + +In questo capitolo imparerai a: + - utilizzare il protocollo MCP (Model Context Protocol) per suddividere le funzionalità del server in un server e un client; + - creare tool, risorse e prompt sul server; + - utilizzare il server utilizzando sia lo strumento di ispezione che un client scritto. + +## Configurazione + +Se non l’hai ancora fatto, configura il tuo ambiente di sviluppo. Ecco come puoi fare: [Configura il tuo ambiente](/docs/setup/README.md). + +## Risorse correlate + +[![Guarda un breve video sul MCP](https://img.youtube.com/vi/YRfOiB0Im64/0.jpg)](https://www.youtube.com/watch?v=YRfOiB0Im64) + +_Questo video illustra il Model Context Protocol._ + +*🎥 Clicca sull’immagine qui sopra per guardare un breve video sul MCP* + +## Storia: “Scipione l’Africano” + +> [!NOTE] +> _La nostra storia finora. Sei un ingegnere meccanico della Londra del 1860. Stavi lavorando al tuo automa e hai ricevuto una lettera da Charles Babbage che ti ha portato in una biblioteca dove hai trovato un dispositivo per viaggiare nel tempo. Durante i tuoi viaggi nel tempo sei arrivato a Firenze, dove hai incontrato Leonardo Da Vinci. Sei anche stato nell’Impero azteco ed è qui che la storia continua._ +> +> Torna alla [Lezione 1](/lessons/translations/01-intro-to-genai/README.it.md) se vuoi ripercorrere la storia dall’inizio e iniziare a usare l’IA generativa. + +> [!NOTE] +> Anche se ti consigliamo di leggere la storia (è divertente!), [clicca qui](#interagisci-con-scipione) se preferisci passare direttamente al contenuto tecnico. + +_I nostri eroi, che hanno appena appreso dei tool e della “tool calling” durante il loro incontro con Amelia Earhart, stanno tornando alla villa di Ada Lovelace per discutere delle loro nuove conoscenze. Un lampo di luce avvolge i nostri eroi mentre lo scarabeo temporale li trasporta indietro nel presente di Ada. Si ritrovano nel seminterrato della villa di Ada Lovelace. Charles Babbage non è presente, ma Ada è lì ad aspettarli. È entusiasta di sapere del loro viaggio e delle conoscenze che hanno acquisito._ + +**Ada Lovelace**: «Bentornato! Spero che il tuo viaggio sia stato illuminante.» + +**Tu**: «Lo è stato! L’incontro con la signora Earhart è stata un’esperienza davvero unica. Ci ha insegnato l’importanza dei tool e come usarli in modo efficace.» + +**Ada Lovelace**: «Poche persone capiscono l’importanza dei tool meglio di Amelia. Immagino che tu abbia anche potenziato il suo Scarabeo del Tempo, vero?» + +**Tu**: «Sì, l’abbiamo fatto! Quindi, qual è il prossimo punto all’ordine del giorno?» + +**Ada Lovelace**: «La tool calling è sicuramente un concetto potente, che migliora il tuo dispositivo. Tuttavia, manca di una certa “finezza”, diciamo così. Dobbiamo imparare _come renderlo scalabile_, abbiamo bisogno di un protocollo. Conosco proprio la persona giusta per aiutarci in questo. Il suo nome è Scipione l’Africano, un grande stratega militare dell’antica Roma. Peccato che abbia dedicato tutto il suo tempo alla strategia militare, sono sicuro che sarebbe stato un ingegnere brillante. Vai.» + +**Tu**: «Scipione l’Africano? Mi pare di ricordarlo dalle lezioni di storia.» + +**Ada Lovelace**: «Bene allora, perché sei ancora qui? Il tempo è essenziale. Tic-tac…» + +Il turbinio di luce ti avvolge di nuovo e ti ritrovi in ​​una grande stanza con un grande tavolo al centro. Le pareti sono decorate con mappe e strategie militari. Scipione l’Africano è in piedi al tavolo, immerso nei suoi pensieri. Alza lo sguardo quando entri. «Ada te misit/Ada ti ha mandato?» + +![Scipione l’Africano](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/07-mcp/assets/scipio.png) + +> Scipione l’Africano, noto anche come Publio Cornelio Scipione ll’Africano, fu un importante generale e statista romano vissuto dal 236 a.C. al 183 a.C. È noto soprattutto per il suo ruolo decisivo nella seconda guerra punica contro Cartagine e per la sua vittoria su Annibale nella battaglia di Zama nel 202 a.C. +> La sua vita e la sua carriera esemplificano le sue qualità di leadership, brillantezza strategica e resilienza. Il suo contributo alla sfera militare e politica di Roma lasciò un impatto duraturo sulll’Impero romano. + +## Interagisci con Scipione + +Se vuoi interagire con Scipione, avvia la app [Personaggi](/app/README.md). + +> [!IMPORTANT] +> Questo dialogo è interamente frutto di fantasia: le risposte sono generate dall’intelligenza artificiale. +> [Dichiarazione di responsabilità sull’IA](../../README.md#responsible-ai-disclaimer) + +![Scipione l’Africano](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/07-mcp/assets/scipio.png) + +**Passaggi**: + +1. Avvia un [![GitHub Codespace](https://img.shields.io/badge/GitHub-Codespace-brightgreen)](https://codespaces.new/microsoft/generative-ai-with-javascript). +2. Passa a _/app_ nella root del repo. +3. Individua la console ed esegui `npm install` seguito da `npm start`. +4. Una volta comparso, seleziona il pulsante “Apri nel Browser”. +5. Chatta con Amelia. + +Per una spiegazione più dettagliata della app, vedi [Interagisci con Dinocrate](/lessons/01-intro-to-genai/translations/README.it.md#interagisci-con-dinocrate). + +> [!NOTE] +> Se stai eseguendo il progetto in locale sul tuo computer, consulta la guida QuickStart per ottenere la configurazione di un token per l’[accesso personale a GitHub](/docs/setup/README.md#creating-a-personal-access-token-pat-for-github-model-access) e sostituisci la chiave nel codice. + +## La necessità di un Model Context Protocol (MCP) + +**Scarabeo del Tempo**: «Il protocollo di cui parlava Ada si chiama Model Context Protocol (MCP). È un protocollo che consente di decentralizzare l’architettura dell’applicazione, rendendola più scalabile e resiliente, aggiungendo risorse su un server, o anche su più server, e scaricandole sul client. Lascio che sia Scipione a spiegarti il concetto.» + +**Tu**: «Sì, ci ha mandato Ada. Ha detto che potevate aiutarci con un protocollo.» + +**Scipione**: «Protocollo? Ho passato la vita a sviluppare strategie di battaglia. Suppongo che un protocollo sia come una strategia. Aiuta a organizzare e gestire le risorse in modo efficace e garantisce la comunicazione tra loro. + +Parliamo di manovre di accerchiamento, infiltrazione e uso della cavalleria.» + +**Tu**: «Ok, andiamo avanti?» + +**Scipione**: «In battaglia, spesso utilizziamo manovre di accerchiamento per attaccare il nemico dai lati o dalle retrovie. Questo scompagina le sue formazioni e ci conferisce un vantaggio. Il motivo è che il nemico non è preparato a un attacco laterale e tende a concentrare tutta la sua attenzione sul fronte.» + +**Tu**: «Mmm, immagino sia un po’ come avere unvapp che fa troppo lavoro in anticipo su un singolo server. Le manovre di aggiramento equivarrebbero a distribuire il carico su più server, giusto?» + +**Scipione**: «Esatto! Distribuendo il carico, si riduce il rischio di un singolo punto di errore e si migliora la resilienza complessiva del sistema. Questo semplifica la gestione e l’utilizzo efficace delle risorse.» + +## Model Context Protocol (MCP) + +**Scarabeo del Tempo**: «Per aggiungere un ulteriore tassello al punto di Scipione, il Model Context Protocol (MCP) è un modo per decentralizzare l’architettura dell’applicazione. Permette di suddividere l’applicazione in componenti più piccoli e gestibili, che possono operare in modo indipendente. Ecco alcuni concetti importanti da tenere a mente: + - **host MCP**: programmi come IDE, ad esempio GitHub Copilot in Visual Studio Code o Claude Desktop, che avviano una connessione al server o ai server; + - **client MCP**: client di protocollo che mantengono connessioni 1:1 con i server MCP; + - **server MCP**: programmi leggeri che espongono funzionalità specifiche tramite MCP; + - **origini dati locali**: file, database e servizi sul computer a cui i server MCP possono accedere in modo sicuro; + - **servizi remoti**: sistemi esterni disponibili su Internet (ad esempio, API) a cui i server MCP possono connettersi. + +Ecco una rapida panoramica dell’architettura MCP:» + +![Architettura del MCP](https://softchris.github.io/mcp-workshop/assets/images/diagram-791787b0cac57bc331c20e72b645d4f7.png) + +## Componenti fondamentali del MCP + +Per costruire un server, è necessario conoscere i componenti fondamentali, ovvero: + - **Tool**: i tool sono strumenti che elaborano qualcosa per te: ricevono un input, eseguono un calcolo e producono un output. In genere si tratta di un calcolo, dell’inserimento di un ordine o di un’azione simile. +- **Risorse**: una risorsa è un dato statico, solitamente si tratta di impostazioni di applicazioni, schemi di database o altri file statici su un server, ad esempio. +- **Prompt**. i prompt, o template di prompt, sono come una ricetta che puoi riutilizzare. L’idea è che, utilizzando una ricetta di questo tipo, potresti inviarle dei parametri e inserirli in un LLM, ottenendo così qualcosa come, ad esempio, la generazione di una descrizione di prodotto. + +### Alla scoperta di tool, risorse e suggerimenti + +**Tu**: «E per quanto riguarda l’infiltrazione?» + +**Scipione**: «L’infiltrazione consiste nell’utilizzare piccole unità per infiltrarsi nelle linee nemiche, in questo modo si scoprono maggiori informazioni sul nemico e si crea confusione.» + +**Tu**: «Mi sembra che possiamo usare questo modo di pensare per scoprire di più sui nostri server, sui tool, i prompt e le risorse di cui dispongono. + +Riassumendo, dovrei: + - **Utilizzare manovre di fiancheggiamento** o, nel mio caso, suddividere le funzionalità in base alle funzionalità dell’app in diversi server MCP, in modo da poter distribuire i server in base all’area di utilizzo. In questo modo, è più facile scalare e gestire l’app. Questi server possono anche essere aggiornati indipendentemente l’uno dall’altro. + - **Utilizzare l’infiltrazione** o, nel mio caso, capire cosa stanno facendo questi server, in termini di tool, prompt e risorse. In questo modo posso assicurarmi di interagire con il server giusto e di utilizzare gli strumenti giusti per il lavoro.» + +**Tu**: «Scarabeo del Tempo, ho capito bene?» + +**Scarabeo del Tempo**: «Sì, certo. Le strategie di Scipione possono essere applicate all’architettura della tua applicazione. Se vuoi, posso spiegarti le specifiche del Model Context Protocol (MCP) e come implementarlo nella tua applicazione.» + +**Tu**: «Sì, grazie!» + +**Scarabeo del Tempo**: «Bene, iniziamo creando un server» + +## Creazione di un server MCP + +**Scarabeo del Tempo**: «Per creare il tuo primo server MCP, hai bisogno di due librerie: `@modelcontextprotocol/sdk` e `zod`. + - la libreria `@modelcontextprotocol/sdk` fornisce i necessari tool per creare e gestire i server MCP; + - `zod` è una libreria di dichiarazione e convalida di schemi TypeScript-first che ti aiuta a definire e convalidare le strutture dati utilizzate nel tuo server MCP. + +```bash +npm install @modelcontextprotocol/sdk zod +``` + +Ecco un semplice esempio di come creare un server MCP utilizzando queste librerie: + +```typescript +import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; +import { z } from "zod"; + +// Create an MCP server +const server = new McpServer({ + name: "Demo", + version: "1.0.0" +}); +``` + +Il codice precedente esegue le seguenti operazioni: + - importa le classi e le funzioni necessarie dalla libreria `@modelcontextprotocol/sdk`; + - crea un’istanza del server. La classe `McpServer` viene utilizzata per creare il server e accetta un oggetto con il nome e la versione del server come parametri.» + +**Tu**: «Questo non fa molto, giusto?» + +**Scarabeo del Tempo**: «No, non ancora, ma possiamo aggiungergli risorse e tool. Un tool è qualcosa che può essere utilizzato per eseguire un’attività specifica, mentre una risorsa è qualcosa che può essere utilizzata per fornire dati o funzionalità al tool. Aggiungiamone alcuni qui sotto: + +```typescript +server.tool("add", + { a: z.number(), b: z.number() }, + async ({ a, b }) => ({ + content: [{ type: "text", text: String(a + b) }] + }) + ); +``` + +Nel codice precedente, abbiamo: + - definito uno strumento denominato “add” che accetta due numeri come input e restituisce la loro somma come output; + - descritto i parametri di input e la loro validazione tramite zod. La funzione `z.number()` viene utilizzata per validare i dati di input, assicurando che sia `a` che `b` siano numeri. + - la funzione `async` viene utilizzata per eseguire l’addizione e restituire il risultato in un formato specifico.» + +**Tu**: «Interessante, quindi il tool è come una function che può essere chiamata dal client MCP?» + +**Scarabeo del Tempo**: «Esatto! Il client MCP può chiamare questo tool e passare i parametri richiesti. Aggiungiamo anche una risorsa al server: + +```typescript +server.resource( + "greeting", + new ResourceTemplate("greeting://{name}", { list: undefined }), + async (uri, { name }) => ({ + contents: [{ + uri: uri.href, + text: `Hello, ${name}!` + }] + }) + ); +``` + +In questo codice: + - abbiamo definito una risorsa denominata “greeting” che accetta un nome come input e restituisce un messaggio di saluto; + - abbiamo utilizzato un template di risorsa per definire come chiamare la risorsa `greeting://{name}`. Questo schema viene utilizzato per definire il formato URI della risorsa, che include un placeholder per il nome. + - la funzione `async` viene utilizzata per generare il messaggio di saluto in base al nome fornito.» + +**Tu**: «Quindi, la risorsa è come una fonte di dati: potrebbe essere un database, un file o persino un’API? Se si trattasse di un file, userei un URI `file://` come questo:» + +```typescript +server.resource( + "file", + new ResourceTemplate("file://{path}", { list: undefined }), + async (uri, { path }) => ({ + // do something with the file at path, e.g., read its contents + contents: [{ + uri: uri.href, + text: `File at ${path}` + }] + }) + ); +``` + +**Scarabeo del Tempo**: «Sì, esatto! La risorsa può essere qualsiasi cosa fornisca dati o funzionalità al server MCP. È possibile definire risorse per file, database, API o qualsiasi altra origine dati si desideri utilizzare. + +Ora, aggiungiamo un livello di trasporto al server in modo che possa comunicare con i client. + +```typescript +// Start receiving messages on stdin and sending messages on stdout +const transport = new StdioServerTransport(); +await server.connect(transport); +``` + +In questo codice, abbiamo: + - creato un livello di trasporto utilizzando la classe `StdioServerTransport`, che consente al server di comunicare con i client tramite input e output standard e viene eseguito sulla macchina locale. Esistono anche altri trasporti come SSE e streaming HTTP che consentono l’esecuzione in remoto su un server, di cui parleremo più avanti. + - chiamato il metodo `connect` per stabilire la connessione tra il server e il livello di trasporto.» + +**Tu**: «Ok, ora che abbiamo un server, come possiamo eseguirlo e testarlo?» + +## Eseguire e testare il server MCP + +**Tu**: «Scipione, hai mai testato le tue tattiche?» + +**Scipione**: «Certo! Testare è fondamentale in qualsiasi strategia. Dovresti sempre testare le tue tattiche prima di metterle in atto. Ricordo, infatti, una battaglia specifica in cui ho usato una nuova tattica e ha fallito miseramente: la Battaglia della Trebbia. Ho imparato la lezione e non ho mai più commesso quell’errore.» + +**Tu**: «Quindi come faccio a testare il mio server MCP?» + +**Scarabeo del Tempo**: «Puoi testare il tuo server MCP eseguendolo in un terminale eseguendo l’inspector in questo modo: + +```bash +npx @modelcontextprotocol/inspector node build/index.js +``` + +Qui sopra, utilizziamo il pacchetto `@modelcontextprotocol/inspector` per eseguire il server MCP. Forniamo l’argomento `node build/index.js` per specificare il punto di ingresso del server. Questo avvierà il server MCP e consentirà di interagire con esso tramite l’inspector.» + +**Tu:** «E come interagisco con lui?» + +**Scarabeo del Tempo:** «Questo avvia un server web sulla porta 6274. Puoi accedere all’inspector aprendo il tuo browser web e andando su `http://localhost:6274`. L’inspector fornisce un’interfaccia intuitiva per interagire con il tuo server MCP, consentendoti di testare gli strumenti e le risorse che hai definito.» + +![User interface dell’inspector](https://softchris.github.io/mcp-workshop/assets/images/connect-7703c67645f368d51c7b24a5d635d6a0.png) + +### -1- Connettiti al server + +**Scarabeo del Tempo:** «Selezionando “Connect” dovresti vedere la finestra qui sotto: + +![Connessione al server](https://softchris.github.io/mcp-workshop/assets/images/connected-7c3570d5d0a8659e27740d2950031cb3.png) + +Dovrebbe indicare che sei connesso. Ora puoi interagire coi tool o le risorse successive.» + +### -2- Elenca tool e risorse + +**Scarabeo del Tempo:** «Successivamente, vogliamo elencare i tool e le risorse disponibili sul server. Puoi farlo selezionando “List Tool” per vedere quali strumenti sono disponibili: + +![Elenco dei tool](https://softchris.github.io/mcp-workshop/assets/images/tools-listed-630aa49c9d7e4347108419fb83c409f6.png) + +Ora dovresti vedere lo strumento “add” nell’elenco. Puoi anche elencare le risorse selezionando la scheda “Resources”.» + +### -3- Esegui il tool + +**Scarabeo del Tempo:** «Per eseguire lo strumento, seleziona lo strumento “add” dall’elenco. Inserisci i parametri nella finestra di dialogo che appare sul lato destro dello schermo. Ad esempio, puoi inserire `a=5` e `b=10` per sommare questi due numeri. Fai clic su “Run Tool” per eseguire lo strumento. Dovresti vedere il risultato nell’area di output sottostante. Il risultato dovrebbe essere `15`.» + +![Esecuzione del tool](https://softchris.github.io/mcp-workshop/assets/images/ran-tool-271ecd5f84a457462e59789b579ee9d4.png) + +**Scipione:** «Interessante, vorrei poter testare le mie strategie in questo modo. Sembra molto utile.» + +**Tu:** «Esatto, davvero! Capisco che potrebbe essere utile per i test e il debug.» + +## Crea un client + +**Scarabeo del Tempo:** «È anche possibile creare un client che si connette al server MCP e interagisce con esso. Ecco un esempio di come creare un semplice client MCP utilizzando la libreria `@modelcontextprotocol/sdk`: + +```typescript +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"; + +const transport = new StdioClientTransport({ + command: "node", + args: ["server.js"] +}); + +const client = new Client( + { + name: "example-client", + version: "1.0.0" + } +); + +await client.connect(transport); +``` + +Nel codice precedente, abbiamo: + - creato un livello di trasporto utilizzando la classe `StdioClientTransport`, che consente al client di comunicare con il server MCP tramite input e output standard. + - avviato una nuova istanza `Client` con un nome e una versione. + - connesso il client al livello di trasporto utilizzando il metodo `connect`.» + +**Tu:** «Lasciami indovinare, c’è molto altro che possiamo fare con il client?» + +**Scarabeo del Tempo:** «Sì, ne parleremo più avanti. Il client MCP può essere utilizzato per interagire con il server, richiamare strumenti e accedere alle risorse.» + +### Elenca e chiama tool e risorse + +**Scarabeo del Tempo:** «In genere, ci sono due scenari da considerare: elencare tool e risorse e chiamarli. Ecco come fare:» + +```typescript +// List prompts +const prompts = await client.listPrompts(); + +// List resources +const resources = await client.listResources(); + +// list tools +const tools = await client.listTools(); +``` + +**Tu:**: «Fantastico, ora so quali sono le capacità del server. Ma come le chiamo?» + +**Scarabeo del Tempo:** «Bene, lasciatemi approfondire un esempio specifico, prima i tool. Quindi si inizia chiedendo quali tool si possiedono, poi si memorizza la risposta e poi si chiama lo strumento desiderato. Ecco un esempio: + +Quindi, quando si elencano i tool, si ottiene una risposta nel seguente formato: + +```json + + { + "name": "", + "description": "". + "inputSchema": { + "type":"object", + "properties":{ + "a":{ + "type":"number" + }, + "b":{ + "type":"number" + }}, + "required":["a","b"], + "additionalProperties":false, + "$schema":"http://json-schema.org/draft-07/schema#" + } + } +``` + +il che significa che se hai untool `add`, la tua risposta, che elenca gli strumenti, apparirà così:» + +```json +{ + "name": "add", + "description": "Adding two numbers". + "inputSchema": { + "type":"object", + "properties":{ + "a":{ + "type":"number" + }, + "b":{ + "type":"number" + }}, + "required":["a","b"], + "additionalProperties":false, + "$schema":"http://json-schema.org/draft-07/schema#" + } +} +``` + +**Tu:** «Ok, bene, credo che posso memorizzarlo in una variabile e poi chiamare il tool che voglio?» + +**Scarabeo del Tempo:** «Esatto! Vediamo ora come può essere chiamato un tool:» + +```typescript +// List tools +const { tools } = await client.listTools(); + +const addTool = tools[0]; // Assuming the first tool is "add" +const subtractTool = tools[1]; // Assuming the second tool is "subtract" + +// Call a tool +const result = await client.callTool({ + name: addTool.name, + arguments: { + a: 5, + b: 10 + } +}); +``` + +**Tu:**: «Ok, ha senso. E per quanto riguarda le risorse?» + +**Scarabeo del Tempo:** «Le risorse sono simili, ma è necessario fornire l’URI della risorsa e tutti i parametri richiesti. Ecco un esempio:» + +```typescript +let resourceUri = "greeting://John"; // Replace with the actual resource URI + +// call resource +// Read a resource +const name = "John Doe"; // Replace with the actual name + +const resourceResult = await client.readResource({ + uri: `greeting:///${name}`, +}); + +console.log(resourceResult); // Hi John Doe! +``` + +**Tu:** «Lo capisco bene, anche se», stai pensando tra te e te, «scommetto che possiamo migliorare in qualche modo? Scarabeo del Tempo, possiamo migliorare, vero?» + +**Scarabeo del Tempo:** «Sì, ma prima di tutto, rendiamo felice Scipione. Alla nostra prossima tappa dobbiamo fare due chiacchiere con la signorina Lamarr.» + +## Compito - Creazione di un sistema di gestione dell'inventario e dei tool per Scipione + +**Scipione:** «Sai, ho così tante pergamene e rotoli sparsi in giro. Mi servirebbe davvero uno strumento che mi aiuti a organizzarli. Ho anche questo abaco che uso per i calcoli. Puoi aiutarmi a creare uno strumento per gestire il mio inventario? + +Ecco un inventario completo delle mie pergamene: +- pergamena delle tattiche; +- pergamena delle scorte alimentari. + +Oh, ecco una pergamena delle tasse. Le tasse sono una cosa importante, l’Impero vuole la sua parte di tutto ciò che acquisiamo. Hai risolto questo problema nel tuo tempo? Non rispondere, non voglio saperlo. + +L’abaco mi serve per supportare le seguenti operazioni: +- addizione: somma due numeri; +- sottrazione: sottrai un numero da un altro; +- moltiplicazione: moltiplica due numeri; +- divisione: dividi un numero per un altro.» + +## Soluzione + +[Soluzione](/lessons/07-mcp/solution/README.md) + +## Verifica delle conoscenze + +**Domanda:** Quali sono i diversi tipi di risorse che un server MCP può esporre? + +A. Tool ed endpoint web. +B. Tool e risorse. +C. Tool, risorse e prompt. + +**Domanda:** Quali sono alcuni modi per testare il tuo server MCP? + +A. Inspector. +B. Un client MCP personalizzato. +C. Visual Studio Code. +D. cURL. +E. Tutti i precedenti. + +[Soluzione del quiz](/lessons/07-mcp/solution/solution-quiz.md) + +## Summario + +In questo capitolo abbiamo appreso quanto segue: +- il Model Context Protocol (MCP) è un ottimo modo per trasferire funzionalità ai server invece di concentrarle tutte in un unico posto. Questo consente alle app di rimanere compatte e focalizzate. Il vantaggio aggiuntivo è che team diversi possono gestire anche server diversi. Grazie al fatto che MCP è un protocollo, chiunque desideri condividere funzionalità può farlo in un formato comune; +- abbiamo inoltre esaminato come utilizzare un server MCP utilizzando lo strumento inspector o un client scritto. + +## Risorse per lo studio autonomo + +- [Building MCP Servers](https://github.com/microsoft/mcp-for-beginners/tree/main/03-GettingStarted/01-first-server) diff --git a/lessons/08-mcp-advanced/translations/README.it.md b/lessons/08-mcp-advanced/translations/README.it.md new file mode 100644 index 00000000..76c4138f --- /dev/null +++ b/lessons/08-mcp-advanced/translations/README.it.md @@ -0,0 +1,251 @@ +# Lezione 8: Miglioramento dei client MCP coi Large Language Model + +Nella lezione precedente, hai creato un server MCP e hai esplorato come aiuta a disaccoppiare la logica di un’applicazione di intelligenza artificiale dalle sue funzionalità. Abbiamo mostrato come aggiungere strumenti e risorse come funzionalità e come il server potesse essere accessibile tramite uno strumento di ispezione o un client personalizzato. Questo era solo l’inizio. In questo capitolo, faremo un ulteriore passo avanti integrando un Large Language Model (LLM) nel client, sbloccando un’esperienza utente più potente e intuitiva. + +In questo capitolo imparerai a: +- potenziare il tuo client con un LLM; +- utilizzare il tuo client migliorato per convertire una risposta del server MCP in un tool; +- sfruttare il tuo client migliorato per creare una user experience più naturale. + +## Configurazione + +Se non l’hai ancora fatto, configura il tuo ambiente di sviluppo. Ecco come puoi fare: [Configura il tuo ambiente](/docs/setup/README.md). + +## Risorse correlate + +[![Guarda un breve video sul MCP](https://img.youtube.com/vi/YRfOiB0Im64/0.jpg)](https://www.youtube.com/watch?v=YRfOiB0Im64) + +_Questo video illustra il Model Context Protocol._ + +*🎥 Clicca sull’immagine qui sopra per guardare un breve video sul MCP* + + +## Storia: “Hedwig ‘Hedy’ Lamarr” + +> [!NOTE] +> _La nostra storia finora. Sei un ingegnere meccanico della Londra del 1860. Stavi lavorando al tuo automa e hai ricevuto una lettera da Charles Babbage che ti ha portato in una biblioteca dove hai trovato un dispositivo per viaggiare nel tempo. Durante i tuoi viaggi nel tempo sei finito in molti luoghi della storia. Ora stai lavorando a stretto contatto con Ada Lovelace, con la sua villa come base operativa, ed è qui che la storia continua._ +> +> Torna alla [Lezione 1](/lessons/translations/01-intro-to-genai/README.it.md) se vuoi ripercorrere la storia dall’inizio e iniziare a usare l’IA generativa. + +> [!NOTE] +> Anche se ti consigliamo di leggere la storia (è divertente!), [clicca qui](##interagisci-con-hedy-lamarr) se preferisci passare direttamente al contenuto tecnico. + +Ancora una volta sei tornato alla villa di Ada. Questa volta Ada ti ha accolto al cancello principale. + +**Ada Lovelace**: «Beh, com’è andata?» + +**Tu**: «Bene, penso che siamo riusciti a far funzionare questa app. Ecco, guarda tu stessa», dici e passi il dispositivo ad Ada. + +**Ada Lovelace**: Prende il dispositivo, lo esamina attentamente e borbotta tra sé e sé: «Mmm hm, ah capisco, sì, sì no, questo non va bene. Manca di una certa finezza.» + +**Tu**: «Ci stavo pensando anch’io, dobbiamo poter digitare o parlare con lui, giusto?» + +**Ada Lovelace**: «Bene, conosco proprio la persona giusta per aiutarci. Anzi, verrò con te questa volta, è passato troppo tempo dall’ultima volta che ci siamo visti. *Scarabeo del Tempo, Hollywood, per favore, 1940, residenza di Hedy Lamarr*.» + +Tutto sfuma nel nero. Un vortice di colori ti attraversa e, pochi istanti dopo, la tua vista inizia a focalizzarsi. Vedi un uomo seduto accanto a un pianoforte, che parla animatamente con una donna dai capelli castano scuro e ricci. Entrambi gesticolano eccitati mentre parlano. + +![Hedy Lamarr](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/08-mcp-advanced/assets/hedy-invention.jpeg) + +La donna si volta verso Ada che era in piedi accanto a te per esclamare «Ada, sei tu, è passato troppo tempo.» + +**Ada Lovelace**: «Carissima Hedwig, suppongo che tu stia lavorando alla tua ultima invenzione?» + +**Hedy Lamarr**: «Sì, in effetti George e io pensiamo di aver scoperto qualcosa di interessante: il “salto di frequenza”, ma probabilmente non dovrei più dirlo, chissà chi sta ascoltando.» + +**Ada Lovelace**: «Oh, intendi lui», indicando te, «è impegnato nella sua avventura.» + +**Hedy Lamarr**: «Capisco, cosa posso fare per te?» + +**Ada Lovelace**: «In realtà, abbiamo bisogno che questo dispositivo funzioni un po’ meglio. Avete qualche idea?» + +**Hedy Lamarr**: Prende il dispositivo e lo osservò da diverse angolazioni. «Dici di aver già separato le funzionalità dalla parte di comunicazione?» + +**Ada Lovelace**: «Sì, sì, l’abbiamo fatto.» + +**Hedy Lamarr**: «Bene, allora renderei la parte relativa alla comunicazione un po’ più intelligente. Questo mi fa pensare a una conversazione che ho avuto con un cadetto della Marina mentre cercavo di vendere titoli di guerra. Credo si chiamasse Minsky. “Che aspetto ha l’intelligenza umana in una macchina?” era l’argomento. Ho la sensazione che un giorno farà qualcosa di grandioso in questo campo. Quindi sì, dategli più intelligenza.» + +**Ada Lovelace**: «Bene, hai sentito la signora Lamarr, mettiti al lavoro.» + +**Tu**: «Scarabeo del Tempo, come possiamo fare?» + +**Scarabeo del Tempo**: «È possibile migliorare il client creato in precedenza integrando un Large Language Model o LLM.» + +> Hedy Lamarr è stata una figura straordinaria, nota sia per la sua fama hollywoodiana che per i suoi straordinari contributi alla tecnologia. +> +> Tuttavia, oltre alla sua carriera di attrice, Lamarr è stata anche una brillante inventrice. Durante la seconda guerra mondiale, inventò insieme al compositore George Antheil un sistema di guida radio per i siluri Alleati. Questo sistema utilizzava la tecnologia a spettro diffuso e a salto di frequenza per impedire alle potenze dell’Asse di interferire con i segnali. Sebbene non fosse utilizzato durante la guerra, questa tecnologia divenne in seguito la base delle moderne comunicazioni wireless, tra cui Wi-Fi, Bluetooth e GPS. +> +> Il contributo di Lamarr alla tecnologia non fu pienamente riconosciuto durante la sua vita, ma oggi è celebrata come una pioniera nel settore. La sua storia è un affascinante mix di glamour e genialità, a dimostrazione che la vera innovazione può nascere dai luoghi più inaspettati. +> Per saperne di più su [Hedy Lamarr](https://en.wikipedia.org/wiki/Hedy_Lamarr) clicca qui e su [Marvin Minsky](https://en.wikipedia.org/wiki/Marvin_Minsky) clicca qui. + +## Interagisci con Hedy Lamarr + +Se vuoi interagire con Hedy, esegui la app [Personaggi](/app/README.md). + +> [!IMPORTANT] +> Questo dialogo è interamente frutto di fantasia: le risposte sono generate dall’intelligenza artificiale. +> [Dichiarazione di responsabilità sull’IA](../../README.md#responsible-ai-disclaimer) + +![Hedy Lamarr](https://raw.githubusercontent.com/microsoft/generative-ai-with-javascript/main/lessons/08-mcp-advanced/assets/hedylamarr.jpeg) + +**Passaggi**: + +1. Avvia un [![GitHub Codespace](https://img.shields.io/badge/GitHub-Codespace-brightgreen)](https://codespaces.new/microsoft/generative-ai-with-javascript). +2. Passa a _/app_ nella root del repo. +3. Individua la console ed esegui `npm install` seguito da `npm start`. +4. Una volta comparso, seleziona il pulsante “Apri nel Browser”. +5. Chatta con Hedy. + +Per una spiegazione più dettagliata della app, vedi [Interagisci con Dinocrate](/lessons/01-intro-to-genai/translations/README.it.md#interagisci-con-dinocrate). + +> [!NOTE] +> Se stai eseguendo il progetto in locale sul tuo computer, consulta la guida QuickStart per ottenere la configurazione di un token per l’[accesso personale a GitHub](/docs/setup/README.md#creating-a-personal-access-token-pat-for-github-model-access) e sostituisci la chiave nel codice. + +## Aggiungere un Large Language Model a un client + +**Scarabeo del Tempo**: «Come dicevo, parliamo di come creare un client che utilizzi un Large Language Model (LLM) per interagire con il server MCP. I vantaggi sono una migliore esperienza utente e la possibilità di utilizzare il linguaggio naturale per interagire con il server. + +Ecco come funzionerebbe ad alto livello: + 1. Il client interagisce con il server MCP per richiedere informazioni sui tool e le risorse disponibili. + 2. Al momento del prompt, l’utente scrive un prompt in linguaggio naturale, che viene poi inviato all’LLM nel client. + 3. Il client determina quale tool o quale risorsa chiamare in base al prompt e agli strumenti e alle risorse disponibili. + +Sembra fattibile, vero?» + +**Tu**: «Sì, è vero! Ma come si fa?» + +**Scarabeo del Tempo**: «Miglioriamo il client creato in precedenza, descrivendo le modifiche al codice in passaggi: + +1. Effettuare una chiamata al server per richiedere tool e risorse disponibili. +2. Convertire la risposta di tool e risorse in uno schema di tool utilizzabile dall’LLM. +3. Istanziare il client OpenAI. +4. Effettuare una chiamata di completamento della chat a OpenAI, passando lo schema degli strumenti come parametro. +5. Determinare quale strumento chiamare in base alla risposta di OpenAI. +6. Chiamare lo strumento sul server utilizzando il client MCP. +7. Rispondere all’utente con il risultato. + +Ecco tutti i passaggi nel codice: + +```typescript +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"; + +// create client instance +const transport = new StdioClientTransport({ + command: "node", + args: ["server.js"] +}); + +const client = new Client( + { + name: "example-client", + version: "1.0.0" + } +); + +await client.connect(transport); + +// 1. make call to server, ask it for tools +const { tools } = await client.listTools(); + +// convert function +function toToolSchema(method, schema) { + return { + name: method, + description: `This is a tool that does ${method}`, + parameters: schema, + }; +} + +// 2. convert the tools and resources response to a tools schema +const toolsForLLM = tools.map((tool) => { + return toToolSchema(tool.method, tool.inputSchema); +}); + +// 3. instantiate openai client +const openai = new OpenAI({ + apiKey: process.env.OPENAI_API_KEY, + model: "gpt-3.5-turbo", + temperature: 0.7, +}); + +// 4. make chat completion call to openai +const response = await openai.chat.completions.create({ + messages: [ + { + role: "user", + content: `I want to add 5 and 10. Please use the tool ${toolsForLLM}`, + }, + ], + functions: toolsForLLM, + function_call: "auto", +}); + +// 5. figure out what tool to call based on the response from openai +const toolName = response.choices[0].message.function_call.name; // add +const args = response.choices[0].message.function_call.arguments; // { a: 5, b: 10 } + +// 6. call the tool on the server +const result = await client.callTool({ + name: toolName, + arguments: args, +}); + +// 7. respond to user +console.log(result); // 15 +``` + +Nel codice precedente (concentrandoci sulle nostre aggiunte): + - abbiamo creato una function `toToolSchema` che converte la risposta di tool e risorse in uno schema utilizzabile dall’LLM; + - abbiamo chiesto al server i tool e le risorse disponibili; + - abbiamo convertito la risposta di tool e risorse in uno schema utilizzabile dall’LLM; + - abbiamo effettuato una chiamata di completion della chat alla nostra IA, passando i tool convertiti come parametro; + - abbiamo capito quale tool chiamare in base alla risposta di OpenAI; + - abbiamo chiamato il tool sul server utilizzando il client MCP; + - abbiamo restituito il risultato all’utente.» + +**Tu**: «Mi piace, è molto meglio! Posso usare il linguaggio naturale senza nemmeno sapere quali tool e risorse sono disponibili. Posso semplicemente chiedere all’IA di farlo per me.» + +**Scarabeo del Tempo**: «Sono contento che ti piaccia. Va detto, però, che potresti voler decidere se mostrare solo una risposta degli strumenti o anche una risposta generica dall’LLM. Quindi, il tuo utente potrebbe trarre vantaggio dalla seguente strategia di risposta: + - **solo tool** se la risposta dell’LLM è uno strumento, chiama lo strumento e restituisci il risultato. + - **solo LLM** se la risposta dell’LLM non è uno strumento, restituisci la risposta dell’LLM “così com’è”. + - **tool e LLM** se la risposta dell’LLM è uno strumento, chiama lo strumento ed effettua un’ulteriore chiamata all’LLM per ottenere la risposta generale. Restituisci sia il risultato dello strumento che la risposta dell’LLM.» + +**Tu**: «Capisco. Qualcosa su cui riflettere. Ma è fantastico! Capisco quanto possa essere utile.» + +## Assignment + +**Ada Lovelace**: «Sembra che tu abbia apportato un notevole miglioramento. Per renderlo davvero utile, ho bisogno che tu crei un server e un client con le seguenti specifiche: + - il server dovrebbe fornire i seguenti strumenti: + - `characterDetails` con l’argomento `name`; + - `place` con l’argomento `name`. + - il client dovrebbe utilizzare un LLM.» + +> [!TIP] +> Ad esempio, puoi dare al server la possibilità di recuperare informazioni da un’API web esterna, come Wikipedia: +> `https://en.wikipedia.org/api/rest_v1/page/summary/${encodeURIComponent(name)}` + +## Soluzione + +[Soluzione](/lessons/08-mcp-advanced/solution/README.md) + +## Verifica delle conoscenze + +**Domanda:** Qual è il vantaggio di aggiungere un LLM al client? + +A. È più facile da gestire. +B. Crea una conversazione più naturale tra l’utente e il server. +C. È meglio avere l’LLM sul server. + +[Soluzione del quiz](/lessons/08-mcp-advanced/solution/solution-quiz.md) + +## Summario + +In questo capitolo hai imparato quanto segue: +- I client potenziati con un LLM offrono un’esperienza utente migliore. +- Le risposte da un server devono essere convertite in un formato che l’LLM possa comprendere come strumento. + +## Risorse per lo studio autonomo + +- [Building MCP Servers](https://github.com/microsoft/mcp-for-beginners/tree/main/03-GettingStarted/01-first-server/README.md) +- [Building a Client](https://github.com/microsoft/mcp-for-beginners/tree/main/03-GettingStarted/02-client/README.md) +- [Building a Client with an LLM](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/03-llm-client/README.md)