99 KiB
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
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 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:
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
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
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.
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 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
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:
"""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:
osper leggere le variabili d'ambiente eOpenAIper 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:
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)
# 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
# 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
# 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
}
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:
- 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: Indica 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 deve 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é è 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
/docse 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:
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 utente: La persona digita nell'interfaccia di chat
- Elaborazione frontend: JavaScript cattura l'input e lo formatta come JSON
- Validazione API: FastAPI valida automaticamente la richiesta utilizzando modelli Pydantic
- Integrazione AI: Il backend aggiunge contesto (prompt di sistema) e chiama il servizio AI
- Gestione della risposta: L'API riceve la risposta AI e può modificarla se necessario
- Visualizzazione frontend: JavaScript mostra la risposta nell'interfaccia di 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?"}
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:
# 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
/docsquando 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
/docsper 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!
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: 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:
# 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.
# 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
# 🚨 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:
- Esposizione al 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 internet
- Condivisione del team: Altri sviluppatori che lavorano sul tuo progetto ottengono accesso alla tua chiave API personale
- 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:
# .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:
- Vai alle Impostazioni GitHub → Impostazioni sviluppatore → Token di accesso personale → Token (classici)
- Clicca su "Genera nuovo token (classico)"
- Imposta la scadenza (30 giorni per i test, più lunga per la produzione)
- Seleziona gli ambiti: Seleziona "repo" e qualsiasi altra autorizzazione necessaria
- Genera il token e copialo immediatamente (non puoi vederlo di nuovo!)
- Incolla 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 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:
# .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 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
$ 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
/docsper 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→ "Try it out" → Inserisci un messaggio di prova → "Execute" - Visualizza la risposta direttamente nel browser con formattazione corretta
Metodo 2: Test di base nel browser
- Vai su
http://localhost:5000per l'endpoint principale - Vai su
http://localhost:5000/healthper controllare lo stato del server - Questo conferma che il 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
# 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.
# 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:
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:
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:
// 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:
// 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:
# 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:
- 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 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
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]
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:
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:
<!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 messaggiaria-live="polite": Annuncia nuovi messaggi ai lettori di schermo senza interromperearia-label: Fornisce etichette descrittive per i controlli del modulorequired: 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:
// 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:
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:
// 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:
// 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:
// 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:
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:
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
- Caricamento della pagina → L'evento
DOMContentLoadedviene attivato → Viene creatonew 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 → Valida 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 – 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:
/* 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:
// 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:5000se 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:
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:5000nel browser - Dovresti vedere il messaggio di benvenuto dal server FastAPI
- Apri
-
Apri il frontend:
- Vai alla directory del frontend
- Apri
index.htmlnel browser web - Oppure usa l'estensione Live Server di VS Code per una migliore esperienza di sviluppo
-
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
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 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:
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:
- Cartella completa del progetto con tutto il codice sorgente
- README.md con descrizione del progetto e istruzioni per l'installazione
- Screenshot che mostrano il tuo assistente di chat in azione
- 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
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:
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:
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à 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
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
- 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. 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.