Intelligence artificielle · Chapitre 36 · Cours 11

Accéder à un modèle local par API

Vous savez désormais installer un modèle et discuter avec lui. L’étape suivante consiste à permettre à un programme de lui envoyer des instructions automatiquement. Découvrez les API locales, les requêtes HTTP, le format JSON et les endpoints proposés par Ollama et LM Studio, puis réalisez vos premières communications avec PowerShell et Python.

À la fin de ce cours, vous saurez :

  • Expliquer ce qu’est une API et son intérêt pour une IA locale.
  • Comprendre les rôles du client, du serveur et du modèle.
  • Identifier une adresse locale et un endpoint.
  • Distinguer les méthodes HTTP GET et POST.
  • Lire et construire un document JSON simple.
  • Vérifier le fonctionnement de l’API Ollama.
  • Envoyer une requête avec PowerShell.
  • Utiliser les endpoints de génération et de conversation.
  • Interroger un modèle local avec Python.
  • Comprendre les réponses en streaming.
  • Utiliser une API compatible OpenAI proposée par un serveur local.
  • Diagnostiquer les erreurs et protéger l’accès au service.
Prérequis

Ollama ou LM Studio doit être installé. Un modèle compatible doit être disponible localement. Une connaissance élémentaire des fichiers, des commandes et des notions client-serveur est utile, mais les principes nécessaires sont expliqués progressivement.

1. Qu’est-ce qu’une API ?

Une API, ou Application Programming Interface, est une interface permettant à des logiciels de communiquer selon des règles définies.

Dans le cas d’une intelligence artificielle locale, une API permet à un programme d’envoyer une demande à un modèle sans passer nécessairement par une interface de conversation graphique.

Par exemple, une application peut envoyer un texte à un modèle local pour obtenir :

  • Une reformulation.
  • Une synthèse.
  • Une classification.
  • Une extraction d’informations.
  • Une proposition de réponse.
  • Une analyse de texte.
Exemple concret

Un programme de gestion reçoit une demande client. Il transmet le texte à une IA locale par API, puis récupère une proposition de catégorie : facturation, assistance ou autre.

Le programme peut ensuite afficher la catégorie proposée à un utilisateur pour validation.

2. Comprendre l’architecture client-serveur

Une API locale repose généralement sur une communication entre un client et un serveur.

APPLICATION CLIENT | | Requête HTTP | Texte + paramètres v SERVEUR API LOCAL | | Prépare la demande v MOTEUR D’INFÉRENCE | | Exécute le modèle v MODÈLE LOCAL | | Génère la réponse v SERVEUR API | | Réponse HTTP / JSON v APPLICATION CLIENT

2.1. Le client

Le client est le logiciel qui envoie une demande.

Il peut s’agir d’un script Python, d’une application bureautique, d’un outil d’automatisation ou d’un programme développé sur mesure.

2.2. Le serveur

Le serveur reçoit les requêtes, vérifie leur format, appelle le moteur d’inférence et renvoie les résultats.

2.3. Le modèle

Le modèle effectue la génération. Il n’est pas nécessairement directement accessible par le client : le serveur assure l’intermédiaire.

Point essentiel

Une API locale n’est pas une intelligence artificielle supplémentaire. C’est un moyen de communiquer avec un modèle déjà installé et exécuté par un moteur compatible.

3. Comprendre localhost et les ports

Un service local est souvent accessible grâce à une adresse utilisant localhost ou l’adresse IP de bouclage 127.0.0.1.

Ces adresses désignent la machine elle-même dans le contexte réseau concerné.

3.1. Exemple avec Ollama

http://localhost:11434

Dans une installation standard, Ollama utilise généralement le port TCP 11434 pour son serveur HTTP.

3.2. Décomposer l’adresse

ÉlémentSignification
http://Protocole de communication HTTP.
localhostNom désignant l’ordinateur local.
11434Port utilisé par le service dans la configuration habituelle d’Ollama.

3.3. Exemple avec LM Studio

Lorsqu’il est activé, le serveur local de LM Studio peut être accessible à une adresse comme :

http://localhost:1234

Le port 1234 est un port couramment proposé par LM Studio. Il peut être modifié dans la configuration.

Attention

Un port est un point d’accès réseau, pas un numéro de modèle. Si le serveur utilise un autre port, les requêtes doivent employer le port réellement configuré.

