AnalyticDB：pgvector相容模式使用指南

前提條件

• AnalyticDB PostgreSQL 6.0版執行個體的核心版本需為v6.6.1.0及以上。詳情請參見查看核心小版本。

• AnalyticDB PostgreSQL 6.0版執行個體已開啟向量檢索引擎功能。詳情請參見開啟或關閉向量檢索引擎最佳化。

pgvector相容模式優勢

對於使用pgvector作為向量檢索引擎的業務，AnalyticDB for PostgreSQL向量資料庫完全相容pgvector的向量讀寫操作，只需修改索引構建的SQL文法即可。因此，使用pgvector的業務可以無縫遷移到pgvector相容模式中，幾乎不需要改動業務代碼。pgvector相容模式優勢如下：

• 無需安裝PGVector外掛程式。執行個體開啟向量檢索引擎最佳化後可以直接使用。

• 完全相容pgvector的SQL文法。pgvector相容模式可以直接複用pgvector生態的用戶端。

• 分布式架構。pgvector主要適用於單機PostgreSQL資料庫，而pgvector相容模式是分布式架構，能處理更大的向量資料量。

• 高效能向量檢索引擎。pgvector相容模式使用自研的FastANN向量檢索引擎，效能優於原生pgvector。

• 混合查詢能力。pgvector相容模式的最佳化器和執行器支援產生和執行混合查詢計劃，具備強大的混合查詢能力，而原生pgvector僅能通過分區等手段實現簡單的情境。

• 儲存成本優勢。pgvector相容模式支援Float2類型壓縮向量表格儲存體，並具備PQ量化能力壓縮向量索引儲存，從而降低儲存成本。

建立向量表

建立相容pgvector文法的向量表和雲原生資料倉儲AnalyticDB PostgreSQL版中原生向量表的文法相同，只是表中的向量列由數組（smallint[]，float2[]和float4[]）類型改為了vector類型（pgvector定義的向量類型），並且一個表可以支援多個向量列。

CREATE TABLE [TABLE_NAME]
(  
    C1 DATATYPE,  
    C2 DATATYPE,  
    ......,  
    CN VECTOR(DIM), 
    PRIMARY KEY(C1 [,C2,...CN])
) DISTRIBUTED BY（C1);

CREATE TABLE FACE_TABLE (  
    C1 INT,  
    C2 VECTOR(512) NOT NULL, 
    C3 VECTOR(1536) NOT NULL, 
    C4 TIMESTAMP NOT NULL,  
    C5 VARCHAR(20) NOT NULL,  
    PRIMARY KEY (C1)
) DISTRIBUTED BY (C1);

建立向量索引

雲原生資料倉儲AnalyticDB PostgreSQL版向量資料庫的pgvector相容模式下向量索引的建立文法，仍然採用FastANN向量檢索引擎的文法，與pgvector的原生文法規則不同，具體可以參考如下所示文法：

