Nacos AI Vector 插件规范解析：PgVector 向量索引 SPI 的设计、实现与运维
发布时间：2026/9/10 21:39:16 作者：尧图编辑部 阅读量：1,286
Nacos AI Vector 插件规范解析PgVector 向量索引 SPI 的设计、实现与运维【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos导读本文基于 ai-vector-plugin-spec.md 规范文档并结合 Nacos 仓库中plugin/ai模块与nacos-default-ai-vector-plugin实现系统讲解 Nacos AI 发现体系中向量检索 SPI 的完整契约从启用开关、Provider 生命周期、索引写入/检索接口、Schema 归属到一致性保障、安全边界与兼容性测试。读者读完可以掌握如何为 Nacos 配置 PostgreSQL pgvector 向量检索、理解向量索引与关系型搜索索引的协作方式以及如何自行实现一个合规的向量 Provider。1. 背景向量检索在 Nacos AI 发现中的定位Nacos 是一个面向 AI 云原生应用的动态服务发现、配置与服务平台。随着 Agent 资源、Prompt、Skill、MCP Server 等 AI 资源被纳入管理仅靠关键词匹配已无法满足语义检索需求。AI Vector 插件为 Nacos AI 发现提供了可选的向量索引与召回能力它扩展了 Nacos Plugin Spec 定义的插件契约但不改变 AI 资源的规范身份identity、生命周期、可见性与授权模型。从源码结构看向量 SPI 归属于 AI 模块SPI 定义位于 plugin/ai/src/main/java/com/alibaba/nacos/plugin/ai/vector/spi包含AiResourceVectorIndex与AiResourceVectorIndexBuilder两个接口公共模型位于 plugin/ai/src/main/java/com/alibaba/nacos/plugin/ai/vector包含AiResourceVectorChunk、AiResourceVectorDocument、AiResourceVectorHit与注册表AiResourceVectorIndexRegistry默认的 PostgreSQL 实现由独立模块 nacos-default-ai-vector-plugin 提供其实现类位于com.alibaba.nacos.plugin.ai.vector.postgresql包下。1.1 向量索引是可选的不影响核心能力规范明确了三条不阻塞原则未启用 AI 资源搜索运行时或没有可用的向量 Provider不得阻止 Nacos 启动不得阻止 AI 资源的规范写入canonical resource writes不得阻止关键词搜索keyword search。这意味着向量能力是纯粹的增强项。即便整个环境不装 pgvectorNacos 核心功能照常工作。2. 启用方式配置开关与 Provider 选择2.1 三个关键配置项配置项默认值作用nacos.ai.resource.search.enabledtrue协议无关的共享 Search Core 总开关RAD、ARD、通用 AI 资源搜索、资源级搜索共用nacos.ai.resource.search.vector.provider未配置选择具体向量 Provider如postgresqlnacos.ai.ard.enabledfalse仅控制 ARD 协议端点不能独立决定向量 Provider 是否激活在 distribution/conf/application.properties 中可以找到这些开关的官方注释说明### Whether protocol-neutral AI Resource Search is enabled. Default is true. ### Search is shared by RAD, ARD, generic AI Resource Search, and resource-specific Search. ### Initialize the AI resource search document/chunk/task tables in the main datasource before enabling it. #nacos.ai.resource.search.enabledtrue ### Whether Agentic Resource Discovery is enabled. Default is false. ### This switch controls only the ARD Web Context and protocol endpoints. nacos.ai.ard.enabledfalse关键点nacos.ai.ard.enabled与向量 Provider 激活解耦——即使 ARD 关闭、仅启用共享 Search Core向量检索依然可服务于其他非 ARD 消费方。2.2 默认 PostgreSQL Provider 的连接配置nacos-default-ai-vector-plugin的 PostgresqlAiResourceVectorIndex.java 定义了如下 Provider 专属配置键名以nacos.ai.resource.search.vector.postgresql.为前缀配置项默认值说明nacos.ai.resource.search.vector.postgresql.url空专用 pgvector 数据源 JDBC URL如jdbc:postgresql://127.0.0.1:5432/nacos_ai_searchnacos.ai.resource.search.vector.postgresql.user空数据源用户名nacos.ai.resource.search.vector.postgresql.password空数据源密码nacos.ai.resource.search.vector.postgresql.driver-class-nameorg.postgresql.DriverJDBC 驱动类名对应的示例配置来自 application.properties#nacos.ai.resource.search.vector.postgresql.urljdbc:postgresql://127.0.0.1:5432/nacos_ai_search #nacos.ai.resource.search.vector.postgresql.usernacos #nacos.ai.resource.search.vector.postgresql.passwordnacos #nacos.ai.resource.search.vector.postgresql.driver-class-nameorg.postgresql.Driver从 getJdbcTemplate() 的实现可以看出数据源选择的优先级若注入了JdbcTemplate测试场景则直接使用否则若配置了专用 URL则基于DataSourcePoolProperties构建一个专用连接池懒加载 双重检查锁见 getDedicatedJdbcTemplate否则回退到 Nacos 主数据源DynamicDataSource。因此向量索引可以复用主数据源也可以使用完全独立的 PostgreSQL 数据源这也是下文Schema 隔离能成立的前提。3. Provider 生命周期Builder、Router 与 no-op 回退3.1 Builder 契约每个向量实现必须提供一个AiResourceVectorIndexBuilder它有两个职责type()返回稳定的 Provider 类型标识例如postgresqlbuild()创建AiResourceVectorIndex实例。默认实现 PostgresqlAiResourceVectorIndexBuilder.java 中type()直接返回PostgresqlAiResourceVectorIndex.TYPE即字符串postgresql。3.2 注册表与加载逻辑AiResourceVectorIndexRegistryAiResourceVectorIndexRegistry.java通过 Nacos 的NacosServiceLoader加载所有AiResourceVectorIndexBuilder并执行三条健壮性规则Provider 类型非空类型为空直接抛IllegalStateException类型唯一重复的 Provider 类型抛IllegalStateException(Duplicate AI resource vector index provider type: ...)构建失败容忍build()抛异常或返回 null 时仅记录 WARN 日志并跳过不影响其他 Provider 加载。这些行为在 AiResourceVectorIndexRegistryTest.java 中有对应测试shouldLoadVectorIndexPlugins验证多 Provider 加载、shouldRejectDuplicateProviderType验证重复类型拒绝、shouldIgnoreProviderThatCannotBeBuilt验证失败容忍。3.3 路由与 no-op 回退Router 至多选择一个 Provider并通过统一的插件管理模型上报插件状态。当没有配置 Provider 或 Provider 不可用时回退到no-op 实现空操作实现保证向量调用方无需判空即可安全调用。available()的语义需要精确理解它报告当前实例能否执行向量操作不代表规范资源或关系型索引不可用。例如默认实现中 available() 会先判断数据源是否为 PostgreSQLisPostgresql()再尝试SELECT COUNT(1) FROM ai_resource_search_embedding_pg WHERE 10探测表和扩展是否就绪异常则返回 false。同时规范要求实现必须在close()中释放连接池、客户端与执行器——默认实现的 close() 关闭专用数据源即体现了这一要求。4. 索引契约文档模型与操作原语4.1 数据模型Chunk、Document、Hit向量索引操作的是资源搜索分块chunk级别的数据三者关系如下AiResourceVectorChunk.java分块元数据包含idchunkId、documentId、namespaceId、resourceType、resourceName、resourceVersion、chunkTypeAiResourceVectorDocument.java一份向量文档 一个 chunk embeddingModel嵌入模型名embeddingdouble[]向量AiResourceVectorHit.java召回结果标识 document/chunk 及资源并携带 Provider 相似度分数score。由此文档身份identity由 namespace、resource type、resource name、version、model、chunk identity 共同组成任何维度都不能缺失否则无法精确对账或删除。4.2 操作原语SPI 方法AiResourceVectorIndex.java 定义了完整操作集方法语义replaceResourceVersion(namespaceId, resourceType, resourceName, resourceVersion, documents)以资源版本为单位整体替换嵌入向量addDocuments(documents)为新增的 chunk 追加文档deleteByResource(namespaceId, resourceType, resourceName)删除整个资源的嵌入deleteByResourceVersion(namespaceId, resourceType, resourceName, resourceVersion)删除某一资源版本的嵌入search(namespaceId, embeddingModel, queryVector, resourceTypes, limit)向量最近邻搜索isResourceVersionReady(...)两个重载版本就绪对账close()释放资源规范对操作语义的约束幂等性替换与删除操作必须幂等重复执行结果一致版本原子性替换某个资源版本后同一 Provider 内要么只见旧完整版本、要么只见新完整版本绝不允许出现半套文档即替换期间不能暴露部分写入的中间态搜索按命名空间隔离并可选限制资源类型命中的结果只标识规范资源与 chunk、带 Provider 相似度分数即可协议专属 DTO、URL、信任清单trust manifests、可见性判定与最终排序不属于向量 SPI 的职责——这些由协议无关的 AI 资源搜索服务在合并向量命中与关键词召回后统一处理生命周期、可见性、最终排序、分页。4.3 默认实现如何满足契约PostgreSQL 实现中replaceResourceVersion使用TransactionTemplateDataSourceTransactionManager在单个本地数据源事务内先按版本删除、再批量插入PostgresqlAiResourceVectorIndex.java#L103-L114从而满足版本原子性search使用 pgvector 的余弦距离运算符计算相似度1 - (embedding ?::vector)并支持按resource_type IN (...)过滤、按距离排序、LIMIT截断L170-L200空模型、空向量等非法输入直接返回空列表。5. Schema 归属与初始化pgvector 只属于插件5.1 关键设计主库 schema 不创建 pgvector 对象规范明确规定每个实现拥有自己的可选数据库对象与迁移脚本Nacos 主 PostgreSQL 数据源 schema 不得创建 pgvector 扩展或 embedding 表。这一点在 pg-schema.sql主数据源脚本与 pg-ai-vector-schema.sql向量插件脚本的文件拆分上得到印证application.properties 中的注释也明确写道pg-schema.sql intentionally does not include pgvector objects.由此带来的运维收益全新部署可以在不装 pgvector 的情况下使用 PostgreSQL没有扩展创建权限的数据库用户也能启动 Nacos只要向量发现被禁用即可。5.2 初始化步骤启用 PostgreSQL 向量存储前需要手动将pg-ai-vector-schema.sql加载到用于嵌入的数据源中无论该数据源是主数据源还是专用数据源。该脚本内容如下CREATE EXTENSION IF NOT EXISTS vector; DROP TABLE IF EXISTS ai_resource_search_embedding_pg; CREATE TABLE ai_resource_search_embedding_pg ( id bigserial NOT NULL, gmt_create timestamp(6) NOT NULL DEFAULT CURRENT_TIMESTAMP, gmt_modified timestamp(6) NOT NULL DEFAULT CURRENT_TIMESTAMP, namespace_id varchar(128) NOT NULL DEFAULT , document_id bigint NOT NULL, chunk_id bigint NOT NULL, resource_type varchar(32) NOT NULL, resource_name varchar(256) NOT NULL, resource_version varchar(64) NOT NULL, embedding_model varchar(128) NOT NULL, embedding_dimension integer NOT NULL, embedding vector NOT NULL );脚本同时创建主键ai_resource_search_embedding_pg_pkey以及三个查询索引idx_search_embedding_pg_chunk按chunk_id的 B-tree支撑 chunk 维度精确删除/对账idx_search_embedding_pg_model按(namespace_id, embedding_model, embedding_dimension, resource_type)的复合 B-tree加速搜索过滤idx_search_embedding_pg_resource按(namespace_id, resource_type, resource_name, resource_version)的复合 B-tree支撑资源/版本维度的删除与就绪检查。5.3 可用性前置校验实现必须在报告自身available()之前校验pgvector 扩展、embedding 表、向量维度、索引兼容性。默认实现通过探测表存在性完成粗校验维度一致性则在写入与搜索时通过embedding_dimension字段与查询向量长度双重约束见search中AND embedding_dimension?。6. 一致性保障双索引、幂等消费者与对账6.1 没有分布式事务靠幂等消费者关系型 AI 资源搜索索引与所选向量索引不共享分布式事务。正确性由 AI 模块中的一个**持久化、幂等的索引消费方indexing consumer**保证它从规范资源状态出发同时驱动关系型索引与向量索引。向量失败只让任务保持可重试绝不能回滚已经提交的规范资源写入。6.2 重试与周期对账消费方对瞬时失败执行有界退避重试**周期对账reconciliation**检测缺失、部分、过期或错误模型的向量数据更换嵌入模型或向量 Provider 时需要重建受影响文档实现必须暴露足够的健康与索引身份信息供对账使用但不得向协议适配器暴露 Provider 专属类型。6.3 isResourceVersionReady精确对账的钩子isResourceVersionReady(...)将以下预期值与 Provider 中实际索引的文档进行比对配置的嵌入模型embedding model预期的关系型文档身份document identity预期的关系型 chunk 数量。接口提供两个重载AiResourceVectorIndex.java#L65-L82基础重载比较模型与数量默认返回 true兼容不暴露对账元数据的旧 Provider带expectedDocumentId的重载额外校验文档身份默认委托给基础重载支持精确对账的 Provider 应覆写它。默认 PostgreSQL Provider 覆写了两个重载基础版按(namespace, resource_type, resource_name, resource_version, embedding_model)计数比对文档感知版进一步用MIN(document_id) MAX(document_id) expectedDocumentId校验单一文档身份L142-L168。6.4 事务性替换默认 PostgreSQL Provider 在单个本地数据源事务内完成资源版本替换删除旧版本 插入新文档兼顾了版本原子性与无跨库分布式事务两个约束。7. 安全与运维要点规范对实现提出的安全要求可以归纳为四点凭据保护连接凭据与 Provider 密钥属于敏感配置插件详情 API 不得返回、日志不得输出数据边界一致嵌入内容由规范资源派生必须与这些资源遵守相同的命名空间与数据处理边界不能越权嵌入其他命名空间内容资源用量有界实现必须约束批大小batch size、查询上限query limit、连接使用与重试并发可观测性分离插件不可用与索引滞后必须能独立于规范资源写入健康状态被观测到即向量问题不能与核心写入问题混为一谈。8. 兼容性约束与测试体系8.1 兼容性规则SPI 变更必须保持插件模块的 Java 8 兼容性并遵循 Nacos 插件兼容性规则新增可选方法必须提供向后兼容的默认实现或进行协调一致的兼容性变更本文档接口中两个isResourceVersionReady重载均带 default 实现即为范例。8.2 契约测试覆盖SPI 契约测试覆盖Provider 选择、no-op 回退、幂等替换/删除、范围搜索、生命周期清理。默认 PostgreSQL 实现额外测试Schema 隔离PostgresqlAiVectorSchemaResourceTest.java禁用 pgvector 时的无扩展运行共享 Search Core 开启、ARD 关闭时对非 ARD 消费方的可用性Provider 内事务性替换PostgresqlAiResourceVectorIndexTest.java模拟向量失败后的对账AiResourceVectorIndexRegistryIntegrationTest.java。9. 快速落地清单要在当前仓库的 Nacos 上启用 PostgreSQL 向量检索操作顺序如下准备 PostgreSQL安装含 pgvector 扩展的 PostgreSQL建议独立数据库如nacos_ai_search初始化向量 schema将 pg-ai-vector-schema.sql 加载到嵌入数据源主数据源或专用数据源均可主库pg-schema.sql故意不含 pgvector 对象确认 Search Core 开启nacos.ai.resource.search.enabledtrue默认即为 true并按注释要求先在主数据源初始化 AI 资源搜索的 document/chunk/task 表配置向量 Provider设置nacos.ai.resource.search.vector.providerpostgresql并按需配置nacos.ai.resource.search.vector.postgresql.url/user/password不配 URL 时复用主数据源按需开启 ARDnacos.ai.ard.enabled只控制 ARD 端点与向量 Provider 激活相互独立验证通过available()反映的插件状态确认向量就绪观察周期对账日志确认无缺失/过期文档。10. 总结Nacos AI Vector 插件以可选、隔离、幂等、可对账四个关键词概括其设计哲学向量索引是可选的锦上添花绝不阻塞核心能力pgvector schema 完全由插件独占主库保持纯净双索引一致依赖幂等消费者而非分布式事务就绪检查与周期对账让向量数据始终可验证、可修复。对于需要语义检索 AI 资源的场景nacos-default-ai-vector-plugin与pg-ai-vector-schema.sql提供了开箱即用的 PostgreSQL 落地方案而AiResourceVectorIndex/AiResourceVectorIndexBuilder接口则为其他向量引擎如 Milvus、Elasticsearch 向量检索等的接入预留了清晰的扩展点。【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 