本页面介绍了用于存储向量索引统计信息的内置 Spanner 表。您可以使用向量索引统计信息来查看向量索引的性能、确定需要改进的方面，以及根据指标对索引进行调优。
您可以使用 SQL 语句从 SPANNER_SYS.VECTOR_INDEX_STATS 表中检索统计信息。
Spanner 在 SPANNER_SYS 架构中提供矢量索引统计信息。您可以通过以下方式访问 SPANNER_SYS 数据：
Google Cloud 控制台中的数据库 Spanner Studio 页面。
向量索引统计信息
SPANNER_SYS.VECTOR_INDEX_STATS 包含数据库中每个向量索引的统计信息，按 STATISTICS_COLLECTION_TIMESTAMP 排序。Spanner 每三天收集一次有关每个向量索引的数据。收集数据后不久，Spanner 就会在 VECTOR_INDEX_STATS 表中提供这些数据。此表中的信息可让您深入了解索引，从而进行调优并应用建议，以提高向量搜索性能。
| 列名 | 说明 | 调优指南 |
|---|---|---|
START_TIME |
Spanner 收集索引指标的时间。 | 不适用 |
VECTOR_INDEX_NAME |
矢量索引的名称，如 CREATE VECTOR INDEX 语句中所示。 |
不适用 |
NUM_LEAVES |
相应向量索引中使用的叶（也称为聚类）总数。此数量是在创建向量索引时确定的。随着 Spanner 自适应地重塑向量索引，此值可能会随时间而变化。 | 如果在创建索引表后向其中添加了许多行，则某些聚类可能会变得非常大，从而影响查询延迟时间。如果索引中的聚类数量等于或大于表中行数的平方根，建议使用更多聚类重建索引。 |
NUM_ZERO_SIZE_CLUSTERS_SAMPLED |
矢量索引中空聚类的抽样数量。空聚类没有任何分配给它们的行。 | 随着时间的推移，当向表中添加行和从表中删除行时，某些聚类可能会变为空。如果存在许多空聚类，则向量索引可能已过时。如果 10% 或更多的聚类为空，请考虑使用较少的聚类重建索引。对于较大的向量索引，Spanner 会使用随机抽样来限制衡量指标的费用。因此，此指标表示抽样到的零大小聚类的数量。如需将此值转换为估计的零大小聚类数量，您可以使用以下查询：
|
CLUSTER_SIZE_PERCENTILES |
向量索引会将已编入索引的嵌入内容划分为邻近向量的聚类。此分布列给出了这些聚类的大小的某些百分位值。 | 为向量编入索引的 K-means 聚类过程通常会生成大小各异的聚类。因此，预计会出现一些不平衡。如果集群大小存在严重偏差，则在搜索较大集群时，查询性能会变慢。 如果第 99 百分位聚类大小至少是第 50 百分位聚类大小的 8 倍，则偏差严重。请参阅示例查询 1。 |
CLUSTER_AVERAGE_DISTANCE_TO_CENTROID_PERCENTILES |
每个聚类都有一个中心点，即形心。为了实现较高的召回率，系统通常会根据您在创建索引期间选择的配置，将向量分配给附近的质心。对于每个聚类，Spanner 会计算从形心到所有分配的向量的估计平均距离。由于各集群之间存在自然差异，因此 Spanner 会以分布形式（即百分位数值列表）报告此指标。 | 此指标在向量索引之间不具可比性（尤其是欧几里得指数和余弦指数的缩放比例不同）。随时间跟踪每个向量索引的这一指标。如果第 99 百分位数值比历史最低值高出一倍，请考虑重建索引以将其降回较低水平。请参阅示例查询 2。 |
示例查询 1
以下查询会报告特定矢量索引的第 99 百分位聚类大小与中位聚类大小的比值（随时间变化）。如果第 99 百分位聚类大小至少比第 50 百分位聚类大小大 8 倍，请考虑重建索引。
SELECT VECTOR_INDEX_NAME,
START_TIME,
SUM(CASE WHEN percentile = 99 THEN value_at_percentile ELSE 0 END)
/ SUM(CASE WHEN percentile = 50 THEN value_at_percentile ELSE 0 END) as cluster_size_imbalance
FROM (
SELECT v.VECTOR_INDEX_NAME,
v.START_TIME, d.percentile,
d.value_at_percentile
FROM SPANNER_SYS.VECTOR_INDEX_METRICS_HISTORY AS v,
UNNEST(v.CLUSTER_AVERAGE_DISTANCE_TO_CENTROID_PERCENTILES)
AS d)
WHERE VECTOR_INDEX_NAME = "VecIndex2"
GROUP BY 1, 2;
查询输出
| VECTOR_INDEX_NAME | START_TIME | cluster_size_imbalance |
|---|---|---|
| VecIndex2 | 2025-12-10 10:09:55.322415+00:00 | 3.288 |
| VecIndex2 | 2025-12-07 10:10:02.362223+00:00 | 3.11 |
| VecIndex2 | 2025-12-04 10:09:55.180895+00:00 | 2.98 |
| VecIndex2 | 2025-12-01 10:10:01.680543+00:00 | 3.01 |
| VecIndex2 | 2025-11-28 10:10:02.130079+00:00 | 2.99 |
示例查询 2
以下查询会报告每个向量索引在不同时间段内与形心的第 99 百分位距离。此指标可间接反映召回性能。值的确切含义取决于您的嵌入。单独跟踪每个向量指数，并将其作为时序进行跟踪。如果某个指数的第 99 百分位数值比历史最低值高出一倍，请考虑重新构建该指数。
SELECT v.VECTOR_INDEX_NAME,
v.START_TIME,
d.value_at_percentile AS distance_to_centroid_99p
FROM SPANNER_SYS.VECTOR_INDEX_METRICS_HISTORY AS v,
UNNEST(v.CLUSTER_AVERAGE_DISTANCE_TO_CENTROID_PERCENTILES) AS d
WHERE d.percentile=99
ORDER BY VECTOR_INDEX_NAME, START_TIME DESC;
查询输出
| VECTOR_INDEX_NAME | START_TIME | distance_to_centroid_99p |
|---|---|---|
| ANNVectorBase_VI | 2025-12-10 10:09:55.322415+00:00 | 1.109 |
| ANNVectorBase_VI | 2025-12-07 10:10:02.362223+00:00 | 1.11 |
| ANNVectorBase_VI | 2025-12-04 10:09:55.180895+00:00 | 1.18 |
| ANNVectorBase_VI | 2025-12-01 10:10:01.680543+00:00 | 1.11 |
| ANNVectorBase_VI | 2025-11-28 10:10:02.130079+00:00 | 1.04 |
数据保留
SPANNER_SYS.VECTOR_INDEX_METRICS_HISTORY 系统表会保留过去 30 天内的数据。
后续步骤
- 了解如何重建向量索引。