Helicone を採用する前に読む: 5サービス構成と自己ホストの実際

Helicone が埋めるのは「本番のリクエストが見えない」という穴

LLM を使った機能を出すと、最初に困るのは失敗の再現である。ユーザーが変な回答を受け取っても、送ったプロンプトと返ってきた本文がどこにも残っていなければ、原因はモデルなのかプロンプトなのか、あるいはリトライの順序なのかを切り分けられない。Helicone はこの記録を、アプリケーションのコードにロガーを足すのではなく、API 呼び出しの経路そのものに挿し込む形で解決しようとする。README は「One-line of code to log all your requests」と表現しており、OpenAI、Anthropic、LangChain、Gemini、Vercel AI SDK などが対象として並んでいる。

想定読者は、チャットボット、エージェント、文書処理パイプラインを本番で動かしている AI エンジニアである。README が挙げる機能は、トレースとセッションの検査、コストとレイテンシの集計、プロンプトのバージョン管理、ゲートウェイ経由のモデル切り替えと自動フォールバック、そして PostHog への1行エクスポートだ。観測とゲートウェイという性格の異なる2つが同じ製品に入っている点が、後述する構成の分岐につながる。

記録はどう流れるか: 5つのサービスと2つのデータベース

自己ホスト時の構成は README に明示されている。Web は NextJS のフロントエンド、Worker は Cloudflare Workers 上で動くプロキシのロギング、Jawn はログ収集を担う Express + Tsoa のサーバー、Supabase はアプリケーション DB と認証、ClickHouse は分析用 DB、Minio はログ用のオブジェクトストレージである。README の見出しは「five services」と書いた直後に6つの名前を並べており、数え方が一致していない。Minio を補助コンポーネントと見なしているのだろうが、記述としては雑である。

データの流れは、アプリからのリクエストが Worker のプロキシを通り、そこから Jawn に渡って ClickHouse と Minio に落ちる、という形が読み取れる。分析クエリを ClickHouse に、生ログの本体を Minio に分ける設計は、集計を軽くしたいという意図の表れだと解釈できる。Supabase が認証を兼ねるため、ユーザー管理を別途作り込む必要はない。ここで注意したいのは、Worker が Cloudflare Workers を前提としている点だ。オンプレミスや閉域網で完結させたい場合、この層をどう置き換えるかは README からは読み取れない。

導入手順: baseURL の差し替えと Docker 起動

マネージドを使う場合の手順は README の Quick Start に具体例がある。OpenAI のクライアントを初期化する際、baseURL を https://ai-gateway.helicone.ai に、apiKey を process.env.HELICONE_API_KEY に変える。モデル名は gpt-4o-mini の例が示され、claude-sonnet-4 や gemini-2.0-flash なども同じ経路で指定できると書かれている。API キーは helicone.ai/signup で取得し、helicone.ai/credits でクレジットを追加する流れだ。無料枠は月 10k リクエストと README に記載されている。

自己ホストの場合は docker ディレクトリで作業する。git clone の後、cd docker、cp .env.example .env、そして ./helicone-compose.sh helicone up の4ステップが README に載っている。Enterprise 向けには Helm チャートが用意されているが、入手には enterprise@helicone.ai への連絡が必要で、公開リポジトリからは取得できない。手動デプロイは「Not Recommended」と明記されており、Docker か Helm を使うよう誘導されている。

つまり、評価を始めるまでの距離はマネージドと自己ホストで大きく違う。前者は環境変数1つ、後者は .env の埋めと6コンポーネントの起動である。

セルフホストのコストはコンテナの数だけ乗る

自己ホストの負担は、サービス数がそのまま運用項目になることだ。Supabase と ClickHouse はどちらも状態を持つ。ClickHouse は分析用とはいえデータを溜め続けるので、保持期間を決めずに走らせるとディスクが伸びる。Minio も同様にオブジェクトを蓄積する。バックアップ、アップグレード、障害時の復旧を、この2つに対して別々に設計する必要がある。

もう一つの現実的な制約は、Helm チャートが公開されていないことだ。Kubernetes で本番運用したいチームは、Docker 構成を自分でマニフェスト化するか、Enterprise 窓口に問い合わせるかの二択になる。README は Helm を「production-ready」と説明しているが、その中身を確認できない以上、公開情報だけでは判断できない。

