PostgreSQL + pgvector完全環境構築ガイド

AI開発でベクトル検索を実装するため、PostgreSQL + pgvector拡張機能の環境構築手順を詳細に解説します。この記事では実際に発生した問題とその解決方法も含めて、確実に動作する手順を紹介します。

必要な環境

Windows 10/11
管理者権限でのコマンド実行が可能
インターネット接続

Step 1: PostgreSQL基本インストール

1.1 公式インストーラーのダウンロード

PostgreSQL公式サイトから最新安定版をダウンロードします。PostgreSQL 16を推奨します。

1.2 インストール実行

インストーラーを実行し、以下の設定で進めます：

重要な選択項目：

PostgreSQL Server: 必須選択
pgAdmin 4: 管理ツール（推奨）
Stack Builder: 拡張機能管理（必須）
Command Line Tools: コマンドライン操作（必須）

設定値：

Installation Directory: C:\Program Files\PostgreSQL\16
Data Directory: C:\Program Files\PostgreSQL\16\data
Port: 5432 （デフォルト）
Superuser Password: 強固なパスワードを設定し、必ずメモする
Locale: Japanese_Japan.932 または C

1.3 環境変数設定

システム環境変数PATHに以下を追加：

C:\Program Files\PostgreSQL\16\bin

1.4 動作確認

コマンドプロンプトで以下を実行：

psql --version
psql -U postgres -h localhost

パスワード入力後、postgres=# プロンプトが表示されれば成功です。

Step 2: pgvector拡張機能インストール

2.1 前提条件の確認

pgvectorのビルドには以下が必要です：

Visual Studio Build Tools
- Visual Studio Community または
- Visual Studio Build Tools for C++
Git for Windows git --version

2.2 pgvectorソースコード取得

x64 Native Tools Command Promptを管理者権限で開く(Winsows検索メニューから検索)

任意の作業ディレクトリ（例：C:\temp）で実行：

set "PGROOT=C:\Program Files\PostgreSQL\16"
cd %TEMP%
git clone --branch v0.7.1 https://github.com/pgvector/pgvector.git
cd pgvector
nmake /F Makefile.win
nmake /F Makefile.win install

2.3 ビルド方法の選択

方法A: MSYS2使用（推奨しない – 問題が発生しやすい）

MSYS2でのビルドはパス名にスペースが含まれる問題でエラーが発生します。

方法B: Visual Studio Build Tools使用（推奨）

Developer Command Prompt起動
- スタートメニューで「Developer Command Prompt for VS」を検索
- 管理者として実行
環境変数設定 set "PGROOT=C:\Program Files\PostgreSQL\16"
ビルド実行 cd C:\temp\pgvector nmake /F Makefile.win nmake /F Makefile.win install

2.4 インストール成功の確認

以下のファイルが作成されていることを確認：

C:\Program Files\PostgreSQL\16\lib\vector.dll
C:\Program Files\PostgreSQL\16\share\extension\vector.control
C:\Program Files\PostgreSQL\16\share\extension\vector--*.sql

Step 3: pgvector動作確認

3.1 拡張機能の有効化

PostgreSQLに接続：

psql -U postgres -h localhost

pgvector拡張機能を作成：

CREATE EXTENSION vector;

拡張機能一覧で確認：

\dx

vector が表示されれば成功です。

3.2 動作テスト

基本的なベクトル演算をテスト：

-- ベクトル型のテスト
SELECT '[1,2,3]'::vector;

-- ベクトル間距離計算
SELECT '[1,2,3]'::vector <-> '[4,5,6]'::vector AS distance;

-- ベクトル次元数確認
SELECT vector_dims('[1,2,3,4,5]'::vector);

正常に結果が表示されれば、pgvectorの環境構築完了です。

よくある問題と解決方法

問題1: “make: No such file or directory”

原因: makeコマンドがWindows環境で認識されない

解決方法: Visual Studio Build ToolsのnmakeコマンドまたはMSYS2環境を使用

問題2: “pg_config: No such file or directory”

原因: PostgreSQLのパスが認識されていない

解決方法:

# 環境変数で明示的に指定
set "PGROOT=C:\Program Files\PostgreSQL\16"

問題3: “pgxs.mk: No such file or directory”

原因: PostgreSQL開発ツールがインストールされていない

解決方法: Stack Builderで開発ツールを追加インストール

問題4: パス名のスペースエラー

原因: Makefileがスペースを含むパス名を適切に処理できない

解決方法:

8.3形式パス使用: /c/PROGRA~1/POSTGR~1/16/
Visual Studio Build Tools使用（推奨）

実用的な使用例

RAGシステム用データベース設計

-- 新しいデータベース作成
CREATE DATABASE rag_system;
\c rag_system

-- pgvector有効化
CREATE EXTENSION vector;

-- ベクトル検索対応テーブル
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    content TEXT NOT NULL,
    embedding VECTOR(768),  -- 768次元ベクトル
    created_at TIMESTAMP DEFAULT NOW()
);

-- ベクトル検索用インデックス
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);

ベクトル類似検索クエリ

-- 類似文書検索
SELECT content, embedding <-> '[0.1,0.2,0.3,...]'::vector AS similarity
FROM documents
ORDER BY embedding <-> '[0.1,0.2,0.3,...]'::vector
LIMIT 5;