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

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定义了五个可导入入口同时支持 CommonJSrequire与 ESMimport两种模块格式Import 路径能力说明genkit-ai/vertexai主入口已弃用的 Gemini / Imagen / Embedder 模型集成见弃用说明genkit-ai/vertexai/modelgarden通过 Vertex AI Model Garden 访问第三方模型Anthropic Claude、Mistral、Llamagenkit-ai/vertexai/rerankersVertex AI Rerankers API按相关性重排文档genkit-ai/vertexai/evaluationVertex AI 内置评估指标BLEU、ROUGE、SAFETY、GROUNDEDNESS 等genkit-ai/vertexai/vectorsearchVertex AI Vector Search支持 BigQuery 与 Firestore 两种文档存储后端插件依赖关系package.json也印证了各子包的底层实现Anthropic 模型走anthropic-ai/sdk与anthropic-ai/vertex-sdkMistral 走mistralai/mistralai-gcpLlama 走 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.tsprojectId?: string要调用的 Google Cloud 项目 ID可选location: stringGoogle Cloud 区域必填googleAuth?: GoogleAuthOptions自定义认证配置来自google-auth-libraryexperimental_debugTraces?: boolean启用额外的调试追踪如原始模型 API 调用详情。值得注意的是虽然类型定义中location标为必填但源码对缺省场景做了兜底。在 src/common/utils.ts 的getDerivedOptions实现中配置解析遵循以下优先级projectId优先取options.projectId其次读取环境变量GCLOUD_PROJECT最后尝试从FIREBASE_CONFIG环境变量中解析项目 IDlocation缺省时回退为us-central1认证若设置环境变量GCLOUD_SERVICE_ACCOUNT_CREDS内容为服务账号 JSON则用其构造GoogleAuth客户端否则使用应用默认凭据ADC并统一以CLOUD_PLATFORM_OAUTH_SCOPE作为 OAuth 作用域。# 方式一环境变量推荐用于无 location/projectId 显式传入的场景 export GCLOUD_PROJECTmy-project export GCLOUD_LOCATIONus-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.tslegacy 侧导出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状态的GenkitErrorsrc/modelgarden/v2/index.ts避免静默失败。各家的已知模型与配置模式可从对应源码确认Anthropicsrc/modelgarden/v2/anthropic.tsKNOWN_MODELS收录了claude-sonnet-5、claude-fable-5、claude-opus-4-8、claude-haiku-4-520251001、claude-sonnet-420250514等带版本时间戳的模型标识。其配置模式AnthropicConfigSchema额外支持thinking思考模式enabled、budgetTokens须为不小于 1024 的整数、adaptive、display与output_config.effortlow/medium/high/xhigh并校验enabled与adaptive不能同时开启src/modelgarden/v2/anthropic.ts。默认能力声明支持多轮对话、媒体、工具调用与 system roleMistralsrc/modelgarden/v2/mistral.ts配置在GenerationCommonConfigSchema基础上扩展location与topP默认值 1通过mistralai/mistralai-gcp调用Llamasrc/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.tsresolver只在 action 类型为reranker且模型名以semantic-ranker-开头时才响应。4.2 已知模型与配置参数已知模型清单定义在 src/rerankers/v2/reranker.ts包括模型标识说明semantic-ranker-defaultlatest默认版本常量DEFAULT_MODEL_NAME指向它semantic-ranker-default-004稳定版本 004semantic-ranker-fast-004快速版 004semantic-ranker-default-003/-002更早的稳定版本重排器配置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 个指标枚举值评估维度BLEU基于 n-gram 重叠的机器翻译质量指标ROUGE面向摘要的召回率导向指标FLUENCY输出流畅度SAFETY输出安全性GROUNDEDNESS输出与给定上下文的事实一致性接地性SUMMARIZATION_QUALITY摘要质量SUMMARIZATION_HELPFULNESS摘要有用性SUMMARIZATION_VERBOSITY摘要冗长度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 双后端 RAGgenkit-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字段必填说明deployedIndexId是已部署的 Vertex AI Index 部署 IDindexEndpointId是Index Endpoint 的 IDpublicDomainName是公共端点域名形如*.vdb.vertexai.goog用于查询公共端点indexId是Vertex AI Index 的 IDdocumentRetriever是文档检索函数将Neighbor[]含datapointId、distance等解析为Document[]documentIndexer是文档索引函数接收Document[]写入自选数据库并返回文档 ID 列表。注意仅支持 Streaming Update Indexersembedder否Embedder 引用未提供时回退到插件级embedder选项embedderOptions否传给 embedder 的默认选项插件级还有一个可选的embedder?: EmbedderReference字段见 src/vectorsearch/types.ts可作为所有向量索引的默认 embedder 兜底。6.3 索引与检索动作插件在vectorSearchOptions非空时会为每一项动态注册 indexer 与 retriever 动作src/vectorsearch/index.tsIndexer动作名形如vertexai/${indexId}通过vertexAiIndexerRef({ indexId })获取引用将文档经 embedder 转为向量后通过upsertDatapoints写入向量索引src/vectorsearch/vector_search/indexers.tsRetriever同样以vertexai/${indexId}命名查询时先对 query 做 embedding再调用queryPublicEndpoint向公共端点发起FindNeighbors请求最后交给documentRetriever还原为完整文档默认返回k10个近邻src/vectorsearch/vector_search/retrievers.ts。6.4 元数据过滤与数值限制向量数据点IndexDatapoint支持携带丰富的过滤元数据相关 Zod 模式定义在 src/vectorsearch/vector_search/types.tsrestricts字符串限制{ namespace, allowList, denyList }例如按颜色、类别做白名单/黑名单过滤numericRestricts数值限制{ namespace, valueInt | valueFloat | valueDouble, op }op支持LESS、LESS_EQUAL、EQUAL、GREATER_EQUAL、GREATER、NOT_EQUAL及OPERATOR_UNSPECIFIEDsrc/vectorsearch/vector_search/types.tscrowdingTag拥挤标签用于控制结果多样性。结合 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 导出了开箱即用的存储后端实现BigQuerygetBigQueryDocumentRetriever(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)同时提供getBigQueryDocumentIndexerFirestoregetFirestoreDocumentRetriever与getFirestoreDocumentIndexer则基于firebase-admin实现文档存取。七、弃用说明主入口迁移到 genkit-ai/google-genaiREADME 明确标注主入口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 Gardenmodelgarden/v2/anthropic_test.ts、llama_test.ts、mistral_test.ts、index_test.tsRerankersrerankers/v2/client_test.ts、reranker_test.ts、index_test.tsVector Searchvectorsearch/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考