80 KiB

Raw Blame History Unescape Escape

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 e personalizzate alle 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 dell'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 con l'AI sembrerà meno un processo misterioso e più 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.

Ecco come apparirà il tuo progetto finito:

Comprendere l'AI: Dal Mistero alla Padronanza

Prima di immergerci nel codice, cerchiamo di capire con cosa stiamo lavorando. Se hai già utilizzato le API, conosci il modello di base: invia una richiesta, ricevi 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'è davvero l'"AI Generativa"?

Considera come la Stele di Rosetta ha 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 e poi usano 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 – ottieni 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 proprie, adattate a ciò che vuoi sapere

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, diventando infine capaci di interpretare nuovi testi utilizzando quei modelli appresi.

Perché Modelli GitHub?

Stiamo utilizzando i Modelli GitHub per un motivo piuttosto pratico: ci dà accesso a un'AI di livello aziendale senza dover configurare la nostra infrastruttura AI (che, fidati, non vorresti 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 come Servizio", e la parte migliore? È gratuito per iniziare, quindi puoi sperimentare senza preoccuparti di accumulare un conto salato.

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 i Modelli GitHub 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 funge da ambiente di test dove puoi sperimentare con diversi modelli AI e comprendere le loro capacità prima di implementarli nel codice.

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
Modifica impostazioni come livello di creatività e lunghezza della risposta per vedere come influenzano il risultato

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 con Python

Ora implementiamo l'integrazione AI utilizzando Python. Python è eccellente per le applicazioni AI grazie alla sua sintassi semplice e alle sue potenti librerie. Partiremo dal codice del playground dei Modelli GitHub e lo riorganizzeremo in una funzione riutilizzabile e pronta per la produzione.

Comprendere l'Implementazione 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.

