Configuration LLM et surcharges de prompt

Ce que c'est

Le centre de contrôle qui régit la façon dont chaque appel de modèle est effectué — quel fournisseur / modèle, avec quels fallbacks, outils, échantillonnage, limites et façonnage du system-prompt, le tout sélectionné par call site.

Surface opérateur

  • Presets — llm_preset_list_v2, llm_preset_get_v2, llm_preset_create_v2, llm_preset_update, llm_preset_delete_v2, et llm_preset_simulate (résolution en dry-run pour un site).
  • Rattachement au site — llm_site_attach_preset, llm_site_detach_preset, llm_site_attached_preset, llm_preset_apply.
  • Modes (bundles atomiques) — llm_mode_list / _get / _create / _update / _delete, llm_mode_preview, llm_mode_apply, llm_mode_history.
  • Fournisseurs / identifiants / backends — llm_provider_list / _create / _test / _refresh_models, llm_credential_list / _create / _set_key / _quarantine / _set_coder_cap, llm_backend_list / _create, llm_config_set_fallback_chain, llm_config_set_max_turns, plus la famille historique llm_config_* et les snapshots (llm_snapshot_list / _get, et llm_call_explain qui réunit en un seul document le snapshot d'un appel et chacune de ses tentatives enregistrées — voir la recette 13 dans docs/MCP-COOKBOOK.md).

REST : LlmConfigController, LlmConfigModesController, LlmValidationController, LlmAvailabilityController.

Comment ça marche

Un preset (LlmPresetRecord) est un bundle composable, optionnellement hérité, regroupant des étapes de routage (LlmPresetStepRecord → RoutingChain / RoutingTarget avec fallbacks), une tool policy (politique d'outils), des profils d'échantillonnage et de limites, une surcharge de prompt (prompt overlay), et des bascules de capacités MCP (browser / emulator / windows). Une surcharge de prompt (PromptOverlayRecord) injecte ou supprime des experts nommés et ajoute un préfixe / suffixe de system-prompt personnalisé.

Les presets se rattachent aux call sites en écrivant une clé de configuration LLM.{SiteId}.Preset ; au moment du dispatch, le ProviderResolver la lit (en se rabattant sur LLM.{Family}:Default.Preset lorsqu'un site spécifique n'est pas rattaché) et résout le fournisseur / modèle concret. Ces catalogues résident dans le control-plane ; les modes (LlmConfigModeRecord) appliquent en une seule fois tout un ensemble de rattachements de sites, avec preview complet et historique. C'est le même chemin de résolution qu'utilisent les sites de planification des Agents et les nodes de call site des Workflows.

Savoir ce qui s'est réellement passé sur un appel

La configuration dit comment un appel aurait dû être effectué. La télémétrie d'appel, elle, dit ce qui s'est produit — et elle se lit sans rien connaître du schéma de stockage.

Chaque snapshot porte son propre dénouement. À côté de la configuration matérialisée, chaque snapshot — dans la liste, dans le détail comme dans le résultat de llm_preset_simulate — indique disposition et dispositionAt (comment et quand l'appel s'est terminé), correlationId (la chaîne à laquelle il appartenait), attemptCount et servedStepOrder (le nombre de tentatives et l'étape de la chaîne de fallback qui a finalement répondu), errorCode, resolutionRule et resolutionId (la règle qui a choisi le preset), writer, totalLatencyMs et estimatedCostUsd.

Les dispositions possibles sont served, failed, walled, refused_preflight, synthetic, cancelled, timed_out et orphaned. Une disposition absente signifie que l'appel est toujours en cours : une liste sans filtre ne se réduit donc pas à la somme de ces états.

Filtrer par dénouement. GET /api/v1/llm/snapshots accepte les filtres disposition et correlationId : « montre-moi ce qui a échoué sur ce site » tient en une requête au lieu d'un parcours page par page. Comme siteId, ces filtres fonctionnent en égalité stricte — il n'existe ni joker ni forme par préfixe.

L'historique des tentatives. GET /api/v1/llm/snapshots/{id}/attempts renvoie une ligne par tentative, dans l'ordre où le runtime les a essayées : dénouement, statut HTTP, détail de l'erreur, identifiant de requête côté fournisseur (celui à citer au support du fournisseur), identifiant et compte utilisés, fenêtre de rate limit consommée et heure de sa réinitialisation, latence jusqu'au premier token, compteurs de tokens de cache, heures de début et de fin. Une étape que la chaîne n'a jamais atteinte n'a aucune ligne : le nombre de lignes montre donc jusqu'où la chaîne de fallback est allée. Un snapshot sans tentative enregistrée renvoie une liste vide, ce qui reste distinct d'un snapshot inconnu.

llm_call_explain répond à la même question en un seul appel, là où il faudrait sinon enchaîner une liste, une lecture de détail et une lecture des tentatives.

Texte des prompts et frontière d'autorisation. L'historique des tentatives ne contient délibérément aucun texte de prompt ni de réponse — et c'est précisément pour cela qu'il est accessible à tout appelant autorisé : un opérateur peut suivre un appel en échec de bout en bout sans être exposé au contenu des conversations. Le texte des prompts et des réponses reste sur la route de détail du snapshot, protégée par la politique d'administration de tenant. Cette séparation est voulue : les champs nécessaires au diagnostic d'une panne ne sont pas ceux qui portent les données client, ils n'ont donc pas à partager le même niveau de permission.