# Routage éco IA

Sovrium traite l'empreinte environnementale comme une propriété de plateforme de premier ordre. L'inférence IA est l'une des opérations les plus gourmandes en ressources qu'une plateforme puisse effectuer, c'est pourquoi Sovrium route les appels IA **local d'abord par défaut** : lorsqu'un modèle local (Ollama) est accessible, il répond ; ce n'est que lorsqu'il ne l'est pas que l'appel bascule vers un fournisseur cloud configuré.

Ceci est contrôlé par une seule variable d'environnement d'opérateur — `ECO_AI_PROVIDER_PRECEDENCE` — jamais par le schéma de l'application. Comme toute variable `ECO_*`, sa valeur par défaut est le réglage aligné sur l'écologie ; les opérateurs se _désengagent_, jamais ne s'engagent.

```bash
ECO_AI_PROVIDER_PRECEDENCE=local-first   # la valeur par défaut — généralement à omettre entièrement
AI_PROVIDER=anthropic                    # cible de repli cloud
ANTHROPIC_API_KEY=sk-ant-...
OLLAMA_BASE_URL=http://localhost:11434   # point d'accès du fournisseur local
```

## Modes de précédence

| Valeur        | Comportement                                                                                                                                                |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `local-first` | **(par défaut)** Privilégier un Ollama local accessible ; basculer vers le fournisseur cloud `AI_PROVIDER` configuré lorsque Ollama est inaccessible.       |
| `cloud-first` | Utiliser le fournisseur cloud configuré ; utiliser un Ollama accessible uniquement lorsqu'aucun fournisseur cloud n'est configuré.                          |
| `local-only`  | Utiliser un fournisseur local exclusivement. Les appels IA n'ont aucun repli cloud — lorsqu'aucun Ollama accessible n'est configuré, l'IA est indisponible. |

Une valeur non définie, vide ou non reconnue résout vers la valeur par défaut alignée sur l'écologie, `local-first`.

## Comment le routage se résout

Le résolveur combine trois entrées : la précédence active, si un point d'accès Ollama est **configuré** (via `OLLAMA_BASE_URL`, ou `AI_BASE_URL` lorsque `AI_PROVIDER=ollama`), et si la sonde d'accessibilité de l'exécution a trouvé Ollama **utilisable** (configuré _et_ répondant).

| Précédence    | Ollama utilisable | Cloud configuré | Route vers     | Notes                                                                           |
| ------------- | ----------------- | --------------- | -------------- | ------------------------------------------------------------------------------- |
| `local-first` | oui               | —               | Ollama         | Chemin local privilégié.                                                        |
| `local-first` | non               | oui             | cloud          | Repli. Signalé avec une raison lorsqu'Ollama était configuré mais inaccessible. |
| `local-first` | non               | non             | Ollama / aucun | Désactivé lorsqu'aucun fournisseur n'est configuré du tout.                     |
| `cloud-first` | —                 | oui             | cloud          | Le cloud l'emporte toujours lorsqu'il est configuré.                            |
| `cloud-first` | oui               | non             | Ollama         | Local utilisé uniquement parce qu'aucun cloud n'est configuré.                  |
| `local-only`  | oui               | —               | Ollama         | Local exclusivement.                                                            |
| `local-only`  | non               | —               | aucun          | Aucun repli — IA indisponible jusqu'à ce qu'un Ollama accessible existe.        |

:::callout
**L'accessibilité est sondée, pas supposée.** L'exécution vérifie si le point d'accès Ollama configuré répond réellement avant de router vers lui. Sous `local-first`, lorsqu'Ollama est _configuré mais inaccessible_, le repli vers le cloud est enregistré avec une raison destinée à l'opérateur ; lorsqu'Ollama n'a jamais été configuré, le repli se produit silencieusement.
:::

## Observabilité

La décision de routage éco active est exposée sur le point d'accès de santé (`GET /api/health`, sous `body.ai`) :

| Champ              | Signification                                                                                            |
| ------------------ | -------------------------------------------------------------------------------------------------------- |
| `precedence`       | La valeur `ECO_AI_PROVIDER_PRECEDENCE` active.                                                           |
| `resolvedProvider` | Le fournisseur canonique vers lequel les appels IA sont routés (ou absent lorsque l'IA est désactivée).  |
| `ollamaReachable`  | Si la sonde Ollama locale a réussi.                                                                      |
| `configured`       | La valeur brute `AI_PROVIDER`.                                                                           |
| `fallbackReason`   | Pourquoi le résolveur a basculé vers un fournisseur non privilégié (présent uniquement en cas de repli). |

Cela rend le routage auditable : les opérateurs peuvent confirmer si un déploiement s'exécute réellement sur son modèle local ou consomme silencieusement des jetons cloud.

## Exemples de configuration

```bash
# Valeur par défaut frugale : Ollama local avec un filet de sécurité Anthropic.
# (ECO_AI_PROVIDER_PRECEDENCE=local-first est la valeur par défaut — affichée pour clarté.)
ECO_AI_PROVIDER_PRECEDENCE=local-first
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
OLLAMA_BASE_URL=http://localhost:11434
AI_MODEL=claude-sonnet-4-5
```

```bash
# Déploiement strict local-only — aucune donnée ne quitte jamais l'hôte.
ECO_AI_PROVIDER_PRECEDENCE=local-only
AI_PROVIDER=ollama
AI_BASE_URL=http://localhost:11434
AI_MODEL=llama3.1
```

```bash
# Qualité d'abord : toujours utiliser le fournisseur cloud.
ECO_AI_PROVIDER_PRECEDENCE=cloud-first
AI_PROVIDER=openai
OPENAI_API_KEY=...
AI_MODEL=gpt-4o
```

## Pages connexes

- [Fournisseurs IA](/fr/docs/ai-providers) — configuration du fournisseur, de la clé et de l'URL de base.
- [Vue d'ensemble de l'IA](/fr/docs/ai-overview) — l'écosystème IA et la philosophie de configuration.
- [Variables d'environnement](/fr/docs/env-vars) — référence complète `ECO_*` et `AI_*`.