"""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"],
)

```python
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 necessari: 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 poco!)
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:

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 di scena 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 AI: Fine-Tuning del 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 esattamente la stessa melodia ogni volta (altamente prevedibile)
Temperatura = 0.7: Aggiunge alcune variazioni di buon gusto rimanendo riconoscibile (creatività bilanciata)
Temperatura = 1.5: Jazz sperimentale completo con svolte inaspettate (altamente imprevedibile)

# 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 se i token fossero 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

# 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 Focalizzazione

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

# 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
}

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 sullo 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
Include una docstring dettagliata che spiega lo scopo e i parametri della funzione
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. Questa è 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 premere un interruttore che attiva tutti quei modelli appresi.

È come il metodo di recitazione 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:

Ruolo/Identità: Chi è l'AI?
Competenza: Cosa sa?
Stile di comunicazione: Come parla?
Istruzioni specifiche: Su cosa dovrebbe concentrarsi?

# ❌ 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:

# 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?"

# 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

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: Dì all'AI come strutturare le risposte

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 dovrebbe fare

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é Questo È Importante per il Tuo Assistente Chat

Comprendere i prompt di sistema ti dà un potere incredibile per creare assistenti AI specializzati:

Bot di assistenza clienti: Utile, paziente, consapevole delle politiche
Tutor di apprendimento: Incoraggiante, passo dopo passo, verifica la comprensione
Partner creativo: Immaginativo, costruisce sulle idee, chiede "e se?"
Esperto tecnico: Preciso, dettagliato, attento alla sicurezza

L'intuizione chiave: Non stai solo chiamando un'API AI – stai creando una personalità AI personalizzata che serve il tuo caso d'uso specifico. Questo è ciò che rende le applicazioni AI moderne utili e personalizzate piuttosto che generiche.

Costruire 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 framework Python moderno che eccelle nella costruzione 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 tuo server FastAPI funge da intermediario che riceve richieste dal frontend, comunica con i servizi AI e restituisce risposte formattate.

Perché FastAPI per le Applicazioni AI?

Potresti chiederti: "Non posso semplicemente chiamare l'AI direttamente dal mio JavaScript frontend?" o "Perché FastAPI invece di Flask o Django?" Ottime domande! Ecco perché FastAPI è perfetto per ciò che stiamo costruendo:

Async di default: Può gestire più richieste AI contemporaneamente senza bloccarsi
Documentazione automatica: Visita /docs e ottieni una pagina di documentazione API interattiva e ben strutturata 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 avanzate di Python

Ed ecco perché abbiamo bisogno di un backend:

Sicurezza: La tua chiave API per l'AI è come una password – se la metti nel JavaScript del frontend, chiunque visualizzi il codice sorgente del tuo sito web potrebbe rubarla e utilizzare i tuoi crediti AI. Il backend mantiene le credenziali sensibili al sicuro.

Limitazione delle richieste e controllo: Il backend ti permette di controllare la frequenza con cui gli utenti possono fare richieste, implementare l'autenticazione degli utenti e aggiungere il logging per monitorare l'utilizzo.

Elaborazione dei dati: Potresti voler salvare le conversazioni, filtrare contenuti inappropriati o combinare più servizi AI. La logica per queste operazioni risiede nel backend.

L'architettura somiglia a un modello client-server:

Frontend: Livello di interfaccia utente per l'interazione
Backend API: Livello di elaborazione e instradamento delle richieste
Servizio AI: Computazione esterna e generazione delle risposte
Variabili d'ambiente: Configurazione sicura e archiviazione delle credenziali

Comprendere il flusso richiesta-risposta

Vediamo cosa succede quando un utente invia un messaggio:

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:

Interazione dell'utente: La persona digita nell'interfaccia della chat
Elaborazione del frontend: JavaScript cattura l'input e lo formatta come JSON
Validazione API: FastAPI valida automaticamente la richiesta utilizzando i modelli Pydantic
Integrazione AI: Il backend aggiunge il contesto (prompt di sistema) e chiama il servizio AI
Gestione della risposta: L'API riceve la risposta dell'AI e può modificarla se necessario
Visualizzazione nel frontend: JavaScript mostra la risposta nell'interfaccia della chat

Comprendere l'architettura API

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?"}

Creare l'applicazione FastAPI

Costruiamo la nostra API passo dopo passo. Crea un file chiamato api.py con il seguente codice FastAPI:

# 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 di FastAPI:

Importa FastAPI per le funzionalità di 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 logging strutturato per monitoraggio e debug
Fornisce un endpoint di controllo dello stato per monitorare lo stato del servizio

Vantaggi principali 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 in Python prevengono errori di runtime e migliorano la qualità del codice
Supporto async: 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. Vediamo perché è importante e come influisce sulla tua applicazione.

Cos'è CORS e perché esiste?

Il problema: Immagina se qualsiasi sito web potesse inviare richieste al sito della tua banca per tuo conto senza il tuo permesso. Sarebbe un incubo per la sicurezza! I browser lo impediscono di default attraverso la "Same-Origin Policy".

Same-Origin Policy: I browser consentono alle pagine web di inviare richieste solo al dominio, alla porta e al protocollo da cui sono state caricate.

Analogia con la vita 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 dirlo esplicitamente alla sicurezza.

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!

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

# 🚨 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: Durante lo 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 riesce a raggiungere il backend	Aggiungi CORSMiddleware a FastAPI
GitHub Pages + Heroku	Il frontend distribuito non riesce a 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 riesce a raggiungere l'API web	Aggiungi il dominio della tua app o usa `*` con cautela

Consiglio utile: Puoi controllare le intestazioni CORS negli strumenti per sviluppatori del browser sotto la scheda Network. Cerca intestazioni come Access-Control-Allow-Origin nella risposta.

Gestione degli errori e validazione

Nota come la nostra API include una gestione degli errori adeguata:

# 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, evitando conflitti tra progetti diversi.

# 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 bolla Python personale 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 ultra veloce 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 conservi in modo sicuro nell'ambiente.

Ecco la differenza:

Il modo sbagliato: Scrivere la tua password su un post-it e metterlo sul monitor
Il modo giusto: Conservare la tua password in un gestore di password sicuro che solo tu puoi accedere

Perché le variabili d'ambiente sono importanti

# 🚨 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 nel codice:

Esposizione nel controllo di versione: Chiunque abbia accesso al tuo repository Git vede la tua chiave API
Repository pubblici: Se pubblichi su GitHub, la tua chiave è visibile a tutto il mondo
Condivisione con il team: Altri sviluppatori che lavorano sul tuo progetto ottengono accesso alla tua chiave API personale
Violazioni di sicurezza: Se qualcuno ruba la tua chiave API, può utilizzare i tuoi crediti AI

Creazione del file di ambiente

Crea un file .env nella directory del tuo backend. Questo file conserva i tuoi segreti localmente:

# .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 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:

Vai su Impostazioni GitHub → Impostazioni sviluppatore → Token di accesso personale → Token (classico)
Clicca su "Genera nuovo token (classico)"
Imposta la scadenza (30 giorni per test, più lunga per produzione)
Seleziona gli ambiti: Spunta "repo" e qualsiasi altra autorizzazione necessaria
Genera il token e copialo immediatamente (non puoi vederlo di nuovo!)
Incollalo nel tuo file .env

# Example of what your token looks like (this is fake!)
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R

Caricamento delle variabili d'ambiente in 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 file .env e rende le variabili disponibili in 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:

# .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:

# .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

# 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 succede 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 tuo 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 l'instradamento delle richieste con validazione automatica
Abilita il ricaricamento automatico per lo sviluppo (riavvio in caso di modifiche ai file)
Genera documentazione API interattiva

3. Il server inizia ad ascoltare:

Il tuo terminale mostra: INFO: Uvicorn running on http://0.0.0.0:5000
Il server può gestire più richieste AI concorrenti
La tua API è pronta con documentazione automatica su http://localhost:5000/docs

Cosa dovresti vedere quando tutto funziona

$ 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:

Osserva le modifiche: Ricaricamento automatico abilitato per lo sviluppo
Uvicorn in esecuzione: Il server ASGI ad alte prestazioni è attivo
Processo di ricaricamento avviato: Osservatore di file per riavvii automatici
Avvio dell'applicazione completato: App FastAPI inizializzata con successo
Documentazione interattiva disponibile: 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)

Apri il browser e vai su http://localhost:5000/docs
Vedrai Swagger UI con tutti i tuoi endpoint documentati
Clicca su /hello → "Prova" → Inserisci un messaggio di test → "Esegui"
Visualizza la risposta direttamente nel browser con formattazione corretta

Metodo 2: Test di base nel browser

Vai su http://localhost:5000 per l'endpoint root
Vai su http://localhost:5000/health per controllare lo stato del server
Questo conferma che il tuo server FastAPI è in esecuzione correttamente

Metodo 2: Test da riga di comando (avanzato)

# 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

Risoluzione dei problemi comuni all'avvio

Messaggio di errore	Cosa significa	Come risolverlo
`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 a `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 elaborabile	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 offre il ricaricamento automatico quando salvi le modifiche ai file Python. Questo significa che puoi modificare il codice e testarlo immediatamente senza dover riavviare manualmente.

Logging per lo sviluppo: Aggiungi il logging per capire cosa sta succedendo:

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 gira sullo stesso computer:

Backend: http://localhost:5000
Frontend: http://localhost:3000 (o file://)

In Codespaces, il tuo ambiente di sviluppo gira 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: Vedrai il familiare messaggio di avvio di FastAPI/Uvicorn, ma noterai che sta girando all'interno dell'ambiente Codespace.

2. Configura la visibilità della porta:

Cerca la scheda "Ports" nel pannello inferiore di VS Code
Trova la porta 5000 nella lista
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 permette al frontend (che gira nel browser) di comunicare con il backend.

3. Ottieni il tuo URL pubblico: Dopo aver reso la porta pubblica, vedrai un URL simile a:

4. Aggiorna la configurazione del frontend:

Comprendere gli URL di Codespace

Gli URL di Codespace seguono un pattern prevedibile:

Analisi di questo pattern:

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 sta girando (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:

2. Testa con gli strumenti per sviluppatori del browser:

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 del 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.

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 è attivo

Workflow di sviluppo:

Apporta modifiche al codice in VS Code
FastAPI si ricarica automaticamente (grazie alla modalità di ricaricamento di Uvicorn)
Testa immediatamente le modifiche tramite l'URL pubblico
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 utenti 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 tuo telefono – tutto scorre e si aggiorna senza interruzioni

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 ai contenuti (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

Fa sembrare tutto bello (colori, font, layout)
Gestisce le 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 fanno gli utenti (clic, digitazione, scorrimento)
Comunica con il backend e aggiorna la pagina
Rende tutto interattivo e dinamico

Pensalo come un progetto architettonico:

HTML: Il progetto strutturale (definizione degli spazi e delle 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 girare in un ciclo Manipolazione del DOM: Aggiornamento dinamico del contenuto della pagina web in base alle interazioni degli utenti e alle risposte delle API

Configurazione della struttura del progetto

Crea una directory frontend con questa struttura organizzata:

Comprendere l'architettura:

Separa le preoccupazioni tra struttura (HTML), comportamento (JavaScript) e presentazione (CSS)
Mantiene una struttura di file semplice e 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 descrivano 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 in modo ponderato:

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 mobile-responsive 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>: Corretto semanticamente per l'input dell'utente, consente una navigazione con tastiera adeguata

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 ganci di stile per il CSS (es. chat-container, input-group)
Attributi id: Consentono al JavaScript di trovare e manipolare elementi specifici
Posizionamento script: File JavaScript 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
Responsive per dispositivi mobili: Il meta tag viewport abilita il design responsive
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 chat. Utilizzeremo modelli di 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 una architettura basata su classi. Pensa a una classe come a un progetto per creare oggetti – come un progetto di un architetto può essere utilizzato per costruire più case.

Perché usare le classi per le applicazioni web?

Organizzazione: Tutte le funzionalità correlate sono raggruppate insieme
Riutilizzabilità: Potresti 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:

Comprendere ogni concetto di JavaScript

Struttura delle classi ES6:

Pattern Async/Await:

Programmazione basata su eventi: Invece di controllare costantemente se qualcosa è accaduto, "ascoltiamo" gli eventi:

Manipolazione del DOM:

Sicurezza e migliori pratiche

Prevenzione XSS:

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:

Considerazioni sull'esperienza utente:

UI ottimistica: Aggiungi immediatamente il messaggio dell'utente, senza aspettare la risposta del server
Stati di caricamento: Disabilita i pulsanti e mostra "Invio in corso..." mentre aspetti
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

Caricamento della pagina → L'evento DOMContentLoaded viene attivato → Viene creato new ChatApp()
Il costruttore viene eseguito → Ottiene i riferimenti agli elementi DOM → Configura i listener degli eventi
L'utente digita un messaggio → Premere Invio o clicca su Invia → Viene eseguito handleSubmit
handleSubmit → Convalida l'input → Mostra lo stato di caricamento → Chiama l'API
Risposta dell'API → Aggiunge il messaggio dell'AI alla chat → Riabilita l'interfaccia
Pronto per il prossimo messaggio → L'utente può continuare a chattare Questa architettura è scalabile: puoi facilmente aggiungere funzionalità come modifica dei messaggi, caricamento di file o thread di conversazione multipli senza dover riscrivere la struttura principale.

Stile della tua interfaccia di chat

Ora creiamo un'interfaccia di chat moderna e visivamente accattivante con CSS. Un buon stile rende la tua applicazione professionale e migliora l'esperienza utente complessiva. Utilizzeremo funzionalità moderne di CSS come Flexbox, CSS Grid e proprietà personalizzate per un design reattivo e accessibile.

Crea styles.css con questi stili completi:

/* 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 una tematizzazione 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

Configurazione dell'URL del backend

L'ultimo passaggio consiste nell'aggiornare il BASE_URL nel tuo JavaScript per corrispondere al server backend:

// 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 tuo browser. Dovresti vedere il messaggio di benvenuto dal tuo server FastAPI.

Test e distribuzione

Ora che hai costruito i componenti frontend e backend, testiamo che tutto funzioni insieme ed esploriamo le opzioni di distribuzione per condividere il tuo assistente di chat con altri.

Workflow di test locale

Segui questi passaggi per testare la tua applicazione completa:

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:

Avvia il server backend:

cd backend
source venv/bin/activate  # or venv\Scripts\activate on Windows
python api.py

Verifica che l'API funzioni:
- Apri http://localhost:5000 nel tuo browser
- Dovresti vedere il messaggio di benvenuto dal tuo server FastAPI
Apri il tuo frontend:
- Vai alla directory del frontend
- Apri index.html nel tuo browser web
- Oppure usa l'estensione Live Server di VS Code per una migliore esperienza di sviluppo
Testa la funzionalità di chat:
- Scrivi 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 FastAPI CORSMiddleware sia configurato correttamente
Errore chiave API	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 di errore	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
Esamina l'output del terminale del backend per errori Python o problemi API
Conferma che le variabili d'ambiente siano caricate e accessibili correttamente

Sfida dell'Agente GitHub Copilot 🚀

Usa la modalità Agente 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 capire 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à agente qui.

Compito: Crea 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:

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:

Personalizza il nostro codice FastAPI e rendilo unico
Crea una personalità AI unica – magari un assistente culinario utile, un partner creativo per la scrittura o un compagno di studio?
Aggiungi una gestione degli errori solida 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 che saresti orgoglioso di mostrare ad altri sviluppatori
Progetta uno stile personalizzato che rifletta la personalità della tua 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 "L'AI sta scrivendo..." mentre si attendono risposte	Animazioni CSS, programmazione asincrona
Timestamp dei messaggi	Mostra quando è stato inviato ogni messaggio	Formattazione data/ora, design UX
Esportazione chat	Permetti agli utenti di scaricare la loro conversazione	Gestione file, esportazione dati
Cambio tema	Interruttore per modalità chiara/scura	Variabili CSS, preferenze utente
Input vocale	Aggiungi funzionalità di riconoscimento vocale	API Web, accessibilità

Test e documentazione

Assicurazione di 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 tramite tastiera e lettori di schermo
Valida HTML e CSS per 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à uniche o personalizzazioni che hai aggiunto
Fornisci istruzioni chiare per l'installazione per altri sviluppatori

Linee guida per la consegna

Materiali da consegnare:

Cartella completa del progetto con tutto il codice sorgente
README.md con descrizione del progetto e istruzioni per l'installazione
Screenshot che dimostrano il funzionamento del tuo assistente di chat
Breve riflessione su ciò che hai imparato e le sfide affrontate

Criteri di valutazione:

Funzionalità: L'assistente di chat funziona come previsto?
Qualità del codice: Il codice è ben organizzato, commentato e mantenibile?
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 con i requisiti di base, poi aggiungi miglioramenti una volta che tutto funziona. Concentrati sulla creazione di un'esperienza principale ben rifinita prima di aggiungere funzionalità avanzate.

Soluzione

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 avviene quando dai al tuo assistente AI una personalità unica. Sperimenta con diversi prompt di sistema per creare assistenti specializzati:

Esempio di assistente professionale:

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 aiuto per la scrittura creativa:

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:

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à avanzate di CSS:

Implementa animazioni e transizioni fluide per i messaggi
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 un 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 il salvataggio automatico su localStorage per evitare la perdita di messaggi

Integrazione avanzata con l'AI

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 ricorda i messaggi precedenti)
Implementa suggerimenti intelligenti basati sull'argomento della conversazione
Crea pulsanti di risposta rapida per domande comuni

🎯 Obiettivo di apprendimento: Queste sfide bonus 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 di chat completo basato sull'AI 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 la funzionalità AI
Costruito un'API RESTful utilizzando Flask con gestione degli errori adeguata
Implementato autenticazione sicura utilizzando variabili d'ambiente
Configurato CORS per richieste cross-origin tra frontend e backend

Sviluppo Frontend:

Creato un'interfaccia di chat reattiva 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 reattivo

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 workflow completo dell'applicazione, dall'input dell'utente alla risposta dell'AI

Risultati chiave di apprendimento

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 costruzione di applicazioni alimentate dall'AI, che rappresentano il futuro dello sviluppo web. Ora comprendi come integrare 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 mobile
Progettazione e sviluppo API per architetture a microservizi
Sviluppo interfacce utente con focus su accessibilità e design reattivo
Pratiche DevOps inclusa la configurazione dell'ambiente e la 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 dell'AI, sull'etica e sulle pratiche di sviluppo responsabile
Costruisci applicazioni più complesse con memoria delle conversazioni e consapevolezza del contesto

Idee per progetti avanzati:

Chat room multiutente con moderazione AI
Chatbot per il servizio clienti alimentati dall'AI
Assistenti di tutoraggio educativo con apprendimento personalizzato
Collaboratori per la scrittura creativa con diverse personalità AI
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.

Configurazione del tuo ambiente di sviluppo

Passaggio 1: Crea dal template

Vai al repository Web Dev For Beginners
Clicca su "Use this template" nell'angolo in alto a destra (assicurati di essere loggato su GitHub)

Passaggio 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

Passaggio 3: Configurazione dell'ambiente Una volta caricato il tuo Codespace, avrai accesso a:

Python, Node.js preinstallati e tutti gli strumenti di sviluppo necessari
Interfaccia VS Code con estensioni per lo sviluppo web
Accesso al terminale per eseguire server backend e frontend
Port forwarding per testare le tue applicazioni

Cosa offre Codespaces:

Elimina i problemi di configurazione e configurazione dell'ambiente locale
Fornisce un ambiente di sviluppo coerente su dispositivi diversi
Include strumenti e estensioni preconfigurati per lo sviluppo web
Offre integrazione senza problemi con GitHub per il controllo delle versioni e la collaborazione

🚀 Consiglio utile: Codespaces è perfetto per imparare e prototipare 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. Sebbene ci impegniamo per garantire l'accuratezza, si prega di notare che le traduzioni automatiche potrebbero contenere errori o imprecisioni. Il documento originale nella sua lingua nativa dovrebbe essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale umana. Non siamo responsabili per eventuali incomprensioni o interpretazioni errate derivanti dall'uso di questa traduzione.

80 KiB Raw Blame History Unescape Escape

Costruire un Assistente Chat con l'AI

Comprendere l'AI: Dal Mistero alla Padronanza

Cos'è davvero l'"AI Generativa"?

Come i Modelli AI Imparano (Versione Semplice)

Perché Modelli GitHub?

Configurare l'Integrazione Backend con Python

Comprendere l'Implementazione Base

Comprendere i Ruoli dei Messaggi: Il Framework di Conversazione AI

Comprendere i Parametri AI: Fine-Tuning del Comportamento delle Risposte

Temperatura (0.0 a 2.0): La Manopola della Creatività

Max Tokens (1 a 4096+): Il Controllore della Lunghezza della Risposta

Top_p (0.0 a 1.0): Il Parametro di Focalizzazione

Mettere Tutto Insieme: Combinazioni di Parametri per Diversi Casi d'Uso

La Magia dei Prompt di Sistema: Programmare la Personalità dell'AI

Perché i Prompt di Sistema Sono Così Potenti

Creare Prompt di Sistema Efficaci: L'Arte e la Scienza

Esempi di Prompt di Sistema con Contesto

Vedere i Prompt di Sistema in Azione

Tecniche Avanzate per i Prompt di Sistema

Perché Questo È Importante per il Tuo Assistente Chat

Costruire l'API Web con FastAPI: Il Tuo Hub di Comunicazione AI ad Alte Prestazioni

Perché FastAPI per le Applicazioni AI?

Comprendere il flusso richiesta-risposta

Comprendere l'architettura API

Creare l'applicazione FastAPI

Comprendere CORS: La guardia di sicurezza del web

Cos'è CORS e perché esiste?

CORS nel tuo ambiente di sviluppo

Sicurezza CORS: Sviluppo vs Produzione

Scenari comuni CORS e soluzioni

Gestione degli errori e validazione

Configurazione e avvio del backend

Configurazione dell'ambiente Python

Configurazione dell'ambiente: mantenere i segreti al sicuro

Cosa sono le variabili d'ambiente?

Perché le variabili d'ambiente sono importanti

Creazione del file di ambiente

Creazione del token di accesso personale GitHub

Caricamento delle variabili d'ambiente in Python

Sicurezza Git: Il file .gitignore

Ambienti diversi, segreti diversi

Avvio del server di sviluppo: dare vita al tuo FastAPI

Comprendere il processo di avvio del server FastAPI

Cosa dovresti vedere quando tutto funziona

Testare il tuo FastAPI: Approcci potenti e multipli

Risoluzione dei problemi comuni all'avvio

Migliori pratiche di sviluppo

Configurazione per GitHub Codespaces: sviluppo cloud semplificato

Comprendere il networking di Codespaces

Configurazione passo-passo di Codespaces

Comprendere gli URL di Codespace

Testare la configurazione di Codespace

Codespaces vs Sviluppo Locale

Consigli per lo sviluppo in Codespaces

Creare l'interfaccia chat del frontend: dove gli utenti incontrano l'AI

Comprendere l'architettura moderna del frontend

I tre pilastri dello sviluppo frontend

Perché l'architettura moderna di JavaScript è importante

Configurazione della struttura del progetto

Costruire la base HTML: struttura semantica per l'accessibilità

Struttura del documento

Elementi semantici

Funzionalità di accessibilità

Integrazione di CSS e JavaScript

Aggiungere JavaScript interattivo: logica moderna per applicazioni web

Comprendere l'architettura moderna di JavaScript

Comprendere ogni concetto di JavaScript

Sicurezza e migliori pratiche

Comprendere il flusso dell'applicazione

Stile della tua interfaccia di chat

Configurazione dell'URL del backend

Test e distribuzione

Workflow di test locale

Risoluzione dei problemi comuni

Sfida dell'Agente GitHub Copilot 🚀

Compito: Crea il tuo assistente AI personale

Requisiti del progetto

Compiti principali di implementazione

Idee per miglioramenti (opzionali)

80 KiB

Raw Blame History Unescape Escape