Skip to main content
本ガイドでは、システムのセットアップ、最初の呼び出し、独自ドキュメントへのクエリ、そしてユースケースの例を通じて、LlamaIndex との連携手順を解説します。LlamaIndex は、LLM (大規模言語モデル) アプリケーションを構築するためのオープンソースのデータオーケストレーションフレームワークです。

前提条件

作業を始める前に、以下の環境を準備してください。
  • 有効な API キーを持つ SambaCloud アカウント。API キーは API キーページ で作成できます。
  • Python 3.10 以上。llama-index-llms-sambanovasystems は Python 3.9 以前をサポートしていません。
  • 独自ドキュメントへのクエリ を実施する場合は、Embedding (埋め込み) モデル。SambaCloud が提供するのはチャットモデルであり Embedding は提供していないため、同セクションでは小さな Embedding モデルをローカルマシン上で実行します。そのために別プロバイダーの API キーを用意する必要はありません。
macOS に標準搭載されている Python は 3.9 で、python ではなく python3 として提供されます。python3 --version でバージョンを確認してください。3.10 未満の場合は、pyenv、uv、または brew install python@3.12 でサポート対象のバージョンをインストールしてから先へ進んでください。

セットアップ

以下の手順で LlamaIndex をセットアップし、連携します。
  1. 仮想環境を作成して有効化し、バージョンを確認します。
  1. 以下のコマンドを実行して、連携パッケージ llama-index-llms-sambanovasystems と SSEClient パッケージをインストールします。連携パッケージは llama-index-core も導入するため、このページの例が llama_index.core からインポートするものはすべて揃います。
  1. SambaCloud の API キーを環境変数に設定します。連携パッケージが自動的に読み取ります。
  1. 最初の呼び出しを行い、連携が機能することを確認します。
model は必ず明示的に指定してください。SambaNovaCloud のデフォルトは Meta-Llama-3.1-8B-Instruct ですが、このモデルは SambaCloud で 2026年4月14日に提供終了となりました。SambaCloud モデル から現行のモデル ID を選択してください。

応答のストリーミング

ステップ 2 でインストールした sseclient-py が Server-Sent Events のストリームを処理します。stream_complete を使用すると、応答全体の完了を待つ代わりに、トークンを到着した順に出力できます。
文章が一度にまとめて表示されるのではなく、数文字ずつ表示されるはずです。 stream_complete は CompletionResponse オブジェクトのジェネレーターを返します。各オブジェクトは、増分のトークンを delta に、それまでの累積テキストを text に保持します。

独自ドキュメントへのクエリ

ここまでのセクションでは、SambaCloud を単なるチャットモデルとして使用してきました。LlamaIndex が真価を発揮するのは独自のファイルを扱うときです。このセクションでは、ドキュメントを読み込んでインデックス化し、その内容に基づいて質問に回答します。 VectorStoreIndex には 2 つのモデルが必要です。回答を生成するチャットモデルと、テキストをベクトルに変換する Embedding モデルです。SambaCloud はチャットモデルを提供しますが、Embedding は SambaCloud ではなく SambaStack で動作するため、Embedding モデルは提供していません。Settings.embed_model を未設定のままにすると、LlamaIndex は OpenAI の Embedding にフォールバックし、SambaNova とは無関係の OPENAI_API_KEY を求めて実行が失敗します。以下の手順では Embedding モデルをローカルのモデルに明示的に設定するため、別プロバイダーのキーは不要です。
  1. ローカル Embedding の連携パッケージをインストールします。
このパッケージは sentence-transformers と PyTorch を導入するため、LLM パッケージよりダウンロードのサイズがはるかに大きく、時間もかかります。すべてローカルマシン上で動作し、API キーは不要です。
  1. クエリ対象のドキュメントを作成します。
  1. インデックスを構築してクエリを実行します。
以下のような、作成したファイルの内容に基づいた回答が表示されるはずです。
この例を発展させる前に、知っておくと役立つ点が 3 つあります。
  • Settings はグローバルです。同じプロセス内でこれ以降に作成するすべてのインデックスとクエリエンジンが、ここで割り当てたモデルを使用するため、呼び出しごとに引き回すのではなく一度設定するだけで済みます。
  • SambaNovaCloud の context_window のデフォルトは 4096 で、Meta-Llama-3.3-70B-Instruct が受け付ける 128k を大きく下回ります。モデルの実際のウィンドウサイズを設定することで、本来切り詰める必要のない検索結果のテキストを LlamaIndex が切り詰めてしまうことを防げます。使用するモデルのウィンドウサイズは SambaCloud モデル ページでご確認ください。
  • SimpleDirectoryReader は、追加パッケージなしで通常のテキストファイルを読み込めます。PDF、DOCX、PPTX、CSV、Excel の各ファイルを読み込むには、llama-index-readers-file も併せてインストールしてください。

