Aller au contenu principal

G-03 Traçage IA (prompts, réponses, outils, scores)

Brique G de la plateforme Enterprise AI. Technologie : Opik (Apache-2.0, auto-hébergé) pour les générations, les prompts, les appels d'outils, les sessions et les scores. Version anglaise : ../../en/bricks/G-03-ai-tracing.md.

Rôle et responsabilités​

  • Stocker prompts, réponses, entrées/sorties d'outils, versions de prompts, latence et tokens par génération.
  • Attacher des scores (retours utilisateurs, métriques Ragas, LLM juge) aux traces pour l'analyse qualité.

Position et interactions​

  • Chemin d'exécution : événement (export asynchrone depuis gateway et runtime).
  • L'id de trace OTel est gardé dans les métadonnées de la trace Opik (eai.trace_id) ; GET /v1/telemetry/traces/{trace_id} renvoie links.opik (page du projet et clé de métadonnée).

Part open source et part développée​

  • Open source réutilisé : Opik, API OTLP et REST d'Opik, intégration OTel.
  • Développé dans la plateforme : Politique de capture du contenu selon la classification, masquage avant export, correspondance tenant -> projet Opik (tenant_id dans les métadonnées).

Modèle de données​

Tables du Control Plane (schéma eai) : eai.telemetry_spans, eai.eval_runs.

Chaque table de tenant a tenant_id uuid NOT NULL et une politique de sécurité au niveau des lignes sur current_setting('app.tenant_id', true)::uuid. ClickHouse usage_events est la réplique analytique de eai.usage_events (ReplacingMergeTree par event_id).

Contrat : contracts/v1/evaluation-contract.schema.json (schema_version 1.0). L'usage est toujours remonté avec contracts/v1/usage-event.schema.json, l'audit avec contracts/v1/audit-event.schema.json.

Endpoints d'API​

MéthodeChemin
POST/v1/telemetry/spans
GET/v1/telemetry/traces/{trace_id}

POST /v1/telemetry/spans​

Requête :

{
  "spans": [
    {
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "span_id": "00f067aa0ba902b7",
      "name": "gen_ai.chat",
      "kind": "client",
      "start_time": "2026-10-29T10:00:00.120Z",
      "end_time": "2026-10-29T10:00:01.940Z",
      "attributes": {
        "gen_ai.request.model": "gpt-4o-mini",
        "gen_ai.usage.input_tokens": 812,
        "eai.agent_id": "agt_ap",
        "eai.run_id": "run_42"
      }
    }
  ]
}

Réponse :

{
  "accepted": 1,
  "rejected": 0
}

GET /v1/telemetry/traces/{trace_id}​

Réponse :

{
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "spans": [
    {
      "span_id": "00f067aa0ba902b7",
      "name": "gen_ai.chat",
      "duration_ms": 1820
    }
  ],
  "links": {
    "opik": {
      "url": "https://<opik-host>/default/redirect/projects?name=eai-platform",
      "metadata_key": "eai.trace_id",
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
    }
  }
}

Exemples SDK​

Python​

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_live_xxx", tenant="acme", locale="fr")
client.telemetry.ingest(spans=spans)
client.telemetry.trace(trace_id="4bf92f3577b34da6a3ce929d0e0e4736")

TypeScript​

import { EnterpriseAI } from "@enterprise-ai/sdk";

const client = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY, tenant: "acme", locale: "fr" });
await client.telemetry.ingestSpans({ spans: spans });
await client.telemetry.trace({ traceId: "4bf92f3577b34da6a3ce929d0e0e4736" });

Java​

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .tenant("acme")
    .locale(Locale.FRENCH)
    .build();
client.telemetry().ingestSpans(Map.of("spans", spans));
client.telemetry().trace("4bf92f3577b34da6a3ce929d0e0e4736");

Go​

client, err := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")), eai.WithTenant("acme"), eai.WithLocale("fr"))
if err != nil { log.Fatal(err) }
ctx := context.Background()
_, err = client.Telemetry.IngestSpans(ctx, map[string]any{"spans": spans})
_, err = client.Telemetry.Trace(ctx, "4bf92f3577b34da6a3ce929d0e0e4736")

Configuration​

Variables d'environnement : EAI_OPIK_URL, EAI_OPIK_UI_URL, EAI_OPIK_WORKSPACE, EAI_OPIK_PROJECT, EAI_OPIK_API_KEY.

Clés de valeurs Helm (deploy/helm/enterprise-ai/values.yaml) : controlPlane.config.EAI_OPIK_URL, controlPlane.secrets.

Sécurité​

  • Capture désactivée pour les données secrètes ; données confidentielles capturées seulement après masquage DLP.
  • Tenant déduit de l'identifiant d'accès, jamais du corps ; sécurité au niveau des lignes PostgreSQL sur chaque table de tenant.
  • Chaque mutation et décision de politique écrit un événement d'audit chaîné par hachage (G-11).
  • Les erreurs utilisent l'enveloppe standard avec message_i18n en et fr.

Observabilité​

  • Retard d'export et générations perdues.
  • traceparent W3C propagé, X-Request-Id renvoyé, les spans portent eai.tenant_id, eai.project, eai.agent_id, eai.run_id.

Unités FinOps​

  • Les tokens dans Opik sont une vue, pas la source comptable : les coûts viennent de H-02.

Modes de défaillance et résilience​

  • Opik indisponible -> tampon de repli en processus, les appels métier continuent.

Adoption autonome​

Les équipes peuvent utiliser Opik via la plateforme pour leurs propres prompts sans le runtime d'agents.

Tests d'acceptation​

  1. Un appel chat/completions apparaît dans Opik avec version de prompt et tokens.
  2. Une requête classée secret n'a aucun contenu dans Opik.

Feuille de route d'implémentation