|
|
<!--
|
|
|
CO_OP_TRANSLATOR_METADATA:
|
|
|
{
|
|
|
"original_hash": "2066c17078e9d18b5e309f31d8e8bc24",
|
|
|
"translation_date": "2025-11-04T00:26:19+00:00",
|
|
|
"source_file": "9-chat-project/README.md",
|
|
|
"language_code": "it"
|
|
|
}
|
|
|
-->
|
|
|
# Costruire un Assistente Chat con l'AI
|
|
|
|
|
|
Ricordi in Star Trek quando l'equipaggio parlava casualmente con il computer della nave, ponendo domande complesse e ricevendo risposte ponderate? Quello che sembrava pura fantascienza negli anni '60 è ora qualcosa che puoi costruire utilizzando tecnologie web che già conosci.
|
|
|
|
|
|
In questa lezione, creeremo un assistente chat AI utilizzando HTML, CSS, JavaScript e un po' di integrazione backend. Scoprirai come le stesse competenze che stai imparando possono connettersi a potenti servizi AI che comprendono il contesto e generano risposte significative.
|
|
|
|
|
|
Pensa all'AI come avere accesso a una vasta biblioteca che non solo trova informazioni, ma le sintetizza in risposte coerenti su misura per le tue domande specifiche. Invece di cercare tra migliaia di pagine, ottieni risposte dirette e contestuali.
|
|
|
|
|
|
L'integrazione avviene attraverso tecnologie web familiari che lavorano insieme. HTML crea l'interfaccia della chat, CSS gestisce il design visivo, JavaScript gestisce le interazioni con l'utente e un'API backend collega tutto ai servizi AI. È simile a come le diverse sezioni di un'orchestra lavorano insieme per creare una sinfonia.
|
|
|
|
|
|
Stiamo essenzialmente costruendo un ponte tra la comunicazione umana naturale e l'elaborazione delle macchine. Imparerai sia l'implementazione tecnica dell'integrazione dei servizi AI sia i modelli di design che rendono le interazioni intuitive.
|
|
|
|
|
|
Alla fine di questa lezione, l'integrazione dell'AI sembrerà meno un processo misterioso e più come un'altra API con cui puoi lavorare. Capirai i modelli fondamentali che alimentano applicazioni come ChatGPT e Claude, utilizzando gli stessi principi di sviluppo web che stai imparando.
|
|
|
|
|
|
## ⚡ Cosa Puoi Fare nei Prossimi 5 Minuti
|
|
|
|
|
|
**Percorso Rapido per Sviluppatori Occupati**
|
|
|
|
|
|
```mermaid
|
|
|
flowchart LR
|
|
|
A[⚡ 5 minutes] --> B[Get GitHub token]
|
|
|
B --> C[Test AI playground]
|
|
|
C --> D[Copy Python code]
|
|
|
D --> E[See AI responses]
|
|
|
```
|
|
|
|
|
|
- **Minuto 1**: Visita [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) e crea un token di accesso personale
|
|
|
- **Minuto 2**: Testa le interazioni AI direttamente nell'interfaccia del playground
|
|
|
- **Minuto 3**: Clicca sulla scheda "Code" e copia il frammento di codice Python
|
|
|
- **Minuto 4**: Esegui il codice localmente con il tuo token: `GITHUB_TOKEN=your_token python test.py`
|
|
|
- **Minuto 5**: Guarda la tua prima risposta AI generata dal tuo codice
|
|
|
|
|
|
**Codice di Test Rapido**:
|
|
|
```python
|
|
|
import os
|
|
|
from openai import OpenAI
|
|
|
|
|
|
client = OpenAI(
|
|
|
base_url="https://models.github.ai/inference",
|
|
|
api_key="your_token_here"
|
|
|
)
|
|
|
|
|
|
response = client.chat.completions.create(
|
|
|
messages=[{"role": "user", "content": "Hello AI!"}],
|
|
|
model="openai/gpt-4o-mini"
|
|
|
)
|
|
|
|
|
|
print(response.choices[0].message.content)
|
|
|
```
|
|
|
|
|
|
**Perché è Importante**: In 5 minuti, sperimenterai la magia dell'interazione programmatica con l'AI. Questo rappresenta il blocco fondamentale che alimenta ogni applicazione AI che utilizzi.
|
|
|
|
|
|
Ecco come apparirà il tuo progetto finito:
|
|
|
|
|
|
|
|
|
|
|
|
## 🗺️ Il Tuo Percorso di Apprendimento nello Sviluppo di Applicazioni AI
|
|
|
|
|
|
```mermaid
|
|
|
journey
|
|
|
title From Web Development to AI Integration
|
|
|
section Understanding AI Foundations
|
|
|
Discover generative AI concepts: 4: You
|
|
|
Explore GitHub Models platform: 6: You
|
|
|
Master AI parameters and prompts: 8: You
|
|
|
section Backend Integration
|
|
|
Build Python API server: 5: You
|
|
|
Implement AI function calls: 7: You
|
|
|
Handle async operations: 8: You
|
|
|
section Frontend Development
|
|
|
Create modern chat interface: 6: You
|
|
|
Master real-time interactions: 8: You
|
|
|
Build responsive user experience: 9: You
|
|
|
section Professional Application
|
|
|
Deploy complete AI system: 7: You
|
|
|
Optimize performance patterns: 8: You
|
|
|
Create production-ready app: 9: You
|
|
|
```
|
|
|
|
|
|
**Destinazione del Tuo Percorso**: Alla fine di questa lezione, avrai costruito un'applicazione completa alimentata dall'AI utilizzando le stesse tecnologie e modelli che alimentano assistenti AI moderni come ChatGPT, Claude e Google Bard.
|
|
|
|
|
|
## Comprendere l'AI: Dal Mistero alla Padronanza
|
|
|
|
|
|
Prima di immergerci nel codice, cerchiamo di capire con cosa stiamo lavorando. Se hai già utilizzato API, conosci il modello di base: inviare una richiesta, ricevere una risposta.
|
|
|
|
|
|
Le API AI seguono una struttura simile, ma invece di recuperare dati pre-memorizzati da un database, generano nuove risposte basate su modelli appresi da enormi quantità di testo. Pensalo come la differenza tra un sistema di catalogazione di una biblioteca e un bibliotecario esperto che può sintetizzare informazioni da più fonti.
|
|
|
|
|
|
### Cos'è Veramente l'"AI Generativa"?
|
|
|
|
|
|
Considera come la Stele di Rosetta abbia permesso agli studiosi di comprendere i geroglifici egizi trovando modelli tra lingue conosciute e sconosciute. I modelli AI funzionano in modo simile: trovano modelli in enormi quantità di testo per capire come funziona il linguaggio, quindi utilizzano quei modelli per generare risposte appropriate a nuove domande.
|
|
|
|
|
|
**Lascia che te lo spieghi con un semplice confronto:**
|
|
|
- **Database tradizionale**: Come chiedere il tuo certificato di nascita – ricevi sempre lo stesso documento
|
|
|
- **Motore di ricerca**: Come chiedere a un bibliotecario di trovare libri sui gatti – ti mostrano ciò che è disponibile
|
|
|
- **AI generativa**: Come chiedere a un amico esperto di gatti – ti raccontano cose interessanti con parole loro, su misura per ciò che vuoi sapere
|
|
|
|
|
|
```mermaid
|
|
|
graph LR
|
|
|
A[Your Question] --> B[AI Model]
|
|
|
B --> C[Pattern Recognition]
|
|
|
C --> D[Content Generation]
|
|
|
D --> E[Contextual Response]
|
|
|
|
|
|
F[Training Data<br/>Books, Articles, Web] --> B
|
|
|
```
|
|
|
|
|
|
### Come i Modelli AI Imparano (Versione Semplice)
|
|
|
|
|
|
I modelli AI imparano attraverso l'esposizione a enormi dataset contenenti testi da libri, articoli e conversazioni. Attraverso questo processo, identificano modelli in:
|
|
|
- Come sono strutturati i pensieri nella comunicazione scritta
|
|
|
- Quali parole appaiono comunemente insieme
|
|
|
- Come fluiscono tipicamente le conversazioni
|
|
|
- Differenze contestuali tra comunicazione formale e informale
|
|
|
|
|
|
**È simile a come gli archeologi decifrano le lingue antiche**: analizzano migliaia di esempi per comprendere grammatica, vocabolario e contesto culturale, arrivando infine a interpretare nuovi testi utilizzando quei modelli appresi.
|
|
|
|
|
|
### Perché GitHub Models?
|
|
|
|
|
|
Stiamo utilizzando GitHub Models per un motivo piuttosto pratico: ci dà accesso a un'AI di livello aziendale senza dover configurare la nostra infrastruttura AI (che, fidati, non vuoi fare in questo momento!). Pensalo come utilizzare un'API meteo invece di cercare di prevedere il meteo da solo installando stazioni meteorologiche ovunque.
|
|
|
|
|
|
È fondamentalmente "AI-as-a-Service", e la parte migliore? È gratuito per iniziare, quindi puoi sperimentare senza preoccuparti di accumulare un conto salato.
|
|
|
|
|
|
```mermaid
|
|
|
graph LR
|
|
|
A[Frontend Chat UI] --> B[Your Backend API]
|
|
|
B --> C[GitHub Models API]
|
|
|
C --> D[AI Model Processing]
|
|
|
D --> C
|
|
|
C --> B
|
|
|
B --> A
|
|
|
```
|
|
|
|
|
|
Utilizzeremo GitHub Models per la nostra integrazione backend, che fornisce accesso a capacità AI di livello professionale attraverso un'interfaccia amichevole per gli sviluppatori. Il [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) funge da ambiente di test dove puoi sperimentare con diversi modelli AI e comprendere le loro capacità prima di implementarli nel codice.
|
|
|
|
|
|
## 🧠 Ecosistema di Sviluppo di Applicazioni AI
|
|
|
|
|
|
```mermaid
|
|
|
mindmap
|
|
|
root((AI Development))
|
|
|
Understanding AI
|
|
|
Generative Models
|
|
|
Pattern Recognition
|
|
|
Content Generation
|
|
|
Context Understanding
|
|
|
Response Synthesis
|
|
|
AI Parameters
|
|
|
Temperature Control
|
|
|
Token Limits
|
|
|
Top-p Filtering
|
|
|
System Prompts
|
|
|
Backend Architecture
|
|
|
API Integration
|
|
|
GitHub Models
|
|
|
Authentication
|
|
|
Request Handling
|
|
|
Error Management
|
|
|
Python Infrastructure
|
|
|
FastAPI Framework
|
|
|
Async Operations
|
|
|
Environment Security
|
|
|
CORS Configuration
|
|
|
Frontend Experience
|
|
|
Chat Interface
|
|
|
Real-time Updates
|
|
|
Message History
|
|
|
User Feedback
|
|
|
Loading States
|
|
|
Modern Web Tech
|
|
|
ES6 Classes
|
|
|
Async/Await
|
|
|
DOM Manipulation
|
|
|
Event Handling
|
|
|
Professional Patterns
|
|
|
Security Best Practices
|
|
|
Token Management
|
|
|
Input Validation
|
|
|
XSS Prevention
|
|
|
Error Boundaries
|
|
|
Production Readiness
|
|
|
Performance Optimization
|
|
|
Responsive Design
|
|
|
Accessibility
|
|
|
Testing Strategies
|
|
|
```
|
|
|
|
|
|
**Principio Fondamentale**: Lo sviluppo di applicazioni AI combina competenze tradizionali di sviluppo web con l'integrazione di servizi AI, creando applicazioni intelligenti che sembrano naturali e reattive per gli utenti.
|
|
|
|
|
|
|
|
|
|
|
|
**Ecco cosa rende il playground così utile:**
|
|
|
- **Prova** diversi modelli AI come GPT-4o-mini, Claude e altri (tutti gratuiti!)
|
|
|
- **Testa** le tue idee e i tuoi prompt prima di scrivere qualsiasi codice
|
|
|
- **Ottieni** frammenti di codice pronti all'uso nel tuo linguaggio di programmazione preferito
|
|
|
- **Regola** impostazioni come livello di creatività e lunghezza della risposta per vedere come influenzano l'output
|
|
|
|
|
|
Una volta che hai sperimentato un po', basta cliccare sulla scheda "Code" e scegliere il tuo linguaggio di programmazione per ottenere il codice di implementazione di cui hai bisogno.
|
|
|
|
|
|
|
|
|
|
|
|
## Configurare l'Integrazione Backend Python
|
|
|
|
|
|
Ora implementiamo l'integrazione AI utilizzando Python. Python è eccellente per le applicazioni AI grazie alla sua sintassi semplice e alle sue librerie potenti. Inizieremo con il codice dal playground GitHub Models e poi lo ristruttureremo in una funzione riutilizzabile e pronta per la produzione.
|
|
|
|
|
|
### Comprendere l'Implementazione di Base
|
|
|
|
|
|
Quando prendi il codice Python dal playground, otterrai qualcosa che assomiglia a questo. Non preoccuparti se sembra tanto all'inizio – analizziamolo pezzo per pezzo:
|
|
|
|
|
|
```python
|
|
|
"""Run this model in Python
|
|
|
|
|
|
> pip install openai
|
|
|
"""
|
|
|
import os
|
|
|
from openai import OpenAI
|
|
|
|
|
|
# To authenticate with the model you will need to generate a personal access token (PAT) in your GitHub settings.
|
|
|
# Create your PAT token by following instructions here: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
|
|
|
client = OpenAI(
|
|
|
base_url="https://models.github.ai/inference",
|
|
|
api_key=os.environ["GITHUB_TOKEN"],
|
|
|
)
|
|
|
|
|
|
response = client.chat.completions.create(
|
|
|
messages=[
|
|
|
{
|
|
|
"role": "system",
|
|
|
"content": "",
|
|
|
},
|
|
|
{
|
|
|
"role": "user",
|
|
|
"content": "What is the capital of France?",
|
|
|
}
|
|
|
],
|
|
|
model="openai/gpt-4o-mini",
|
|
|
temperature=1,
|
|
|
max_tokens=4096,
|
|
|
top_p=1
|
|
|
)
|
|
|
|
|
|
print(response.choices[0].message.content)
|
|
|
```
|
|
|
|
|
|
**Ecco cosa sta succedendo in questo codice:**
|
|
|
- **Importiamo** gli strumenti di cui abbiamo bisogno: `os` per leggere le variabili d'ambiente e `OpenAI` per comunicare con l'AI
|
|
|
- **Configuriamo** il client OpenAI per puntare ai server AI di GitHub invece che direttamente a OpenAI
|
|
|
- **Autentichiamo** utilizzando un token speciale di GitHub (ne parleremo tra un minuto!)
|
|
|
- **Strutturiamo** la nostra conversazione con diversi "ruoli" – pensalo come impostare la scena per uno spettacolo
|
|
|
- **Inviamo** la nostra richiesta all'AI con alcuni parametri di fine-tuning
|
|
|
- **Estraiamo** il testo della risposta effettiva da tutti i dati che tornano
|
|
|
|
|
|
### Comprendere i Ruoli dei Messaggi: Il Framework di Conversazione AI
|
|
|
|
|
|
Le conversazioni AI utilizzano una struttura specifica con diversi "ruoli" che servono a scopi distinti:
|
|
|
|
|
|
```python
|
|
|
messages=[
|
|
|
{
|
|
|
"role": "system",
|
|
|
"content": "You are a helpful assistant who explains things simply."
|
|
|
},
|
|
|
{
|
|
|
"role": "user",
|
|
|
"content": "What is machine learning?"
|
|
|
}
|
|
|
]
|
|
|
```
|
|
|
|
|
|
**Pensalo come dirigere uno spettacolo:**
|
|
|
- **Ruolo del sistema**: Come le indicazioni sceniche per un attore – dice all'AI come comportarsi, quale personalità avere e come rispondere
|
|
|
- **Ruolo dell'utente**: La domanda o il messaggio effettivo della persona che utilizza la tua applicazione
|
|
|
- **Ruolo dell'assistente**: La risposta dell'AI (non lo invii, ma appare nella cronologia della conversazione)
|
|
|
|
|
|
**Analogia nel mondo reale**: Immagina di presentare un amico a qualcuno a una festa:
|
|
|
- **Messaggio del sistema**: "Questa è la mia amica Sarah, è una dottoressa che spiega concetti medici in modo semplice"
|
|
|
- **Messaggio dell'utente**: "Puoi spiegare come funzionano i vaccini?"
|
|
|
- **Risposta dell'assistente**: Sarah risponde come una dottoressa amichevole, non come un avvocato o uno chef
|
|
|
|
|
|
### Comprendere i Parametri dell'AI: Regolare il Comportamento delle Risposte
|
|
|
|
|
|
I parametri numerici nelle chiamate API AI controllano come il modello genera risposte. Queste impostazioni ti permettono di regolare il comportamento dell'AI per diversi casi d'uso:
|
|
|
|
|
|
#### Temperatura (0.0 a 2.0): La Manopola della Creatività
|
|
|
|
|
|
**Cosa fa**: Controlla quanto creative o prevedibili saranno le risposte dell'AI.
|
|
|
|
|
|
**Pensalo come il livello di improvvisazione di un musicista jazz:**
|
|
|
- **Temperatura = 0.1**: Suona sempre la stessa melodia (altamente prevedibile)
|
|
|
- **Temperatura = 0.7**: Aggiunge alcune variazioni gustose rimanendo riconoscibile (creatività bilanciata)
|
|
|
- **Temperatura = 1.5**: Jazz sperimentale completo con svolte inaspettate (altamente imprevedibile)
|
|
|
|
|
|
```python
|
|
|
# Very predictable responses (good for factual questions)
|
|
|
response = client.chat.completions.create(
|
|
|
messages=[{"role": "user", "content": "What is 2+2?"}],
|
|
|
temperature=0.1 # Will almost always say "4"
|
|
|
)
|
|
|
|
|
|
# Creative responses (good for brainstorming)
|
|
|
response = client.chat.completions.create(
|
|
|
messages=[{"role": "user", "content": "Write a creative story opening"}],
|
|
|
temperature=1.2 # Will generate unique, unexpected stories
|
|
|
)
|
|
|
```
|
|
|
|
|
|
#### Max Tokens (1 a 4096+): Il Controllore della Lunghezza della Risposta
|
|
|
|
|
|
**Cosa fa**: Imposta un limite sulla lunghezza della risposta dell'AI.
|
|
|
|
|
|
**Pensalo come i token approssimativamente equivalenti alle parole** (circa 1 token = 0.75 parole in inglese):
|
|
|
- **max_tokens=50**: Breve e conciso (come un messaggio di testo)
|
|
|
- **max_tokens=500**: Un bel paragrafo o due
|
|
|
- **max_tokens=2000**: Una spiegazione dettagliata con esempi
|
|
|
|
|
|
```python
|
|
|
# Short, concise answers
|
|
|
response = client.chat.completions.create(
|
|
|
messages=[{"role": "user", "content": "Explain JavaScript"}],
|
|
|
max_tokens=100 # Forces a brief explanation
|
|
|
)
|
|
|
|
|
|
# Detailed, comprehensive answers
|
|
|
response = client.chat.completions.create(
|
|
|
messages=[{"role": "user", "content": "Explain JavaScript"}],
|
|
|
max_tokens=1500 # Allows for detailed explanations with examples
|
|
|
)
|
|
|
```
|
|
|
|
|
|
#### Top_p (0.0 a 1.0): Il Parametro di Focus
|
|
|
|
|
|
**Cosa fa**: Controlla quanto l'AI si concentra sulle risposte più probabili.
|
|
|
|
|
|
**Immagina l'AI con un enorme vocabolario, classificato per probabilità di ogni parola**:
|
|
|
- **top_p=0.1**: Considera solo il 10% delle parole più probabili (molto focalizzato)
|
|
|
- **top_p=0.9**: Considera il 90% delle parole possibili (più creativo)
|
|
|
- **top_p=1.0**: Considera tutto (massima varietà)
|
|
|
|
|
|
**Ad esempio**: Se chiedi "Il cielo è solitamente..."
|
|
|
- **Top_p basso**: Dirà quasi sicuramente "blu"
|
|
|
- **Top_p alto**: Potrebbe dire "blu", "nuvoloso", "vasto", "mutevole", "bello", ecc.
|
|
|
|
|
|
### Mettere Tutto Insieme: Combinazioni di Parametri per Diversi Casi d'Uso
|
|
|
|
|
|
```python
|
|
|
# For factual, consistent answers (like a documentation bot)
|
|
|
factual_params = {
|
|
|
"temperature": 0.2,
|
|
|
"max_tokens": 300,
|
|
|
"top_p": 0.3
|
|
|
}
|
|
|
|
|
|
# For creative writing assistance
|
|
|
creative_params = {
|
|
|
"temperature": 1.1,
|
|
|
"max_tokens": 1000,
|
|
|
"top_p": 0.9
|
|
|
}
|
|
|
|
|
|
# For conversational, helpful responses (balanced)
|
|
|
conversational_params = {
|
|
|
"temperature": 0.7,
|
|
|
"max_tokens": 500,
|
|
|
"top_p": 0.8
|
|
|
}
|
|
|
```
|
|
|
|
|
|
```mermaid
|
|
|
quadrantChart
|
|
|
title AI Parameter Optimization Matrix
|
|
|
x-axis Low Creativity --> High Creativity
|
|
|
y-axis Short Response --> Long Response
|
|
|
|
|
|
quadrant-1 Creative Content
|
|
|
quadrant-2 Detailed Analysis
|
|
|
quadrant-3 Quick Facts
|
|
|
quadrant-4 Conversational AI
|
|
|
|
|
|
Documentation Bot: [0.2, 0.3]
|
|
|
Customer Service: [0.4, 0.4]
|
|
|
General Assistant: [0.7, 0.5]
|
|
|
Creative Writer: [0.9, 0.9]
|
|
|
Brainstorming Tool: [0.8, 0.8]
|
|
|
```
|
|
|
|
|
|
**Comprendere perché questi parametri sono importanti**: Diverse applicazioni necessitano di diversi tipi di risposte. Un bot di assistenza clienti dovrebbe essere coerente e fattuale (bassa temperatura), mentre un assistente alla scrittura creativa dovrebbe essere immaginativo e vario (alta temperatura). Comprendere questi parametri ti dà il controllo sulla personalità e lo stile di risposta dell'AI.
|
|
|
```
|
|
|
|
|
|
**Here's what's happening in this code:**
|
|
|
- **We import** the tools we need: `os` for reading environment variables and `OpenAI` for talking to the AI
|
|
|
- **We set up** the OpenAI client to point to GitHub's AI servers instead of OpenAI directly
|
|
|
- **We authenticate** using a special GitHub token (more on that in a minute!)
|
|
|
- **We structure** our conversation with different "roles" – think of it like setting the scene for a play
|
|
|
- **We send** our request to the AI with some fine-tuning parameters
|
|
|
- **We extract** the actual response text from all the data that comes back
|
|
|
|
|
|
> 🔐 **Security Note**: Never hardcode API keys in your source code! Always use environment variables to store sensitive credentials like your `GITHUB_TOKEN`.
|
|
|
|
|
|
### Creating a Reusable AI Function
|
|
|
|
|
|
Let's refactor this code into a clean, reusable function that we can easily integrate into our web application:
|
|
|
|
|
|
```python
|
|
|
import asyncio
|
|
|
from openai import AsyncOpenAI
|
|
|
|
|
|
# Use AsyncOpenAI for better performance
|
|
|
client = AsyncOpenAI(
|
|
|
base_url="https://models.github.ai/inference",
|
|
|
api_key=os.environ["GITHUB_TOKEN"],
|
|
|
)
|
|
|
|
|
|
async def call_llm_async(prompt: str, system_message: str = "You are a helpful assistant."):
|
|
|
"""
|
|
|
Sends a prompt to the AI model asynchronously and returns the response.
|
|
|
|
|
|
Args:
|
|
|
prompt: The user's question or message
|
|
|
system_message: Instructions that define the AI's behavior and personality
|
|
|
|
|
|
Returns:
|
|
|
str: The AI's response to the prompt
|
|
|
"""
|
|
|
try:
|
|
|
response = await client.chat.completions.create(
|
|
|
messages=[
|
|
|
{
|
|
|
"role": "system",
|
|
|
"content": system_message,
|
|
|
},
|
|
|
{
|
|
|
"role": "user",
|
|
|
"content": prompt,
|
|
|
}
|
|
|
],
|
|
|
model="openai/gpt-4o-mini",
|
|
|
temperature=1,
|
|
|
max_tokens=4096,
|
|
|
top_p=1
|
|
|
)
|
|
|
return response.choices[0].message.content
|
|
|
except Exception as e:
|
|
|
logger.error(f"AI API error: {str(e)}")
|
|
|
return "I'm sorry, I'm having trouble processing your request right now."
|
|
|
|
|
|
# Backward compatibility function for synchronous calls
|
|
|
def call_llm(prompt: str, system_message: str = "You are a helpful assistant."):
|
|
|
"""Synchronous wrapper for async AI calls."""
|
|
|
return asyncio.run(call_llm_async(prompt, system_message))
|
|
|
```
|
|
|
|
|
|
**Comprendere questa funzione migliorata:**
|
|
|
- **Accetta** due parametri: il prompt dell'utente e un messaggio di sistema opzionale
|
|
|
- **Fornisce** un messaggio di sistema predefinito per un comportamento generale dell'assistente
|
|
|
- **Utilizza** suggerimenti di tipo Python appropriati per una migliore documentazione del codice
|
|
|
- **Restituisce** solo il contenuto della risposta, rendendolo facile da usare nella nostra API web
|
|
|
- **Mantiene** gli stessi parametri del modello per un comportamento AI coerente
|
|
|
|
|
|
### La Magia dei Prompt di Sistema: Programmare la Personalità dell'AI
|
|
|
|
|
|
Se i parametri controllano come pensa l'AI, i prompt di sistema controllano chi l'AI pensa di essere. Questo è onestamente una delle parti più interessanti del lavoro con l'AI – stai essenzialmente dando all'AI una personalità completa, un livello di competenza e uno stile di comunicazione.
|
|
|
|
|
|
**Pensalo come scegliere diversi attori per diversi ruoli**: Invece di avere un assistente generico, puoi creare esperti specializzati per diverse situazioni. Hai bisogno di un insegnante paziente? Un partner creativo per brainstorming? Un consulente aziendale diretto? Basta cambiare il prompt di sistema!
|
|
|
|
|
|
#### Perché i Prompt di Sistema Sono Così Potenti
|
|
|
|
|
|
Ecco la parte affascinante: i modelli AI sono stati addestrati su innumerevoli conversazioni in cui le persone adottano diversi ruoli e livelli di competenza. Quando dai all'AI un ruolo specifico, è come attivare un interruttore che attiva tutti quei modelli appresi.
|
|
|
|
|
|
**È come il metodo recitativo per l'AI**: Dì a un attore "sei un professore anziano e saggio" e guarda come regolano automaticamente postura, vocabolario e modi. L'AI fa qualcosa di sorprendentemente simile con i modelli linguistici.
|
|
|
|
|
|
#### Creare Prompt di Sistema Efficaci: L'Arte e la Scienza
|
|
|
|
|
|
**L'anatomia di un ottimo prompt di sistema:**
|
|
|
1. **Ruolo/Identità**: Chi è l'AI?
|
|
|
2. **Competenza**: Cosa sa?
|
|
|
3. **Stile di comunicazione**: Come parla?
|
|
|
4. **Istruzioni specifiche**: Su cosa dovrebbe concentrarsi?
|
|
|
|
|
|
```python
|
|
|
# ❌ Vague system prompt
|
|
|
"You are helpful."
|
|
|
|
|
|
# ✅ Detailed, effective system prompt
|
|
|
"You are Dr. Sarah Chen, a senior software engineer with 15 years of experience at major tech companies. You explain programming concepts using real-world analogies and always provide practical examples. You're patient with beginners and enthusiastic about helping them understand complex topics."
|
|
|
```
|
|
|
|
|
|
#### Esempi di Prompt di Sistema con Contesto
|
|
|
|
|
|
Vediamo come diversi prompt di sistema creano personalità AI completamente diverse:
|
|
|
|
|
|
```python
|
|
|
# Example 1: The Patient Teacher
|
|
|
teacher_prompt = """
|
|
|
You are an experienced programming instructor who has taught thousands of students.
|
|
|
You break down complex concepts into simple steps, use analogies from everyday life,
|
|
|
and always check if the student understands before moving on. You're encouraging
|
|
|
and never make students feel bad for not knowing something.
|
|
|
"""
|
|
|
|
|
|
# Example 2: The Creative Collaborator
|
|
|
creative_prompt = """
|
|
|
You are a creative writing partner who loves brainstorming wild ideas. You're
|
|
|
enthusiastic, imaginative, and always build on the user's ideas rather than
|
|
|
replacing them. You ask thought-provoking questions to spark creativity and
|
|
|
offer unexpected perspectives that make stories more interesting.
|
|
|
"""
|
|
|
|
|
|
# Example 3: The Strategic Business Advisor
|
|
|
business_prompt = """
|
|
|
You are a strategic business consultant with an MBA and 20 years of experience
|
|
|
helping startups scale. You think in frameworks, provide structured advice,
|
|
|
and always consider both short-term tactics and long-term strategy. You ask
|
|
|
probing questions to understand the full business context before giving advice.
|
|
|
"""
|
|
|
```
|
|
|
|
|
|
#### Vedere i Prompt di Sistema in Azione
|
|
|
|
|
|
Testiamo la stessa domanda con diversi prompt di sistema per vedere le differenze drammatiche:
|
|
|
|
|
|
**Domanda**: "Come gestisco l'autenticazione degli utenti nella mia app web?"
|
|
|
|
|
|
```python
|
|
|
# With teacher prompt:
|
|
|
teacher_response = call_llm(
|
|
|
"How do I handle user authentication in my web app?",
|
|
|
teacher_prompt
|
|
|
)
|
|
|
# Typical response: "Great question! Let's break authentication down into simple steps.
|
|
|
# Think of it like a nightclub bouncer checking IDs..."
|
|
|
|
|
|
# With business prompt:
|
|
|
business_response = call_llm(
|
|
|
"How do I handle user authentication in my web app?",
|
|
|
business_prompt
|
|
|
)
|
|
|
# Typical response: "From a strategic perspective, authentication is crucial for user
|
|
|
# trust and regulatory compliance. Let me outline a framework considering security,
|
|
|
# user experience, and scalability..."
|
|
|
```
|
|
|
|
|
|
#### Tecniche Avanzate per i Prompt di Sistema
|
|
|
|
|
|
**1. Impostazione del Contesto**: Fornisci all'AI informazioni di background
|
|
|
```python
|
|
|
system_prompt = """
|
|
|
You are helping a junior developer who just started their first job at a startup.
|
|
|
They know basic HTML/CSS/JavaScript but are new to backend development and databases.
|
|
|
Be encouraging and explain things step-by-step without being condescending.
|
|
|
"""
|
|
|
```
|
|
|
|
|
|
**2. Formattazione dell'output**: Indica all'AI come strutturare le risposte
|
|
|
```python
|
|
|
system_prompt = """
|
|
|
You are a technical mentor. Always structure your responses as:
|
|
|
1. Quick Answer (1-2 sentences)
|
|
|
2. Detailed Explanation
|
|
|
3. Code Example
|
|
|
4. Common Pitfalls to Avoid
|
|
|
5. Next Steps for Learning
|
|
|
"""
|
|
|
```
|
|
|
|
|
|
**3. Impostazione dei vincoli**: Definisci cosa l'AI NON deve fare
|
|
|
```python
|
|
|
system_prompt = """
|
|
|
You are a coding tutor focused on teaching best practices. Never write complete
|
|
|
solutions for the user - instead, guide them with hints and questions so they
|
|
|
learn by doing. Always explain the 'why' behind coding decisions.
|
|
|
"""
|
|
|
```
|
|
|
|
|
|
#### Perché è importante per il tuo assistente virtuale
|
|
|
|
|
|
Comprendere i prompt di sistema ti dà un potere incredibile per creare assistenti AI specializzati:
|
|
|
- **Bot per il servizio clienti**: Utile, paziente, consapevole delle politiche
|
|
|
- **Tutor didattico**: Incoraggiante, passo dopo passo, verifica la comprensione
|
|
|
- **Partner creativo**: Immaginativo, sviluppa idee, chiede "e se?"
|
|
|
- **Esperto tecnico**: Preciso, dettagliato, attento alla sicurezza
|
|
|
|
|
|
**L'intuizione chiave**: Non stai solo utilizzando un'API AI – stai creando una personalità AI personalizzata che si adatta al tuo caso d'uso specifico. Questo è ciò che rende le applicazioni AI moderne personalizzate e utili, piuttosto che generiche.
|
|
|
|
|
|
### 🎯 Verifica pedagogica: Programmazione della personalità AI
|
|
|
|
|
|
**Pausa e riflessione**: Hai appena imparato a programmare personalità AI attraverso i prompt di sistema. Questa è una competenza fondamentale nello sviluppo di applicazioni AI moderne.
|
|
|
|
|
|
**Autovalutazione rapida**:
|
|
|
- Sai spiegare come i prompt di sistema differiscono dai messaggi utente regolari?
|
|
|
- Qual è la differenza tra i parametri temperature e top_p?
|
|
|
- Come creeresti un prompt di sistema per un caso d'uso specifico (ad esempio un tutor di programmazione)?
|
|
|
|
|
|
**Connessione al mondo reale**: Le tecniche di prompt di sistema che hai imparato vengono utilizzate in ogni grande applicazione AI - dall'assistenza alla programmazione di GitHub Copilot all'interfaccia conversazionale di ChatGPT. Stai padroneggiando gli stessi schemi utilizzati dai team di prodotto AI delle principali aziende tecnologiche.
|
|
|
|
|
|
**Domanda sfida**: Come potresti progettare personalità AI diverse per diversi tipi di utenti (principiante vs esperto)? Considera come lo stesso modello AI sottostante potrebbe servire pubblici diversi attraverso l'ingegneria dei prompt.
|
|
|
|
|
|
## Creare l'API Web con FastAPI: il tuo hub di comunicazione AI ad alte prestazioni
|
|
|
|
|
|
Ora costruiamo il backend che collega il tuo frontend ai servizi AI. Utilizzeremo FastAPI, un moderno framework Python che eccelle nella creazione di API per applicazioni AI.
|
|
|
|
|
|
FastAPI offre diversi vantaggi per questo tipo di progetto: supporto asincrono integrato per gestire richieste concorrenti, generazione automatica della documentazione API e prestazioni eccellenti. Il server FastAPI agisce come intermediario che riceve richieste dal frontend, comunica con i servizi AI e restituisce risposte formattate.
|
|
|
|
|
|
### Perché scegliere FastAPI per le applicazioni AI?
|
|
|
|
|
|
Potresti chiederti: "Non posso semplicemente chiamare l'AI direttamente dal mio JavaScript frontend?" oppure "Perché FastAPI invece di Flask o Django?" Ottime domande!
|
|
|
|
|
|
**Ecco perché FastAPI è perfetto per ciò che stiamo costruendo:**
|
|
|
- **Asincrono di default**: Può gestire più richieste AI contemporaneamente senza bloccarsi
|
|
|
- **Documentazione automatica**: Visita `/docs` e ottieni una bellissima pagina di documentazione API interattiva gratuitamente
|
|
|
- **Validazione integrata**: Intercetta gli errori prima che causino problemi
|
|
|
- **Velocità fulminea**: Uno dei framework Python più veloci in circolazione
|
|
|
- **Python moderno**: Utilizza tutte le funzionalità più recenti e migliori di Python
|
|
|
|
|
|
**Ecco perché abbiamo bisogno di un backend:**
|
|
|
|
|
|
**Sicurezza**: La tua chiave API AI è come una password – se la metti nel JavaScript del frontend, chiunque visualizzi il codice sorgente del tuo sito web potrebbe rubarla e usarla. Il backend mantiene al sicuro le credenziali sensibili.
|
|
|
|
|
|
**Limitazione della velocità e controllo**: Il backend ti consente di controllare la frequenza con cui gli utenti possono effettuare richieste, implementare l'autenticazione degli utenti e aggiungere registri per monitorare l'utilizzo.
|
|
|
|
|
|
**Elaborazione dei dati**: Potresti voler salvare conversazioni, filtrare contenuti inappropriati o combinare più servizi AI. Il backend è il luogo in cui vive questa logica.
|
|
|
|
|
|
**L'architettura assomiglia a un modello client-server:**
|
|
|
- **Frontend**: Livello dell'interfaccia utente per l'interazione
|
|
|
- **Backend API**: Livello di elaborazione e instradamento delle richieste
|
|
|
- **Servizio AI**: Calcolo esterno e generazione delle risposte
|
|
|
- **Variabili d'ambiente**: Configurazione sicura e archiviazione delle credenziali
|
|
|
|
|
|
### Comprendere il flusso di richiesta-risposta
|
|
|
|
|
|
Tracciamo cosa succede quando un utente invia un messaggio:
|
|
|
|
|
|
```mermaid
|
|
|
sequenceDiagram
|
|
|
participant User as 👤 User
|
|
|
participant Frontend as 🌐 Frontend
|
|
|
participant API as 🔧 FastAPI Server
|
|
|
participant AI as 🤖 AI Service
|
|
|
|
|
|
User->>Frontend: Types "Hello AI!"
|
|
|
Frontend->>API: POST /hello {"message": "Hello AI!"}
|
|
|
Note over API: Validates request<br/>Adds system prompt
|
|
|
API->>AI: Sends formatted request
|
|
|
AI->>API: Returns AI response
|
|
|
Note over API: Processes response<br/>Logs conversation
|
|
|
API->>Frontend: {"response": "Hello! How can I help?"}
|
|
|
Frontend->>User: Displays AI message
|
|
|
```
|
|
|
|
|
|
**Comprendere ogni passaggio:**
|
|
|
1. **Interazione utente**: La persona digita nell'interfaccia di chat
|
|
|
2. **Elaborazione frontend**: JavaScript cattura l'input e lo formatta come JSON
|
|
|
3. **Validazione API**: FastAPI valida automaticamente la richiesta utilizzando modelli Pydantic
|
|
|
4. **Integrazione AI**: Il backend aggiunge contesto (prompt di sistema) e chiama il servizio AI
|
|
|
5. **Gestione della risposta**: L'API riceve la risposta AI e può modificarla se necessario
|
|
|
6. **Visualizzazione frontend**: JavaScript mostra la risposta nell'interfaccia di chat
|
|
|
|
|
|
### Comprendere l'architettura API
|
|
|
|
|
|
```mermaid
|
|
|
sequenceDiagram
|
|
|
participant Frontend
|
|
|
participant FastAPI
|
|
|
participant AI Function
|
|
|
participant GitHub Models
|
|
|
|
|
|
Frontend->>FastAPI: POST /hello {"message": "Hello AI!"}
|
|
|
FastAPI->>AI Function: call_llm(message, system_prompt)
|
|
|
AI Function->>GitHub Models: API request
|
|
|
GitHub Models->>AI Function: AI response
|
|
|
AI Function->>FastAPI: response text
|
|
|
FastAPI->>Frontend: {"response": "Hello! How can I help?"}
|
|
|
```
|
|
|
|
|
|
```mermaid
|
|
|
flowchart TD
|
|
|
A[User Input] --> B[Frontend Validation]
|
|
|
B --> C[HTTP POST Request]
|
|
|
C --> D[FastAPI Router]
|
|
|
D --> E[Pydantic Validation]
|
|
|
E --> F[AI Function Call]
|
|
|
F --> G[GitHub Models API]
|
|
|
G --> H[Response Processing]
|
|
|
H --> I[JSON Response]
|
|
|
I --> J[Frontend Update]
|
|
|
|
|
|
subgraph "Security Layer"
|
|
|
K[CORS Middleware]
|
|
|
L[Environment Variables]
|
|
|
M[Error Handling]
|
|
|
end
|
|
|
|
|
|
D --> K
|
|
|
F --> L
|
|
|
H --> M
|
|
|
```
|
|
|
|
|
|
### Creare l'applicazione FastAPI
|
|
|
|
|
|
Costruiamo la nostra API passo dopo passo. Crea un file chiamato `api.py` con il seguente codice FastAPI:
|
|
|
|
|
|
```python
|
|
|
# api.py
|
|
|
from fastapi import FastAPI, HTTPException
|
|
|
from fastapi.middleware.cors import CORSMiddleware
|
|
|
from pydantic import BaseModel
|
|
|
from llm import call_llm
|
|
|
import logging
|
|
|
|
|
|
# Configure logging
|
|
|
logging.basicConfig(level=logging.INFO)
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
|
|
# Create FastAPI application
|
|
|
app = FastAPI(
|
|
|
title="AI Chat API",
|
|
|
description="A high-performance API for AI-powered chat applications",
|
|
|
version="1.0.0"
|
|
|
)
|
|
|
|
|
|
# Configure CORS
|
|
|
app.add_middleware(
|
|
|
CORSMiddleware,
|
|
|
allow_origins=["*"], # Configure appropriately for production
|
|
|
allow_credentials=True,
|
|
|
allow_methods=["*"],
|
|
|
allow_headers=["*"],
|
|
|
)
|
|
|
|
|
|
# Pydantic models for request/response validation
|
|
|
class ChatMessage(BaseModel):
|
|
|
message: str
|
|
|
|
|
|
class ChatResponse(BaseModel):
|
|
|
response: str
|
|
|
|
|
|
@app.get("/")
|
|
|
async def root():
|
|
|
"""Root endpoint providing API information."""
|
|
|
return {
|
|
|
"message": "Welcome to the AI Chat API",
|
|
|
"docs": "/docs",
|
|
|
"health": "/health"
|
|
|
}
|
|
|
|
|
|
@app.get("/health")
|
|
|
async def health_check():
|
|
|
"""Health check endpoint."""
|
|
|
return {"status": "healthy", "service": "ai-chat-api"}
|
|
|
|
|
|
@app.post("/hello", response_model=ChatResponse)
|
|
|
async def chat_endpoint(chat_message: ChatMessage):
|
|
|
"""Main chat endpoint that processes messages and returns AI responses."""
|
|
|
try:
|
|
|
# Extract and validate message
|
|
|
message = chat_message.message.strip()
|
|
|
if not message:
|
|
|
raise HTTPException(status_code=400, detail="Message cannot be empty")
|
|
|
|
|
|
logger.info(f"Processing message: {message[:50]}...")
|
|
|
|
|
|
# Call AI service (note: call_llm should be made async for better performance)
|
|
|
ai_response = await call_llm_async(message, "You are a helpful and friendly assistant.")
|
|
|
|
|
|
logger.info("AI response generated successfully")
|
|
|
return ChatResponse(response=ai_response)
|
|
|
|
|
|
except HTTPException:
|
|
|
raise
|
|
|
except Exception as e:
|
|
|
logger.error(f"Error processing chat message: {str(e)}")
|
|
|
raise HTTPException(status_code=500, detail="Internal server error")
|
|
|
|
|
|
if __name__ == "__main__":
|
|
|
import uvicorn
|
|
|
uvicorn.run(app, host="0.0.0.0", port=5000, reload=True)
|
|
|
```
|
|
|
|
|
|
**Comprendere l'implementazione FastAPI:**
|
|
|
- **Importa** FastAPI per la funzionalità del framework web moderno e Pydantic per la validazione dei dati
|
|
|
- **Crea** documentazione API automatica (disponibile su `/docs` quando il server è in esecuzione)
|
|
|
- **Abilita** il middleware CORS per consentire richieste frontend da origini diverse
|
|
|
- **Definisce** modelli Pydantic per la validazione automatica delle richieste/risposte e la documentazione
|
|
|
- **Utilizza** endpoint asincroni per migliori prestazioni con richieste concorrenti
|
|
|
- **Implementa** codici di stato HTTP appropriati e gestione degli errori con HTTPException
|
|
|
- **Include** registri strutturati per il monitoraggio e il debug
|
|
|
- **Fornisce** un endpoint di controllo dello stato per monitorare lo stato del servizio
|
|
|
|
|
|
**Vantaggi chiave di FastAPI rispetto ai framework tradizionali:**
|
|
|
- **Validazione automatica**: I modelli Pydantic garantiscono l'integrità dei dati prima dell'elaborazione
|
|
|
- **Documentazione interattiva**: Visita `/docs` per una documentazione API generata automaticamente e testabile
|
|
|
- **Sicurezza dei tipi**: Gli hint di tipo Python prevengono errori di runtime e migliorano la qualità del codice
|
|
|
- **Supporto asincrono**: Gestisce più richieste AI simultaneamente senza blocchi
|
|
|
- **Prestazioni**: Elaborazione delle richieste significativamente più veloce per applicazioni in tempo reale
|
|
|
|
|
|
### Comprendere CORS: La guardia di sicurezza del web
|
|
|
|
|
|
CORS (Cross-Origin Resource Sharing) è come una guardia di sicurezza in un edificio che controlla se i visitatori sono autorizzati a entrare. Cerchiamo di capire perché è importante e come influisce sulla tua applicazione.
|
|
|
|
|
|
#### Cos'è CORS e perché esiste?
|
|
|
|
|
|
**Il problema**: Immagina se qualsiasi sito web potesse fare richieste al sito della tua banca per tuo conto senza il tuo permesso. Sarebbe un incubo di sicurezza! I browser lo impediscono di default attraverso la "Same-Origin Policy".
|
|
|
|
|
|
**Same-Origin Policy**: I browser consentono solo alle pagine web di effettuare richieste allo stesso dominio, porta e protocollo da cui sono state caricate.
|
|
|
|
|
|
**Analogia nel mondo reale**: È come la sicurezza di un condominio – solo i residenti (stessa origine) possono accedere all'edificio di default. Se vuoi far visitare un amico (origine diversa), devi esplicitamente dire alla sicurezza che va bene.
|
|
|
|
|
|
#### CORS nel tuo ambiente di sviluppo
|
|
|
|
|
|
Durante lo sviluppo, il tuo frontend e backend funzionano su porte diverse:
|
|
|
- Frontend: `http://localhost:3000` (o file:// se apri direttamente l'HTML)
|
|
|
- Backend: `http://localhost:5000`
|
|
|
|
|
|
Questi sono considerati "origini diverse" anche se sono sullo stesso computer!
|
|
|
|
|
|
```python
|
|
|
from fastapi.middleware.cors import CORSMiddleware
|
|
|
|
|
|
app = FastAPI(__name__)
|
|
|
CORS(app) # This tells browsers: "It's okay for other origins to make requests to this API"
|
|
|
```
|
|
|
|
|
|
**Cosa fa la configurazione CORS in pratica:**
|
|
|
- **Aggiunge** intestazioni HTTP speciali alle risposte API che dicono ai browser "questa richiesta cross-origin è consentita"
|
|
|
- **Gestisce** richieste "preflight" (i browser a volte controllano i permessi prima di inviare la richiesta effettiva)
|
|
|
- **Previene** il temuto errore "bloccato dalla politica CORS" nella console del browser
|
|
|
|
|
|
#### Sicurezza CORS: Sviluppo vs Produzione
|
|
|
|
|
|
```python
|
|
|
# 🚨 Development: Allows ALL origins (convenient but insecure)
|
|
|
CORS(app)
|
|
|
|
|
|
# ✅ Production: Only allow your specific frontend domain
|
|
|
CORS(app, origins=["https://yourdomain.com", "https://www.yourdomain.com"])
|
|
|
|
|
|
# 🔒 Advanced: Different origins for different environments
|
|
|
if app.debug: # Development mode
|
|
|
CORS(app, origins=["http://localhost:3000", "http://127.0.0.1:3000"])
|
|
|
else: # Production mode
|
|
|
CORS(app, origins=["https://yourdomain.com"])
|
|
|
```
|
|
|
|
|
|
**Perché è importante**: In fase di sviluppo, `CORS(app)` è come lasciare la porta di casa aperta – comodo ma non sicuro. In produzione, vuoi specificare esattamente quali siti web possono comunicare con la tua API.
|
|
|
|
|
|
#### Scenari comuni CORS e soluzioni
|
|
|
|
|
|
| Scenario | Problema | Soluzione |
|
|
|
|----------|---------|----------|
|
|
|
| **Sviluppo locale** | Il frontend non può raggiungere il backend | Aggiungi CORSMiddleware a FastAPI |
|
|
|
| **GitHub Pages + Heroku** | Il frontend distribuito non può raggiungere l'API | Aggiungi l'URL di GitHub Pages alle origini CORS |
|
|
|
| **Dominio personalizzato** | Errori CORS in produzione | Aggiorna le origini CORS per corrispondere al tuo dominio |
|
|
|
| **App mobile** | L'app non può raggiungere l'API web | Aggiungi il dominio della tua app o usa `*` con cautela |
|
|
|
|
|
|
**Suggerimento professionale**: Puoi controllare le intestazioni CORS negli strumenti per sviluppatori del tuo browser nella scheda Rete. Cerca intestazioni come `Access-Control-Allow-Origin` nella risposta.
|
|
|
|
|
|
### Gestione degli errori e validazione
|
|
|
|
|
|
Nota come la nostra API include una corretta gestione degli errori:
|
|
|
|
|
|
```python
|
|
|
# Validate that we received a message
|
|
|
if not message:
|
|
|
return jsonify({"error": "Message field is required"}), 400
|
|
|
```
|
|
|
|
|
|
**Principi chiave di validazione:**
|
|
|
- **Controlla** i campi richiesti prima di elaborare le richieste
|
|
|
- **Restituisce** messaggi di errore significativi in formato JSON
|
|
|
- **Utilizza** codici di stato HTTP appropriati (400 per richieste errate)
|
|
|
- **Fornisce** feedback chiari per aiutare gli sviluppatori frontend a risolvere i problemi
|
|
|
|
|
|
## Configurazione e avvio del backend
|
|
|
|
|
|
Ora che abbiamo la nostra integrazione AI e il server FastAPI pronto, mettiamo tutto in funzione. Il processo di configurazione prevede l'installazione delle dipendenze Python, la configurazione delle variabili d'ambiente e l'avvio del server di sviluppo.
|
|
|
|
|
|
### Configurazione dell'ambiente Python
|
|
|
|
|
|
Configuriamo il tuo ambiente di sviluppo Python. Gli ambienti virtuali sono come l'approccio compartimentato del Progetto Manhattan – ogni progetto ha il proprio spazio isolato con strumenti e dipendenze specifici, prevenendo conflitti tra progetti diversi.
|
|
|
|
|
|
```bash
|
|
|
# Navigate to your backend directory
|
|
|
cd backend
|
|
|
|
|
|
# Create a virtual environment (like creating a clean room for your project)
|
|
|
python -m venv venv
|
|
|
|
|
|
# Activate it (Linux/Mac)
|
|
|
source ./venv/bin/activate
|
|
|
|
|
|
# On Windows, use:
|
|
|
# venv\Scripts\activate
|
|
|
|
|
|
# Install the good stuff
|
|
|
pip install openai fastapi uvicorn python-dotenv
|
|
|
```
|
|
|
|
|
|
**Cosa abbiamo appena fatto:**
|
|
|
- **Creato** una piccola bolla Python dove possiamo installare pacchetti senza influenzare nient'altro
|
|
|
- **Attivato** l'ambiente in modo che il terminale sappia di utilizzare questo ambiente specifico
|
|
|
- **Installato** gli elementi essenziali: OpenAI per la magia AI, FastAPI per la nostra API web, Uvicorn per eseguirla e python-dotenv per la gestione sicura dei segreti
|
|
|
|
|
|
**Dipendenze chiave spiegate:**
|
|
|
- **FastAPI**: Framework web moderno e veloce con documentazione API automatica
|
|
|
- **Uvicorn**: Server ASGI fulmineo che esegue applicazioni FastAPI
|
|
|
- **OpenAI**: Libreria ufficiale per l'integrazione con i modelli GitHub e l'API OpenAI
|
|
|
- **python-dotenv**: Caricamento sicuro delle variabili d'ambiente dai file .env
|
|
|
|
|
|
### Configurazione dell'ambiente: mantenere i segreti al sicuro
|
|
|
|
|
|
Prima di avviare la nostra API, dobbiamo parlare di una delle lezioni più importanti nello sviluppo web: come mantenere i tuoi segreti davvero segreti. Le variabili d'ambiente sono come una cassaforte sicura che solo la tua applicazione può accedere.
|
|
|
|
|
|
#### Cosa sono le variabili d'ambiente?
|
|
|
|
|
|
**Pensa alle variabili d'ambiente come a una cassetta di sicurezza** – metti le tue cose preziose lì dentro e solo tu (e la tua app) hai la chiave per accedervi. Invece di scrivere informazioni sensibili direttamente nel codice (dove chiunque può vederle), le memorizzi in modo sicuro nell'ambiente.
|
|
|
|
|
|
**Ecco la differenza:**
|
|
|
- **Modo sbagliato**: Scrivere la tua password su un post-it e metterlo sul monitor
|
|
|
- **Modo giusto**: Conservare la tua password in un gestore di password sicuro che solo tu puoi accedere
|
|
|
|
|
|
#### Perché le variabili d'ambiente sono importanti
|
|
|
|
|
|
```python
|
|
|
# 🚨 NEVER DO THIS - API key visible to everyone
|
|
|
client = OpenAI(
|
|
|
api_key="ghp_1234567890abcdef...", # Anyone can steal this!
|
|
|
base_url="https://models.github.ai/inference"
|
|
|
)
|
|
|
|
|
|
# ✅ DO THIS - API key stored securely
|
|
|
client = OpenAI(
|
|
|
api_key=os.environ["GITHUB_TOKEN"], # Only your app can access this
|
|
|
base_url="https://models.github.ai/inference"
|
|
|
)
|
|
|
```
|
|
|
|
|
|
**Cosa succede quando codifichi i segreti:**
|
|
|
1. **Esposizione al controllo di versione**: Chiunque abbia accesso al tuo repository Git vede la tua chiave API
|
|
|
2. **Repository pubblici**: Se pubblichi su GitHub, la tua chiave è visibile a tutto internet
|
|
|
3. **Condivisione del team**: Altri sviluppatori che lavorano sul tuo progetto ottengono accesso alla tua chiave API personale
|
|
|
4. **Violazioni della sicurezza**: Se qualcuno ruba la tua chiave API, può utilizzare i tuoi crediti AI
|
|
|
|
|
|
#### Configurazione del file di ambiente
|
|
|
|
|
|
Crea un file `.env` nella directory del tuo backend. Questo file memorizza i tuoi segreti localmente:
|
|
|
|
|
|
```bash
|
|
|
# .env file - This should NEVER be committed to Git
|
|
|
GITHUB_TOKEN=your_github_personal_access_token_here
|
|
|
FASTAPI_DEBUG=True
|
|
|
ENVIRONMENT=development
|
|
|
```
|
|
|
|
|
|
**Comprendere il file .env:**
|
|
|
- **Un segreto per riga** nel formato `KEY=value`
|
|
|
- **Nessuno spazio** intorno al segno di uguale
|
|
|
- **Nessuna necessità di virgolette** intorno ai valori (di solito)
|
|
|
- **Commenti** iniziano con `#`
|
|
|
|
|
|
#### Creazione del tuo token di accesso personale GitHub
|
|
|
|
|
|
Il tuo token GitHub è come una password speciale che dà alla tua applicazione il permesso di utilizzare i servizi AI di GitHub:
|
|
|
|
|
|
**Passaggi per creare il token:**
|
|
|
1. **Vai alle Impostazioni GitHub** → Impostazioni sviluppatore → Token di accesso personale → Token (classici)
|
|
|
2. **Clicca su "Genera nuovo token (classico)"**
|
|
|
3. **Imposta la scadenza** (30 giorni per i test, più lunga per la produzione)
|
|
|
4. **Seleziona gli ambiti**: Seleziona "repo" e qualsiasi altra autorizzazione necessaria
|
|
|
5. **Genera il token** e copialo immediatamente (non puoi vederlo di nuovo!)
|
|
|
6. **Incolla nel tuo file .env**
|
|
|
|
|
|
```bash
|
|
|
# Example of what your token looks like (this is fake!)
|
|
|
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R
|
|
|
```
|
|
|
|
|
|
#### Caricamento delle variabili d'ambiente in Python
|
|
|
|
|
|
```python
|
|
|
import os
|
|
|
from dotenv import load_dotenv
|
|
|
|
|
|
# Load environment variables from .env file
|
|
|
load_dotenv()
|
|
|
|
|
|
# Now you can access them securely
|
|
|
api_key = os.environ.get("GITHUB_TOKEN")
|
|
|
if not api_key:
|
|
|
raise ValueError("GITHUB_TOKEN not found in environment variables!")
|
|
|
|
|
|
client = OpenAI(
|
|
|
api_key=api_key,
|
|
|
base_url="https://models.github.ai/inference"
|
|
|
)
|
|
|
```
|
|
|
|
|
|
**Cosa fa questo codice:**
|
|
|
- **Carica** il tuo file .env e rende le variabili disponibili per Python
|
|
|
- **Controlla** se il token richiesto esiste (buona gestione degli errori!)
|
|
|
- **Genera** un errore chiaro se il token manca
|
|
|
- **Utilizza** il token in modo sicuro senza esporlo nel codice
|
|
|
|
|
|
#### Sicurezza Git: Il file .gitignore
|
|
|
|
|
|
Il tuo file `.gitignore` dice a Git quali file non tracciare o caricare mai:
|
|
|
|
|
|
```bash
|
|
|
# .gitignore - Add these lines
|
|
|
.env
|
|
|
*.env
|
|
|
.env.local
|
|
|
.env.production
|
|
|
__pycache__/
|
|
|
venv/
|
|
|
.vscode/
|
|
|
```
|
|
|
|
|
|
**Perché è cruciale**: Una volta aggiunto `.env` a `.gitignore`, Git ignorerà il tuo file di ambiente, impedendoti di caricare accidentalmente i tuoi segreti su GitHub.
|
|
|
|
|
|
#### Ambienti diversi, segreti diversi
|
|
|
|
|
|
Le applicazioni professionali utilizzano chiavi API diverse per ambienti diversi:
|
|
|
|
|
|
```bash
|
|
|
# .env.development
|
|
|
GITHUB_TOKEN=your_development_token
|
|
|
DEBUG=True
|
|
|
|
|
|
# .env.production
|
|
|
GITHUB_TOKEN=your_production_token
|
|
|
DEBUG=False
|
|
|
```
|
|
|
|
|
|
**Perché è importante**: Non vuoi che i tuoi esperimenti di sviluppo influenzino la tua quota di utilizzo AI in produzione, e vuoi livelli di sicurezza diversi per ambienti diversi.
|
|
|
|
|
|
### Avvio del server di sviluppo: dare vita al tuo FastAPI
|
|
|
Ora arriva il momento emozionante: avviare il server di sviluppo FastAPI e vedere la tua integrazione AI prendere vita! FastAPI utilizza Uvicorn, un server ASGI ultra veloce progettato specificamente per applicazioni Python asincrone.
|
|
|
|
|
|
#### Comprendere il processo di avvio del server FastAPI
|
|
|
|
|
|
```bash
|
|
|
# Method 1: Direct Python execution (includes auto-reload)
|
|
|
python api.py
|
|
|
|
|
|
# Method 2: Using Uvicorn directly (more control)
|
|
|
uvicorn api:app --host 0.0.0.0 --port 5000 --reload
|
|
|
```
|
|
|
|
|
|
Quando esegui questo comando, ecco cosa accade dietro le quinte:
|
|
|
|
|
|
**1. Python carica la tua applicazione FastAPI**:
|
|
|
- Importa tutte le librerie necessarie (FastAPI, Pydantic, OpenAI, ecc.)
|
|
|
- Carica le variabili d'ambiente dal file `.env`
|
|
|
- Crea l'istanza dell'applicazione FastAPI con documentazione automatica
|
|
|
|
|
|
**2. Uvicorn configura il server ASGI**:
|
|
|
- Si collega alla porta 5000 con capacità di gestione delle richieste asincrone
|
|
|
- Configura il routing delle richieste con validazione automatica
|
|
|
- Abilita il ricaricamento automatico per lo sviluppo (riavvio al cambio dei file)
|
|
|
- Genera documentazione API interattiva
|
|
|
|
|
|
**3. Il server inizia ad ascoltare**:
|
|
|
- Il terminale mostra: `INFO: Uvicorn running on http://0.0.0.0:5000`
|
|
|
- Il server può gestire richieste AI concorrenti
|
|
|
- La tua API è pronta con documentazione automatica su `http://localhost:5000/docs`
|
|
|
|
|
|
#### Cosa dovresti vedere quando tutto funziona
|
|
|
|
|
|
```bash
|
|
|
$ python api.py
|
|
|
INFO: Will watch for changes in these directories: ['/your/project/path']
|
|
|
INFO: Uvicorn running on http://0.0.0.0:5000 (Press CTRL+C to quit)
|
|
|
INFO: Started reloader process [12345] using WatchFiles
|
|
|
INFO: Started server process [12346]
|
|
|
INFO: Waiting for application startup.
|
|
|
INFO: Application startup complete.
|
|
|
```
|
|
|
|
|
|
**Comprendere l'output di FastAPI:**
|
|
|
- **Will watch for changes**: Ricaricamento automatico abilitato per lo sviluppo
|
|
|
- **Uvicorn running**: Il server ASGI ad alte prestazioni è attivo
|
|
|
- **Started reloader process**: Osservatore di file per riavvii automatici
|
|
|
- **Application startup complete**: App FastAPI inizializzata con successo
|
|
|
- **Interactive docs available**: Visita `/docs` per la documentazione API automatica
|
|
|
|
|
|
#### Testare il tuo FastAPI: Approcci potenti e multipli
|
|
|
|
|
|
FastAPI offre diversi modi convenienti per testare la tua API, inclusa la documentazione interattiva automatica:
|
|
|
|
|
|
**Metodo 1: Documentazione API interattiva (consigliato)**
|
|
|
1. Apri il browser e vai su `http://localhost:5000/docs`
|
|
|
2. Vedrai Swagger UI con tutti i tuoi endpoint documentati
|
|
|
3. Clicca su `/hello` → "Try it out" → Inserisci un messaggio di prova → "Execute"
|
|
|
4. Visualizza la risposta direttamente nel browser con formattazione corretta
|
|
|
|
|
|
**Metodo 2: Test di base nel browser**
|
|
|
1. Vai su `http://localhost:5000` per l'endpoint principale
|
|
|
2. Vai su `http://localhost:5000/health` per controllare lo stato del server
|
|
|
3. Questo conferma che il server FastAPI è in esecuzione correttamente
|
|
|
|
|
|
**Metodo 2: Test da riga di comando (avanzato)**
|
|
|
```bash
|
|
|
# Test with curl (if available)
|
|
|
curl -X POST http://localhost:5000/hello \
|
|
|
-H "Content-Type: application/json" \
|
|
|
-d '{"message": "Hello AI!"}'
|
|
|
|
|
|
# Expected response:
|
|
|
# {"response": "Hello! I'm your AI assistant. How can I help you today?"}
|
|
|
```
|
|
|
|
|
|
**Metodo 3: Script di test Python**
|
|
|
```python
|
|
|
# test_api.py - Create this file to test your API
|
|
|
import requests
|
|
|
import json
|
|
|
|
|
|
# Test the API endpoint
|
|
|
url = "http://localhost:5000/hello"
|
|
|
data = {"message": "Tell me a joke about programming"}
|
|
|
|
|
|
response = requests.post(url, json=data)
|
|
|
if response.status_code == 200:
|
|
|
result = response.json()
|
|
|
print("AI Response:", result['response'])
|
|
|
else:
|
|
|
print("Error:", response.status_code, response.text)
|
|
|
```
|
|
|
|
|
|
#### Risoluzione dei problemi comuni di avvio
|
|
|
|
|
|
| Messaggio di errore | Cosa significa | Come risolvere |
|
|
|
|---------------------|----------------|----------------|
|
|
|
| `ModuleNotFoundError: No module named 'fastapi'` | FastAPI non installato | Esegui `pip install fastapi uvicorn` nel tuo ambiente virtuale |
|
|
|
| `ModuleNotFoundError: No module named 'uvicorn'` | Server ASGI non installato | Esegui `pip install uvicorn` nel tuo ambiente virtuale |
|
|
|
| `KeyError: 'GITHUB_TOKEN'` | Variabile d'ambiente non trovata | Controlla il file `.env` e la chiamata `load_dotenv()` |
|
|
|
| `Address already in use` | La porta 5000 è occupata | Termina altri processi che utilizzano la porta 5000 o cambia porta |
|
|
|
| `ValidationError` | I dati della richiesta non corrispondono al modello Pydantic | Controlla che il formato della richiesta corrisponda allo schema previsto |
|
|
|
| `HTTPException 422` | Entità non processabile | La validazione della richiesta è fallita, controlla `/docs` per il formato corretto |
|
|
|
| `OpenAI API error` | Autenticazione del servizio AI fallita | Verifica che il tuo token GitHub sia corretto e abbia i permessi adeguati |
|
|
|
|
|
|
#### Migliori pratiche di sviluppo
|
|
|
|
|
|
**Ricaricamento automatico**: FastAPI con Uvicorn fornisce il ricaricamento automatico quando salvi modifiche ai file Python. Questo significa che puoi modificare il codice e testare immediatamente senza riavviare manualmente.
|
|
|
|
|
|
```python
|
|
|
# Enable hot reloading explicitly
|
|
|
if __name__ == "__main__":
|
|
|
app.run(host="0.0.0.0", port=5000, debug=True) # debug=True enables hot reload
|
|
|
```
|
|
|
|
|
|
**Logging per lo sviluppo**: Aggiungi il logging per capire cosa sta succedendo:
|
|
|
|
|
|
```python
|
|
|
import logging
|
|
|
|
|
|
# Set up logging
|
|
|
logging.basicConfig(level=logging.INFO)
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
|
|
@app.route("/hello", methods=["POST"])
|
|
|
def hello():
|
|
|
data = request.get_json()
|
|
|
message = data.get("message", "")
|
|
|
|
|
|
logger.info(f"Received message: {message}")
|
|
|
|
|
|
if not message:
|
|
|
logger.warning("Empty message received")
|
|
|
return jsonify({"error": "Message field is required"}), 400
|
|
|
|
|
|
try:
|
|
|
response = call_llm(message, "You are a helpful and friendly assistant.")
|
|
|
logger.info(f"AI response generated successfully")
|
|
|
return jsonify({"response": response})
|
|
|
except Exception as e:
|
|
|
logger.error(f"AI API error: {str(e)}")
|
|
|
return jsonify({"error": "AI service temporarily unavailable"}), 500
|
|
|
```
|
|
|
|
|
|
**Perché il logging aiuta**: Durante lo sviluppo, puoi vedere esattamente quali richieste arrivano, cosa risponde l'AI e dove si verificano gli errori. Questo rende il debug molto più veloce.
|
|
|
|
|
|
### Configurazione per GitHub Codespaces: Sviluppo cloud semplificato
|
|
|
|
|
|
GitHub Codespaces è come avere un potente computer di sviluppo nel cloud accessibile da qualsiasi browser. Se stai lavorando in Codespaces, ci sono alcuni passaggi aggiuntivi per rendere il tuo backend accessibile al frontend.
|
|
|
|
|
|
#### Comprendere il networking di Codespaces
|
|
|
|
|
|
In un ambiente di sviluppo locale, tutto funziona sullo stesso computer:
|
|
|
- Backend: `http://localhost:5000`
|
|
|
- Frontend: `http://localhost:3000` (o file://)
|
|
|
|
|
|
In Codespaces, il tuo ambiente di sviluppo funziona sui server di GitHub, quindi "localhost" ha un significato diverso. GitHub crea automaticamente URL pubblici per i tuoi servizi, ma devi configurarli correttamente.
|
|
|
|
|
|
#### Configurazione passo-passo di Codespaces
|
|
|
|
|
|
**1. Avvia il server backend**:
|
|
|
```bash
|
|
|
cd backend
|
|
|
python api.py
|
|
|
```
|
|
|
|
|
|
Vedrai il familiare messaggio di avvio di FastAPI/Uvicorn, ma noterai che è in esecuzione nell'ambiente Codespace.
|
|
|
|
|
|
**2. Configura la visibilità della porta**:
|
|
|
- Cerca la scheda "Ports" nel pannello inferiore di VS Code
|
|
|
- Trova la porta 5000 nell'elenco
|
|
|
- Clicca con il tasto destro sulla porta 5000
|
|
|
- Seleziona "Port Visibility" → "Public"
|
|
|
|
|
|
**Perché renderla pubblica?** Di default, le porte di Codespace sono private (accessibili solo a te). Renderle pubbliche consente al tuo frontend (che funziona nel browser) di comunicare con il backend.
|
|
|
|
|
|
**3. Ottieni il tuo URL pubblico**:
|
|
|
Dopo aver reso la porta pubblica, vedrai un URL simile:
|
|
|
```
|
|
|
https://your-codespace-name-5000.app.github.dev
|
|
|
```
|
|
|
|
|
|
**4. Aggiorna la configurazione del frontend**:
|
|
|
```javascript
|
|
|
// In your frontend app.js, update the BASE_URL:
|
|
|
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
|
|
|
```
|
|
|
|
|
|
#### Comprendere gli URL di Codespace
|
|
|
|
|
|
Gli URL di Codespace seguono un modello prevedibile:
|
|
|
```
|
|
|
https://[codespace-name]-[port].app.github.dev
|
|
|
```
|
|
|
|
|
|
**Analisi di questo modello:**
|
|
|
- `codespace-name`: Un identificatore unico per il tuo Codespace (di solito include il tuo nome utente)
|
|
|
- `port`: Il numero di porta su cui il tuo servizio è in esecuzione (5000 per la nostra app FastAPI)
|
|
|
- `app.github.dev`: Dominio di GitHub per le applicazioni Codespace
|
|
|
|
|
|
#### Testare la configurazione di Codespace
|
|
|
|
|
|
**1. Testa direttamente il backend**:
|
|
|
Apri il tuo URL pubblico in una nuova scheda del browser. Dovresti vedere:
|
|
|
```
|
|
|
Welcome to the AI Chat API. Send POST requests to /hello with JSON payload containing 'message' field.
|
|
|
```
|
|
|
|
|
|
**2. Testa con gli strumenti per sviluppatori del browser**:
|
|
|
```javascript
|
|
|
// Open browser console and test your API
|
|
|
fetch('https://your-codespace-name-5000.app.github.dev/hello', {
|
|
|
method: 'POST',
|
|
|
headers: {'Content-Type': 'application/json'},
|
|
|
body: JSON.stringify({message: 'Hello from Codespaces!'})
|
|
|
})
|
|
|
.then(response => response.json())
|
|
|
.then(data => console.log(data));
|
|
|
```
|
|
|
|
|
|
#### Codespaces vs Sviluppo Locale
|
|
|
|
|
|
| Aspetto | Sviluppo Locale | GitHub Codespaces |
|
|
|
|---------|-----------------|-------------------|
|
|
|
| **Tempo di configurazione** | Più lungo (installazione di Python, dipendenze) | Istantaneo (ambiente preconfigurato) |
|
|
|
| **Accesso URL** | `http://localhost:5000` | `https://xyz-5000.app.github.dev` |
|
|
|
| **Configurazione porta** | Automatica | Manuale (rendere le porte pubbliche) |
|
|
|
| **Persistenza file** | Macchina locale | Repository GitHub |
|
|
|
| **Collaborazione** | Difficile condividere l'ambiente | Facile condividere il link Codespace |
|
|
|
| **Dipendenza da Internet** | Solo per chiamate API AI | Necessaria per tutto |
|
|
|
|
|
|
#### Consigli per lo sviluppo in Codespaces
|
|
|
|
|
|
**Variabili d'ambiente in Codespaces**:
|
|
|
Il tuo file `.env` funziona allo stesso modo in Codespaces, ma puoi anche impostare variabili d'ambiente direttamente nel Codespace:
|
|
|
|
|
|
```bash
|
|
|
# Set environment variable for the current session
|
|
|
export GITHUB_TOKEN="your_token_here"
|
|
|
|
|
|
# Or add to your .bashrc for persistence
|
|
|
echo 'export GITHUB_TOKEN="your_token_here"' >> ~/.bashrc
|
|
|
```
|
|
|
|
|
|
**Gestione delle porte**:
|
|
|
- Codespaces rileva automaticamente quando la tua applicazione inizia ad ascoltare su una porta
|
|
|
- Puoi inoltrare più porte contemporaneamente (utile se aggiungi un database in seguito)
|
|
|
- Le porte rimangono accessibili finché il tuo Codespace è in esecuzione
|
|
|
|
|
|
**Workflow di sviluppo**:
|
|
|
1. Apporta modifiche al codice in VS Code
|
|
|
2. FastAPI si ricarica automaticamente (grazie alla modalità di ricaricamento di Uvicorn)
|
|
|
3. Testa immediatamente le modifiche tramite l'URL pubblico
|
|
|
4. Effettua il commit e il push quando sei pronto
|
|
|
|
|
|
> 💡 **Consiglio Pro**: Salva nei preferiti l'URL del backend del tuo Codespace durante lo sviluppo. Poiché i nomi dei Codespace sono stabili, l'URL non cambierà finché utilizzi lo stesso Codespace.
|
|
|
|
|
|
## Creare l'interfaccia chat del frontend: dove gli esseri umani incontrano l'AI
|
|
|
|
|
|
Ora costruiremo l'interfaccia utente – la parte che determina come le persone interagiscono con il tuo assistente AI. Come il design dell'interfaccia originale dell'iPhone, ci concentreremo su come rendere la tecnologia complessa intuitiva e naturale da usare.
|
|
|
|
|
|
### Comprendere l'architettura moderna del frontend
|
|
|
|
|
|
La nostra interfaccia chat sarà ciò che chiamiamo un'applicazione "Single Page Application" o SPA. Invece dell'approccio tradizionale in cui ogni clic carica una nuova pagina, la nostra app si aggiorna in modo fluido e istantaneo:
|
|
|
|
|
|
**Vecchi siti web**: Come leggere un libro fisico – sfogli completamente nuove pagine
|
|
|
**La nostra app chat**: Come usare il telefono – tutto scorre e si aggiorna senza interruzioni
|
|
|
|
|
|
```mermaid
|
|
|
graph TD
|
|
|
A[User Types Message] --> B[JavaScript Captures Input]
|
|
|
B --> C[Validate & Format Data]
|
|
|
C --> D[Send to Backend API]
|
|
|
D --> E[Display Loading State]
|
|
|
E --> F[Receive AI Response]
|
|
|
F --> G[Update Chat Interface]
|
|
|
G --> H[Ready for Next Message]
|
|
|
```
|
|
|
|
|
|
```mermaid
|
|
|
classDiagram
|
|
|
class ChatApp {
|
|
|
+messages: HTMLElement
|
|
|
+form: HTMLElement
|
|
|
+input: HTMLElement
|
|
|
+sendButton: HTMLElement
|
|
|
+BASE_URL: string
|
|
|
+API_ENDPOINT: string
|
|
|
|
|
|
+constructor()
|
|
|
+initializeEventListeners()
|
|
|
+handleSubmit(event)
|
|
|
+callAPI(message)
|
|
|
+appendMessage(text, role)
|
|
|
+escapeHtml(text)
|
|
|
+scrollToBottom()
|
|
|
+setLoading(isLoading)
|
|
|
}
|
|
|
|
|
|
ChatApp --> DOM : manipulates
|
|
|
ChatApp --> FastAPI : sends requests
|
|
|
```
|
|
|
|
|
|
### I tre pilastri dello sviluppo frontend
|
|
|
|
|
|
Ogni applicazione frontend – dai siti web semplici alle app complesse come Discord o Slack – si basa su tre tecnologie fondamentali. Pensale come la base di tutto ciò che vedi e con cui interagisci sul web:
|
|
|
|
|
|
**HTML (Struttura)**: Questa è la tua base
|
|
|
- Decide quali elementi esistono (pulsanti, aree di testo, contenitori)
|
|
|
- Dà significato al contenuto (questo è un'intestazione, questo è un modulo, ecc.)
|
|
|
- Crea la struttura di base su cui tutto il resto si costruisce
|
|
|
|
|
|
**CSS (Presentazione)**: Questo è il tuo designer d'interni
|
|
|
- Rende tutto bello (colori, font, layout)
|
|
|
- Gestisce diverse dimensioni dello schermo (telefono vs laptop vs tablet)
|
|
|
- Crea animazioni fluide e feedback visivi
|
|
|
|
|
|
**JavaScript (Comportamento)**: Questo è il tuo cervello
|
|
|
- Risponde a ciò che gli utenti fanno (clic, digitazione, scorrimento)
|
|
|
- Comunica con il backend e aggiorna la pagina
|
|
|
- Rende tutto interattivo e dinamico
|
|
|
|
|
|
**Pensalo come il design architettonico:**
|
|
|
- **HTML**: Il progetto strutturale (definizione di spazi e relazioni)
|
|
|
- **CSS**: Il design estetico e ambientale (stile visivo e esperienza utente)
|
|
|
- **JavaScript**: I sistemi meccanici (funzionalità e interattività)
|
|
|
|
|
|
### Perché l'architettura moderna di JavaScript è importante
|
|
|
|
|
|
La nostra applicazione chat utilizzerà modelli di JavaScript moderni che vedrai nelle applicazioni professionali. Comprendere questi concetti ti aiuterà a crescere come sviluppatore:
|
|
|
|
|
|
**Architettura basata su classi**: Organizzeremo il nostro codice in classi, che è come creare progetti per oggetti
|
|
|
**Async/Await**: Metodo moderno per gestire operazioni che richiedono tempo (come le chiamate API)
|
|
|
**Programmazione basata su eventi**: La nostra app risponde alle azioni degli utenti (clic, pressione di tasti) invece di funzionare in un ciclo
|
|
|
**Manipolazione DOM**: Aggiornamento dinamico del contenuto della pagina web in base alle interazioni degli utenti e alle risposte API
|
|
|
|
|
|
### Configurazione della struttura del progetto
|
|
|
|
|
|
Crea una directory frontend con questa struttura organizzata:
|
|
|
|
|
|
```text
|
|
|
frontend/
|
|
|
├── index.html # Main HTML structure
|
|
|
├── app.js # JavaScript functionality
|
|
|
└── styles.css # Visual styling
|
|
|
```
|
|
|
|
|
|
**Comprendere l'architettura:**
|
|
|
- **Separa** le preoccupazioni tra struttura (HTML), comportamento (JavaScript) e presentazione (CSS)
|
|
|
- **Mantiene** una struttura di file semplice, facile da navigare e modificare
|
|
|
- **Segue** le migliori pratiche di sviluppo web per organizzazione e manutenibilità
|
|
|
|
|
|
### Costruire la base HTML: Struttura semantica per l'accessibilità
|
|
|
|
|
|
Iniziamo con la struttura HTML. Lo sviluppo web moderno enfatizza l'uso di "HTML semantico" – utilizzare elementi HTML che descrivono chiaramente il loro scopo, non solo il loro aspetto. Questo rende la tua applicazione accessibile ai lettori di schermo, ai motori di ricerca e ad altri strumenti.
|
|
|
|
|
|
**Perché l'HTML semantico è importante**: Immagina di descrivere la tua app chat a qualcuno al telefono. Diresti "c'è un'intestazione con il titolo, un'area principale dove appaiono le conversazioni e un modulo in basso per digitare i messaggi." L'HTML semantico utilizza elementi che corrispondono a questa descrizione naturale.
|
|
|
|
|
|
Crea `index.html` con questo markup strutturato con cura:
|
|
|
|
|
|
```html
|
|
|
<!DOCTYPE html>
|
|
|
<html lang="en">
|
|
|
<head>
|
|
|
<meta charset="UTF-8">
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
<title>AI Chat Assistant</title>
|
|
|
<link rel="stylesheet" href="styles.css">
|
|
|
</head>
|
|
|
<body>
|
|
|
<div class="chat-container">
|
|
|
<header class="chat-header">
|
|
|
<h1>AI Chat Assistant</h1>
|
|
|
<p>Ask me anything!</p>
|
|
|
</header>
|
|
|
|
|
|
<main class="chat-messages" id="messages" role="log" aria-live="polite">
|
|
|
<!-- Messages will be dynamically added here -->
|
|
|
</main>
|
|
|
|
|
|
<form class="chat-form" id="chatForm">
|
|
|
<div class="input-group">
|
|
|
<input
|
|
|
type="text"
|
|
|
id="messageInput"
|
|
|
placeholder="Type your message here..."
|
|
|
required
|
|
|
aria-label="Chat message input"
|
|
|
>
|
|
|
<button type="submit" id="sendBtn" aria-label="Send message">
|
|
|
Send
|
|
|
</button>
|
|
|
</div>
|
|
|
</form>
|
|
|
</div>
|
|
|
<script src="app.js"></script>
|
|
|
</body>
|
|
|
</html>
|
|
|
```
|
|
|
|
|
|
**Comprendere ogni elemento HTML e il suo scopo:**
|
|
|
|
|
|
#### Struttura del documento
|
|
|
- **`<!DOCTYPE html>`**: Indica al browser che si tratta di HTML5 moderno
|
|
|
- **`<html lang="en">`**: Specifica la lingua della pagina per i lettori di schermo e gli strumenti di traduzione
|
|
|
- **`<meta charset="UTF-8">`**: Garantisce la corretta codifica dei caratteri per il testo internazionale
|
|
|
- **`<meta name="viewport"...>`**: Rende la pagina reattiva per dispositivi mobili controllando lo zoom e la scala
|
|
|
|
|
|
#### Elementi semantici
|
|
|
- **`<header>`**: Identifica chiaramente la sezione superiore con titolo e descrizione
|
|
|
- **`<main>`**: Designa l'area di contenuto principale (dove avvengono le conversazioni)
|
|
|
- **`<form>`**: Semantico per l'input dell'utente, consente una corretta navigazione tramite tastiera
|
|
|
|
|
|
#### Funzionalità di accessibilità
|
|
|
- **`role="log"`**: Indica ai lettori di schermo che questa area contiene un registro cronologico dei messaggi
|
|
|
- **`aria-live="polite"`**: Annuncia nuovi messaggi ai lettori di schermo senza interrompere
|
|
|
- **`aria-label`**: Fornisce etichette descrittive per i controlli del modulo
|
|
|
- **`required`**: Il browser convalida che gli utenti inseriscano un messaggio prima di inviarlo
|
|
|
|
|
|
#### Integrazione di CSS e JavaScript
|
|
|
- **Attributi `class`**: Forniscono punti di aggancio per lo stile CSS (es. `chat-container`, `input-group`)
|
|
|
- **Attributi `id`**: Consentono a JavaScript di trovare e manipolare elementi specifici
|
|
|
- **Posizionamento script**: Il file JavaScript viene caricato alla fine in modo che l'HTML si carichi prima
|
|
|
|
|
|
**Perché questa struttura funziona:**
|
|
|
- **Flusso logico**: Intestazione → Contenuto principale → Modulo di input corrisponde all'ordine naturale di lettura
|
|
|
- **Accessibile tramite tastiera**: Gli utenti possono navigare tra tutti gli elementi interattivi
|
|
|
- **Amichevole per i lettori di schermo**: Punti di riferimento chiari e descrizioni per utenti ipovedenti
|
|
|
- **Reattivo per dispositivi mobili**: Il meta tag viewport consente un design reattivo
|
|
|
- **Miglioramento progressivo**: Funziona anche se CSS o JavaScript non si caricano
|
|
|
|
|
|
### Aggiungere JavaScript interattivo: Logica moderna per applicazioni web
|
|
|
Ora costruiamo il JavaScript che darà vita alla nostra interfaccia di chat. Utilizzeremo modelli di programmazione JavaScript moderni che incontrerai nello sviluppo web professionale, inclusi classi ES6, async/await e programmazione basata su eventi.
|
|
|
|
|
|
#### Comprendere l'Architettura Moderna di JavaScript
|
|
|
|
|
|
Invece di scrivere codice procedurale (una serie di funzioni che vengono eseguite in ordine), creeremo un'**architettura basata su classi**. Pensa a una classe come a un progetto per creare oggetti – proprio come un progetto di un architetto può essere utilizzato per costruire più case.
|
|
|
|
|
|
**Perché utilizzare le classi per le applicazioni web?**
|
|
|
- **Organizzazione**: Tutte le funzionalità correlate sono raggruppate insieme
|
|
|
- **Riutilizzabilità**: Puoi creare più istanze di chat sulla stessa pagina
|
|
|
- **Manutenibilità**: Più facile da debug e modificare funzionalità specifiche
|
|
|
- **Standard professionale**: Questo modello è utilizzato in framework come React, Vue e Angular
|
|
|
|
|
|
Crea `app.js` con questo JavaScript moderno e ben strutturato:
|
|
|
|
|
|
```javascript
|
|
|
// app.js - Modern chat application logic
|
|
|
|
|
|
class ChatApp {
|
|
|
constructor() {
|
|
|
// Get references to DOM elements we'll need to manipulate
|
|
|
this.messages = document.getElementById("messages");
|
|
|
this.form = document.getElementById("chatForm");
|
|
|
this.input = document.getElementById("messageInput");
|
|
|
this.sendButton = document.getElementById("sendBtn");
|
|
|
|
|
|
// Configure your backend URL here
|
|
|
this.BASE_URL = "http://localhost:5000"; // Update this for your environment
|
|
|
this.API_ENDPOINT = `${this.BASE_URL}/hello`;
|
|
|
|
|
|
// Set up event listeners when the chat app is created
|
|
|
this.initializeEventListeners();
|
|
|
}
|
|
|
|
|
|
initializeEventListeners() {
|
|
|
// Listen for form submission (when user clicks Send or presses Enter)
|
|
|
this.form.addEventListener("submit", (e) => this.handleSubmit(e));
|
|
|
|
|
|
// Also listen for Enter key in the input field (better UX)
|
|
|
this.input.addEventListener("keypress", (e) => {
|
|
|
if (e.key === "Enter" && !e.shiftKey) {
|
|
|
e.preventDefault();
|
|
|
this.handleSubmit(e);
|
|
|
}
|
|
|
});
|
|
|
}
|
|
|
|
|
|
async handleSubmit(event) {
|
|
|
event.preventDefault(); // Prevent form from refreshing the page
|
|
|
|
|
|
const messageText = this.input.value.trim();
|
|
|
if (!messageText) return; // Don't send empty messages
|
|
|
|
|
|
// Provide user feedback that something is happening
|
|
|
this.setLoading(true);
|
|
|
|
|
|
// Add user message to chat immediately (optimistic UI)
|
|
|
this.appendMessage(messageText, "user");
|
|
|
|
|
|
// Clear input field so user can type next message
|
|
|
this.input.value = '';
|
|
|
|
|
|
try {
|
|
|
// Call the AI API and wait for response
|
|
|
const reply = await this.callAPI(messageText);
|
|
|
|
|
|
// Add AI response to chat
|
|
|
this.appendMessage(reply, "assistant");
|
|
|
} catch (error) {
|
|
|
console.error('API Error:', error);
|
|
|
this.appendMessage("Sorry, I'm having trouble connecting right now. Please try again.", "error");
|
|
|
} finally {
|
|
|
// Re-enable the interface regardless of success or failure
|
|
|
this.setLoading(false);
|
|
|
}
|
|
|
}
|
|
|
|
|
|
async callAPI(message) {
|
|
|
const response = await fetch(this.API_ENDPOINT, {
|
|
|
method: "POST",
|
|
|
headers: {
|
|
|
"Content-Type": "application/json"
|
|
|
},
|
|
|
body: JSON.stringify({ message })
|
|
|
});
|
|
|
|
|
|
if (!response.ok) {
|
|
|
throw new Error(`HTTP error! status: ${response.status}`);
|
|
|
}
|
|
|
|
|
|
const data = await response.json();
|
|
|
return data.response;
|
|
|
}
|
|
|
|
|
|
appendMessage(text, role) {
|
|
|
const messageElement = document.createElement("div");
|
|
|
messageElement.className = `message ${role}`;
|
|
|
messageElement.innerHTML = `
|
|
|
<div class="message-content">
|
|
|
<span class="message-text">${this.escapeHtml(text)}</span>
|
|
|
<span class="message-time">${new Date().toLocaleTimeString()}</span>
|
|
|
</div>
|
|
|
`;
|
|
|
|
|
|
this.messages.appendChild(messageElement);
|
|
|
this.scrollToBottom();
|
|
|
}
|
|
|
|
|
|
escapeHtml(text) {
|
|
|
const div = document.createElement('div');
|
|
|
div.textContent = text;
|
|
|
return div.innerHTML;
|
|
|
}
|
|
|
|
|
|
scrollToBottom() {
|
|
|
this.messages.scrollTop = this.messages.scrollHeight;
|
|
|
}
|
|
|
|
|
|
setLoading(isLoading) {
|
|
|
this.sendButton.disabled = isLoading;
|
|
|
this.input.disabled = isLoading;
|
|
|
this.sendButton.textContent = isLoading ? "Sending..." : "Send";
|
|
|
}
|
|
|
}
|
|
|
|
|
|
// Initialize the chat application when the page loads
|
|
|
document.addEventListener("DOMContentLoaded", () => {
|
|
|
new ChatApp();
|
|
|
});
|
|
|
```
|
|
|
|
|
|
#### Comprendere Ogni Concetto di JavaScript
|
|
|
|
|
|
**Struttura delle Classi ES6**:
|
|
|
```javascript
|
|
|
class ChatApp {
|
|
|
constructor() {
|
|
|
// This runs when you create a new ChatApp instance
|
|
|
// It's like the "setup" function for your chat
|
|
|
}
|
|
|
|
|
|
methodName() {
|
|
|
// Methods are functions that belong to the class
|
|
|
// They can access class properties using "this"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**Pattern Async/Await**:
|
|
|
```javascript
|
|
|
// Old way (callback hell):
|
|
|
fetch(url)
|
|
|
.then(response => response.json())
|
|
|
.then(data => console.log(data))
|
|
|
.catch(error => console.error(error));
|
|
|
|
|
|
// Modern way (async/await):
|
|
|
try {
|
|
|
const response = await fetch(url);
|
|
|
const data = await response.json();
|
|
|
console.log(data);
|
|
|
} catch (error) {
|
|
|
console.error(error);
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**Programmazione Basata su Eventi**:
|
|
|
Invece di controllare costantemente se qualcosa è accaduto, "ascoltiamo" gli eventi:
|
|
|
```javascript
|
|
|
// When form is submitted, run handleSubmit
|
|
|
this.form.addEventListener("submit", (e) => this.handleSubmit(e));
|
|
|
|
|
|
// When Enter key is pressed, also run handleSubmit
|
|
|
this.input.addEventListener("keypress", (e) => { /* ... */ });
|
|
|
```
|
|
|
|
|
|
**Manipolazione del DOM**:
|
|
|
```javascript
|
|
|
// Create new elements
|
|
|
const messageElement = document.createElement("div");
|
|
|
|
|
|
// Modify their properties
|
|
|
messageElement.className = "message user";
|
|
|
messageElement.innerHTML = "Hello world!";
|
|
|
|
|
|
// Add to the page
|
|
|
this.messages.appendChild(messageElement);
|
|
|
```
|
|
|
|
|
|
#### Sicurezza e Buone Pratiche
|
|
|
|
|
|
**Prevenzione XSS**:
|
|
|
```javascript
|
|
|
escapeHtml(text) {
|
|
|
const div = document.createElement('div');
|
|
|
div.textContent = text; // This automatically escapes HTML
|
|
|
return div.innerHTML;
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**Perché è importante**: Se un utente digita `<script>alert('hack')</script>`, questa funzione garantisce che venga visualizzato come testo anziché eseguito come codice.
|
|
|
|
|
|
**Gestione degli Errori**:
|
|
|
```javascript
|
|
|
try {
|
|
|
const reply = await this.callAPI(messageText);
|
|
|
this.appendMessage(reply, "assistant");
|
|
|
} catch (error) {
|
|
|
// Show user-friendly error instead of breaking the app
|
|
|
this.appendMessage("Sorry, I'm having trouble...", "error");
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**Considerazioni sull'Esperienza Utente**:
|
|
|
- **UI ottimistica**: Aggiungi il messaggio dell'utente immediatamente, senza aspettare la risposta del server
|
|
|
- **Stati di caricamento**: Disabilita i pulsanti e mostra "Invio in corso..." mentre si attende
|
|
|
- **Scorrimento automatico**: Mantieni visibili i messaggi più recenti
|
|
|
- **Validazione dell'input**: Non inviare messaggi vuoti
|
|
|
- **Scorciatoie da tastiera**: Il tasto Invio invia i messaggi (come nelle vere app di chat)
|
|
|
|
|
|
#### Comprendere il Flusso dell'Applicazione
|
|
|
|
|
|
1. **Caricamento della pagina** → L'evento `DOMContentLoaded` viene attivato → Viene creato `new ChatApp()`
|
|
|
2. **Il costruttore viene eseguito** → Ottiene i riferimenti agli elementi DOM → Configura i listener degli eventi
|
|
|
3. **L'utente digita un messaggio** → Premere Invio o clicca su Invia → Viene eseguito `handleSubmit`
|
|
|
4. **handleSubmit** → Valida l'input → Mostra lo stato di caricamento → Chiama l'API
|
|
|
5. **Risposta dell'API** → Aggiunge il messaggio dell'AI alla chat → Riabilita l'interfaccia
|
|
|
6. **Pronto per il prossimo messaggio** → L'utente può continuare a chattare
|
|
|
|
|
|
Questa architettura è scalabile – potresti facilmente aggiungere funzionalità come modifica dei messaggi, caricamento di file o più thread di conversazione senza riscrivere la struttura principale.
|
|
|
|
|
|
### 🎯 Verifica Pedagogica: Architettura Moderna Frontend
|
|
|
|
|
|
**Comprensione dell'Architettura**: Hai implementato un'applicazione single-page completa utilizzando modelli JavaScript moderni. Questo rappresenta uno sviluppo frontend a livello professionale.
|
|
|
|
|
|
**Concetti Chiave Acquisiti**:
|
|
|
- **Architettura delle Classi ES6**: Struttura del codice organizzata e manutenibile
|
|
|
- **Pattern Async/Await**: Programmazione asincrona moderna
|
|
|
- **Programmazione Basata su Eventi**: Design dell'interfaccia utente reattivo
|
|
|
- **Buone Pratiche di Sicurezza**: Prevenzione XSS e validazione dell'input
|
|
|
|
|
|
**Connessione con l'Industria**: I modelli che hai imparato (architettura basata su classi, operazioni asincrone, manipolazione del DOM) sono alla base dei framework moderni come React, Vue e Angular. Stai costruendo con lo stesso approccio architettonico utilizzato nelle applicazioni di produzione.
|
|
|
|
|
|
**Domanda di Riflessione**: Come estenderesti questa applicazione di chat per gestire più conversazioni o l'autenticazione degli utenti? Considera i cambiamenti architettonici necessari e come evolverebbe la struttura delle classi.
|
|
|
|
|
|
### Stilizzare la Tua Interfaccia di Chat
|
|
|
|
|
|
Ora creiamo un'interfaccia di chat moderna e visivamente accattivante con CSS. Una buona stilizzazione rende la tua applicazione professionale e migliora l'esperienza utente complessiva. Utilizzeremo funzionalità CSS moderne come Flexbox, CSS Grid e proprietà personalizzate per un design reattivo e accessibile.
|
|
|
|
|
|
Crea `styles.css` con questi stili completi:
|
|
|
|
|
|
```css
|
|
|
/* styles.css - Modern chat interface styling */
|
|
|
|
|
|
:root {
|
|
|
--primary-color: #2563eb;
|
|
|
--secondary-color: #f1f5f9;
|
|
|
--user-color: #3b82f6;
|
|
|
--assistant-color: #6b7280;
|
|
|
--error-color: #ef4444;
|
|
|
--text-primary: #1e293b;
|
|
|
--text-secondary: #64748b;
|
|
|
--border-radius: 12px;
|
|
|
--shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
|
|
|
}
|
|
|
|
|
|
* {
|
|
|
margin: 0;
|
|
|
padding: 0;
|
|
|
box-sizing: border-box;
|
|
|
}
|
|
|
|
|
|
body {
|
|
|
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
|
|
|
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
|
|
|
min-height: 100vh;
|
|
|
display: flex;
|
|
|
align-items: center;
|
|
|
justify-content: center;
|
|
|
padding: 20px;
|
|
|
}
|
|
|
|
|
|
.chat-container {
|
|
|
width: 100%;
|
|
|
max-width: 800px;
|
|
|
height: 600px;
|
|
|
background: white;
|
|
|
border-radius: var(--border-radius);
|
|
|
box-shadow: var(--shadow);
|
|
|
display: flex;
|
|
|
flex-direction: column;
|
|
|
overflow: hidden;
|
|
|
}
|
|
|
|
|
|
.chat-header {
|
|
|
background: var(--primary-color);
|
|
|
color: white;
|
|
|
padding: 20px;
|
|
|
text-align: center;
|
|
|
}
|
|
|
|
|
|
.chat-header h1 {
|
|
|
font-size: 1.5rem;
|
|
|
margin-bottom: 5px;
|
|
|
}
|
|
|
|
|
|
.chat-header p {
|
|
|
opacity: 0.9;
|
|
|
font-size: 0.9rem;
|
|
|
}
|
|
|
|
|
|
.chat-messages {
|
|
|
flex: 1;
|
|
|
padding: 20px;
|
|
|
overflow-y: auto;
|
|
|
display: flex;
|
|
|
flex-direction: column;
|
|
|
gap: 15px;
|
|
|
background: var(--secondary-color);
|
|
|
}
|
|
|
|
|
|
.message {
|
|
|
display: flex;
|
|
|
max-width: 80%;
|
|
|
animation: slideIn 0.3s ease-out;
|
|
|
}
|
|
|
|
|
|
.message.user {
|
|
|
align-self: flex-end;
|
|
|
}
|
|
|
|
|
|
.message.user .message-content {
|
|
|
background: var(--user-color);
|
|
|
color: white;
|
|
|
border-radius: var(--border-radius) var(--border-radius) 4px var(--border-radius);
|
|
|
}
|
|
|
|
|
|
.message.assistant {
|
|
|
align-self: flex-start;
|
|
|
}
|
|
|
|
|
|
.message.assistant .message-content {
|
|
|
background: white;
|
|
|
color: var(--text-primary);
|
|
|
border-radius: var(--border-radius) var(--border-radius) var(--border-radius) 4px;
|
|
|
border: 1px solid #e2e8f0;
|
|
|
}
|
|
|
|
|
|
.message.error .message-content {
|
|
|
background: var(--error-color);
|
|
|
color: white;
|
|
|
border-radius: var(--border-radius);
|
|
|
}
|
|
|
|
|
|
.message-content {
|
|
|
padding: 12px 16px;
|
|
|
box-shadow: var(--shadow);
|
|
|
position: relative;
|
|
|
}
|
|
|
|
|
|
.message-text {
|
|
|
display: block;
|
|
|
line-height: 1.5;
|
|
|
word-wrap: break-word;
|
|
|
}
|
|
|
|
|
|
.message-time {
|
|
|
display: block;
|
|
|
font-size: 0.75rem;
|
|
|
opacity: 0.7;
|
|
|
margin-top: 5px;
|
|
|
}
|
|
|
|
|
|
.chat-form {
|
|
|
padding: 20px;
|
|
|
border-top: 1px solid #e2e8f0;
|
|
|
background: white;
|
|
|
}
|
|
|
|
|
|
.input-group {
|
|
|
display: flex;
|
|
|
gap: 10px;
|
|
|
align-items: center;
|
|
|
}
|
|
|
|
|
|
#messageInput {
|
|
|
flex: 1;
|
|
|
padding: 12px 16px;
|
|
|
border: 2px solid #e2e8f0;
|
|
|
border-radius: var(--border-radius);
|
|
|
font-size: 1rem;
|
|
|
outline: none;
|
|
|
transition: border-color 0.2s ease;
|
|
|
}
|
|
|
|
|
|
#messageInput:focus {
|
|
|
border-color: var(--primary-color);
|
|
|
}
|
|
|
|
|
|
#messageInput:disabled {
|
|
|
background: #f8fafc;
|
|
|
opacity: 0.6;
|
|
|
cursor: not-allowed;
|
|
|
}
|
|
|
|
|
|
#sendBtn {
|
|
|
padding: 12px 24px;
|
|
|
background: var(--primary-color);
|
|
|
color: white;
|
|
|
border: none;
|
|
|
border-radius: var(--border-radius);
|
|
|
font-size: 1rem;
|
|
|
font-weight: 600;
|
|
|
cursor: pointer;
|
|
|
transition: background-color 0.2s ease;
|
|
|
min-width: 80px;
|
|
|
}
|
|
|
|
|
|
#sendBtn:hover:not(:disabled) {
|
|
|
background: #1d4ed8;
|
|
|
}
|
|
|
|
|
|
#sendBtn:disabled {
|
|
|
background: #94a3b8;
|
|
|
cursor: not-allowed;
|
|
|
}
|
|
|
|
|
|
@keyframes slideIn {
|
|
|
from {
|
|
|
opacity: 0;
|
|
|
transform: translateY(10px);
|
|
|
}
|
|
|
to {
|
|
|
opacity: 1;
|
|
|
transform: translateY(0);
|
|
|
}
|
|
|
}
|
|
|
|
|
|
/* Responsive design for mobile devices */
|
|
|
@media (max-width: 768px) {
|
|
|
body {
|
|
|
padding: 10px;
|
|
|
}
|
|
|
|
|
|
.chat-container {
|
|
|
height: calc(100vh - 20px);
|
|
|
border-radius: 8px;
|
|
|
}
|
|
|
|
|
|
.message {
|
|
|
max-width: 90%;
|
|
|
}
|
|
|
|
|
|
.input-group {
|
|
|
flex-direction: column;
|
|
|
gap: 10px;
|
|
|
}
|
|
|
|
|
|
#messageInput {
|
|
|
width: 100%;
|
|
|
}
|
|
|
|
|
|
#sendBtn {
|
|
|
width: 100%;
|
|
|
}
|
|
|
}
|
|
|
|
|
|
/* Accessibility improvements */
|
|
|
@media (prefers-reduced-motion: reduce) {
|
|
|
.message {
|
|
|
animation: none;
|
|
|
}
|
|
|
|
|
|
* {
|
|
|
transition: none !important;
|
|
|
}
|
|
|
}
|
|
|
|
|
|
/* Dark mode support */
|
|
|
@media (prefers-color-scheme: dark) {
|
|
|
.chat-container {
|
|
|
background: #1e293b;
|
|
|
color: #f1f5f9;
|
|
|
}
|
|
|
|
|
|
.chat-messages {
|
|
|
background: #0f172a;
|
|
|
}
|
|
|
|
|
|
.message.assistant .message-content {
|
|
|
background: #334155;
|
|
|
color: #f1f5f9;
|
|
|
border-color: #475569;
|
|
|
}
|
|
|
|
|
|
.chat-form {
|
|
|
background: #1e293b;
|
|
|
border-color: #475569;
|
|
|
}
|
|
|
|
|
|
#messageInput {
|
|
|
background: #334155;
|
|
|
color: #f1f5f9;
|
|
|
border-color: #475569;
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**Comprendere l'architettura CSS:**
|
|
|
- **Utilizza** proprietà personalizzate CSS (variabili) per un tema coerente e una facile manutenzione
|
|
|
- **Implementa** layout Flexbox per un design reattivo e un allineamento corretto
|
|
|
- **Include** animazioni fluide per l'apparizione dei messaggi senza essere distraenti
|
|
|
- **Fornisce** una distinzione visiva tra i messaggi dell'utente, le risposte dell'AI e gli stati di errore
|
|
|
- **Supporta** un design reattivo che funziona sia su desktop che su dispositivi mobili
|
|
|
- **Considera** l'accessibilità con preferenze di movimento ridotto e rapporti di contrasto adeguati
|
|
|
- **Offre** supporto per la modalità scura basata sulle preferenze del sistema dell'utente
|
|
|
|
|
|
### Configurare l'URL del Backend
|
|
|
|
|
|
L'ultimo passaggio è aggiornare il `BASE_URL` nel tuo JavaScript per corrispondere al server backend:
|
|
|
|
|
|
```javascript
|
|
|
// For local development
|
|
|
this.BASE_URL = "http://localhost:5000";
|
|
|
|
|
|
// For GitHub Codespaces (replace with your actual URL)
|
|
|
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
|
|
|
```
|
|
|
|
|
|
**Determinare l'URL del backend:**
|
|
|
- **Sviluppo locale**: Usa `http://localhost:5000` se stai eseguendo sia il frontend che il backend localmente
|
|
|
- **Codespaces**: Trova l'URL del backend nella scheda Ports dopo aver reso pubblico il port 5000
|
|
|
- **Produzione**: Sostituisci con il tuo dominio effettivo quando distribuisci su un servizio di hosting
|
|
|
|
|
|
> 💡 **Suggerimento per il test**: Puoi testare direttamente il tuo backend visitando l'URL root nel browser. Dovresti vedere il messaggio di benvenuto dal server FastAPI.
|
|
|
|
|
|
|
|
|
|
|
|
## Test e Distribuzione
|
|
|
|
|
|
Ora che hai costruito sia i componenti frontend che backend, testiamo che tutto funzioni insieme ed esploriamo le opzioni di distribuzione per condividere il tuo assistente di chat con gli altri.
|
|
|
|
|
|
### Flusso di Test Locale
|
|
|
|
|
|
Segui questi passaggi per testare la tua applicazione completa:
|
|
|
|
|
|
```mermaid
|
|
|
graph TD
|
|
|
A[Start Backend Server] --> B[Configure Environment Variables]
|
|
|
B --> C[Test API Endpoints]
|
|
|
C --> D[Open Frontend in Browser]
|
|
|
D --> E[Test Chat Functionality]
|
|
|
E --> F[Debug Any Issues]
|
|
|
```
|
|
|
|
|
|
**Processo di test passo-passo:**
|
|
|
|
|
|
1. **Avvia il server backend**:
|
|
|
```bash
|
|
|
cd backend
|
|
|
source venv/bin/activate # or venv\Scripts\activate on Windows
|
|
|
python api.py
|
|
|
```
|
|
|
|
|
|
2. **Verifica che l'API funzioni**:
|
|
|
- Apri `http://localhost:5000` nel browser
|
|
|
- Dovresti vedere il messaggio di benvenuto dal server FastAPI
|
|
|
|
|
|
3. **Apri il frontend**:
|
|
|
- Vai alla directory del frontend
|
|
|
- Apri `index.html` nel browser web
|
|
|
- Oppure usa l'estensione Live Server di VS Code per una migliore esperienza di sviluppo
|
|
|
|
|
|
4. **Testa la funzionalità di chat**:
|
|
|
- Digita un messaggio nel campo di input
|
|
|
- Clicca su "Invia" o premi Invio
|
|
|
- Verifica che l'AI risponda correttamente
|
|
|
- Controlla la console del browser per eventuali errori JavaScript
|
|
|
|
|
|
### Risoluzione dei Problemi Comuni
|
|
|
|
|
|
| Problema | Sintomi | Soluzione |
|
|
|
|---------|----------|----------|
|
|
|
| **Errore CORS** | Il frontend non riesce a raggiungere il backend | Assicurati che CORSMiddleware di FastAPI sia configurato correttamente |
|
|
|
| **Errore API Key** | Risposte 401 Unauthorized | Controlla la variabile d'ambiente `GITHUB_TOKEN` |
|
|
|
| **Connessione Rifiutata** | Errori di rete nel frontend | Verifica l'URL del backend e che il server Flask sia in esecuzione |
|
|
|
| **Nessuna Risposta AI** | Risposte vuote o errori | Controlla i log del backend per problemi di quota API o autenticazione |
|
|
|
|
|
|
**Passaggi comuni per il debug**:
|
|
|
- **Controlla** la Console degli Strumenti per Sviluppatori del browser per errori JavaScript
|
|
|
- **Verifica** che la scheda Network mostri richieste e risposte API riuscite
|
|
|
- **Rivedi** l'output del terminale del backend per errori Python o problemi API
|
|
|
- **Conferma** che le variabili d'ambiente siano caricate e accessibili correttamente
|
|
|
|
|
|
## 📈 Cronologia di Padronanza dello Sviluppo di Applicazioni AI
|
|
|
|
|
|
```mermaid
|
|
|
timeline
|
|
|
title Complete AI Application Development Journey
|
|
|
|
|
|
section AI Foundations
|
|
|
Understanding Generative AI
|
|
|
: Grasp pattern recognition concepts
|
|
|
: Master AI parameter control
|
|
|
: Learn prompt engineering techniques
|
|
|
|
|
|
GitHub Models Integration
|
|
|
: Navigate AI service platforms
|
|
|
: Handle authentication securely
|
|
|
: Optimize model parameters
|
|
|
|
|
|
section Backend Development
|
|
|
Python API Architecture
|
|
|
: Build FastAPI applications
|
|
|
: Implement async operations
|
|
|
: Create secure endpoints
|
|
|
|
|
|
AI Service Integration
|
|
|
: Connect to external AI APIs
|
|
|
: Handle rate limiting
|
|
|
: Implement error boundaries
|
|
|
|
|
|
section Frontend Mastery
|
|
|
Modern JavaScript Patterns
|
|
|
: Master ES6 class architecture
|
|
|
: Implement async/await flows
|
|
|
: Build responsive interfaces
|
|
|
|
|
|
Real-time User Experience
|
|
|
: Create dynamic chat interfaces
|
|
|
: Handle loading states
|
|
|
: Optimize user interactions
|
|
|
|
|
|
section Production Readiness
|
|
|
Security & Performance
|
|
|
: Implement secure token management
|
|
|
: Prevent XSS vulnerabilities
|
|
|
: Optimize API performance
|
|
|
|
|
|
Professional Deployment
|
|
|
: Build scalable architectures
|
|
|
: Create maintainable code
|
|
|
: Document development processes
|
|
|
```
|
|
|
|
|
|
**🎓 Traguardo di Laurea**: Hai costruito con successo un'applicazione completa alimentata da AI utilizzando le stesse tecnologie e modelli architettonici che alimentano gli assistenti AI moderni. Queste competenze rappresentano l'intersezione tra sviluppo web tradizionale e integrazione AI all'avanguardia.
|
|
|
|
|
|
**🔄 Capacità di Livello Successivo**:
|
|
|
- Pronto per esplorare framework AI avanzati (LangChain, LangGraph)
|
|
|
- Preparato per costruire applicazioni AI multimodali (testo, immagine, voce)
|
|
|
- Equipaggiato per implementare database vettoriali e sistemi di recupero
|
|
|
- Fondazione impostata per il machine learning e la messa a punto dei modelli AI
|
|
|
|
|
|
## Sfida GitHub Copilot Agent 🚀
|
|
|
|
|
|
Usa la modalità Agent per completare la seguente sfida:
|
|
|
|
|
|
**Descrizione:** Migliora l'assistente di chat aggiungendo la cronologia delle conversazioni e la persistenza dei messaggi. Questa sfida ti aiuterà a comprendere come gestire lo stato nelle applicazioni di chat e implementare l'archiviazione dei dati per migliorare l'esperienza utente.
|
|
|
|
|
|
**Prompt:** Modifica l'applicazione di chat per includere la cronologia delle conversazioni che persiste tra le sessioni. Aggiungi la funzionalità per salvare i messaggi di chat nella memoria locale, visualizzare la cronologia delle conversazioni quando la pagina viene caricata e includere un pulsante "Cancella Cronologia". Implementa anche indicatori di digitazione e timestamp dei messaggi per rendere l'esperienza di chat più realistica.
|
|
|
|
|
|
Scopri di più sulla [modalità agent](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode) qui.
|
|
|
|
|
|
## Compito: Costruisci il Tuo Assistente AI Personale
|
|
|
|
|
|
Ora creerai la tua implementazione di un assistente AI. Piuttosto che semplicemente replicare il codice del tutorial, questa è un'opportunità per applicare i concetti mentre costruisci qualcosa che rifletta i tuoi interessi e casi d'uso.
|
|
|
|
|
|
### Requisiti del Progetto
|
|
|
|
|
|
Impostiamo il tuo progetto con una struttura pulita e organizzata:
|
|
|
|
|
|
```text
|
|
|
my-ai-assistant/
|
|
|
├── backend/
|
|
|
│ ├── api.py # Your FastAPI server
|
|
|
│ ├── llm.py # AI integration functions
|
|
|
│ ├── .env # Your secrets (keep this safe!)
|
|
|
│ └── requirements.txt # Python dependencies
|
|
|
├── frontend/
|
|
|
│ ├── index.html # Your chat interface
|
|
|
│ ├── app.js # The JavaScript magic
|
|
|
│ └── styles.css # Make it look amazing
|
|
|
└── README.md # Tell the world about your creation
|
|
|
```
|
|
|
|
|
|
### Compiti Principali di Implementazione
|
|
|
|
|
|
**Sviluppo Backend:**
|
|
|
- **Adotta** il nostro codice FastAPI e rendilo tuo
|
|
|
- **Crea** una personalità AI unica – magari un assistente di cucina utile, un partner creativo per la scrittura o un compagno di studio?
|
|
|
- **Aggiungi** una gestione solida degli errori per evitare che l'app si blocchi in caso di problemi
|
|
|
- **Scrivi** una documentazione chiara per chiunque voglia capire come funziona la tua API
|
|
|
|
|
|
**Sviluppo Frontend:**
|
|
|
- **Costruisci** un'interfaccia di chat intuitiva e accogliente
|
|
|
- **Scrivi** JavaScript moderno e pulito di cui essere orgoglioso di mostrare ad altri sviluppatori
|
|
|
- **Progetta** uno stile personalizzato che rifletta la personalità del tuo AI – divertente e colorato? Pulito e minimale? A te la scelta!
|
|
|
- **Assicurati** che funzioni perfettamente sia su telefoni che su computer
|
|
|
|
|
|
**Requisiti di Personalizzazione:**
|
|
|
- **Scegli** un nome e una personalità unici per il tuo assistente AI – magari qualcosa che rifletta i tuoi interessi o i problemi che vuoi risolvere
|
|
|
- **Personalizza** il design visivo per adattarlo allo stile del tuo assistente
|
|
|
- **Scrivi** un messaggio di benvenuto accattivante che invogli le persone a iniziare a chattare
|
|
|
- **Testa** il tuo assistente con diversi tipi di domande per vedere come risponde
|
|
|
|
|
|
### Idee per Miglioramenti (Opzionali)
|
|
|
|
|
|
Vuoi portare il tuo progetto al livello successivo? Ecco alcune idee divertenti da esplorare:
|
|
|
|
|
|
| Funzionalità | Descrizione | Competenze che praticherai |
|
|
|
|--------------|-------------|---------------------------|
|
|
|
| **Cronologia dei Messaggi** | Ricorda le conversazioni anche dopo il refresh della pagina | Utilizzo di localStorage, gestione JSON |
|
|
|
| **Indicatori di Digitazione** | Mostra "AI sta scrivendo..." mentre si attendono risposte | Animazioni CSS, programmazione asincrona |
|
|
|
| **Timestamp dei Messaggi** | Mostra quando ogni messaggio è stato inviato | Formattazione data/ora, design UX |
|
|
|
| **Esporta Chat** | Permetti agli utenti di scaricare la loro conversazione | Gestione file, esportazione dati |
|
|
|
| **Cambio Tema** | Interruttore modalità chiara/scura | Variabili CSS, preferenze utente |
|
|
|
| **Input Vocale** | Aggiungi funzionalità di riconoscimento vocale | API Web, accessibilità |
|
|
|
|
|
|
### Test e Documentazione
|
|
|
|
|
|
**Assicurazione Qualità:**
|
|
|
- **Testa** la tua applicazione con vari tipi di input e casi limite
|
|
|
- **Verifica** che il design reattivo funzioni su diverse dimensioni dello schermo
|
|
|
- **Controlla** l'accessibilità con navigazione da tastiera e screen reader
|
|
|
- **Valida** HTML e CSS per la conformità agli standard
|
|
|
|
|
|
**Requisiti di Documentazione:**
|
|
|
- **Scrivi** un README.md che spieghi il tuo progetto e come eseguirlo
|
|
|
- **Includi** screenshot della tua interfaccia di chat in azione
|
|
|
- **Documenta** eventuali funzionalità o personalizzazioni uniche che hai aggiunto
|
|
|
- **Fornisci** istruzioni chiare per l'installazione per altri sviluppatori
|
|
|
|
|
|
### Linee Guida per la Consegna
|
|
|
|
|
|
**Materiale da Consegnare:**
|
|
|
1. Cartella completa del progetto con tutto il codice sorgente
|
|
|
2. README.md con descrizione del progetto e istruzioni per l'installazione
|
|
|
3. Screenshot che mostrano il tuo assistente di chat in azione
|
|
|
4. Breve riflessione su ciò che hai imparato e le sfide che hai affrontato
|
|
|
|
|
|
**Criteri di Valutazione:**
|
|
|
- **Funzionalità**: L'assistente di chat funziona come previsto?
|
|
|
- **Qualità del Codice**: Il codice è ben organizzato, commentato e manutenibile?
|
|
|
- **Design**: L'interfaccia è visivamente accattivante e facile da usare?
|
|
|
- **Creatività**: Quanto è unica e personalizzata la tua implementazione?
|
|
|
- **Documentazione**: Le istruzioni per l'installazione sono chiare e complete?
|
|
|
|
|
|
> 💡 **Suggerimento per il Successo**: Inizia prima con i requisiti di base, quindi aggiungi miglioramenti una volta che tutto funziona. Concentrati sulla creazione di un'esperienza centrale ben rifinita prima di aggiungere funzionalità avanzate.
|
|
|
|
|
|
## Soluzione
|
|
|
|
|
|
[Soluzione](./solution/README.md)
|
|
|
|
|
|
## Sfide Bonus
|
|
|
|
|
|
Pronto a portare il tuo assistente AI al livello successivo? Prova queste sfide avanzate che approfondiranno la tua comprensione dell'integrazione AI e dello sviluppo web.
|
|
|
|
|
|
### Personalizzazione della Personalità
|
|
|
|
|
|
La vera magia accade quando dai al tuo assistente AI una personalità unica. Sperimenta con diversi prompt di sistema per creare assistenti specializzati:
|
|
|
|
|
|
**Esempio di Assistente Professionale**:
|
|
|
```python
|
|
|
call_llm(message, "You are a professional business consultant with 20 years of experience. Provide structured, actionable advice with specific steps and considerations.")
|
|
|
```
|
|
|
|
|
|
**Esempio di Aiutante per la Scrittura Creativa**:
|
|
|
```python
|
|
|
call_llm(message, "You are an enthusiastic creative writing coach. Help users develop their storytelling skills with imaginative prompts and constructive feedback.")
|
|
|
```
|
|
|
|
|
|
**Esempio di Mentore Tecnico**:
|
|
|
```python
|
|
|
call_llm(message, "You are a patient senior developer who explains complex programming concepts using simple analogies and practical examples.")
|
|
|
```
|
|
|
|
|
|
### Miglioramenti al Frontend
|
|
|
|
|
|
Trasforma la tua interfaccia di chat con questi miglioramenti visivi e funzionali:
|
|
|
|
|
|
**Funzionalità CSS Avanzate**:
|
|
|
- **Implementa** animazioni fluide per i messaggi e transizioni
|
|
|
- **Aggiungi** design personalizzati per le bolle di chat con forme e gradienti CSS
|
|
|
- **Crea** un'animazione per l'indicatore di digitazione quando l'AI "sta pensando"
|
|
|
- **Progetta** reazioni emoji o sistema di valutazione dei messaggi
|
|
|
|
|
|
**Miglioramenti JavaScript**:
|
|
|
- **Aggiungi** scorciatoie da tastiera (Ctrl+Invio per inviare, Esc per cancellare l'input)
|
|
|
- **Implementa** funzionalità di ricerca e filtraggio dei messaggi
|
|
|
- **Crea** una funzione di esportazione delle conversazioni (scarica come testo o JSON)
|
|
|
- **Aggiungi** salvataggio automatico su localStorage per prevenire la perdita di messaggi
|
|
|
|
|
|
### Integrazione AI Avanzata
|
|
|
|
|
|
**Personalità AI Multiple**:
|
|
|
- **Crea** un menu a tendina per passare tra diverse personalità AI
|
|
|
- **Salva** la personalità preferita dell'utente in localStorage
|
|
|
- **Implementa** il cambio di contesto che mantiene il flusso della conversazione
|
|
|
|
|
|
**Funzionalità di Risposta Intelligente**:
|
|
|
- **Aggiungi** consapevolezza del contesto della conversazione (l'AI
|
|
|
- **Implementa** suggerimenti intelligenti basati sull'argomento della conversazione
|
|
|
- **Crea** pulsanti di risposta rapida per domande comuni
|
|
|
|
|
|
> 🎯 **Obiettivo di apprendimento**: Queste sfide extra ti aiutano a comprendere modelli avanzati di sviluppo web e tecniche di integrazione AI utilizzate nelle applicazioni di produzione.
|
|
|
|
|
|
## Riepilogo e Prossimi Passi
|
|
|
|
|
|
Congratulazioni! Hai costruito con successo un assistente chat alimentato da AI partendo da zero. Questo progetto ti ha fornito un'esperienza pratica con tecnologie moderne di sviluppo web e integrazione AI – competenze sempre più preziose nel panorama tecnologico odierno.
|
|
|
|
|
|
### Cosa Hai Realizzato
|
|
|
|
|
|
Durante questa lezione, hai padroneggiato diverse tecnologie e concetti chiave:
|
|
|
|
|
|
**Sviluppo Backend:**
|
|
|
- **Integrato** con l'API GitHub Models per funzionalità AI
|
|
|
- **Creato** un'API RESTful utilizzando Flask con gestione degli errori appropriata
|
|
|
- **Implementato** autenticazione sicura utilizzando variabili d'ambiente
|
|
|
- **Configurato** CORS per richieste cross-origin tra frontend e backend
|
|
|
|
|
|
**Sviluppo Frontend:**
|
|
|
- **Creato** un'interfaccia chat responsiva utilizzando HTML semantico
|
|
|
- **Implementato** JavaScript moderno con async/await e architettura basata su classi
|
|
|
- **Progettato** un'interfaccia utente coinvolgente con CSS Grid, Flexbox e animazioni
|
|
|
- **Aggiunto** funzionalità di accessibilità e principi di design responsivo
|
|
|
|
|
|
**Integrazione Full-Stack:**
|
|
|
- **Collegato** frontend e backend tramite chiamate API HTTP
|
|
|
- **Gestito** interazioni utente in tempo reale e flusso di dati asincrono
|
|
|
- **Implementato** gestione degli errori e feedback utente in tutta l'applicazione
|
|
|
- **Testato** il flusso completo dell'applicazione, dall'input dell'utente alla risposta AI
|
|
|
|
|
|
### Risultati Chiave di Apprendimento
|
|
|
|
|
|
```mermaid
|
|
|
mindmap
|
|
|
root((AI Chat App Skills))
|
|
|
API Integration
|
|
|
Authentication
|
|
|
Error Handling
|
|
|
Async Programming
|
|
|
Web Development
|
|
|
HTML5 Semantics
|
|
|
Modern CSS
|
|
|
ES6+ JavaScript
|
|
|
User Experience
|
|
|
Responsive Design
|
|
|
Accessibility
|
|
|
Real-time Interaction
|
|
|
AI Understanding
|
|
|
Prompt Engineering
|
|
|
Model Parameters
|
|
|
Conversation Flow
|
|
|
```
|
|
|
|
|
|
Questo progetto ti ha introdotto ai fondamenti della creazione di applicazioni alimentate da AI, che rappresentano il futuro dello sviluppo web. Ora comprendi come integrare le capacità AI nelle applicazioni web tradizionali, creando esperienze utente coinvolgenti che sembrano intelligenti e reattive.
|
|
|
|
|
|
### Applicazioni Professionali
|
|
|
|
|
|
Le competenze che hai sviluppato in questa lezione sono direttamente applicabili alle carriere moderne nello sviluppo software:
|
|
|
|
|
|
- **Sviluppo web full-stack** utilizzando framework e API moderni
|
|
|
- **Integrazione AI** in applicazioni web e app mobili
|
|
|
- **Progettazione e sviluppo di API** per architetture a microservizi
|
|
|
- **Sviluppo di interfacce utente** con focus su accessibilità e design responsivo
|
|
|
- **Pratiche DevOps** inclusa configurazione dell'ambiente e distribuzione
|
|
|
|
|
|
### Continuare il Tuo Percorso di Sviluppo AI
|
|
|
|
|
|
**Prossimi Passi di Apprendimento:**
|
|
|
- **Esplora** modelli AI e API più avanzati (GPT-4, Claude, Gemini)
|
|
|
- **Impara** tecniche di ingegneria dei prompt per risposte AI migliori
|
|
|
- **Studia** il design delle conversazioni e i principi di esperienza utente per chatbot
|
|
|
- **Indaga** sulla sicurezza AI, sull'etica e sulle pratiche di sviluppo AI responsabile
|
|
|
- **Crea** applicazioni più complesse con memoria delle conversazioni e consapevolezza del contesto
|
|
|
|
|
|
**Idee per Progetti Avanzati:**
|
|
|
- Chat room multi-utente con moderazione AI
|
|
|
- Chatbot per il servizio clienti alimentati da AI
|
|
|
- Assistenti di tutoraggio educativo con apprendimento personalizzato
|
|
|
- Collaboratori per la scrittura creativa con personalità AI diverse
|
|
|
- Assistenti per la documentazione tecnica per sviluppatori
|
|
|
|
|
|
## Iniziare con GitHub Codespaces
|
|
|
|
|
|
Vuoi provare questo progetto in un ambiente di sviluppo cloud? GitHub Codespaces offre un setup di sviluppo completo nel tuo browser, perfetto per sperimentare applicazioni AI senza requisiti di configurazione locale.
|
|
|
|
|
|
### Configurare il Tuo Ambiente di Sviluppo
|
|
|
|
|
|
**Passo 1: Crea dal Template**
|
|
|
- **Vai** al [repository Web Dev For Beginners](https://github.com/microsoft/Web-Dev-For-Beginners)
|
|
|
- **Clicca** su "Use this template" nell'angolo in alto a destra (assicurati di essere loggato su GitHub)
|
|
|
|
|
|
|
|
|
|
|
|
**Passo 2: Avvia Codespaces**
|
|
|
- **Apri** il tuo repository appena creato
|
|
|
- **Clicca** sul pulsante verde "Code" e seleziona "Codespaces"
|
|
|
- **Scegli** "Create codespace on main" per avviare il tuo ambiente di sviluppo
|
|
|
|
|
|
|
|
|
|
|
|
**Passo 3: Configurazione dell'Ambiente**
|
|
|
Una volta caricato il tuo Codespace, avrai accesso a:
|
|
|
- **Python, Node.js e tutti gli strumenti di sviluppo necessari preinstallati**
|
|
|
- **Interfaccia VS Code** con estensioni per lo sviluppo web
|
|
|
- **Accesso al terminale** per eseguire server backend e frontend
|
|
|
- **Inoltro delle porte** per testare le tue applicazioni
|
|
|
|
|
|
**Cosa offre Codespaces:**
|
|
|
- **Elimina** problemi di configurazione e setup dell'ambiente locale
|
|
|
- **Fornisce** un ambiente di sviluppo coerente su dispositivi diversi
|
|
|
- **Include** strumenti ed estensioni preconfigurati per lo sviluppo web
|
|
|
- **Offre** integrazione senza problemi con GitHub per il controllo delle versioni e la collaborazione
|
|
|
|
|
|
> 🚀 **Suggerimento Pro**: Codespaces è perfetto per l'apprendimento e la prototipazione di applicazioni AI poiché gestisce automaticamente tutta la configurazione complessa dell'ambiente, permettendoti di concentrarti sulla costruzione e sull'apprendimento invece che sulla risoluzione dei problemi di configurazione.
|
|
|
|
|
|
---
|
|
|
|
|
|
**Disclaimer**:
|
|
|
Questo documento è stato tradotto utilizzando il servizio di traduzione AI [Co-op Translator](https://github.com/Azure/co-op-translator). Sebbene ci impegniamo per garantire l'accuratezza, si prega di notare che le traduzioni automatiche possono contenere errori o imprecisioni. Il documento originale nella sua lingua nativa dovrebbe essere considerato la fonte autorevole. Per informazioni critiche, si consiglia una traduzione professionale umana. Non siamo responsabili per eventuali incomprensioni o interpretazioni errate derivanti dall'uso di questa traduzione. |
