MCP Toolbox 集成 Gemini Embedding：为数据库工具配置文本向量化-开发者社区

MCP Toolbox 集成 Gemini Embedding：为数据库工具配置文本向量化

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

本篇技术指南讲解如何在 MCP Toolbox for Databases（下称 Toolbox）中配置 Google Gemini 嵌入模型，将客户端传入的原始文本自动转换为高维数值向量，并注入 PostgreSQL、ClickHouse 等数据库工具的参数，从而为向量检索与相似度查询提供基础能力。读完本文，你将掌握 Gemini Embedding 的两种认证模式、kind: embeddingModel配置项的完整语义、embeddedBy参数挂载方式，以及背后的批处理调用与向量格式化原理。

关于 Gemini Embedding

Google Gemini 提供了业界领先的文本嵌入模型，能够把自然语言文本转换为高维浮点向量（embedding），这是语义搜索、RAG（检索增强生成）与向量数据库写入的关键一步。在 Toolbox 中，嵌入模型被建模为一种独立的"原语配置"（primitive config），通过kind: embeddingModel在 YAML 配置文件中声明，并可在任意工具的字符串参数上通过embeddedBy字段按名称引用。

从源码结构看，当前仓库的嵌入模型实现位于 internal/embeddingmodels 目录，其中gemini子包是唯一的现成实现，核心代码见 gemini.go。它依赖 Google 官方google.golang.org/genaiSDK 完成底层 API 调用，因此并不局限于某一种数据库，任何接入 Toolbox 的数据源都能复用同一套向量化能力。

认证模式

Toolbox 的 Gemini Embedding 支持两种认证模式，二者由配置字段与对应的环境变量共同决定，具体解析逻辑在Config.Initialize()中实现（gemini.go）：

模式	触发条件	认证方式	底层后端
Google AI（API Key）	配置了`apiKey`，或设置了`GOOGLE_API_KEY`/`GEMINI_API_KEY`环境变量	API Key	Google AI Studio（Gemini API）
Vertex AI（ADC）	同时配置了`project`与`location`，或设置了`GOOGLE_CLOUD_PROJECT`/`GOOGLE_CLOUD_LOCATION`环境变量	Application Default Credentials（ADC）	Vertex AI

推荐策略：快速测试用 API Key，生产环境用 Vertex AI + ADC。API Key 可以从 Google AI Studio 的控制台申请；ADC 则是 Google Cloud 推荐的服务身份认证方式，适合在运行于 Google Cloud 或已配置工作负载身份的环境中安全使用。

值得注意的细节是，两种模式并非互斥的"开关"，而是按优先级动态判定。从 gemini.go 的初始化逻辑可以看到：

若project与location均非空（无论来自 YAML 还是环境变量），走Vertex AI后端；
否则若apiKey非空，走Google AI（Gemini API）后端；
两者皆缺失则直接报错退出，错误信息会同时提示两种模式的补齐方式。

也就是说，即使同时配置了apiKey和project/location，project+location也会优先命中 Vertex AI。环境变量仅作为兜底：配置字段为空时才读取对应的环境变量（apiKey→GOOGLE_API_KEY→GEMINI_API_KEY；project→GOOGLE_CLOUD_PROJECT；location→GOOGLE_CLOUD_LOCATION）。

工作行为：自动向量化与维度匹配

自动向量化（Automatic Vectorization）

当某个工具参数通过embeddedBy: <your-gemini-model-name>引用嵌入模型时，Toolbox 会在工具真正执行前拦截客户端传来的原始文本输入，将其批量发送到 Gemini API，把返回的数值数组按目标数据库的格式要求格式化后，再作为参数值传给数据库 source。

这一过程的底层实现在 parameters.go 的EmbedParams函数中，关键机制如下：

