Qdrantを接続する

Qdrantは、別のサーバーとして運用するベクトルDBです。文書が多く検索データが数万件を超える場合や、AI検索データをSpaceBuilderサーバーから分離して運用したい場合に使用します。

Qdrantを使用しても、元のファイルと文書のテキストはSpaceBuilderにそのまま残ります。Qdrantには、検索に必要なベクトルと最小限の情報だけが保存されます。

始める前に

• 必要な権限：Workspace管理者と、Qdrantの接続情報を管理する権限
• SpaceBuilderサーバーから、QdrantのRESTおよびgRPCエンドポイントにアクセスできる必要があります。
• 埋め込みモデルの出力次元を確認します。

Qdrantのインストール

SpaceBuilderサーバーから接続できるQdrantサーバーが必要です。すでに運用中のQdrantがある場合は、この節を飛ばして接続設定に進んでください。

Qdrantは、Dockerでインストールするのが最も簡単です。次の手順は、LinuxサーバーにDockerがインストールされていることを前提としています。

準備

実行

コンテナを削除してもデータが残るように、保存フォルダを必ずマウントしてください。次は、/data/qdrantに保存し、サーバーが再起動しても自動的に再開するように設定した例です。

イメージのバージョンは、QDRANT_VERSION変数で固定します。バージョンを指定しないとlatestがインストールされ、コンテナを作り直したときに意図せずバージョンが上がる場合があります。次のバージョンは、ドキュメント作成時点の例です。実際にインストールするときは、Qdrantのリリースページで、組織が検証したバージョンに置き換えてください。

QDRANT_VERSION=v1.19.1
sudo mkdir -p /data/qdrant

docker run -d --name qdrant \
  --restart unless-stopped \
  -p 6333:6333 \
  -p 6334:6334 \
  -v /data/qdrant:/qdrant/storage \
  qdrant/qdrant:${QDRANT_VERSION}

SpaceBuilderとは別のサーバーで運用する場合や、複数の人がアクセスできるネットワークの場合は、APIキーもあわせて有効にしてください。キーには、長く推測しにくい値を設定します。

QDRANT_VERSION=v1.19.1
docker run -d --name qdrant \
  --restart unless-stopped \
  -p 6333:6333 \
  -p 6334:6334 \
  -v /data/qdrant:/qdrant/storage \
  -e QDRANT__SERVICE__API_KEY='<APIキー>' \
  qdrant/qdrant:${QDRANT_VERSION}

インストールの確認

curl http://localhost:6333/collections

"status":"ok"を含む応答が返れば正常です。APIキーを有効にした場合は、curl -H 'api-key: <APIキー>' http://localhost:6333/collectionsのようにapi-keyヘッダーを付けないと応答が返りません。

ブラウザーでhttp://<Qdrantサーバーのアドレス>:6333/dashboardを開くと、コレクションと保存されたデータを確認できるダッシュボードが表示されます。

運用のヒント

• アップデート：Qdrant公式のアップグレード案内に従い、マイナーバージョンを1段階ずつ（例：1.12 → 1.13）上げてください。QDRANT_VERSIONを次のバージョンに変更し、docker pull qdrant/qdrant:${QDRANT_VERSION}でイメージを取得した後、コンテナを削除して同じコマンドでもう一度実行します。データは/data/qdrantに残ります。
• バックアップ：コンテナを停止してから/data/qdrantフォルダをまるごとコピーするか、QdrantのスナップショットAPIを使用します。ただし、ベクトルは元の資料から作り直せる派生データであるため、バックアップがなくても、SpaceBuilderの既存の埋め込みを同期でベクトルDBにデータを入れ直すことができます。
• ファイアウォール：SpaceBuilderサーバーだけが6333と6334ポートに接続できるように制限してください。HTTPSで接続する必要がある場合は、Qdrantの前にリバースプロキシを置く方法を推奨します。

接続設定

ナレッジストレージ画面のベクトルDB構成で、次のように入力して保存します。

Qdrantはサービス型のストレージであるため、データパスの入力欄は表示されません。データはすべてQdrantサーバーに保存されます。

保存すると、インデックススケジューラーがすぐに新しい設定を確認し、必要な場合は元の資料全体の再インデックスを自動的に開始します。別途同期を実行する必要はありません。

コレクションは自動的に作成されます

Qdrantのダッシュボードで、コレクションを事前に作成する必要はありません。SpaceBuilderが最初の検索データを保存するときに、設定した名前でコレクションを作成し、検索フィルターに必要なインデックスもあわせて作成します。

初回のインデックス作成前は、ベクトルDBの運用状況のコレクション設定に未作成・初回インデックス作成時に自動で作成されますと表示されます。エラーではないため、インデックス作成が始まるまでお待ちください。

コレクションを手動で作成するときの注意点

QdrantダッシュボードのCreate New Collection画面で、Simple Hybrid Searchや名前付きベクトル（named vector）を使って作成したコレクションは、SpaceBuilderと互換性がありません。このようなコレクションを指定すると、コレクション設定にコレクション設定の確認が必要と表示され、インデックス作成が保存の段階で失敗します。

コレクションを手動で作成する必要がある場合は、ダッシュボードのConsoleで次のリクエストを実行してください。sizeは、設定したベクトル次元数と同じにする必要があります。

PUT /collections/setfn_knowledge_example
{
  "vectors": { "size": 1024, "distance": "Cosine" }
}

保存されたデータの確認

ベクトルDBの運用状況でQdrantの状態を確認します。

ベクトル1個は、文書の断片（チャンク）1個に対応します。文書は形式に応じてまずセクション、ページ、行の単位に分割し、さらに韓国語基準で約700〜1,000文字のサイズに分割して保存します。そのため、文書数よりベクトル数のほうがはるかに多いのが正常です。

QdrantダッシュボードのConsoleで、実際に保存されている内容を確認できます。

ファイルごとのベクトル数を確認：

POST /collections/setfn_knowledge_example/facet
{ "key": "source_path", "limit": 50 }

保存された文書チャンクの一部を確認：

POST /collections/setfn_knowledge_example/points/scroll
{ "limit": 10, "with_payload": ["source_path", "text"], "with_vector": false }

複数のインスタンスが1つのQdrantを共有するとき

インスタンスごとに異なるコレクション名を使用すると、データは完全に分離されます。デフォルトのコレクション名（knowledge_vectors）をそのまま使用すると、画面に警告とともに、このインスタンスの推奨名が表示されます。

同じコレクションを共有する場合でも、新しく保存するベクトルにはインスタンス分離キーが付き、検索と削除はそれぞれのインスタンスのデータの中だけで行われます。ただし、バックアップ、容量の管理、削除をインスタンスごとに行うには、コレクションを分けるほうが安全です。

同じサーバーで実行中の別のSpaceBuilderプロジェクトが同じコレクションを使用している場合は、設定画面に警告が表示されます。

関連ドキュメント

• ナレッジストレージ
• ナレッジストレージを運用する
• Milvusを接続する
• 収集・インデックス作成