Bases de connaissance (RAG)

Une base de connaissance regroupe vos documents, découpés en extraits chiffrés et indexés. Vous pouvez la brancher sur n’importe quel appel chat/completions (texte ou JSON) : le modèle répond en s’appuyant sur les extraits les plus pertinents, et les sources sont renvoyées dans une clé séparée — jamais mélangées à la réponse.

Le retrieval (recherche vectorielle + déchiffrement) se fait côté Astrolabe : vos clés de chiffrement ne quittent jamais notre infrastructure.

Où trouver l’identifiant d’une base ?

Chaque base a un slug (ex. faq-support), visible sur sa page dans le portail sous « Identifiant API ». C’est ce slug que vous passez dans knowledge_base.

Renommer le slug d’une base

Le slug est modifiable (page de la base → « Identifiant API »), mais c’est la référence utilisée partout. Au renommage, Astrolabe repointe automatiquement les références internes qui pointaient sur l’ancien slug : synchronisations de connecteurs (sync.target_kb) et tâches programmées. En revanche, ce qui vit hors de la plateforme n’est pas mis à jour : vos appels API (knowledge_base: "…"), vos scénarios Make/Zapier et vos connexions MCP continueront de citer l’ancien slug et renverront 404 (ou, en RAG statique, une réponse signalant la base introuvable) tant que vous ne les aurez pas mis à jour. Évitez aussi de réutiliser un ancien slug pour une autre base.

Activer le RAG sur un appel

Ajoutez les paramètres dans le corps de la requête (via extra_body avec les SDK OpenAI) :

Paramètre	Type	Rôle
knowledge_base	string | string[]	Une ou plusieurs bases (par slug). Active le RAG statique (injection forcée). Pour le mode agentique, préférez tools_enabled (cf. ci-dessous).
knowledge_base_mode	string	(optionnel, défaut "static") "static" = une recherche avant la réponse ; "agentic" = le modèle décide lui-même de chercher et boucle (cf. Mode agentique). Alias : tools_enabled: ["kb:<slug>"] est la forme recommandée pour l’agentique.
knowledge_base_max_steps	number	(optionnel, défaut 8, max 15) Mode agentique uniquement : nombre maximum de tours. Alias unifié : tools_max_steps.
knowledge_base_request	string	(optionnel) Texte ciblé pour la recherche. Par défaut : les derniers tours de la conversation (cf. knowledge_base_history).
knowledge_base_history	number	(optionnel, défaut 3) Nombre de tours utilisateur repliés dans la requête de recherche, pour que les suites courtes (« et le lien ? ») gardent le sujet. 1 = recherche sur le seul dernier message. Ignoré si knowledge_base_request est fourni.
knowledge_base_facets	object	(optionnel) Filtre dur sur les facettes des extraits.
knowledge_base_top_k	number	(optionnel) Nombre d’extraits sémantiques (défaut 6).
knowledge_base_cite_sources	boolean	(optionnel, défaut false) Autorise le modèle à citer le lien source (source_url) des extraits qui en ont un, dans sa réponse — pour retrouver la ressource d’origine.
knowledge_base_date_range	object	(optionnel) { from?, to? } (ISO) — ne retient que les extraits dont la date métier est dans la plage.
knowledge_base_expand	object	(optionnel) Renforce le contexte par les « frères » reliés par facettes (relation métier). Voir ci-dessous.

Exemple — chat

curl https://api.astrolabe.chat/v1/chat/completions \
  -H "Authorization: Bearer $ASTROLABE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-small",
    "messages": [{ "role": "user", "content": "Comment recharger des crédits ?" }],
    "knowledge_base": "faq-support"
  }'

from openai import OpenAI

client = OpenAI(base_url="https://api.astrolabe.chat/v1", api_key="VOTRE_CLE")

resp = client.chat.completions.create(
    model="mistral-small",
    messages=[{"role": "user", "content": "Comment recharger des crédits ?"}],
    extra_body={"knowledge_base": "faq-support"},
)
print(resp.choices[0].message.content)        # la réponse, propre
print(resp.model_extra["astrolabe_sources"])  # les extraits utilisés

