> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Langfuse

[Langfuse](https://langfuse.com/) は、トレーシング、プロンプト Playground、LLM-as-a-judge 評価の機能を備えたオープンソースの LLM エンジニアリングプラットフォームです。Langfuse はカスタムのベース URL を通じて任意の OpenAI 互換プロバイダーを利用できるため、Langfuse 側のコードを変更することなく、SambaCloud のモデルをそのまま使用できます。本ガイドでは、**Playground**、**Experiments** (データセット実行)、**LLM-as-a-judge Evaluator** (評価器)、そしてそれらの結果が集約される **Scores** について解説します。

> [!NOTE]
>
> この連携では、Project Settings 配下に保存される Langfuse のプロジェクトごとの
> **LLM Connections** を使用します。これとは別に、セルフホスト型のデプロイメントでは、
> インスタンス全体に適用される設定
> (`LANGFUSE_AI_PROVIDER` / `LANGFUSE_AI_BASE_URL`) で Langfuse 自身の
> Assistant を SambaCloud に向けることもできます。詳細は後述の
> [応用: インスタンス全体の Assistant](#応用-インスタンス全体の-assistant) をご参照ください。

## 前提条件

* [SambaCloud アカウント](https://cloud.sambanova.ai/?utm_source=langfuse\&utm_medium=external\&utm_campaign=cloud_signup) と API キー。
* **Owner** または **Admin** ロールを持つ [Langfuse プロジェクト](https://langfuse.com/docs/get-started) (クラウドまたはセルフホスト型)。LLM Connections の作成には `llmApiKeys:create` 権限が必要です。Member や Viewer ロールでは、既存の接続は閲覧できますが、「Add LLM Connection」ボタンは表示されません。

## セットアップ

**1. LLM Connections の表示**

Langfuse プロジェクトで **Settings → LLM Connections** に移動し、**Add LLM Connection** をクリックします。

![接続が 1 件も存在しない状態の Langfuse Project Settings の LLM Connections ページ。None と表示された空のテーブルと Add LLM Connection ボタンが写っている](https://mintcdn.com/sambanova-systems/XLkT1cmmawJ9GMO5/images/docs/integrations/langfuse/langfuse-cloud-llm-connections-empty.png?fit=max\&auto=format\&n=XLkT1cmmawJ9GMO5\&q=85\&s=36c07592d3cd63742031e6bd3862e6fc)

**2. 接続の設定**

* **LLM adapter**: `openai` (`api.openai.com` 以外のベース URL は、Langfuse が自動的に OpenAI 互換クライアント経由でルーティングします)
* **Provider name**: `sambanova` (任意のラベルで構いません。モデルピッカーでの表示名になるだけです)
* **API Key**: お使いの SambaCloud API キー
* **Show advanced settings** を展開します。
  * **API Base URL**: `https://api.sambanova.ai/v1`
  * **Enable default models**: **オフ**にします。この設定は OpenAI 自身のモデル一覧を取り込むもので、ここでは該当しません
  * **Custom models**: 使用したい [SambaCloud モデル ID](https://docs.sambanova.ai/docs/ja/models/sambacloud-models.md) を追加します (例: `MiniMax-M3`)。本ガイドを通じて使うモデルとしては `MiniMax-M3` を推奨します。構造化出力に対応しているため、テストでは Playground、Experiments、Evaluator のいずれでも安定して動作しました。

**3. 接続の作成**

**Create connection** をクリックします。設定したベース URL とマスクされた API キーとともに、接続がテーブルに表示されます。

![sambanova 接続が設定された Langfuse の LLM Connections 設定ページ。アダプターは openai、ベース URL は https://api.sambanova.ai/v1 で、API キーはマスクされている](https://mintcdn.com/sambanova-systems/XLkT1cmmawJ9GMO5/images/docs/integrations/langfuse/langfuse-cloud-llm-connection.png?fit=max\&auto=format\&n=XLkT1cmmawJ9GMO5\&q=85\&s=9534414ec6840cd7b3f97e32c9401c2d)

## Playground での利用

**Playground** を開き、モデルセレクターで SambaNova の接続と `MiniMax-M3` モデルを選択し、**"What are your capabilities?"**（どのようなことができますか？）のような質問を投げかけます。実際の質問には、読んで意味のある実際の回答が返ってくるため、使い捨てのテスト文字列よりも適切な動作確認 (そして見栄えのするスクリーンショット) になります。

![sambanova: MiniMax-M3 モデルが選択された Langfuse Playground。メッセージ "What are your capabilities?" に対し、"# My Capabilities" で始まり "I'm a versatile AI assistant that can help with a wide range of tasks" と続く実際の応答が表示されている](https://mintcdn.com/sambanova-systems/XLkT1cmmawJ9GMO5/images/docs/integrations/langfuse/langfuse-cloud-playground.png?fit=max\&auto=format\&n=XLkT1cmmawJ9GMO5\&q=85\&s=0d96dbb14e56bbf1a3bcacca00022f6b)

## Experiments (データセット実行) での利用

**Experiments** を開き、**Run experiment → via User Interface → Configure** をクリックします。プロンプトを選択し、プロバイダー `sambanova` とモデル `MiniMax-M3` をそのまま使用 (または選択) し、データセットを選び、必要に応じて Evaluator を添付し、実行に名前を付けて内容を確認したうえで **Run Experiment** をクリックします。Langfuse はデータセットの項目ごとにモデルを 1 回呼び出し、各行の出力、レイテンシ、コストを記録します。

![データセット実行の Langfuse Experiment 結果テーブル。各行で MiniMax-M3 の実際の出力が期待出力と一致しており、出力テキスト Berlin が期待出力 Berlin の隣に、出力テキスト Paris が期待出力 Paris の隣に表示されている](https://mintcdn.com/sambanova-systems/XLkT1cmmawJ9GMO5/images/docs/integrations/langfuse/langfuse-cloud-experiment-run.png?fit=max\&auto=format\&n=XLkT1cmmawJ9GMO5\&q=85\&s=6ac135e579d58ff5e7244b0b8cd86b7a)

## LLM-as-a-judge Evaluator での利用

**Evaluators → New evaluator** を開き、テンプレートを選択 (または自作) し、**Step 1: Define evaluation** で SambaNova の接続と `MiniMax-M3` モデルを選択します。右側の **Test with sample observations** パネルでは、保存前にサンプルのトレースに対して実際の呼び出しを実行できます。

Evaluator を保存してルールに紐付けると (過去のオブザベーション (observation) への一回限りの遡及適用には「Run evaluator on past observations」を、新しいオブザベーションに対しては定期実行のルールを使用)、Evaluator が動き始めます。以降、Evaluator が実行されるたびに、実際の `Score` 行が書き込まれます。代わりに Evaluator を Experiment の実行に添付すると、そのスコアは各項目の出力のすぐ隣に表示されます。

![Langfuse Experiment 結果テーブル。各行に MiniMax-M3 の実際の出力と、同じモデルが生成した "Classify Input Topic" Evaluator の実際のスコア "other" が並んで表示されている](https://mintcdn.com/sambanova-systems/XLkT1cmmawJ9GMO5/images/docs/integrations/langfuse/langfuse-cloud-evaluator-scores.png?fit=max\&auto=format\&n=XLkT1cmmawJ9GMO5\&q=85\&s=ba515261d8ce4f26655c72c73ce7399a)

## Scores での Evaluator と Experiment の結果の確認

**Scores** を開くと、Evaluator のルール由来かデータセット実行の Experiment 由来かを問わず、`MiniMax-M3` が生成したすべてのスコアを、モデル自身の reasoning と元のトレースへのリンクとともに確認できます。

![source:EVAL でフィルタリングされた Langfuse Scores テーブル。Classify Input Topic という名前の MiniMax-M3 による実際の Evaluator スコアが表示され、いずれも値は "other" で、モデルの reasoning がコメントとして付き、元のトレースへのリンクがある](https://mintcdn.com/sambanova-systems/XLkT1cmmawJ9GMO5/images/docs/integrations/langfuse/langfuse-cloud-scores.png?fit=max\&auto=format\&n=XLkT1cmmawJ9GMO5\&q=85\&s=34663231727ba0aff06ab813df0b7732)

## API による自動化

Settings を画面から操作する代わりに、セットアップをスクリプト化することもできます。Langfuse のパブリック API を使うと、プロジェクトの API キーペアで認証したうえで、LLM Connection を直接作成・更新できます。

```bash theme={}
curl -u <public-key>:<secret-key> \
  -X PUT https://your-langfuse-host/api/public/llm-connections \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "sambanova",
    "adapter": "openai",
    "secretKey": "your-sambacloud-key",
    "baseURL": "https://api.sambanova.ai/v1",
    "withDefaultModels": false,
    "customModels": ["MiniMax-M3"]
  }'
```

この API は `(project, provider)` をキーとしたアップサート (upsert) として動作するため、同じ `provider` 値で再実行しても、接続が重複することなく既存の接続が更新されます。セルフホスト環境の再デプロイ後やローカル開発環境のリセット後に、接続を再プロビジョニングする際に便利です。UI のフォームとまったく同じ行を作成するため、この方法で設定した内容は Playground、Experiments、Evaluator で即座に利用できます。

## 応用: インスタンス全体の Assistant

セルフホスト型のデプロイメントでは、プロジェクトごとの LLM Connection の代わりに (または併用して)、Langfuse 自身の Assistant (アプリ内エージェント) をインスタンス全体で SambaCloud に向けることもできます。

```bash theme={}
LANGFUSE_AI_PROVIDER=openai
LANGFUSE_AI_BASE_URL=https://api.sambanova.ai/v1
LANGFUSE_AI_API_KEY=your-sambacloud-key
LANGFUSE_AI_MODEL=Meta-Llama-3.3-70B-Instruct
LANGFUSE_IN_APP_AGENT_ENABLED=true
```

> [!NOTE]
>
> 「Ask AI」と検索バーの AI サジェストは、Langfuse Cloud のリージョンに限定された
> 別機能です。どのプロバイダーを設定しても、セルフホスト型のデプロイメントでは
> 利用できません。これは Langfuse プラットフォーム側の制約であり、SambaNova
> 固有の問題ではありません。

## トラブルシューティング

> **Add LLM Connection ボタンが表示されない**
>
> LLM Connections の作成には `llmApiKeys:create` 権限が必要で、この権限はプロジェクトの
> **Owner** ロールと **Admin** ロールにのみ付与されます。**Member** や **Viewer** には
> 接続のテーブルは表示されますが、作成ボタンは表示されません。プロジェクトのオーナーに
> 接続の追加、またはロールの昇格を依頼してください。

> **接続テスト、Playground、Experiment の呼び出しが認証エラーで失敗する**
>
> API キーが有効で失効していない [SambaCloud API キー](https://cloud.sambanova.ai/apis)
> であること、**API Base URL** が正確に `https://api.sambanova.ai/v1` であること
> (末尾にパスや `/chat/completions` を付けない) を確認してください。Experiment の実行は、
> 全項目がエラーとして記録されていても、Formatted 表示にはエラーバナーが出ないまま
> 完了することがあります。エラー数が想定外に多い状態で実行が完了した場合は、
> **Raw output** や各項目のエラーステータスを確認してください。

> **Evaluator や Experiment の呼び出しがエラー BAD REQUEST で失敗する**
>
> この Evaluator やデータセット実行には、`MiniMax-M3` か、構造化出力に対応した
> カタログ内の別モデルへの切り替えを推奨します。Langfuse のツール呼び出しを強制する
> フローには、制約付きデコーディング (constrained decoding) を備えたモデルの方が
> 適しています。

> **Playground、Experiment、Evaluator のモデルピッカーにモデルが表示されない**
>
> モデル ID が接続の **Custom models** に登録されていること
> (Settings → LLM Connections → 編集)、そして実在する
> [SambaCloud モデル ID](https://docs.sambanova.ai/docs/ja/models/sambacloud-models.md) と正確に一致していることを
> 確認してください。モデル ID は大文字と小文字を区別します。

## 参考情報

* [Langfuse の LLM Connections ドキュメント](https://langfuse.com/docs/administration/llm-connection)（英語）
* [SambaCloud モデル](https://docs.sambanova.ai/docs/ja/models/sambacloud-models.md)