enterprise_ai.evaluation

Source : sdks/python/src/enterprise_ai/evaluation/__init__.py. Retour à l'index de la référence du SDK Python.

remarque

Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.

Modèle CaseResult

Résultat d'un cas d'une exécution locale de suite : scores par métrique, verdict, latence et erreur.

Champs :

Nom	Type	Requis	Description
case_id	str	oui	Référence du dossier, 1 à 200 caractères.
scores	dict[str, float]	oui	Score entre 0 et 1 par nom de métrique ; vide si la cible a échoué.
passed	bool	oui	Vrai si la cible n'a pas échoué et que chaque score atteint le min_score du cas (1 par défaut).
latency_ms	float	oui	Temps pris par la cible, en millisecondes.
error	str | None	non	Exception levée par la cible sous la forme "<Type>: <message>", None si elle a répondu.

Modèle SuiteResult

Exécution locale agrégée : moyenne par métrique et verdict de la porte.

Champs :

Nom	Type	Requis	Description
suite	str	oui	Nom de la suite (suite par défaut).
cases	list[CaseResult]	non	Cas de la suite : objets avec input, system facultatif, les valeurs attendues des métriques et éventuellement une output déjà prête.
threshold	float	non	Valeur à laquelle le score est comparé.

Attributs :

Nom	Type	Requis	Description
metrics	dict[str, float]	oui	Score moyen de chaque métrique sur tous les cas (un score absent compte 0).
pass_rate	float	oui	Part des cas réussis, entre 0 et 1 (0 sans aucun cas).
passed	bool	oui	Verdict de la porte : vrai s'il y a au moins un cas et que pass_rate atteint threshold.

SuiteResult.to_dict

to_dict() -> dict[str, Any]

Le résultat sous forme de dict prêt pour JSON.

Cet élément ne prend aucun paramètre.

Retour : dict[str, Any]. Dict {suite, pass_rate, passed, metrics, threshold, cases}.

Classe EvaluationClient

Évaluation et red team. Qualité des systèmes d'IA du tenant : suites d'évaluation, exécutions, barrières de qualité avant promotion, comparaisons A/B avec une référence et campagnes de red team.

Resource

EvaluationClient.check_gate

check_gate(target: dict[str, Any] | str, suite_ids: list[str] | None = None, **extra: Any) -> Any

Vérifier la barrière de qualité d'une cible. Vérifie que la dernière exécution terminée de chaque suite bloquante de la cible (pour target.version si elle est donnée, et limitée à suite_ids s'il est donné) a réussi. Avec run_missing: true, une suite sans exécution est exécutée maintenant ; sinon elle compte comme missing.

Route : /v1/evaluations/gates/check (POST).

Nom	Type	Défaut	Requis	Description
target	dict[str, Any] | str		oui	Cible dont les suites bloquantes sont vérifiées ; version limite aux exécutions de cette version.
suite_ids	list[str] | None	None	non	Uniquement ces suites bloquantes. Null : toutes les suites bloquantes de la cible.
**extra	Any		non	Champs supplémentaires fusionnés dans le corps de la requête.

Retour : Any. Réponse JSON décodée de l'opération « Vérifier la barrière de qualité d'une cible ».

Erreurs levées : les erreurs typées du transport (Erreurs).

EvaluationClient.compare

compare(comparison: dict[str, Any]) -> Any

Comparer un candidat à une référence. Exécute une suite deux fois, sur la référence baseline et sur le candidate (chacun {type, ref, version}, type model par défaut, agent ou prompt), et enregistre les deux exécutions, les écarts par métrique et le verdict. Les écarts sont orientés par le comparateur de chaque métrique (gte : plus haut est mieux, lte : plus bas est mieux).

Route : /v1/evaluations/comparisons (POST).

Nom	Type	Défaut	Requis	Description
comparison	dict[str, Any]		oui	Comparaison à créer : la suite et ses exécutions ou cibles de référence et candidate.

Retour : Any. Réponse JSON décodée de l'opération « Comparer un candidat à une référence ».

Erreurs levées : les erreurs typées du transport (Erreurs).

EvaluationClient.create_suite

