# Construire un assistant de chat avec l’IA
Vous souvenez-vous dans Star Trek quand l’équipage discutait tranquillement avec l’ordinateur du vaisseau, lui posant des questions complexes et obtenant des réponses réfléchies ? Ce qui semblait relever de la pure science-fiction dans les années 1960 est désormais quelque chose que vous pouvez construire en utilisant les technologies web que vous connaissez déjà.
Dans cette leçon, nous allons créer un assistant de chat IA en utilisant HTML, CSS, JavaScript et une certaine intégration back-end. Vous découvrirez comment les mêmes compétences que vous apprenez peuvent se connecter à des services IA puissants capables de comprendre le contexte et de générer des réponses significatives.
Pensez à l’IA comme à une vaste bibliothèque qui peut non seulement trouver des informations mais aussi les synthétiser en réponses cohérentes, adaptées à vos questions spécifiques. Au lieu de parcourir des milliers de pages, vous obtenez des réponses directes et contextuelles.
L’intégration se fait via des technologies web familières qui collaborent. HTML crée l’interface de chat, CSS gère le design visuel, JavaScript gère les interactions utilisateur, et une API back-end connecte tout cela aux services IA. C’est similaire à la façon dont différentes sections d’un orchestre jouent ensemble pour créer une symphonie.
Nous construisons essentiellement un pont entre la communication humaine naturelle et le traitement machine. Vous apprendrez à la fois l’implémentation technique de l’intégration des services IA et les modèles de conception qui rendent les interactions intuitives.
À la fin de cette leçon, l’intégration IA vous paraîtra moins mystérieuse et plus comme une autre API avec laquelle vous travaillez. Vous comprendrez les modèles fondamentaux qui alimentent des applications comme ChatGPT et Claude, en utilisant les mêmes principes de développement web que vous apprenez.
## ⚡ Ce que vous pouvez faire dans les 5 prochaines minutes
**Parcours de démarrage rapide pour développeurs pressés**
```mermaid
flowchart LR
A[⚡ 5 minutes] --> B[Obtenir un jeton GitHub]
B --> C[Tester le terrain de jeu AI]
C --> D[Copier le code Python]
D --> E[Voir les réponses AI]
```
- **Minute 1** : Visitez [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) et créez un jeton d’accès personnel
- **Minute 2** : Testez les interactions IA directement dans l’interface du playground
- **Minute 3** : Cliquez sur l’onglet « Code » et copiez l’extrait Python
- **Minute 4** : Exécutez le code localement avec votre jeton : `GITHUB_TOKEN=your_token python test.py`
- **Minute 5** : Regardez votre première réponse IA générée depuis votre propre code
**Code de test rapide** :
```python
import os
from openai import OpenAI
client = OpenAI(
base_url="https://models.github.ai/inference",
api_key="your_token_here"
)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Hello AI!"}],
model="openai/gpt-4o-mini"
)
print(response.choices[0].message.content)
```
**Pourquoi c’est important** : En 5 minutes, vous vivrez la magie de l’interaction IA programmée. Cela représente la brique fondamentale qui alimente chaque application IA que vous utilisez.
Voici à quoi ressemblera votre projet final :
## 🗺️ Votre parcours d’apprentissage au travers du développement d’applications IA
```mermaid
journey
title De Développement Web à Intégration IA
section Comprendre les Fondations de l'IA
Découvrir les concepts de l'IA générative: 4: You
Explorer la plateforme GitHub Models: 6: You
Maîtriser les paramètres et prompts de l'IA: 8: You
section Intégration Backend
Construire un serveur API Python: 5: You
Implémenter des appels de fonctions IA: 7: You
Gérer les opérations asynchrones: 8: You
section Développement Frontend
Créer une interface de chat moderne: 6: You
Maîtriser les interactions en temps réel: 8: You
Construire une expérience utilisateur réactive: 9: You
section Application Professionnelle
Déployer un système IA complet: 7: You
Optimiser les modèles de performance: 8: You
Créer une application prête pour la production: 9: You
```
**Votre destination de parcours** : À la fin de cette leçon, vous aurez construit une application complète propulsée par IA en utilisant les mêmes technologies et modèles qui pilotent des assistants IA modernes comme ChatGPT, Claude et Google Bard.
## Comprendre l’IA : du mystère à la maîtrise
Avant de plonger dans le code, comprenons ce avec quoi nous travaillons. Si vous avez déjà utilisé des API, vous connaissez le schéma de base : envoyer une requête, recevoir une réponse.
Les API IA suivent une structure similaire, mais au lieu de récupérer des données préenregistrées depuis une base de données, elles génèrent des réponses nouvelles basées sur des modèles appris à partir d’énormes quantités de texte. Pensez-y comme la différence entre un système de catalogue de bibliothèque et un bibliothécaire savant qui peut synthétiser l’information provenant de multiples sources.
### Qu’est-ce que « l’IA générative » exactement ?
Considérez comment la pierre de Rosette a permis aux chercheurs de comprendre les hiéroglyphes égyptiens en trouvant des correspondances entre des langues connues et inconnues. Les modèles IA fonctionnent de la même manière – ils identifient des modèles dans d’énormes volumes de texte pour comprendre le fonctionnement du langage, puis utilisent ces modèles pour générer des réponses adaptées à de nouvelles questions.
**Laissez-moi décomposer cela avec une comparaison simple :**
- **Base de données traditionnelle** : Comme demander votre acte de naissance – vous obtenez toujours le même document exact
- **Moteur de recherche** : Comme demander à un bibliothécaire de trouver des livres sur les chats – il vous montre ce qui est disponible
- **IA générative** : Comme demander à un ami savant sur les chats – il vous raconte des choses intéressantes avec ses propres mots, adaptées à ce que vous voulez savoir
```mermaid
graph LR
A[Votre Question] --> B[Modèle IA]
B --> C[Reconnaissance de Motifs]
C --> D[Génération de Contenu]
D --> E[Réponse Contextuelle]
F[Données d'Entraînement Livres, Articles, Web] --> B
```
### Comment les modèles IA apprennent (version simple)
Les modèles IA apprennent par exposition à des jeux de données énormes contenant des textes extraits de livres, articles, conversations. Au travers de ce processus, ils identifient des modèles sur :
- La structure des pensées dans la communication écrite
- Quels mots apparaissent souvent ensemble
- Comment les conversations s’enchaînent typiquement
- Les différences contextuelles entre la communication formelle et informelle
**C’est similaire à la façon dont les archéologues déchiffrent les langues anciennes** : ils analysent des milliers d’exemples pour comprendre grammaire, vocabulaire et contexte culturel, devenant ensuite capables d’interpréter de nouveaux textes en utilisant ces modèles appris.
### Pourquoi GitHub Models ?
Nous utilisons GitHub Models pour une raison pratique – cela nous donne accès à une IA de niveau entreprise sans avoir à mettre en place notre propre infrastructure IA (ce que croyez-moi, vous ne voulez pas faire maintenant !). Pensez-y comme utiliser une API météo au lieu d’essayer de prédire le temps vous-même en installant des stations météo partout.
C’est en gros de « l’IA en tant que service », et le meilleur dans tout ça ? C’est gratuit pour commencer, vous pouvez donc expérimenter sans craindre de vous retrouver avec une grosse facture.
```mermaid
graph LR
A[Interface de chat frontend] --> B[Votre API backend]
B --> C[API des modèles GitHub]
C --> D[Traitement du modèle IA]
D --> C
C --> B
B --> A
```
Nous utiliserons GitHub Models pour notre intégration back-end, qui fournit un accès à des capacités IA professionnelles via une interface conviviale pour développeurs. Le [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) sert d’environnement de test où vous pouvez expérimenter différents modèles IA et comprendre leurs capacités avant de les implémenter dans le code.
## 🧠 Écosystème de développement d’applications IA
```mermaid
mindmap
root((Développement IA))
Understanding AI
Generative Models
Reconnaissance de motifs
Génération de contenu
Compréhension du contexte
Synthèse de réponse
AI Parameters
Contrôle de la température
Limites de jetons
Filtrage Top-p
Messages système
Backend Architecture
API Integration
Modèles GitHub
Authentification
Gestion des requêtes
Gestion des erreurs
Python Infrastructure
Framework FastAPI
Opérations asynchrones
Sécurité de l’environnement
Configuration CORS
Frontend Experience
Chat Interface
Mises à jour en temps réel
Historique des messages
Retours des utilisateurs
États de chargement
Modern Web Tech
Classes ES6
Async/Await
Manipulation du DOM
Gestion des événements
Professional Patterns
Security Best Practices
Gestion des jetons
Validation des entrées
Prévention XSS
Frontières d’erreur
Production Readiness
Optimisation des performances
Design adaptatif
Accessibilité
Stratégies de test
```
**Principe clé** : Le développement d’applications IA combine des compétences traditionnelles de développement web avec l’intégration de services IA, créant des applications intelligentes qui paraissent naturelles et réactives pour les utilisateurs.
**Voici ce qui rend le playground si utile :**
- **Essayez** différents modèles IA comme GPT-4o-mini, Claude et d’autres (tous gratuits !)
- **Testez** vos idées et vos prompts avant d’écrire du code
- **Obtenez** des extraits de code prêts à l’emploi dans votre langage de programmation préféré
- **Ajustez** des paramètres comme le niveau de créativité ou la longueur de la réponse pour voir comment cela impacte le résultat
Une fois que vous avez joué un peu, cliquez simplement sur l’onglet « Code » et choisissez votre langage pour obtenir le code d’implémentation dont vous avez besoin.
## Mise en place de l’intégration back-end Python
Passons maintenant à l’implémentation de l’intégration IA en utilisant Python. Python est excellent pour les applications IA grâce à sa syntaxe simple et ses bibliothèques puissantes. Nous commencerons avec le code du playground GitHub Models puis le refactoriserons en une fonction réutilisable, prête pour la production.
### Comprendre l’implémentation de base
Lorsque vous récupérez le code Python du playground, vous obtenez quelque chose qui ressemble à ceci. Ne vous inquiétez pas si cela vous semble beaucoup au début – parcourons-le pas à pas :
```python
"""Run this model in Python
> pip install openai
"""
import os
from openai import OpenAI
# Pour vous authentifier avec le modèle, vous devrez générer un jeton d'accès personnel (PAT) dans vos paramètres GitHub.
# Créez votre jeton PAT en suivant les instructions ici : 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)
```
**Voici ce qui se passe dans ce code :**
- **Nous importons** les outils nécessaires : `os` pour lire les variables d’environnement et `OpenAI` pour communiquer avec l’IA
- **Nous configurons** le client OpenAI pour qu’il pointe vers les serveurs IA de GitHub au lieu d’OpenAI directement
- **Nous authentifions** avec un jeton GitHub spécial (plus d’infos là-dessus dans une minute !)
- **Nous structurons** notre conversation avec différents « rôles » – pensez-y comme poser la scène pour une pièce de théâtre
- **Nous envoyons** notre requête à l’IA avec quelques paramètres de réglage fin
- **Nous extrayons** le texte de réponse réel à partir de toutes les données retournées
### Comprendre les rôles des messages : le cadre de conversation IA
Les conversations IA utilisent une structure spécifique avec différents « rôles » qui servent des buts distincts :
```python
messages=[
{
"role": "system",
"content": "You are a helpful assistant who explains things simply."
},
{
"role": "user",
"content": "What is machine learning?"
}
]
```
**Pensez-y comme diriger une pièce de théâtre :**
- **Rôle système** : Comme les didascalies pour un acteur – indique à l’IA comment se comporter, quelle personnalité adopter et comment répondre
- **Rôle utilisateur** : La question ou le message réel de la personne utilisant votre application
- **Rôle assistant** : La réponse de l’IA (vous ne l’envoyez pas, mais elle apparaît dans l’historique de la conversation)
**Analogie dans la vie réelle** : Imaginez que vous présentez un ami à quelqu’un lors d’une fête :
- **Message système** : « Voici mon amie Sarah, elle est médecin et explique très bien les concepts médicaux simplement »
- **Message utilisateur** : « Peux-tu expliquer comment fonctionnent les vaccins ? »
- **Réponse assistant** : Sarah répond en tant que médecin aimable, pas en tant qu’avocat ou chef cuisinier
### Comprendre les paramètres IA : ajuster le comportement des réponses
Les paramètres numériques dans les appels API IA contrôlent la manière dont le modèle génère les réponses. Ces réglages vous permettent d’ajuster le comportement de l’IA selon différents cas d’usage :
#### Température (0,0 à 2,0) : le cadran de créativité
**Ce que ça fait** : Contrôle le niveau de créativité ou de prévisibilité des réponses de l’IA.
**Pensez-y comme au niveau d’improvisation d’un musicien de jazz :**
- **Température = 0,1** : Rejoue la même mélodie à chaque fois (très prévisible)
- **Température = 0,7** : Ajoute des variations subtiles tout en restant reconnaissable (créativité équilibrée)
- **Température = 1,5** : Jazz expérimental complet avec des tournures inattendues (très imprévisible)
```python
# Réponses très prévisibles (bon pour les questions factuelles)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "What is 2+2?"}],
temperature=0.1 # Dirait presque toujours "4"
)
# Réponses créatives (bon pour le brainstorming)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Write a creative story opening"}],
temperature=1.2 # Générera des histoires uniques et inattendues
)
```
#### Max Tokens (1 à 4096+) : le contrôleur de longueur de réponse
**Ce que ça fait** : Définit une limite à la longueur de la réponse de l’IA.
**Pensez aux tokens comme approximativement équivalents à des mots** (environ 1 token = 0,75 mots en anglais) :
- **max_tokens=50** : Court et concis (comme un SMS)
- **max_tokens=500** : Un paragraphe ou deux agréables
- **max_tokens=2000** : Une explication détaillée avec des exemples
```python
# Réponses courtes et concises
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=100 # Oblige à une explication brève
)
# Réponses détaillées et complètes
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=1500 # Permet des explications détaillées avec des exemples
)
```
#### Top_p (0,0 à 1,0) : le paramètre de focus
**Ce que ça fait** : Contrôle à quel point l’IA reste focalisée sur les réponses les plus probables.
**Imaginez que l’IA possède un énorme vocabulaire, classé par probabilité de chaque mot :**
- **top_p=0,1** : Ne considère que les 10% de mots les plus probables (très concentré)
- **top_p=0,9** : Considère 90% des mots possibles (plus créatif)
- **top_p=1,0** : Considère tout (variété maximale)
**Par exemple** : Si vous demandez « Le ciel est généralement... »
- **top_p bas** : Dit presque toujours « bleu »
- **top_p élevé** : Peut dire « bleu », « nuageux », « vaste », « changeant », « magnifique », etc.
### Mise en pratique : combinaisons de paramètres pour différents cas d’usage
```python
# Pour des réponses factuelles et cohérentes (comme un bot de documentation)
factual_params = {
"temperature": 0.2,
"max_tokens": 300,
"top_p": 0.3
}
# Pour l'assistance en écriture créative
creative_params = {
"temperature": 1.1,
"max_tokens": 1000,
"top_p": 0.9
}
# Pour des réponses conversationnelles et utiles (équilibrées)
conversational_params = {
"temperature": 0.7,
"max_tokens": 500,
"top_p": 0.8
}
```
```mermaid
quadrantChart
title Matrice d'Optimisation des Paramètres de l'IA
x-axis Faible Créativité --> Forte Créativité
y-axis Réponse Courte --> Réponse Longue
quadrant-1 Contenu Créatif
quadrant-2 Analyse Approfondie
quadrant-3 Faits Rapides
quadrant-4 IA Conversationnelle
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]
```
**Pourquoi ces paramètres comptent** : Différentes applications ont besoin de types de réponses différents. Un bot service client doit être cohérent et factuel (température basse), alors qu’un assistant d’écriture créative doit être imaginatif et varié (température haute). Comprendre ces paramètres vous donne le contrôle sur la personnalité et le style de réponse de votre IA.
```
**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))
```
**Comprendre cette fonction améliorée :**
- **Accepte** deux paramètres : le prompt de l’utilisateur et un message système optionnel
- **Fournit** un message système par défaut pour un comportement assistant général
- **Utilise** des annotations de type Python appropriées pour une meilleure documentation du code
- **Inclut** une docstring détaillée expliquant l’objectif et les paramètres de la fonction
- **Retourne** uniquement le contenu de la réponse, facilitant son usage dans notre API web
- **Maintient** les mêmes paramètres de modèle pour un comportement IA cohérent
### La magie des prompts système : programmer la personnalité de l’IA
Si les paramètres contrôlent la manière dont l’IA pense, les prompts système contrôlent qui l’IA pense être. C’est honnêtement l’une des parties les plus fascinantes du travail avec l’IA – vous donnez essentiellement à l’IA une personnalité complète, un niveau d’expertise et un style de communication.
**Pensez aux prompts système comme au choix d’acteurs différents pour différents rôles** : Au lieu d’avoir un assistant générique, vous pouvez créer des experts spécialisés pour diverses situations. Besoin d’un professeur patient ? D’un partenaire de brainstorming créatif ? D’un conseiller d’affaires direct ? Changez simplement le prompt système !
#### Pourquoi les prompts système sont si puissants
Voici la partie fascinante : les modèles IA ont été entraînés sur d’innombrables conversations où les gens adoptent différents rôles et niveaux d’expertise. Lorsque vous donnez un rôle spécifique à l’IA, c’est comme activer un interrupteur qui déploie tous ces modèles appris.
**C’est comme le jeu d’acteur méthode pour l’IA** : dites à un acteur « vous êtes un vieux professeur sage » et regardez comment il ajuste instantanément posture, vocabulaire et manières. L’IA fait quelque chose de remarquablement similaire avec les modèles de langage.
#### Concevoir des prompts système efficaces : l’art et la science
**L’anatomie d’un excellent prompt système :**
1. **Rôle/Identité** : Qui est l’IA ?
2. **Expertise** : Que sait-elle ?
3. **Style de communication** : Comment s’exprime-t-elle ?
4. **Instructions spécifiques** : Sur quoi doit-elle se concentrer ?
```python
# ❌ Invite système vague
"You are helpful."
# ✅ Invite système détaillée et efficace
"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."
```
#### Exemples de prompts système avec contexte
Voyons comment différents prompts système créent des personnalités IA complètement différentes :
```python
# Exemple 1 : Le professeur patient
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.
"""
# Exemple 2 : Le collaborateur créatif
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.
"""
# Exemple 3 : Le conseiller commercial stratégique
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.
"""
```
#### Voir les prompts système en action
Testons la même question avec différents prompts système pour voir les différences spectaculaires :
**Question** : « Comment gérer l’authentification utilisateur dans mon application web ? »
```python
# Avec une invite de l'enseignant :
teacher_response = call_llm(
"How do I handle user authentication in my web app?",
teacher_prompt
)
# Réponse typique : « Excellente question ! Décomposons l'authentification en étapes simples.
# Imaginez-le comme un videur de boîte de nuit vérifiant les pièces d'identité... »
# Avec une invite commerciale :
business_response = call_llm(
"How do I handle user authentication in my web app?",
business_prompt
)
# Réponse typique : « D'un point de vue stratégique, l'authentification est cruciale pour la confiance des utilisateurs et la conformité réglementaire.
# Laissez-moi vous présenter un cadre tenant compte de la sécurité,
# de l'expérience utilisateur et de la scalabilité... »
```
#### Techniques avancées de prompts système
**1. Mise en contexte** : Fournissez un contexte à l’IA
```python
system_prompt = """
You are helping a junior developer who just started their first job at a startup.
They know basic HTML/CSS/JavaScript but are new to backend development and databases.
Be encouraging and explain things step-by-step without being condescending.
"""
```
**2. Formatage de la sortie** : Dites à l’IA comment structurer les réponses
```python
system_prompt = """
You are a technical mentor. Always structure your responses as:
1. Quick Answer (1-2 sentences)
2. Detailed Explanation
3. Code Example
4. Common Pitfalls to Avoid
5. Next Steps for Learning
"""
```
**3. Définition des contraintes** : Définissez ce que l’IA ne doit PAS faire
```python
system_prompt = """
You are a coding tutor focused on teaching best practices. Never write complete
solutions for the user - instead, guide them with hints and questions so they
learn by doing. Always explain the 'why' behind coding decisions.
"""
```
#### Pourquoi c’est important pour votre assistant de chat
Comprendre les invites système vous donne un pouvoir incroyable pour créer des assistants IA spécialisés :
- **Bot de service client** : Utile, patient, conscient des politiques
- **Tuteur d’apprentissage** : Encourageant, étape par étape, vérifie la compréhension
- **Partenaire créatif** : Imaginatif, construit sur les idées, pose la question « et si ? »
- **Expert technique** : Précis, détaillé, conscient de la sécurité
**L’idée clé** : Vous n’appelez pas simplement une API IA – vous créez une personnalité IA personnalisée qui sert votre cas d’usage spécifique. C’est ce qui rend les applications IA modernes adaptées et utiles plutôt que génériques.
### 🎯 Vérification pédagogique : Programmation de la personnalité IA
**Pause et réflexion** : Vous venez d’apprendre à programmer des personnalités IA par des invites système. C’est une compétence fondamentale dans le développement moderne d’applications IA.
**Auto-évaluation rapide** :
- Pouvez-vous expliquer en quoi les invites système diffèrent des messages utilisateur classiques ?
- Quelle est la différence entre les paramètres temperature et top_p ?
- Comment créeriez-vous une invite système pour un cas d’utilisation spécifique (comme un tuteur de code) ?
**Lien avec le monde réel** : Les techniques d’invite système que vous avez apprises sont utilisées dans toutes les grandes applications IA – de l’assistance au codage de GitHub Copilot à l’interface conversationnelle de ChatGPT. Vous maîtrisez les mêmes modèles utilisés par les équipes produits IA des grandes entreprises tech.
**Question défi** : Comment pourriez-vous concevoir différentes personnalités IA pour différents types d’utilisateurs (débutant vs expert) ? Réfléchissez à comment un même modèle IA sous-jacent peut servir différents publics via l’ingénierie des invites.
## Construire l’API Web avec FastAPI : Votre hub de communication IA haute performance
Construisons maintenant le backend qui connecte votre frontend aux services IA. Nous allons utiliser FastAPI, un framework Python moderne qui excelle dans la création d’API pour applications IA.
FastAPI offre plusieurs avantages pour ce type de projet : support natif de l’async pour gérer des requêtes concurrentes, génération automatique de documentation API, et excellente performance. Votre serveur FastAPI agit comme intermédiaire qui reçoit les requêtes du frontend, communique avec les services IA, et renvoie les réponses formatées.
### Pourquoi FastAPI pour les applications IA ?
Vous vous demandez peut-être : « Ne puis-je pas appeler directement l’IA depuis mon JavaScript frontend ? » ou « Pourquoi FastAPI plutôt que Flask ou Django ? » Excellentes questions !
**Voici pourquoi FastAPI est parfait pour ce que nous construisons :**
- **Async par défaut** : Peut gérer plusieurs requêtes IA simultanément sans blocage
- **Docs automatiques** : Visitez `/docs` et obtenez gratuitement une documentation API interactive superbe
- **Validation intégrée** : Détecte les erreurs avant qu’elles ne causent des problèmes
- **Ultra rapide** : Un des frameworks Python les plus rapides
- **Python moderne** : Profite des dernières fonctionnalités avancées de Python
**Et pourquoi avons-nous besoin d’un backend :**
**Sécurité** : Votre clé API IA est comme un mot de passe – si vous la placez dans le JavaScript frontend, toute personne qui voit le code source de votre site web pourrait la voler et utiliser vos crédits IA. Le backend garde les identifiants sensibles en sécurité.
**Limitation de débit et contrôle** : Le backend vous permet de contrôler la fréquence des requêtes utilisateurs, d’implémenter l’authentification, et d’ajouter des logs pour suivre l’usage.
**Traitement des données** : Vous pourriez vouloir sauvegarder les conversations, filtrer du contenu inapproprié, ou combiner plusieurs services IA. Le backend est l’endroit où cette logique vit.
**L’architecture ressemble à un modèle client-serveur :**
- **Frontend** : couche interface utilisateur pour l’interaction
- **Backend API** : couche de traitement et de routage des requêtes
- **Service IA** : calcul externe et génération de réponses
- **Variables d’environnement** : stockage sécurisé de la configuration et des identifiants
### Comprendre le flux requête-réponse
Suivons ce qui se passe quand un utilisateur envoie un message :
```mermaid
sequenceDiagram
participant User as 👤 Utilisateur
participant Frontend as 🌐 Frontend
participant API as 🔧 Serveur FastAPI
participant AI as 🤖 Service IA
User->>Frontend: Tape "Bonjour IA !"
Frontend->>API: POST /hello {"message": "Bonjour IA !"}
Note over API: Valide la requête Ajoute une invite système
API->>AI: Envoie la requête formatée
AI->>API: Retourne la réponse IA
Note over API: Traite la réponse Enregistre la conversation
API->>Frontend: {"response": "Bonjour ! Comment puis-je aider ?"}
Frontend->>User: Affiche le message IA
```
**Comprendre chaque étape :**
1. **Interaction utilisateur** : la personne tape dans l’interface de chat
2. **Traitement frontend** : JavaScript capture l’entrée et la formate en JSON
3. **Validation API** : FastAPI valide automatiquement la requête avec les modèles Pydantic
4. **Intégration IA** : le backend ajoute le contexte (invite système) et appelle le service IA
5. **Gestion de la réponse** : l’API reçoit la réponse IA et peut la modifier si besoin
6. **Affichage frontend** : JavaScript affiche la réponse dans l’interface de chat
### Comprendre l’architecture API
```mermaid
sequenceDiagram
participant Frontend
participant FastAPI
participant AI Function
participant GitHub Models
Frontend->>FastAPI: POST /hello {"message": "Bonjour IA !"}
FastAPI->>AI Function: call_llm(message, system_prompt)
AI Function->>GitHub Models: requête API
GitHub Models->>AI Function: réponse IA
AI Function->>FastAPI: texte de réponse
FastAPI->>Frontend: {"response": "Bonjour ! Comment puis-je vous aider ?"}
```
```mermaid
flowchart TD
A[Saisie Utilisateur] --> B[Validation Frontend]
B --> C[Requête HTTP POST]
C --> D[Routeur FastAPI]
D --> E[Validation Pydantic]
E --> F[Appel Fonction IA]
F --> G[API Modèles GitHub]
G --> H[Traitement de la Réponse]
H --> I[Réponse JSON]
I --> J[Mise à jour Frontend]
subgraph "Couche de Sécurité"
K[Middleware CORS]
L[Variables d'Environnement]
M[Gestion des Erreurs]
end
D --> K
F --> L
H --> M
```
### Création de l’application FastAPI
Construisons notre API pas à pas. Créez un fichier nommé `api.py` avec le code FastAPI suivant :
```python
# api.py
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
from llm import call_llm
import logging
# Configurer la journalisation
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# Créer l'application FastAPI
app = FastAPI(
title="AI Chat API",
description="A high-performance API for AI-powered chat applications",
version="1.0.0"
)
# Configurer le CORS
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # Configurer correctement pour la production
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Modèles Pydantic pour la validation des requêtes/réponses
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:
# Extraire et valider le 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]}...")
# Appeler le service IA (note : call_llm devrait être asynchrone pour de meilleures performances)
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)
```
**Comprendre l’implémentation FastAPI :**
- **Imports** FastAPI pour les fonctionnalités modernes du framework web et Pydantic pour validation des données
- **Crée** la documentation API automatique (disponible à `/docs` quand le serveur tourne)
- **Active** le middleware CORS pour permettre les requêtes frontend provenant d’origines différentes
- **Définit** les modèles Pydantic pour validation et documentation automatiques des requêtes/réponses
- **Utilise** des endpoints async pour de meilleures performances lors de requêtes concurrentes
- **Implémente** des codes HTTP adéquats et gestion d’erreurs avec HTTPException
- **Inclut** un logging structuré pour monitoring et débogage
- **Fournit** un endpoint de vérification de l’état de santé pour surveiller le service
**Avantages clés de FastAPI par rapport aux frameworks traditionnels :**
- **Validation automatique** : les modèles Pydantic garantissent l’intégrité des données avant traitement
- **Docs interactives** : visitez `/docs` pour une documentation API autogénérée et testable
- **Sécurité de typage** : les annotations Python préviennent erreurs d’exécution et améliorent la qualité du code
- **Support async** : gérer plusieurs requêtes IA simultanément sans blocage
- **Performance** : traitement des requêtes nettement plus rapide pour des applications en temps réel
### Comprendre CORS : Le gardien de sécurité du web
CORS (Cross-Origin Resource Sharing) est comme un agent de sécurité dans un immeuble qui vérifie si les visiteurs ont le droit d’entrer. Comprenons pourquoi c’est important et comment cela affecte votre application.
#### Qu’est-ce que CORS et pourquoi existe-t-il ?
**Le problème** : Imaginez que n’importe quel site web puisse envoyer des requêtes au site de votre banque en votre nom, sans votre accord. Ce serait un cauchemar de sécurité ! Les navigateurs empêchent cela par défaut grâce à la « politique de même origine ».
**Politique de même origine** : Les navigateurs autorisent uniquement les pages web à faire des requêtes vers le même domaine, port, et protocole d’où elles ont été chargées.
**Analogie réelle** : C’est comme la sécurité d’un immeuble d’appartements – seuls les résidents (même origine) peuvent entrer par défaut. Si vous voulez laisser un ami (origine différente) visiter, vous devez dire explicitement à la sécurité que c’est OK.
#### CORS dans votre environnement de développement
Pendant le développement, votre frontend et backend tournent sur des ports différents :
- Frontend : `http://localhost:3000` (ou file:// si vous ouvrez le HTML directement)
- Backend : `http://localhost:5000`
Ce sont des « origines différentes » même s’ils sont sur le même ordinateur !
```python
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(__name__)
CORS(app) # Cela indique aux navigateurs : "Il est acceptable que d'autres origines fassent des requêtes à cette API"
```
**Ce que la configuration CORS fait en pratique :**
- **Ajoute** des en-têtes HTTP spéciaux dans les réponses API qui disent aux navigateurs « cette requête cross-origin est autorisée »
- **Gère** les requêtes « preflight » (les navigateurs vérifient parfois les permissions avant d’envoyer la requête réelle)
- **Évite** l’erreur redoutée « bloqué par la politique CORS » dans la console de votre navigateur
#### Sécurité CORS : développement vs production
```python
# 🚨 Développement : Autorise TOUS les origines (pratique mais non sécurisé)
CORS(app)
# ✅ Production : Autoriser uniquement votre domaine frontend spécifique
CORS(app, origins=["https://yourdomain.com", "https://www.yourdomain.com"])
# 🔒 Avancé : Différents origines pour différents environnements
if app.debug: # Mode développement
CORS(app, origins=["http://localhost:3000", "http://127.0.0.1:3000"])
else: # Mode production
CORS(app, origins=["https://yourdomain.com"])
```
**Pourquoi c’est important** : En développement, `CORS(app)` est comme laisser votre porte d’entrée ouverte – pratique mais pas sécurisé. En production, vous devez spécifier exactement quels sites web peuvent accéder à votre API.
#### Scénarios courants CORS et solutions
| Scénario | Problème | Solution |
|----------------------|---------------------------------|----------------------------------------|
| **Développement local** | Le frontend ne peut pas joindre le backend | Ajouter CORSMiddleware à FastAPI |
| **GitHub Pages + Heroku** | Frontend déployé ne peut pas joindre l’API | Ajouter l’URL GitHub Pages dans les origines CORS |
| **Domaine personnalisé** | Erreurs CORS en production | Mettre à jour les origines CORS pour correspondre à votre domaine |
| **Application mobile** | L’app ne peut pas joindre l’API web | Ajouter le domaine de l’app ou utiliser `*` avec précaution |
**Astuce pro** : Vous pouvez vérifier les en-têtes CORS dans les outils développeur de votre navigateur, onglet Réseau. Cherchez des en-têtes comme `Access-Control-Allow-Origin` dans la réponse.
### Gestion des erreurs et validation
Notez comment notre API inclut une gestion correcte des erreurs :
```python
# Valider que nous avons reçu un message
if not message:
return jsonify({"error": "Message field is required"}), 400
```
**Principes clés de validation :**
- **Vérifie** les champs obligatoires avant traitement des requêtes
- **Renvoie** des messages d’erreur clairs en format JSON
- **Utilise** des codes HTTP appropriés (400 pour requêtes incorrectes)
- **Fournit** un retour clair pour aider les développeurs frontend à déboguer
## Mise en place et lancement de votre backend
Maintenant que notre intégration IA et serveur FastAPI sont prêts, mettons tout en route. Le processus d’installation implique l’installation des dépendances Python, la configuration des variables d’environnement, et le lancement de votre serveur de développement.
### Configuration de l’environnement Python
Mettons en place votre environnement de développement Python. Les environnements virtuels fonctionnent comme l’approche compartimentée du Projet Manhattan – chaque projet a son espace isolé avec ses outils et dépendances spécifiques, évitant les conflits entre projets différents.
```bash
# Naviguez vers votre répertoire backend
cd backend
# Créez un environnement virtuel (comme créer une pièce propre pour votre projet)
python -m venv venv
# Activez-le (Linux/Mac)
source ./venv/bin/activate
# Sous Windows, utilisez :
# venv\Scripts\activate
# Installez les bons trucs
pip install openai fastapi uvicorn python-dotenv
```
**Ce que nous venons de faire :**
- **Créé** notre propre petit bubble Python où installer les packages sans affecter autre chose
- **Activé** cet environnement pour que le terminal utilise celui-ci spécifiquement
- **Installé** les essentiels : OpenAI pour la magie IA, FastAPI pour notre API web, Uvicorn pour le lancement, et python-dotenv pour la gestion sécurisée des secrets
**Dépendances clés expliquées :**
- **FastAPI** : framework web moderne et rapide avec documentation API automatique
- **Uvicorn** : serveur ASGI ultra rapide qui exécute les applications FastAPI
- **OpenAI** : bibliothèque officielle pour les modèles GitHub et intégration API OpenAI
- **python-dotenv** : chargement sécurisé des variables d’environnement depuis les fichiers .env
### Configuration de l’environnement : garder les secrets en sécurité
Avant de démarrer notre API, parlons d’une des leçons les plus importantes du développement web : comment garder vos secrets vraiment secrets. Les variables d’environnement fonctionnent comme un coffre-fort sécurisé accessible uniquement par votre application.
#### Qu’est-ce que les variables d’environnement ?
**Pensez aux variables d’environnement comme un coffre-fort** – vous y mettez vos objets précieux, et seuls vous (et votre app) avez la clé pour les sortir. Au lieu d’écrire des infos sensibles directement dans votre code (où littéralement tout le monde peut les voir), vous les stockez en sécurité dans l’environnement.
**Voici la différence :**
- **La mauvaise méthode** : écrire votre mot de passe sur un post-it collé à votre écran
- **La bonne méthode** : garder votre mot de passe dans un gestionnaire de mots de passe sécurisé auquel vous seul avez accès
#### Pourquoi les variables d’environnement comptent
```python
# 🚨 NE JAMAIS FAIRE CECI - Clé API visible par tous
client = OpenAI(
api_key="ghp_1234567890abcdef...", # N'importe qui peut la voler !
base_url="https://models.github.ai/inference"
)
# ✅ FAIRE CECI - Clé API stockée en toute sécurité
client = OpenAI(
api_key=os.environ["GITHUB_TOKEN"], # Seule votre application peut y accéder
base_url="https://models.github.ai/inference"
)
```
**Ce qui arrive quand vous codez en dur vos secrets :**
1. **Exposition dans le contrôle de version** : toute personne ayant accès à votre dépôt Git voit votre clé API
2. **Répertoires publics** : si vous poussez sur GitHub, votre clé est visible par Internet entier
3. **Partage en équipe** : les autres développeurs voient votre clé personnelle
4. **Failles de sécurité** : si quelqu’un vole votre clé, il peut utiliser vos crédits IA
#### Mise en place de votre fichier d’environnement
Créez un fichier `.env` dans votre répertoire backend. Ce fichier stocke vos secrets localement :
```bash
# Fichier .env - Ceci ne doit JAMAIS être commis dans Git
GITHUB_TOKEN=your_github_personal_access_token_here
FASTAPI_DEBUG=True
ENVIRONMENT=development
```
**Comprendre le fichier .env :**
- **Un secret par ligne** au format `CLÉ=valeur`
- **Pas d’espaces** autour du signe égal
- **Pas de guillemets** nécessaires autour des valeurs (en général)
- **Commentaires** commencent par `#`
#### Création de votre token d’accès personnel GitHub
Votre token GitHub est comme un mot de passe spécial qui donne à votre application la permission d’utiliser les services IA de GitHub :
**Création du token pas à pas :**
1. **Allez dans les paramètres GitHub** → Paramètres développeur → Tokens d’accès personnel → Tokens (classiques)
2. **Cliquez sur « Générer un nouveau token (classique) »**
3. **Configurez la date d’expiration** (30 jours pour test, plus long en production)
4. **Sélectionnez les scopes** : Cochez « repo » et toute autre permission nécessaire
5. **Générez le token** et copiez-le immédiatement (vous ne pourrez plus le voir !)
6. **Collez-le dans votre fichier .env**
```bash
# Exemple de ce à quoi ressemble votre jeton (c'est faux !)
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R
```
#### Chargement des variables d’environnement en Python
```python
import os
from dotenv import load_dotenv
# Charger les variables d'environnement à partir du fichier .env
load_dotenv()
# Vous pouvez désormais y accéder en toute sécurité
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"
)
```
**Ce que fait ce code :**
- **Charge** votre fichier .env et rend les variables disponibles dans Python
- **Vérifie** si le token requis existe (bonne gestion d’erreur !)
- **Lève** une erreur claire si le token manque
- **Utilise** le token en toute sécurité sans l’exposer dans le code
#### Sécurité Git : Le fichier .gitignore
Votre fichier `.gitignore` indique à Git quels fichiers ne jamais suivre ou uploader :
```bash
# .gitignore - Ajoutez ces lignes
.env
*.env
.env.local
.env.production
__pycache__/
venv/
.vscode/
```
**Pourquoi c’est crucial** : une fois `.env` ajouté à `.gitignore`, Git ignore votre fichier d’environnement, vous évitant de téléverser accidentellement vos secrets sur GitHub.
#### Environnements différents, secrets différents
Les applications professionnelles utilisent différentes clés API pour différents environnements :
```bash
# .env.developpement
GITHUB_TOKEN=your_development_token
DEBUG=True
# .env.production
GITHUB_TOKEN=your_production_token
DEBUG=False
```
**Pourquoi c’est important** : Vous ne voulez pas que vos expérimentations de développement impactent votre quota IA de production, et vous souhaitez différents niveaux de sécurité selon les environnements.
### Démarrage de votre serveur de développement : donner vie à votre FastAPI
Voici venu le moment excitant : lancer votre serveur de développement FastAPI et voir votre intégration IA prendre vie ! FastAPI utilise Uvicorn, un serveur ASGI ultra-rapide spécialement conçu pour les applications Python asynchrones.
#### Comprendre le processus de démarrage du serveur FastAPI
```bash
# Méthode 1 : Exécution directe en Python (avec rechargement automatique)
python api.py
# Méthode 2 : Utilisation directe de Uvicorn (plus de contrôle)
uvicorn api:app --host 0.0.0.0 --port 5000 --reload
```
Lorsque vous exécutez cette commande, voici ce qui se passe en coulisses :
**1. Python charge votre application FastAPI** :
- Importe toutes les bibliothèques requises (FastAPI, Pydantic, OpenAI, etc.)
- Charge les variables d’environnement depuis votre fichier `.env`
- Crée l’instance de l’application FastAPI avec documentation automatique
**2. Uvicorn configure le serveur ASGI** :
- Se lie au port 5000 avec des capacités de gestion asynchrone des requêtes
- Configure le routage des requêtes avec validation automatique
- Active le rechargement à chaud pour le développement (redémarrage lors de modifications)
- Génère une documentation interactive de l’API
**3. Le serveur commence à écouter** :
- Votre terminal affiche : `INFO: Uvicorn running on http://0.0.0.0:5000`
- Le serveur peut gérer plusieurs requêtes IA simultanément
- Votre API est prête avec une documentation automatique à `http://localhost:5000/docs`
#### Ce que vous devriez voir lorsque tout fonctionne
```bash
$ python api.py
INFO: Will watch for changes in these directories: ['/your/project/path']
INFO: Uvicorn running on http://0.0.0.0:5000 (Press CTRL+C to quit)
INFO: Started reloader process [12345] using WatchFiles
INFO: Started server process [12346]
INFO: Waiting for application startup.
INFO: Application startup complete.
```
**Comprendre la sortie FastAPI :**
- **Will watch for changes** : Rechargement automatique activé pour le développement
- **Uvicorn running** : Serveur ASGI haute performance est actif
- **Started reloader process** : Observateur de fichiers pour redémarrages automatiques
- **Application startup complete** : Application FastAPI initialisée avec succès
- **Interactive docs available** : Visitez `/docs` pour la documentation automatique de l’API
#### Tester votre FastAPI : plusieurs approches puissantes
FastAPI fournit plusieurs moyens pratiques pour tester votre API, y compris une documentation interactive automatique :
**Méthode 1 : Documentation interactive de l’API (recommandée)**
1. Ouvrez votre navigateur et allez sur `http://localhost:5000/docs`
2. Vous verrez Swagger UI avec tous vos endpoints documentés
3. Cliquez sur `/hello` → « Try it out » → Entrez un message de test → « Execute »
4. Voyez la réponse directement dans le navigateur avec une mise en forme adéquate
**Méthode 2 : Test simple via navigateur**
1. Allez sur `http://localhost:5000` pour le point d’entrée racine
2. Allez sur `http://localhost:5000/health` pour vérifier la santé du serveur
3. Cela confirme que votre serveur FastAPI fonctionne correctement
**Méthode 2 : Test en ligne de commande (avancé)**
```bash
# Test avec curl (si disponible)
curl -X POST http://localhost:5000/hello \
-H "Content-Type: application/json" \
-d '{"message": "Hello AI!"}'
# Réponse attendue :
# {"response": "Bonjour ! Je suis votre assistant IA. Comment puis-je vous aider aujourd'hui ?"}
```
**Méthode 3 : Script de test Python**
```python
# test_api.py - Créez ce fichier pour tester votre API
import requests
import json
# Tester le point de terminaison de l'API
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)
```
#### Résolution des problèmes courants au démarrage
| Message d’erreur | Signification | Comment réparer |
|------------------|---------------|-----------------|
| `ModuleNotFoundError: No module named 'fastapi'` | FastAPI non installé | Lancez `pip install fastapi uvicorn` dans votre environnement virtuel |
| `ModuleNotFoundError: No module named 'uvicorn'` | Serveur ASGI non installé | Lancez `pip install uvicorn` dans votre environnement virtuel |
| `KeyError: 'GITHUB_TOKEN'` | Variable d’environnement introuvable | Vérifiez votre fichier `.env` et l’appel à `load_dotenv()` |
| `Address already in use` | Le port 5000 est occupé | Tuez les autres processus utilisant le port 5000 ou changez de port |
| `ValidationError` | Les données de la requête ne correspondent pas au modèle Pydantic | Vérifiez que le format de votre requête correspond au schéma attendu |
| `HTTPException 422` | Entité non traitable | La validation de la requête a échoué, vérifiez `/docs` pour le format correct |
| `OpenAI API error` | Échec d’authentification au service IA | Vérifiez que votre token GitHub est correct et dispose des bonnes permissions |
#### Bonnes pratiques de développement
**Rechargement à chaud** : FastAPI avec Uvicorn fournit un rechargement automatique lorsque vous enregistrez des modifications dans vos fichiers Python. Cela signifie que vous pouvez modifier votre code et tester immédiatement sans redémarrage manuel.
```python
# Activer le rechargement à chaud explicitement
if __name__ == "__main__":
app.run(host="0.0.0.0", port=5000, debug=True) # debug=True active le rechargement à chaud
```
**Journalisation pour le développement** : Ajoutez des logs pour comprendre ce qui se passe :
```python
import logging
# Configurer la journalisation
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
```
**Pourquoi la journalisation est utile** : Pendant le développement, vous pouvez voir exactement quelles requêtes arrivent, comment l’IA répond et où les erreurs surviennent. Cela accélère grandement le débogage.
### Configuration pour GitHub Codespaces : développement cloud simplifié
GitHub Codespaces, c’est comme avoir un puissant ordinateur de développement dans le cloud accessible depuis n’importe quel navigateur. Si vous travaillez dans Codespaces, quelques étapes supplémentaires sont nécessaires pour rendre votre backend accessible à votre frontend.
#### Comprendre le réseau dans Codespaces
Dans un environnement de développement local, tout fonctionne sur la même machine :
- Backend : `http://localhost:5000`
- Frontend : `http://localhost:3000` (ou file://)
Dans Codespaces, votre environnement s’exécute sur les serveurs GitHub, donc « localhost » a un sens différent. GitHub crée automatiquement des URL publiques pour vos services, mais vous devez les configurer correctement.
#### Configuration étape par étape dans Codespaces
**1. Démarrez votre serveur backend** :
```bash
cd backend
python api.py
```
Vous verrez le message habituel de démarrage FastAPI/Uvicorn, mais remarquez qu’il s’exécute dans l’environnement Codespace.
**2. Configurez la visibilité du port** :
- Cherchez l’onglet « Ports » dans le panneau inférieur de VS Code
- Trouvez le port 5000 dans la liste
- Faites un clic droit sur le port 5000
- Sélectionnez « Port Visibility » → « Public »
**Pourquoi le rendre public ?** Par défaut, les ports Codespace sont privés (accessibles uniquement par vous). Le rendre public permet à votre frontend (qui tourne dans le navigateur) de communiquer avec votre backend.
**3. Récupérez votre URL publique** :
Après avoir rendu le port public, vous verrez une URL comme :
```
https://your-codespace-name-5000.app.github.dev
```
**4. Mettez à jour votre configuration frontend** :
```javascript
// Dans votre frontend app.js, mettez à jour le BASE_URL:
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
```
#### Comprendre les URLs Codespace
Les URLs Codespace suivent un modèle prédictible :
```
https://[codespace-name]-[port].app.github.dev
```
**Détail de la composition :**
- `codespace-name` : Identifiant unique de votre Codespace (généralement inclut votre nom d’utilisateur)
- `port` : Le numéro de port sur lequel votre service tourne (5000 pour notre app FastAPI)
- `app.github.dev` : Domaine GitHub pour les applications Codespace
#### Tester votre configuration Codespace
**1. Testez directement le backend** :
Ouvrez votre URL publique dans un nouvel onglet du navigateur. Vous devriez voir :
```
Welcome to the AI Chat API. Send POST requests to /hello with JSON payload containing 'message' field.
```
**2. Testez avec les outils développeurs du navigateur** :
```javascript
// Ouvrez la console du navigateur et testez votre 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 développement local
| Aspect | Développement local | GitHub Codespaces |
|--------|---------------------|-------------------|
| **Temps d’installation** | Plus long (installation Python, dépendances) | Instantané (environnement pré-configuré) |
| **Accès URL** | `http://localhost:5000` | `https://xyz-5000.app.github.dev` |
| **Configuration des ports** | Automatique | Manuelle (rendre les ports publics) |
| **Persistance des fichiers** | Machine locale | Répertoire GitHub |
| **Collaboration** | Partage d’environnement difficile | Partage facile du lien Codespace |
| **Dépendance internet** | Uniquement pour les appels API IA | Requise pour tout |
#### Conseils pour le développement dans Codespaces
**Variables d’environnement dans Codespaces** :
Votre fichier `.env` fonctionne de la même façon dans Codespaces, mais vous pouvez aussi définir des variables d’environnement directement dans le Codespace :
```bash
# Définir une variable d'environnement pour la session en cours
export GITHUB_TOKEN="your_token_here"
# Ou l'ajouter à votre .bashrc pour la persistance
echo 'export GITHUB_TOKEN="your_token_here"' >> ~/.bashrc
```
**Gestion des ports** :
- Codespaces détecte automatiquement lorsque votre application commence à écouter un port
- Vous pouvez rediriger plusieurs ports simultanément (utile si vous ajoutez une base de données plus tard)
- Les ports restent accessibles tant que votre Codespace est actif
**Workflow de développement** :
1. Faites des modifications dans VS Code
2. FastAPI se recharge automatiquement (grâce au mode reload d’Uvicorn)
3. Testez les modifications immédiatement via l’URL publique
4. Committez et poussez quand c’est prêt
> 💡 **Astuce pro** : Mettez en favori l’URL de votre backend Codespace pendant le développement. Comme les noms des Codespaces sont stables, l’URL ne changera pas tant que vous utilisez le même Codespace.
## Création de l’interface chat frontend : où les humains rencontrent l’IA
Nous allons maintenant construire l’interface utilisateur – la partie qui détermine comment les gens interagissent avec votre assistant IA. Comme pour le design de l’interface originale de l’iPhone, l’objectif est de rendre la technologie complexe intuitive et naturelle à utiliser.
### Comprendre l’architecture moderne du frontend
Notre interface chat sera ce que nous appelons une « application monopage » ou SPA. Au lieu de l’approche traditionnelle où chaque clic charge une nouvelle page, notre application se met à jour de façon fluide et instantanée :
**Sites web anciens** : Comme lire un livre physique – vous tournez des pages complètement nouvelles
**Notre application de chat** : Comme utiliser votre téléphone – tout coule et se met à jour sans rupture
```mermaid
graph TD
A[Utilisateur Tape un Message] --> B[JavaScript Capture l'Entrée]
B --> C[Valider & Formater les Données]
C --> D[Envoyer à l'API Backend]
D --> E[Afficher l'État de Chargement]
E --> F[Recevoir la Réponse de l'IA]
F --> G[Mettre à Jour l'Interface de Chat]
G --> H[Prêt pour le Message Suivant]
```
```mermaid
classDiagram
class ChatApp {
+messages: HTMLElement
+form: HTMLElement
+input: HTMLElement
+sendButton: HTMLElement
+BASE_URL: string
+API_ENDPOINT: string
+constructor()
+initializeEventListeners()
+handleSubmit(event)
+callAPI(message)
+appendMessage(text, role)
+escapeHtml(text)
+scrollToBottom()
+setLoading(isLoading)
}
ChatApp --> DOM : manipule
ChatApp --> FastAPI : envoie des requêtes
```
### Les trois piliers du développement frontend
Toute application frontend – des sites simples aux apps complexes comme Discord ou Slack – repose sur trois technologies fondamentales. Pensez-y comme à la base de tout ce que vous voyez et avec quoi vous interagissez sur le web :
**HTML (Structure)** : C’est votre fondation
- Décide quels éléments existent (boutons, zones de texte, conteneurs)
- Donne du sens au contenu (c’est un titre, c’est un formulaire, etc.)
- Crée la structure de base sur laquelle tout le reste s’appuie
**CSS (Présentation)** : C’est votre décorateur d’intérieur
- Rend tout joli (couleurs, polices, mises en page)
- Gère les différentes tailles d’écran (téléphone vs portable vs tablette)
- Crée des animations fluides et des retours visuels
**JavaScript (Comportement)** : C’est votre cerveau
- Réagit aux actions utilisateurs (clics, saisies, défilement)
- Communique avec votre backend et met à jour la page
- Rend tout interactif et dynamique
**Pensez-y comme un projet architectural :**
- **HTML** : Le plan structurel (définition des espaces et relations)
- **CSS** : Le design esthétique et environnemental (style visuel et expérience utilisateur)
- **JavaScript** : Les systèmes mécaniques (fonctionnalité et interactivité)
### Pourquoi l’architecture JavaScript moderne est importante
Notre application chat utilisera des patterns JavaScript modernes que vous rencontrerez dans des applications professionnelles. Comprendre ces concepts vous aidera à progresser en tant que développeur :
**Architecture basée sur les classes** : Nous organiserons notre code en classes, ce qui revient à créer des plans pour des objets
**Async/Await** : Manière moderne de gérer les opérations longues (comme les appels API)
**Programmation événementielle** : Notre app réagit aux actions de l’utilisateur (clics, pressions de touches) au lieu de tourner en boucle
**Manipulation du DOM** : Mise à jour dynamique du contenu de la page web selon les interactions utilisateur et les réponses API
### Configuration de la structure du projet
Créez un répertoire frontend avec cette structure organisée :
```text
frontend/
├── index.html # Main HTML structure
├── app.js # JavaScript functionality
└── styles.css # Visual styling
```
**Comprendre l’architecture :**
- **Sépare** les préoccupations entre structure (HTML), comportement (JavaScript) et présentation (CSS)
- **Maintient** une structure de fichiers simple facile à naviguer et modifier
- **Suit** les meilleures pratiques web pour l’organisation et la maintenabilité
### Construire la fondation HTML : structure sémantique pour l’accessibilité
Commençons par la structure HTML. Le développement web moderne met l’accent sur le « HTML sémantique » – utiliser des éléments HTML qui décrivent clairement leur rôle, pas seulement leur apparence. Cela rend votre application accessible aux lecteurs d’écran, moteurs de recherche et autres outils.
**Pourquoi le HTML sémantique est important** : Imaginez décrire votre application de chat à quelqu’un au téléphone. Vous diriez « il y a un en-tête avec le titre, une zone principale où apparaissent les conversations, et un formulaire en bas pour taper les messages ». Le HTML sémantique utilise des éléments qui correspondent à cette description naturelle.
Créez `index.html` avec ce balisage structuré avec soin :
```html
AI Chat Assistant
AI Chat Assistant
Ask me anything!
```
**Comprendre chaque élément HTML et son rôle :**
#### Structure du document
- **``** : Indique au navigateur qu’il s’agit de HTML5 moderne
- **``** : Spécifie la langue de la page pour les lecteurs d’écran et outils de traduction
- **``** : Assure un encodage de caractères correct pour le texte international
- **``** : Rend la page responsive en contrôlant le zoom et l’échelle
#### Éléments sémantiques
- **``** : Identifie clairement la section supérieure avec titre et description
- **``** : Désigne la zone de contenu principal (où ont lieu les conversations)
- **`