Skip to main content
Langfuse は、トレーシング、プロンプト Playground、LLM-as-a-judge 評価の機能を備えたオープンソースの LLM エンジニアリングプラットフォームです。Langfuse はカスタムのベース URL を通じて任意の OpenAI 互換プロバイダーを利用できるため、Langfuse 側のコードを変更することなく、SambaCloud のモデルをそのまま使用できます。本ガイドでは、Playground、Experiments (データセット実行)、LLM-as-a-judge Evaluator (評価器)、そしてそれらの結果が集約される Scores について解説します。
この連携では、Project Settings 配下に保存される Langfuse のプロジェクトごとの LLM Connections を使用します。これとは別に、セルフホスト型のデプロイメントでは、 インスタンス全体に適用される設定 (LANGFUSE_AI_PROVIDER / LANGFUSE_AI_BASE_URL) で Langfuse 自身の Assistant を SambaCloud に向けることもできます。詳細は後述の 応用: インスタンス全体の Assistant をご参照ください。

​
前提条件

  • SambaCloud アカウント と API キー。
  • Owner または Admin ロールを持つ Langfuse プロジェクト (クラウドまたはセルフホスト型)。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 ボタンが写っている
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 を追加します (例: MiniMax-M3)。本ガイドを通じて使うモデルとしては MiniMax-M3 を推奨します。構造化出力に対応しているため、テストでは Playground、Experiments、Evaluator のいずれでも安定して動作しました。
3

接続の作成

Create connection をクリックします。設定したベース URL とマスクされた API キーとともに、接続がテーブルに表示されます。
sambanova 接続が設定された Langfuse の LLM Connections 設定ページ。アダプターは openai、ベース URL は https://api.sambanova.ai/v1 で、API キーはマスクされている

​
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" と続く実際の応答が表示されている

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

Experiments を開き、Run experiment → via User Interface → Configure をクリックします。プロンプトを選択し、プロバイダー sambanova とモデル MiniMax-M3 をそのまま使用 (または選択) し、データセットを選び、必要に応じて Evaluator を添付し、実行に名前を付けて内容を確認したうえで Run Experiment をクリックします。Langfuse はデータセットの項目ごとにモデルを 1 回呼び出し、各行の出力、レイテンシ、コストを記録します。
データセット実行の Langfuse Experiment 結果テーブル。各行で MiniMax-M3 の実際の出力が期待出力と一致しており、出力テキスト Berlin が期待出力 Berlin の隣に、出力テキスト Paris が期待出力 Paris の隣に表示されている

​
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" が並んで表示されている

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

Scores を開くと、Evaluator のルール由来かデータセット実行の Experiment 由来かを問わず、MiniMax-M3 が生成したすべてのスコアを、モデル自身の reasoning と元のトレースへのリンクとともに確認できます。
source:EVAL でフィルタリングされた Langfuse Scores テーブル。Classify Input Topic という名前の MiniMax-M3 による実際の Evaluator スコアが表示され、いずれも値は "other" で、モデルの reasoning がコメントとして付き、元のトレースへのリンクがある

​
API による自動化

Settings を画面から操作する代わりに、セットアップをスクリプト化することもできます。Langfuse のパブリック API を使うと、プロジェクトの API キーペアで認証したうえで、LLM Connection を直接作成・更新できます。
この API は (project, provider) をキーとしたアップサート (upsert) として動作するため、同じ provider 値で再実行しても、接続が重複することなく既存の接続が更新されます。セルフホスト環境の再デプロイ後やローカル開発環境のリセット後に、接続を再プロビジョニングする際に便利です。UI のフォームとまったく同じ行を作成するため、この方法で設定した内容は Playground、Experiments、Evaluator で即座に利用できます。

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

セルフホスト型のデプロイメントでは、プロジェクトごとの LLM Connection の代わりに (または併用して)、Langfuse 自身の Assistant (アプリ内エージェント) をインスタンス全体で SambaCloud に向けることもできます。
「Ask AI」と検索バーの AI サジェストは、Langfuse Cloud のリージョンに限定された 別機能です。どのプロバイダーを設定しても、セルフホスト型のデプロイメントでは 利用できません。これは Langfuse プラットフォーム側の制約であり、SambaNova 固有の問題ではありません。

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

LLM Connections の作成には llmApiKeys:create 権限が必要で、この権限はプロジェクトの Owner ロールと Admin ロールにのみ付与されます。Member や Viewer には 接続のテーブルは表示されますが、作成ボタンは表示されません。プロジェクトのオーナーに 接続の追加、またはロールの昇格を依頼してください。
API キーが有効で失効していない SambaCloud API キー であること、API Base URL が正確に https://api.sambanova.ai/v1 であること (末尾にパスや /chat/completions を付けない) を確認してください。Experiment の実行は、 全項目がエラーとして記録されていても、Formatted 表示にはエラーバナーが出ないまま 完了することがあります。エラー数が想定外に多い状態で実行が完了した場合は、 Raw output や各項目のエラーステータスを確認してください。
この Evaluator やデータセット実行には、MiniMax-M3 か、構造化出力に対応した カタログ内の別モデルへの切り替えを推奨します。Langfuse のツール呼び出しを強制する フローには、制約付きデコーディング (constrained decoding) を備えたモデルの方が 適しています。
モデル ID が接続の Custom models に登録されていること (Settings → LLM Connections → 編集)、そして実在する SambaCloud モデル ID と正確に一致していることを 確認してください。モデル ID は大文字と小文字を区別します。

​
参考情報