CREATE INDEX [INDEX_NAME]
ON [SCHEMA_NAME].[TABLE_NAME]   
USING ANN(COLUMN_NAME) 
WITH (DIM=<DIMENSION>,
      DISTANCEMEASURE=<MEASURE>,
      HNSW_M=<M>,
      HNSW_EF_CONSTRUCTION=<EF_CONSTURCTION>,
      PQ_ENABLE=<PQ_ENABLE>,
      PQ_SEGMENTS=<PQ_SEGMENTS>,
      PQ_CENTERS=<PQ_CENTERS>,
      EXTERNAL_STORAGE=<EXTERNAL_STORAGE>;

-- 在向量列C2上建立三種向量索引。
CREATE INDEX idx_c2_l2 ON FACE_TABLE USING ann(C2) WITH (distancemeasure=l2, hnsw_m=64, pq_enable=1);
CREATE INDEX idx_c2_ip ON FACE_TABLE USING ann(C2) WITH (distancemeasure=ip, hnsw_m=64, pq_enable=1);
CREATE INDEX idx_c2_cosine ON FACE_TABLE USING ann(C2) WITH (distancemeasure=cosine, hnsw_m=64, pq_enable=1);
-- 在向量列C3上建立三種向量索引。
CREATE INDEX idx_c3_l2 ON FACE_TABLE USING ann(C3) WITH (distancemeasure=l2, hnsw_m=64, pq_enable=1);
CREATE INDEX idx_c3_ip ON FACE_TABLE USING ann(C3) WITH (distancemeasure=ip, hnsw_m=64, pq_enable=1);
CREATE INDEX idx_c3_cosine ON FACE_TABLE USING ann(C3) WITH (distancemeasure=cosine, hnsw_m=64, pq_enable=1);

向量資料匯入

相容pgvector文法的向量表的向量資料匯入完全相容pgvector的文法。以上文的FACE_TABLE表為例說明INSERT的使用方法，具體樣本如下：

INSERT INTO FACE_TABLE 
values (1, '[1,2,3 ... 512]', '[1,2,3 ... 1536]', '2023-12-29 00:00:00', 'aaa.bbb.ccc/face1.jpg');

向量檢索

對於使用pgvector文法的向量表，向量檢索的文法和pgvector原生文法完全相容，可以直接使用pgvector的原生查詢方式進行查詢。

與向量檢索召回率相關的核心參數與雲原生資料倉儲AnalyticDB PostgreSQL版向量資料庫的原生參數一致，詳情請參見向量檢索。以FACE_TABLE為例說明向量檢查的具體使用方式：

-- 精確搜尋方式：按歐氏距離排序。
SELECT C1 FROM FACE_TABLE ORDER BY vector_l2_squared_distance(C2, '[1,2,3 ... 512]') LIMIT 10;
-- 精確搜尋方式：按內積距離排序。
SELECT C1 FROM FACE_TABLE ORDER BY vector_negative_inner_product(C2, '[1,2,3 ... 512]') LIMIT 10;
-- 精確搜尋方式：按餘弦相似性排序。
SELECT C1 FROM FACE_TABLE ORDER BY cosine_distance(C2, '[1,2,3 ... 512]') LIMIT 10;

-- 近似搜尋方式：按歐氏距離排序。
SELECT C1 FROM FACE_TABLE ORDER BY C2 <-> '[1,2,3 ... 512]' LIMIT 10;
-- 近似搜尋方式：按內積距離排序。
SELECT C1 FROM FACE_TABLE ORDER BY C2 <#> '[1,2,3 ... 512]' LIMIT 10;
-- 近似搜尋方式：按餘弦相似性排序。
SELECT C1 FROM FACE_TABLE ORDER BY C2 <=> '[1,2,3 ... 512]' LIMIT 10;

由於已經在FACE_TABLE表的C2列上建了歐氏距離，內積距離和餘弦相似性三種距離度量的索引，因此樣本中的三種近似搜尋方式均能命中對應的向量索引。在實際使用的過程中，需要注意近似查詢方式中的操作符<->，<#>，<=>必須與向量索引的距離度量一一對應，否則如果沒有對應的距離度量的索引，將會退化為精確搜尋。

混合查詢

對於使用pgvector文法的向量表，混合查詢的方式與雲原生資料倉儲AnalyticDB PostgreSQL版向量資料庫的原生文法完全一致，詳情請參見混合檢索使用指南。下文以FACE_TABLE舉例說明混合查詢使用方法。

SELECT C1 FROM FACE_TABLE WHERE
  C4 > '2023-10-01 00:00:00' AND C4 < '2024-01-01 00:00:00'
ORDER BY 
  C2 <-> '[1,2,3 ... 512]'
LIMIT 10;

開原始碼庫適配

以開源大模型應用研發平台DIFY為例，介紹如何通過簡單的改造，讓使用pgvector的業務應用代碼能快速適配雲原生資料倉儲AnalyticDB PostgreSQL版向量資料庫。主要涉及三個方面的修改：

• 去除pgvector的外掛程式安裝。由於雲原生資料倉儲AnalyticDB PostgreSQL版向量資料庫並沒有適配pgvector外掛程式，只是在文法上相容了pgvector的向量表讀寫，因此不需要安裝pgvector的外掛程式。雲原生資料倉儲AnalyticDB PostgreSQL版向量資料庫在開通時會預設安裝自研向量檢索引擎外掛程式FastANN，只需要去掉pgvector的外掛程式即可。具體範例程式碼如下：

  # 代碼位於api/core/rag/datasource/vdb/pgvector/pgvector.py
  
  def _create_collection(self, dimension: int):
      cache_key = f"vector_indexing_{self._collection_name}"
      lock_name = f"{cache_key}_lock"
      WITH redis_client.lock(lock_name, timeout=20):
          collection_exist_cache_key = f"vector_indexing_{self._collection_name}"
          if redis_client.get(collection_exist_cache_key):
              RETURN
  
          WITH self._get_cursor() AS cur:
              # 去除下面的pgvector外掛程式安裝
              #cur.execute("CREATE EXTENSION IF NOT EXISTS vector")
              cur.execute(SQL_CREATE_TABLE.format(table_name=self.table_name, dimension=dimension))
              # TODO: CREATE index https://github.com/pgvector/pgvector?tab=readme-ov-file#indexing
          redis_client.set(collection_exist_cache_key, 1, ex=3600)
      

• 修改向量表建立。由於雲原生資料倉儲AnalyticDB PostgreSQL版向量資料庫是基於PostgreSQL9.4版本，不支援建表時使用using heap文法。雲原生資料倉儲AnalyticDB PostgreSQL版屬於分散式資料庫，需要設定分布鍵。修改向量表建立語句範例程式碼如下：

  # 代碼位於api/core/rag/datasource/vdb/pgvector/pgvector.py
  
  SQL_CREATE_TABLE = """
  CREATE TABLE IF NOT EXISTS {table_name} (
      id uuid PRIMARY KEY,
      text text NOT NULL,
      meta jsonb NOT NULL,
      embedding vector({dimension}) NOT NULL
  ) USING heap; 
  """
  
  # 修改為如下代碼:
  
  SQL_CREATE_TABLE = """
  CREATE TABLE IF NOT EXISTS {table_name} (
      id uuid PRIMARY KEY,
      text text NOT NULL,
      meta jsonb NOT NULL,
      embedding vector({dimension}) NOT NULL
  ) DISTRIBUTED BY (id); 
  """

• 修改向量索引建立。由於雲原生資料倉儲AnalyticDB PostgreSQL版向量資料庫採用的是自研向量檢索引擎FastANN的向量能力，並不是直接移植的pgvector外掛程式，在向量索引的建立文法上是有區別的，尤其是索引關鍵詞是不同的。因此必須按照雲原生資料倉儲AnalyticDB PostgreSQL版向量資料庫的文法進行索引的建立。具體範例程式碼如下：

  # 代碼位於api/core/rag/datasource/vdb/pgvector/pgvector.py
  
  # 添加建立向量索引的SQL（也可以直接在資料庫上建立索引，不再此添加）
  
  SQL_CREATE_INDEX = """
  CREATE INDEX ON  {table_name} USING ann(embedding) WITH (HNSW_M=16, HNSW_EF_CONSTRUCTION=500, PQ_ENABLE=1);
  """
  
  def _create_collection(self, dimension: int):
      cache_key = f"vector_indexing_{self._collection_name}"
      lock_name = f"{cache_key}_lock"
      WITH redis_client.lock(lock_name, timeout=20):
          collection_exist_cache_key = f"vector_indexing_{self._collection_name}"
          if redis_client.get(collection_exist_cache_key):
              RETURN
  
          WITH self._get_cursor() AS cur:
              # 去除下面的pgvector外掛程式安裝
              #cur.execute("CREATE EXTENSION IF NOT EXISTS vector")
              cur.execute(SQL_CREATE_TABLE.format(table_name=self.table_name, dimension=dimension))
              # TODO: CREATE index https://github.com/pgvector/pgvector?tab=readme-ov-file#indexing
              # 建立ADB-PG向量資料庫的向量索引
              cur.execute(SQL_CREATE_INDEX.format(table_name=self.table_name))
          redis_client.set(collection_exist_cache_key, 1, ex=3600)

相關參考

-- 歐氏距離
SELECT l2_distance('[1,1,1,1]'::vector, '[2,2,2,2]'::vector);
-- 內積距離
SELECT inner_product('[1,1,1,1]'::vector, '[2,2,2,2]'::vector);
-- 餘弦相似性
SELECT cosine_similarity('[1,1,1,1]'::vector, '[2,2,2,2]'::vector);
-- 向量維度
SELECT vector_dims('[1,1,1,1]'::vector);
-- 向量模長
SELECT vector_norm('[1,1,1,1]'::vector);
-- 向量加法
SELECT vector_add('[1,1,1,1]'::vector, '[2,2,2,2]'::vector);
-- 向量減法
SELECT vector_sub('[1,1,1,1]'::vector, '[2,2,2,2]'::vector);
-- 向量乘法
SELECT vector_mul('[1,1,1,1]'::vector, '[2,2,2,2]'::vector);
-- 向量夾角
SELECT vector_angle('[1,1,1,1]'::vector, '[2,2,2,2]'::vector);
-- 歐氏平方距離
SELECT vector_l2_squared_distance('[1,1,1,1]'::vector, '[2,2,2,2]'::vector);
-- 反內積距離
SELECT vector_negative_inner_product('[1,1,1,1]'::vector, '[2,2,2,2]'::vector);
-- 餘弦距離
SELECT cosine_distance('[1,1,1,1]'::vector, '[2,2,2,2]'::vector);

-- 歐氏距離（平方）
SELECT '[1,1,1,1]'::vector <-> '[2,2,2,2]'::vector AS score;
 
-- 反內積距離
SELECT '[1,1,1,1]'::vector <#> '[2,2,2,2]'::vector AS score;
 
-- 餘弦距離
SELECT '[1,1,1,1]'::vector <=> '[2,2,2,2]'::vector AS score;

-- 加法
SELECT '[1,1,1,1]'::vector + '[2,2,2,2]'::vector AS value;

-- 減法
SELECT '[1,1,1,1]'::vector - '[2,2,2,2]'::vector AS value;

-- 乘法
SELECT '[1,1,1,1]'::vector * '[2,2,2,2]'::vector AS value;