前提条件
作業を始める前に、以下の環境を準備してください。- 有効な API キーを持つ SambaCloud アカウント。API キーは API キーページ で作成できます。
- Python 3.10 以上。
llama-index-llms-sambanovasystemsは Python 3.9 以前をサポートしていません。 - 独自ドキュメントへのクエリ を実施する場合は、Embedding (埋め込み) モデル。SambaCloud が提供するのはチャットモデルであり Embedding は提供していないため、同セクションでは小さな Embedding モデルをローカルマシン上で実行します。そのために別プロバイダーの API キーを用意する必要はありません。
セットアップ
以下の手順で LlamaIndex をセットアップし、連携します。- 仮想環境を作成して有効化し、バージョンを確認します。
- 以下のコマンドを実行して、連携パッケージ
llama-index-llms-sambanovasystemsとSSEClientパッケージをインストールします。連携パッケージはllama-index-coreも導入するため、このページの例がllama_index.coreからインポートするものはすべて揃います。
- SambaCloud の API キーを環境変数に設定します。連携パッケージが自動的に読み取ります。
- 最初の呼び出しを行い、連携が機能することを確認します。
応答のストリーミング
ステップ 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 モデルをローカルのモデルに明示的に設定するため、別プロバイダーのキーは不要です。
- ローカル Embedding の連携パッケージをインストールします。
このパッケージは
sentence-transformers と PyTorch を導入するため、LLM パッケージよりダウンロードのサイズがはるかに大きく、時間もかかります。すべてローカルマシン上で動作し、API キーは不要です。- クエリ対象のドキュメントを作成します。
- インデックスを構築してクエリを実行します。
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 を実際のユースケースに適用する方法を紹介しています。- Patient Case Summary ノートブックでは、患者情報を処理し、医療基準と照らし合わせ、確認用の要約を生成するワークフローを構築します。
- Contract Review ノートブックでは、提供された規制やガイドラインに照らしてドキュメントをチェックするコンプライアンスシステムを構築します。
トラブルシューティング
command not found: python
command not found: python
macOS には
python 実行ファイルはなく、python3 のみが提供されます。仮想環境の作成には python3 -m venv .venv を使用してください。source .venv/bin/activate で有効化すれば、環境内では python が期待どおりに動作します。ValueError: Did not find sambanova_api_key
ValueError: Did not find sambanova_api_key
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 で呼び出しが失敗します。ModuleNotFoundError: No module named 'llama_index'
ModuleNotFoundError: No module named 'llama_index'
仮想環境が有効になっていません。
source .venv/bin/activate を実行し、プロンプトに (.venv) が表示されることを確認してから、インストールコマンドを再実行してください。ストリーミング呼び出しが失敗する・ハングする
ストリーミング呼び出しが失敗する・ハングする
Server-Sent Events のストリームは
sseclient-py が処理しますが、このパッケージは連携パッケージとは別にインストールされます。pip show sseclient-py でインストールされていることを確認してください。RuntimeError: Sambanova /complete call failed with status code 401
RuntimeError: Sambanova /complete call failed with status code 401
キーは設定されていますが、有効ではありません。キー未設定の場合と異なり、この場合はリクエストが SambaNova に到達したうえで拒否されているため、エラーは構築時の
ValueError ではなく、リクエスト由来の RuntimeError として届きます。SambaCloud ポータル からキーをコピーし直してください。RuntimeError: Sambanova /complete call failed (ステータスコードが 401 以外)
RuntimeError: Sambanova /complete call failed (ステータスコードが 401 以外)
キーは SambaNova に到達しましたが、リクエスト自体が拒否されました。最も多い原因は、SambaCloud で提供されなくなったモデルを
model に指定していることです。モデル ID を SambaCloud モデル と モデルの提供終了 で確認してください。エラー内のステータスコードに続くテキストは API の生のレスポンスで、問題のあるフィールド名が示されています。ImportError: llama-index-embeddings-openai package not found
ImportError: llama-index-embeddings-openai package not found
Settings.embed_model を設定せずにインデックスを構築したため、LlamaIndex がデフォルトの OpenAI Embedding モデルを試み、そのパッケージを見つけられなかった状態です。これは SambaNova のエラーではありません。独自ドキュメントへのクエリ の手順に従って Settings.embed_model を設定してください。このメッセージを消すために OpenAI のパッケージをインストールしないでください。次の実行では代わりに OpenAI のキーを要求されるだけです。ValueError: Could not load OpenAI embedding model
ValueError: Could not load OpenAI embedding model
上記と同じく
Settings.embed_model の未設定が原因ですが、こちらは OpenAI の Embedding パッケージがすでにインストールされている環境 (多くの場合、メタパッケージ llama-index をインストールしたケース) で発生します。フォールバック処理が OPENAI_API_KEY を探すところまで進んだ状態です。OpenAI のキーは不要です。代わりに Settings.embed_model をローカルの Embedding モデルに設定してください。クエリエンジンが Empty Response を出力する
クエリエンジンが Empty Response を出力する
LlamaIndex が回答の材料を何も検索できていません。
print(len(documents)) で、SimpleDirectoryReader が実際に何かを読み込んだか確認してください。件数が 0 の場合は、指定したディレクトリが空か、パスが誤っています。件数が 0 でないのに回答が意味をなさない場合は、PDF や DOCX などのバイナリ形式を生のバイト列のままインデックス化している可能性が高いです。llama-index-readers-file をインストールすると、これらのファイルが適切なパーサーで処理されます。ValueError: ServiceContext is deprecated
ValueError: ServiceContext is deprecated
古い LlamaIndex チュートリアルに従った場合に発生します。
ServiceContext は Settings に置き換えられており、現在は構築時に例外が発生します。独自ドキュメントへのクエリ の例のように、Settings.llm と Settings.embed_model でモデルを設定してください。参考情報
- LlamaIndex ドキュメントの SambaNova LLM integration(英語): コンストラクターのオプション、チャットメッセージ、非同期呼び出しについて。
- LlamaIndex ドキュメントの Embedding models(英語): ローカルモデルが適さない場合の、その他の Embedding の選択肢について。
- SambaCloud モデル: 現行のモデル ID とコンテキストウィンドウについて。

