Aller au contenu

Catalog Sync — auto-enrichissement catalog + couche sémantique

La couche Catalog Sync répond au problème du catalog froid : quand un opérateur ajoute un nouveau dataset, schéma ou source, le Catalog reste vide (aucune description, aucun tag, aucune FK), le vector store de la couche AI ne peut pas le retrouver via recherche sémantique, et le recall@5 du langage naturel → SQL chute pour cette nouvelle source.

Le daemon parcourt l'inventaire des tables du Catalog, échantillonne 5 % de chaque table via la couche Query, anonymise les lignes (masking Presidio), envoie un prompt RAG court à un LLM local via la passerelle AI, puis écrit le résultat dans le Catalog + le vector store. Les samples ne sortent jamais du cluster.

Sprint 63 / ADR-049 — squelette livré, chemin MVP

La phase 63.1 (cette release) livre le squelette du service, le chemin OM PATCH et Vector store (Milvus) upsert, et un toggle off par défaut. Les phases 63.4–63.7 ajoutent la découverte des FK implicites, le minage du query log et une UI cockpit accept/reject. Voir ADR-049.

Architecture

flowchart LR
  subgraph Triggers
    CRON[CronJob 6h]
    HOOK[POST /sync<br/>webhook]
    CLI[Manuel --table=fqn]
  end
  subgraph Daemon["akko-catalog-sync (FastAPI)"]
    DISC[Discovery<br/>OM list + watermark]
    SAMP[Sampler<br/>Trino TABLESAMPLE 5%]
    ENR[Enrich<br/>Ollama qwen2.5:3b<br/>≤20 mots]
    PUB[Publish<br/>OM PATCH + Milvus upsert]
  end
  subgraph Backends
    OM[(OpenMetadata)]
    TR[(Trino)]
    LL[LiteLLM → Ollama]
    MV[(Milvus<br/>collection : catalog)]
  end
  CRON --> DISC
  HOOK --> DISC
  CLI --> DISC
  DISC --> SAMP --> ENR --> PUB
  DISC --> OM
  SAMP --> TR
  ENR --> LL
  PUB --> OM
  PUB --> MV

Garantie de souveraineté

La NetworkPolicy livrée par le chart n'autorise que :

  • kube-dns (UDP/TCP 53)
  • Egress same-namespace vers Catalogue (OpenMetadata) (8585), Moteur de requête (Trino) (8080), Passerelle IA (LiteLLM) (4000), Vector store (19530), Postgres (5432)

Aucun egress public n'est permis. C'est le seul auto-enricher de catalog OSS basé LLM avec cette garantie — DataHub Cloud route les samples via AWS Bedrock, Atlan / Coalesce / Select Star / Secoda sont SaaS par design.

API

Endpoint Méthode Rôle
/healthz GET Probe liveness / readiness
/metrics GET Exposition Couche Métriques (Prometheus)
/status GET Snapshot des feature flags + config
/sync POST Exécute un cycle discover → sample → enrich → publish

Body de POST /sync :

{
  "fqns": ["iceberg.banking.transactions"],
  "since_ms": 0,
  "dry_run": true,
  "limit": 50
}

Le défaut est dry_run=true (positionné dans les values du chart). L'UI cockpit "Sync staged changes" passe à false quand l'opérateur accepte un delta.

Configuration (zero hardcoding)

Chaque URL, modèle et toggle est lu depuis des env vars câblées par le sub-chart Helm. Aucun nom d'hôte, mot de passe ou ID de modèle n'est codé en dur dans le code Python. Les valeurs sont dans helm/akko/charts/akko-catalog-sync/values.yaml.

Flags clés (gated par global.features.catalogSyncEnabled) :

  • features.llmDescriptions — active/désactive le path LLM description
  • features.piiLlmVote — vote majoritaire Presidio + LLM pour le tagging PII
  • features.fkDiscovery — phase 63.4 fingerprint matching
  • features.queryMiner — phase 63.5 minage du query log Couche Logs (VictoriaLogs)
  • features.milvusPush — push de l'enrichissement vers la collection ADEN

Métriques

  • akko_catalog_sync_tables_processed_total{outcome="ok|dry_run|error|sample_failed"}
  • akko_catalog_sync_llm_latency_seconds (histogramme)
  • akko_catalog_sync_publish_failures_total{sink="openmetadata|milvus"}

Smoke test

Après activation du daemon (global.features.catalogSyncEnabled=true) et provisionnement du Secret OM bot-token :

kubectl -n akko run csync-curl --rm -it --image=curlimages/curl:8.10.1 -- \
  sh -c 'curl -sX POST -H "Content-Type: application/json" \
    -d "{\"limit\":3,\"dry_run\":true}" \
    http://akko-akko-catalog-sync:8000/sync | head -c 4000'

Le résultat attendu : un tableau JSON de 3 entrées, chacune avec une description ≤20 mots générée et om_updated:false (dry-run).

Liens