Plusieurs bases, requête ciblée, filtre facettes

resp = client.chat.completions.create(
    model="mistral-small",
    messages=[{"role": "user", "content": "Bonjour, une question de facturation…"}],
    extra_body={
        "knowledge_base": ["faq-support", "docs-produit"],   # plusieurs bases
        "knowledge_base_request": "tarifs des crédits prépayés",  # texte de recherche ciblé
        "knowledge_base_facets": {"theme": "facturation"},        # filtre sur les facettes
    },
)

Précision du retrieval

Par défaut, c’est tout votre message qui sert de requête de recherche — ce qui peut être imprécis sur un message long ou un suivi (« et le prix ? »). Pour de meilleurs résultats :

• knowledge_base_request : fournissez un texte de recherche ciblé ;
• knowledge_base_facets : pré-filtrez par métadonnées (ex. {"theme": "facturation"}).

Renforcer le contexte par les facettes (« frères »)

La recherche sémantique trouve les extraits proches par le sens. Parfois, vous voulez aussi les extraits reliés par une logique métier — même client, même dossier, même produit — même s’ils ne se ressemblent pas. C’est le rôle de knowledge_base_expand : à partir des meilleurs hits sémantiques (les « graines »), on ramène leurs frères partageant des facettes.

Champ d’expand	Défaut	Rôle
seeds	3	Nombre de hits sémantiques servant de point de départ.
facets	(toutes)	Clés de facettes sur lesquelles matcher. Omis → on matche sur toutes les facettes de la graine.
match	"all"	"all" = frère partageant toutes ces facettes ; "any" = au moins une.
depth	1	Niveaux de traversée. À chaque niveau, on cherche les frères des frères (arbre).
max_chunks	30	Plafond dur d’extraits ajoutés par expansion (max absolu 200).

resp = client.chat.completions.create(
    model="mistral-small",
    messages=[{"role": "user", "content": "Fais le point sur le dossier Acme."}],
    extra_body={
        "knowledge_base": "crm",
        "knowledge_base_expand": {
            "seeds": 3,
            "facets": ["client"],   # tout ce qui partage le même client que les graines
            "depth": 1,
        },
    },
)

Les extraits ainsi ramenés apparaissent dans astrolabe_sources avec relation: "facet" (et leur level de profondeur), à côté des hits relation: "semantic".

Profondeur, match et coût

Avec match: "all" (défaut), la profondeur n’élargit quasiment pas (les frères stricts partagent déjà tout). L’arbre grossit surtout avec match: "any" (recouvrement) et depth > 1 — on peut alors atteindre des dizaines d’extraits. Chaque extrait injecté est facturé en tokens d’entrée et consomme de la fenêtre de contexte : max_chunks est là pour borner. Montez la profondeur progressivement.

Les sources dans la réponse

Les extraits utilisés sont renvoyés dans la clé astrolabe_sources, à côté de la réponse — jamais dans message.content. Vous les utilisez (ou non) dans votre process.

{
  "choices": [
    { "message": { "content": "Pour recharger des crédits, rendez-vous dans…" } }
  ],
  "astrolabe_sources": [
    {
      "n": 1,
      "knowledge_base": "faq-support",
      "document": "FAQ",
      "source_url": "https://docs.astrolabe.chat/credits",
      "score": 0.876,
      "date": null,
      "facets": { "theme": "facturation" },
      "content": "Q : Comment recharger mon compte en crédits ? R : …"
    }
  ]
}

Champ	Description
n	Rang de l’extrait (1 = le plus pertinent)
knowledge_base	Slug de la base d’origine
document	Document source de l’extrait
source_url	Lien vers la ressource d’origine du document, ou null
score	Pertinence (cosinus, 0 → 1)
date	Date métier de l’extrait (chunk_date), ou null
created	Date d’insertion en base de l’extrait (created_at)
facets	Métadonnées de l’extrait
content	Texte de l’extrait
relation	"semantic" (remonté par similarité) ou "facet" (frère ramené par relation de facettes)
level	(frères seulement) Profondeur de la traversée (1 = frère direct d’une graine)

