> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fim.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Compatibilité des fournisseurs LLM
> Comment FIM One achemine les appels LLM, l'architecture tool_choice et les pièges spécifiques aux fournisseurs — en particulier la réflexion Anthropic + AWS Bedrock.
## Détection du fournisseur
FIM One utilise LiteLLM comme adaptateur universel. La fonction `_resolve_litellm_model()` dans `core/model/openai_compatible.py` mappe l'`LLM_BASE_URL` + `LLM_MODEL` de l'utilisateur à un identifiant de modèle LiteLLM avec un préfixe de fournisseur. Le préfixe détermine comment LiteLLM achemine la requête — protocole API natif (Anthropic Messages API, Gemini, etc.) ou générique OpenAI-compatible `/v1/chat/completions`.
Ordre de résolution :
1. **Fournisseur explicite** (champ DB `ModelConfig.provider`) — priorité la plus élevée. Si le fournisseur correspond à un domaine connu dans l'URL, aucun `api_base` n'est renvoyé (LiteLLM achemine nativement). Sinon, `api_base` est défini sur l'URL de relais.
2. **Correspondance de domaine** par rapport à `KNOWN_DOMAINS` — les points de terminaison API officiels sont reconnus par nom d'hôte.
3. **Indice de chemin d'URL** par rapport à `PATH_PROVIDER_HINTS` — courant sur les plateformes de relais comme UniAPI où `/claude` ou `/anthropic` dans le chemin indique le protocole en amont.
4. **Secours** — préfixe `openai/` (générique OpenAI-compatible).
| Domaine / Chemin | Préfixe du fournisseur | Protocole |
| -------------------------------------------- | ---------------------- | ----------------------------------- |
| `api.openai.com` | `openai/` | OpenAI Chat Completions |
| `anthropic.com` | `anthropic/` | Anthropic Messages API |
| `generativelanguage.googleapis.com` | `gemini/` | Google Gemini |
| `api.deepseek.com` | `deepseek/` | DeepSeek (OpenAI-compatible) |
| `api.mistral.ai` | `mistral/` | Mistral |
| Le chemin contient `/claude` ou `/anthropic` | `anthropic/` | Anthropic Messages API (via relais) |
| Le chemin contient `/gemini` | `gemini/` | Google Gemini (via relais) |
| Tout le reste | `openai/` | Générique OpenAI-compatible |
Lorsque le préfixe du fournisseur est un protocole natif (anthropic, gemini, etc.) et que l'URL n'est pas le point de terminaison officiel, LiteLLM utilise le protocole natif mais envoie les requêtes à l'`api_base` du relais. Cela signifie que les comportements spécifiques au fournisseur — y compris le problème de prefill Bedrock décrit ci-dessous — s'appliquent indépendamment du fait que la requête aille à l'API officielle ou via un relais.
Si votre URL de relais contient `/claude` dans le chemin, FIM One achemine automatiquement via le protocole natif d'Anthropic. C'est généralement correct (meilleur streaming, support de la réflexion), mais cela signifie que les comportements spécifiques au fournisseur s'appliquent — y compris le problème de prefill Bedrock décrit ci-dessous.
## tool\_choice — les quatre modes
Le paramètre `tool_choice` est standardisé via le format OpenAI. LiteLLM le traduit vers le protocole natif de chaque fournisseur avant d'envoyer la requête.
| Mode | Signification | Support des fournisseurs |
| --------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `"auto"` | Le modèle décide s'il faut appeler un outil ou répondre avec du texte | Tous les fournisseurs |
| `"required"` | Doit appeler un outil, mais le modèle choisit lequel | La plupart des fournisseurs |
| `{"type":"function","function":{"name":"X"}}` | Doit appeler la fonction X spécifiquement | La plupart des fournisseurs — **incompatible avec la réflexion Anthropic** |
| `"none"` | Impossible d'utiliser les outils, texte uniquement | Tous les fournisseurs |
La distinction entre `"auto"` et forcé (`{"type":"function",...}`) est au cœur de chaque problème de compatibilité dans FIM One. Ces deux modes sont utilisés par des sous-systèmes complètement différents avec des exigences différentes.
## Où tool\_choice est utilisé
Deux sous-systèmes utilisent `tool_choice`, et ils l'utilisent de manières fondamentalement différentes.
### Moteur ReAct — tool\_choice="auto"
La boucle ReAct nécessite que le modèle décide à chaque itération : appeler un outil ou donner une réponse finale. Seul `"auto"` a du sens ici — le modèle choisit librement entre produire des `tool_calls` ou du contenu textuel. Ceci est compatible avec tous les fournisseurs, tous les modèles et tous les modes, y compris la réflexion étendue.
```mermaid theme={null}
flowchart TD
A["Itération ReAct"] --> B{"Le modèle décide
(tool_choice=auto)"}
B -->|"tool_calls présents"| C["Exécuter l'outil → itération suivante"]
B -->|"contenu textuel uniquement"| D["Réponse finale"]
```
Le moteur ReAct utilise l'appel de fonction natif (`_run_native`) quand `abilities["tool_call"] = True`, en se repliant sur le mode JSON-dans-le-contenu (`_run_json`) sinon. Les deux modes utilisent `"auto"` — la différence est que les outils sont passés via le paramètre `tools` ou décrits dans l'invite système. Voir [Moteur ReAct — Exécution en mode dual](/architecture/react-engine#dual-mode-execution) pour plus de détails.
### structured\_llm\_call — tool\_choice=forced
Extraction structurée en une seule tentative (annotation de schéma, planification DAG, analyse de plan). Force le modèle à appeler une fonction virtuelle spécifique, garantissant une sortie JSON structurée. C'est le site d'appel qui déclenche les erreurs spécifiques au fournisseur.
`structured_llm_call` implémente une chaîne de dégradation à 3 niveaux :
```mermaid theme={null}
flowchart TD
START["structured_llm_call()"] --> L1{"abilities.tool_call
AND tool_choice?"}
L1 -->|Both true| FC["Level 1: native_fc
forced tool_choice"]
L1 -->|Either false| L2
FC -->|"Success"| DONE["Return StructuredCallResult"]
FC -->|"Fail (catch Exception)"| L2{"abilities.json_mode?"}
L2 -->|Yes| JM["Level 2: json_mode
response_format=json_object"]
L2 -->|No| PT["Level 3: plain_text
extract JSON from free text"]
JM -->|"Success"| DONE
JM -->|"Fail → retry once"| PT
PT -->|"Success"| DONE
PT -->|"Fail → retry once"| ERR["StructuredOutputError
or default_value"]
```
La différence de conception critique : le fallback de `structured_llm_call` est **runtime** — il essaie dynamiquement chaque niveau et capture les exceptions pour passer au suivant. La sélection de mode du moteur ReAct est **build-time** — elle vérifie `_native_mode_active` une seule fois au démarrage et s'engage dans un mode pour l'ensemble de la boucle. Cela signifie que `structured_llm_call` peut récupérer de manière transparente des erreurs 400 spécifiques au fournisseur, tandis que ReAct s'appuie sur le fait que le mode soit correctement choisi dès le départ.
## Le piège du prefill Bedrock
Lorsque `response_format={"type":"json_object"}` est transmis pour un modèle résolu avec le préfixe `anthropic/`, LiteLLM injecte en interne un message d'assistant prefill pour simuler le mode JSON. L'API Messages d'Anthropic n'a pas de paramètre `response_format` natif, donc LiteLLM l'approxime en ajoutant une accolade ouvrante comme contenu d'assistant :
```json theme={null}
{"role": "assistant", "content": "{"}
```
Cela fonctionne sur l'API directe d'Anthropic. Cependant, les versions plus récentes des modèles AWS Bedrock rejettent toute conversation dont le dernier message a `role: "assistant"` — ils appellent cela « assistant message prefill » et lèvent :
```
ValidationException: This model does not support assistant message prefill.
The conversation must end with a user message.
```
Cette erreur se produit uniquement lorsque **les trois conditions** sont remplies simultanément :
1. Le modèle est résolu avec le préfixe `anthropic/` (via correspondance de domaine ou indice de chemin URL).
2. `response_format={"type":"json_object"}` est transmis (le chemin de code json\_mode dans `structured_llm_call`).
3. Le backend réel est AWS Bedrock (qui rejette le prefill).
**Bedrock via endpoint compatible OpenAI ?** Si votre relais Bedrock expose un endpoint `/v1/chat/completions` compatible OpenAI (soit la passerelle compatible OpenAI d'AWS elle-même, soit un proxy tiers), et que le chemin URL ne contient **pas** `/claude` ou `/anthropic`, FIM One le résout avec le préfixe `openai/`. LiteLLM traite alors le backend comme un serveur standard compatible OpenAI, transmet `response_format` directement sans injecter de prefill, et le serveur gère la contrainte JSON nativement. **Le piège du prefill ne s'applique pas** — vous n'avez pas besoin de définir `json_mode_enabled=false`.
Cela n'affecte **pas** l'appel d'outil natif (`tool_choice="auto"` avec le paramètre `tools=`). L'injection de prefill se produit uniquement pour `response_format`. L'exécution de l'agent ReAct n'est complètement pas affectée.
Si le Niveau 1 (native\_fc) et le Niveau 2 (json\_mode) échouent tous deux sur Bedrock, le système se rétablit au Niveau 3 (plain\_text). Le drapeau `json_mode_enabled` décrit ci-dessous élimine l'appel gaspillé du Niveau 2.
### Le correctif : json\_mode\_enabled
Un indicateur `json_mode_enabled` par modèle contrôle si le Niveau 2 (json\_mode) est jamais tenté :
* **Modèles configurés via BD** : basculer dans Admin → Models → Advanced settings. L'indicateur est stocké sur `ModelProviderModel.json_mode_enabled` (par défaut `TRUE`).
* **Modèles configurés via ENV** : définir `LLM_JSON_MODE_ENABLED=false` dans votre environnement.
* **Effet** : lorsque désactivé, `abilities["json_mode"]` retourne `False` → `response_format` n'est jamais passé → pas de prefill → Bedrock fonctionne. La chaîne de dégradation devient `native_fc → plain_text`, en ignorant entièrement l'appel json\_mode voué à l'échec.
* **Aucune perte de qualité** : le modèle retourne toujours du JSON valide car le system prompt l'impose. Le niveau plain\_text utilise `extract_json()` pour analyser le JSON à partir de contenu libre, ce qui fonctionne de manière fiable avec les modèles modernes.
## Modèles de réflexion + forced tool\_choice
Certains modèles ont la réflexion étendue (chaîne de pensée) activée de manière permanente. Leurs API rejettent le `tool_choice` forcé car forcer un appel de fonction spécifique contredit la liberté du modèle de raisonner d'abord :
```
tool_choice 'specified' is incompatible with thinking enabled
```
Anthropic applique cette contrainte au niveau du protocole, et certains autres fournisseurs (par exemple Moonshot AI / Kimi K2.5) suivent le même modèle.
Pour les modèles Anthropic, `structured_llm_call` gère cela automatiquement en passant `reasoning_effort=None` lors de l'appel de native\_fc, désactivant la réflexion étendue pour cet appel spécifique. Les appels de sortie structurée ont besoin de **conformité au schéma**, pas de réflexion profonde — désactiver la réflexion ici est à la fois correct et bénéfique (latence plus faible, coût plus faible).
Cependant, certains modèles (par exemple Kimi K2.5) ont la réflexion activée de manière permanente sans aucun moyen de la désactiver de l'extérieur. Pour ces modèles, native\_fc échoue toujours avec une erreur 400, ajoutant environ 10 secondes de latence gaspillée par appel structuré avant que la chaîne de dégradation ne passe à json\_mode.
### Le correctif : tool\_choice\_enabled
Un drapeau `tool_choice_enabled` par modèle contrôle si le Niveau 1 (native\_fc) est jamais tenté :
* **Modèles configurés en BD** : basculer dans Admin → Models → Advanced → "Native Function Calling". Le drapeau est stocké sur `ModelProviderModel.tool_choice_enabled` (par défaut `TRUE`).
* **Modèles configurés par ENV** : définissez `LLM_TOOL_CHOICE_ENABLED=false` dans votre environnement.
* **Effet** : lorsque désactivé, `abilities["tool_choice"]` retourne `False` → la chaîne de dégradation commence au Niveau 2 (json\_mode) ou Niveau 3 (plain\_text), en ignorant complètement native\_fc. Cela élimine la pénalité d'\~10s par appel structuré pour les modèles incompatibles.
* **Agent ReAct non affecté** : `tool_choice_enabled` contrôle uniquement la sélection d'outil forcée dans `structured_llm_call`. Le moteur ReAct utilise `tool_choice="auto"` (le modèle décide librement), qui fonctionne avec tous les modèles indépendamment de ce paramètre.
`tool_choice_enabled` et `tool_call` sont des drapeaux de capacité distincts. `tool_call` (toujours `True` pour `OpenAICompatibleLLM`) contrôle si les outils sont transmis au modèle du tout — le désactiver casserait l'agent ReAct. `tool_choice` contrôle uniquement si la sélection d'outil **forcée** est tentée pour l'extraction de sortie structurée.
`tool_choice="auto"` n'est pas affecté par le mode de réflexion. Le moteur ReAct utilise `"auto"` exclusivement, donc l'exécution de l'agent fonctionne avec la réflexion activée.
Ne définissez PAS `abilities["tool_call"] = False` pour éviter cette contrainte. Cela désactiverait le mode `_run_native` de ReAct (qui utilise `tool_choice="auto"` et fonctionne bien avec la réflexion), le forçant dans le mode `_run_json` moins fiable.
**Note de migration de fournisseur :** Certains relais tiers suppriment silencieusement les paramètres non supportés comme `reasoning_effort` (`drop_params=True`), donc la réflexion n'est jamais activée même si configurée. Lors de la migration vers un fournisseur qui supporte correctement la réflexion (Bedrock, API Anthropic directe), le `reasoning_effort=None` dans native\_fc assure un comportement cohérent. Aucune action utilisateur n'est nécessaire — la sortie structurée fonctionne de manière identique sur tous les fournisseurs.
## Référence rapide : ce qui fonctionne où
| Scénario | Mode ReAct | Chemin structured\_llm\_call | Notes |
| -------------------------------------------- | ------------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
| OpenAI (n'importe quel modèle) | `_run_native` | native\_fc | Support complet |
| Anthropic (sans thinking) | `_run_native` | native\_fc | Support complet |
| Anthropic + thinking | `_run_native` | native\_fc (thinking auto-désactivé) | Thinking désactivé pour la sortie structurée uniquement |
| Relais Bedrock (sans thinking) | `_run_native` | native\_fc | Support complet |
| Relais Bedrock + thinking | `_run_native` | native\_fc (thinking auto-désactivé) | Thinking désactivé pour la sortie structurée uniquement |
| Bedrock via endpoint compatible OpenAI | `_run_native` | native\_fc | Support complet — pas de problème de prefill ; voir le conseil ci-dessus |
| Gemini | `_run_native` | native\_fc | Support complet |
| DeepSeek (non-thinking) | `_run_native` | native\_fc | Support complet |
| DeepSeek R1 (thinking) | `_run_native` | json\_mode (définir `tool_choice_enabled=false`) | Thinking toujours activé ; ignorer native\_fc |
| Kimi K2 (non-thinking) | `_run_native` | native\_fc | Support complet |
| Kimi K2.5 (thinking) | `_run_native` | json\_mode (définir `tool_choice_enabled=false`) | Thinking toujours activé ; ignorer native\_fc |
| OpenAI-compatible générique | `_run_native` | native\_fc | Support complet |
| N'importe quel modèle avec `tool_call=false` | `_run_json` | json\_mode ou plain\_text | Secours pour les modèles sans support d'appel d'outil |
## Configuration recommandée par modèle
`tool_choice_enabled` et `json_mode_enabled` peuvent tous deux être activés/désactivés par modèle dans Admin → Models → Advanced settings. Les valeurs par défaut (tous deux `TRUE`) fonctionnent pour la plupart des fournisseurs. Ajustez uniquement si vous rencontrez des erreurs ou une latence inutile.
| Type de modèle | FC natif | Mode JSON | Raison |
| -------------------------- | -------- | --------- | ------------------------------------------------------- |
| Série OpenAI GPT | ON | ON | Support complet — les valeurs par défaut sont correctes |
| Anthropic Claude | ON | ON | Thinking auto-désactivé pour native\_fc |
| Google Gemini | ON | ON | Support complet |
| DeepSeek V3 / Coder | ON | ON | Support complet |
| **DeepSeek R1 (thinking)** | **OFF** | ON | Thinking toujours activé ; native\_fc rejeté |
| **Kimi K2.5 (thinking)** | **OFF** | ON | Thinking toujours activé ; native\_fc rejeté |
| Kimi K2 (non-thinking) | ON | ON | Support complet |
| **Relais AWS Bedrock** | ON | **OFF** | Bedrock rejette le prefill assistant en json\_mode |
| Modèles faibles / petits | OFF | OFF | Aller directement à l'extraction plain\_text |
**Quand changer :** si vous voyez des avertissements `structured_llm_call: native_fc call raised` dans vos logs suivis d'une extraction json\_mode réussie, le modèle ne bénéficie pas de native\_fc. Désactivez « Native Function Calling » pour ce modèle afin d'éliminer l'appel API gaspillé (\~10s par demande de sortie structurée).
**Les remplacements au niveau ENV** s'appliquent à tous les modèles configurés via des variables d'environnement (pas l'interface admin) :
```bash theme={null}
# Disable native_fc globally (for thinking-model-only deployments)
LLM_TOOL_CHOICE_ENABLED=false
# Disable json_mode globally (for Bedrock relay deployments)
LLM_JSON_MODE_ENABLED=false
```
## Effort de raisonnement et configuration de la réflexion
FIM One expose deux variables d'environnement pour contrôler la réflexion étendue / le raisonnement :
| Variable | Valeurs | Effet |
| ----------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LLM_REASONING_EFFORT` | `low`, `medium`, `high` | Passé en tant que `reasoning_effort` à LiteLLM. Anthropic : mappé au paramètre `thinking`. OpenAI o-series : passé directement. Autres : silencieusement supprimé (`drop_params=True`). |
| `LLM_REASONING_BUDGET_TOKENS` | entier (ex. `10000`) | Anthropic uniquement : définit un plafond explicite `thinking.budget_tokens`, contournant le mappage automatique de LiteLLM. Utile pour contrôler les coûts sur les modèles Claude. |
Lorsque `reasoning_effort` est défini et que le modèle est résolu en tant que `anthropic/`, deux comportements supplémentaires s'appliquent :
1. **La température est forcée à 1.0.** Bedrock rejette `temperature != 1.0` lorsque la réflexion est activée. FIM One gère cela automatiquement — aucune action utilisateur nécessaire.
2. **GPT-5.x avec outils** : `reasoning_effort` est silencieusement supprimé lorsque des `tools` sont présents, car le point de terminaison GPT-5 `/v1/chat/completions` rejette la combinaison. Cela n'affecte que la boucle d'outil ReAct ; les appels `structured_llm_call` qui manquent d'un paramètre `tools` ne sont pas affectés.
## Analyse défensive pour la sortie structurée
Même avec native\_fc fonctionnant correctement, le pipeline de sortie structurée inclut une couche d'analyse défensive pour gérer les cas limites de n'importe quel fournisseur ou couche de compatibilité.
L'analyseur `_dict_to_steps` du planificateur DAG gère trois cas limites courants :
1. **Objet unique au lieu de tableau.** Certains modèles retournent `{"steps": {"id": "1", "task": "..."}}` (un objet d'étape unique) au lieu de `{"steps": [{"id": "1", "task": "..."}]}` (un tableau). L'analyseur détecte cela en vérifiant la présence de clés `id` ou `task` et enveloppe l'objet dans une liste.
2. **Chaîne JSON double-encodée.** Lorsque la sortie structurée revient à json\_mode (qui manque d'application de schéma), certains fournisseurs retournent la valeur `steps` comme chaîne JSON plutôt que comme tableau natif — par exemple, `{"steps": "[{\"id\": \"1\", ...}]"}`. Cette chaîne peut également contenir des sauts de ligne littéraux (du formatage du modèle) qui cassent le `json.loads` standard. L'analyseur utilise `extract_json_value()` (qui inclut `_repair_json_strings`) pour gérer :
* Les sauts de ligne littéraux à l'intérieur des valeurs de chaîne JSON
* Les séquences d'échappement invalides (courantes avec le contenu LaTeX ou de code)
* Autres particularités de sérialisation des couches de compatibilité
3. **Enveloppe `steps` manquante.** Le modèle peut retourner une seule étape comme objet de niveau supérieur sans la clé d'enveloppe `steps`. L'analyseur détecte `id` et `task` au niveau racine et enveloppe en conséquence.
En fonctionnement normal, native\_fc retourne des arguments d'appel d'outil correctement structurés et ces cas limites ne se produisent pas. Les analyseurs défensifs existent comme filet de sécurité pour les sous-classes `BaseLLM` personnalisées, les comportements inhabituels des fournisseurs, ou les scénarios de secours où la sortie structurée se dégrade en json\_mode ou plain\_text.
## Mise en cache des prompts (multi-fournisseur)
FIM One implémente la mise en cache explicite des prompts d'Anthropic via des points de rupture `cache_control` et bénéficie simultanément de la mise en cache automatique des préfixes de tous les autres fournisseurs grâce au **Registre des sections de prompts**. L'objectif est un chemin unique d'assemblage des prompts qui fonctionne sur tous les fournisseurs sans divergence de forme de prompt par appel.
### Architecture
Le module `fim_one.core.prompt` expose trois primitives :
* **`PromptSection`** — un fragment nommé avec soit un `content: str` statique, soit un `content: Callable` dynamique
* **`PromptRegistry`** — un magasin mémoïsé (les sections statiques se rendent une fois, les sections dynamiques se re-rendent par appel)
* **`DYNAMIC_BOUNDARY`** — un marqueur sentinel que le registre insère entre la dernière section statique et la première dynamique, afin que les appelants puissent diviser le prompt rendu au point de rupture du cache
Les prompts système pour ReAct (mode JSON, mode d'appel de fonction natif, synthèse) sont divisés en :
* **Préfixe statique** (\~95% du prompt) — identité, directives principales, descriptions d'outils
* **Suffixe dynamique** — date/heure actuelle, directive de langue par requête, contexte de transfert
### Détection des capacités
`fim_one.core.prompt.caching.is_cache_capable(model_id)` retourne `True` quand l'ID du modèle contient l'un des éléments suivants : `claude`, `anthropic`, `bedrock/anthropic`, `vertex_ai/claude`. Ces fournisseurs reçoivent **deux** messages avec `role="system"` et `cache_control: {"type": "ephemeral"}` sur le premier message (statique).
Tous les autres fournisseurs reçoivent un **seul** message système concaténé sans champ `cache_control` — cela est nécessaire car les points de terminaison non-Anthropic rejettent soit le champ, soit le suppriment silencieusement, et l'envoyer via certains relais provoque des erreurs `400 unknown parameter`.
### Couverture multi-fournisseurs
| Fournisseur | Mécanisme | Réduction de lecture | Notre gestion |
| -------------------------------- | -------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------- |
| **Anthropic Claude** (3, 3.5, 4) | `cache_control` explicite | 0.10× | Deux messages système avec point d'arrêt éphémère |
| **AWS Bedrock Anthropic** | Transmission du cache Anthropic | 0.10× | Identique à Anthropic |
| **GCP Vertex AI Claude** | Transmission du cache Anthropic | 0.10× | Identique à Anthropic |
| **OpenAI GPT / o-series** | Hash de préfixe automatique (≥1024 tokens) | 0.50× | Préfixe stable en octets via Section Registry → hit automatique |
| **DeepSeek (v3 / R1)** | Cache de préfixe automatique sauvegardé sur disque | 0.10× | Identique à OpenAI |
| **Moonshot Kimi (K1/K2)** | Cache de préfixe automatique | 0.10×/0.50× | Identique |
| **ZhipuAI GLM-4.5+** | Cache de long contexte automatique | 0.20× | Identique |
| **Grok (xAI)** | Cache de préfixe automatique | 0.25× | Identique |
| **Google Gemini** | API `createCachedContent` séparée | 0.25× | **Pas encore implémenté** — suivi sur la feuille de route v0.9 en tant que `GeminiCacheAdapter` |
| **Mistral / Cohere** | Pas de cache natif | N/A | N/A |
Le `PromptRegistry` bénéficie à chaque fournisseur avec mise en cache de préfixe automatique « gratuitement » — en gardant la portion statique identique en octets entre les appels (la date/heure actuelle se trouve dans le suffixe dynamique, pas le préfixe), le hash de chaque fournisseur avec mise en cache automatique correspond et atteint son cache. C'est pourquoi le Registry est une victoire fondamentale indépendante du modèle, même avant de considérer le `cache_control` spécifique à Anthropic.
### Observabilité
Chaque réponse `chat/*` inclut maintenant dans sa `done_payload` :
```json theme={null}
"cache": {
"read_tokens": 1067,
"creation_tokens": 0
}
```
`TurnProfiler` émet une ligne de journal structurée par tour : `turn_cache summary | model=claude-sonnet-4-6 | read_tokens=1067 | create_tokens=0 | saved_input_tokens=961 (~90%)`. Cela fonctionne également comme une **sonde d'honnêteté de relais** — si vous routez via un relais API, comparez les entrées réellement facturées par rapport à `read_tokens` pour détecter si le relais supprime `cache_control` ou conserve la réduction de 0,10×.
Aucune estimation en dollars n'est retournée au niveau du LLM — la tarification et la majoration du relais sont appliquées au-dessus, donc la couche LLM retourne uniquement les comptages de tokens objectifs.
### ROI du cache multi-tour
Mesuré sur les tours Claude 4 ReAct avec l'invite d'agent par défaut :
| Mode | Tokens de préfixe statique | Tokens de suffixe dynamique | Ratio de cache |
| -------------------------- | -------------------------- | --------------------------- | -------------- |
| Mode JSON, sans outils | \~753 | \~46 | 94,2 % |
| Mode JSON avec \~10 outils | \~1067 | \~46 | 95,9 % |
| Appel de fonction natif | \~523 | \~46 | 91,9 % |
Une exécution ReAct de 10 itérations avec 10 outils économise \~8 640 tokens d'entrée par tour après le premier (9 accès au cache × 1067 tokens × 90 %). Anthropic facture 1,25× pour l'écriture du cache au premier appel, donc le seuil de rentabilité se situe au **deuxième** appel — les requêtes à un seul tour n'en bénéficient pas.
## Politique de relecture du raisonnement (exactitude sans modèle)
Les blocs de réflexion étendue / raisonnement se comportent différemment selon les fournisseurs. Une politique de sérialisation uniforme rompt à la fois les contrats de protocole et les caches de préfixe automatiques. `fim_one.core.prompt.reasoning.reasoning_replay_policy(model_id)` retourne l'une des trois valeurs et contrôle `ChatMessage.to_openai_dict(replay_policy=...)` dans `OpenAICompatibleLLM._build_request_kwargs()`.
### Trois politiques
* **`anthropic_thinking`** — Famille Claude (y compris `anthropic/`, `bedrock/anthropic`, `vertex_ai/claude`). Les blocs de réflexion DOIVENT être rejoués avec `signature` attachée ; Anthropic rejette les tours suivants si la signature est manquante ou modifiée.
* **`informational_only`** — modèles qui émettent CoT mais n'attendent PAS de rejouer : DeepSeek R1 / R1-Distill, Qwen QwQ, Gemini 2.x thinking, OpenAI o1 / o3 / o4. Leur documentation dit explicitement « n'envoyez pas `reasoning_content` dans l'historique des messages ». L'envoyer quand même :
* Viole le contrat du fournisseur (peut commencer à rejeter dans les versions futures)
* **Invalide silencieusement leur cache de préfixe automatique** — les octets du message mutent à chaque tour, cassant le hash
* **`unsupported`** — modèles sans capacité de réflexion (GPT-4o, GPT-4 Turbo, Gemini 1.5, Mistral, Llama). Pas de CoT à rejouer ; le champ ne devrait jamais apparaître. Cette politique est aussi le défaut sûr pour les identifiants de modèle inconnus.
### Application
Toute l'évaluation des politiques se fait en un seul endroit (`_build_request_kwargs`). `ChatMessage.to_openai_dict(replay_policy=None)` préserve la valeur par défaut permissive A3 afin que les appelants non coordonnés ne régressent pas. La matrice de test multi-fournisseurs se trouve dans `tests/test_reasoning_replay_policy.py` avec des **assertions inverses** prouvant que les requêtes non-Anthropic ne divulguent PAS `reasoning_content`.
### Pour les utilisateurs
Le comportement des fonctionnalités et des bugs est automatique — vous n'avez besoin de configurer quoi que ce soit. Implications du flux de travail :
* **Si vous basculez entre les agents Claude et DeepSeek dans la même conversation**, l'historique est stocké avec les blocs de réflexion intacts ; au tour suivant, la forme du message sortant s'adapte selon le modèle actuel.
* **Si vous utilisez un proxy / une sous-classe `BaseLLM` personnalisée**, assurez-vous que son identifiant de modèle est reconnaissable (contient l'un des fragments) ou la politique `unsupported` par défaut s'appliquera — ce qui est sûr mais signifie que Claude derrière un proxy inhabituel pourrait perdre la relecture de la réflexion. Ajoutez le fragment d'identifiant de modèle à `_CACHE_CAPABLE_MODEL_FRAGMENTS` (dans `core/prompt/caching.py`) et/ou à la recherche de politique de réflexion.
## Dépannage
**« Ce modèle ne supporte pas le remplissage préalable des messages d'assistant »**
Bedrock + json\_mode. Deux solutions : (1) définir `LLM_JSON_MODE_ENABLED=false` ou désactiver le mode JSON dans les paramètres du modèle d'administration ; ou (2) si votre fournisseur Bedrock propose un point de terminaison compatible OpenAI `/v1/chat/completions`, basculer vers celui-ci — FIM One le résout en tant que `openai/` et l'injection de remplissage préalable ne se produit jamais.
**« La réflexion peut ne pas être activée lorsque tool\_choice force l'utilisation d'outils »** / **« tool\_choice 'specified' est incompatible avec la réflexion activée »**
Pour les modèles Anthropic, `structured_llm_call` désactive automatiquement la réflexion pour les appels native\_fc. Pour les autres fournisseurs avec réflexion toujours active (par exemple Kimi K2.5), désactiver « Native Function Calling » dans les paramètres avancés du modèle, ou définir `LLM_TOOL_CHOICE_ENABLED=false` globalement. La chaîne de dégradation ignorera native\_fc et extraira la sortie structurée via json\_mode ou plain\_text à la place.
**« Échec du pipeline DAG : le champ 'steps' du LLM n'est pas un tableau »**
Le LLM a renvoyé le champ `steps` sous forme de chaîne ou d'objet unique au lieu d'un tableau. Cela signifie généralement que la sortie structurée est tombée en json\_mode (qui manque d'application de schéma). Vérifier le journal pour `structured_llm_call: level=xxx` — s'il affiche `json_mode` au lieu de `native_fc`, native\_fc échoue silencieusement. Si vous utilisez une sous-classe `BaseLLM` personnalisée, vérifier qu'elle accepte l'argument `reasoning_effort`.
**ReAct bascule vers le mode JSON de manière inattendue**
Vérifier que `abilities["tool_call"]` du modèle est `True`. C'est toujours `True` pour `OpenAICompatibleLLM`, mais une sous-classe `BaseLLM` personnalisée pourrait l'ignorer. Vérifier avec le point de terminaison de détail du modèle dans l'API d'administration.
**structured\_llm\_call épuise tous les niveaux et lève StructuredOutputError**
Le modèle n'a pas pu produire de JSON analysable à aucun niveau. C'est rare avec les modèles modernes. Vérifier : (1) le schéma est un schéma JSON valide, (2) le modèle dispose de suffisamment de `max_tokens` pour produire la réponse complète, (3) l'invite système ne contredit pas les instructions du schéma. Le planificateur et l'analyseur DAG fournissent tous deux des solutions de secours `default_value`, donc cette erreur ne se propage que depuis les sites d'appel qui omettent explicitement les valeurs par défaut.