4. Comprendre les endpoints

Un endpoint est un point d’accès précis d’une API.

Il correspond généralement à une adresse associée à une opération.

4.1. Exemple

http://localhost:11434/api/generate

Cette adresse combine :

  • L’adresse du serveur local.
  • Le port utilisé.
  • Le chemin /api/generate.

4.2. Quelques endpoints Ollama

EndpointUtilisation
GET /api/tagsConsulter les modèles locaux.
POST /api/generateProduire une réponse à partir d’un prompt.
POST /api/chatEnvoyer une conversation structurée en messages.
POST /api/showConsulter les informations d’un modèle.
GET /api/psConsulter les modèles chargés.

Les endpoints disponibles et leurs paramètres doivent être vérifiés dans la documentation correspondant à la version installée.

5. Comprendre les méthodes HTTP

HTTP définit différentes méthodes permettant d’indiquer l’opération demandée au serveur.

5.1. GET

La méthode GET sert généralement à récupérer des informations.

Exemple :

GET /api/tags

Cette opération permet de demander la liste des modèles disponibles localement.

5.2. POST

La méthode POST permet notamment d’envoyer des données à un endpoint.

Exemple :

POST /api/generate

Le corps de la requête peut contenir le nom du modèle, l’instruction et des paramètres.

5.3. Autres méthodes

PUT, PATCH et DELETE existent également dans HTTP, mais elles ne sont pas nécessaires pour les premières manipulations de ce cours.

Repère

GET est généralement utilisé pour consulter une ressource. POST est souvent utilisé pour transmettre des données ou déclencher un traitement. La méthode attendue dépend de chaque endpoint.

6. Comprendre le format JSON

JSON signifie JavaScript Object Notation.

Il s’agit d’un format textuel structuré couramment utilisé pour échanger des données entre applications.

6.1. Exemple simple

{ « nom »: « Alice », « age »: 30, « actif »: true }

Dans cet exemple :

  • nom est une clé associée à une chaîne de caractères.
  • age est associé à un nombre.
  • actif est associé à une valeur booléenne.

6.2. Règles importantes

  • Les clés doivent être placées entre guillemets doubles.
  • Les chaînes de caractères utilisent également des guillemets doubles.
  • Les éléments sont séparés par des virgules.
  • Il ne faut pas ajouter de virgule après le dernier élément.
  • Les valeurs booléennes s’écrivent true et false.
  • Les objets utilisent des accolades et les tableaux des crochets.

6.3. Exemple JSON pour une IA

{ « model »: « gemma3:1b », « prompt »: « Explique ce qu’est un CPU. », « stream »: false }

Ce document contient le modèle à utiliser, l’instruction et un paramètre indiquant que la réponse doit être renvoyée sans streaming.

7. Préparer Ollama pour les appels API

Pour communiquer avec Ollama, son service HTTP doit être accessible.

7.1. Vérifier l’installation

Ouvrir PowerShell ou un terminal et saisir :

ollama –version

Une information de version doit apparaître si la commande est correctement installée et accessible.

7.2. Vérifier les modèles

ollama list

Le modèle utilisé dans les exemples doit apparaître dans la liste.

Si nécessaire :

ollama pull gemma3:1b

7.3. Vérifier le service

Selon le système et le mode d’installation, Ollama peut démarrer automatiquement en arrière-plan.

Dans une installation manuelle, le serveur peut être lancé avec :

ollama serve

Il ne faut pas lancer une seconde instance si le service est déjà actif sur le même port.

7.4. Tester la disponibilité

Dans un navigateur, ouvrir :

http://localhost:11434

Lorsque le serveur est accessible, il peut afficher un message indiquant qu’Ollama fonctionne.

Ce test ne confirme pas à lui seul qu’un modèle est téléchargé ou prêt à générer une réponse.

8. Première requête API avec PowerShell

PowerShell permet d’envoyer des requêtes HTTP sans installer de bibliothèque Python.

Cette première manipulation utilise Invoke-RestMethod.

Étape 1 — Ouvrir PowerShell

Ouvrir PowerShell sur l’ordinateur où Ollama est installé.

Étape 2 — Consulter les modèles locaux

Invoke-RestMethod ` -Uri « http://localhost:11434/api/tags » ` -Method Get

Le caractère accent grave situé en fin de ligne permet de poursuivre la commande sur la ligne suivante dans PowerShell.

