Hub documentation
Spaces での Langfuse
Spaces での Langfuse
このガイドでは、LangfuseをHugging Face Spacesにデプロイし、LLMアプリケーションの観測可能性（Observability）のために計装（Instrumentation）を開始する方法を示します。この統合により、Hugging Face Hub上でLLM APIの実験を行い、プロンプトを1か所で管理し、モデルの出力を評価できます。
Langfuseとは何ですか？
Langfuseは、LLMアプリケーションのデバッグ、評価、反復改善をチームで協力的に行うことを支援するオープンソースのLLMエンジニアリングプラットフォームです。
Langfuseの主な機能には、アプリケーションの実行フローの完全なコンテキストをキャプチャするためのLLMトレーシング、プロンプトの集中管理と協業による反復を可能にするプロンプト管理、出力品質を評価するための評価指標、テストおよびベンチマーク作成のためのデータセット作成、そしてプロンプトやモデル設定の実験を行うためのプレイグラウンドが含まれます。
この動画は、Langfuseの機能を紹介する10分のウォークスルーです：
なぜLLMの観測可能性（Observability）が必要なのか？
- 言語モデルがより広く普及するにつれ、その動作やパフォーマンスを理解することが重要になります。
- LLM observabilityとは、LLMアプリケーションの出力を通じて、その内部状態を監視し理解することを指します。
- 次のような課題に対処するために不可欠です:
- 繰り返し呼び出しや連鎖した呼び出しを含む複雑な制御フローにより、デバッグが困難になる。
- 非決定論的な出力により、一貫した品質評価の複雑さが生じる。
- 多様なユーザーの意図。ユーザー体験を向上させるには、深い理解が必要です。
- LLMアプリケーションの構築には複雑なワークフローが伴いますが、オブザーバビリティを活用することで、これらの複雑さを管理できます。
ステップ1: SpacesでLangfuseを設定する
Langfuse Hugging Face Space を使用すると、数回のクリックでデプロイ済みの Langfuse をすぐに利用できます。
開始するには、上記のボタンをクリックするか、以下の手順に従ってください:
- 新しい Hugging Face Space を作成します
- Space SDK として Docker を選択します
- Space テンプレートとしてLangfuseを選択します
- 再起動後も Langfuse のデータが永続化されるように、Storage Bucket をアタッチしてください
- Langfuse API/SDKがアプリにアクセスできるように、スペースの表示設定をpublicに設定してください（詳細は以下の注記を参照してください）
- [（任意ですが推奨）安全なデプロイメントのために、 環境変数:
NEXTAUTH_SECRET: ログインセッションのCookieを検証するために使用します。openssl rand -base64 32を使用して、少なくとも256のエントロピーを持つシークレットを生成してください。SALT: ハッシュ化された API キーのソルトに使用します。openssl rand -base64 32を使用して、少なくとも 256 ビットのエントロピーを持つシークレットを生成してください。ENCRYPTION_KEY: 機密データの暗号化に使用します。256ビット、16進数形式の64文字の文字列である必要があります。生成にはopenssl rand -hex 32を使用してください。
- スペースを作成をクリックしてください!
ユーザーアクセス
Langfuse Space は、安全な認証のために Hugging Face OAuth が事前設定されています。そのため、初回ログイン時にポップアップの指示に従い、Hugging Face アカウントへのreadアクセスを承認する必要があります。
アプリ内では、ネイティブの Langfuse 機能を使用して、Organization、Project、User を管理できます。
Langfuseスペースの必須設定として、Langfuse API/SDKがアプリにアクセスできるように、可視性をpublicに設定する必要があります。これにより、デフォルトでは、すべてのログイン済みのHugging FaceユーザーがLangfuseスペースにアクセスできるようになります。
新しいユーザーがサインアップしてスペースにアクセスすることを防ぐには、2つの異なる方法があります。
1. (推奨) Hugging Face ネイティブの組織レベルの OAuth 制限
指定した組織のメンバーのみへのアクセスを制限したい場合は、こちらに示されているように、スペースのREADME.mdファイルにhf_oauth_authorized_orgメタデータフィールドを設定するだけです。
設定が完了すると、指定された組織のメンバーのみがスペースにアクセスできるようになります。
2. 手動アクセス制御
AUTH_DISABLE_SIGNUP 環境変数を true に設定することで、ユーザー単位でアクセスを制限することもできます。この変数を設定する前に、必ずスペースへのサインインと認証を完了してください。そうしないと、ご自身のユーザープロファイルが認証できなくなります。
注:
AUTH_DISABLE_SIGNUP環境変数をtrueに設定してアクセスを制限している場合、新しいユーザーにスペースへのアクセス権を付与するには、まずfalseに設定し直してください（再ビルドの完了を待ってから）、ユーザーを追加して OAuth による認証を行ってもらい、その後trueに設定し直してください。
ステップ2: Langfuseの使用
Langfuseが実行できるようになったので、LLMアプリケーションに計装（instrumentation）を追加して、トレースをキャプチャし、プロンプトを管理し始めることができます。方法を見ていきましょう。
任意のアプリケーションを監視
Langfuseはモデル非依存であり、任意のアプリケーションのトレースに使用できます。Langfuseのドキュメントにある入門ガイドに従って、コードに計装を追加する方法を確認してください。
Langfuseは、Langchain、LlamaIndex、OpenAIなど、多くの人気のあるLLMフレームワークとのネイティブ統合を維持しており、コードの計装を行うためのPythonおよびJS/TS SDKを提供しています。また、Langfuseはデータの取り込みのためのさまざまなAPIエンドポイントを提供しており、Langflow、Dify、Haystackなどの他のオープンソースプロジェクトにも統合されています。
例1: 推論プロバイダーへの呼び出しをトレースする
簡単な例として、Langfuse Python SDK を使用して Inference Providers への LLM 呼び出しをトレースする方法を示します。
まず、LANGFUSE_HOST、LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY の環境変数を設定し、Hugging Face アカウントで認証していることを確認してください。
from langfuse.openai import openai
from huggingface_hub import get_token
client = openai.OpenAI(
base_url="https://huggingface.co/proxy/router.huggingface.co/hf-inference/models/meta-llama/Llama-3.3-70B-Instruct/v1",
api_key=get_token(),
)
messages = [{"role": "user", "content": "What is observability for LLMs?"}]
response = client.chat.completions.create(
model="meta-llama/Llama-3.3-70B-Instruct",
messages=messages,
max_tokens=100,
)例2: Gradioアプリケーションの監視
Hugging Face モデルを使用してシンプルなチャットアプリケーションを作成し、Langfuse でモデル呼び出しとユーザーフィードバックをトレースする方法を示す Gradio テンプレートスペースを作成しました。すべて Hugging Face の外に出ることなく行えます。
始めるには、この Gradio テンプレートスペースを複製し、README の手順に従ってください。
ステップ3: Langfuseでトレースを表示
アプリケーションに計装を実装し、トレースまたはユーザーフィードバックをLangfuseに取り込んだ後、Langfuseでトレースを表示できます。
追加のリソースとサポート
さらにサポートが必要な場合は、GitHub discussionsでスレッドを作成するか、issue を開くことができます。
Update on GitHub