mcp-toolbox vector-assist-modify-spec 工具详解调整 Cloud SQL for PostgreSQL 向量规格并自动重算 SQL 建议【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolboxvector-assist-modify-spec是 MCP Toolbox for Databases 中面向 Cloud SQL for PostgreSQL 的向量检索配置工具用于在已定义的向量规格vector specification基础上修改参数如目标召回率、嵌入模型、量化方式等并自动重算、刷新由vector_assist.define-spec生成的 SQL 建议列表。读完本文你将掌握该工具的完整参数语义、YAML 配置写法、底层 SQL 调用链路以及它与 define-spec / apply-spec 等配套工具构成的向量工作负载配置工作流从而能在不手工编写 DDL 的前提下通过 Agent 迭代调优 PostgreSQL 向量索引方案。工具概述与定位官方文档 vector-assist-modify-spec 说明 对该工具的定义是修改由必填参数spec_id标识的既有向量规格接受新的参数或覆盖项修改完成后自动重新计算并刷新vector_assist.define-spec生成的 SQL 建议列表使其与更新后的规格要求保持一致适用场景在真正执行建索引、生成嵌入等 setup 命令之前由用户或 Agent 对已定义好的向量规格做微调例如更换目标召回率、嵌入模型或量化方式底层机制工具连接到目标数据库执行vector_assist.modify_spec函数以生成更新后的规格与建议。从源码结构看这一描述与实现完全一致vectorassistmodifyspec.go 中的modifySpecQuery正是通过SELECT ... FROM vector_assist.modify_spec(...)一次性传入全部覆盖参数并返回重算后的建议行。在 vector-assist 工作流中的位置向量检索的配置流程由一组配套工具组成。仓库的预置配置 cloud-sql-postgres.yaml 中同时声明了这组工具kind: tool name: define_spec type: vector-assist-define-spec source: cloudsql-pg-source --- kind: tool name: modify_spec type: vector-assist-modify-spec source: cloudsql-pg-source --- kind: tool name: apply_spec type: vector-assist-apply-spec source: cloudsql-pg-source --- kind: tool name: generate_query type: vector-assist-generate-query source: cloudsql-pg-source --- kind: tool name: delete_spec type: vector-assist-delete-spec source: cloudsql-pg-source --- kind: tool name: list_specs type: vector-assist-list-specs source: cloudsql-pg-source --- kind: tool name: get_spec type: vector-assist-get-spec source: cloudsql-pg-source --- kind: tool name: improve_query_recall type: vector-assist-improve-query-recall source: cloudsql-pg-source典型工作流为define用 vector-assist-define-spec 捕获意图、生成规格及一套有序的 SQL 建议modify本文主题在执行建议前通过vector-assist-modify-spec覆盖规格中的任意参数系统自动刷新建议apply用 vector-assist-apply-spec 执行建议后续可通过 get-spec / list-specs 查询、improve-query-recall 迭代召回率、delete-spec 清理。modify工具的设计意图体现在其默认描述中见 Initialize 方法它是“在 apply 采取行动之前修改向量规格中列配置的途径”未显式指定的可选参数会使用针对具体工作负载优化的内部默认值。前置要求目标 PostgreSQL 数据库必须已安装vector_assist扩展并且vector_assist.modify_spec函数可用否则工具无法执行成功原文档明确要求从源码看工具要求绑定的 source 实现compatibleSource接口——即同时具备PostgresPool() *pgxpool.Pool与RunSQL(...)能力的 PostgreSQL 类数据源如cloud-sql-postgres、postgres源接口定义见 vectorassistmodifyspec.go校验逻辑在 ValidateSource 中完成。YAML 配置方式在 Toolbox 配置文件中按如下方式声明该工具type必须为vector-assist-modify-speckind: tool name: modify_spec type: vector-assist-modify-spec source: my-database-source description: This tool modifies an existing vector specification (identified by a required spec_id) with new parameters or overrides. Upon modification, it automatically recalculates and refreshes the list of generated SQL recommendations to match the updated requirements. Use this tool when a user wants to adjust or fine-tune the configuration of an already defined vector spec (such as changing the target recall, embedding model, or quantization) before actually executing the setup commands.配置字段参考对应Config结构体见 vectorassistmodifyspec.go字段类型必填说明typestring是必须为vector-assist-modify-spec用于匹配工具注册表sourcestring是SQL 应执行在其上的数据源名称必须为兼容的 PostgreSQL 类源descriptionstring否传递给 Agent 的工具描述缺省时使用内置默认描述此外还支持可选的annotations字段源码中Initialize会为该工具设置写操作标注tools.NewWriteAnnotations从实现上表明它属于“写”语义工具。完整参数表工具接受以下输入参数spec_id必填其余为可选覆盖项。参数与文档 Parameters 一节 保持一致并与源码中Initialize构造的参数清单第 79-97 行逐一对应参数类型说明必填spec_idstring要修改的向量规格的唯一 ID是table_namestring新的向量工作负载目标表名否schema_namestring包含目标表的新的 schema 名否vector_column_namestring存放向量嵌入的新列名否text_column_namestring用于向量检索的文本列新名否vector_index_typestring新的向量索引类型hnsw、ivfflat、scann否embeddings_availableboolean更新“表中是否已存在向量嵌入”否num_vectorsinteger更新预期的向量总数否dimensionalityinteger更新向量或嵌入模型的维度否embedding_modelstring更新用于生成嵌入的模型否prefilter_column_namesarray更新用于向量查询预过滤的列否distance_funcstring更新距离函数cosine、ip、l2、l1否quantizationstring更新量化方式none、halfvec、bit否memory_budget_kbinteger更新索引构建时的最大内存KB否target_recallfloat更新索引的目标召回率否target_top_kinteger更新每次检索返回的 Top-K 结果数否tune_vector_indexboolean更新是否需要自动调优索引否注意参数的必填/可选标注基于 vector assist 函数定义vector_assist.modify_spec函数还可能对可选参数做进一步校验以确保返回响应前必要数据齐备。各可选参数在源码中的精确描述可直接作为 Agent 调用时的语义依据vector_index_typeModify the type of the vector index to be created (Allowed inputs: hnsw, ivfflat, scann).distance_funcModify the distance function to be used for comparing vectors (Allowed inputs: cosine, ip, l2, l1).quantizationModify the quantization to be used for creating the vector indexes (Allowed inputs: none, halfvec, bit).源码级执行链路SQL 查询与命名参数工具的核心是一条命名参数查询modifySpecQuerySELECT recommendation_id, vector_spec_id, table_name, schema_name, query, recommendation, applied, modified, created_at FROM vector_assist.modify_spec(spec_id spec_id::TEXT, table_name table_name::TEXT, schema_name schema_name::TEXT, vector_column_name vector_column_name::TEXT, text_column_name text_column_name::TEXT, vector_index_type vector_index_type::TEXT, embeddings_available embeddings_available::BOOLEAN, num_vectors num_vectors::INTEGER, dimensionality dimensionality::INTEGER, embedding_model embedding_model::TEXT, prefilter_column_names prefilter_column_names, distance_func distance_func::TEXT, quantization quantization::TEXT, memory_budget_kb memory_budget_kb::INTEGER, target_recall target_recall::FLOAT, target_top_k target_top_k::INTEGER, tune_vector_index tune_vector_index::BOOLEAN);几点实现细节值得注意全量传参无论调用方提供了哪些覆盖项16 个参数除spec_id外的所有可选项加上spec_id都会以命名参数形式传入vector_assist.modify_spec未提供的参数在数据库端按 NULL/默认值语义处理返回重算结果查询直接返回刷新后的建议集字段包括recommendation_id、vector_spec_id、table_name、schema_name、query、recommendation、applied、modified、created_at——因此一次 modify 调用即可拿到“修改后的规格 最新 SQL 建议”的完整快照驱动层映射Invoke方法将解析后的参数转换为pgx.NamedArgs后交给source.RunSQL见 Invoke 方法。源码注释明确说明只要 source 的RunSQL将参数展开为pgx.Query(ctx, sql, args...)pgx 就会负责param命名参数的映射。这意味着调用方无需关心参数顺序prefilter_column_names数组也能由 pgx 正确展开。工具注册与配置解析init()将类型名vector-assist-modify-spec注册进全局工具注册表tools.Register若类型名冲突会直接 panic保证类型名全局唯一newConfig通过 YAML 解码器反序列化出Config内嵌tools.ConfigBase含name、description等公共字段单元测试 TestParseFromYaml 验证了典型 YAML 片段kind: tool / name / type / description / source能被正确解析为期望的Config结构即上文配置写法是经过测试确认的。默认描述当配置中未提供description时源码内置一段更完整的描述强调该工具“为在 apply 及采取行动之前修改向量规格中的列提供途径”并且“虽然高度可定制但未指定的可选参数将使用针对特定工作负载优化的内部默认值”建议用它来修改由define_spec建立的配置例如调整目标召回率、嵌入模型或量化设置vectorassistmodifyspec.go。典型使用示例假设你先用define_spec为documents表定义了规格spec_doc_search默认 hnsw 索引、cosine 距离现在希望改用 scann 索引并将目标召回率提高到 0.95。Agent 可调用该工具{ spec_id: spec_doc_search, vector_index_type: scann, target_recall: 0.95 }执行后vector_assist.modify_spec返回刷新后的建议行其中query/recommendation字段即按新参数重新生成的 SQL 建议如新的CREATE INDEX语句applied标记可帮助判断哪些建议已落地。在确认无误前这些建议仅是“待执行”状态——这正是 modify 位于 apply 之前的意义所在先迭代规格、预览建议再执行。适用前提与限制该工具仅对安装了vector_assist扩展的 PostgreSQL 数据库有效且vector_assist.modify_spec函数必须存在spec_id必填目标规格须由vector_assist.define_spec对应 vector-assist-define-spec 工具预先定义从源码结构看vector_index_typehnsw/ivfflat/scann、distance_funccosine/ip/l2/l1、quantizationnone/halfvec/bit的取值约束在参数描述中明确声明最终合法性由数据库端函数校验该工具属于 Cloud SQL for PostgreSQL 集成的一部分源连接配置项目、区域、实例、认证方式等参考 Cloud SQL for PostgreSQL 数据源文档。小结vector-assist-modify-spec是 mcp-toolbox 向量工作负载配置闭环中“定义—修改—应用”三段式里的关键一环它以spec_id为锚点接受 17 个参数的任意子集作为覆盖通过一条命名参数查询委托给数据库侧vector_assist.modify_spec函数完成重算并直接返回刷新后的 SQL 建议集。结合源码vectorassistmodifyspec.go、解析测试vectorassistmodifyspec_test.go与预置配置cloud-sql-postgres.yaml可以确认其配置写法、参数语义与执行链路均与官方文档一致是可放心接入 Agent 工作流的成熟工具。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考