Base de connaissances

La base de connaissances est ce qui rend les réponses de l'agent ancrées — le LLM n'a pas à deviner depuis les données d'entraînement parce qu'il peut chercher dans vos runbooks, vos postmortems passés et la doc de votre équipe à chaque tour.

Forme du stockage

Un seul vector store, trois types de source.

Type de source	D'où ça vient	Lecture seule ?
vault	La collection de playbooks intégrée ongridio/vault (96 docs markdown au 2026-05-29)	Oui
repo	URLs git que vous enregistrez — HTTPS public ou SSH via identité par repo	Non (éditer settings + re-sync)
upload	Uploads directs (md / txt / pdf / docx) via la page /knowledge de la SPA	Non (éditer / supprimer la ligne)
manual	Coller du markdown via l'éditeur inline	Non

Les quatre types partagent une seule collection Qdrant (ongrid_knowledge) et un seul modèle d'embedding. Les hits de recherche renvoient le champ payload source_type pour que l'UI puisse rendre le bon badge « depuis le vault » / « depuis vos repos ».

ADR-028 — sources de connaissance, étagées

Pourquoi une seule collection : l'alternative (une collection par type de source) forçait le LLM à appeler N recherches par question pour avoir la couverture, faisant exploser le budget d'appels d'outils. Une collection + filtre source_type donne la même isolation en une requête.

Le client Qdrant

Surface étroite, dans internal/manager/biz/knowledge/usecase.go:62 :

type QdrantClient interface {
    EnsureCollection(ctx context.Context, name string, dim int) error
    EnsurePayloadIndex(ctx context.Context, collection, field, schema string) error
    Upsert(ctx context.Context, collection string, points []qdrantx.Point) error
    DeleteByFilter(ctx context.Context, collection string, mustMatch map[string]any) error
    DeleteByID(ctx context.Context, collection string, id uint64) error
    GetPoints(ctx context.Context, collection string, ids []uint64) ([]qdrantx.SearchHit, error)
    Search(ctx context.Context, collection string, vector []float32, opts qdrantx.SearchOpts) ([]qdrantx.SearchHit, error)
    Scroll(ctx context.Context, collection string, opts qdrantx.ScrollOpts) (*qdrantx.ScrollResult, error)
}

Soutenu par internal/pkg/qdrantx en production, fake-able en tests. Qdrant est livré dans le docker-compose ; un Qdrant externe est supporté via ONGRID_QDRANT_URL.

Le vault

Le vault est un dépôt git public (pas d'auth) qui livre des playbooks de diagnostics pré-curés. Sujets couverts (au 2026-05-29) :

• Réseau : recettes de debug DNS / TCP / TLS / HTTP.
• Kubernetes : cartes symptôme-à-cause pod / node / kubelet.
• Linux : chemins d'investigation processus / mémoire / disque / journald.
• Base de données : triage slow-log MySQL, lag de réplication PostgreSQL.
• Diagnostics : 70+ playbooks indexés par symptôme.

ADR-029 a ajouté la sync cloud : le manager tire le dernier vault sur un planning (défaut 24h, configurable via les settings de la SPA) et ré-embed sur changements. Le checkout sur disque vit sous /var/lib/ongrid/repos/<vault_id>/ ; les points qdrant sont tagués source=vault pour qu'un Sync ne supprime que les points vault, jamais les vôtres.

Ne traitez pas le vault comme votre repo

Le vault est une source intégrée — il n'apparaît jamais dans la page CRUD /knowledge/repos. Le code utilise isBuiltinVault() / is_builtin pour le gater ; ne faites pas de substring-match ongridio/vault (voir le feedback sur les pièges récurrents).

Vos propres repos

POST /v1/knowledge/repos avec un body { url, name } enregistre un dépôt git. Au prochain tick de sync, le manager :

1. git clone --depth=1 (ou git pull si le dir existe déjà) dans /var/lib/ongrid/repos/<id>/.
2. Parcourt l'arbre pour les fichiers .md / .txt / .rst / .yaml / .yml / .toml / .json.
3. Embed chaque fichier avec le modèle d'embedding configuré.
4. Remplace le set de points pour ce repo (source=repo, repo_id=<id>) de façon atomique.

Auth SSH

Identité par repo, gérée via la table ssh_identities et la page /knowledge/identities de la SPA. La ligne Repository ne porte PAS de champ provider — la table d'identités est la source unique de credentials git (ADR-023).

GIT_SSH_COMMAND est posé par sync pour pointer vers le fichier de clé de l'identité, de sorte que le clone de chaque repo utilise sa propre clé sans polluer $HOME/.ssh/.

Auth HTTPS

Les repos HTTPS publics clonent sans auth. L'auth HTTPS privée est en attente : le chemin GitHub-PAT original a été retiré quand SSH a couvert les cas d'usage réalistes. Tant que le RepoFetcher d'ADR-018 n'atterrit pas, utilisez SSH pour le privé.

Uploads

La page /knowledge/upload accepte :

Format	Extracteur
.md, .txt	Read brut + chunk
.pdf	docextract (internal/pkg/docextract)
.docx	docextract

Chaque upload devient une ligne dans knowledge_docs et un point dans qdrant avec source=upload. Édition et suppression inline marchent par ligne depuis l'arbre « Organization knowledge ».

Recherche

Le LLM reçoit un BaseTool query_knowledge — schéma dans query_knowledge_basetool.go. Args : query, filtre source_type optionnel, top_k optionnel. Renvoie : une liste de hits {score, source, title, snippet, url?}.

La persona coordinator est instruite d'appeler ceci tôt pour toute question « comment faire » / « pourquoi X arrive » / « quel est le runbook pour Y » — le coût d'une recherche de connaissance est bien inférieur à celui d'une investigation à 5 outils qui atterrit sur la même réponse que le playbook avait déjà.

L'UI de chat expose aussi un bouton Quick Action « Search knowledge » pour que les opérateurs puissent taper le même index sans passer par le chat.

Voir aussi

• Skills — query_knowledge est l'un des 18 BaseTools pontés présents dans le registre de skills.
• RCA — la persona investigator qui appelle la recherche de connaissances comme outil de premier recours.
• Architecture — où se situe Qdrant dans la stack L1.