Mastra RAGcreateVectorQueryTool 数据库专属配置、多租户动态解析与 Bedrock 知识库工具【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文围绕mastra/rag包中的向量查询工具 createVectorQueryTool 展开系统讲解databaseConfig数据库专属配置Pinecone、pgVector、Chroma、MongoDB、Turbopuffer的用法与底层参数映射机制、基于RequestContext的运行时配置覆盖、面向多租户应用的动态向量库解析器VectorStoreResolver以及配套的createBedrockKBTool托管知识库工具。读完本文你能够针对不同向量数据库精确调优检索行为在请求粒度动态切换 namespace/租户数据并理解这些能力在源码中的真实调用链与默认值。工具的基本形态与输入输出契约createVectorQueryTool是mastra/rag/tools导出的工厂函数用于把一个向量库索引包装成可被 Agent 调用的 Mastra Tool。它支持两种互斥的向量库定位方式判别联合类型按名称传vectorStoreName从 Mastra 实例中查找已注册的向量库mastra.getVector(name)直接实例或解析函数传vectorStore可以是MastraVector实例也可以是动态解析器函数多租户场景详见下文。工具的输入输出 schema 定义在 tool-schemas.ts 中输入基础 schemabaseSchemaqueryText检索文本与topK返回条数经z.coerce.number()强制转为数字当构造时传入enableFilter: true时输入 schema 切换为filterSchema额外暴露一个filter字段字符串形式的 JSON 过滤条件输出 schema 固定为{ relevantContext, sources }relevantContext是结果元数据数组sources是完整的检索结果对象数组每项包含id、metadata、vector、score、document字段。构造工具时的完整选项类型是 VectorQueryToolOptions关键字段如下字段说明默认值indexName向量库内索引名必填无model用于把查询文本转为向量的嵌入模型必填无vectorStoreName/vectorStore二选一注册名 或 实例/解析器无id工具 IDVectorQuery {storeName} {indexName} Tooldescription给 LLM 看的工具描述内置默认描述enableFilter是否在输入 schema 中暴露filter字段falseincludeVectors结果是否包含嵌入向量falseincludeSources响应是否包含sourcestruereranker重排器配置RerankConfig无databaseConfig数据库专属配置详见下节无providerOptions嵌入模型的提供方选项注意仅 AI SDK v2 模型可用v1 模型应在创建模型时配置无databaseConfig为不同向量数据库传递专属参数不同向量数据库的检索 API 各有独特的可调参数——Pinecone 关心 namespace 与稀疏向量pgVector 关心 HNSW/IVFFlat 搜索参数Chroma 关心元数据过滤。databaseConfig字段就是为此设计的一个以数据库名为键的对象把各库专属参数透传给vectorStore.query()。各数据库配置类型全部在 types.ts 中定义并导出Pinecone 配置PineconeConfig支持两个字段namespacePinecone 命名空间与sparseVectorindices/values数组对用于混合检索。import { createVectorQueryTool } from mastra/rag/tools; const pineconeVectorTool createVectorQueryTool({ id: pinecone-search, indexName: my-index, vectorStoreName: pinecone, model: embedModel, databaseConfig: { pinecone: { namespace: my-namespace, // Pinecone namespace sparseVector: { // For hybrid search indices: [0, 1, 2], values: [0.1, 0.2, 0.3], }, }, }, });pgVector 配置PgVectorConfig支持三个字段minScore最低相似度分数、efHNSW 搜索参数、probesIVFFlat 探测参数。const pgVectorTool createVectorQueryTool({ id: pgvector-search, indexName: my-index, vectorStoreName: postgres, model: embedModel, databaseConfig: { pgvector: { minScore: 0.7, // Minimum similarity score ef: 200, // HNSW search parameter probes: 10, // IVFFlat probe parameter }, }, });Chroma 配置ChromaConfig支持where元数据过滤类型完整建模了 Chroma 的$and/$or/$in/$gt等运算符体系与whereDocument文档内容过滤支持$contains/$not_contains。const chromaTool createVectorQueryTool({ id: chroma-search, indexName: my-index, vectorStoreName: chroma, model: embedModel, databaseConfig: { chroma: { where: { // Metadata filtering category: documents, }, whereDocument: { // Document content filtering $contains: important, }, }, }, });注意这与工具级enableFilter 输入filter字段是两套机制where/whereDocument是 Chroma 原生的过滤语法直接透传而filter字段走的是 Mastra 通用的 VectorFilter 解析路径。MongoDB 与 Turbopuffer 配置除文档示例的三种数据库外DatabaseConfig还内置了另外两种见 types.ts并有对应测试用例覆盖const mongoTool createVectorQueryTool({ vectorStoreName: mongodb, indexName: my-index, model: embedModel, databaseConfig: { mongodb: { numCandidates: 500, // HNSW 候选数须 topK默认 20 * topK上限 10000 }, }, }); const turboTool createVectorQueryTool({ vectorStoreName: turbopuffer, indexName: my-index, model: embedModel, databaseConfig: { turbopuffer: { consistency: eventual, // strong默认或 eventual更低延迟 }, }, });DatabaseConfig类型本身带[key: string]: any索引签名允许为未来新数据库任意扩展键export type DatabaseConfig { pinecone?: PineconeConfig; pgvector?: PgVectorConfig; chroma?: ChromaConfig; mongodb?: MongoDBConfig; turbopuffer?: TurbopufferConfig; // Add other database configs as needed [key: string]: any; // Allow for future database extensions };参数如何抵达 query 调用源码级映射配置并不是原样透传的。在 vector-search.ts 的databaseSpecificParams()中框架按数据库名把嵌套配置“摊平”为vectorStore.query()能直接识别的顶层参数pinecone.namespace→namespacepinecone.sparseVector→sparseVectorpgvector.minScore/ef/probes→ 同名顶层参数chroma.where/whereDocument→ 同名顶层参数mongodb.numCandidates→numCandidatesturbopuffer.consistency→consistency。最终在 vector-search.ts 处合并进查询参数results await vectorStore.query({ ...queryParams, ...databaseSpecificParams(databaseConfig) });其中queryParams由indexName、queryVector嵌入结果、topK、filter、includeVector组成。运行时覆盖用 RequestContext 按请求改写配置工具级databaseConfig是静态的若需要按请求动态调整例如切换 Pinecone namespace 到不同环境的数据分区可以在RequestContext中设置同名键databaseConfig。在 vector-query.ts 中几乎所有运行时变量都遵循“requestContext 优先、options 兜底”的取值顺序const indexName: string requestContext?.get(indexName) ?? options.indexName; const databaseConfig requestContext?.get(databaseConfig) ?? options.databaseConfig; const model: MastraEmbeddingModelstring requestContext?.get(model) ?? options.model; const topK: number requestContext?.get(topK) ?? (inputData.topK as number) ?? 10; // includeVectors、includeSources、reranker、filter、providerOptions 同理可覆盖的键包括indexName、vectorStoreName、includeVectors、includeSources、reranker、databaseConfig、model、providerOptions、topK、filter。基于测试用例 vector-query-database-config.test.ts 验证过的运行时覆盖写法如下import { RequestContext } from mastra/core/request-context; const tool createVectorQueryTool({ vectorStoreName: pinecone, indexName: testIndex, model: embedModel, databaseConfig: { pinecone: { namespace: initial-namespace } }, }); // 运行时覆盖 Pinecone namespace const requestContext new RequestContext(); requestContext.set(databaseConfig, { pinecone: { namespace: runtime-namespace }, }); const result await tool.execute( { queryText: test query, topK: 5 }, { mastra, requestContext }, );一个需要注意的语义细节由于取值是??而非深合并requestContext中一旦设置了databaseConfig将整体替换工具级配置而不是逐字段合并。测试用例明确断言了运行时配置会完整取代初始配置databaseConfig: runtimeConfig。多租户应用动态向量库解析器 VectorStoreResolver对于每个租户数据隔离的场景例如各租户使用独立的 PostgreSQL schemavectorStore除了接收静态实例外还可以接收一个解析器函数。类型定义在 types.tsexport interface VectorStoreResolverContext { requestContext?: RequestContext; mastra?: MastraUnion; } export type VectorStoreResolver ( context: VectorStoreResolverContext ) MastraVector | PromiseMastraVector;解析器在每次execute时收到requestContext和mastra据此返回当次请求应使用的向量库import { createVectorQueryTool, VectorStoreResolver } from mastra/rag/tools; import { PgVector } from mastra/pg; // Resolver function receives requestContext and mastra instance const vectorStoreResolver: VectorStoreResolver async ({ requestContext }) { const tenantId requestContext?.get(tenantId); return new PgVector({ id: pg-vector-${tenantId}, connectionString: process.env.POSTGRES_CONNECTION_STRING!, schemaName: tenant_${tenantId}, // Each tenant has their own schema }); }; const vectorQueryTool createVectorQueryTool({ indexName: embeddings, model: embedModel, vectorStore: vectorStoreResolver, // Dynamic resolution! }); // Usage with tenant context const requestContext new RequestContext(); requestContext.set(tenantId, acme-corp); const result await vectorQueryTool.execute( { queryText: search query, topK: 5 }, { requestContext }, );从源码看解析逻辑集中在 tool-helpers.ts 的resolveVectorStore()中若vectorStore是函数则以{ requestContext, mastra }调用并await其结果返回值经过isValidMastraVector运行时校验非 null/undefined 的对象resolver 返回无效值时会抛出带上下文的错误错误信息会附带vectorStoreName、schemaId、tenantId等诊断信息便于排查若未提供vectorStore则回退到mastra.getVector(vectorStoreName)。同样的解析机制对 GraphRAG 工具同样生效——createGraphRAGTool 接受相同的判别联合选项见 GraphRagToolOptions含dimension默认 1536、randomWalkSteps默认 100、restartProb默认 0.15、threshold默认 0.7import { createGraphRAGTool } from mastra/rag/tools; const graphTool createGraphRAGTool({ indexName: embeddings, model: embedModel, vectorStore: vectorStoreResolver, });执行流程与容错行为源码级理解工具在execute中做了什么有助于判断异常时的行为边界。vector-query.ts 的执行链是解析运行时变量如上节requestContext 优先coerceTopK把topK规整为有限正数无效值回退默认10见 tool-helpers.tsresolveVectorStore解析向量库。若解析结果为undefined按名称找不到已注册向量库工具记录 error 日志并优雅降级——返回{ relevantContext: [], sources: [] }而非抛错嵌入查询文本。vectorQuerySearch 按model.specificationVersion分派到embedV3/embedV2/embedV1并创建RAG_EMBEDDING观测 span记录模型、提供方、维度与 token 用量向量查询。携带RAG_VECTOR_OPERATIONspan 调用vectorStore.query(...)可选重排。若配置了reranker则走 rerank/rerankWithScorer重排后relevantContext取重排结果的元数据sources由重排结果转换异常兜底。整个流程包在 try/catch 中任何未预期异常都会记录 error 日志并返回空结果避免单次检索失败中断整个 Agent 对话。此外filter输入如果是字符串会经 parseFilterValue 做JSON.parse并校验必须是普通对象解析失败会抛错并记录日志。扩展新数据库系统为扩展预留了两条路径与 README 的说明一致添加类型为新库定义配置接口并加入DatabaseConfig[key: string]: any索引签名已允许直接加键export interface NewDatabaseConfig { customParam1?: string; customParam2?: number; } export type DatabaseConfig { pinecone?: PineconeConfig; pgvector?: PgVectorConfig; chroma?: ChromaConfig; newdatabase?: NewDatabaseConfig; // Add your config here [key: string]: any; };参数透传databaseSpecificParams()的兜底分支vector-search.ts会把不在内置五库枚举中的键对应的配置对象整体平铺合并进查询参数Object.keys(databaseConfig).forEach(dbName { if (!DATABASE_TYPE_MAP.includes(dbName)) { // For unknown database types, merge the config directly const config databaseConfig[dbName]; if (config typeof config object) { Object.assign(databaseSpecificParams, config); } } });也就是说新数据库只要其query()接受的参数名与配置对象的键一致无需改动核心代码即可透传——类型安全由你自行补充的接口保证。createBedrockKBToolAmazon Bedrock 托管知识库mastra/rag还导出了 createBedrockKBTool直接对接 Amazon Bedrock 托管知识库——向量存储、索引与检索基础设施全部由 AWS 托管无需自行维护任何向量库import { createBedrockKBTool } from mastra/rag; const kbTool createBedrockKBTool({ knowledgeBaseId: ABCDEFGHIJ, region: us-west-2, }); const results await kbTool.execute({ queryText: What are our policies? });也可以像普通工具一样挂到 Agent 上参考 BEDROCK_MANAGED_KB.mdimport { Agent } from mastra/core; const agent new Agent({ name: research-agent, tools: { kb: kbTool }, instructions: Use the knowledge base to answer questions., });选项与默认值选项/环境变量说明默认值knowledgeBaseIdBedrock 知识库 ID必填无regionAWS 区域对应环境变量AWS_REGIONAWS_REGION或us-east-1numberOfResults最大返回条数5useAgenticRetrieval是否启用 Agentic Retrieval对应环境变量USE_AGENTIC_RETRIEVAL设为false即关闭trueuserId访问控制用的默认 AWS 用户 ID请求上下文requestContext.get(userId)优先无凭证走标准 AWS 环境变量AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY。Agentic Retrieval 与自动回退从源码bedrock-knowledge-base.ts看useAgenticRetrieval为 true 时调用AgenticRetrieveStreamCommand配置foundationModelType: MANAGED与rerankingModelType: MANAGED——即由 Bedrock 托管模型自动完成查询分解与重排流式收集结果一旦失败则catch中自动回退到标准RetrieveCommandmanagedRetrieve并打印警告。这也解释了 README 中“Agentic Retrieval 默认开启、失败自动降级为标准检索”的描述。关闭方式export USE_AGENTIC_RETRIEVALfalse # disable agentic, use standard retrieve其他实现细节工具 ID 固定为bedrock_knowledge_base_${knowledgeBaseId}输入 schema 仅queryText一个字段输出的source字段会从检索结果的location中提取来源 URI支持 S3、Web、Confluence、Salesforce、SharePoint、自定义文档六类来源见 getSourceUri所需 IAM 权限来自 BEDROCK_MANAGED_KB.md{ Effect: Allow, Action: [bedrock:Retrieve, bedrock:AgenticRetrieveStream], Resource: arn:aws:bedrock:region:account-id:knowledge-base/kb-id }SDK 要求aws-sdk/client-bedrock-agent-runtime需 3.1000 以上AgenticRetrieveStreamCommand依赖该版本能力。向后兼容旧代码无需改动databaseConfig是完全增量式的可选项不传时行为与旧版本一致。测试用例专门验证了“无databaseConfig时vectorQuerySearch收到databaseConfig: undefined”这一向后兼容路径。给既有工具补充数据库配置只需加一个字段const vectorTool createVectorQueryTool({ indexName: my-index, vectorStoreName: pinecone, model: embedModel, databaseConfig: { pinecone: { namespace: my-namespace } } });测试覆盖与延伸阅读本文所有关键行为均有仓库内测试佐证vector-query-database-config.test.ts覆盖 Pinecone/pgVector/MongoDB/Turbopuffer 配置透传、requestContext 覆盖、无配置时的向后兼容、多库配置共存vector-query.test.ts向量查询工具的主流程测试bedrock-knowledge-base.test.tsBedrock 知识库工具的检索与回退测试类型与默认值types.ts、default-settings.ts模块导出入口index.ts。需要注意的适用前提databaseConfig的专属参数只有当对应向量库驱动的query()实现支持该参数时才会实际生效框架只负责透传providerOptions仅对 AI SDK v2 嵌入模型有效。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考