ユースケースの例

以下の 2 つのノートブックでは、LlamaIndex と SambaCloud を実際のユースケースに適用する方法を紹介しています。
  1. Patient Case Summary ノートブックでは、患者情報を処理し、医療基準と照らし合わせ、確認用の要約を生成するワークフローを構築します。
  2. Contract Review ノートブックでは、提供された規制やガイドラインに照らしてドキュメントをチェックするコンプライアンスシステムを構築します。

トラブルシューティング

macOS には python 実行ファイルはなく、python3 のみが提供されます。仮想環境の作成には python3 -m venv .venv を使用してください。source .venv/bin/activate で有効化すれば、環境内では python が期待どおりに動作します。
SAMBANOVA_API_KEY がプロセスから参照できていません。SambaNovaCloud はオブジェクトの構築時にこの変数を読み取るため、リクエストが送信される前の SambaNovaCloud(...) の行で失敗します。echo $SAMBANOVA_API_KEY で確認してください。export は実行したシェルにのみ適用されるため、新しいターミナルやエディタのセッションでは再度設定が必要です。シェルではなく Python 側でキーを設定したい場合は、クライアントを構築する前に環境変数へ代入してください。
キーは sambanova_api_key 引数として渡すのではなく、この方法で設定してください。llama-index-llms-sambanovasystems 0.6.0 では、コンストラクターが同じ引数から sambanova_url を導出するため、この引数を渡すとリクエスト URL までキーの値に置き換わり、無効な URL で呼び出しが失敗します。
仮想環境が有効になっていません。source .venv/bin/activate を実行し、プロンプトに (.venv) が表示されることを確認してから、インストールコマンドを再実行してください。
Server-Sent Events のストリームは sseclient-py が処理しますが、このパッケージは連携パッケージとは別にインストールされます。pip show sseclient-py でインストールされていることを確認してください。
キーは設定されていますが、有効ではありません。キー未設定の場合と異なり、この場合はリクエストが SambaNova に到達したうえで拒否されているため、エラーは構築時の ValueError ではなく、リクエスト由来の RuntimeError として届きます。SambaCloud ポータル からキーをコピーし直してください。
キーは SambaNova に到達しましたが、リクエスト自体が拒否されました。最も多い原因は、SambaCloud で提供されなくなったモデルを model に指定していることです。モデル ID を SambaCloud モデル と モデルの提供終了 で確認してください。エラー内のステータスコードに続くテキストは API の生のレスポンスで、問題のあるフィールド名が示されています。
Settings.embed_model を設定せずにインデックスを構築したため、LlamaIndex がデフォルトの OpenAI Embedding モデルを試み、そのパッケージを見つけられなかった状態です。これは SambaNova のエラーではありません。独自ドキュメントへのクエリ の手順に従って Settings.embed_model を設定してください。このメッセージを消すために OpenAI のパッケージをインストールしないでください。次の実行では代わりに OpenAI のキーを要求されるだけです。
上記と同じく Settings.embed_model の未設定が原因ですが、こちらは OpenAI の Embedding パッケージがすでにインストールされている環境 (多くの場合、メタパッケージ llama-index をインストールしたケース) で発生します。フォールバック処理が OPENAI_API_KEY を探すところまで進んだ状態です。OpenAI のキーは不要です。代わりに Settings.embed_model をローカルの Embedding モデルに設定してください。
LlamaIndex が回答の材料を何も検索できていません。print(len(documents)) で、SimpleDirectoryReader が実際に何かを読み込んだか確認してください。件数が 0 の場合は、指定したディレクトリが空か、パスが誤っています。件数が 0 でないのに回答が意味をなさない場合は、PDF や DOCX などのバイナリ形式を生のバイト列のままインデックス化している可能性が高いです。llama-index-readers-file をインストールすると、これらのファイルが適切なパーサーで処理されます。
古い LlamaIndex チュートリアルに従った場合に発生します。ServiceContext は Settings に置き換えられており、現在は構築時に例外が発生します。独自ドキュメントへのクエリ の例のように、Settings.llm と Settings.embed_model でモデルを設定してください。

参考情報

  • LlamaIndex ドキュメントの SambaNova LLM integration(英語): コンストラクターのオプション、チャットメッセージ、非同期呼び出しについて。
  • LlamaIndex ドキュメントの Embedding models(英語): ローカルモデルが適さない場合の、その他の Embedding の選択肢について。
  • SambaCloud モデル: 現行のモデル ID とコンテキストウィンドウについて。