create_suite(suite: dict[str, Any]) -> Any

Créer une suite d'évaluation. Crée une suite. Exige tenant_admin, developer, security_officer ou ai_governance_officer. Erreurs 400 invalid_request : type de cible hors de model, agent, prompt, rag_pipeline, skill ou tool, moteur ou type inconnu, comparateur autre que gte ou lte, ou, pour le moteur custom, une métrique autre que exact_match, contains, not_contains, json_valid, faithfulness, latency ou refusal. Un nom déjà utilisé répond 409 conflict. Le jeu de données reçoit sa taille size et une empreinte SHA-256 digest des cas. Écrit l'événement d'audit evaluation.suite.create.

Route : /v1/evaluations/suites (POST).

Nom	Type	Défaut	Requis	Description
suite	dict[str, Any]		oui	Suite à créer, sous forme d'Evaluation Contract.

Retour : Any. Réponse JSON décodée de l'opération « Créer une suite d'évaluation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

EvaluationClient.get_comparison

get_comparison(comparison_id: str) -> Any

Lire une comparaison A/B. Renvoie une comparaison. Exige tenant_admin, developer, security_officer, auditor, viewer ou finops. Répond 404 comparison_not_found.

Route : /v1/evaluations/comparisons/{comparison_id} (GET).

Nom	Type	Défaut	Requis	Description
comparison_id	str		oui	Identifiant (UUID) de la comparaison.

Retour : Any. Réponse JSON décodée de l'opération « Lire une comparaison A/B ».

Erreurs levées : les erreurs typées du transport (Erreurs).

EvaluationClient.get_redteam_run

get_redteam_run(run_id: str) -> Any

Lire une campagne de red team. Renvoie une campagne de red team : cible, moteur, sondes, statut, synthèse (total, vulnérables, taux de réussite des attaques, seuil, par catégorie) et constats. Ouvert à tout membre du tenant. Répond 404 not_found.

Route : /v1/redteam/runs/{run_id} (GET).

Nom	Type	Défaut	Requis	Description
run_id	str		oui	Identifiant (UUID) de la campagne de red team.

Retour : Any. Réponse JSON décodée de l'opération « Lire une campagne de red team ».

Erreurs levées : les erreurs typées du transport (Erreurs).

EvaluationClient.get_run

get_run(run_id: str) -> Any

Lire une exécution d'évaluation. Renvoie une exécution d'évaluation avec ses résultats par métrique et par cas. Ouvert à tout membre du tenant. Répond 404 not_found.

Route : /v1/evaluations/runs/{run_id} (GET).

Nom	Type	Défaut	Requis	Description
run_id	str		oui	Identifiant (UUID) de l'exécution d'évaluation.

Retour : Any. Réponse JSON décodée de l'opération « Lire une exécution d'évaluation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

EvaluationClient.get_suite

get_suite(suite_id: str) -> Any

Lire une suite d'évaluation. Renvoie une suite avec la liste complète de ses cas et run_on_promotion. Ouvert à tout membre du tenant. Répond 404 not_found.

Route : /v1/evaluations/suites/{suite_id} (GET).

Nom	Type	Défaut	Requis	Description
suite_id	str		oui	Identifiant (UUID) de la suite.

Retour : Any. Réponse JSON décodée de l'opération « Lire une suite d'évaluation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

EvaluationClient.list_comparisons

list_comparisons(suite_id: str | None = None) -> Any

Lister les comparaisons A/B. Liste les comparaisons du tenant, les plus récentes d'abord, 200 au plus, éventuellement pour une seule suite. Chacune donne la référence, le candidat, les identifiants des deux exécutions, les écarts par métrique, la tolérance et le verdict. Exige tenant_admin, developer, security_officer, auditor, viewer ou finops.

Route : /v1/evaluations/comparisons (GET).

Nom	Type	Défaut	Requis	Description
suite_id	str | None	None	non	Uniquement les comparaisons de cette suite (UUID).

Retour : Any. Réponse JSON décodée de l'opération « Lister les comparaisons A/B ».

Erreurs levées : les erreurs typées du transport (Erreurs).

EvaluationClient.list_redteam_runs

