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

# DeepEval

[DeepEval](https://deepeval.com/) は、`pytest` に組み込んで使えるオープンソースの LLM 評価フレームワークです。ジャッジ (judge) モデルの呼び出しを、通常のテストスイートや CI パイプラインの一部として実行できます。

## 前提条件

* [SambaCloud](https://cloud.sambanova.ai/?utm_source=deepeval\&utm_medium=external\&utm_campaign=cloud_signup) のアカウントと [API キー](https://cloud.sambanova.ai/apis?utm_source=deepeval\&utm_medium=external\&utm_campaign=cloud_signup)
* Python 3.9 以上

## セットアップ

**1. DeepEval のインストール**

```bash theme={}
pip install deepeval pytest
```

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

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

**3. DeepEval のジャッジモデルを SambaCloud に接続**

DeepEval の `OpenAIModel` クラスに、カスタムの `base_url` を指定して使用します。これは DeepEval が本来の OpenAI への接続に使うクラスそのもので、接続先を差し替えているだけです。

```python theme={}
import os
from deepeval.models import OpenAIModel

model = OpenAIModel(
    model="MiniMax-M3",
    api_key=os.environ["SAMBANOVA_API_KEY"],
    base_url="https://api.sambanova.ai/v1",
)
```

> [!NOTE]
>
> パラメータの完全な一覧は、[DeepEval の OpenAI モデルリファレンス](https://deepeval.com/integrations/models/openai)（英語）をご参照ください。旧称の `GPTModel` もまったく同じように動作しますが、DeepEval 4.x 時点で非推奨 (deprecated) となっており、現行の名前は `OpenAIModel` です。

## 使用例: テストケースの採点

```python test_sambanova.py theme={}
import os
from deepeval.models import OpenAIModel
from deepeval.test_case import LLMTestCase
from deepeval.metrics import AnswerRelevancyMetric

model = OpenAIModel(
    model="MiniMax-M3",
    api_key=os.environ["SAMBANOVA_API_KEY"],
    base_url="https://api.sambanova.ai/v1",
)

test_case = LLMTestCase(
    input="What is the capital of France?",
    actual_output="The capital of France is Paris.",
)

metric = AnswerRelevancyMetric(model=model, threshold=0.5)
metric.measure(test_case)
print(metric.score)
print(metric.reason)
```

```text Output theme={}
1.0
The score is 1.00 because the response directly and accurately addresses the question about the capital of France with no irrelevant information. Excellent work!
```

`reason` の文字列はジャッジモデルが生成するものであり、スコアの値を言い換えるのではなく、そのスコアになった理由を説明します。

## 使用例: pytest の CI チェックとしての実行

通常のテストスイートの中でジャッジモデルの呼び出しを実行する、DeepEval の主なユースケースです。

```python test_ci_example.py theme={}
import os
from deepeval import assert_test
from deepeval.models import OpenAIModel
from deepeval.test_case import LLMTestCase
from deepeval.metrics import AnswerRelevancyMetric

model = OpenAIModel(
    model="MiniMax-M3",
    api_key=os.environ["SAMBANOVA_API_KEY"],
    base_url="https://api.sambanova.ai/v1",
)

def test_answer_relevancy():
    test_case = LLMTestCase(
        input="What is the capital of France?",
        actual_output="The capital of France is Paris.",
    )
    metric = AnswerRelevancyMetric(model=model, threshold=0.5)
    assert_test(test_case, [metric])
```

DeepEval 自身の CLI で実行します (公式ドキュメントに記載されているコマンドで、内部では `pytest` が動作します)。

```bash theme={}
deepeval test run test_ci_example.py
```

```text Output (abridged) theme={}
✓ Evaluation completed 🎉! (time taken: 5.44s | token cost: None)
» Test Results (1 total tests):
   » Pass Rate: 100.0% | Passed: 1 | Failed: 0
```

> [!NOTE]
>
> DeepEval は `pytest` プラグインであるため、通常どおり `pytest test_ci_example.py -v` でも実行できます。ただし、公式ドキュメントに記載されているコマンドは `deepeval test run` で、上記のような詳細なテスト結果の表も表示されます。

> [!TIP]
>
> 評価をローカルで実行するにあたり、DeepEval 自体へのログインや API キーは不要です。`deepeval login` は任意で、Confident AI のクラウドダッシュボードを利用する場合にのみ必要です。本ページの例で必要な認証情報は、`OpenAIModel` に渡す SambaCloud の API キーのみです。

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

> **DeprecationWarning: 'GPTModel' is deprecated**
>
> 代わりに `OpenAIModel` を使用してください。コンストラクターも `base_url` の指定方法も同一で、DeepEval 4.x 時点の現行の名前に変わっただけです。

> **KeyError: SAMBANOVA\_API\_KEY**
>
> 実行前にキーをエクスポートしてください: `export SAMBANOVA_API_KEY="your-key"`。`echo $SAMBANOVA_API_KEY` で確認できます。

> **AnswerRelevancyMetric のスコアが低い・想定と異なる**
>
> `metric.reason` を確認してください。これはジャッジモデル自身が生成する文字列で、何を減点したのかを具体的に説明しています。問題の原因がプロンプトにあるのか、テストケースにあるのか、ジャッジモデルの解釈にあるのかを切り分けるうえで、スコアの値だけを見るよりも役立ちます。

## 参考情報

* [DeepEval スタートガイド](https://deepeval.com/docs/getting-started)（英語）
* [DeepEval の OpenAI モデルリファレンス](https://deepeval.com/integrations/models/openai)（英語）
* [SambaCloud の対応モデル](https://docs.sambanova.ai/docs/ja/models/sambacloud-models.md)