Skip to main content
Haystack は、本番環境に対応した LLM パイプラインを構築するためのオープンソースフレームワークです。本ガイドでは、SambaNova モデルを Haystack に組み込み、すぐに使い始めるための手順を解説します。

​
前提条件

作業を始める前に、以下の環境を準備してください。
  • 有効な API キーを取得済みの SambaCloud アカウント
  • Python 3.10 以降。後述の手順でバージョンを固定している haystack-ai 2.31 は Python 3.10 以降を必要とするため、3.9 ではインストールできません。
  • SambaCloud のモデル一覧にあるモデル ID。本ガイドでは Meta-Llama-3.3-70B-Instruct を使用します。
macOS には Python 3.9 が同梱されており、python ではなく python3 として提供されます。python3 --version でバージョンを確認してください。3.10 未満の場合は、続行する前に pyenv、uv、または brew install python@3.12 で対応バージョンをインストールしてください。

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

以下の手順に従って、Haystack のセットアップとインストールを行います。
1

仮想環境の作成

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

Haystack のインストール

Haystack 3.0 では、サンプルノートブックがインポートする OpenAIGenerator コンポーネントが削除されたため、バージョンを 2.x 系に固定しています。なお、OpenAIGenerator は 2.x でもすでに非推奨 (deprecated) となっており、実行のたびに警告が表示されます。新規コードには OpenAIChatGenerator を使用することを Haystack は推奨しています。ノートブックの Web ページの例では HTMLToDocument を使って HTML を変換しますが、このコンポーネントには trafilatura が必要です。trafilatura は haystack-ai の依存関係に含まれておらず、extra 経由でも提供されないため、あわせてインストールします。
3

API キーの設定

コードにハードコードせずに読み取れるよう、API キーを環境変数として export します。
この変数名は重要です。後述のスニペットもサンプルノートブックも SAMBANOVA_API_KEY を読み取るため、異なる名前にするとキー未設定のエラーになります。

​
最初の呼び出し

ノートブックを開く前に、セットアップをエンドツーエンドで確認します。OpenAIGenerator は OpenAI 互換エンドポイント経由で SambaNova と通信するため、ベース URL と API キーが必要です。以下のコードを first_call.py として保存します。
python first_call.py で実行します。セットアップが正しければ、以下のような 1 文のモデル出力と非推奨の警告が表示されます。
出力される文はモデルが生成するため、実行ごとに変わります。FutureWarning は haystack-ai 2.31 自体が出力するもので、固定したバージョンでは想定どおりの動作であり、結果には影響しません。警告が表示されない場合は 2.x 系のより古いリリースを使用していることになりますが、それでも問題ありません。

​
ユースケースの例

  • Web ページの内容に基づく質問応答 — URL を取得し、HTMLToDocument で HTML をテキストに変換して OpenAIGenerator に渡すことで、そのページの内容に基づいてユーザーの質問に回答します。
  • 検索拡張生成 (RAG) パイプラインの構築 — InMemoryBM25Retriever でドキュメントをインデックス化し、取得したパッセージに基づいてモデルに質問へ回答させます。Embedding モデルや 2 つ目の API キーは不要です。
  • SambaNova モデルによるモジュール型 LLM コンポーネントのオーケストレーション — Haystack のコンポーネント (コンバーター、リトリーバー、ジェネレーター、ランカー) を 1 つのパイプラインにつなぎ、任意の SambaCloud モデル ID に差し替えて利用できます。

​
サンプルノートブック

以下の 2 つの例は、いずれも 1 つのノートブック haystack_sambanova_examples.ipynb に含まれています。
  • Webpage Q&A: Web ページの内容に基づいて質問に回答するパイプラインを構築します。trafilatura が必要になるのはこの例です。
  • RAG: Haystack と SambaCloud で検索拡張生成 (RAG) を実装します。キーワードベースの InMemoryBM25Retriever で検索するため、この例には Embedding モデルも 2 つ目のプロバイダーキーも不要です。
ノートブックの最初のセルは !pip install haystack-ai==2.8.0 を実行します。このセルはスキップしてください。前のセクションですでに対応バージョンをインストールしているうえ、2.8.0 は環境をダウングレードし、さらに python <3.13 を宣言しているため Python 3.13 以降ではインストール自体が失敗します。また、ノートブックは先頭から順に実行してください。RAG のセルは Secret.from_env_var を呼び出していますが Secret をインポートしていないため、新しいカーネルでそのセルだけを実行すると NameError: name 'Secret' is not defined が発生します。単独で実行する場合は from haystack.utils import Secret を追加してください。

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

macOS には python 実行ファイルはなく、python3 のみが提供されます。仮想環境の作成には python3 -m venv .venv を使用してください。source .venv/bin/activate で有効化すれば、環境内では python が想定どおり動作します。
Haystack 3.0 以降がインストールされています。このコンポーネントは 3.0 で削除されましたが、サンプルノートブックはこれをインポートしています。固定したバージョン範囲で再インストールしてください: pip install "haystack-ai>=2.31,<3"
2.x 系では想定どおりの動作であり、ノートブックの実行では無視して問題ありません。この警告は実行のたびに表示されます。新規コードには、文字列入力にも対応した OpenAIChatGenerator を使用することを Haystack は推奨しています。
trafilatura がインストールされていません。Haystack の HTML コンバーターは trafilatura に依存していますが、haystack-ai のインストールには含まれず、extra 経由でも提供されないため、別途インストールする必要があります: pip install trafilatura
ノートブックは os.environ["SAMBANOVA_API_KEY"] を読み取ります。本ガイドの以前のバージョンでは api_key を export するよう案内していましたが、ノートブックはこの名前を読み取りません。代わりに SAMBANOVA_API_KEY を export してください。
API キーが未設定か、値が誤っているか、コードを実行するシェルに export されていません。echo $SAMBANOVA_API_KEY で確認してください。export は現在のシェルにのみ適用される点にご注意ください。Haystack はコンポーネントの構築時に環境変数を読み取るため、export 後は Python プロセスまたはノートブックのカーネルを再起動してください。
model に指定した値が、呼び出し可能なモデルではありません。モデル ID は大文字と小文字が区別され、SambaCloud のモデル一覧と正確に一致している必要があります。以前は動作していたモデル ID が使えなくなった場合は、提供終了ページをご確認ください。
ノートブックの RAG セルを、それより前のセルを実行せずに実行しています。このセルは Secret を使用していますが、インポートは含んでいません。ノートブックを先頭から実行するか、セルに from haystack.utils import Secret を追加してください。

​
参考情報