Une réponse structurée contenant les modèles disponibles doit être retournée.

Étape 3 — Préparer la demande

$body = @{ model = « gemma3:1b » prompt = « Explique ce qu’est une API. » stream = $false } | ConvertTo-Json

Cette commande construit un objet PowerShell puis le convertit en JSON.

Étape 4 — Envoyer la requête

$result = Invoke-RestMethod ` -Uri « http://localhost:11434/api/generate » ` -Method Post ` -ContentType « application/json; charset=utf-8 » ` -Body $body $result.response

La propriété response contient le texte généré par le modèle dans la réponse habituelle de cet endpoint.

Résultat attendu

PowerShell envoie une instruction au serveur Ollama local et affiche le texte produit par le modèle, sans utiliser l’interface interactive de conversation.

9. Comprendre la requête envoyée

Reprenons le corps JSON de la demande :

{ « model »: « gemma3:1b », « prompt »: « Explique ce qu’est une API. », « stream »: false }
ChampFonction
modelIdentifie le modèle à utiliser.
promptContient l’instruction transmise.
streamIndique si la réponse doit être diffusée progressivement.

Les champs supplémentaires disponibles dépendent de l’endpoint.

10. Lire la réponse d’Ollama

Lorsque stream vaut false, l’endpoint /api/generate retourne généralement un objet JSON unique.

Exemple simplifié et fictif :

{ « model »: « gemma3:1b », « response »: « Une API permet à deux logiciels de communiquer. », « done »: true }

La réponse réelle peut contenir davantage de champs.

10.1. Les champs principaux

  • model : identifiant du modèle.
  • response : texte généré.
  • done : indicateur de fin de génération.

10.2. Les métadonnées

Selon l’endpoint et la version, Ollama peut également fournir des durées de traitement et des compteurs de tokens.

Ces informations sont utiles pour mesurer les performances.

11. Utiliser l’endpoint de conversation

L’endpoint /api/chat est conçu pour recevoir des messages structurés par rôle.

Il permet de transmettre explicitement une conversation.

11.1. Exemple JSON

{ « model »: « gemma3:1b », « messages »: [ { « role »: « system », « content »: « Réponds en français. » }, { « role »: « user », « content »: « Explique ce qu’est une adresse IP. » } ], « stream »: false }

11.2. Les rôles

RôleSignification
systemInstructions générales de comportement.
userMessage de l’utilisateur.
assistantRéponse précédente du modèle.

11.3. Requête PowerShell

$body = @{ model = « gemma3:1b » messages = @( @{ role = « system » content = « Réponds en français. » }, @{ role = « user » content = « Explique ce qu’est une adresse IP. » } ) stream = $false } | ConvertTo-Json -Depth 5 $result = Invoke-RestMethod ` -Uri « http://localhost:11434/api/chat » ` -Method Post ` -ContentType « application/json; charset=utf-8 » ` -Body $body $result.message.content

Dans la réponse habituelle de cet endpoint, le texte généré est accessible dans message.content.

12. Conserver le contexte d’une conversation par API

Un point important distingue l’utilisation d’une API d’une interface graphique.

Avec une API de conversation sans gestion automatique de session, le programme client doit généralement renvoyer les messages nécessaires à chaque nouvelle requête.

12.1. Premier échange

[ { « role »: « user », « content »: « Explique ce qu’est un routeur. » } ]

12.2. Deuxième échange

[ { « role »: « user », « content »: « Explique ce qu’est un routeur. » }, { « role »: « assistant », « content »: « Un routeur relie des réseaux et transmet des paquets selon les informations de routage. » }, { « role »: « user », « content »: « Donne un exemple dans une maison. » } ]

Le second appel inclut les messages précédents pour conserver leur contexte.

Attention

Le modèle ne mémorise pas automatiquement toutes les conversations entre deux appels API indépendants. Le programme doit gérer les messages, leur conservation et les limites de contexte.

13. Comprendre le streaming

Le streaming permet de recevoir une génération progressivement, plutôt que d’attendre la réponse complète.

13.1. Sans streaming

« stream »: false

Le client attend une réponse complète.

13.2. Avec streaming

« stream »: true

Le serveur transmet plusieurs fragments au fur et à mesure de la génération.

Avec l’API native d’Ollama, les fragments sont généralement transmis sous forme de lignes JSON successives.

13.3. Exemple conceptuel

