使用 Vertex AI Vector Search 与 Firestore 构建 Genkit 文档索引与检索（RAG）实战-北京尧图网络

使用 Vertex AI Vector Search 与 Firestore 构建 Genkit 文档索引与检索RAG实战【免费下载链接】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/testapps/vertexai-vector-search-firestore深入讲解如何将 Vertex AI Vector Search向量检索与 Cloud Firestore文档内容与元数据存储结合通过 Genkit 的索引器Indexer与检索器Retriever机制搭建一条完整的 RAG检索增强生成数据管线。读完本文你将掌握从部署 Vertex AI Vector Search 索引、配置环境变量到用 Genkit 定义indexFlow与queryFlow两个流程并最终用genkit start启动服务进行索引与检索的完整闭环同时理解底层genkit-ai/vertexai/vectorsearch插件的实现原理。前置条件Prerequisites运行本示例前需要确认以下基础环境与云端资源就绪Node.js本示例使用 TypeScript 编写需要 Node.js 环境。PNPM仓库使用 pnpm workspace 管理依赖本示例依赖workspace:*协议因此必须使用 PNPM 安装。Vertex AI Vector Search 已部署的索引Index与索引端点Index Endpoint向量索引需先通过 Google Cloud Console 或gcloud命令行完成创建、部署并获取对应的公共域名与各类 ID。Firestore 实例用于持久化存储文档内容与元数据作为“文档仓库”document store同时需要 Google Cloud 服务账号的凭据文件。此外示例源码在 src/index.ts 中会对全部环境变量做一次性校验任一变量缺失都会抛出Missing environment variables. Please check your .env file.因此环境变量配置是整个示例能否启动的前提。快速开始Getting Started第一步克隆仓库并安装依赖Genkit 仓库采用 pnpm workspace 结构示例通过workspace:*引用核心包如genkit、genkit-ai/vertexai因此必须先让这些包可被解析cd js/testapps/vertexai-vector-search-firestore pnpm i执行前请先按照仓库根目录 README.md 的指引构建核心包。示例的依赖清单可在 package.json 中查看其中genkit-ai/vertexai与firebase-admin是本节的两个关键运行时依赖。第二步配置环境变量确保你已经在 Vertex AI Vector Search 中部署好了索引。在示例根目录创建.env文件并设置以下变量可参照仓库中的.env.examplePROJECT_IDyour-google-cloud-project-id LOCATIONyour-vertex-ai-location FIRESTORE_COLLECTIONyour_firestore_collection_here VECTOR_SEARCH_PUBLIC_DOMAIN_NAMEyour-vector-search-public-domain-name VECTOR_SEARCH_INDEX_ENDPOINT_IDyour-index-endpoint-id VECTOR_SEARCH_INDEX_IDyour-index-id VECTOR_SEARCH_DEPLOYED_INDEX_IDyour-deployed-index-id GOOGLE_APPLICATION_CREDENTIALSpath-to-your-service-account-key.json这些变量在 src/config.ts 中通过dotenv加载逐项导出为常量供业务代码使用。各变量含义变量用途PROJECT_IDGoogle Cloud 项目 ID用于初始化 Firebase 与 Vertex AI 客户端LOCATIONVertex AI 区域如us-central1FIRESTORE_COLLECTION存储文档内容与元数据的 Firestore 集合名VECTOR_SEARCH_PUBLIC_DOMAIN_NAME索引端点Index Endpoint的公共访问域名形如xxx.vdb.vertexai.googVECTOR_SEARCH_INDEX_ENDPOINT_ID索引端点 IDVECTOR_SEARCH_INDEX_ID向量索引 IDVECTOR_SEARCH_DEPLOYED_INDEX_ID已部署索引Deployed IndexIDGOOGLE_APPLICATION_CREDENTIALS服务账号密钥 JSON 文件路径用于认证 Google Cloud API第三步运行示例启动 Genkit 服务器注册并暴露两个流程genkit start开发模式下也可以使用 package.json 中预设的脚本pnpm genkit:dev内部执行genkit start -- tsx --watch src/index.ts或直接以pnpm devtsx --watch src/index.ts运行。示例总体结构Overview本示例演示了如何自定义“文档索引器”与“文档检索器”将 Cloud Firestore 作为文档存储后端并与 Vertex AI 深度集成实现文档的索引与检索。核心组件包括Firestore Document Indexer把文档写入 Firestore 集合并返回生成的文档 IDFirestore Document Retriever根据邻居NeighborID 从 Firestore 集合中读取文档Genkit 配置将 Vertex AI 插件与 Vector Search 插件接入 Genkit配置项目、区域与向量搜索索引选项索引流程Indexing FlowindexFlow将文本输入转换为文档并写入索引查询流程Query FlowqueryFlow根据查询检索文档并按距离排序返回结果。整个数据链路为文本 → Embeddingtext-embedding-004→ Vertex AI Vector Search向量相似度计算→ Firestore回源取回原始文档其中向量索引负责“相似度检索”Firestore 负责“内容存储”二者通过 datapoint ID 关联。Firestore Document Indexer把文档写入 Firestore示例通过genkit-ai/vertexai/vectorsearch提供的工厂函数创建索引器传入 Firestore 实例与集合名const firestoreDocumentIndexer: DocumentIndexer getFirestoreDocumentIndexer( db, FIRESTORE_COLLECTION );从源码 js/plugins/vertexai/src/vectorsearch/vector_search/firestore.ts 可以看到其底层实现对传入的每个Document在指定集合中创建一个新文档引用db.collection(collectionName).doc()以批量写db.batch()的方式一次性写入{ content, metadata }最后batch.commit()并返回全部新文档 ID。这些 ID 随后会作为 Vertex AI Vector Search 的 datapoint ID使向量与原始文档一一对应。DocumentIndexer的类型定义types.ts明确其签名输入Document[]输出Promisestring[]文档 ID 列表。同时注释指出目前仅支持Streaming Update Indexers即增量更新模式。Firestore Retriever按邻居 ID 回源取文档检索器同样由工厂函数创建const firestoreDocumentRetriever: DocumentRetriever getFirestoreDocumentRetriever(db, FIRESTORE_COLLECTION);底层实现firestore.ts的流程是接收 Vertex AI Vector Search 返回的Neighbor[]每个邻居包含 datapoint 及其距离逐个用neighbor.datapoint.datapointId作为文档 ID读取collection.doc(id)的快照若文档存在则将原始content、metadata与邻居信息如distance合并再通过DocumentDataSchema.safeParse校验并构造出Document返回。这样检索结果天然携带相似度距离供上层排序使用。Genkit 配置接入 Vertex AI 与 Vector Search 插件示例在 src/index.ts 中完成 Genkit 初始化同时注册两个插件const ai genkit({ plugins: [ vertexAI({ projectId: PROJECT_ID, location: LOCATION, googleAuth: { scopes: [https://www.googleapis.com/auth/cloud-platform], }, }), vertexAIVectorSearch({ projectId: PROJECT_ID, location: LOCATION, vectorSearchOptions: [ { publicDomainName: VECTOR_SEARCH_PUBLIC_DOMAIN_NAME, indexEndpointId: VECTOR_SEARCH_INDEX_ENDPOINT_ID, indexId: VECTOR_SEARCH_INDEX_ID, deployedIndexId: VECTOR_SEARCH_DEPLOYED_INDEX_ID, documentRetriever: firestoreDocumentRetriever, documentIndexer: firestoreDocumentIndexer, embedder: textEmbedding004, }, ], }), ], });关键点说明vertexAI插件提供文本嵌入模型textEmbedding004对应 Vertex AI 的text-embedding-004embedder.ts 中以embedderRef注册维度 768、支持文本输入以及模型生成等能力。vertexAIVectorSearch插件vectorSearchOptions数组中每个元素代表一套“索引文档仓库”绑定关系将向量索引indexId/indexEndpointId/deployedIndexId/publicDomainName与自定义的documentRetriever、documentIndexer、embedder组合在一起。插件实现js/plugins/vertexai/src/vectorsearch/index.ts会在存在vectorSearchOptions时调用内部的vertexAiIndexers与vertexAiRetrievers把默认的索引器、检索器动作注册进 Genkit。vectorSearchOptions中每个配置项的类型定义见 types.ts除四类 ID 与域名外还可选配embedder默认嵌入器与embedderOptions。定义流程indexFlow 与 queryFlow示例定义了两个 Genkit 流程均使用 Zod schema 约束输入输出并借助ai.index/ai.retrieve高层 API 与注册的索引器、检索器交互。索引流程 indexFlowsrc/index.ts 中indexFlow接收一组datapoints每个 datapoint 包含文本text与可选的过滤条件restricts分类限制namespace allowList/denyList用于元数据过滤numericRestricts数值限制valueInt/valueFloat/valueDouble namespace用于数值范围过滤。流程内将每个 datapoint 通过Document.fromText(dp.text, metadata)转为 GenkitDocument随后调用await ai.index({ indexer: vertexAiIndexerRef({ indexId: VECTOR_SEARCH_INDEX_ID, displayName: firestore_index, }), documents, });vertexAiIndexerRef引用此前注册的 Vertex AI 索引器动作ai.index会先对文档调用embeddertext-embedding-004生成向量再写入 Vertex AI Vector Search 索引同时由documentIndexer将原文与元数据写入 Firestore。查询流程 queryFlowsrc/index.ts 中queryFlow的输入为查询文本query、返回条数k以及可选的restricts与numericRestricts数值过滤额外支持op运算符OPERATOR_UNSPECIFIED、LESS、LESS_EQUAL、EQUAL、GREATER_EQUAL、GREATER、NOT_EQUAL。流程执行逻辑const queryDocument Document.fromText(query, metadata); const res await ai.retrieve({ retriever: vertexAiRetrieverRef({ indexId: VECTOR_SEARCH_INDEX_ID, displayName: firestore_index, }), query: queryDocument, options: { k }, });ai.retrieve内部会先用 embedder 对查询文本编码 → 调用 Vertex AI Vector Search 的FindNeighbors找到 top-k 个近邻 → 交由documentRetriever从 Firestore 按邻居 ID 取回原文与元数据。最后输出对结果按distance降序排列并附带length命中条数与time耗时毫秒用performance.now()统计。Neighbor与各类过滤 Schema 的 Zod 定义RestrictionSchema、NumericRestrictionSchema、NeighborSchema等均可在 types.ts 中查看它们直接对应 Vertex AI IndexDatapoint 的 protobuf 结构保证与云端 API 的字段一一映射。启动服务器与整体架构流程定义完成后调用startFlowsServer()启动 Genkit 服务器将indexFlow、queryFlow以 HTTP 端点形式暴露供 Dev UI 或外部调用。本示例的架构可以概括为三层协作┌──────────────────────────────┐ 文本/查询 ──► Genkitembedder index/retrieve │ │ │ ▼ ▼ ▼ Vertex AI Vector Search Firestore原文元数据向量索引 / FindNeighbors 按 datapoint ID 回源向量索引层Vertex AI Vector Search负责高维向量的相似度计算与过滤restricts / numericRestricts文档存储层Firestore负责保存content与metadata是“回源”的数据仓库编排层Genkit 插件体系通过vertexAIVectorSearch将两层绑定并通过ai.index/ai.retrieve提供统一编程接口。该模式与仓库中 js/plugins/vertexai/README.md 描述的 RAG 用法一致且同一套vertexAIVectorSearch插件还支持 BigQuery 后端对应getBigQueryDocumentIndexer/getBigQueryDocumentRetrievervectorsearch/index.ts如需对比可查看 bigquery.ts。结语与扩展方向本示例演示了 Genkit 与 Vertex AI 插件在“文档索引检索”上的最小闭环以 Firestore 为文档仓库、以 Vertex AI Vector Search 为向量检索引擎通过自定义DocumentIndexer/DocumentRetriever实现解耦与定制。你可以在此基础上将 Firestore 替换为其他存储如 BigQuery、PostgreSQL仅需实现同样的DocumentIndexer/DocumentRetriever契约在indexFlow中增加分块chunking与清洗逻辑提升检索质量在queryFlow中串联生成模型形成完整的 RAG 问答链路利用restricts与numericRestricts做租户隔离、类目过滤、价格区间等精细化检索。本示例基于 Apache License 2.0 开源完整代码见 src/index.ts插件源码见 js/plugins/vertexai/src/vectorsearch测试用例可参考 tests/vectorsearch 目录。【免费下载链接】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），仅供参考

使用 Vertex AI Vector Search 与 Firestore 构建 Genkit 文档索引与检索（RAG）实战

相关推荐

如何挑选第一个Claude插件？claude-plugins-community四大插件选型指南

数学建模竞赛结果文档的可复现性解析与工程化落地

X6 元素交互完全指南：连线规则、节点嵌入、高亮样式与交互限制

更多资讯

网盘直链解析：3 步拿到网盘文件，快速上手指南

DeepChat Chat Scroll Ownership 重构实战：从 3000 行 ChatPage 到单滚动所有者状态机

Rerun Position2D 组件深度解析：2D 空间坐标的编码、序列化与多语言使用

fluent-bit 内置 nghttp2 的 HPACK 头字段压缩：nghttp2_hd_deflate_hd 函数深入解析

Kubernetes Goat 私有容器镜像仓库攻击实战：利用 Registry HTTP API v2 拉取镜像元数据与敏感凭证

一次现网问题定位-接口偶发报500,PrematureCloseException: Connection prematurely closed DURING response

今日更新

AWS无服务器应用开发指南：从Lambda到SAM的架构与实践

SpringBoot+Vue人事系统实战：解决HR数据断点与事务一致性

MATLAB手写紧束缚模型计算石墨烯能带结构

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？