Limites

L'API d'évaluations impose des limites pour garantir la stabilité du service lors d'évaluations volumineuses ou à fort fan-out. Ces limites sont fixées bien au-delà d'un usage classique, et la plupart des évaluations ne les atteignent jamais.

Cette page répertorie l'ensemble des limites, ce qui se passe lorsque vous en dépassez une et comment restructurer une évaluation dans ce cas.

Une requête qui dépasse la limite de taille du corps est rejetée avec une erreur 413. Un champ ou un enregistrement trop volumineux est rejeté avec une erreur 422 lors de la validation. Pour stocker de gros blobs (documents, images, transcriptions longues), référencez-les par URL ou par ID plutôt que de les intégrer directement dans un enregistrement.

Comment corriger chaque erreur :

• 413 : la requête entière dépasse la limite de taille du corps. Réduisez upload_batch_size pour envoyer moins d'enregistrements par requête.
• 422 sur un champ JSON : la limite de 1 Mo s'applique à chaque champ de chaque enregistrement, et non à un batch. Un batch plus petit n'y change rien : réduisez la taille du champ trop volumineux.

evaluation.run() et evaluation.optimize() téléchargent les résultats pendant leur exécution. Le SDK gère les échecs de téléchargement de deux manières :

• Payload non valide (400, 413 ou 422) : l'exécution s'arrête au premier téléchargement rejeté au lieu de traiter les enregistrements restants, et est marquée failed. L'erreur est levée telle quelle, quelle que soit la valeur de max_concurrency.
• Tout autre échec (erreurs réseau, 5xx et autres 4xx comme 401, 403, 404, 408, 409 ou 429) : le SDK relance le téléchargement. Un batch qui échoue encore après cinq tentatives fait échouer l'exécution. Pour modifier ce nombre, définissez la variable d'environnement MISTRAL_EVAL_UPLOAD_MAX_FAILED_ATTEMPTS (un entier d'au moins 1).

Lorsqu'un téléchargement ne reçoit aucune réponse (un timeout ou une erreur 504, par exemple), le serveur a peut-être déjà stocké le batch. Le SDK renvoie le même batch, inchangé, et considère qu'une erreur 409 lors de ce renvoi signifie « déjà téléchargé », de sorte que l'exécution se poursuit. Seule une erreur 409 avec le code d'erreur EVALUATION_RUN_OUTPUT_RECORD_CONFLICT (téléchargements d'enregistrements) ou EVALUATION_RUN_RETRY_CONFLICT (correctifs d'enregistrements en échec) est prise en compte : toute autre erreur 409 entraîne une nouvelle tentative, comme pour les autres erreurs 4xx ci-dessus. Un tel batch ne provoque jamais d'échec immédiat et n'est pas compté dans la limite de tentatives.

Les appels à l'API d'évaluations utilisent un timeout d'au moins 60 secondes. Un timeout plus long défini via Mistral(timeout_ms=...) s'applique toujours.

Un appel API qui échoue lève une ObservabilityAPIError avec status_code, error_code et details. Pour les échecs de validation (422), le message indique les champs en cause et details les liste sous forme d'entrées {"loc": [...], "msg": "..."} :

API request failed with status 422 (VALIDATION_ERROR): records.0.input: JSON field exceeds the maximum allowed size of 1000000 bytes

API request failed with status 422 (VALIDATION_ERROR): records.0.input: JSON field exceeds the maximum allowed size of 1000000 bytes

Les valeurs soumises ne sont jamais incluses ni dans le message, ni dans details, ni dans les logs de debug du SDK.

from mistralai.evaluations import ObservabilityAPIError

try:
    ...
except ObservabilityAPIError as error:
    print(error.status_code, error.error_code, error.details)

from mistralai.evaluations import ObservabilityAPIError

try:
    ...
except ObservabilityAPIError as error:
    print(error.status_code, error.error_code, error.details)

Une erreur 403 indique l'autorisation manquante, au lieu de vous demander de vérifier la clé API, ce qui prêtait à confusion pour un compte de service qui ne possède pas de clé. L'erreur reste une ObservabilityAPIError. Son message précise l'appelant (utilisateur ou compte de service), les autorisations concernées (évaluations hors ligne, ensembles de données ou juges) ainsi que la marche à suivre pour corriger le problème sur un déploiement managé de workflow : exécuter le workflow avec on_behalf_of=True, ou accorder le rôle offline_evaluations_manager au compte de service du déploiement (requested_roles dans l'API de déploiement, service_account_roles dans Mistral MCP). Il inclut également le détail fourni par le serveur lorsqu'il y en a un. Voir Déploiements managés. Cela nécessite le SDK 0.10.0+.

Une erreur 5xx lors d'un téléchargement lève une ObservabilityUnknownOutcomeError : le serveur a peut-être stocké les données, ou non. Il s'agit d'une sous-classe de ObservabilityAPIError, donc un bloc except ObservabilityAPIError l'intercepte également.

Une exécution d'évaluation se traduit par records × generations × evaluators lignes de scores, chaque facteur est donc plafonné :

Le dépassement de l'une de ces limites renvoie une erreur 422 : soit une erreur « list too long », soit, pour les totaux par exécution, une erreur de validation indiquant le nombre actuel et le maximum.

Le SDK effectue les téléchargements par batch pour vous, vous n'avez donc normalement pas à gérer cela. Si vous appelez l'API directement, maintenez chaque requête dans ces limites.

Le plafond d'évaluateurs par exécution (250) est la limite la plus susceptible d'affecter une évaluation qui note de nombreux nœuds ou branches d'un graphe de workflow.

Un anti-pattern courant consiste à utiliser un évaluateur par nœud. Par exemple, une métrique accuracy divisée en accuracy/MyWorkflow::node_1, accuracy/MyWorkflow::node_2 et ainsi de suite. Cette approche attache des centaines d'évaluateurs à chaque enregistrement, alors que chaque enregistrement n'utilise que quelques nœuds. La plupart des lignes de scores obtenues sont des placeholders vides.

À la place, utilisez un évaluateur par métrique, avec le nœud comme dimension dans le metadata du score (ou dans le name du score). Émettez un score uniquement pour les nœuds qu'un enregistrement utilise réellement. Vous conservez le même découpage par nœud, restez bien en dessous du plafond et évitez de créer des milliers de scores vides.

Ces valeurs sont des paramètres par défaut côté serveur destinés à protéger l'infrastructure partagée. Si votre cas d'utilisation nécessite une limite plus élevée, contactez votre représentant Mistral plutôt que de contourner ces limites.

• Référence API : paramètres de evaluation.run(), dont upload_batch_size.
• Limites du plugin d'évaluation de workflow : les limites supplémentaires qui s'appliquent lorsqu'une évaluation s'exécute dans un workflow.