{« response »: »Une « , »done »:false} {« response »: »API « , »done »:false} {« response »: »permet… », »done »:false} {« response »: » », »done »:true}

Il s’agit d’une illustration simplifiée, pas d’une réponse complète reproduisant tous les champs réels.

13.4. Pourquoi utiliser le streaming ?

  • Afficher une réponse progressivement.
  • Réduire le délai perçu avant le premier texte.
  • Améliorer l’expérience utilisateur.
  • Traiter certains fragments au fur et à mesure.

Le streaming ne garantit pas une augmentation de la vitesse totale de génération.

14. Première requête avec Python

Python permet de créer des programmes capables d’interroger automatiquement une API locale.

Pour cette première démonstration, nous utiliserons uniquement la bibliothèque standard de Python.

14.1. Vérifier Python

Dans un terminal :

python –version

Selon le système, la commande peut être python3 --version.

14.2. Créer un fichier

Créer un fichier nommé :

test_ollama.py

14.3. Écrire le programme

import json import urllib.request url = « http://127.0.0.1:11434/api/generate » donnees = { « model »: « gemma3:1b », « prompt »: « Explique ce qu’est un réseau local. », « stream »: False } corps = json.dumps(donnees).encode(« utf-8 ») requete = urllib.request.Request( url, data=corps, headers={ « Content-Type »: « application/json » }, method= »POST » ) with urllib.request.urlopen( requete, timeout=120 ) as reponse: resultat = json.load(reponse) print(resultat[« response »])

14.4. Exécuter le programme

Dans le dossier contenant le fichier :

python test_ollama.py

Sur certains systèmes :

python3 test_ollama.py

14.5. Résultat attendu

Le programme envoie une instruction au modèle local puis affiche la réponse générée.

Avantage de cette méthode

Le programme fonctionne sans bibliothèque Python tierce. Il utilise les outils HTTP et JSON intégrés à Python.

15. Comprendre le programme Python

Examinons les principales étapes.

15.1. Importer les modules

import json import urllib.request

Le module json permet de convertir des données Python en JSON et inversement.

urllib.request permet d’effectuer des requêtes HTTP.

15.2. Définir l’adresse

url = « http://127.0.0.1:11434/api/generate »

Cette adresse désigne l’endpoint local de génération d’Ollama.

15.3. Construire les données

donnees = { « model »: « gemma3:1b », « prompt »: « Explique ce qu’est un réseau local. », « stream »: False }

En Python, False est une valeur booléenne.

Lors de la conversion en JSON, elle devient false.

15.4. Convertir en JSON

corps = json.dumps(donnees).encode(« utf-8 »)

Le dictionnaire Python est converti en texte JSON puis encodé en octets UTF-8.

15.5. Envoyer la requête

urlopen ouvre la connexion HTTP et attend la réponse du serveur.

15.6. Lire le résultat

resultat = json.load(reponse)

La réponse JSON est convertie en objet Python.

15.7. Afficher le texte

print(resultat[« response »])

Cette instruction affiche la valeur associée à la clé response.

16. Ajouter une gestion des erreurs

Un programme doit prévoir les cas où le serveur est indisponible, où le modèle est introuvable ou où la requête est incorrecte.

Voici une version simplifiée avec gestion des principales erreurs réseau et HTTP.

import json import urllib.request import urllib.error url = « http://127.0.0.1:11434/api/generate » donnees = { « model »: « gemma3:1b », « prompt »: « Explique ce qu’est un pare-feu. », « stream »: False } corps = json.dumps(donnees).encode(« utf-8 ») requete = urllib.request.Request( url, data=corps, headers={ « Content-Type »: « application/json » }, method= »POST » ) try: with urllib.request.urlopen( requete, timeout=120 ) as reponse: resultat = json.load(reponse) print(resultat[« response »]) except urllib.error.HTTPError as erreur: print(« Erreur HTTP : », erreur.code) except urllib.error.URLError as erreur: print(« Connexion impossible : », erreur.reason) except TimeoutError: print(« Le serveur met trop de temps à répondre. ») except (ValueError, KeyError) as erreur: print(« Réponse inattendue : », erreur)

Ce programme traite plusieurs erreurs courantes, sans couvrir tous les scénarios possibles.

17. Comprendre les codes HTTP

Une API utilise des codes de statut HTTP pour indiquer le résultat du traitement de la requête.