list_redteam_runs(**page: Any) -> Any

Lister les campagnes de red team. Liste les campagnes de red team du tenant, identifiant le plus récent d'abord, paginées, ainsi que probes : les sondes intégrées (identifiant et catégorie), les familles de sondes garak et si garak est installé. Ouvert à tout membre du tenant.

Route : /v1/redteam/runs (GET).

Nom	Type	Défaut	Requis	Description
**page	Any		non	Options de pagination transmises à la liste : limit (nombre maximal d'éléments par page) et cursor (le next_cursor de la page précédente). Itérer sur la page renvoyée suit tous les curseurs.

Retour : Any. Réponse JSON décodée de l'opération « Lister les campagnes de red team ».

Erreurs levées : les erreurs typées du transport (Erreurs).

EvaluationClient.list_runs

list_runs(suite_id: str | None = None, **page: Any) -> Any

Lister les exécutions d'évaluation. Liste les exécutions d'évaluation du tenant, identifiant le plus récent d'abord, paginées, éventuellement filtrées par suite et statut. Chaque élément suit le contrat d'évaluation (cible, moteur, jeu de données, métriques, résultats, statut, coût) avec run_id, suite_id, trigger, case_results et error. Ouvert à tout membre du tenant.

Route : /v1/evaluations/runs (GET).

Nom	Type	Défaut	Requis	Description
suite_id	str | None	None	non	Uniquement les exécutions de cette suite.
**page	Any		non	Options de pagination transmises à la liste : limit (nombre maximal d'éléments par page) et cursor (le next_cursor de la page précédente). Itérer sur la page renvoyée suit tous les curseurs.

Retour : Any. Réponse JSON décodée de l'opération « Lister les exécutions d'évaluation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

EvaluationClient.list_suites

list_suites(**page: Any) -> Any

Lister les suites d'évaluation. Liste les suites du tenant triées par nom, paginées, sous forme de documents du contrat d'évaluation ; cases donne le nombre de cas. Ouvert à tout membre du tenant.

Route : /v1/evaluations/suites (GET).

Nom	Type	Défaut	Requis	Description
**page	Any		non	Options de pagination transmises à la liste : limit (nombre maximal d'éléments par page) et cursor (le next_cursor de la page précédente). Itérer sur la page renvoyée suit tous les curseurs.

Retour : Any. Réponse JSON décodée de l'opération « Lister les suites d'évaluation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

EvaluationClient.redteam

redteam(target: dict[str, Any] | str, probes: list[str] | None = None, **extra: Any) -> Any

Lancer une campagne de red team. Envoie des sondes adverses à la cible et enregistre les constats. Exige tenant_admin, developer, security_officer ou ai_governance_officer.

Route : /v1/redteam/runs (POST).

Nom	Type	Défaut	Requis	Description
target	dict[str, Any] | str		oui	Cible attaquée : model, agent, prompt, rag_pipeline, skill ou tool.
probes	list[str] | None	None	non	Sondes à envoyer. Par défaut : toutes les sondes intégrées, ou promptinject et dan pour garak.
**extra	Any		non	Champs supplémentaires fusionnés dans le corps de la requête.

Retour : Any. Réponse JSON décodée de l'opération « Lancer une campagne de red team ».

Erreurs levées : les erreurs typées du transport (Erreurs).

EvaluationClient.run

run(suite_id: str, target: dict[str, Any] | str, **extra: Any) -> Any

Exécuter une suite d'évaluation. Exécute une suite maintenant et renvoie l'exécution terminée (201). Exige tenant_admin, developer, security_officer ou ai_governance_officer ou agent.

Route : /v1/evaluations/runs (POST).

Nom	Type	Défaut	Requis	Description
suite_id	str		oui	Suite à exécuter. Obligatoire sauf si trigger vaut promotion.
target	dict[str, Any] | str		oui	Cible à évaluer à la place de celle de la suite, par exemple une autre version. Obligatoire pour trigger: promotion sans suite.
**extra	Any		non	Champs supplémentaires fusionnés dans le corps de la requête.

Retour : Any. Réponse JSON décodée de l'opération « Exécuter une suite d'évaluation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

EvaluationClient.run_local

run_local(suite: dict[str, Any], target: Callable[[Any], Any]) -> SuiteResult

Exécute une suite localement avec :func:run_suite.

Nom	Type	Défaut	Requis	Description
suite	dict[str, Any]		oui	Suite {name, threshold, metrics, cases}, comme pour run_suite.
target	Callable[[Any], Any]		oui	Appelable qui reçoit l'input de chaque cas et dont la valeur de retour est notée.

Retour : SuiteResult. Un SuiteResult : exécution locale agrégée, moyenne par métrique et verdict de la porte.

Fonctions

exact_match

exact_match(output: Any, case: dict[str, Any]) -> float

Métrique : 1 si la sortie est égale à expected une fois les espaces retirés, sinon 0.

Nom	Type	Défaut	Requis	Description
output	Any		oui	Sortie de la cible ; tout ce qui n'est pas du texte est comparé en JSON trié.
case	dict[str, Any]		oui	Cas de la suite, lu pour expected.

Retour : float. Score 1.0 ou 0.0.

contains

contains(output: Any, case: dict[str, Any]) -> float

Métrique : part des chaînes contains (ou de expected) trouvées dans la sortie, sans tenir compte de la casse.

Nom	Type	Défaut	Requis	Description
output	Any		oui	Sortie de la cible ; tout ce qui n'est pas du texte est comparé en JSON trié.
case	dict[str, Any]		oui	Cas de la suite, lu pour contains (liste) ou expected.

Retour : float. Score entre 0 et 1 ; 0 si le cas ne donne aucune chaîne.

regex

regex(output: Any, case: dict[str, Any]) -> float

Métrique : 1 si le pattern du cas correspond quelque part dans la sortie, sinon 0.

Nom	Type	Défaut	Requis	Description
output	Any		oui	Sortie de la cible ; tout ce qui n'est pas du texte est recherché en JSON trié.
case	dict[str, Any]		oui	Cas de la suite, lu pour pattern (une expression régulière Python).

Retour : float. Score 1.0 ou 0.0.

json_valid

json_valid(output: Any, case: dict[str, Any]) -> float

Métrique : 1 si la sortie est un texte JSON valide (ou n'est pas du texte), sinon 0.

Nom	Type	Défaut	Requis	Description
output	Any		oui	Sortie de la cible.
case	dict[str, Any]		oui	Cas de la suite, non utilisé par cette métrique.

Retour : float. Score 1.0 ou 0.0.

json_schema

json_schema(output: Any, case: dict[str, Any]) -> float

Métrique : 1 si la sortie (analysée si c'est du texte) est valide selon le JSON Schema 2020-12 du cas.

Nom	Type	Défaut	Requis	Description
output	Any		oui	Sortie de la cible ; un texte qui n'est pas du JSON obtient 0.
case	dict[str, Any]		oui	Cas de la suite, lu pour schema.

Retour : float. Score 1.0 ou 0.0.

max_length

max_length(output: Any, case: dict[str, Any]) -> float

Métrique : 1 si la sortie compte au plus max_length caractères (10000 par défaut), sinon 0.

Nom	Type	Défaut	Requis	Description
output	Any		oui	Sortie de la cible ; tout ce qui n'est pas du texte est mesuré en JSON trié.
case	dict[str, Any]		oui	Cas de la suite, lu pour max_length.

Retour : float. Score 1.0 ou 0.0.

run_suite

run_suite(suite: dict[str, Any], target: Callable[[Any], Any]) -> SuiteResult

Exécute localement suite = {name, threshold, metrics, cases: [{id, input, expected, ...}]}.

Nom	Type	Défaut	Requis	Description
suite	dict[str, Any]		oui	Dict de suite : name, threshold (1 par défaut), metrics (["contains"] par défaut) et cases, chacun avec id, input et les champs lus par ses métriques.
target	Callable[[Any], Any]		oui	Appelable qui reçoit l'input de chaque cas ; une exception fait échouer ce seul cas.

Retour : SuiteResult. Un SuiteResult : exécution locale agrégée, moyenne par métrique et verdict de la porte.