RAG, embeddings et appels d'outils

Le RAG (Retrieval-Augmented Generation, génération augmentée par récupération) consiste à chercher dans tes propres documents les passages qui répondent à une question, puis à les donner au modèle avec la question pour qu'il réponde à partir d'eux. Les appels d'outils (function calling ou tool use) permettent au modèle de demander à ton programme d'exécuter une fonction, consulter un ticket par exemple, puis d'utiliser le résultat. Les deux techniques relient un LLM à des données qu'il n'a jamais vues pendant son entraînement, ce qui réduit les hallucinations sur ces données.

Pourquoi le RAG

Le modèle ne connaît ni les procédures de Sorbier, ni son plan d'adressage, ni l'historique de ses tickets. Trois solutions existent pour qu'il s'en serve :

Pour faire répondre un assistant à partir de documents internes qui évoluent, le RAG est presque toujours le bon choix.

Les deux phases d'un RAG

L'indexation, faite une fois puis à chaque mise à jour des documents :

1. Découper chaque document en passages (chunks) de quelques centaines de tokens, si possible en suivant sa structure : une procédure, une section, un paragraphe.
2. Calculer le plongement de chaque passage avec un modèle d'embedding : un vecteur de quelques centaines à quelques milliers de nombres qui résume son sens.
3. Stocker les vecteurs avec le texte et des métadonnées (source, date, droits d'accès) dans une base vectorielle : une extension de base de données comme pgvector pour PostgreSQL, ou un moteur dédié comme Qdrant ou Chroma.

L'interrogation, à chaque question :

1. Calculer le plongement de la question avec le même modèle d'embedding.
2. Chercher les passages dont les vecteurs sont les plus proches.
3. Construire le prompt : les passages trouvés, la question, et la consigne de ne répondre qu'à partir d'eux en citant leur source.
4. Le LLM génère la réponse.

Les embeddings et la similarité cosinus

Un modèle d'embedding transforme un texte en vecteur, de façon que deux textes de sens proche donnent des vecteurs qui pointent dans des directions proches, même s'ils n'ont aucun mot en commun : « le VPN ne marche plus » et « impossible de se connecter au réseau de l'entreprise depuis l'hôtel ».

Pour mesurer cette proximité, on calcule la similarité cosinus, le cosinus de l'angle entre les deux vecteurs :

cos(a, b) = (a · b) / (‖a‖ × ‖b‖)

a · b = a₁b₁ + a₂b₂ + … + aₙbₙ          (produit scalaire)
‖a‖  = √(a₁² + a₂² + … + aₙ²)           (norme, la longueur du vecteur)

Le résultat est compris entre −1 et 1. Proche de 1, les deux textes parlent de la même chose ; proche de 0, ils n'ont rien à voir. La recherche garde les passages dont le cosinus avec la question est le plus élevé. Les vrais vecteurs ont des centaines de dimensions, mais le calcul est le même qu'en dimension 3, comme dans l'exercice de fin de chapitre.

Un mini-RAG en Python avec Ollama

Ce programme fait tout le chemin avec trois procédures de Sorbier, une base vectorielle réduite à une liste Python, et deux modèles Ollama : embeddinggemma pour les plongements, llama3.2:3b pour la réponse. Télécharge-les d'abord avec ollama pull embeddinggemma et ollama pull llama3.2:3b.

import json
import math
import urllib.request

OLLAMA = "http://localhost:11434"


def appeler(chemin, donnees):
    requete = urllib.request.Request(
        OLLAMA + chemin,
        data=json.dumps(donnees).encode("utf-8"),
        headers={"Content-Type": "application/json"},
    )
    with urllib.request.urlopen(requete, timeout=300) as reponse:
        return json.load(reponse)


def vecteurs(textes):
    return appeler("/api/embed", {"model": "embeddinggemma", "input": textes})["embeddings"]


def cosinus(a, b):
    produit = sum(x * y for x, y in zip(a, b))
    return produit / (math.sqrt(sum(x * x for x in a)) * math.sqrt(sum(y * y for y in b)))


# 1. Indexation : une seule fois, puis à chaque mise à jour des procédures
procedures = [
    "MDP-01 : pour réinitialiser un mot de passe, le technicien vérifie l'identité du salarié "
    "en le rappelant sur son poste fixe, puis impose un changement à la prochaine connexion.",
    "IMP-03 : si une imprimante signale un bourrage alors qu'aucune feuille n'est coincée, "
    "l'éteindre, ouvrir le capot arrière, vérifier qu'aucun morceau de papier ne reste près "
    "du rouleau de sortie, puis la rallumer.",
    "VPN-02 : un nomade qui n'arrive plus à se connecter au VPN WireGuard vérifie d'abord la "
    "date et l'heure de son poste, puis réimporte le profil fourni par le service informatique.",
]
index = list(zip(procedures, vecteurs(procedures)))

# 2. Interrogation : à chaque question
question = "Un commercial en déplacement n'arrive plus à joindre le réseau de l'entreprise."
vecteur_question = vecteurs([question])[0]
classement = sorted(index, key=lambda paire: cosinus(vecteur_question, paire[1]), reverse=True)
extraits = "\n".join(texte for texte, _ in classement[:2])

reponse = appeler("/api/chat", {
    "model": "llama3.2:3b",
    "stream": False,
    "messages": [
        {"role": "system", "content": "Réponds uniquement à partir des procédures fournies et cite leur code. "
                                      "Si elles ne permettent pas de répondre, dis-le."},
        {"role": "user", "content": f"<procedures>\n{extraits}\n</procedures>\n\nQuestion : {question}"},
    ],
})
print(reponse["message"]["content"])

L'endpoint /api/embed accepte une liste de textes et renvoie une liste de vecteurs, un par texte. La question ne contient ni « VPN » ni « WireGuard », et pourtant la procédure VPN-02 doit arriver en tête : c'est tout l'intérêt de la recherche par le sens. Affiche les scores avec print(cosinus(vecteur_question, v)) pour le vérifier.

Les pièges du RAG

• Un mauvais découpage. Une procédure coupée au milieu donne des passages incompréhensibles ; des passages trop longs noient l'information.
• Des documents périmés. Le RAG répond avec ce qu'il trouve : une ancienne procédure non supprimée devient une réponse fausse, citée avec assurance. L'indexation suit le cycle de vie des documents.
• Les droits d'accès. Si la base contient les procédures RH et les comptes rendus de direction, l'assistant peut les citer à n'importe quel salarié. Filtre les passages selon les droits de l'utilisateur avant de les envoyer au modèle, jamais en lui demandant de ne pas les citer.
• L'injection par les documents. Un document indexé peut contenir des instructions cachées (chapitre 9).
• La recherche qui ne trouve pas. Si aucun passage n'est pertinent, le modèle doit le dire. La consigne « si les procédures ne permettent pas de répondre, dis-le » est indispensable, et un seuil de similarité minimal aide.

Les appels d'outils

Avec les appels d'outils, le modèle ne se contente plus de lire : il demande une action à ton programme. Le principe :

1. Dans la requête, tu décris les outils disponibles : un nom, une description, et le schéma JSON des paramètres.
2. Si le modèle a besoin d'un outil, il ne répond pas par du texte : il renvoie un appel d'outil, avec le nom de l'outil et des arguments en JSON, et stop_reason vaut tool_use.
3. Ton code exécute la fonction, avec ses propres contrôles, et renvoie le résultat au modèle.
4. Le modèle rédige la réponse finale à partir du résultat, ou demande un autre outil.

Le modèle n'exécute jamais rien lui-même : il écrit une demande, et c'est ton programme qui décide de l'exécuter. Voici outil_ticket.py, un assistant qui peut consulter un ticket de la base parc, ici remplacée par un dictionnaire :

import json
import anthropic

client = anthropic.Anthropic()

# Les données viennent ici d'un dictionnaire ; dans l'application, d'une requête préparée sur la base parc.
TICKETS = {
    6: {"titre": "Ventilateur bruyant", "priorite": "basse", "statut": "en_cours"},
}

outils = [{
    "name": "consulter_ticket",
    "description": "Renvoie le titre, la priorité et le statut d'un ticket d'assistance à partir de son numéro.",
    "input_schema": {
        "type": "object",
        "properties": {
            "id_ticket": {"type": "integer", "description": "Numéro du ticket, par exemple 6"},
        },
        "required": ["id_ticket"],
    },
}]


def executer(nom, arguments):
    if nom != "consulter_ticket" or not isinstance(arguments.get("id_ticket"), int):
        return json.dumps({"erreur": "appel d'outil invalide"})
    ticket = TICKETS.get(arguments["id_ticket"])
    return json.dumps(ticket if ticket else {"erreur": "ticket introuvable"}, ensure_ascii=False)


messages = [{"role": "user", "content": "Où en est mon ticket 6 ?"}]

while True:
    reponse = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=16000,
        tools=outils,
        messages=messages,
    )
    if reponse.stop_reason != "tool_use":
        break
    messages.append({"role": "assistant", "content": reponse.content})
    resultats = []
    for bloc in reponse.content:
        if bloc.type == "tool_use":
            resultats.append({
                "type": "tool_result",
                "tool_use_id": bloc.id,
                "content": executer(bloc.name, bloc.input),
            })
    messages.append({"role": "user", "content": resultats})

