# Spaces での Langfuse

このガイドでは、LangfuseをHugging Face Spacesにデプロイし、LLMアプリケーションの観測可能性（Observability）のために計装（Instrumentation）を開始する方法を示します。この統合により、Hugging Face Hub上でLLM APIの実験を行い、プロンプトを1か所で管理し、モデルの出力を評価できます。

## Langfuseとは何ですか？

[Langfuse](https://langfuse.com)は、LLMアプリケーションのデバッグ、評価、反復改善をチームで協力的に行うことを支援するオープンソースのLLMエンジニアリングプラットフォームです。

Langfuseの主な機能には、アプリケーションの実行フローの完全なコンテキストをキャプチャするためのLLMトレーシング、プロンプトの集中管理と協業による反復を可能にするプロンプト管理、出力品質を評価するための評価指標、テストおよびベンチマーク作成のためのデータセット作成、そしてプロンプトやモデル設定の実験を行うためのプレイグラウンドが含まれます。

_この動画は、Langfuseの機能を紹介する10分のウォークスルーです：_

## なぜLLMの観測可能性（Observability）が必要なのか？

- 言語モデルがより広く普及するにつれ、その動作やパフォーマンスを理解することが重要になります。
- **LLM observability**とは、LLMアプリケーションの出力を通じて、その内部状態を監視し理解することを指します。
- 以下のような課題に対処するために不可欠です：
  - 繰り返し呼び出しや連鎖した呼び出しを含む**複雑な制御フロー**により、デバッグが困難になる。
  - **非決定論的な出力**により、一貫した品質評価の複雑さが生じる。
  - **多様なユーザーの意図**。ユーザー体験を向上させるには、深い理解が必要です。
- LLMアプリケーションの構築には複雑なワークフローが伴いますが、オブザーバビリティを活用することで、これらの複雑さを管理できます。

## ステップ1: SpacesでLangfuseを設定する

Langfuse Hugging Face Space を使用すると、数回のクリックでデプロイ済みの Langfuse をすぐに利用できます。

    

開始するには、上記のボタンをクリックするか、以下の手順に従ってください:

1. [**新しい Hugging Face Space**](https://huggingface.co/new-space) を作成します
2. Space SDK として **Docker** を選択します
3. Space テンプレートとして**Langfuse**を選択します
4. 再起動後も Langfuse のデータが永続化されるように、**[Storage Bucket](https://huggingface.co/docs/hub/storage-buckets)** をアタッチしてください
5. Langfuse API/SDKがアプリにアクセスできるように、スペースの表示設定を**public**に設定してください（詳細は以下の注記を参照してください）
6. [任意ですが推奨] 安全なデプロイのために、**環境変数**のデフォルト値を置き換えてください：
   - `NEXTAUTH_SECRET`: ログインセッションのCookieを検証するために使用します。`openssl rand -base64 32` を使用して、少なくとも256のエントロピーを持つシークレットを生成してください。
   - `SALT`: ハッシュ化された API キーのソルトに使用します。`openssl rand -base64 32` を使用して、少なくとも 256 ビットのエントロピーを持つシークレットを生成してください。
   - `ENCRYPTION_KEY`: 機密データの暗号化に使用します。256ビット、16進数形式の64文字の文字列である必要があります。生成には `openssl rand -hex 32` を使用してください。
7. **スペースを作成**をクリックしてください!

![Clone the Langfuse Space](https://langfuse.com/images/cookbook/huggingface/huggingface-space-setup.png)

### ユーザーアクセス

Langfuse Space は、安全な認証のために Hugging Face OAuth が事前設定されています。そのため、初回ログイン時にポップアップの指示に従い、Hugging Face アカウントへの`read`アクセスを承認する必要があります。

アプリ内では、[ネイティブの Langfuse 機能](https://langfuse.com/docs/rbac)を使用して、Organization、Project、User を管理できます。

Langfuseスペースの_必須_設定として、Langfuse API/SDKがアプリにアクセスできるように、可視性を**public**に設定する必要があります。これにより、デフォルトでは、_すべての_ログイン済みのHugging FaceユーザーがLangfuseスペースにアクセスできるようになります。

新しいユーザーがサインアップしてスペースにアクセスすることを防ぐには、2つの異なる方法があります。

#### 1. (推奨) Hugging Face ネイティブの組織レベルの OAuth 制限

指定した組織のメンバーのみへのアクセスを制限したい場合は、[こちら](https://huggingface.co/docs/hub/spaces-oauth#create-an-oauth-app)に示されているように、スペースの`README.md`ファイルに`hf_oauth_authorized_org`メタデータフィールドを設定するだけです。

設定が完了すると、指定された組織のメンバーのみがスペースにアクセスできるようになります。

#### 2. 手動アクセス制御

`AUTH_DISABLE_SIGNUP` 環境変数を `true` に設定することで、ユーザー単位でアクセスを制限することもできます。この変数を設定する前に、必ずスペースへのサインインと認証を完了してください。そうしないと、ご自身のユーザープロファイルが認証できなくなります。

> [!TIP]
> **注:** `AUTH_DISABLE_SIGNUP` 環境変数を `true` に設定してアクセスを制限している場合、新しいユーザーにスペースへのアクセス権を付与するには、まず `false` に設定し直してください（再ビルドの完了を待ってから）、ユーザーを追加して OAuth による認証を行ってもらい、その後 `true` に設定し直してください。

## ステップ2: Langfuseの使用

Langfuseが実行できるようになったので、LLMアプリケーションに計装（instrumentation）を追加して、トレースをキャプチャし、プロンプトを管理し始めることができます。方法を見ていきましょう。

### 任意のアプリケーションを監視 

Langfuseはモデル非依存であり、任意のアプリケーションのトレースに使用できます。Langfuseのドキュメントにある[入門ガイド](https://langfuse.com/docs)に従って、コードに計装を追加する方法を確認してください。

Langfuseは、[Langchain](https://langfuse.com/docs/integrations/langchain/tracing)、[LlamaIndex](https://langfuse.com/docs/integrations/llama-index/get-started)、[OpenAI](https://langfuse.com/docs/integrations/openai/python/get-started)など、多くの人気のあるLLMフレームワークとのネイティブ統合を維持しており、コードの計装を行うためのPythonおよびJS/TS SDKを提供しています。また、Langfuseはデータの取り込みのためのさまざまなAPIエンドポイントを提供しており、[Langflow](https://langfuse.com/docs/integrations/langflow)、[Dify](https://langfuse.com/docs/integrations/dify)、[Haystack](https://langfuse.com/docs/integrations/haystack/get-started)などの他のオープンソースプロジェクトにも統合されています。

### 例1: 推論プロバイダーへの呼び出しをトレースする

簡単な例として、Langfuse Python SDKを使用して[Inference Providers](https://huggingface.co/docs/inference-providers/en/index)へのLLM呼び出しをトレースする方法を示します。

まず、`LANGFUSE_HOST`、`LANGFUSE_PUBLIC_KEY`、`LANGFUSE_SECRET_KEY` の環境変数を設定し、[Hugging Face アカウントで認証](https://huggingface.co/docs/huggingface_hub/en/quick-start#authentication)していることを確認してください。

```python
from langfuse.openai import openai
from huggingface_hub import get_token

client = openai.OpenAI(
    base_url="https://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 テンプレートスペースを複製](https://huggingface.co/spaces/langfuse/langfuse-gradio-example-template?duplicate=true)し、[README](https://huggingface.co/spaces/langfuse/langfuse-gradio-example-template/blob/main/README.md) の手順に従ってください。

## ステップ3: Langfuseでトレースを表示

アプリケーションに計装を実装し、トレースまたはユーザーフィードバックをLangfuseに取り込んだ後、Langfuseでトレースを表示できます。

![Example trace with Gradio](https://langfuse.com/images/cookbook/huggingface/huggingface-gradio-example-trace.png)

_[Langfuse UI でのトレースの例](https://langfuse-langfuse-template-space.hf.space/project/cm4r1ajtn000a4co550swodxv/traces/9cdc12fb-71bf-4074-ab0b-0b8d212d839f?timestamp=2024-12-20T12%3A12%3A50.089Z&view=preview)_

## 追加のリソースとサポート

- [Langfuse ドキュメント](https://langfuse.com/docs)
- [Langfuse GitHub リポジトリ](https://github.com/langfuse/langfuse)
- [Langfuse Discord](https://langfuse.com/discord)
- [Langfuse テンプレートスペース](https://huggingface.co/spaces/langfuse/langfuse-template-space)

さらにサポートが必要な場合は、[GitHub discussions](https://langfuse.com/discussions)でスレッドを作成するか、[issue を開く](https://github.com/langfuse/langfuse/issues)ことができます。