Spring AI PGVector 報 type vector does not exist

報 type "vector" does not exist，十有八九不是 Spring AI 配錯了，而是 PostgreSQL 里根本沒啟用 pgvector 擴展。initialize-schema=true 只能幫你建表，幫不了你安裝數據庫擴展。

Issue & Env（案發現場與環境）

業務場景：項目接入 PgVectorStore，啟動時希望由 Spring AI 自動建表並寫入 embedding。
常見環境：Spring Boot 3.x、Spring AI 1.1.x / 2.0.x、PostgreSQL 15+，本地數據庫可能是純 Postgres 鏡像，不是預裝 pgvector 的鏡像。

StackTrace（堆疊日誌）

報錯原文直接打在建表 SQL 上：

org.postgresql.util.PSQLException: ERROR: type "vector" does not exist
  Position: 146

完整堆疊從 Spring AI 建表一路走到 PG JDBC 驅動：

org.springframework.jdbc.BadSqlGrammarException:
StatementCallback; bad SQL grammar [CREATE TABLE IF NOT EXISTS vector_store (...)];
nested exception is org.postgresql.util.PSQLException: ERROR: type "vector" does not exist
    at org.springframework.jdbc.core.JdbcTemplate.execute(JdbcTemplate.java:414)
    at org.springframework.ai.vectorstore.pgvector.PgVectorStore.initializeSchema(PgVectorStore.java:173)
    at org.springframework.ai.vectorstore.pgvector.PgVectorStore.afterPropertiesSet(PgVectorStore.java:138)
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.invokeInitMethods(AbstractAutowireCapableBeanFactory.java:1863)
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.initializeBean(AbstractAutowireCapableBeanFactory.java:1812)
Caused by: org.postgresql.util.PSQLException: ERROR: type "vector" does not exist
    at org.postgresql.core.v3.QueryExecutorImpl.receiveErrorResponse(QueryExecutorImpl.java:2731)
    at org.postgresql.core.v3.QueryExecutorImpl.processResults(QueryExecutorImpl.java:2420)
    at org.postgresql.core.v3.QueryExecutorImpl.execute(QueryExecutorImpl.java:352)
    at org.postgresql.jdbc.PgStatement.executeInternal(PgStatement.java:498)
    at org.postgresql.jdbc.PgStatement.execute(PgStatement.java:413)

BadSqlGrammarException 是 Spring JDBC 對“SQL 本身語法/類型錯誤”的統一包裝，Caused by 裡的 PSQLException 才是 PG 服務端拒絕建表的原始報錯。

如果你自己先手寫了擴展語句，但數據庫裡沒有安裝 pgvector，也可能看到：

ERROR: extension "vector" is not available
DETAIL: Could not open extension control file ".../vector.control": No such file or directory.

Reproduce（復現程式碼）

只配 Spring AI 的 PGvector starter 和初始化開關，但數據庫本身沒裝擴展：

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/ai
    username: postgres
    password: postgres
  ai:
    vectorstore:
      pgvector:
        initialize-schema: true
        dimensions: 1536

啟動後，框架會嘗試創建類似這樣的表結構：

CREATE TABLE IF NOT EXISTS vector_store (
  id uuid DEFAULT uuid_generate_v4() PRIMARY KEY,
  content text,
  metadata json,
  embedding vector(1536)
);

只要當前數據庫裡沒有 vector 類型，這句 SQL 就會直接失敗。

Root Cause（根因分析）

Spring AI 官方文檔把前提寫得很明確：使用 PGvector 之前，PostgreSQL 實例裡要先啟用 vector、hstore 和 uuid-ossp 擴展。也就是說，Spring AI 負責的是向量表和索引層；pgvector 這個數據庫擴展本身，必須由你或 DBA 先安裝。

這裡最容易踩的坑有兩個：

1. 把“初始化 schema”誤解成“安裝擴展”

spring.ai.vectorstore.pgvector.initialize-schema=true 的職責是創建 Spring AI 需要的表、索引和字段，不會替你執行操作系統層面的擴展安裝，也不會替你把 CREATE EXTENSION vector 變成萬能修復。

2. 用了純 PostgreSQL 鏡像

很多人本地起的是官方 postgres 鏡像，而不是帶 pgvector 的鏡像。這樣數據庫雖然能連，但 vector 類型根本不存在。你直到建表時才會看見 type "vector" does not exist，於是誤以為是 ORM、DDL 或維度設定的問題。

The Fix（解決方案）

先確認數據庫真的安裝了 pgvector

在數據庫裡執行：

SELECT * FROM pg_extension WHERE extname IN ('vector', 'hstore', 'uuid-ossp');

如果查不到 vector，先安裝擴展，再談 Spring AI。

本地開發直接用帶 pgvector 的鏡像

最省事的辦法是直接起帶擴展的鏡像，例如：

docker run --name pgvector-demo \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=ai \
  -p 5432:5432 \
  -d pgvector/pgvector:pg16

然後連進去執行：

CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS hstore;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

再讓 Spring AI 建表

擴展確認無誤後，再保留：

spring:
  ai:
    vectorstore:
      pgvector:
        initialize-schema: true

此時 embedding vector(1536) 才能被 PostgreSQL 正常識別。

生產環境別把擴展安裝放在應用啟動裡賭運氣

如果是線上數據庫，建議把擴展安裝和權限開通放進數據庫初始化腳本、Terraform、Flyway/Liquibase 或 DBA 流程，而不是指望應用第一次啟動時“順便搞定”。因為很多託管 PostgreSQL 服務預設不允許普通業務賬號執行 CREATE EXTENSION。

小結

type "vector" does not exist 的本質，是數據庫裡沒有 vector 類型。
Spring AI 會幫你建向量表，不會替你安裝 pgvector 擴展。
修復順序是：安裝擴展 -> 執行 CREATE EXTENSION -> 再讓 Spring AI 初始化 schema。
如果你用的是純 Postgres 鏡像，這個錯誤幾乎必現。