> ## 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.

# Braintrust

[Braintrust](https://www.braintrust.dev/) は、LLM アプリケーション向けの評価・モニタリングプラットフォームです。すべてのモデル呼び出しを記録し、評価指標に照らしてスコアを付け、実験 (experiment) を時系列で比較できます。

SambaNova と連携する方法は 2 つあります。Braintrust の **AI providers** 設定でカスタムの OpenAI 互換プロバイダーとして登録し、Playground とゲートウェイから利用する方法と、標準の OpenAI Python クライアントから直接呼び出してプログラムから評価を実行する方法です。本ガイドでは両方を解説します。

## 前提条件

* [SambaCloud](https://cloud.sambanova.ai/?utm_source=braintrust\&utm_medium=external\&utm_campaign=cloud_signup) のアカウントと API キー
* [Braintrust](https://www.braintrust.dev/signup) のアカウント
* Python 3.10 以降

## セットアップ

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

```bash theme={}
pip install braintrust openai
```

**2. API キーのエクスポート**

```bash theme={}
export SAMBANOVA_API_KEY="your-sambanova-api-key"
export BRAINTRUST_API_KEY="your-braintrust-api-key"
```

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

**3. カスタム 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 キーはマスクされている](https://mintcdn.com/sambanova-systems/HObY37FkTNsi58im/images/docs/integrations/braintrust/braintrust-custom-provider-configured.png?fit=max\&auto=format\&n=HObY37FkTNsi58im\&q=85\&s=f76c51af2d46c6e3749f50a9dad2ebfa)

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

**4. 使用する SambaCloud モデルの登録**

プロバイダーの **Models → Available models** 一覧に表示されるのは、プロバイダー種別「OpenAI」に対する Braintrust の静的カタログだけです。設定したエンドポイントから動的に取得されるわけではないため、`MiniMax` などの SambaNova モデル名で検索しても一致するものはありません。これは表示上の仕様にすぎませんが、明示的に追加するまでは SambaNova のモデルが UI のどこにも (Playground にもゲートウェイにも) 表示されない、という意味を持ちます。

同じプロバイダーの **Setup** タブで **Models** までスクロールし、Registry models の下で **All models** または **None** を選択したうえで、**+ Custom model** をクリックして正確なモデル ID (例: `MiniMax-M3`) を入力します。使用する予定のモデルごとにこの操作を繰り返します。

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

## 使用例: Playground での利用

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

![SambaNova プロバイダーグループの下で MiniMax-M3 がモデルとして選択された Braintrust Playground。モデルの能力を列挙した応答が完了した状態で表示されている](https://mintcdn.com/sambanova-systems/HObY37FkTNsi58im/images/docs/integrations/braintrust/braintrust-playground-minimax-m3.png?fit=max\&auto=format\&n=HObY37FkTNsi58im\&q=85\&s=65ec5694ad7b773ea2262b2e5618f584)

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

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

```bash theme={}
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?"}]}'
```

```text Output (abridged) theme={}
HTTP/2 200
x-bt-used-endpoint: SambaNova

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

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

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

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

```python eval_sambanova.py theme={}
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],
)
```

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

```bash theme={}
braintrust eval eval_sambanova.py
```

```text Output (abridged) theme={}
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 が表示されている](https://mintcdn.com/sambanova-systems/HObY37FkTNsi58im/images/docs/integrations/braintrust/braintrust-experiment-results.png?fit=max\&auto=format\&n=HObY37FkTNsi58im\&q=85\&s=149de99f11935fd56f52ada77dad8212)

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

## 参考情報

> **[Braintrust ドキュメント](https://www.braintrust.dev/docs)**
>
> 評価、ログ記録、データセット、Playground を扱う公式ガイドです。

> **[対応モデル](https://docs.sambanova.ai/docs/ja/models/sambacloud-models.md)**
>
> 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"` でエクスポートしてください。

> **ValueError: Could not login to Braintrust**
>
> `BRAINTRUST_API_KEY` が設定されていません。エクスポートする (`export BRAINTRUST_API_KEY="your-key"`) か、`.env.braintrust` ファイルに追加してください。Braintrust にログを送信せずに評価を実行するには、`--no-send-logs` を追加します。