Braintrust

Braintrust は、LLM アプリケーション向けの評価・モニタリングプラットフォームです。すべてのモデル呼び出しを記録し、評価指標に照らしてスコアを付け、実験 (experiment) を時系列で比較できます。 SambaNova と連携する方法は 2 つあります。Braintrust の AI providers 設定でカスタムの OpenAI 互換プロバイダーとして登録し、Playground とゲートウェイから利用する方法と、標準の OpenAI Python クライアントから直接呼び出してプログラムから評価を実行する方法です。本ガイドでは両方を解説します。

前提条件

SambaCloud のアカウントと API キー
Braintrust のアカウント
Python 3.10 以降

セットアップ

Braintrust SDK と OpenAI クライアントのインストール

pip install braintrust openai

API キーのエクスポート

export SAMBANOVA_API_KEY="your-sambanova-api-key"
export BRAINTRUST_API_KEY="your-braintrust-api-key"

Braintrust の API キーは、Settings 内の AI providers ページまたは API keys ページのどちらからでも生成できます。アプリ内のどこにある「Generate API key」ボタンも同じように機能します。

カスタム AI プロバイダーとしての SambaNova の登録

Braintrust で Settings → AI providers → Organization provider に移動し、Custom providers の下にある + をクリックします。以下のとおり設定します。

Provider type: OpenAI
Name: SambaNova
API key: お使いの SambaCloud API キー
More settings → API base URL: https://api.sambanova.ai/v1

SambaNova という名前の Organization AI プロバイダーが表示された Braintrust の AI providers 設定ページ。種別は Custom、ステータスは Saved で、API キーはマスクされている

ダイアログ内の Test ボタンはブラウザから直接プロバイダーを呼び出すため、SambaNova のエンドポイントに対しては TypeError: Failed to fetch で失敗します。これはテスト呼び出しに対するブラウザの CORS 制限によるもので、設定の誤りを示すものではありません。そのまま Create をクリックしてください。プロバイダーは問題なく動作します (後述)。

使用する SambaCloud モデルの登録

プロバイダーの Models → Available models 一覧に表示されるのは、プロバイダー種別「OpenAI」に対する Braintrust の静的カタログだけです。設定したエンドポイントから動的に取得されるわけではないため、MiniMax などの SambaNova モデル名で検索しても一致するものはありません。これは表示上の仕様にすぎませんが、明示的に追加するまでは SambaNova のモデルが UI のどこにも (Playground にもゲートウェイにも) 表示されない、という意味を持ちます。同じプロバイダーの Setup タブで Models までスクロールし、Registry models の下で All models または None を選択したうえで、+ Custom model をクリックして正確なモデル ID (例: MiniMax-M3) を入力します。使用する予定のモデルごとにこの操作を繰り返します。

Braintrust の UI 全体で SambaNova モデルを利用可能にするのがこのステップです。Playground のモデルピッカーも後述のゲートウェイエンドポイントも、静的カタログではなくこの一覧を参照します。

使用例: Playground での利用

カスタムモデルとして登録すると (前のステップ)、SambaNova のモデルは Playground のモデルピッカーで、Braintrust 組み込みのプロバイダー群と並ぶ SambaNova グループの下に表示されます。

SambaNova プロバイダーグループの下で MiniMax-M3 がモデルとして選択された Braintrust Playground。モデルの能力を列挙した応答が完了した状態で表示されている

使用例: ゲートウェイ経由での呼び出し

