Bienvenue ! Si vous dirigez une petite équipe technique et que vous partagez une clé API pour GPT-4.1, Claude Sonnet 4.5 ou DeepSeek, vous avez probablement déjà vécu ce moment gênant : un collègue lance trente expériences la nuit, la facture explose, et personne ne sait qui doit combien. Dans ce tutoriel pas à pas, je vais vous montrer comment installer Langfuse sur votre propre serveur en moins d'une heure, puis comment y brancher vos appels LLM pour que chaque euro dépensé soit attribué automatiquement à la bonne personne.

Nous utiliserons la passerelle HolySheep AI — S'inscrire ici, qui centralise Claude, GPT, DeepSeek et Gemini derrière une seule clé compatible OpenAI. C'est le moyen le plus simple d'envoyer tous vos appels vers un point unique que Langfuse peut tracer, sans jongler avec quatre SDK différents. Paiement en WeChat ou Alipay, latence inférieure à 50 ms, crédits gratuits au démarrage : vous n'avez rien à installer côté HolySheep, tout se fait via une URL.

Pourquoi héberger Langfuse vous-même ?

La version SaaS de Langfuse est pratique, mais elle stocke les prompts et les traces de vos utilisateurs sur des serveurs tiers. Pour une équipe européenne soucieuse du RGPD, ou simplement pour garder la maîtrise de la facturation interne, l'auto-hébergement reste la voie la plus sûre. Vous gardez le contrôle total sur les données et vous pouvez connecter votre base PostgreSQL à votre outil comptable.

Capture d'écran à insérer : tableau de bord Langfuse vide juste après l'installation. C'est normal, il se remplira dès que vous aurez branché votre premier script Python.

Prérequis : ce qu'il vous faut avant de commencer

Étape 1 : installer Langfuse avec Docker Compose

Créez un dossier de travail, par exemple ~/langfuse, puis collez le contenu suivant dans un fichier docker-compose.yml. Aucune ligne n'est facultative : la base Postgres, la clé NextAuth et l'URL publique sont toutes nécessaires au premier démarrage.

version: '3.8'

services:
  langfuse-server:
    image: langfuse/langfuse:2
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://langfuse:langfuse@db:5432/langfuse
      - NEXTAUTH_SECRET=changez-moi-par-une-chaine-aleatoire-de-64-caracteres-minimum
      - NEXTAUTH_URL=http://localhost:3000
      - TELEMETRY_DISABLED=true
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:15
    environment:
      POSTGRES_USER: langfuse
      POSTGRES_PASSWORD: langfuse
      POSTGRES_DB: langfuse
    volumes:
      - langfuse_db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U langfuse"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  langfuse_db:

Lancez ensuite l'installation avec ces deux commandes. La première démarre les conteneurs en arrière-plan, la seconde suit les logs pour vérifier que tout démarre correctement.

cd ~/langfuse
docker compose up -d
docker compose logs -f langfuse-server

Attendez que les logs affichent « server is ready » puis ouvrez votre navigateur à l'adresse http://IP_DU_SERVEUR:3000. Vous verrez l'écran de création du premier compte administrateur.

Capture d'écran à insérer : page de connexion Langfuse avec le bouton « Sign up » en haut à droite. Créez votre compte administrateur, il将成为 le propriétaire du premier projet.

Étape 2 : créer votre projet et récupérer les clés de traçage

Une fois connecté, cliquez sur « New Project » en haut à droite et donnez-lui un nom explicite, par exemple production-equipe-data. Ouvrez ensuite l'onglet « Settings → API Keys ». Vous obtenez trois valeurs qu'il faut copier immédiatement :

Rangez-les dans un fichier .env local, jamais dans Git, et ajoutez .env à votre .gitignore.

Capture d'écran à insérer : page « API Keys » avec les trois champs surlignés en jaune. Le bouton « Copy » à droite de chaque champ vous évite les erreurs de copier-coller.

Étape 3 : brancher vos appels LLM via la passerelle HolySheep AI

HolySheep AI expose une API strictement compatible avec le protocole OpenAI. Vous gardez donc le SDK Python officiel, mais vous changez simplement l'URL de base. Voici le script minimal qui appelle GPT-4.1 et envoie automatiquement la trace à Langfuse, avec un tag metadata qui vous servira plus tard à filtrer par utilisateur.

# Installation préalable :

  pip install langfuse openai python-dotenv

import os
from dotenv import load_dotenv
from langfuse.openai import openai

load_dotenv()


Clés Langfuse (celles copiées à l'étape 2)

os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-xxxxxxxxxxxxxxxxxxxx"
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-xxxxxxxxxxxxxxxxxxxx"
os.environ["LANGFUSE_HOST"]       = "http://localhost:3000"


Une seule clé HolySheep AI pour GPT-4.1, Claude, DeepSeek et Gemini

client = openai.OpenAI(
    api_key  = "YOUR_HOLYSHEEP_API_KEY",
    base_url = "https://api.holysheep.ai/v1"
)

reponse = client.chat.completions.create(
    model="gpt-4.1",
    messages=[
        {"role": "system", "content": "Tu es un assistant juridique concis."},
        {"role": "user",   "content": "Résume ce contrat en 3 bullet points."}
    ],
    metadata={
        "utilisateur": "[email protected]",
        "projet"     : "client-acme",
        "departement": "juridique"
    }
)

print(reponse.choices[0].message.content)
print("Tokens utilisés :", reponse.usage.total_tokens)

Deux choses importantes à remarquer :

  1. La base_url pointe vers HolySheep AI et non vers api.openai.com, ce qui vous permet d'accéder à Claude Sonnet

    Ressources connexes

    Articles connexes