CodeSignification généraleAction possible
200 Requête traitée avec succès. Lire la réponse.
400 Requête incorrecte. Vérifier le JSON et les paramètres.
401 Authentification nécessaire ou invalide. Vérifier les mécanismes d’accès lorsqu’ils existent.
403 Accès refusé. Vérifier les autorisations.
404 Ressource introuvable. Vérifier l’endpoint ou le modèle demandé.
500 Erreur interne du serveur. Consulter les journaux et l’état du service.
503 Service indisponible. Vérifier la disponibilité et la charge.

Ces significations sont générales. Une API donnée peut retourner des détails complémentaires permettant d’identifier précisément la cause.

18. Utiliser LM Studio comme serveur API

LM Studio peut proposer un serveur HTTP local permettant à d’autres applications de communiquer avec les modèles chargés.

Cette fonction est distincte de l’interface de conversation graphique.

18.1. Préparer le modèle

  1. Ouvrir LM Studio.
  2. Vérifier qu’un modèle compatible est téléchargé.
  3. Accéder à la fonctionnalité de serveur local ou de développement.
  4. Charger le modèle si nécessaire.
  5. Activer le serveur HTTP local.

Les intitulés exacts des menus dépendent de la version installée.

18.2. Vérifier l’adresse

Une configuration courante utilise :

http://localhost:1234

Vérifier le port réellement indiqué par LM Studio.

18.3. Comprendre la compatibilité OpenAI

LM Studio propose des endpoints compatibles avec certaines conventions de l’API OpenAI.

Cette compatibilité permet à certains clients de communiquer avec un serveur local en modifiant l’adresse de base.

Elle ne garantit pas que toutes les fonctionnalités, tous les paramètres ou tous les modèles soient pris en charge à l’identique.

19. Première requête vers LM Studio

Pour cet exemple, le serveur LM Studio doit être actif et un modèle doit être disponible.

19.1. Lister les modèles

Depuis PowerShell :

Invoke-RestMethod ` -Uri « http://localhost:1234/v1/models » ` -Method Get

La réponse permet d’identifier les modèles exposés par le serveur.

19.2. Repérer l’identifiant

Noter l’identifiant exact du modèle à utiliser.

Il ne faut pas supposer que son identifiant est identique à celui employé dans Ollama.

19.3. Envoyer une conversation

Remplacer IDENTIFIANT_DU_MODELE par la valeur réellement retournée.

$body = @{ model = « IDENTIFIANT_DU_MODELE » messages = @( @{ role = « user » content = « Explique ce qu’est une API locale. » } ) temperature = 0.3 stream = $false } | ConvertTo-Json -Depth 5 $result = Invoke-RestMethod ` -Uri « http://localhost:1234/v1/chat/completions » ` -Method Post ` -ContentType « application/json; charset=utf-8 » ` -Body $body $result.choices[0].message.content

Cette requête utilise le format habituel d’un endpoint de conversation compatible OpenAI.

Différence importante

Ollama possède une API native utilisant notamment /api/chat. LM Studio peut exposer un endpoint compatible OpenAI utilisant /v1/chat/completions. Le format des réponses n’est donc pas identique.

20. Comparer les API Ollama et LM Studio

CaractéristiqueOllama natifLM Studio compatible OpenAI
Adresse habituelle localhost:11434 localhost:1234
Conversation /api/chat /v1/chat/completions
Liste des modèles /api/tags /v1/models
Champ principal de la requête messages messages
Texte de réponse message.content choices[0].message.content
Streaming Fragments JSON natifs. Généralement flux compatible avec les conventions OpenAI.

Ollama peut également proposer des endpoints de compatibilité OpenAI. Ce tableau compare volontairement son API native à l’interface compatible OpenAI de LM Studio.

21. Comprendre la différence entre API native et API compatible

Une API native est conçue autour des conventions propres à un logiciel.

Une API compatible reprend tout ou partie du format d’une autre interface pour faciliter l’intégration.

21.1. Exemple

Une application sait envoyer des requêtes au format /v1/chat/completions.

Si un serveur local propose un endpoint compatible, cette application peut parfois être adaptée simplement en modifiant :

  • L’adresse du serveur.
  • Le nom du modèle.
  • Les paramètres de connexion.

21.2. Limites