ライセンスは Apache-2.0 で、リポジトリはアーカイブされていない。ただし Apache-2.0 がカバーするのはリポジトリ内のコードであり、マネージド版の利用条件や Enterprise 契約の内容は別に定められる。ここは法的な判断ではなく、確認事項として挙げておく。

向かないケース: 観測だけが目的ならゲートウェイは要らない

Helicone は観測とゲートウェイを一つの製品に束ねている。この統合は、モデルの切り替えやフォールバックを自前で書きたくないチームには利点になる。逆に、既に自社のルーティング層を持ち、そこに独自のリトライ戦略やコスト配分を実装しているチームにとっては、baseURL を Helicone に向けることが経路の二重化を意味する。プロキシが1段増えれば、その分のレイテンシと、プロキシ自体が落ちたときの影響を引き受けることになる。

もう一つの境界は、プロンプトの扱いだ。README は「Your prompts remain under your control, always accessible」と書いており、プロンプト管理機能がプロンプトを囲い込まないことを売りにしている。これは裏を返せば、プロンプトを Helicone 側で管理する設計を選ぶ余地があるということで、外部にプロンプトを置けない組織では自己ホスト以外の選択肢がない。

さらに、README が対象として挙げるのは OpenAI、Anthropic、Gemini、LangChain、Vercel AI SDK などであり、これらに当てはまらない独自推論基盤や社内モデルが対象になるかは、この資料からは判断できない。

Langfuse や OpenLLMetry との違いはどこにあるか

同じ領域には選択肢がある。Helicone 自身の README も Async Logging (OpenLLMetry) を統合先として挙げており、OpenLLMetry は JS/TS と Python 向けの非同期ロギングを提供する。これは Helicone と競合するというより、計装の手段を Helicone 側が用意しているという関係だ。

対抗軸として分かりやすいのは Langfuse のような観測専用のツールである。違いはゲートウェイの有無に集約される。Helicone はリクエストを自分のプロキシ経由で通すことで、モデルの切り替え、自動フォールバック、プロンプトのバージョンをコード変更なしに適用する仕組みを同じ製品内に持つ。観測専用ツールはアプリの呼び出し経路に手を入れず、計装ライブラリからトレースを送る。経路を触らない分だけ導入の侵襲性は低いが、その代わりにルーティングやプロンプト配信の機能は自分で用意することになる。

どちらが優れているという話ではない。本番のトラフィック経路を自分で握り続けたいか、そこを製品に委ねて運用を減らしたいか、という設計判断である。

導入前に確かめるべき3点

第一に、記録される内容の粒度である。README はトレースとセッションの検査、コストとレイテンシの集計を挙げているが、実際にどのフィールドが保存され、どの保持期間で消えるかは、この資料からは分からない。無料枠で数リクエストを流し、ダッシュボードに何が残るかを自分の目で確認するのが早い。

第二に、自己ホストを選ぶなら docker/.env.example の中身を先に読むこと。Supabase、ClickHouse、Minio の接続情報と認証設定が並んでいるはずで、その数がそのまま初期構築の作業量になる。あわせて ClickHouse のディスク容量を、1日あたりのリクエスト数と平均プロンプト長から見積もっておきたい。

第三に、Helm を使いたい場合は enterprise@helicone.ai への問い合わせが前提になる。公開チャートではないため、ライセンス条件とサポート範囲を確認しないまま本番計画を立てるのは避けたい。リリースは v2025.08.21-1 のように日付ベースで頻繁に出ており、更新の追従コストも見込んでおく必要がある。

編集部の結論

マネージドのゲートウェイ経由で始めるなら、baseURL を https://ai-gateway.helicone.ai に変えるだけで試せるので、まず無料枠で自社のプロンプトがどう記録されるかを見るのが妥当だ。自己ホストを選ぶべきなのは、プロンプトとログを外部に出せない制約が先にあり、かつ ClickHouse と Supabase を運用できる体制がある場合に限られる。逆に、観測だけが目的で独自のルーティングを既に持っているチーム、Docker も Helm も回せない小規模チームには向かない。導入前に確認すべきは、docker ディレクトリの .env.example に並ぶ必須キーの数、ClickHouse のディスク見積もり、そして Worker が Cloudflare Workers 前提である以上、社内ネットワークから ai-gateway.helicone.ai へ到達できるかどうかである。

公式情報源

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