メインコンテンツへスキップ
pgvector は、ベクトルの保存と検索のための PostgreSQL 拡張機能です。SambaStack の Embedding (埋め込み) モデルで Embedding を生成し、ベクトルを Postgres のテーブルに書き込み、SambaNova のチャットモデルで質問に回答することで、SambaNova と組み合わせて利用できます。
Embedding は SambaStack のみで提供されています。E5-Mistral-7B-Instruct は SambaCloud では利用できません。Embedding (埋め込み) 機能の実装 をご参照ください。SambaCloud でも pgvector 自体は利用できます。SAMBANOVA_BASE_URL を https://api.sambanova.ai/v1 に設定し、pip install fastembed で FastEmbed をインストールして、ステップ 1 の embed 関数を、ローカルで埋め込みを行う次の関数に置き換えてください。
Embedding の生成、保存、クエリ のステップは、そのまま動作します。これらのベクトルは 384 次元であるため、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 次元ベクトルのインデックス作成 をご参照ください。

前提条件

  • E5-Mistral-7B-Instruct をサービングしている SambaStack インスタンスと、そのインスタンスのベース URL および API キー。API キーと URL をご参照ください。
  • 同インスタンス上のチャットモデル。本ガイドでは gpt-oss-120b を使用します。
  • pgvector 0.7.0 以上を備えた PostgreSQL データベースと、その接続 URL。バージョン 0.7.0 で、下記で使用するバイナリ量子化関数が追加されました。pgvector のインストールは、インストール手順 に従ってください。
  • Python 3.10 以上。
macOS には Python 3.9 が同梱されており、python ではなく python3 として提供されます。python3 --version でバージョンを確認してください。3.10 未満の場合は、続行する前に pyenv、uv、または brew install python@3.12 で対応バージョンをインストールしてください。

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

1

仮想環境の作成

2

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

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

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

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

Embedding の生成、保存、クエリ

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

ドキュメントの埋め込み

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

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

拡張機能を有効化し、dimension に一致するサイズの vector 列を作成します。vector 列は、最大 16,000 次元まで保持できます。DROP TABLE IF EXISTS の行があるため、already exists エラーを起こさずに本ガイドを再実行できます。
Python のリストは、必ず ::vector で vector にキャストしてください。キャストがない場合、Postgres はリストを double precision[] と見なし、距離演算子が失敗します。
3

テーブルのクエリ

E5-Mistral-7B-Instruct はインストラクションチューニング済み (instruction-tuned) のモデルであるため、各クエリは、インストラクションに続けて質問を書く形式にします。ドキュメント側は、プレーンテキストとして埋め込みます。<=> 演算子はコサイン距離を返すため、1 - distance がコサイン類似度になります。
最も近い一致は SN40L チップに関するパッセージで、コサインスコアは約 0.71 です。次に近いものは約 0.52 です。値が大きいほど、近い一致です。インデックスがない場合、Postgres はクエリをすべての行と比較するため、結果は厳密です。
4

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

検索で取得したパッセージを、コンテキストとしてチャットモデルに渡します。
question は、ステップ 3 の検索で使用したものと同じ質問です。モデルは、SambaNova が SN40L チップを製造していると回答します。

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

大きいテーブルでは、近似インデックスを使うことでクエリを高速に保てます。ただし、pgvector の hnsw インデックスと ivfflat インデックスは 4096 次元を扱えません。上限は vector で 2,000 次元、halfvec で 4,000 次元のため、次の 2 つはどちらも失敗します。
バイナリ量子化 (binary quantization) は、最大 64,000 次元までインデックス化できます。インデックスには 1 次元あたり 1 ビットだけを保持し、ハミング距離で候補リストを絞り込んだうえで、その候補リストを厳密なコサイン距離で rerank (再ランク付け) します。インデックスは式に対して作成するため、テーブル側には完全なベクトルがそのまま残ります。
クエリでは、量子化後の距離で候補リストを絞り込み、その後に rerank します。
候補リストのサイズ (LIMIT 20) は、速度と再現率 (recall) のトレードオフを決めます。候補リストを大きくするほど、rerank の対象となる候補が増えます。この 4 行のテーブルでは、結果は厳密なクエリと一致します。 クエリ内のインデックス式は、CREATE INDEX の式と厳密に一致している必要があります。一致していない場合、Postgres はインデックスを使用しません。確認するには、候補リストを絞り込むクエリに対して EXPLAIN を実行し、Index Scan using items_embedding_bq が表示されるかを見ます。この例のように小さいテーブルでは、Postgres がシーケンシャルスキャンを選ぶことがあります。インデックスが使用可能であることを確認するには、先に SET enable_seqscan = off を実行してください。

クリーンアップ

参考情報

GitHub 上の pgvector

インストール、演算子、インデックスの種類、上限について説明しています。

psycopg ドキュメント

本ガイドで PostgreSQL への接続に使用している Python ドライバです。

FastEmbed

ローカルの Embedding ライブラリです。上記の SambaCloud に関する注記で使用しています。

Embedding (埋め込み) 機能の実装

SambaStack で SambaNova の Embedding モデルを利用する方法です。

トラブルシューティング

セットアップのステップで設定する環境変数が、Python を実行するシェルに設定されていません。エラーには、DATABASE_URL、SAMBANOVA_BASE_URL、SAMBANOVA_API_KEY など、不足している変数名が表示されます。インストールとセットアップ のとおり設定し、同じシェルからコードを再実行してください。
ivfflat インデックスを作成した場合は、同じエラーの末尾が for ivfflat index になります。4096 次元の vector 列は、hnsw インデックスにも ivfflat インデックスにも大きすぎます。4096 次元ベクトルのインデックス作成 のバイナリ量子化インデックスを使用するか、インデックスなしで検索してください。
halfvec へのキャストでは解決しません。その上限は 4,000 次元であるのに対し、モデルは 4096 次元を返すためです。代わりにバイナリ量子化を使用してください。
クエリベクトルが、素の配列として Postgres に渡っています。上記の例のとおり、%s::vector でキャストしてください。
お使いの pgvector が 0.7.0 より古いバージョンです。pgvector をアップグレードし、データベースで ALTER EXTENSION vector UPDATE を実行してください。
SambaNova のキーがベース URL に対して正しくありません。お使いの SambaStack インスタンス用に発行されたキーを使用し、SAMBANOVA_BASE_URL がそのインスタンスを指していて、末尾が /v1 であることを確認してください。/v1 がない場合、Embedding リクエストは 404 page not found を返します。
呼び出しているインスタンスが同モデルをサービングしていないか、キーにアクセス権がありません。インスタンスがサービングしているモデルの一覧を確認してください。
SambaCloud は Embedding を提供していません。本ページ冒頭の SambaCloud に関する注記をご参照ください。