Coûts, rétention et passage en production

Le contrôleur de gestion d'Arvea pose une question simple : combien coûte l'assistant par conseiller et par mois, et combien coûtera-t-il en janvier ? Le premier tableau de coûts produit pendant ce projet affichait 0,00 USD pour l'agent : aucune définition de prix ne correspondait aux modèles utilisés. Un chiffre faux est pire qu'une absence de chiffre, parce qu'on le croit. Cette leçon rend les coûts justes, les garde sous contrôle, et prépare la sortie du lab.

Le mécanisme : le coût est calculé une fois, à l'ingestion

Langfuse a deux façons d'obtenir un coût : vous l'envoyez (cost_details), ou il le déduit à partir de l'usage et d'une définition de modèle (expression régulière de correspondance + prix par clé d'usage). Le calcul a lieu dans le worker, au moment de l'ingestion, et n'est jamais refait : une définition ajoutée ou corrigée ne s'applique qu'aux nouvelles observations.

flowchart LR
  G["Génération<br/>model = gemini-3.5-flash-lite<br/>usage : input 196, output 47"] --> W["Worker"]
  D[("Définitions de modèles<br/>motif : gemini-3.5-flash-lite, avec ou sans models/<br/>input 0,30 / output 2,50 USD par M")] --> W
  W -->|"196 × 0,30e-6 + 47 × 2,50e-6"| C[("ClickHouse<br/>totalCost 0,0001763")]
  C --> M["API Metrics v2<br/>coût par modèle, par conseiller"]

La correspondance porte sur le nom de modèle enregistré et le prix sur chaque clé d'usage : une clé sans prix compte pour zéro. D'où deux pièges vus dans ce projet : un modèle servi différent du modèle demandé (leçon 2), et les tokens de réflexion, que Gemini facture au prix de la sortie mais que l'instrumentation range sous une clé distincte, output_reasoning_tokens.

La mise en œuvre

1. Déclarer les prix, toutes les clés

Les tarifs viennent de la page officielle de l'API Gemini (palier payant standard, relevés le 2026-10-15) :

PRIX: dict[str, dict[str, float]] = {
    "gemini-3.5-flash-lite": {"input": 0.30e-6, "input_cached_tokens": 0.03e-6,
                              "output": 2.50e-6, "output_reasoning_tokens": 2.50e-6},
    "gemini-3.8-flash": {"input": 0.75e-6, "input_cached_tokens": 0.075e-6,
                         "output": 3.75e-6, "output_reasoning_tokens": 3.75e-6},
}

def declarer_prix(langfuse) -> int:
    existants = {m.model_name for m in langfuse.api.models.list(limit=100).data if not m.is_langfuse_managed}
    for nom, prix in PRIX.items():
        if nom in existants:
            continue
        langfuse.api.models.create(
            model_name=nom, match_pattern=motif(nom), unit="TOKENS",
            pricing_tiers=[PricingTierInput(name="Standard", is_default=True, priority=0,
                                            conditions=[], prices=prix)])

Un test unitaire garantit que la réflexion est facturée au prix de la sortie pour chaque modèle. Les définitions vivent dans le code, versionnées, et make seed les applique : une instance reconstruite retrouve les mêmes prix.

2. Lire les coûts là où ils sont agrégés

L'API Metrics v2 agrège côté Langfuse ; inutile de rapatrier les observations pour les additionner :

base = {"view": "observations", "metrics": [{"measure": "totalCost", "aggregation": "sum"},
                                             {"measure": "count", "aggregation": "count"}],
        "fromTimestamp": debut.isoformat(), "toTimestamp": fin.isoformat(),
        "orderBy": [{"field": "sum_totalCost", "direction": "desc"}], "config": {"row_limit": 10}}
for dimension in ("providedModelName", "userId"):
    rep = lf.api.metrics.metrics(query=json.dumps({**base, "dimensions": [{"field": dimension}]}))

userId a une forte cardinalité : Langfuse n'accepte de grouper dessus qu'en requête « top N » (limite explicite, tri décroissant sur une mesure).

3. Limiter ce qu'on garde

LANGFUSE_INIT_PROJECT_RETENTION=30 (leçon 1) supprime automatiquement les observations de plus de 30 jours. Pour un assistant qui manipule des données d'adhérents, c'est la durée de conservation qu'il faut pouvoir justifier au DPO. Les prompts, jeux de données et scores d'expérience, eux, ne contiennent pas de données de production et restent.

4. Arrêter proprement

make down arrête la pile et supprime ses volumes, puis vérifie qu'il ne reste aucun volume portant l'étiquette du projet Compose :

down:
	@$(COMPOSE) down -v --remove-orphans
	@left=$$(docker volume ls -q --filter label=com.docker.compose.project=lab-$(SLUG)); \
	  if [ -n "$$left" ]; then echo "Volumes restants : $$left"; exit 1; else echo "Pile et volumes lab-$(SLUG) supprimés."; fi

Résultat obtenu

make couts après make e2e, le 2026-10-15 :

Coût par providedModelName (7 j) :
  gemini-3.8-flash             0.025795 USD    16 observations
  gemini-3.5-flash-lite        0.003674 USD    23 observations
  None                         0.000000 USD   105 observations
Coût par userId (7 j) :
  None                         0.025795 USD    96 observations
  evaluation                   0.002221 USD    32 observations
  cons-0977                    0.001126 USD    12 observations
  cons-0412                    0.000327 USD     4 observations

Deux lectures : les 105 observations sans modèle sont des spans, agents et outils, sans coût par nature. Et 0,0258 USD n'est rattaché à aucun utilisateur : ce sont les appels du juge, exécutés par le SDK hors du bloc propagate_attributes de la tâche. L'exercice ci-dessous corrige cela.

Capture réelle : le tableau d'accueil du projet après make e2e. Le tableau de bord « Langfuse Cost Dashboard » fourni par défaut affichait « Widget not found » sur cette instance 4.59.0 : l'accueil et l'API Metrics donnent les mêmes chiffres.

Le même make e2e tourne sur Vertex AI sans modifier le code : le client google-genai et ADK lisent GOOGLE_GENAI_USE_VERTEXAI. Rejoué ainsi le 2026-10-16 (location global, mêmes modèles) :

$ env -u GEMINI_API_KEY GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT=<projet> GOOGLE_CLOUD_LOCATION=global make e2e
production : {'moyenne_cite_reference': 0.125, 'moyenne_exactitude_juge': 0.8125}
staging    : {'moyenne_cite_reference': 0.875, 'moyenne_exactitude_juge': 0.78125}
staging promu en production (version 2)
OK : appli 2 générations (prompt conseiller-reponse v1), agent 5 générations, coût 0.001245 USD, 103 s

La dépense passe alors sur la facture Google Cloud du projet. Les prix déclarés dans Langfuse sont ceux de l'API Gemini : comparez-les à la grille Vertex AI avant de vous fier au coût affiché.

Puis l'arrêt, vérifié :

$ make down
 Volume lab-langfuse_langfuse_postgres_data  Removed
 Network lab-langfuse_default  Removed
Pile et volumes lab-langfuse supprimés.
$ docker ps -a --filter name=lab-langfuse -q | wc -l ; docker volume ls --filter name=lab-langfuse -q | wc -l
0
0

Ce qui casse en production

Passer du lab à la production sur Google Cloud

Le fichier Compose convient à un pilote. Pour une instance d'équipe durable, l'éditeur fournit un module Terraform pour Google Cloud (langfuse/langfuse-terraform-gcp) : GKE pour les conteneurs web et worker, Cloud SQL pour PostgreSQL, Memorystore pour Redis, Cloud Storage pour le stockage objet, ClickHouse déployé dans le cluster. Ce projet ne crée aucune de ces ressources (coût d'un cluster), mais la correspondance est directe :

La règle de décision

Un coût n'est fiable que si chaque clé d'usage émise a un prix et si chaque modèle enregistré a une définition : vérifiez-le avec un test, et alertez sur toute génération dont l'usage est non nul et le coût nul. Attribuez chaque appel payant à un utilisateur, réel ou technique. Fixez la rétention le premier jour. Restez sur Compose tant qu'une interruption de quelques heures est acceptable ; au-delà, passez au module Terraform ou à Langfuse Cloud.

Pratique

Exercice. Faites en sorte que les appels du juge soient attribués à un utilisateur technique juge-llm et portent le tag evaluation, puis vérifiez avec make couts que la ligne None ne porte plus de coût.

from langfuse import propagate_attributes

with propagate_attributes(user_id="juge-llm", tags=["evaluation"]):
    with get_client().start_as_current_observation(as_type="generation", name="juge",
                                                   model=SETTINGS.judge_model, input=prompt) as gen:
        ...

• Je sais déclarer des prix de modèle couvrant toutes les clés d'usage, et le vérifier par un test.
• Je sais pourquoi un changement de tarif doit être appliqué le jour même.
• Je sais obtenir le coût par modèle et par conseiller sans exporter les observations.
• Je sais fixer une rétention et arrêter le lab en supprimant tout, vérification comprise.
• Je sais décrire la cible Google Cloud équivalente au fichier Compose.