Helicone : observabilité LLM et passerelle IA dans un seul dépôt Apache-2.0

Le problème visé : instrumenter des appels LLM sans écrire de proxy

Une application qui appelle un modèle de langage produit des requêtes dont on veut connaître le coût, la latence et le contenu. Instrumenter cela à la main suppose d'envelopper chaque client, de normaliser les formats de réponse entre fournisseurs et de stocker les traces quelque part. Helicone se présente comme une plateforme d'observabilité LLM et une passerelle IA, avec pour argument une intégration en une ligne de code. Le public visé est décrit dans le README comme des ingénieurs IA, avec des cas d'usage nommés : agents, chatbots, pipelines de traitement de documents. Le dépôt est écrit principalement en TypeScript et publié sous Apache-2.0, ce qui laisse la possibilité d'auto-héberger l'ensemble plutôt que de dépendre du service hébergé. La page d'accueil du projet renvoie vers www.helicone.ai, et le README mentionne une offre gratuite de 10 000 requêtes par mois sans carte bancaire.

Une passerelle qui sert aussi de point de collecte

Le mécanisme central tient dans le changement de baseURL. L'exemple du README montre un client OpenAI construit avec baseURL: "https://ai-gateway.helicone.ai" et apiKey: process.env.HELICONE_API_KEY. Le modèle demandé reste un identifiant classique, gpt-4o-mini dans l'exemple, et le README cite aussi claude-sonnet-4 et gemini-2.0-flash. Autrement dit, le trafic passe par le domaine de Helicone, qui relaie vers le fournisseur réel. C'est ce passage obligé qui permet la journalisation : pas de SDK à installer côté application, pas d'enveloppe autour du client. Le même point d'entrée sert au routage intelligent et aux bascules automatiques annoncées dans le README. Cette conception a une conséquence directe : la passerelle voit le contenu des requêtes et des réponses, ce qui est précisément ce qui rend les traces exploitables, et ce qui impose de réfléchir à ce qu'on accepte d'envoyer à un tiers si l'on n'auto-héberge pas.

Cinq services pour l'auto-hébergement, pas un seul binaire

Le README détaille l'architecture : Web (frontend NextJS), Worker (proxy de journalisation sur Cloudflare Workers), Jawn (serveur dédié à la collecte des logs, Express avec Tsoa), Supabase pour la base applicative et l'authentification, ClickHouse pour l'analyse, et Minio pour le stockage objet des logs. Ce découpage explique pourquoi la documentation qualifie le déploiement manuel de non recommandé. Chaque brique a son propre cycle de vie : une montée de version de ClickHouse ou de Supabase ne se traite pas comme une mise à jour du frontend. Pour une équipe qui veut juste voir ses traces, c'est un coût d'exploitation réel. Pour une équipe qui a déjà ces briques en interne, l'intégration est plus naturelle. Le README mentionne aussi un chart Helm décrit comme prêt pour la production, mais son accès passe par un contact à enterprise@helicone.ai : ce n'est pas un artefact public du dépôt.

Démarrage concret : Docker Compose et variables d'environnement

La voie recommandée dans le README tient en quatre commandes. On clone le dépôt, on entre dans le répertoire docker, on copie .env.example vers .env, puis on lance ./helicone-compose.sh helicone up. Le script helicone-compose.sh est donc le point d'entrée, et le fichier .env issu de .env.example contient la configuration à renseigner avant le premier démarrage. Le README ne détaille pas les clés présentes dans ce fichier ; il faut se référer à la documentation d'auto-déploiement Docker pour la liste exacte. Côté intégration applicative, la seule modification est la baseURL et la clé. Pour les cas où l'on ne veut pas faire transiter le trafic, le README mentionne une journalisation asynchrone via OpenLLMetry, en JS/TS et en Python. Le paquet npm cité dans le tableau des intégrations est @helicone/helicone. Les intégrations listées couvrent OpenAI, Anthropic, Gemini, LangChain et le Vercel AI SDK.

Ce que la documentation ne tranche pas

