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

# pgvector

> SambaStack の Embedding を pgvector で PostgreSQL に保存して検索し、4096 次元のベクトルをバイナリ量子化でインデックス化します。

[pgvector](https://github.com/pgvector/pgvector) は、ベクトルの保存と検索のための PostgreSQL 拡張機能です。SambaStack の Embedding (埋め込み) モデルで Embedding を生成し、ベクトルを Postgres のテーブルに書き込み、SambaNova のチャットモデルで質問に回答することで、SambaNova と組み合わせて利用できます。

> [!WARNING]
>
> Embedding は SambaStack のみで提供されています。`E5-Mistral-7B-Instruct` は SambaCloud では利用できません。[Embedding (埋め込み) 機能の実装](https://docs.sambanova.ai/docs/ja/features/embeddings.md) をご参照ください。
>
> SambaCloud でも pgvector 自体は利用できます。`SAMBANOVA_BASE_URL` を `https://api.sambanova.ai/v1` に設定し、`pip install 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)]
> ```
>
> [Embedding の生成、保存、クエリ](#embedding-の生成、保存、クエリ) のステップは、そのまま動作します。これらのベクトルは 384 次元であるため、[4096 次元ベクトルのインデックス作成](#4096-次元ベクトルのインデックス作成) は不要です。標準の `hnsw` インデックスが機能します。

## pgvector での SambaNova の使われ方

pgvector 自体が Embedding API やチャット API を呼び出すことはありません。pgvector が行うのはベクトルの保存と比較だけなので、設定すべきモデル設定は存在しません。両方の呼び出しを行うのは、お使いのコードです。SambaStack でテキストを埋め込み、ベクトルを Postgres に書き込み、検索で取得したテキストをチャットモデルに送信します。

同じ手順は、pgvector を備えた任意の Postgres で機能します。pgvector を提供するマネージドサービスも対象です。

`E5-Mistral-7B-Instruct` は 4096 次元のベクトルを返しますが、これは pgvector が標準オプションでインデックス化できる次元数を超えています。本ガイドでは、実際に機能する方法を示します。小さいテーブルには厳密検索 (exact search) を、より大きいテーブルにはバイナリ量子化 (binary quantization) のインデックスを使用します。[4096 次元ベクトルのインデックス作成](#4096-次元ベクトルのインデックス作成) をご参照ください。

## 前提条件

* `E5-Mistral-7B-Instruct` をサービングしている SambaStack インスタンスと、そのインスタンスのベース URL および API キー。[API キーと URL](https://docs.sambanova.ai/docs/ja/get-started/api-keys-urls.md) をご参照ください。
* 同インスタンス上のチャットモデル。本ガイドでは `gpt-oss-120b` を使用します。
* pgvector 0.7.0 以上を備えた PostgreSQL データベースと、その接続 URL。バージョン 0.7.0 で、下記で使用するバイナリ量子化関数が追加されました。pgvector のインストールは、[インストール手順](https://github.com/pgvector/pgvector#installation) に従ってください。
* 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 "psycopg[binary]" openai
```

本ガイドは `psycopg` 3.3.6、`openai` 3.35.1、PostgreSQL 17.11、pgvector 0.8.7 で動作確認済みです。

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

SambaStack のベース URL は、末尾が `/v1` である必要があります。

```bash macOS / Linux theme={}
export SAMBANOVA_BASE_URL="your-sambastack-base-url/v1"
export SAMBANOVA_API_KEY="your-sambanova-api-key"
export DATABASE_URL="postgresql://user:password@localhost:5432/your-database"
```

```powershell Windows theme={}
$env:SAMBANOVA_BASE_URL="your-sambastack-base-url/v1"
$env:SAMBANOVA_API_KEY="your-sambanova-api-key"
$env:DATABASE_URL="postgresql://user:password@localhost:5432/your-database"
```

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

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

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

OpenAI クライアントは、SambaStack の Embedding エンドポイントに対してそのまま機能します。

```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.",
    "PostgreSQL is an open-source relational database, and pgvector adds vector search to it.",
    "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
```

Embedding エンドポイントは `dimensions` 引数を受け付けますが、無視します。そのため、この方法でベクトルを短くすることはできません。すべてのベクトルが 4096 個の値を持ちます。

**2. テーブルの作成とベクトルの挿入**

拡張機能を有効化し、`dimension` に一致するサイズの `vector` 列を作成します。`vector` 列は、最大 16,000 次元まで保持できます。`DROP TABLE IF EXISTS` の行があるため、`already exists` エラーを起こさずに本ガイドを再実行できます。

```python theme={}
import psycopg

conn = psycopg.connect(os.environ["DATABASE_URL"], autocommit=True)
conn.execute("CREATE EXTENSION IF NOT EXISTS vector")
conn.execute("DROP TABLE IF EXISTS items")
conn.execute(f"CREATE TABLE items (id bigserial PRIMARY KEY, content text, embedding vector({dimension}))")

for content, vector in zip(docs, vectors):
    conn.execute(
        "INSERT INTO items (content, embedding) VALUES (%s, %s::vector)",
        (content, vector),
    )
```

Python のリストは、必ず `::vector` で `vector` にキャストしてください。キャストがない場合、Postgres はリストを `double precision[]` と見なし、距離演算子が失敗します。

**3. テーブルのクエリ**

`E5-Mistral-7B-Instruct` はインストラクションチューニング済み (instruction-tuned) のモデルであるため、各クエリは、インストラクションに続けて質問を書く形式にします。ドキュメント側は、プレーンテキストとして埋め込みます。`<=>` 演算子はコサイン距離を返すため、`1 - distance` がコサイン類似度になります。

```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]
rows = conn.execute(
    """
    SELECT content, 1 - (embedding <=> %s::vector) AS score
    FROM items
    ORDER BY embedding <=> %s::vector
    LIMIT 2
    """,
    (query_vector, query_vector),
).fetchall()

for content, score in rows:
    print(f"{score:.3f} {content}")
```

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

インデックスがない場合、Postgres はクエリをすべての行と比較するため、結果は厳密です。

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

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

```python theme={}
context = "\n".join(content for content, _ in rows)

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 チップを製造していると回答します。

## 4096 次元ベクトルのインデックス作成

大きいテーブルでは、近似インデックスを使うことでクエリを高速に保てます。ただし、pgvector の `hnsw` インデックスと `ivfflat` インデックスは 4096 次元を扱えません。上限は `vector` で 2,000 次元、`halfvec` で 4,000 次元のため、次の 2 つはどちらも失敗します。

```sql theme={}
CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops);
-- ERROR: column cannot have more than 2000 dimensions for hnsw index

CREATE INDEX ON items USING hnsw ((embedding::halfvec(4096)) halfvec_cosine_ops);
-- ERROR: column cannot have more than 4000 dimensions for hnsw index
```

バイナリ量子化 (binary quantization) は、最大 64,000 次元までインデックス化できます。インデックスには 1 次元あたり 1 ビットだけを保持し、ハミング距離で候補リストを絞り込んだうえで、その候補リストを厳密なコサイン距離で rerank (再ランク付け) します。インデックスは式に対して作成するため、テーブル側には完全なベクトルがそのまま残ります。

```python theme={}
conn.execute(
    f"""
    CREATE INDEX items_embedding_bq ON items
    USING hnsw ((binary_quantize(embedding)::bit({dimension})) bit_hamming_ops)
    """
)
```

クエリでは、量子化後の距離で候補リストを絞り込み、その後に rerank します。

```python theme={}
rows = conn.execute(
    f"""
    SELECT content, 1 - (embedding <=> %s::vector) AS score
    FROM (
        SELECT * FROM items
        ORDER BY binary_quantize(embedding)::bit({dimension}) <~> binary_quantize(%s::vector)
        LIMIT 20
    ) AS shortlist
    ORDER BY embedding <=> %s::vector
    LIMIT 2
    """,
    (query_vector, query_vector, query_vector),
).fetchall()

for content, score in rows:
    print(f"{score:.3f} {content}")
```

候補リストのサイズ (`LIMIT 20`) は、速度と再現率 (recall) のトレードオフを決めます。候補リストを大きくするほど、rerank の対象となる候補が増えます。この 4 行のテーブルでは、結果は厳密なクエリと一致します。

クエリ内のインデックス式は、`CREATE INDEX` の式と厳密に一致している必要があります。一致していない場合、Postgres はインデックスを使用しません。確認するには、候補リストを絞り込むクエリに対して `EXPLAIN` を実行し、`Index Scan using items_embedding_bq` が表示されるかを見ます。この例のように小さいテーブルでは、Postgres がシーケンシャルスキャンを選ぶことがあります。インデックスが使用可能であることを確認するには、先に `SET enable_seqscan = off` を実行してください。

## クリーンアップ

```python theme={}
conn.execute("DROP TABLE items")
conn.close()
```

## 参考情報

> [card] [GitHub 上の pgvector](https://github.com/pgvector/pgvector)
>
> インストール、演算子、インデックスの種類、上限について説明しています。

> [card] [psycopg ドキュメント](https://www.psycopg.org/psycopg3/docs/)
>
> 本ガイドで PostgreSQL への接続に使用している Python ドライバです。

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

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

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

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

> [accordion] column cannot have more than 2000 dimensions for hnsw index
>
> `ivfflat` インデックスを作成した場合は、同じエラーの末尾が `for ivfflat index` になります。4096 次元の `vector` 列は、`hnsw` インデックスにも `ivfflat` インデックスにも大きすぎます。[4096 次元ベクトルのインデックス作成](#4096-次元ベクトルのインデックス作成) のバイナリ量子化インデックスを使用するか、インデックスなしで検索してください。

> [accordion] column cannot have more than 4000 dimensions for hnsw index
>
> `halfvec` へのキャストでは解決しません。その上限は 4,000 次元であるのに対し、モデルは 4096 次元を返すためです。代わりにバイナリ量子化を使用してください。

> [accordion] operator does not exist: vector \<=> double precision\[]
>
> クエリベクトルが、素の配列として Postgres に渡っています。上記の例のとおり、`%s::vector` でキャストしてください。

> [accordion] function binary\_quantize(vector) does not exist
>
> お使いの pgvector が 0.7.0 より古いバージョンです。pgvector をアップグレードし、データベースで `ALTER EXTENSION vector UPDATE` を実行してください。

> [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 に関する注記をご参照ください。