astrolabe_sources est un champ additionnel

Préfixé astrolabe_, il est ignoré par les SDK OpenAI standards (lisible via model_extra / l’objet JSON brut). Votre code existant ne casse pas.

Citer les liens dans la réponse

Par défaut, le source_url n’est renvoyé que dans astrolabe_sources (la réponse texte reste propre). Passez knowledge_base_cite_sources: true pour autoriser le modèle à insérer ces liens directement dans sa réponse (en Markdown), pour les extraits qu’il a réellement utilisés et qui ont un lien.

Mode agentique

Par défaut le RAG est statique : une seule recherche, faite avant la réponse, à partir de votre message. En knowledge_base_mode: "agentic", c’est le modèle qui décide quand et quoi chercher : il dispose d’outils kb_search (recherche/listing, avec filtres typés, tri, regroupement par document) et kb_facets (découvrir les facettes et leurs valeurs), peut enchaîner plusieurs recherches, puis répond. Idéal pour les questions qui demandent de croiser plusieurs requêtes ou de filtrer finement.

curl https://api.astrolabe.chat/v1/chat/completions \
  -H "Authorization: Bearer $ASTROLABE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-small",
    "messages": [{ "role": "user", "content": "Compare ce que dit la base sur la facturation et sur la sécurité." }],
    "knowledge_base": "faq-support",
    "knowledge_base_mode": "agentic",
    "knowledge_base_max_steps": 3
  }'

Activer via tools_enabled (forme recommandée)

En mode agentique, une base est un outil que le modèle peut appeler — exactement comme la recherche web, les connecteurs ou l’exécution de code. La forme recommandée, homogène avec ces outils, est donc de l’activer dans tools_enabled :

Dans tools_enabled	Effet
"kb:<slug>"	Active cette base (comme connection:<slug>). Cumulable : ["kb:a", "kb:b"].
"kb"	Active toutes les bases accessibles à la clé.

curl https://api.astrolabe.chat/v1/chat/completions \
  -H "Authorization: Bearer $ASTROLABE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-small",
    "messages": [{ "role": "user", "content": "Compare ce que dit la base sur la facturation et sur la sécurité." }],
    "tools_enabled": ["kb:faq-support"],
    "tools_max_steps": 3
  }'

KB, recherche web, connecteurs et code coexistent dans la même liste, p. ex. "tools_enabled": ["kb:faq-support", "web_search"]. Le plafond de tours est tools_max_steps (commun à tous les outils ; défaut 8, max 15).

Note

Compatibilité. L’ancienne forme — knowledge_base + knowledge_base_mode: "agentic" (+ knowledge_base_max_steps) — reste pleinement supportée (alias). Le RAG statique, lui, continue de s’activer avec knowledge_base seul (sans tools_enabled) : ce n’est pas un outil que le modèle appelle, c’est une injection forcée de contexte. Si vous passez les deux à la fois, la forme agentique (tools_enabled) l’emporte.

À savoir :

• Coût : le mode agentique fait plusieurs appels au modèle (un par tour + la réponse) → plus coûteux que le statique. tools_max_steps (défaut 8, max 15) borne le nombre de tours.
• Non-streaming : le mode agentique répond en une fois (stream: true est ignoré). Idéal pour les automatisations (Make/n8n) ; pour un affichage progressif, restez en statique.
• Routeur d’intention (intent_router, défaut true) : avant de mobiliser les bases, un petit modèle décide si le dernier message en a besoin (il écarte les salutations / le bavardage pour ne pas chercher inutilement). Passez "intent_router": false pour le désactiver : l’agent reçoit alors toujours les outils et décide seul d’appeler (ou non) la recherche. Utile pour comparer le comportement avec vs sans routeur.
• Sources : les extraits réellement utilisés sont renvoyés dans astrolabe_sources, comme en statique.
• Réflexion : les recherches que l’agent a décidé de lancer (outil, base, requête/filtres/ facettes, nombre de résultats) sont renvoyées dans astrolabe_steps — utile pour comprendre ou auditer comment la réponse a été construite.
• Se combine avec le mode JSON (la réponse finale respecte alors votre response_format).

