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

# Qdrant

> SambaStack で Embedding を生成し、Qdrant に保存・検索して、SambaNova のチャットモデルで質問に回答します。

[Qdrant](https://qdrant.tech/) は、オープンソースのベクトル DB です。SambaStack の Embedding (埋め込み) モデルで Embedding を生成し、ベクトルを Qdrant のコレクションに保存して、SambaNova のチャットモデルで質問に回答することで、SambaNova と組み合わせて利用できます。

> [!WARNING]
>
> Embedding は SambaStack のみで提供されています。`E5-Mistral-7B-Instruct` は SambaCloud では利用できません。[Embedding (埋め込み) 機能の実装](https://docs.sambanova.ai/docs/ja/features/embeddings.md) をご参照ください。
>
> SambaCloud でも Qdrant 自体は利用できます。`SAMBANOVA_BASE_URL` を `https://api.sambanova.ai/v1` に設定し、`pip install "qdrant-client[fastembed]"` で FastEmbed をインストールして、ステップ 1 の `embed` 関数を、ローカルで埋め込みを行う次の関数に置き換えてください。
>
> ```python theme={}
> from fastembed import TextEmbedding
>
> local_model = TextEmbedding()
>
> def embed(texts):
>     return [vector.tolist() for vector in local_model.embed(texts)]
> ```
>
> 本ガイドの残りの部分は、そのまま動作します。

## Qdrant での SambaNova の使われ方

Qdrant には Embedding を代わりに生成する機能がありますが、対象は Qdrant が把握しているモデルに限られます。[Qdrant Cloud Inference](https://qdrant.tech/documentation/inference/cloud-inference/) は Qdrant 自身がホストするモデルを提供し、[外部プロバイダー](https://qdrant.tech/documentation/inference/external-inference-providers/) は OpenAI、Cohere、Jina AI、OpenRouter に限られます。どちらも Qdrant Cloud 経由で利用するもので、カスタムのベース URL を設定する手段はないため、Qdrant が SambaNova のエンドポイントを代わりに呼び出すことはできません。

Qdrant の [推論オプション](https://qdrant.tech/documentation/inference/) には、独自の推論サービスを運用するチーム向けの代替手段として、クライアントサイド推論が示されています。テキストを自分で埋め込み、そのベクトルを保存・クエリする方式です。本ガイドはこの方式を採用しており、両方の呼び出しを行うのはお使いのコードです。SambaStack でテキストを埋め込み、そのベクトルを Qdrant に送信します。

## 前提条件

* `E5-Mistral-7B-Instruct` をサービングしている SambaStack インスタンスと、そのインスタンスのベース URL および API キー。[API キーと URL](https://docs.sambanova.ai/docs/ja/get-started/api-keys-urls.md) をご参照ください。
* 同インスタンス上のチャットモデル。本ガイドでは `gpt-oss-120b` を使用します。
* 稼働中の Qdrant サーバー、または [Qdrant Cloud](https://cloud.qdrant.io/) のクラスター。ローカルで実行する場合は、[Qdrant クイックスタート](https://qdrant.tech/documentation/quickstart/) に従ってください。サーバーなしで本ガイドを試すには、代わりに `QdrantClient(":memory:")` でクライアントを作成してください。
* Python 3.10 以上。

> [!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` で対応バージョンをインストールしてください。

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

**1. 仮想環境の作成**

```bash macOS / Linux theme={}
python3 -m venv .venv
source .venv/bin/activate
```

```powershell Windows theme={}
python -m venv .venv
.venv\Scripts\Activate.ps1
```

**2. 依存パッケージのインストール**

```bash theme={}
pip install qdrant-client openai
```

本ガイドは `qdrant-client` 1.20.0、`openai` 3.40.0、Qdrant サーバー 1.20.0 で動作確認済みです。

**3. SambaStack のベース URL、API キー、Qdrant URL の設定**

SambaStack のベース URL は、末尾が `/v1` である必要があります。以下の Qdrant URL は、ローカルサーバーのデフォルト値です。Qdrant Cloud の場合は、`QDRANT_URL` にクラスターの URL を設定し、あわせて `QDRANT_API_KEY` にクラスターの API キーを設定してください。ローカルサーバーにキーは不要です。

```bash macOS / Linux theme={}
export SAMBANOVA_BASE_URL="your-sambastack-base-url/v1"
export SAMBANOVA_API_KEY="your-sambanova-api-key"
export QDRANT_URL="http://localhost:6333"
```

```powershell Windows theme={}
$env:SAMBANOVA_BASE_URL="your-sambastack-base-url/v1"
$env:SAMBANOVA_API_KEY="your-sambanova-api-key"
$env:QDRANT_URL="http://localhost:6333"
```

## Embedding の生成、保存、クエリ

このセクションのステップは、1 つの Python ファイルまたはセッション内で実行してください。各ステップでは、前のステップで定義した変数を使用します。

**1. ドキュメントの埋め込み**

OpenAI クライアントは、SambaStack の Embedding エンドポイントに対してそのまま機能します。`E5-Mistral-7B-Instruct` は 4096 次元のベクトルを返し、これが次のステップで作成する Qdrant コレクションのサイズになります。

```python theme={}
import os
from openai import OpenAI

sn = OpenAI(
    base_url=os.environ["SAMBANOVA_BASE_URL"],
    api_key=os.environ["SAMBANOVA_API_KEY"],
)

docs = [
    "SambaNova builds the SN40L chip, a reconfigurable dataflow unit for fast AI inference.",
    "Qdrant is an open-source vector database for similarity search.",
    "Sourdough bread needs a live starter, flour, water, and salt, and a long slow fermentation.",
    "The capital of Brazil is Brasilia, which was inaugurated in 1960.",
]

def embed(texts):
    response = sn.embeddings.create(model="E5-Mistral-7B-Instruct", input=texts)
    return [d.embedding for d in response.data]

vectors = embed(docs)
dimension = len(vectors[0])  # 4096
```

**2. コレクションの作成とベクトルのアップサート**

コレクションの `size` には、直前に作成したベクトルの長さを設定します。ベクトルがこのサイズと一致しないアップサート (upsert) を、Qdrant は拒否します。ポイント ID には符号なし整数または UUID しか使えないため、テキストはペイロードに格納します。

```python theme={}
from qdrant_client import QdrantClient, models

client = QdrantClient(
    url=os.environ["QDRANT_URL"],
    api_key=os.environ.get("QDRANT_API_KEY"),  # Qdrant Cloud only
)

if not client.collection_exists("sambanova-demo"):
    client.create_collection(
        collection_name="sambanova-demo",
        vectors_config=models.VectorParams(size=dimension, distance=models.Distance.COSINE),
    )

client.upsert(
    collection_name="sambanova-demo",
    points=[
        models.PointStruct(id=i, vector=vector, payload={"text": text})
        for i, (text, vector) in enumerate(zip(docs, vectors))
    ],
)
```

`upsert` はデフォルトで書き込みの完了を待つため、戻った直後からクエリを実行できます。

**3. コレクションのクエリ**

`E5-Mistral-7B-Instruct` はインストラクションチューニング済み (instruction-tuned) のモデルであるため、各クエリは、インストラクションに続けて質問を書く形式にします。ドキュメント側は、プレーンテキストとして埋め込みます。

```python theme={}
task = "Given a question, retrieve passages that answer the question"
question = "Which chip does SambaNova make?"

query_vector = embed([f"Instruct: {task}\nQuery: {question}"])[0]
hits = client.query_points(
    collection_name="sambanova-demo",
    query=query_vector,
    limit=2,
    with_payload=True,
).points

for hit in hits:
    print(f"{hit.score:.3f} {hit.id} {hit.payload['text']}")
```

最も近い一致は SN40L チップに関するパッセージで、コサインスコアは約 0.71 です。次に近いものは約 0.47 です。値が大きいほど、近い一致です。

**4. SambaNova チャットモデルでの回答生成**

検索で取得したパッセージを、コンテキストとしてチャットモデルに渡します。

```python theme={}
context = "\n".join(hit.payload["text"] for hit in hits)

answer = sn.chat.completions.create(
    model="gpt-oss-120b",
    messages=[
        {"role": "system", "content": f"Answer using only the context below.\n\nContext:\n{context}"},
        {"role": "user", "content": question},
    ],
)
print(answer.choices[0].message.content)
```

`question` は、ステップ 3 の検索で使用したものと同じ質問です。

モデルは、SambaNova が SN40L チップを製造していると回答します。

**5. 使い終わったコレクションの削除**

```python theme={}
client.delete_collection("sambanova-demo")
```

## 参考情報

> [card] [Qdrant ドキュメント](https://qdrant.tech/documentation/)
>
> コレクション、ポイント、検索、デプロイを扱う公式ガイドです。

> [card] [Qdrant の推論オプション](https://qdrant.tech/documentation/inference/)
>
> Qdrant 向けに Embedding を生成する、サーバーサイドとクライアントサイドの方法です。

> [card] [FastEmbed](https://qdrant.tech/documentation/fastembed/)
>
> Qdrant のローカル Embedding ライブラリです。上記の SambaCloud に関する注記で使用しています。

> [card] [Embedding (埋め込み) 機能の実装](https://docs.sambanova.ai/docs/ja/features/embeddings.md)
>
> SambaStack で SambaNova の Embedding モデルを利用する方法です。

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

> [accordion] KeyError: 'QDRANT\_URL'
>
> セットアップのステップで設定する環境変数が、Python を実行するシェルに設定されていません。エラーには、`QDRANT_URL`、`SAMBANOVA_BASE_URL`、`SAMBANOVA_API_KEY` など、不足している変数名が表示されます。[インストールとセットアップ](#インストールとセットアップ) のとおり設定し、同じシェルからコードを再実行してください。

> [accordion] Wrong input: Vector dimension error: expected dim: 4096, got 1536
>
> コレクションが、アップサートしようとしているベクトルとは異なる `size` で作成されています。`E5-Mistral-7B-Instruct` は、入力 1 件につき 4096 個の値を返します。コレクションを削除して `size=4096` で作成し直すか、上記のとおり返されたベクトルから長さを読み取ってください。

> [accordion] 409 Conflict: Collection already exists
>
> コレクションがすでに存在します。上記のコードは、コレクションが存在する場合は `create_collection` をスキップします。このチェックを削除した場合は、`client.delete_collection("sambanova-demo")` でコレクションを削除してください。

> [accordion] 400 Bad Request: value doc1 is not a valid point ID
>
> ポイント ID には、符号なし整数または UUID しか使えません。ID には数値または `str(uuid.uuid4())` を使用し、独自のラベルはペイロードに保持してください。

> [accordion] QdrantClient の接続が Connection refused で失敗する
>
> `QDRANT_URL` で待ち受けている Qdrant サーバーがありません。[Qdrant クイックスタート](https://qdrant.tech/documentation/quickstart/) に従ってサーバーを起動し、URL とポートが一致していることを確認してください。サーバーなしで本ガイドを試すには、`QdrantClient(":memory:")` を使用してください。

> [accordion] Embedding エンドポイントが 401 invalid\_api\_key を返す
>
> SambaNova のキーがベース URL に対して正しくありません。お使いの SambaStack インスタンス用に発行されたキーを使用し、`SAMBANOVA_BASE_URL` がそのインスタンスを指していて、末尾が `/v1` であることを確認してください。`/v1` がない場合、Embedding リクエストは `404 page not found` を返します。

> [accordion] E5-Mistral-7B-Instruct に対する 404 model\_not\_found
>
> 呼び出しているインスタンスが同モデルをサービングしていないか、キーにアクセス権がありません。インスタンスがサービングしているモデルの一覧を確認してください。
>
> ```bash macOS / Linux theme={}
> curl -H "Authorization: Bearer $SAMBANOVA_API_KEY" "$SAMBANOVA_BASE_URL/models"
> ```
>
> ```powershell Windows theme={}
> curl.exe -H "Authorization: Bearer $env:SAMBANOVA_API_KEY" "$env:SAMBANOVA_BASE_URL/models"
> ```
>
> SambaCloud は Embedding を提供していません。本ページ冒頭の SambaCloud に関する注記をご参照ください。

> [accordion] Qdrant のサーバーサイド推論に SambaNova のモデルが見つからない
>
> これは想定どおりの動作です。Qdrant が Embedding を生成できるのは、Cloud Inference のモデルと、OpenAI、Cohere、Jina AI、OpenRouter の各プロバイダーに限られます。上記のとおり、`size` を指定してコレクションを作成し、自分で生成したベクトルをアップサートしてください。
