pgvector 源码学习: 1 pgvector 简介 (Introduction to pgvector)

pgvector不用多介绍, PostgreSQL的向量索引插件, 也可能是数据库领域最早一批支持向量搜索功能的开源插件!

今天把这一系列文章一把梭了(接下来每半个小时发一篇, 敬请关注本公众号)。祝贺PolarDB第二届国赛开赛, 祝愿同学们取得好成绩! ( 必须提前声明一下, 我对赛题细节一无所知! 如果想取得优异的成绩, 建议多关注官方渠道和“PolarDB公众号”! )

本文介绍 pgvector PostgreSQL 扩展（PostgreSQL extension）的高级概述（high-level overview），包括其架构（architecture）、核心功能（core capabilities）和关键组件（key components）。分享帮助理解 pgvector 如何在 PostgreSQL 中实现向量相似性搜索（vector similarity search）所需的基本概念。

什么是 pgvector？ (What is pgvector?)

pgvector 是一个开源的 PostgreSQL 扩展（extension），它为 PostgreSQL 添加了向量相似性搜索（vector similarity search）功能。它支持存储和查询高维向量嵌入（vector embeddings）以及常规关系数据，并完全支持 PostgreSQL 的 ACID 属性、时间点恢复（point-in-time recovery, PITR）、JOINs（连接）和事务语义（transactional semantics）。

该扩展实现了针对生产使用优化的近似最近邻（approximate nearest neighbor, ANN）搜索算法，使应用程序能够高效地在从数千到数十亿个向量的数据集中查找相似向量。

来源:README.md 1-15

核心功能 (Core Capabilities)

pgvector 提供了以下功能:

来源:README.md 5-12

系统架构概览 (System Architecture Overview)

下图展示了 pgvector 如何与 PostgreSQL 集成并暴露其功能:

关键集成点 (Key Integration Points):

1. Type System (类型系统): 向 PostgreSQL 的类型系统（type system）注册四种自定义数据类型（vector、halfvec、sparsevec、bit）
2. Operators (运算符): 定义与 PostgreSQL 运算符框架（operator framework）集成的距离运算符（<->、<#>、<=>、<+>、<~>、<%>）
3. Access Methods (访问方法): 实现两个 IndexAmRoutine 处理器（hnswhandler、ivfflathandler），它们接入 PostgreSQL 的索引扫描机制（index scan machinery）
4. Cost Estimation (成本估算): 提供成本估算函数（cost estimation functions），帮助查询规划器选择最优执行计划（optimal execution plans）

来源:README.md 1-15README.md 194-203README.md 330-332

关键组件和代码结构 (Key Components and Code Structure)

下图将系统组件映射到其实现文件:

来源:README.md 942-1059

文件组织 (File Organization)

pgvector 的源代码被组织成功能模块（functional modules）:

核心类型系统 (Core Type System)

• src/vector.c - vector 类型实现（float32 密集向量）
• src/halfvec.c - halfvec 类型实现（float16 密集向量）
• src/sparsevec.c - sparsevec 类型实现（sparse vectors, 稀疏向量）
• src/bitvector.c - 二进制量化（Binary quantization）和位向量操作（bit vector operations）

HNSW 索引 (HNSW Index)

• src/hnsw.c - 主 HNSW 访问方法处理器（access method handler）
• src/hnswbuild.c - 索引构建逻辑（Index construction logic）
• src/hnswinsert.c - 插入和更新操作（Insert and update operations）
• src/hnswscan.c - 搜索算法实现（Search algorithm implementation）
• src/hnswvacuum.c - VACUUM（清理）和维护操作（maintenance operations）
• src/hnswutils.c - HNSW 实用函数（Utility functions）

IVFFlat 索引 (IVFFlat Index)

• src/ivfflat.c - 主 IVFFlat 访问方法处理器（access method handler）
• src/ivfbuild.c - 使用 k-means（k-均值）进行索引构建
• src/ivfinsert.c - 插入操作（Insert operations）
• src/ivfscan.c - 基于列表的搜索实现（List-based search implementation）
• src/ivfvacuum.c - VACUUM（清理）操作
• src/ivfkmeans.c - Elkan 的 k-均值聚类算法（Elkan's k-means clustering algorithm）
• src/ivfutils.c - IVFFlat 实用函数（Utility functions）

支持文件 (Support Files)

• src/halfutils.c - 使用 F16C 进行半精度浮点转换（Half-precision float conversion）
• src/bitutils.c - 带有 AVX512 优化的位操作（Bit manipulation）
• sql/vector--*.sql - 类型、运算符、函数的 SQL 定义（SQL definitions）

来源:README.md 1-15

扩展生命周期 (Extension Lifecycle)

下图展示了 pgvector 如何与 PostgreSQL 的扩展系统（extension system）集成:

来源:README.md 52-57README.md 204-263

版本信息与兼容性 (Version Information and Compatibility)

当前版本 (Current Version)

• 最新版本（Latest Release）: 0.8.1 (2025-09-04)
• PostgreSQL 支持（PostgreSQL Support）: Versions 13 through 19 (including rc1)

关键版本里程碑 (Key Version Milestones)

平台支持 (Platform Support)

• 操作系统（Operating Systems）: Linux, macOS, Windows, FreeBSD
• 架构（Architectures）: x86-64 (带有 SIMD 优化), ARM64, i386
• CPU 特性（CPU Features）: 对 AVX、F16C、FMA、AVX512 的运行时调度（Runtime dispatch）

来源:CHANGELOG.md 1-226README.md 16-50

维度限制 (Dimension Limits)

不同的向量类型和索引方法有不同的维度限制（dimensional limitations）:

对于更高维度，可以采用半精度索引（half-precision indexing）、二进制量化（binary quantization）或降维（dimensionality reduction）等技术。

来源:README.md 250-254README.md 368-373README.md 813-816README.md 942-945

存储要求 (Storage Requirements)

每种向量类型都有不同的内存占用（memory footprints）:

这些存储特性（storage characteristics）会影响索引大小（index size）和查询性能（query performance）。选择合适的类型需要在精度要求（precision requirements）与存储和性能约束之间进行权衡。

来源:README.md 944-945README.md 982-983README.md 1020-1021README.md 1037-1039