按模型分组批处理：所有声明了同一嵌入模型的参数会被聚合为一次批量请求（stringBatch），而不是逐条调用，有效降低 API 调用次数与延迟；
输入必须是字符串：只有type: string的参数才能挂载embeddedBy，如果被标记参数的运行值不是字符串，会直接返回parameter ... is marked for embedding but has a non-string value错误；
输出数量校验：模型返回的向量数量必须与输入文本数量一致，否则报错，防止静默错位；
向量格式化：原始[]float32向量会经过VectorFormatter转换为目标数据库可接受的形态（见下文"向量格式化"小节）。

此外，从 parameters.go 的ParseParameter可以看到，integer、float、boolean、array、map类型的参数若声明了embeddedBy会直接被拒绝——向量化仅面向字符串参数，这是配置期的强约束而非运行时约定。

维度匹配（Dimension Matching）

嵌入模型输出的向量维度必须与数据库列定义一致，例如 PostgreSQL 的vector(768)列要求向量长度为 768。因此 Toolbox 提供了可选的dimension字段用于显式指定输出维度。

在 gemini.go 的EmbedParameters实现中，只有当dimension大于 0 时才会把该值作为OutputDimensionality传给 Gemini API；不配置则使用模型默认维度。需要特别注意的限制：

dimension只被2024 年之后发布的较新模型支持；
使用早期模型models/embedding-001时不能设置该字段；
具体某个模型支持哪些维度，以官方"可用 Gemini 模型"列表为准（可查阅 Vertex AI 文档中 get-text-embeddings 的 supported models 说明）。

任务类型（Task Type）

从源码可以看到，每次嵌入请求都会固定携带TaskType: "SEMANTIC_SIMILARITY"（gemini.go）。这是 Google 嵌入 API 支持的任务类型之一，用于让模型针对语义相似度场景优化向量质量，适用于向量检索、相似度排序等典型用途。

配置示例

使用 Google AI（API Key）

Google AI 模式使用 API Key 认证。API Key 从 Google AI Studio 申请后，可以安全地通过环境变量注入：

kind: embeddingModel name: gemini-model type: gemini model: gemini-embedding-001 apiKey: ${GOOGLE_API_KEY} dimension: 768

使用 Vertex AI（ADC）

Vertex AI 模式使用 ADC 认证，需要事先在目标环境完成 ADC 的配置（例如通过gcloud auth application-default login或服务账号）：

kind: embeddingModel name: gemini-model type: gemini model: gemini-embedding-001 project: ${GOOGLE_CLOUD_PROJECT} location: us-central1 dimension: 768

安全建议：请使用${ENV_NAME}形式的环境变量替换来引用密钥，避免把凭据硬编码进配置文件。Toolbox 会在加载配置时自动完成替换。

上面两个示例均被 gemini_test.go 的单元测试覆盖：测试分别验证了"仅含基础字段"、"Google AI 全字段（apiKey + dimension）"、"Vertex AI 全字段（project + location + dimension）"三种 YAML 的解析结果，其中dimension: 768与dimension: 512均被正确解析为Config.Dimension。

配置字段参考

原文档给出了完整的字段语义，结合 gemini.go 中Config结构体的定义，各字段说明如下：

字段	类型	必填	说明
`type`	string	是	必须为`gemini`，用于路由到 gemini 嵌入模型实现（对应源码常量`EmbeddingModelType`）
`name`	string	是	嵌入模型的唯一名称，供工具参数的`embeddedBy`引用（源码中带`required`校验标签）
`model`	string	是	Gemini 模型 ID，如`gemini-embedding-001`（源码中带`required`校验标签）
`apiKey`	string	否	Google AI 模式的 API Key；留空时依次回退到`GOOGLE_API_KEY`、`GEMINI_API_KEY`环境变量
`project`	string	否	Vertex AI 项目 ID；留空时回退到`GOOGLE_CLOUD_PROJECT`环境变量
`location`	string	否	Vertex AI 区域，如`us-central1`；留空时回退到`GOOGLE_CLOUD_LOCATION`环境变量
`dimension`	integer	否	输出向量维度（如`768`），须与数据库列维度一致；仅较新模型支持，`models/embedding-001`不可设置

