G-09 Évaluation

Brique G de la plateforme Enterprise AI. Technologie : Ragas (métriques RAG) + Promptfoo (régression des prompts et des agents, assertions). Version anglaise : ../../en/bricks/G-09-evaluation.md.

Rôle et responsabilités

• Définir des suites (jeu de données + métriques + seuils), les exécuter contre une version d'agent, prompt, modèle ou RAG, stocker les résultats.
• Métriques : fidélité, pertinence des réponses, précision/rappel du contexte (Ragas), assertions, budgets de latence et de coût (Promptfoo).

Position et interactions

• Chemin d'exécution : workflow batch.
• Les runs sont des workflows (Temporal) appelant le gateway comme tout agent, donc tracés et chiffrés.
• Les résultats alimentent les quality gates G-13 et les scores de retour Opik.

Part open source et part développée

• Open source réutilisé : Ragas, Promptfoo.
• Développé dans la plateforme : Evaluation Contract, adaptateurs de moteurs, versionnement des jeux de données, normalisation des résultats.

Modèle de données

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

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éthode	Chemin
POST	/v1/evaluations/suites
POST	/v1/evaluations/runs
GET	/v1/evaluations/runs/{id}
GET	/v1/evaluations/runs

POST /v1/evaluations/suites

Requête :

{
  "name": "invoice-agent-regression",
  "target": {
    "type": "agent",
    "ref": "agt_ap"
  },
  "engine": "ragas",
  "kind": "rag",
  "dataset": {
    "ref": "eai-datasets/invoice-qa-v3.jsonl",
    "version": "3"
  },
  "metrics": [
    {
      "name": "faithfulness",
      "threshold": 0.85
    },
    {
      "name": "answer_relevancy",
      "threshold": 0.8
    }
  ]
}

Réponse :

{
  "id": "evs_12",
  "name": "invoice-agent-regression",
  "status": "active"
}

POST /v1/evaluations/runs

Requête :

{
  "suite_id": "evs_12",
  "target": {
    "type": "agent",
    "ref": "agt_ap",
    "version": "1.4.0"
  }
}

Réponse :

{
  "evaluation_id": "evr_77",
  "status": "running"
}

GET /v1/evaluations/runs/{id}

Réponse :

{
  "evaluation_id": "evr_77",
  "status": "succeeded",
  "results": [
    {
      "metric": "faithfulness",
      "value": 0.91,
      "passed": true
    }
  ],
  "gate": {
    "passed": true
  },
  "cost": {
    "measured": {
      "amount": "3.12",
      "currency": "EUR"
    }
  }
}

GET /v1/evaluations/runs

Réponse :

{
  "items": [
    {
      "evaluation_id": "evr_77",
      "status": "succeeded"
    }
  ],
  "next_cursor": null
}

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.evaluation.create_suite({"name": "invoice-agent-regression", "engine": "ragas", "target": {"type": "agent", "ref": "agt_ap"}, "dataset": {"ref": "ds_invoices"}, "metrics": [{"name": "faithfulness", "threshold": 0.85}]})
client.evaluation.run("evs_12", {"type": "agent", "ref": "agt_ap", "version": "1.4.0"})
client.evaluation.get_run("evr_77")
client.evaluation.list_runs(suite_id="evs_12")

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.evaluations.createSuite({ name: "invoice-agent-regression", engine: "ragas", target: { type: "agent", ref: "agt_ap" }, dataset: { ref: "ds_invoices" }, metrics: [{ name: "faithfulness", threshold: 0.85 }] });
await client.evaluations.createRun({ suite_id: "evs_12", target: { type: "agent", ref: "agt_ap", version: "1.4.0" } });
await client.evaluations.getRun("evr_77");
await client.evaluations.listRuns({ suite_id: "evs_12" });

Java

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .tenant("acme")
    .locale(Locale.FRENCH)
    .build();
client.evaluations().createSuite(Map.of("name", "invoice-agent-regression", "engine", "ragas", "target", Map.of("type", "agent", "ref", "agt_ap"), "dataset", Map.of("ref", "ds_invoices"), "metrics", List.of(Map.of("name", "faithfulness", "threshold", 0.85))));
client.evaluations().createRun(Map.of("suite_id", "evs_12", "target", Map.of("type", "agent", "ref", "agt_ap", "version", "1.4.0")));
client.evaluations().getRun("evr_77");
client.evaluations().listRuns(Map.of("suite_id", "evs_12"));

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.Evaluations.CreateSuite(ctx, map[string]any{"name": "invoice-agent-regression", "engine": "ragas", "target": map[string]any{"type": "agent", "ref": "agt_ap"}, "dataset": map[string]any{"ref": "ds_invoices"}, "metrics": []map[string]any{{"name": "faithfulness", "threshold": 0.85}}})
_, err = client.Evaluations.CreateRun(ctx, map[string]any{"suite_id": "evs_12", "target": map[string]any{"type": "agent", "ref": "agt_ap", "version": "1.4.0"}})
_, err = client.Evaluations.GetRun(ctx, "evr_77")
_, err = client.Evaluations.ListRuns(ctx, eai.WithQuery(map[string]string{"suite_id": "evs_12"}))

Configuration

Variables d'environnement : EAI_PROMPTFOO_NPX.

Clés de valeurs Helm (deploy/helm/enterprise-ai/values.yaml) : workers.items[name=evaluation].

Sécurité

• Les jeux de données sont des médias classifiés ; utiliser des données de production pour évaluer exige une approbation.
• 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é

• Tendances des métriques par version de cible.
• traceparent W3C propagé, X-Request-Id renvoyé, les spans portent eai.tenant_id, eai.project, eai.agent_id, eai.run_id.

Unités FinOps

• Le coût d'évaluation est stocké dans le champ cost de l'Evaluation Contract et en Usage Events avec labels.purpose=evaluation.

Modes de défaillance et résilience

• Modèle juge indisponible -> run en échec, la gate ne peut pas passer (échec fermé).

Adoption autonome

Les équipes peuvent évaluer leur propre RAG avec la seule API d'évaluation.

Tests d'acceptation

1. Une suite avec un seuil de fidélité à 0.85 échoue sur un retriever volontairement cassé.
2. Le document de run est valide selon evaluation-contract.schema.json.

Feuille de route d'implémentation