Les différences peuvent concerner :

  • Les modèles disponibles.
  • Les paramètres acceptés.
  • Le streaming.
  • Les outils et fonctions avancées.
  • La gestion des erreurs.
  • Les formats de réponse.
À retenir

Compatible ne signifie pas strictement identique. Une intégration doit toujours être testée avec le serveur et le modèle réellement utilisés.

22. Ajouter des paramètres de génération

Les API permettent généralement de transmettre certains paramètres influençant la génération.

22.1. Exemple avec Ollama

{ « model »: « gemma3:1b », « prompt »: « Propose trois titres d’article. », « stream »: false, « options »: { « temperature »: 0.4, « num_predict »: 150 } }

Dans l’API native d’Ollama, plusieurs paramètres de génération sont transmis dans l’objet options.

22.2. Comprendre les paramètres

  • temperature : influence l’échantillonnage.
  • num_predict : limite le nombre de tokens générés selon les conventions d’Ollama.

22.3. Bonnes pratiques

Pour comparer les effets d’un paramètre, conserver la même instruction et modifier une seule valeur à la fois.

23. Mesurer les performances d’une requête API

Les appels API peuvent fournir des informations permettant d’analyser les performances.

Il faut distinguer le temps total, le temps de chargement et le temps de génération.

23.1. Mesure du temps total dans PowerShell

$mesure = Measure-Command { $result = Invoke-RestMethod ` -Uri « http://localhost:11434/api/generate » ` -Method Post ` -ContentType « application/json » ` -Body ‘{« model »: »gemma3:1b », »prompt »: »Bonjour », »stream »:false}’ } $mesure.TotalSeconds

Cette mesure inclut le temps nécessaire à l’appel HTTP et à son traitement, y compris le chargement éventuel du modèle.

23.2. Calculer une vitesse moyenne

Si un modèle génère 300 tokens en 25 secondes :

300 / 25 = 12 tokens/seconde

Cette vitesse représente une moyenne sur la durée de génération considérée.

23.3. Éviter les comparaisons trompeuses

Pour comparer deux essais, vérifier que les modèles sont dans des conditions similaires : état de chargement, longueur du prompt, paramètres et charge de l’ordinateur.

24. Sécuriser une API locale

Une API locale peut devenir un point d’entrée vers les ressources de l’ordinateur.

Elle doit être configurée avec prudence.

24.1. Écouter uniquement sur l’interface locale

Pour un usage individuel, privilégier une configuration limitée à l’adresse de bouclage.

Cette restriction évite qu’un autre ordinateur du réseau puisse accéder directement au service via une interface réseau externe.

24.2. Ne pas exposer le port sur Internet

Éviter toute redirection de port ou exposition publique sans architecture de sécurité appropriée.

24.3. Comprendre l’authentification

Certains serveurs locaux ne demandent pas d’authentification dans leur configuration de base.

Cette simplicité est adaptée à certains usages locaux, mais ne constitue pas une protection suffisante pour une exposition réseau.

24.4. Vérifier les applications clientes

Une application ayant accès à l’API peut lui transmettre des informations.

Il faut donc contrôler les programmes autorisés à communiquer avec le service.

24.5. Limiter les données

Éviter d’envoyer des informations confidentielles lorsqu’elles ne sont pas nécessaires.

24.6. Protéger les journaux

Les requêtes, les erreurs et les traces peuvent contenir des données sensibles selon la configuration.

Risque important

Une API accessible sur localhost n’est pas automatiquement protégée contre tous les programmes exécutés sur l’ordinateur. La sécurité dépend également du système, des applications clientes et des permissions.

25. Diagnostiquer les problèmes courants

ProblèmeCause possibleVérification
Connexion refusée. Serveur arrêté ou mauvais port. Vérifier le service et l’adresse.
Modèle introuvable. Identifiant incorrect ou modèle absent. Consulter la liste des modèles.
Erreur 400. JSON invalide ou paramètres incorrects. Vérifier la structure et les champs.
Erreur 404. Endpoint ou ressource indisponible. Contrôler le chemin demandé.
Réponse très lente. Modèle volumineux ou ressources limitées. Observer la mémoire et le temps de génération.
Réponse vide. Format de réponse inattendu ou génération interrompue. Examiner l’objet JSON complet.
Texte incomplet. Limite de tokens ou interruption. Vérifier les paramètres et les indicateurs de fin.
Contexte perdu. Messages précédents non transmis. Renvoyer l’historique utile.
Programme bloqué. Requête longue ou absence de délai maximal. Définir un timeout adapté.

