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

# Vapi

[Vapi](https://dashboard.vapi.ai/login) は、音声 AI エージェントを構築するための開発者向けプラットフォームです。基盤となるインフラを Vapi が処理するため、開発者は音声体験の構築に集中できます。

Vapi で構築した音声エージェントは、以下のことができます。

* ユーザーとの自然な会話
* 電話の発着信
* 既存のシステムや API との連携
* 予約スケジューリングやカスタマーサポートなど、高度なユースケースを含む複雑なワークフローへの対応

SambaNova の高速推論は低レイテンシの音声対話を実現します。これは、自然に聞こえる会話にとって不可欠な要素です。

本ガイドでは、お使いのマシン上で動作する小さな Flask プロキシを介して、Vapi を SambaNova に接続します。Vapi は **Custom LLM** プロバイダーとしてこのプロキシを呼び出し、プロキシは各リクエストを SambaCloud に転送します。最後まで進めると、ブラウザから会話できるアシスタントが完成します。

## 前提条件

作業を始める前に、以下の環境を準備してください。

* [SambaCloud](https://cloud.sambanova.ai/apis) アカウントと API キー (API キーは SambaCloud ポータルの **API Keys** タブから生成できます)。
* ダッシュボードにアクセスできる [Vapi](https://dashboard.vapi.ai/login) アカウント。電話番号は不要です。Vapi はダッシュボードから Web 通話を発信できるため、動作するマイクと、マイクにアクセスできるブラウザがあれば十分です。
* Python 3.9 以降。
* [ngrok](https://ngrok.com/) のインストール済み環境と、無料の ngrok アカウント。[ステップ 4](#ステップ-4-ngrok-のインストール) で認証トークンを追加するまで ngrok はトンネルを開かないため、アカウントが必要です。
* ターミナル 2 つ。Flask サーバーと ngrok トンネルはどちらもフォアグラウンドで実行され、本ガイドの残りの手順の間、両方を起動したままにしておく必要があります。

<Note>
  macOS には Python 3.9 が同梱されており、`python` ではなく `python3` として提供されています。バージョンは `python3 --version` で確認してください。本ガイドで使用する 2 つの依存ライブラリはいずれも `requires-python >= 3.9` を宣言しているため、macOS 標準のインタープリターで十分です。
</Note>

## モデルの選択

プロキシは受け取ったモデル名をそのまま SambaCloud に転送するため、Vapi に入力する値は正確な SambaCloud のモデル ID でなければなりません。本ガイドの例では `gpt-oss-120b` を使用します。

| モデル ID | コンテキスト長 | 開発者ティア RPM | 開発者ティア RPD |
| :- | :- | :- | :- |
| `gpt-oss-120b` | 128k トークン | 60 | 12,000 |
| `Meta-Llama-3.3-70B-Instruct` | 128k トークン | 240 | 48,000 |

音声用途のモデル選定では、以下の点を考慮してください。

* **会話の 1 ターンが 1 リクエストになります。** 発信者が話し終えるたびに、Vapi はトランスクリプト全体をプロキシに送信するため、1 回の通話ではターンごとに 1 リクエストを消費します。無料ティア (Free Tier) のアカウントはモデルごとに 1 日 20 リクエストに制限されており、おおよそ 20 ターンでエージェントが通話の途中で失敗し始めます。支払い方法を登録すると、開発者ティア (Developer Tier) に移行できます。
* **`Meta-Llama-3.3-70B-Instruct` はリクエスト数の余裕が最も大きいモデルです。** 開発者ティアで 240 RPM・48,000 RPD と、他のすべての本番モデルの 4 倍のリクエスト許容量があり、同時通話が見込まれる場合に重要です。
* **ストリーミングは有効のままにしてください。** プロキシはリクエストで `"stream": true` が設定されている場合にのみストリーミングし、Vapi の音声合成は最初のトークンを受信した時点で始まります。ストリーミングなしでは、応答全体の生成が完了するまで発信者には何も聞こえません。
* **応答は短く保ちます。** 音声では、応答が長いほど発信者が聞き続ける時間も長くなります。Vapi が独自の `max_tokens` を送信しない場合、`app.py` は応答を 250 トークンに制限します。

モデルの一覧とコンテキスト長については、[SambaCloud モデル](/docs/ja/models/sambacloud-models) をご参照ください。レート制限の一覧表については、[レート制限](/docs/ja/models/rate-limits) をご参照ください。

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

以下の手順に従って、リポジトリのクローンと環境の設定を行い、ローカルのプロキシサーバーを介して SambaNova を Vapi に接続します。

### ステップ 1: リポジトリのクローン

SambaNova の integrations リポジトリをクローンし、Vapi ディレクトリに移動します。

```bash theme={}
git clone https://github.com/sambanova/integrations.git
cd integrations/vapi
```

### ステップ 2: 仮想環境の作成

プロジェクトの依存関係を分離するため、Python の仮想環境を作成して有効化します。

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

インストールの前に、環境がサポート対象のバージョンを使用していることを確認します。

```bash theme={}
python --version
```

### ステップ 3: 依存関係のインストール

必要な Python ライブラリをインストールします。

```bash theme={}
pip install "flask>=3.1,<4" "sambanova>=1.12,<2"
```

### ステップ 4: ngrok のインストール

Vapi から到達できるようにローカルサーバーをインターネットに公開するため、ngrok が必要です。

**macOS の場合**、Homebrew を使用して ngrok をインストールします。

```bash theme={}
brew install ngrok
```

Linux および Windows の場合は、お使いのプラットフォーム向けの [ngrok インストールガイド](https://ngrok.com/docs/start)に従ってください。

インストール後、認証トークンで ngrok を認証します。トークンは ngrok のダッシュボードで確認できます。詳細は [ngrok のドキュメント](https://dashboard.ngrok.com/get-started/your-authtoken)をご覧ください。

```bash theme={}
ngrok config add-authtoken $YOUR_NGROK_AUTHTOKEN
```

### ステップ 5: API キーの設定

SambaNova の API キーを環境変数としてエクスポートします。`your-sambanova-api-key` は、[SambaCloud ポータル](https://cloud.sambanova.ai/apis)で取得したキーに置き換えてください。

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

<Warning>
  integrations リポジトリの `app.py` は現在、プレースホルダのキーをハードコードしており、この環境変数を読み取りません。アップストリームで修正されるまでは、`app.py` を自分で編集する必要があります。編集しない場合、すべてのリクエストが `AuthenticationError: Error code: 401 - Incorrect API key provided: YOUR_S*****_KEY` で失敗します。
</Warning>

`app.py` を開き、ハードコードされたキーを削除します。SambaNova クライアントは環境変数 `SAMBANOVA_API_KEY` を自動的に読み取るため、他の変更は不要です。

```python theme={}
# Replace this line:
client = SambaNova(api_key="YOUR_SAMBANOVA_API_KEY")

# With this one:
client = SambaNova()
```

変数が未設定の場合、クライアントは `SambaNovaError: The api_key client option must be set either by passing api_key to the client or by setting the SAMBANOVA_API_KEY environment variable` を送出します。

### ステップ 6: ローカル LLM サーバーの起動

1 つ目のターミナルで Flask サーバーを起動し、そのまま実行し続けます。

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

サーバーはポート 5000 でリッスンし、`POST /chat/completions` という単一のルートを公開します。ブラウザで `http://localhost:5000/` を開くと 404 が返りますが、これは想定どおりの動作です。本ガイドの残りの手順では、このターミナルを常に確認してください。Vapi からのすべてのリクエストが `POST /chat/completions` のログ行としてここに表示されるため、トラフィックが届いていることを確認する最も速い方法です。

### ステップ 7: ngrok によるサーバーの公開

別のターミナルで、次を実行します。

```bash theme={}
ngrok http 5000
```

ngrok は、次のような公開 URL を生成します。

```text theme={}
https://abcd-1234.ngrok-free.dev
```

これが Vapi の呼び出し先となるエンドポイントです。

<Warning>
  `app.py` は `app.run(debug=True)` を呼び出しており、対話型の Werkzeug デバッガーを提供します。また、このエンドポイントには認証がありません。トンネルが開いている間は、ngrok URL を知っている人なら誰でも SambaNova のクォータを消費するリクエストを送信でき、未処理のエラーが発生すると、ソースコード・ローカル変数・評価コンソールを露出するデバッガーページが返されます。このトンネルを起動したまま放置しない、URL を共有しない、このサーバーをそのままデプロイしない、という点を徹底してください。

  テスト中のデバッガーの露出を防ぐには、`app.py` の最終行を `app.run(port=5000)` に変更します。
</Warning>

### ステップ 8: エンドポイントのテスト

cURL リクエストでセットアップを確認します。

```bash theme={}
curl -X POST https://abcd-1234.ngrok-free.dev/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "call": "chat.completions",
    "metadata": {
      "request_id": "example-123"
    },
    "model": "gpt-oss-120b",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello! Explain what an LLM is in one sentence."
      }
    ],
    "temperature": 0.7,
    "max_tokens": 150,
    "stream": true
  }'
```

<Note>
  `https://abcd-1234.ngrok-free.dev` は、実際の ngrok URL に置き換えてください。
</Note>

このリクエストは `"stream": true` を設定しているため、サーバーは単一の JSON ボディではなく server-sent events で応答します。`app.py` は各チャンクをシリアライズし、1 つの `data:` 行として出力します。

```text theme={}
data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":"A"},...}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":" large"},...}]}
```

`data:` 行のストリームが返れば、プロキシは SambaNova に到達しており、Vapi もこれを利用できます。代わりに HTML ページが返る場合は、サーバーでエラーが発生しています。[トラブルシューティング](#トラブルシューティング) をご参照ください。

### ステップ 9: カスタム LLM を使った Vapi の設定

1. [Vapi ダッシュボード](https://dashboard.vapi.ai/)にログインします。
2. **Create Assistant** を選択し、空のテンプレートから開始します。
3. アシスタントの **Model** セクションで、プロバイダーを **Custom LLM** に設定します。
4. モデル名を入力します。この値はそのまま SambaCloud に転送されるため、[SambaCloud モデル](/docs/ja/models/sambacloud-models)に掲載された正確なモデル ID である必要があります (例: `gpt-oss-120b`)。大文字・小文字を含めて完全に一致しない名前は、最初のターンで失敗します。
5. エンドポイント URL フィールドに、パスを付けずに ngrok の URL を貼り付けます。
   ```text theme={}
   https://abcd-1234.ngrok-free.dev
   ```
   Vapi はこの値を OpenAI クライアントのベース URL として使用し、自身で `/chat/completions` を付加します。これはプロキシサーバーが公開するルートと一致します。ここにパスを含めると `/chat/completions/chat/completions` となり、リクエストは 404 を返します。
6. 設定を保存します。

<Warning>
  ngrok は再起動のたびに新しい公開 URL を発行するため、この設定は気付かないうちに無効になります。Vapi からサーバーに届かなくなった場合は、現在の ngrok URL を確認し、エンドポイントを更新してください。
</Warning>

### ステップ 10: アシスタントとの会話

Flask サーバーと ngrok トンネルの両方を起動したまま、Vapi ダッシュボードで **Talk** を選択します。Vapi はブラウザで Web 通話を開始するため、電話番号は不要です。プロンプトが表示されたらマイクへのアクセスを許可し、アシスタントに話しかけてください。

以下の 3 点がすべて確認できれば、連携は正常に動作しています。

* 発話するたびに、Flask のターミナルに `200` ステータスの `POST /chat/completions` 行が記録される。
* アシスタントが音声で応答し、その応答が一括で届くのではなく、生成の途中から再生され始める。
* Vapi ダッシュボードに通話が表示され、LLM パイプラインのエラーがない。

<Tip>
  トンネルが開いている間、ngrok は `http://127.0.0.1:4040` でローカルのリクエストインスペクターを実行しています。ブラウザで開くと、Vapi が送信した正確な JSON ボディとサーバーが返したレスポンスを確認できます。Vapi の設定の問題と SambaNova 側の問題を切り分ける最も手軽な方法です。
</Tip>

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

<AccordionGroup>
  <Accordion title="command not found: python">
    macOS には `python` 実行ファイルはなく、`python3` のみが提供されています。環境の作成には `python3 -m venv .venv` を使用してください。`source .venv/bin/activate` で有効化した後は、環境内で `python` が期待どおりに動作します。
  </Accordion>

  <Accordion title="AuthenticationError: Error code: 401 - Incorrect API key provided: YOUR_S*****_KEY">
    `app.py` がまだプレースホルダのキーを使用しています。このファイルは環境変数を読み取らないため、`SAMBANOVA_API_KEY` をエクスポートするだけでは効果がありません。[ステップ 5](#ステップ-5-api-キーの設定) の編集を適用し、サーバーを再起動してください。
  </Accordion>

  <Accordion title="OSError: [Errno 48] Address already in use">
    別のプロセスがポート 5000 を使用しています。macOS では、デフォルトで有効になっている AirPlay Receiver がポート 5000 を占有していることがよくあります。**System Settings** → **General** → **AirDrop & Handoff** で無効化できます。それ以外の場合は、`app.py` の最終行を `app.run(port=5001)` に変更して空いているポートに移し、[ステップ 7](#ステップ-7-ngrok-によるサーバーの公開) では代わりに `ngrok http 5001` を実行してください。
  </Accordion>

  <Accordion title="Vapi からのエンドポイント呼び出しが 404 になる">
    Vapi ダッシュボードのエンドポイント URL にパスが含まれています。Vapi は入力された値に `/chat/completions` を付加するため、フルパスを入力すると `/chat/completions/chat/completions` となり、プロキシサーバーはこのルートを提供しません。パスを付けず、ngrok のベース URL のみを入力してください。
  </Accordion>

  <Accordion title="動作していた Vapi がサーバーに到達しなくなる">
    ngrok は再起動のたびに新しい公開 URL を発行し、古い URL は解決できなくなります。Vapi ダッシュボードは警告なしに古い値を保持し続けます。現在の ngrok URL を確認し、アシスタント設定のエンドポイントを更新してください。
  </Accordion>

  <Accordion title="エラーではなく対話型デバッガーのページが返される">
    `app.py` は `debug=True` で実行されており、未処理の例外が発生すると Werkzeug デバッガーを提供します。公開トンネル経由では、ソースコード・ローカル変数・評価コンソールが露出します。`app.py` の最終行を `app.run(port=5000)` に変更すると、通常のエラーページが返されるようになります。
  </Accordion>

  <Accordion title="最初のターンでモデル名が拒否される">
    Vapi の **Model** セクションの名前はそのまま SambaCloud に渡されるため、正確なモデル ID でない値はすべて拒否されます。大文字・小文字を含めて [SambaCloud モデル](/docs/ja/models/sambacloud-models)の値と照合し、[モデルの提供終了](/docs/ja/models/deprecations)ページに掲載されていないことを確認してください。[ステップ 8](#ステップ-8-エンドポイントのテスト) の cURL リクエストにも同じ ID を使用し、両方の経路で同じモデルを検証してください。
  </Accordion>

  <Accordion title="通話はつながるがアシスタントが応答しない、または会話の途中で無音になる">
    お使いのマシンから外側に向かって切り分けます。Flask のターミナルに `POST /chat/completions` の行が表示されない場合、Vapi はサーバーに到達していません。トンネルが閉じているか、エンドポイント URL が古くなっているため、[ステップ 7](#ステップ-7-ngrok-によるサーバーの公開) とダッシュボードに保存された URL を再確認してください。行はあるものの 500 が返っている場合、リクエストはサーバーに到達した後、下流で失敗しています。原因の多くは [ステップ 5](#ステップ-5-api-キーの設定) の API キーか無効なモデル名で、`http://127.0.0.1:4040` の ngrok インスペクターに表示されるレスポンスボディで原因を特定できます。リクエストが成功しているのに発信者に何も聞こえない場合は、Vapi ダッシュボードで通話を開き、その終了理由 (ended reason) を確認してください。終了理由は [Vapi の call ended reasons](https://docs.vapi.ai/calls/call-ended-reason)（英語）に記載されています。
  </Accordion>

  <Accordion title="しばらく動作した後にリクエストが失敗し始める">
    SambaCloud のレート制限に達しています。会話の 1 ターンは 1 リクエストであり、無料ティアのアカウントはモデルごとに 1 日 20 リクエストに制限されています。レスポンスのレート制限ヘッダーと、[レート制限](/docs/ja/models/rate-limits)ページのティア別の表を確認し、支払い方法を登録して開発者ティアに移行してください。
  </Accordion>
</AccordionGroup>

## 参考情報

* 詳細な手順と完全なソースコードについては、GitHub の [Vapi 連携サンプル](https://github.com/sambanova/integrations/tree/main/vapi)をご覧ください。
* Vapi の詳細については、[Vapi の公式ドキュメント](https://docs.vapi.ai/quickstart/introduction)をご覧ください。
* Vapi ダッシュボードで指定できるモデルについては、[SambaCloud モデル](/docs/ja/models/sambacloud-models) をご参照ください。
* モデルごとのリクエスト数とトークン数の制限については、[レート制限](/docs/ja/models/rate-limits) をご参照ください。
* プロキシを介さずに SambaNova を直接呼び出す方法については、[API リファレンス](/docs/ja/api-reference/overview) をご参照ください。