Bases de procédures (playbooks)

Une base peut être marquée comme base de procédures (role: "process", voir gestion des bases). Au lieu de contenir des données, chaque document y décrit, étape par étape, comment mener une analyse : quelles recherches lancer, quelles facettes filtrer, quoi vérifier.

En mode agentique, sélectionnez la base de procédures avec vos bases de données dans knowledge_base. L’IA consulte d’abord la base de procédures, et si elle y trouve une fiche pertinente, elle suit ses étapes sur les bases de données — sinon elle mène l’analyse par elle-même. C’est une façon de capitaliser vos méthodes d’analyse récurrentes sans écrire de code.

curl https://api.astrolabe.chat/v1/chat/completions \
  -H "Authorization: Bearer $ASTROLABE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-medium",
    "messages": [{ "role": "user", "content": "Fais le bilan de vitalité de la startup ReFarm." }],
    "knowledge_base": ["procedures-fonds-impact", "suivi-participations"],
    "knowledge_base_mode": "agentic"
  }'

Une fiche-playbook est un simple document texte. Pour qu’elle reste entière (un seul extrait), écrivez-la en un seul bloc (sans ligne vide) et indexez-la en découpage simple. Référencez-y les vraies facettes de vos bases de données (score_sante, mrr_keur…) : l’IA traduira d’autant mieux les étapes en recherches concrètes.

Créer une fiche depuis un échange réussi

Vous n’êtes pas obligé d’écrire les playbooks à la main. Dans le bac à sable, quand un échange agentique a donné la bonne réponse, le bouton « Transformer en process » demande à l’IA d’en distiller la méthode : elle généralise les étapes (les valeurs précises deviennent des paramètres) et, le cas échéant, transforme le script utilisé en modèle réutilisable. Avant de lancer, vous choisissez le modèle et la clé (la consommation y est imputée), le périmètre (ce seul échange ou toute la discussion) et, en option, une finalité qui cadre la fiche. Sur toute une discussion, la distillation ne retient que le cheminement qui a mené au résultat, en écartant les fausses pistes. Vous relisez et éditez la fiche, puis l’enregistrez dans une base de procédures (si une fiche proche existe déjà, la mise à jour est proposée plutôt qu’un doublon). La fois suivante, sur une question du même type, l’IA retrouve la fiche et applique directement la méthode. Toujours avec un humain dans la boucle : aucune fiche n’est créée sans votre validation.

Mode JSON

Le RAG se combine avec la sortie structurée : la réponse reste un JSON propre, fondé sur la base, et les sources restent à part. En mode agentique, le response_format est appliqué au tour final (la recherche se fait d’abord, le formatage JSON ensuite).

resp = client.chat.completions.create(
    model="mistral-small",
    response_format={"type": "json_object"},
    messages=[{"role": "user", "content": "Moyens de paiement acceptés ? Réponds en JSON."}],
    extra_body={"knowledge_base": "faq-support"},
)
# content = {"paiements": ["Carte bancaire via Stripe"]}
# astrolabe_sources = [ … ]

Streaming

En streaming (stream: true), les sources arrivent dans un dernier chunk portant astrolabe_sources (avec un delta vide). Les clients qui ne lisent que le texte l’ignorent ; ceux qui veulent les sources lisent ce chunk final.

À savoir

• Facturation : seule la vectorisation de la requête est facturée (un embedding), en plus des tokens de génération habituels. Pas de surcoût caché.
• Souveraineté : avec un modèle en cloud UE (mistral-*, souverain au sens juridiction UE), les extraits injectés sont envoyés au fournisseur (Mistral, UE) au même titre que votre message. Avec un modèle auto-hébergé (astrolabe-*), tout reste dans notre infrastructure.
• Sécurité : en base, le texte des extraits est chiffré (une clé par base) ; il n’est déchiffré que le temps de répondre.
• Tolérance aux pannes : si une base est introuvable ou le retrieval échoue, l’appel n’est pas bloqué — le modèle répond sans contexte.