Braintrust のゲートウェイ (https://gateway.braintrust.dev) は、登録済みの任意のカスタムプロバイダーとモデルへリクエストをプロキシします。認証にはプロバイダー自身のキーではなく、Braintrust の API キーを使用します。

curl -i -X POST 'https://gateway.braintrust.dev/chat/completions' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "x-bt-org-name: Your Org Name" \
  -H "x-bt-endpoint-name: SambaNova" \
  -d '{"model":"MiniMax-M3","messages":[{"role":"user","content":"What can you do?"}]}'

Output (abridged)

HTTP/2 200
x-bt-used-endpoint: SambaNova

{"choices":[{"message":{"content":"I'm a versatile AI assistant...","role":"assistant"}}], "model":"MiniMax-M3", ...}

この方法が機能するのは、プロバイダーに カスタムモデル として明示的に追加したモデルだけです (前のセクション)。静的カタログにしか存在しないモデル ID や、追加前のモデル ID で呼び出すと、404 とともに Braintrust gateway error: no provider named '...' configured ... Configured providers: [] が返されます。プロバイダー自体が存在しないかのように見えるエラーですが、実際には、リクエストしたモデルがまだそのプロバイダーに登録されていないことを意味します。

使用例: スコア付き評価の実行

プログラムから評価を実行するための方法です。実際の評価をスコア付きで実行し、結果をダッシュボードで確認できます。標準の OpenAI クライアントを SambaNova に向け、braintrust.wrap_openai でラップすることで、Braintrust はスコアに加えて呼び出しの完全なトレース情報 (トークン数、所要時間、呼び出し回数) を記録します。

eval_sambanova.py

import os
from openai import OpenAI
from braintrust import Eval, wrap_openai

client = wrap_openai(
    OpenAI(
        base_url="https://api.sambanova.ai/v1",
        api_key=os.environ["SAMBANOVA_API_KEY"],
    )
)

def task(input):
    response = client.chat.completions.create(
        model="MiniMax-M3",
        messages=[{"role": "user", "content": input}],
    )
    return response.choices[0].message.content

def exact_match(input, output, expected):
    return 1.0 if expected.lower() in output.lower() else 0.0

Eval(
    "SambaNova Docs Verification",
    data=lambda: [
        {"input": "What is the capital of France?", "expected": "Paris"},
        {"input": "What is the capital of Japan?", "expected": "Tokyo"},
    ],
    task=task,
    scores=[exact_match],
)

以下のコマンドで実行します。

braintrust eval eval_sambanova.py

Output (abridged)

Experiment your-name-1792348392 is running at https://www.braintrust.dev/app/.../experiments/...

=========================SUMMARY=========================
100.00% 'exact_match' score

1 'llm_calls'
134tok 'prompt_tokens'
46.50tok 'completion_tokens'
180.50tok 'total_tokens'
7.00s 'duration'

2 行からなる Braintrust の実験結果テーブル。各行とも exact_match 列のスコアは 100% で、正しい出力として Tokyo と Paris が表示されている

ここで鍵になるのが wrap_openai です。ラップなしで同じ評価を実行しても完了し、スコアも正しく算出されますが、サマリーには 0 llm_calls と表示され、トークン関連のメトリクスもすべて 0tok になります。クライアントがラップされていない限り、Braintrust は背後のモデル呼び出しを把握できないためです。評価は成功しているのに実験ダッシュボードの LLM 呼び出し数が 0 になっている場合、これが原因です。なお、この方法ではセットアップのステップ 4 で行ったカスタムモデルの登録は不要です。素の OpenAI クライアントは Braintrust のゲートウェイや UI を経由せず SambaCloud と直接通信するため、登録の有無にかかわらず任意のモデル文字列で動作します。

参考情報

Braintrust ドキュメント

評価、ログ記録、データセット、Playground を扱う公式ガイドです。

対応モデル

SambaCloud で現在利用可能なモデルの一覧です。

トラブルシューティング

ゲートウェイや Playground でモデルが見つからない、または Configured providers: [] と表示される

そのモデルがまだプロバイダーにカスタムモデルとして追加されていません。Settings → AI providers → SambaNova → Setup → Models に移動し、+ Custom model をクリックして正確なモデル ID を追加してください。Models → Available models の静的カタログ検索には、この手順を終えても SambaNova のモデルは表示されません。この一覧は、実際にどのモデルが動作するかとは無関係です。

カスタムプロバイダーの Test ボタンが TypeError: Failed to fetch で失敗する

これは、ダイアログ内のテスト呼び出しが SambaNova のエンドポイントに対して受けるブラウザの CORS 制限によるもので、設定の誤りではありません。Create をクリックし、動作確認は Playground か実際の評価で行ってください。

評価は実行できるが、すべてのメトリクスが 0 llm_calls・0tok になる

OpenAI クライアントがラップされていません。素の OpenAI(...) インスタンスではなく braintrust.wrap_openai(OpenAI(...)) を使用してください。詳細はスコア付き評価の実行をご参照ください。

Failed to import eval_sambanova.py: 'SAMBANOVA_API_KEY'

braintrust eval を実行しているシェルで SAMBANOVA_API_KEY が設定されていません。export SAMBANOVA_API_KEY="your-key" でエクスポートしてください。

概要

開発者ツール

フレームワーク

インターフェースとローコード

データとインフラ

マルチモーダル

評価とモニタリング

前提条件

セットアップ

使用例: Playground での利用

使用例: ゲートウェイ経由での呼び出し

使用例: スコア付き評価の実行

参考情報

Braintrust ドキュメント

対応モデル

トラブルシューティング

​前提条件

​セットアップ

​使用例: Playground での利用

​使用例: ゲートウェイ経由での呼び出し

​使用例: スコア付き評価の実行

​参考情報

Braintrust ドキュメント

対応モデル

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

前提条件

セットアップ

使用例: Playground での利用

使用例: ゲートウェイ経由での呼び出し

使用例: スコア付き評価の実行

参考情報

トラブルシューティング