26. Étude de cas — Classer des demandes avec une IA locale

Une petite organisation souhaite automatiser une première classification de messages reçus.

Elle distingue trois catégories :

  • Facturation : questions concernant les factures et paiements.
  • Assistance : problèmes techniques et demandes d’aide.
  • Autre : demandes ne relevant pas des deux premières catégories.

Un modèle local doit proposer une catégorie à partir du texte d’une demande.

26.1. Exemple de message

Bonjour, Je ne parviens plus à accéder à mon espace client depuis hier. Pouvez-vous m’aider ?

26.2. Instruction transmise au modèle

Classe le message suivant dans une seule catégorie : – Facturation – Assistance – Autre Réponds uniquement avec le nom de la catégorie. Message : « Je ne parviens plus à accéder à mon espace client. »

La catégorie attendue est Assistance.

26.3. Exemple de requête JSON

{ « model »: « gemma3:1b », « prompt »: « Classe le message dans Facturation, Assistance ou Autre. Réponds uniquement par la catégorie. Message : Je ne parviens plus à accéder à mon espace client. », « stream »: false }

26.4. Contrôle du résultat

Le programme ne doit pas considérer la réponse comme nécessairement correcte.

Il doit notamment vérifier :

  • Que la catégorie retournée est autorisée.
  • Que la réponse n’est pas vide.
  • Qu’aucune catégorie supplémentaire n’a été inventée.
  • Que les messages ambigus peuvent être examinés manuellement.

26.5. Questions

  1. Pourquoi utiliser une API plutôt qu’une interface graphique ?
  2. Quel endpoint Ollama peut être utilisé ?
  3. Quelle méthode HTTP faut-il employer ?
  4. Pourquoi faut-il vérifier la catégorie retournée ?
  5. Comment traiter un message ambigu ?
  6. Quelles précautions de confidentialité faut-il prendre ?
Afficher la correction détaillée

1. Intérêt de l’API

Elle permet au programme de transmettre automatiquement les messages au modèle et de récupérer les résultats sans intervention manuelle à chaque requête.

2. Endpoint

POST /api/generate convient à cet exemple de classification simple.

3. Méthode

POST, car le client transmet un corps JSON contenant les données de la demande.

4. Validation

Le modèle peut produire une catégorie incorrecte ou une réponse qui ne respecte pas le format. Le programme doit donc contrôler les valeurs retournées.

5. Message ambigu

Le programme peut signaler le cas pour une vérification humaine, au lieu de prendre automatiquement une décision.

6. Confidentialité

Il faut limiter les données transmises, contrôler les applications ayant accès au service et éviter toute exposition réseau non protégée.

27. Mise en pratique guidée

Cette activité permet de vérifier que vous savez communiquer avec un modèle local par API.

1
Préparer l’environnement

Vérifier qu’Ollama est installé et qu’un modèle compatible est disponible.

2
Tester le serveur

Vérifier que l’API répond sur l’adresse locale configurée.

3
Consulter les modèles

Effectuer une requête GET vers /api/tags.

4
Construire un JSON

Définir le modèle, l’instruction et stream: false.

5
Envoyer la requête

Utiliser PowerShell ou Python pour interroger /api/generate.

6
Lire la réponse

Extraire le texte généré et vérifier qu’il correspond à la demande.

7
Tester une erreur

Essayer volontairement un identifiant de modèle inexistant et observer le résultat.

8
Documenter les résultats

Noter les commandes, les erreurs rencontrées et les solutions appliquées.

Fiche de résultat

Système d’exploitation : Logiciel : Version : Modèle : Identifiant exact : Adresse du serveur : Port : Endpoint : Méthode HTTP : Format du corps : Requête réussie : Oui / Non Code HTTP observé : Texte retourné : Temps de réponse : Erreur testée : Solution appliquée : Précautions de sécurité :

28. Questions fréquentes

Une API locale nécessite-t-elle Internet ?

Non, si le modèle, le moteur et les composants nécessaires sont installés localement et que l’application n’utilise aucun service distant.

Quelle différence entre localhost et 127.0.0.1 ?

localhost est un nom généralement résolu vers une adresse de bouclage. 127.0.0.1 est une adresse IPv4 de bouclage. Selon le système, localhost peut également être associé à IPv6.