print("".join(bloc.text for bloc in reponse.content if bloc.type == "text"))

Le déroulé d'un tour :

1. Premier appel : le modèle répond par un bloc tool_use avec name = "consulter_ticket" et input = {"id_ticket": 6}.
2. Le programme renvoie toute la réponse du modèle, puis un message user contenant un bloc tool_result, avec le même identifiant (tool_use_id) et le résultat en JSON.
3. Second appel : le modèle lit le résultat et répond par du texte, « Ton ticket 6, Ventilateur bruyant, est en cours de traitement ». stop_reason vaut end_turn, la boucle s'arrête.

C'est exactement la boucle d'un agent du chapitre 6, avec un seul outil. Ollama propose la même mécanique avec le champ tools de /api/chat, pour les modèles qui la prennent en charge. Un serveur MCP, lui, sert à partager des outils entre plusieurs assistants sans les redéfinir dans chaque application (MCP).

Sécuriser les outils

Un outil donne au modèle un pouvoir sur ton système. Les arguments qu'il fournit sont des données non fiables, au même titre qu'une saisie dans un formulaire : ils peuvent être faux, ou dictés par une injection de prompt.

• Moindre privilège. L'outil consulter_ticket lit ; il ne modifie rien. La connexion à la base utilise un compte en lecture seule sur les tables utiles.
• Validation dans le code. Vérifie le type et les valeurs de chaque argument, comme executer() le fait pour id_ticket, puis utilise une requête préparée.
• Contrôle des droits dans le code. L'utilisateur connecté a-t-il le droit de voir ce ticket ? C'est ton application qui le vérifie, avec l'identité de l'utilisateur, pas le modèle.
• Confirmation humaine pour toute action qui modifie ou supprime : clôturer un ticket, réinitialiser un mot de passe, créer un compte.
• Journalisation de chaque appel d'outil : qui, quoi, avec quels arguments, quel résultat.

Exercices

{
    "name": "creer_ticket",
    "description": "Crée un ticket d'assistance au nom d'un employé.",
    "input_schema": {
        "type": "object",
        "properties": {
            "titre": {"type": "string", "maxLength": 100, "description": "Résumé du problème"},
            "priorite": {"type": "string", "enum": ["basse", "normale", "haute", "critique"]},
            "id_demandeur": {"type": "integer", "description": "Numéro de l'employé demandeur"},
        },
        "required": ["titre", "priorite", "id_demandeur"],
    },
}