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

# LlamaIndex

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

## 前提条件

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

* 有効な API キーを持つ [SambaCloud](https://cloud.sambanova.ai?utm_source=llamaindex\&utm_medium=external\&utm_campaign=cloud_signup) アカウント。API キーは [API キーページ](/docs/ja/get-started/api-keys-urls) で作成できます。
* Python 3.10 以上。`llama-index-llms-sambanovasystems` は Python 3.9 以前をサポートしていません。
* [独自ドキュメントへのクエリ](#独自ドキュメントへのクエリ) を実施する場合は、Embedding (埋め込み) モデル。SambaCloud が提供するのはチャットモデルであり Embedding は提供していないため、同セクションでは小さな Embedding モデルをローカルマシン上で実行します。そのために別プロバイダーの API キーを用意する必要はありません。

<Note>
  macOS に標準搭載されている Python は 3.9 で、`python` ではなく `python3` として提供されます。`python3 --version` でバージョンを確認してください。3.10 未満の場合は、[pyenv](https://github.com/pyenv/pyenv)、[uv](https://docs.astral.sh/uv/)、または `brew install python@3.12` でサポート対象のバージョンをインストールしてから先へ進んでください。
</Note>

## セットアップ

以下の手順で LlamaIndex をセットアップし、連携します。

1. 仮想環境を作成して有効化し、バージョンを確認します。

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

2. 以下のコマンドを実行して、連携パッケージ `llama-index-llms-sambanovasystems` と `SSEClient` パッケージをインストールします。連携パッケージは `llama-index-core` も導入するため、このページの例が `llama_index.core` からインポートするものはすべて揃います。

```bash theme={}
pip install "llama-index-llms-sambanovasystems>=0.6.0" sseclient-py
```

3. SambaCloud の API キーを環境変数に設定します。連携パッケージが自動的に読み取ります。

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

4. 最初の呼び出しを行い、連携が機能することを確認します。

```python theme={}
from llama_index.llms.sambanovasystems import SambaNovaCloud

# Reads your key from the SAMBANOVA_API_KEY environment variable
llm = SambaNovaCloud(model="Meta-Llama-3.3-70B-Instruct")

response = llm.complete("Say hello in one sentence.")
print(response)
# → Hello! It's great to connect with you. How can I help you today?
```

<Warning>
  `model` は必ず明示的に指定してください。`SambaNovaCloud` のデフォルトは `Meta-Llama-3.1-8B-Instruct` ですが、このモデルは SambaCloud で [2026年4月14日に提供終了](/docs/ja/models/deprecations)となりました。[SambaCloud モデル](/docs/ja/models/sambacloud-models) から現行のモデル ID を選択してください。
</Warning>

## 応答のストリーミング

ステップ 2 でインストールした `sseclient-py` が Server-Sent Events のストリームを処理します。`stream_complete` を使用すると、応答全体の完了を待つ代わりに、トークンを到着した順に出力できます。

```python theme={}
from llama_index.llms.sambanovasystems import SambaNovaCloud

llm = SambaNovaCloud(model="Meta-Llama-3.3-70B-Instruct")

for chunk in llm.stream_complete("Explain what an LLM is in one sentence."):
    print(chunk.delta, end="", flush=True)
print()
```

文章が一度にまとめて表示されるのではなく、数文字ずつ表示されるはずです。

`stream_complete` は `CompletionResponse` オブジェクトのジェネレーターを返します。各オブジェクトは、増分のトークンを `delta` に、それまでの累積テキストを `text` に保持します。

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

ここまでのセクションでは、SambaCloud を単なるチャットモデルとして使用してきました。LlamaIndex が真価を発揮するのは独自のファイルを扱うときです。このセクションでは、ドキュメントを読み込んでインデックス化し、その内容に基づいて質問に回答します。

`VectorStoreIndex` には 2 つのモデルが必要です。回答を生成するチャットモデルと、テキストをベクトルに変換する Embedding モデルです。SambaCloud はチャットモデルを提供しますが、[Embedding](/docs/ja/features/embeddings) は SambaCloud ではなく SambaStack で動作するため、Embedding モデルは提供していません。`Settings.embed_model` を未設定のままにすると、LlamaIndex は OpenAI の Embedding にフォールバックし、SambaNova とは無関係の `OPENAI_API_KEY` を求めて実行が失敗します。以下の手順では Embedding モデルをローカルのモデルに明示的に設定するため、別プロバイダーのキーは不要です。

1. ローカル Embedding の連携パッケージをインストールします。

```bash theme={}
pip install "llama-index-embeddings-huggingface>=0.7.0"
```

<Note>
  このパッケージは `sentence-transformers` と PyTorch を導入するため、LLM パッケージよりダウンロードのサイズがはるかに大きく、時間もかかります。すべてローカルマシン上で動作し、API キーは不要です。
</Note>

2. クエリ対象のドキュメントを作成します。

```bash theme={}
mkdir -p data
cat > data/sambanova.txt <<'EOF'
SambaCloud serves open models on SambaNova RDU hardware.
Meta-Llama-3.3-70B-Instruct accepts a context window of 128k tokens.
The LlamaIndex integration package for SambaCloud is llama-index-llms-sambanovasystems.
EOF
```

3. インデックスを構築してクエリを実行します。

```python theme={}
from llama_index.core import Settings, SimpleDirectoryReader, VectorStoreIndex
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.llms.sambanovasystems import SambaNovaCloud

# SambaCloud writes the answer.
Settings.llm = SambaNovaCloud(
    model="Meta-Llama-3.3-70B-Instruct",
    context_window=128000,
)

# A local model creates the vectors. It downloads on the first run.
Settings.embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-en-v1.5")

documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()

response = query_engine.query("What context window does Llama 3.3 70B accept?")
print(response)
```

以下のような、作成したファイルの内容に基づいた回答が表示されるはずです。

```text theme={}
Meta-Llama-3.3-70B-Instruct accepts a context window of 128k tokens.
```

この例を発展させる前に、知っておくと役立つ点が 3 つあります。

* `Settings` はグローバルです。同じプロセス内でこれ以降に作成するすべてのインデックスとクエリエンジンが、ここで割り当てたモデルを使用するため、呼び出しごとに引き回すのではなく一度設定するだけで済みます。
* `SambaNovaCloud` の `context_window` のデフォルトは 4096 で、`Meta-Llama-3.3-70B-Instruct` が受け付ける 128k を大きく下回ります。モデルの実際のウィンドウサイズを設定することで、本来切り詰める必要のない検索結果のテキストを LlamaIndex が切り詰めてしまうことを防げます。使用するモデルのウィンドウサイズは [SambaCloud モデル](/docs/ja/models/sambacloud-models) ページでご確認ください。
* `SimpleDirectoryReader` は、追加パッケージなしで通常のテキストファイルを読み込めます。PDF、DOCX、PPTX、CSV、Excel の各ファイルを読み込むには、`llama-index-readers-file` も併せてインストールしてください。

## ユースケースの例

以下の 2 つのノートブックでは、LlamaIndex と SambaCloud を実際のユースケースに適用する方法を紹介しています。

1. [Patient Case Summary](https://github.com/sambanova/integrations/tree/main/llamaindex/patient_case_summary) ノートブックでは、患者情報を処理し、医療基準と照らし合わせ、確認用の要約を生成するワークフローを構築します。
2. [Contract Review](https://github.com/sambanova/integrations/tree/main/llamaindex/contract_review) ノートブックでは、提供された規制やガイドラインに照らしてドキュメントをチェックするコンプライアンスシステムを構築します。

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

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

  <Accordion title="ValueError: Did not find sambanova_api_key">
    `SAMBANOVA_API_KEY` がプロセスから参照できていません。`SambaNovaCloud` はオブジェクトの構築時にこの変数を読み取るため、リクエストが送信される前の `SambaNovaCloud(...)` の行で失敗します。`echo $SAMBANOVA_API_KEY` で確認してください。`export` は実行したシェルにのみ適用されるため、新しいターミナルやエディタのセッションでは再度設定が必要です。

    シェルではなく Python 側でキーを設定したい場合は、クライアントを構築する前に環境変数へ代入してください。

    ```python theme={}
    import os

    os.environ["SAMBANOVA_API_KEY"] = "your-api-key"
    ```

    キーは `sambanova_api_key` 引数として渡すのではなく、この方法で設定してください。`llama-index-llms-sambanovasystems` 0.6.0 では、コンストラクターが同じ引数から `sambanova_url` を導出するため、この引数を渡すとリクエスト URL までキーの値に置き換わり、無効な URL で呼び出しが失敗します。
  </Accordion>

  <Accordion title="ModuleNotFoundError: No module named 'llama_index'">
    仮想環境が有効になっていません。`source .venv/bin/activate` を実行し、プロンプトに `(.venv)` が表示されることを確認してから、インストールコマンドを再実行してください。
  </Accordion>

  <Accordion title="ストリーミング呼び出しが失敗する・ハングする">
    Server-Sent Events のストリームは `sseclient-py` が処理しますが、このパッケージは連携パッケージとは別にインストールされます。`pip show sseclient-py` でインストールされていることを確認してください。
  </Accordion>

  <Accordion title="RuntimeError: Sambanova /complete call failed with status code 401">
    キーは設定されていますが、有効ではありません。キー未設定の場合と異なり、この場合はリクエストが SambaNova に到達したうえで拒否されているため、エラーは構築時の `ValueError` ではなく、リクエスト由来の `RuntimeError` として届きます。[SambaCloud ポータル](https://cloud.sambanova.ai/apis) からキーをコピーし直してください。
  </Accordion>

  <Accordion title="RuntimeError: Sambanova /complete call failed (ステータスコードが 401 以外)">
    キーは SambaNova に到達しましたが、リクエスト自体が拒否されました。最も多い原因は、SambaCloud で提供されなくなったモデルを `model` に指定していることです。モデル ID を [SambaCloud モデル](/docs/ja/models/sambacloud-models) と [モデルの提供終了](/docs/ja/models/deprecations) で確認してください。エラー内のステータスコードに続くテキストは API の生のレスポンスで、問題のあるフィールド名が示されています。
  </Accordion>

  <Accordion title="ImportError: llama-index-embeddings-openai package not found">
    `Settings.embed_model` を設定せずにインデックスを構築したため、LlamaIndex がデフォルトの OpenAI Embedding モデルを試み、そのパッケージを見つけられなかった状態です。これは SambaNova のエラーではありません。[独自ドキュメントへのクエリ](#独自ドキュメントへのクエリ) の手順に従って `Settings.embed_model` を設定してください。このメッセージを消すために OpenAI のパッケージをインストールしないでください。次の実行では代わりに OpenAI のキーを要求されるだけです。
  </Accordion>

  <Accordion title="ValueError: Could not load OpenAI embedding model">
    上記と同じく `Settings.embed_model` の未設定が原因ですが、こちらは OpenAI の Embedding パッケージがすでにインストールされている環境 (多くの場合、メタパッケージ `llama-index` をインストールしたケース) で発生します。フォールバック処理が `OPENAI_API_KEY` を探すところまで進んだ状態です。OpenAI のキーは不要です。代わりに `Settings.embed_model` をローカルの Embedding モデルに設定してください。
  </Accordion>

  <Accordion title="クエリエンジンが Empty Response を出力する">
    LlamaIndex が回答の材料を何も検索できていません。`print(len(documents))` で、`SimpleDirectoryReader` が実際に何かを読み込んだか確認してください。件数が `0` の場合は、指定したディレクトリが空か、パスが誤っています。件数が 0 でないのに回答が意味をなさない場合は、PDF や DOCX などのバイナリ形式を生のバイト列のままインデックス化している可能性が高いです。`llama-index-readers-file` をインストールすると、これらのファイルが適切なパーサーで処理されます。
  </Accordion>

  <Accordion title="ValueError: ServiceContext is deprecated">
    古い LlamaIndex チュートリアルに従った場合に発生します。`ServiceContext` は `Settings` に置き換えられており、現在は構築時に例外が発生します。[独自ドキュメントへのクエリ](#独自ドキュメントへのクエリ) の例のように、`Settings.llm` と `Settings.embed_model` でモデルを設定してください。
  </Accordion>
</AccordionGroup>

## 参考情報

* LlamaIndex ドキュメントの [SambaNova LLM integration](https://developers.llamaindex.ai/python/framework/integrations/llm/sambanovasystems/)（英語）: コンストラクターのオプション、チャットメッセージ、非同期呼び出しについて。
* LlamaIndex ドキュメントの [Embedding models](https://developers.llamaindex.ai/python/framework/module_guides/models/embeddings/)（英語）: ローカルモデルが適さない場合の、その他の Embedding の選択肢について。
* [SambaCloud モデル](/docs/ja/models/sambacloud-models): 現行のモデル ID とコンテキストウィンドウについて。