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

# Deepgram

[Deepgram](https://deepgram.com/) は音声プラットフォームで、その Voice Agent API は、speech-to-text (音声認識)、LLM、text-to-speech (音声合成) を単一の WebSocket 上で実行します。LLM のステップは差し替え可能です: `open_ai` プロバイダータイプは、OpenAI Chat Completions 形式に従う任意のエンドポイントを受け付けます。接続先を SambaCloud にすると、Deepgram の音声エージェントが SambaNova モデルで回答するようになります。音声では最初のトークンが届くまでの速さが重要になるため、本ガイドではモデルごとにその時間も計測します。

## 前提条件

* [SambaCloud](https://cloud.sambanova.ai/?utm_source=deepgram\&utm_medium=external\&utm_campaign=cloud_signup) のアカウントと [API キー](https://cloud.sambanova.ai/apis?utm_source=deepgram\&utm_medium=external\&utm_campaign=cloud_signup)
* [Deepgram](https://console.deepgram.com/signup) のアカウントと API キー。キーはコンソールの **API keys** で作成します。
* Python 3.9 以上

> [!NOTE]
>
> macOS では、Python は `python` ではなく `python3` として提供されます。バージョンは `python3 --version` で確認してください。macOS 標準の Python 3.9 で本ガイドは動作します。

## インストールとセットアップ

**1. 仮想環境の作成**

```bash macOS / Linux theme={}
python3 -m venv .venv
source .venv/bin/activate
```

```powershell Windows theme={}
python -m venv .venv
.venv\Scripts\Activate.ps1
```

**2. WebSocket クライアントのインストール**

```bash theme={}
pip install websockets
```

本ガイドは、Python 3.12 上の `websockets` 17.4 と、Python 3.9.6 上の `websockets` 15.0.1 で動作確認済みです。

**3. API キーの設定**

```bash macOS / Linux theme={}
export SAMBANOVA_API_KEY="your-sambanova-api-key"
export DEEPGRAM_API_KEY="your-deepgram-api-key"
```

```powershell Windows theme={}
$env:SAMBANOVA_API_KEY="your-sambanova-api-key"
$env:DEEPGRAM_API_KEY="your-deepgram-api-key"
```

## 音声エージェントの SambaCloud への接続

エージェントの設定は、WebSocket が開いたらすぐに送信する `Settings` メッセージで行います。SambaNova 向けに変更するのは `agent.think` の部分です。

```json theme={}
"think": {
  "provider": {
    "type": "open_ai",
    "model": "MiniMax-M3.1-Flash"
  },
  "endpoint": {
    "url": "https://api.sambanova.ai/v1/chat/completions",
    "headers": { "authorization": "Bearer your-sambanova-api-key" }
  }
}
```

* `provider.type` は `open_ai` で、「OpenAI Chat Completions 形式」を意味します。モデル名には SambaCloud のモデル ID を指定します。
* `endpoint.url` は、ベース URL ではなく、チャット補完のフル URL です。
* `endpoint.headers.authorization` には SambaCloud のキーを設定します。

以下のスクリプトはこの `Settings` メッセージを送信した後、`InjectUserMessage` メッセージでエージェントに質問をテキスト入力するため、マイクなしでテストできます。スクリプトは、会話のトランスクリプトと、各ターンの後に Deepgram が送信するレイテンシレポートを出力し、音声の返答を `reply.wav` として保存します。

```python voice_agent.py theme={}
import asyncio
import json
import os
import wave

import websockets

MODEL = "MiniMax-M3.1-Flash"
QUESTION = "What can you do?"

settings = {
    "type": "Settings",
    "audio": {
        "input": {"encoding": "linear16", "sample_rate": 24000},
        "output": {"encoding": "linear16", "sample_rate": 24000, "container": "none"},
    },
    "agent": {
        "listen": {"provider": {"type": "deepgram", "model": "nova-3"}},
        "think": {
            "provider": {"type": "open_ai", "model": MODEL, "temperature": 0.7},
            "endpoint": {
                "url": "https://api.sambanova.ai/v1/chat/completions",
                "headers": {"authorization": f"Bearer {os.environ['SAMBANOVA_API_KEY']}"},
            },
            "prompt": "You are a helpful voice assistant. Keep answers under two sentences.",
        },
        "speak": {"provider": {"type": "deepgram", "model": "aura-2-thalia-en"}},
    },
}


async def main():
    headers = {"Authorization": f"Token {os.environ['DEEPGRAM_API_KEY']}"}
    audio = bytearray()
    async with websockets.connect(
        "wss://agent.deepgram.com/v1/agent/converse", additional_headers=headers
    ) as ws:
        await ws.send(json.dumps(settings))
        while True:
            try:
                message = await asyncio.wait_for(ws.recv(), timeout=3 if audio else 20)
            except asyncio.TimeoutError:
                break
            if isinstance(message, bytes):
                audio.extend(message)
                continue
            event = json.loads(message)
            kind = event["type"]
            if kind == "SettingsApplied":
                await ws.send(json.dumps({"type": "InjectUserMessage", "content": QUESTION}))
            elif kind == "ConversationText":
                print(f"{event['role']}: {event['content']}")
            elif kind == "LatencyReport":
                print({k: round(v, 3) for k, v in event.items() if k != "type"})
            elif kind in ("Warning", "Error"):
                print(f"{kind}: {event['description']}")
                if kind == "Error":
                    break

    with wave.open("reply.wav", "wb") as wav:
        wav.setnchannels(1)
        wav.setsampwidth(2)
        wav.setframerate(24000)
        wav.writeframes(bytes(audio))
    print(f"Saved reply.wav ({len(audio)} bytes of audio)")


asyncio.run(main())
```

```bash theme={}
python voice_agent.py
```

```text Output theme={}
user: What can you do?
{'ttt_token_latency': 1.534}
{'ttt_text_latency': 1.534}
assistant: I can answer questions, explain concepts, brainstorm ideas, draft and edit text, summarize information, and help with planning or problem-solving.
{'tts_latency': 0.066}
{'total_latency': 1.599}
Saved reply.wav (503040 bytes of audio)
```

> [!NOTE]
>
> `ttt_text_latency` は、LLM からの最初のテキストトークンまでの時間で、音声エージェントで注目すべき数値です。`total_latency` は、ユーザーのターンの終わりから最初の音声バイトが届くまでの時間です。実際の数値は、モデル、プロンプト、ネットワークによって変わります。このテストはテキストを送信しているため、数値に speech-to-text の時間は含まれません。

## 音声向けモデルの選択

上のスクリプトは `MiniMax-M3.1-Flash` を使用しています。音声は、最初のトークンまでのレイテンシが最も重要になる用途であるため、モデルを比較する価値があります。次の表の各行は、`MODEL` だけを変更して上のスクリプトで計測した `ttt_text_latency` です。

| モデル | 最初のテキストトークンまでの時間 |
| :- | :- |
| `MiniMax-M3.1-Flash` | 10 回中 8 回は 1.4〜3.5 秒、2 回は 10〜11 秒 |
| `Meta-Llama-3.3-70B-Instruct` | 12 回中 10 回は 0.24〜0.41 秒、2 回は 3 秒超 |
| `gpt-oss-120b` | 5 回中 4 回は 0.22〜0.26 秒、1 回は 4.9 秒 |
| `gemma-4-31B-it` | 34 回で 1.1〜10.8 秒、中央値 4.3 秒 (2 秒未満が 8 回、5 秒超が 11 回) |

> [!WARNING]
>
> `MiniMax-M3.1-Flash` は Reasoning モデルです。回答を始める前に考える時間を取り、その時間は最初のテキストトークンまでの時間に含まれるため、reasoning を行わないモデルと比べて返答の開始が遅く、遅延はターンごとに変動します。間の長さが最も重要になる音声エージェントでは、`MODEL` を `Meta-Llama-3.3-70B-Instruct` に設定してください。このモデルは、ほとんどの実行で 0.5 秒未満で回答しました。

> [!NOTE]
>
> ばらつきが最も大きかったのは `gemma-4-31B-it` です。最初のトークンまでの時間は約 1.1 秒から 10 秒超まで幅があり、大半の実行は 3〜6 秒でした。`Meta-Llama-3.3-70B-Instruct` と `gpt-oss-120b` でも、テスト中に最初のトークンが数秒かかる遅い実行が時折ありました。レイテンシの数値を引用する前に、複数回の実行で計測してください。

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

> [accordion] KeyError: 'DEEPGRAM\_API\_KEY' or 'SAMBANOVA\_API\_KEY'
>
> Python を実行しているシェルで環境変数が設定されていません。[インストールとセットアップ](#インストールとセットアップ) のとおり設定し、同じシェルからスクリプトを再実行してください。

> [accordion] server rejected WebSocket connection: HTTP 401
>
> Deepgram が接続を拒否しており、`DEEPGRAM_API_KEY` が有効ではありません。Deepgram コンソールの **API keys** でキーを作成し、エクスポートし直してください。

> [accordion] Code: 401 Unauthorized ... Incorrect API key provided
>
> この警告は SambaCloud への LLM リクエストに起因するもので、`authorization` ヘッダーのキーが有効ではありません。[SambaCloud の API キーページ](https://cloud.sambanova.ai/apis) からキーをコピーし、`Bearer ` プレフィックスは残してください。

> [accordion] Code: 404 Not Found ... model\_not\_found
>
> `model` の値が SambaCloud のモデル ID ではありません。現在の一覧は [SambaCloud モデル](https://docs.sambanova.ai/docs/ja/models/sambacloud-models.md) をご参照ください。

> [accordion] Code: 404 Not Found. Body: 404 page not found
>
> `endpoint.url` がベース URL になっています。フルパスの `https://api.sambanova.ai/v1/chat/completions` を使用してください。

> [accordion] We have now waited 5 seconds for a think response
>
> Deepgram は、LLM が 5 秒経っても回答を始めない場合にこの警告を出力し、10 秒の時点で再度出力します。Reasoning モデルの `MiniMax-M3.1-Flash` や `gemma-4-31B-it` のような遅めのモデルでは、最初のトークンの生成に 5 秒以上かかることがあります。返答自体は届きます。長い間を避けるには、[音声向けモデルの選択](#音声向けモデルの選択) の説明に従って、より高速なモデルに切り替えてください。

> [accordion] FAILED\_TO\_THINK: Failed to think. Please check your agent.think settings.
>
> Deepgram が LLM リクエストを 3 回再試行して断念しました。このエラーの直前に出力されている `Warning` メッセージが、上の 2 つのエラーのような本当の原因を示しています。

> [accordion] CLIENT\_MESSAGE\_TIMEOUT: We did not receive audio within our timeout
>
> Deepgram は、しばらく音声を受信しないセッションを閉じます。このエラーは、モデルの回答が遅い場合にも発生することがあります。テストでは、最初のテキストトークンまでに約 4 秒以上かかった実行で発生しました。スクリプトはエラーを出力して停止しますが、`reply.wav` は保存されます。テキストのみのセッションをより長く開いたままにする場合も、このエラーの発生を想定してください。

## 参考情報

* [Deepgram Voice Agent API](https://developers.deepgram.com/docs/voice-agent)
* [Deepgram の LLM モデルとカスタムエンドポイント](https://developers.deepgram.com/docs/voice-agent-llm-models)
* [Deepgram Voice Agent のレイテンシレポート](https://developers.deepgram.com/docs/voice-agent-latency-report)
* [SambaCloud の対応モデル](https://docs.sambanova.ai/docs/ja/models/sambacloud-models.md)