Plusieurs points restent flous à la lecture du README. Le calcul des coûts renvoie à une page de FAQ intitulée how-we-calculate-cost, ce qui suggère une table de tarifs maintenue côté projet : la fraîcheur de cette table pour des modèles récents n'est pas vérifiable depuis le dépôt seul. La gestion de prompts est présentée comme un moyen de versionner et de déployer sans changement de code, mais le README n'explique pas comment les versions sont résolues à l'exécution ni ce qui se passe si une version référencée disparaît. Les fonctionnalités d'évaluation et de jeux de données apparaissent dans les badges et les sujets du dépôt, sans détail de mise en oeuvre dans le texte fourni. Enfin, la conformité SOC 2 et GDPR est annoncée sous l'étiquette Enterprise Ready, sans préciser si elle couvre l'auto-hébergement ou seulement l'offre hébergée. Ce sont des questions à poser avant de s'engager, pas des défauts établis.

Quand Helicone n'est pas le bon outil

Le cas le plus net est celui d'une équipe qui refuse qu'un proxy externe voie ses prompts. Sans auto-hébergement, le trafic passe par ai-gateway.helicone.ai. Même en auto-hébergement, le modèle reste celui d'un proxy : le Worker intercepte la requête avant le fournisseur. Si votre besoin se limite à du tracing local dans un processus unique, sans routage multi-fournisseurs ni tableau de bord partagé, une bibliothèque d'instrumentation en cours de processus sera plus simple à opérer qu'un empilement ClickHouse plus Supabase plus Minio. Autre cas défavorable : une équipe sans compétence sur les bases colonnaires. ClickHouse n'est pas Postgres, et les schémas de rétention ou de migration de logs ne se traitent pas de la même façon. Le README ne promet d'ailleurs aucune procédure de migration entre versions majeures de ces composants.

Face à Langfuse, la différence se joue sur la passerelle

Langfuse est l'alternative open source la plus directement comparable sur le tracing LLM, et la différence d'approche est structurelle. Helicone met en avant une passerelle : le changement de baseURL place le projet sur le chemin de la requête, ce qui donne le routage, les bascules automatiques et l'accès à plus de 100 modèles avec une seule clé. Langfuse se présente d'abord comme une couche d'observabilité, où l'instrumentation se fait via des SDK et des intégrations dans le code de l'application, sans nécessairement intercepter le trafic. Le choix se ramène donc à une question de position dans l'architecture : intercepter pour observer et router, ou instrumenter pour observer sans se placer sur le chemin critique. Helicone propose aussi la journalisation asynchrone via OpenLLMetry, ce qui rapproche les deux approches, mais l'argument de vente du dépôt reste la passerelle. Aucun des deux modèles n'est gratuit en exploitation : les deux demandent des ressources pour la base de traces.

Coût de maintenance et implications de licence

Le dépôt est publié sous Apache-2.0, une licence permissive qui autorise l'usage commercial, la modification et la redistribution, avec conservation des mentions de copyright et du fichier de licence. Elle ne couvre que le code du dépôt : les composants tiers de l'architecture, Supabase, ClickHouse et Minio, ont leurs propres licences, et il faut les vérifier séparément. Le rythme de publication observé est élevé, avec des versions datées des 20 et 21 août 2025 puis une release v2025.08.21-1 quelques heures après v2025.08.21. Cette cadence implique de choisir une politique de mise à jour : suivre chaque version expose à des régressions, rester en arrière expose à des écarts de schéma. Le README ne décrit pas de procédure de retour arrière. Pour l'offre hébergée, la conformité SOC 2 et GDPR est mentionnée ; pour l'auto-hébergement, la responsabilité de la conformité revient à l'exploitant, ce qui n'est pas un conseil juridique mais une conséquence de l'architecture décrite.

Conclusion éditoriale

Adoptez Helicone si vous voulez centraliser le routage multi-fournisseurs et la journalisation des traces sans écrire votre propre couche de proxy, et si vous acceptez la version hébergée ou les cinq services de l'auto-hébergement. Évitez-le si vous cherchez uniquement un tracing local sans dépendance réseau, ou si vous ne pouvez pas maintenir ClickHouse, Supabase et Minio. Avant tout déploiement, vérifiez le fichier docker/.env.example et la licence Apache-2.0 du dépôt, puis confirmez dans la documentation la liste des variables d'environnement requises par Jawn et le Worker.

Sources officielles

1. Helicone/helicone on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases