企业官网建设流程全解析

Genkit Vertex AI 插件完全指南：Model Garden、Rerankers、Evaluation 与 Vector Search 实战

【免费下载链接】genkitOpen-source framework for building agentic apps in JavaScript, Go, Dart, and Python, built and used in production by Google项目地址: https://gitcode.com/GitHub_Trending/ge/genkit

本指南围绕 Genkit 官方仓库中的 js/plugins/vertexai/README.md 展开，系统讲解@genkit-ai/vertexai插件的四大子包能力：Model Garden 第三方模型接入、Rerankers 相关性重排、Evaluation 质量评估与 Vector Search 向量检索。读完本文，你将掌握该插件的安装方式、认证与配置细节、各子包的完整接入代码，以及底层源码实现原理，可直接在 JavaScript/TypeScript 项目中落地构建 RAG 与 Agent 应用。

一、插件概述与包结构

@genkit-ai/vertexai是 Genkit 官方提供的 Vertex AI 集成插件，将 Google Cloud Vertex AI 的核心生成式 AI 能力接入 Genkit 运行时，涵盖Model Garden（模型花园）、Rerankers（重排器）、Evaluation（评估）、Vector Search（向量搜索）四大能力。

从源码结构看，该插件以「主包 + 子包」的形式组织。package.json的exports字段（见 js/plugins/vertexai/package.json）定义了五个可导入入口，同时支持 CommonJS（require）与 ESM（import）两种模块格式：

插件依赖关系（package.json）也印证了各子包的底层实现：Anthropic 模型走@anthropic-ai/sdk与@anthropic-ai/vertex-sdk，Mistral 走@mistralai/mistralai-gcp，Llama 走 OpenAI 兼容协议（openai包），底层 API 调用统一使用google-auth-library完成认证；BigQuery 与 Firestore 文档存储则分别依赖可选的@google-cloud/bigquery与firebase-admin。

二、安装与前置条件

2.1 安装插件

npm i --save @genkit-ai/vertexai

安装后，根据所需能力从对应的子包路径导入。由于插件以genkit作为 peerDependency（见 package.json），使用前需确保项目中已安装genkit核心包。

2.2 认证与项目配置

所有子包共享同一套「公共插件选项」，定义在 src/common/types.ts：

• projectId?: string：要调用的 Google Cloud 项目 ID，可选；
• location: string：Google Cloud 区域（必填）；
• googleAuth?: GoogleAuthOptions：自定义认证配置（来自google-auth-library）；
• experimental_debugTraces?: boolean：启用额外的调试追踪（如原始模型 API 调用详情）。

值得注意的是，虽然类型定义中location标为必填，但源码对缺省场景做了兜底。在 src/common/utils.ts 的getDerivedOptions实现中，配置解析遵循以下优先级：

1. projectId：优先取options.projectId，其次读取环境变量GCLOUD_PROJECT，最后尝试从FIREBASE_CONFIG环境变量中解析项目 ID；
2. location：缺省时回退为us-central1；
3. 认证：若设置环境变量GCLOUD_SERVICE_ACCOUNT_CREDS（内容为服务账号 JSON），则用其构造GoogleAuth客户端；否则使用应用默认凭据（ADC），并统一以CLOUD_PLATFORM_OAUTH_SCOPE作为 OAuth 作用域。

# 方式一：环境变量（推荐用于无 `location`/`projectId` 显式传入的场景） export GCLOUD_PROJECT=my-project export GCLOUD_LOCATION=us-central1 # 方式二：服务账号凭据 export GCLOUD_SERVICE_ACCOUNT_CREDS='{"type": "service_account", ...}'

若解析后仍缺少location或projectId，插件会抛出带插件名的明确错误提示（src/common/utils.ts）。

三、Model Garden：接入 Claude / Mistral / Llama 第三方模型

Vertex AI Model Garden 允许在一个平台上托管并调用第三方大模型。@genkit-ai/vertexai/modelgarden子包将这些模型封装为标准的 Genkit 模型引用，可直接用于ai.generate()。

3.1 基本用法

import { genkit } from 'genkit'; import { vertexModelGarden } from '@genkit-ai/vertexai/modelgarden'; const ai = genkit({ plugins: [ vertexModelGarden({ projectId: 'my-project', location: 'us-central1' }), ], }); const { text } = await ai.generate({ model: vertexModelGarden.model('claude-sonnet-4'), prompt: 'Write a haiku about cloud computing', }); console.log(text);

3.2 源码实现原理

从源码看，Model Garden 子包同时保留了 legacy 与新版（v2）两套实现（src/modelgarden/index.ts）：legacy 侧导出vertexAIModelGarden以及claude35Sonnet、claude3Opus、llama3、mistralLarge等预定义模型引用；新版vertexModelGarden则采用genkitPluginV2的动态解析机制（src/modelgarden/v2/index.ts）。

在 v2 实现中，插件通过initializer预先枚举 Anthropic、Mistral、Llama 三家的已知模型清单，resolver则根据 action 名称按前缀路由到对应的defineModel实现（src/modelgarden/v2/index.ts）。而vertexModelGarden.model()会在传入不认识的模型名时抛出INVALID_ARGUMENT状态的GenkitError（src/modelgarden/v2/index.ts），避免静默失败。

各家的已知模型与配置模式可从对应源码确认：

• Anthropic（src/modelgarden/v2/anthropic.ts）：KNOWN_MODELS收录了claude-sonnet-5、claude-fable-5、claude-opus-4-8、claude-haiku-4-5@20251001、claude-sonnet-4@20250514等带版本时间戳的模型标识。其配置模式（AnthropicConfigSchema）额外支持thinking（思考模式：enabled、budgetTokens（须为不小于 1024 的整数）、adaptive、display）与output_config.effort（low/medium/high/xhigh），并校验enabled与adaptive不能同时开启（src/modelgarden/v2/anthropic.ts）。默认能力声明支持多轮对话、媒体、工具调用与 system role；
• Mistral（src/modelgarden/v2/mistral.ts）：配置在GenerationCommonConfigSchema基础上扩展location与topP（默认值 1），通过@mistralai/mistralai-gcp调用；
• Llama（src/modelgarden/v2/llama.ts）：走 OpenAI 兼容协议，扩展location，默认声明输出支持text与json两种格式。

若 Model Garden 中部署了KNOWN_MODELS之外的模型，可通过PluginOptions中的models字段注入自定义ModelReference，或使用openAiBaseUrlTemplate模板（见 src/modelgarden/v2/types.ts）。

四、Rerankers：按相关性重排检索结果

Rerankers（重排器）用于对候选文档按语义相关性重新排序，是提升 RAG 检索精度的关键环节。

4.1 基本用法

import { genkit } from 'genkit'; import { vertexRerankers } from '@genkit-ai/vertexai/rerankers'; const ai = genkit({ plugins: [ vertexRerankers({ projectId: 'my-project', location: 'us-central1' }), ], });

插件初始化后，可通过vertexRerankers.reranker(name, config)获取具体的重排器引用（src/rerankers/v2/index.ts），resolver只在 action 类型为reranker且模型名以semantic-ranker-开头时才响应。

4.2 已知模型与配置参数

已知模型清单定义在 src/rerankers/v2/reranker.ts，包括：

重排器配置（VertexRerankerConfigSchema，见 src/rerankers/v2/reranker.ts）支持三个可选参数：

• topN?: number：返回的前 N 个最相关文档数量；
• ignoreRecordDetailsInResponse?: boolean：为true时响应仅包含记录 ID 与分数（默认false，返回完整记录详情）；
• location?: string：重排模型所在的 Google Cloud 区域，例如"us-central1"。

4.3 底层调用链

vertexRerankers插件会将请求转发到 Vertex AI Ranking 服务。从 src/rerankers/v2/client.ts 的实现可见，其请求 URL 为：

https://discoveryengine.googleapis.com/v1/projects/{projectId}/locations/{location}/rankingConfigs/default_ranking_config:rank

请求头携带Authorization: Bearer <token>与x-goog-user-project: <projectId>，默认区域同样是us-central1。认证失败时，插件会提示开发者根据运行环境使用gcloud auth login等本地认证方式（src/rerankers/v2/client.ts）。由于该子包走的是 Discovery Engine 的 HTTP 接口而非生成式 AI 端点，因此与 Model Garden 等子包的请求路径是相互独立的。

五、Evaluation：内置质量评估指标

@genkit-ai/vertexai/evaluation子包将 Vertex AI 的托管评估能力封装为 Genkit 的 evaluator 动作，可直接接入 Genkit 的评测工作流。

5.1 基本用法

import { vertexAIEvaluation } from '@genkit-ai/vertexai/evaluation'; import { VertexAIEvaluationMetricType } from '@genkit-ai/vertexai/evaluation'; const ai = genkit({ plugins: [ vertexAIEvaluation({ projectId: 'my-project', location: 'us-central1', metrics: [ VertexAIEvaluationMetricType.BLEU, VertexAIEvaluationMetricType.ROUGE, VertexAIEvaluationMetricType.SAFETY, VertexAIEvaluationMetricType.GROUNDEDNESS, ], }), ], });

5.2 指标清单

VertexAIEvaluationMetricType枚举定义在 src/evaluation/types.ts，共 8 个指标：

5.3 进阶：metricSpec 自定义

metrics数组的每一项既可以是一个枚举值，也可以是一个带metricSpec的配置对象（VertexAIEvaluationMetricConfig，见 src/evaluation/types.ts）。metricSpec会原样透传给 Vertex AI 评估 API，其类型与各指标的官方*Spec（如IBleuSpec、IRougeSpec、IFluencySpec、ISafetySpec、IGroundednessSpec、ISummarizationQualitySpec等）一一对应，可参考 Vertex AI 官方评估参数文档按需定制各指标的阈值与配置。

在实现层面，插件启动时通过vertexEvaluators()将每个指标映射为独立的 evaluator 动作（src/evaluation/evaluation.ts），例如BLEU对应createBleuEvaluator、ROUGE对应createRougeEvaluator，响应体也会按指标类型做独立的 Zod 结构校验（如bleuResults、rougeResults等字段），保证返回数据的类型安全。

六、Vector Search：构建 BigQuery / Firestore 双后端 RAG

@genkit-ai/vertexai/vectorsearch子包将 Vertex AI Vector Search 与 Genkit 的检索抽象结合，支持 BigQuery 与 Firestore 两种文档存储后端，适合构建生产级 RAG 应用。

6.1 基本用法

import { vertexAIVectorSearch } from '@genkit-ai/vertexai/vectorsearch'; const ai = genkit({ plugins: [ vertexAIVectorSearch({ projectId: 'my-project', location: 'us-central1', vectorSearchOptions: [ { publicDomainName: 'my-public-endpoint.vdb.vertexai.goog', indexEndpointId: 'my-index-endpoint-id', indexId: 'my-index-id', deployedIndexId: 'my-deployed-index-id', documentRetriever: myDocRetriever, documentIndexer: myDocIndexer, embedder: myEmbedder, }, ], }), ], });

6.2 配置项详解

vectorSearchOptions中的每一项对应一个向量索引配置，其完整字段定义在 src/vectorsearch/vector_search/types.ts：

插件级还有一个可选的embedder?: EmbedderReference字段（见 src/vectorsearch/types.ts），可作为所有向量索引的默认 embedder 兜底。

6.3 索引与检索动作

插件在vectorSearchOptions非空时，会为每一项动态注册 indexer 与 retriever 动作（src/vectorsearch/index.ts）：

• Indexer：动作名形如vertexai/${indexId}，通过vertexAiIndexerRef({ indexId })获取引用，将文档经 embedder 转为向量后，通过upsertDatapoints写入向量索引（src/vectorsearch/vector_search/indexers.ts）；
• Retriever：同样以vertexai/${indexId}命名，查询时先对 query 做 embedding，再调用queryPublicEndpoint向公共端点发起FindNeighbors请求，最后交给documentRetriever还原为完整文档；默认返回k=10个近邻（src/vectorsearch/vector_search/retrievers.ts）。

6.4 元数据过滤与数值限制

向量数据点（IndexDatapoint）支持携带丰富的过滤元数据，相关 Zod 模式定义在 src/vectorsearch/vector_search/types.ts：

• restricts（字符串限制）：{ namespace, allowList, denyList }，例如按颜色、类别做白名单/黑名单过滤；
• numericRestricts（数值限制）：{ namespace, valueInt | valueFloat | valueDouble, op }，op支持LESS、LESS_EQUAL、EQUAL、GREATER_EQUAL、GREATER、NOT_EQUAL及OPERATOR_UNSPECIFIED（src/vectorsearch/vector_search/types.ts）；
• crowdingTag：拥挤标签，用于控制结果多样性。

结合 src/vectorsearch/index.ts 内嵌的完整示例：索引阶段用ai.index({ indexer: vertexAiIndexerRef(...), [doc] })写入带restricts/numericRestricts的文档；查询阶段构造带过滤条件的 query 文档后调用ai.retrieve({ retriever: vertexAIRetrieverRef(...), query, options: { k } })，即可实现「带元数据约束的语义检索」。

6.5 BigQuery 与 Firestore 后端

子包从 src/vectorsearch/vector_search/index.ts 导出了开箱即用的存储后端实现：

• BigQuery：getBigQueryDocumentRetriever(bq, tableId, datasetId)通过SELECT * FROM \${datasetId}.${tableId}` WHERE id IN UNNEST(@ids)按 datapointId 批量回查文档，并解析content/metadata的 JSON 字段（[src/vectorsearch/vector_search/bigquery.ts](https://link.gitcode.com/i/e17a095e9ab36f58ac546ccb1314c7cb)）；同时提供getBigQueryDocumentIndexer`；
• Firestore：getFirestoreDocumentRetriever与getFirestoreDocumentIndexer则基于firebase-admin实现文档存取。

七、弃用说明：主入口迁移到 @genkit-ai/google-genai

README 明确标注：主入口vertexAI插件导出（Gemini、Imagen 与 embedder 模型）已弃用（deprecated），官方要求迁移到@genkit-ai/google-genai：

// Before (deprecated) import { vertexAI } from '@genkit-ai/vertexai'; // After import { vertexAI } from '@genkit-ai/google-genai';

从源码看，src/index.ts 仍保留了gemini15Pro、gemini25FlashPreview0417、gemini25ProExp0325等 Gemini 模型引用、imagen2/imagen3/imagen3Fast文生图模型，以及textEmbedding004、textEmbedding005、multimodalEmbedding001等 embedding 模型，但这些属于遗留能力。本文重点介绍的四个子包（modelgarden、rerankers、evaluation、vectorsearch）不受弃用影响，可放心使用。

八、测试与验证

插件仓库内置了覆盖各子包的测试用例（js/plugins/vertexai/tests），可作为实现行为的可执行佐证：

• Model Garden：modelgarden/v2/anthropic_test.ts、llama_test.ts、mistral_test.ts、index_test.ts；
• Rerankers：rerankers/v2/client_test.ts、reranker_test.ts、index_test.ts；
• Vector Search：vectorsearch/bigquery_test.ts、query_public_endpoint_test.ts、upsert_datapoints_test.ts、utils_test.ts；
• 主插件：plugin_test.ts、gemini_test.ts、上下文缓存context-caching/utils_test.ts。

在本地运行测试：

cd js/plugins/vertexai npm test

（脚本定义于 package.json，通过tsx --test执行./tests/**/*_test.ts。）

九、小结

@genkit-ai/vertexai插件的四个子包分别回答了 Agent/RAG 应用构建中的四类核心问题：Model Garden 让 Genkit 应用能以统一接口调用 Claude、Mistral、Llama 等第三方模型；Rerankers 在检索后做相关性精排；Evaluation 提供 BLEU、ROUGE、SAFETY 等托管指标衡量输出质量；Vector Search 则打通了从文档索引、向量检索到元数据过滤的完整 RAG 链路。所有子包共享一致的认证与项目配置体系，并遵循 Genkit 的插件与动作抽象，接入成本低、可组合性强。

如需深入了解各子包的完整源码，可继续阅读 src/modelgarden/v2、src/rerankers/v2、src/evaluation 与 src/vectorsearch/vector_search 目录下的实现与测试文件。插件遵循 Apache 2.0 许可（见 js/plugins/vertexai/LICENSE），其问题反馈与后续迭代均发生在 Genkit 主仓库中。

【免费下载链接】genkitOpen-source framework for building agentic apps in JavaScript, Go, Dart, and Python, built and used in production by Google项目地址: https://gitcode.com/GitHub_Trending/ge/genkit