Faut-il connaître Python pour utiliser une API locale ?

Non. Des outils comme PowerShell permettent d’effectuer des requêtes HTTP. Python devient utile pour créer des automatisations et des applications.

Pourquoi utiliser JSON ?

JSON permet de représenter des données structurées dans un format largement pris en charge par les logiciels.

Peut-on utiliser plusieurs modèles avec la même API ?

Oui, si le serveur prend en charge les modèles concernés. Le client doit généralement préciser l’identifiant du modèle souhaité.

Une API conserve-t-elle automatiquement les conversations ?

Pas nécessairement. Avec de nombreux endpoints de conversation, le client doit gérer l’historique et transmettre les messages utiles à chaque appel.

Pourquoi utiliser le streaming ?

Il permet de recevoir les fragments de réponse progressivement et d’améliorer le délai perçu avant l’affichage du premier texte.

Peut-on utiliser une API compatible OpenAI avec un modèle local ?

Oui, certains serveurs locaux proposent des endpoints compatibles avec une partie des conventions OpenAI. Il faut vérifier les fonctionnalités réellement prises en charge.

Une API locale est-elle sécurisée par défaut ?

Pas nécessairement. La sécurité dépend notamment de l’adresse d’écoute, des autorisations, de l’authentification éventuelle et des applications pouvant accéder au service.

Que faire si le serveur ne répond pas ?

Vérifier que le service est démarré, que le port est correct et qu’aucun problème réseau ou de configuration ne bloque la communication.

À retenir

  • Une API permet à un logiciel de communiquer avec un modèle local.
  • La communication repose généralement sur une architecture client-serveur.
  • Ollama utilise habituellement le port 11434.
  • LM Studio peut proposer un serveur local sur le port 1234.
  • Un endpoint correspond à une opération précise de l’API.
  • GET sert généralement à récupérer des informations ; POST permet notamment d’envoyer des données.
  • JSON est un format courant pour les requêtes et les réponses.
  • L’API native d’Ollama propose notamment /api/generate et /api/chat.
  • Le paramètre stream permet de choisir entre réponse complète et diffusion progressive.
  • PowerShell permet de tester une API sans installer de bibliothèque Python.
  • Python permet d’intégrer les appels API dans des programmes.
  • Le client doit généralement gérer l’historique des conversations.
  • Les formats natifs et compatibles OpenAI ne sont pas nécessairement identiques.
  • Les codes HTTP et les messages d’erreur facilitent le diagnostic.
  • Une API locale ne doit pas être exposée sans protections adaptées.
  • Les réponses du modèle doivent être contrôlées avant toute utilisation importante.
Vérifiez votre compréhension

Question 1 : Quel est le rôle d’une API dans une installation d’IA locale ?

Voir la réponse
Elle permet à une application d’envoyer des demandes au serveur local et de récupérer les résultats produits par le modèle.

Question 2 : Quelle différence existe-t-il entre GET et POST ?

Voir la réponse
GET sert généralement à consulter une ressource, tandis que POST permet notamment de transmettre des données pour déclencher un traitement.

Question 3 : Quel endpoint Ollama permet de demander une génération simple ?

Voir la réponse
POST /api/generate.

Question 4 : À quoi sert le champ stream ?

Voir la réponse
Il permet de demander une réponse complète ou une diffusion progressive des fragments générés.

Question 5 : Pourquoi faut-il transmettre les messages précédents lors d’une conversation par API ?

Voir la réponse
Parce que de nombreux endpoints ne conservent pas automatiquement le contexte entre des appels indépendants. Le client doit fournir l’historique nécessaire.

Question 6 : Quelle différence existe-t-il entre message.content et choices[0].message.content ?

Voir la réponse
Le premier correspond au format habituel de l’API native de conversation Ollama ; le second correspond au format de réponse courant des endpoints compatibles OpenAI.

Question 7 : Pourquoi ne faut-il pas exposer une API locale directement sur Internet ?

Voir la réponse
Parce qu’un service non protégé pourrait être utilisé par des personnes ou applications non autorisées, avec des risques pour les ressources et les données.
À suivre — Cours 12 Gérer les performances et les ressources →

Apprenez à mesurer la vitesse d’un modèle local, surveiller la RAM et la VRAM, comprendre les ralentissements et optimiser les paramètres d’inférence selon votre matériel.