API locale et RAG

Une API locale transforme un modèle isolé en service réutilisable. Une interface, un script ou un agent peut envoyer une requête structurée et recevoir des tokens. Le RAG ajoute une recherche documentaire avant cette génération.

L'API comme frontière

L'API sépare le client du runtime. Le client ne gère pas directement les poids ou le GPU. Il envoie un modèle demandé, des messages et des paramètres. Le serveur valide, planifie et renvoie le résultat.

Cette frontière permet de changer d'interface sans changer de modèle, ou de remplacer le runtime sans réécrire chaque client. Elle concentre aussi le risque : accès réseau, authentification, quotas et journaux.

Interroger l'API locale

Ollama écoute par défaut sur http://localhost:11434. Une requête contient le modèle, les messages et les options. Avec "stream": false, la réponse arrive en un seul bloc JSON au lieu d'un flux de tokens :

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3:8b",
  "messages": [{ "role": "user", "content": "Cite trois usages possibles pour une API locale." }],
  "stream": false
}'

Le même serveur expose aussi une API compatible avec le format d'OpenAI. Beaucoup d'outils peuvent donc s'y connecter en changeant seulement l'adresse de base :

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{ "model": "qwen3:8b", "messages": [{ "role": "user", "content": "Bonjour" }] }'

Sous Windows, PowerShell propose un équivalent qui évite les problèmes de guillemets :

$body = @{ model = "qwen3:8b"; stream = $false; messages = @(@{ role = "user"; content = "Bonjour" }) } | ConvertTo-Json -Depth 4
Invoke-RestMethod -Uri http://localhost:11434/api/chat -Method Post -Body $body -ContentType "application/json"

llama-server expose la même route /v1/chat/completions sur son propre port, 8080 dans la leçon précédente.

Le principe du RAG

Le pipeline comporte généralement quatre opérations : découper les documents, calculer leurs embeddings, indexer les fragments, puis retrouver ceux qui ressemblent à la question.

Découper sans perdre le sens

Des fragments trop courts perdent leur contexte. Des fragments trop longs diluent l'information et consomment la fenêtre. Le bon découpage suit la structure du document : titres, paragraphes, sections et tableaux.

Conservez les métadonnées utiles : fichier, page, section, date et niveau d'accès. Elles servent à citer la source et à filtrer la recherche.

Embeddings et recherche

Un embedding représente un texte par un vecteur. Les textes proches par le sens obtiennent souvent des vecteurs proches. Une base vectorielle retrouve rapidement les fragments les plus similaires.

La similarité ne garantit pas la pertinence. Une recherche hybride combine parfois mots-clés et vecteurs. Un reranker peut ensuite réordonner les candidats avec un modèle plus précis.

Pour voir un embedding, téléchargez un modèle multilingue comme bge-m3, puis envoyez-lui deux phrases :

ollama pull bge-m3
curl http://localhost:11434/api/embed -d '{
  "model": "bge-m3",
  "input": ["Le KV cache grandit avec le contexte.", "La VRAM est la mémoire du GPU."]
}'

La réponse contient un tableau embeddings : une liste de nombres par phrase, toutes de la même longueur. Une base vectorielle stocke ces listes et compare celle de la question à celles des fragments, souvent par similarité cosinus. Des interfaces comme Open WebUI réalisent ces étapes pour vous, mais le principe reste celui-ci.

Composer la requête finale

Le système ajoute les passages retenus avec des instructions claires : utiliser les sources, citer leur origine et dire quand elles ne suffisent pas. Placez une limite au nombre de fragments pour éviter de noyer la question.

Mesurer chaque étape

Évaluez d'abord la recherche : le bon passage apparaît-il dans les premiers résultats ? Évaluez ensuite la génération : la réponse respecte-t-elle les passages ? Enfin, testez les questions absentes : le système refuse-t-il d'inventer ?

Sécurité locale

Indexez seulement les documents autorisés pour l'utilisateur. Si plusieurs personnes partagent le service, appliquez les droits avant la recherche. Ne comptez pas sur le modèle pour masquer une information qu'il a déjà reçue dans son contexte.

Journalisez les erreurs techniques sans enregistrer par défaut l'intégralité des documents et des conversations. Définissez une durée de conservation et un accès restreint.