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

# Haystack

[Haystack](https://haystack.deepset.ai/) は、本番環境に対応した LLM パイプラインを構築するためのオープンソースフレームワークです。本ガイドでは、SambaNova モデルを Haystack に組み込み、すぐに使い始めるための手順を解説します。

## 前提条件

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

* 有効な API キーを取得済みの [SambaCloud](https://cloud.sambanova.ai?utm_source=haystack\&utm_medium=external\&utm_campaign=cloud_signup) アカウント
* Python 3.10 以降。後述の手順でバージョンを固定している `haystack-ai` 2.31 は Python 3.10 以降を必要とするため、3.9 ではインストールできません。
* [SambaCloud のモデル一覧](/docs/ja/models/sambacloud-models)にあるモデル ID。本ガイドでは `Meta-Llama-3.3-70B-Instruct` を使用します。

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

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

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

<Steps>
  <Step title="仮想環境の作成">
    ```bash theme={}
    python3 -m venv .venv
    source .venv/bin/activate
    ```

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

    ```bash theme={}
    python --version
    ```
  </Step>

  <Step title="Haystack のインストール">
    ```bash theme={}
    pip install "haystack-ai>=2.31,<3" trafilatura
    ```

    Haystack 3.0 では、サンプルノートブックがインポートする `OpenAIGenerator` コンポーネントが削除されたため、バージョンを 2.x 系に固定しています。なお、`OpenAIGenerator` は 2.x でもすでに非推奨 (deprecated) となっており、実行のたびに警告が表示されます。新規コードには `OpenAIChatGenerator` を使用することを Haystack は推奨しています。

    ノートブックの Web ページの例では `HTMLToDocument` を使って HTML を変換しますが、このコンポーネントには `trafilatura` が必要です。`trafilatura` は `haystack-ai` の依存関係に含まれておらず、extra 経由でも提供されないため、あわせてインストールします。
  </Step>

  <Step title="API キーの設定">
    コードにハードコードせずに読み取れるよう、API キーを環境変数として export します。

    ```bash theme={}
    export SAMBANOVA_API_KEY="your_sambanova_api_key"
    ```

    この変数名は重要です。後述のスニペットもサンプルノートブックも `SAMBANOVA_API_KEY` を読み取るため、異なる名前にするとキー未設定のエラーになります。
  </Step>
</Steps>

## 最初の呼び出し

ノートブックを開く前に、セットアップをエンドツーエンドで確認します。`OpenAIGenerator` は OpenAI 互換エンドポイント経由で SambaNova と通信するため、ベース URL と API キーが必要です。以下のコードを `first_call.py` として保存します。

```python theme={}
from haystack.components.generators import OpenAIGenerator
from haystack.utils import Secret

generator = OpenAIGenerator(
    api_key=Secret.from_env_var("SAMBANOVA_API_KEY"),
    api_base_url="https://api.sambanova.ai/v1",
    model="Meta-Llama-3.3-70B-Instruct",
)

result = generator.run("Say hello in one sentence.")
print(result["replies"][0])
```

`python first_call.py` で実行します。セットアップが正しければ、以下のような 1 文のモデル出力と非推奨の警告が表示されます。

```text theme={}
FutureWarning: The `OpenAIGenerator` component is deprecated and will be removed in Haystack 3.0. Use `OpenAIChatGenerator` instead, which now also supports string inputs.
Hello! It's a pleasure to meet you.
```

出力される文はモデルが生成するため、実行ごとに変わります。`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`](https://github.com/sambanova/integrations/blob/main/haystack/haystack_sambanova_examples.ipynb) に含まれています。

* **Webpage Q\&A**: Web ページの内容に基づいて質問に回答するパイプラインを構築します。`trafilatura` が必要になるのはこの例です。
* **RAG**: Haystack と SambaCloud で検索拡張生成 (RAG) を実装します。キーワードベースの `InMemoryBM25Retriever` で検索するため、この例には Embedding モデルも 2 つ目のプロバイダーキーも不要です。

<Warning>
  ノートブックの最初のセルは `!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` を追加してください。
</Warning>

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

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

  <Accordion title="ImportError: cannot import name 'OpenAIGenerator'">
    Haystack 3.0 以降がインストールされています。このコンポーネントは 3.0 で削除されましたが、サンプルノートブックはこれをインポートしています。固定したバージョン範囲で再インストールしてください: `pip install "haystack-ai>=2.31,<3"`
  </Accordion>

  <Accordion title="FutureWarning: The OpenAIGenerator component is deprecated">
    2.x 系では想定どおりの動作であり、ノートブックの実行では無視して問題ありません。この警告は実行のたびに表示されます。新規コードには、文字列入力にも対応した `OpenAIChatGenerator` を使用することを Haystack は推奨しています。
  </Accordion>

  <Accordion title="Web ページの例が HTMLToDocument で失敗する">
    `trafilatura` がインストールされていません。Haystack の HTML コンバーターは `trafilatura` に依存していますが、`haystack-ai` のインストールには含まれず、extra 経由でも提供されないため、別途インストールする必要があります: `pip install trafilatura`
  </Accordion>

  <Accordion title="ノートブックが API キーを見つけられない">
    ノートブックは `os.environ["SAMBANOVA_API_KEY"]` を読み取ります。本ガイドの以前のバージョンでは `api_key` を export するよう案内していましたが、ノートブックはこの名前を読み取りません。代わりに `SAMBANOVA_API_KEY` を export してください。
  </Accordion>

  <Accordion title="openai.AuthenticationError または 401 レスポンス">
    API キーが未設定か、値が誤っているか、コードを実行するシェルに export されていません。`echo $SAMBANOVA_API_KEY` で確認してください。`export` は現在のシェルにのみ適用される点にご注意ください。Haystack はコンポーネントの構築時に環境変数を読み取るため、export 後は Python プロセスまたはノートブックのカーネルを再起動してください。
  </Accordion>

  <Accordion title="404 またはモデルが見つからないというレスポンス">
    `model` に指定した値が、呼び出し可能なモデルではありません。モデル ID は大文字と小文字が区別され、[SambaCloud のモデル一覧](/docs/ja/models/sambacloud-models)と正確に一致している必要があります。以前は動作していたモデル ID が使えなくなった場合は、[提供終了ページ](/docs/ja/models/deprecations)をご確認ください。
  </Accordion>

  <Accordion title="NameError: name 'Secret' is not defined">
    ノートブックの RAG セルを、それより前のセルを実行せずに実行しています。このセルは `Secret` を使用していますが、インポートは含んでいません。ノートブックを先頭から実行するか、セルに `from haystack.utils import Secret` を追加してください。
  </Accordion>
</AccordionGroup>

## 参考情報

* [Haystack の公式ドキュメント](https://docs.haystack.deepset.ai/docs)
* 利用可能なモデル ID は [SambaCloud のモデル一覧](/docs/ja/models/sambacloud-models)をご参照ください
* 本番環境でモデルを固定する前に、[モデルの提供終了](/docs/ja/models/deprecations)をご確認ください