Langfuse の Self-hosted インストールのパターンと解説

本記事は  <a href='https://www.gao-ai.com/blog'>GAO 公式ブログ</a> からの転載となります。

## インストールのパターン

Langfuse v3 になって、「Self-hosting は良さそうだけど、結構インストール面倒なんでしょう？」という声をよく聞きます。もちろん複雑な構成を作ることも可能ではありますが、一方でLangfuse には簡単なものもふくめて幾つかのインストール方法が用意されており、利用用途や条件に合わせた選択が可能です。

この記事では、各インストールオプションおよび公式ページのリンク、使い分けについて解説します。まず簡単なケースごとのフローチャートは以下のような形になります。当てはまりそうなオプションを中心にぜひご確認ください。


![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4048367/37593ef8-73d4-4181-9e21-8d299d0078a1.png)


実際のインストールコマンドは、各オプションのリンクから公式をご参照ください。


## Langfuse のインストールオプション

### 1. ローカルインストール

Docker と docker compose を利用したローカル環境でのセットアップ方法です。

特筆すべきものはなく、非常にシンプルな手順で利用可能なもので、個人利用や簡単なテスト環境向きです。Mac やWindows でDocker をインストールしたら、docker compose upコマンド一つで起動します。特に悩むところもないです。  
  

**使用するケース**
- 手元のアプリ開発の可視化やテスト目的で手軽にLangfuse を試してみたい
- このLangfuse を本番環境に使う予定はない
  

### 2. Docker Composeを使ったインストール

公式ドキュメントとしては区別されていますが、1と基本的には一緒です。ただしAWS/Google Cloud/Azure などで仮想マシン (EC2 など) をつかうことが想定されており、公式ページにはdockerパッケージの導入手順などについても記載してあります

大規模なトラフィックがなく、可用性が許容されるのであれば本番環境にも適用可能です。また一部にマネージドサービスを使うといった方法で可用性も向上できます。


**使用するケース**
- 小〜中規模のチームでの本番やステージング環境を構築したい
- Trace などの欠損リスクがある程度は許容できる
- VM の構築や管理をできる人がチームにいる
- インフラ構築をシンプルに管理したい

**必要なリソース**
- 4Core 16GiB メモリなどが推奨 (それ以下でも立ち上がりはする)
- 100GiB ストレージ, 外部から接続できるNW設定 (Public IPなど)

**本番利用に向けて、可用性を高める応用例**
- Object storage はVMではなくS3 / blob /GCS などに変更
- プロンプト取得の可用性を高めるため、Web server のコンテナとPostgreSQL だけをマネージドサービス利用する

またdocker-compose.yml を修正することで、ディスクやデータベースの接続など各種設定を変更することもできます。langfuse ディレクトリ直下にありますので必要に応じてご確認ください。


### 3. Dockerを使ったインストール

Docker composeではなくDocker コンテナを使ってカスタマイズ構成を作るパターンです。
利点は複数のコンポーネントで構成されているLangfuse をクラウドサービス側のマネージドサービスを利用して、高い可用性を保つことができることなどにあります。
PostgreSQL, Redis, Clickhouse をマネージドサービスで起動しておいて、docker コマンドの引数として指定しましょう。


**使用するケース**
- Kubernetes は使いたくないが、VM単体よりも可用性を高く保ちたい
- 一方でクラウドサービスのマネージドサービスを使って、手はかけたくない
- クラウドサービスのネットワークなどを構築・管理できる

**改善したい可用性と構成例**
- プロンプト取得における可用性を向上させたい
    - Web server のコンテナをECS やCloudRun で稼働
    - PostgreSQL  をAurora や CloudSQL で稼働


**Traceデータの可用性を高めたい**
- Object Strage にS3, GCS などを活用
    - Clickhouse としてClickhouse Cloud などを使う、あるいはECSや GCE container optimized OS 上で動かす
    - Async worker のコンテナをECS やCloud Run などで稼働
    - RedisにElasticashe や Memorystore  などを活用する


最近では以下のようなTeraform, CDK, あるいはマニュアル などで比較的簡単 (あるいはほぼ自動) で構築できるようにリソースを公開しているものもあります。ご自身のケースに当てはまるかもご確認ください。

-----
**参考リンク**

[AWS]
- tuboneさん (<a href='https://tubone-project24.xyz/2024-12-30/Langfuse-v3%E3%82%92AWS%E3%83%9E%E3%83%8D%E3%83%BC%E3%82%B8%E3%83%89%E3%82%B5%E3%83%BC%E3%83%93%E3%82%B9%E3%81%A7%E4%BD%9C%E3%82%8B'>Blog</a>) リソース https://github.com/tubone24/langfuse-v3-terraform　
- mazyu36さん (<a href='https://mazyu36.hatenablog.com/entry/2025/02/06/12125'>Blog</a>)リソース https://github.com/mazyu36/langfuse-with-aws-cdk

[Google Cloud]
- クラウドエース株式会社 高木さん (<a href='https://zenn.dev/cloud_ace/articles/deploy-langfusev3-on-gcp'>Blog</a>)
- Takafumi Kubota さん リソース https://github.com/xxkuboxx/langfuse-tf-gcp


## 4. Kubernetes Helmを使ったインストール

Kubernetes クラスタにHelm を使ってLangfuseを導入する方法です。可用性やスケーラビリティを確保しつつ、運用をKubernetesに任せたいケースにおいて利用可能です。


**使用するケース**
- 比較的大規模なチームやエンタープライズ環境
- 高い可用性とスケーラビリティを求める
- Kubernetesクラスタを運用することができる


なお、Langfuse 公式で Helm Chart がリリースされており、特に理由がなければこれを使うことが最初の入口として良いと思います。その上で、さらに可用性を向上させたい場合には以下のオプションなどが有益です。


**Traceを格納するClickhouse自体の可用性や保守性などを高めたい**
- コストや諸条件が合えばClickhouse Cloud など利用を検討する

**プロンプト取得における可用性を向上させたい**
- PostgreSQL  をAurora や CloudSQL などで稼働


以下の記事では、Langfuse をKubernetes + マネージドサービスの構成でデプロイをした構成について言及しています。
  

<br>

**参考リンク：Google CloudでLangfuse v3の構築手順（推奨設定/GKE）**
 GAO 遠矢 (<a href='https://www.gao-ai.com/post/google-cloud%E3%81%A7langfuse-v3%E3%82%92%E3%82%BB%E3%83%AB%E3%83%95%E3%83%9B%E3%82%B9%E3%83%86%E3%82%A3%E3%83%B3%E3%82%B0%E3%81%A7%E3%83%87%E3%83%97%E3%83%AD%E3%82%A4%E3%81%99%E3%82%8B%E6%89%8B%E9%A0%86%EF%BC%88%E3%82%BB%E3%83%83%E3%83%88%E3%82%A2%E3%83%83%E3%83%97%EF%BC%89'>Blog</a>)


-----
本記事がインストール方法の決定における参考になれば幸いです。
もし企業における導入サポートなどが必要でしたら、 お気軽にお問い合わせください。

https://www.gao-ai.com/contact