字段校验是严格模式：从 gemini_test.go 的失败用例可以看到，缺失必填的model字段会报Field validation for 'Model' failed on the 'required' tag，配置文件中出现未知字段（如invalid_param）也会被[1:1] unknown field拒绝，而同时缺失两套凭据时初始化会以明确的错误信息失败。因此建议在写配置时保持字段名拼写精确。

把嵌入模型接入数据库工具

kind: embeddingModel只是声明了向量化能力，要让它在真实工具中生效，还需要在工具参数上挂载它。以下示例取自 ClickHouse 工具配置的单元测试（clickhousesql_test.go）：

kind: tool name: vector_insert type: clickhouse-sql source: my-instance description: Stores content and its vector embedding. statement: INSERT INTO docs (content, embedding) VALUES (?, ?) parameters: - name: content type: string description: The text content to store. - name: text_to_embed type: string description: The text content used to generate the vector. embeddedBy: gemini-model valueFromParam: content

这里的embeddedBy: gemini-model引用了上文声明的嵌入模型名称，valueFromParam: content则指示 Toolbox 把content参数的实际值作为该参数的取值来源——即客户端只传一个content，Toolbox 会自动为它生成向量并绑定到 SQL 的第二个占位符。对于 PostgreSQL 等数据源，写法完全相同，只需把statement改为INSERT INTO docs (content, embedding) VALUES ($1, $2)之类的目标方言。

底层调用链

一次带向量化的工具调用会依次经过：

参数解析：parameters.go 的ParseParams先把客户端 JSON 参数解析为有序的ParamValues；
向量化入口：各工具实现EmbedParams方法并调用 parameters.go 的EmbedParams，例如 PostgreSQL 的 postgressql.go 与 ClickHouse 的 clickhousesql.go；
模型调用：EmbedParameters通过genai客户端调用Client.Models.EmbedContent（gemini.go），携带SEMANTIC_SIMILARITY任务类型与可选的OutputDimensionality；
结果注入：向量经格式化后写回对应参数槽位，随 SQL 一起下发到数据库。

同时，HTTP 层（api.go）以及 MCP 各协议版本（v20241105、v20250326、v20250618、v20251125、v20260728的 method.go）都会在调用工具前统一触发tool.EmbedParams，保证 REST 与 MCP 通道行为一致。

向量格式化：适配不同数据库

不同数据库接收向量的方式不同，Toolbox 通过VectorFormatter函数类型（embeddingmodels.go）解耦了这一差异，目前已内置两种格式化器：

PostgreSQL / SingleStore（pgvector 风格）：FormatVectorForPgvector把[]float32序列化为字符串字面量'[x, y, z]'，可直接用于 pgvector 的vector类型列；
ClickHouse：FormatVectorForClickHouse直接返回原始[]float32切片，由 clickhouse-go 驱动原生绑定为Array(Float32)参数。

如果某个工具没有显式传入 formatter（如 ArcadeDB 的 execute 类工具），则原始[]float32会直接作为参数值透传。这意味着：同样的 Gemini 嵌入模型，写入 pgvector 列时得到'[...]'字符串，写入 ClickHouse 时得到浮点数组，无需为不同数据库重复配置模型。

小结与注意事项

认证二选一：快速验证用apiKey（Google AI），生产环境优先project+location（Vertex AI + ADC）；两者都没有时会初始化失败，日志会给出补齐指引。
维度对齐：dimension必须与数据库列（如vector(768)）严格一致，且只适用于 2024 年后的新模型，models/embedding-001不可设置。
仅字符串参数可向量化：embeddedBy只能挂在string类型参数上，其他类型在配置期即被拒绝。
配置校验严格：type、name、model为必填，未知字段、缺失必填项都会在加载配置时直接报错（参见 gemini_test.go 的解析测试）。
凭据安全：统一使用${ENV_NAME}环境变量替换，避免在 YAML 中明文保存密钥。