Mastra Astra 向量存储深度指南基于 DataStax Astra DB 的向量检索实现与版本演进【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/astra是 Mastra 框架官方的 DataStax Astra DB 向量存储适配包它借助 Cassandra 的向量搜索能力为 Agent、工作流与 RAG 场景提供向量相似度检索。本文以该包自身的 CHANGELOG 为脉络主线结合 源码实现、过滤器翻译器、内置提示词 与 测试用例完整梳理其安装配置、核心 API、元数据过滤体系以及从 0.x 到 1.1.1 的版本演进中沉淀出的工程实践。读完你既能直接上手接入 Astra DB也能理解这些变更背后的设计取舍。一、包定位Mastra 与 DataStax Astra DB 之间的向量存储桥梁根据 stores/astra/README.md 的说明mastra/astra是DataStax Astra DB 的向量存储实现基于 Cassandra 的向量搜索能力提供向量相似度检索。在 package.json 中可以看到它的关键元信息包名mastra/astra当前仓库版本为1.1.1描述为 Astra DB provider for Mastra - includes vector store capabilities运行时依赖仅datastax/astra-db-ts^1.5.0即官方 TypeScript 客户端同伴依赖mastra/core1.0.0-0 2.0.0-0说明它作为核心框架的插件化存储扩展存在运行环境engines.node 22.13.0与 CHANGELOG 中 1.0.0 的 Bump minimum required Node.js version to 22.13.0 对应包出口exports同时提供 ESMdist/index.js与 CJSdist/index.cjs两种产物且发布时仅包含dist目录。从 入口文件 可以看出包对外只暴露两样东西export * from ./vector; export { ASTRA_PROMPT } from ./vector/prompt;即核心的AstraVector向量存储类以及一个向量存储专属的过滤器构造提示词ASTRA_PROMPT。后者正是 CHANGELOG 0.2.12 条目 Moved vector store specific prompts from mastra/rag to be exported from the store that the prompt belongs to 的落地成果——原本散落在mastra/rag中的各存储专属提示词被迁回各自的 store 包方便 Agent 在生成过滤器时直接读取。二、安装与五分钟快速上手安装方式见 READMEnpm install mastra/astra随后创建向量存储实例需要 Astra DB 的 token、endpoint 与可选 keyspaceimport { AstraVector } from mastra/astra; const vectorStore new AstraVector({ token: your-astra-token, endpoint: your-astra-endpoint, keyspace: your-keyspace, // 可选 });对应 构造函数实现内部用new DataAPIClient(token)创建官方客户端再client.db(endpoint, { keyspace })获得数据库句柄。注意构造函数还要求一个id字段——这是 1.0.0 破坏性变更 Each primitive also now requires an id to be set 的直接体现见 CHANGELOG 1.0.0。README 给出的最小工作流是建集合 → 写入向量 → 检索三步// 1. 创建集合即索引 await vectorStore.createIndex({ indexName: myCollection, dimension: 3, metric: cosine }); // 2. 写入向量可附带元数据 const vectors [ [0.1, 0.2, 0.3], [0.3, 0.4, 0.5], ]; const metadata [{ text: doc1 }, { text: doc2 }]; const ids await vectorStore.upsert({ indexName: myCollection, vectors, metadata }); // 3. 向量检索 const results await vectorStore.query({ indexName: myCollection, queryVector: [0.1, 0.2, 0.3], topK: 10, // 返回条数 filter: { text: { $eq: doc1 } }, // 可选元数据过滤 includeVector: false, // 是否在结果中带回原始向量 });需要留意的是 README 示例中的filter: { text: ... }是示意写法结合 upsert 实现 可以看到写入的文档实际结构是{ id, $vector, metadata }因此真实过滤通常应使用点号路径指向元数据字段例如{ metadata.text: { $eq: doc1 } }——这一点在集成测试 index.test.ts 中被反复验证如metadata.category、metadata.specs.color。三、核心 API 全景从源码看懂每个方法的实际行为AstraVector继承自mastra/core的MastraVector基类见 index.ts因此对上层 Agent、RAG 与工作流暴露统一接口。下面逐个剖析实现细节。3.1 createIndex建集合与度量方式映射async createIndex({ indexName, dimension, metric cosine }: CreateIndexParams): Promisevoid先做输入校验dimension必须为正整数否则抛出MastraError错误 ID 为MASTRA_VECTOR_ASTRA_CREATE_INDEX_INVALID_DIMENSION通过this.#db.createCollection(indexName, { vector: { dimension, metric }, checkExists: false })创建集合度量方式不是直接透传的而是经过metricMap转换Mastra 与 Astra DB 对 cosine、euclidean 命名一致但 dotproduct 在 Astra DB 侧叫dot_product见 源码注释const metricMap { cosine: cosine, euclidean: euclidean, dotproduct: dot_product, } as const;也就是说在 Mastra 侧统一书写metric: dotproductSDK 会自动翻译为 Astra DB 认识的dot_product。3.2 upsert写入/更新向量async upsert({ indexName, vectors, metadata, ids }: UpsertVectorParams): Promisestring[]未传ids时自动用UUID.v7()为每个向量生成 ID每条记录组装为{ id, $vector: vector, metadata: metadata?.[i] || {} }一次insertMany批量写入返回写入成功的 ID 数组方便后续按 ID 更新或删除。3.3 query向量相似度检索async query({ indexName, queryVector, topK 10, filter, includeVector false }): PromiseQueryResult[]这是整个包的核心。实现上有四个值得注意的点queryVector为必填一旦缺失立即抛出MastraErrorMASTRA_VECTOR_ASTRA_QUERY_MISSING_VECTOR错误文案明确说明 Metadata-only queries are not supported by this vector store。这正是 CHANGELOG 1.0.1 的变更PR #13286——此前遗漏queryVector只会得到难懂的 SDK 层错误现在各 store 统一抛出结构化错误ErrorCategory.USER表明这是调用方的使用问题过滤条件翻译filter先交给AstraFilterTranslator详见第五节翻译校验空过滤直接透传{}底层查询collection.find(filter, { sort: { $vector: queryVector }, limit: topK, includeSimilarity: true, projection: { $vector: includeVector } })即按向量相似度排序、取前 topK 条并让服务端返回相似度分数$similarity结果规整每条结果映射为{ id, score: result.$similarity, metadata, ...(includeVector { vector: result.$vector }) }与 Mastra 统一的QueryResult类型对齐。3.4 索引管理listIndexes / describeIndex / deleteIndexlistIndexes()db.listCollections({ nameOnly: true })返回全部集合名describeIndex({ indexName })并行调用collection.options()与collection.countDocuments({}, 100)返回{ dimension, metric, count }。其中metric会反向用metricMap把 Astra DB 的dot_product还原为 Mastra 侧的dotproductdeleteIndex({ indexName })collection.drop()删除整个集合。3.5 单条更新与删除updateVector / deleteVectorupdateVector({ indexName, id, update })使用findOneAndUpdate({ id }, { $set: updateDoc })做局部更新。先校验id必填、update.vector与update.metadata至少提供一个$vector与metadata按需写入更新文档。这正是 CHANGELOG 1.0.0 Add new deleteVectors, updateVector by filter 中 updateVector 部分的实现deleteVector({ indexName, id })collection.deleteOne({ id })按 ID 删除。3.6 批量删除deleteVectors 尚未实现值得注意的是虽然 CHANGELOG 1.0.0 宣布新增了deleteVectors按过滤条件批量删除能力但Astra 当前实现中该方法直接抛出MASTRA_VECTOR_ASTRA_DELETE_VECTORS_NOT_SUPPORTED错误类别为ErrorCategory.SYSTEM见 index.ts提示 deleteVectors is not yet implemented for Astra vector store。因此在选择批量清理策略时Astra 用户目前只能退回到按 ID 逐个deleteVector或在集合层面做deleteIndex重建。这一点在接入时需要根据实际版本确认。四、版本演进主线CHANGELOG 里的关键技术决策CHANGELOG 完整记录了从 0.2.x 到 1.1.1 的演进。剔除大量Updated dependencies的例行条目后可以提炼出四条清晰的技术主线。4.1 破坏性变更命名参数化与稳定化0.10.0 → 1.0.00.10.0commitd0ee3c6、a7292b0所有 vector store 的公共函数与构造函数改用命名参数named args同时删除废弃函数与位置参数。这是 0.x 时代最大的一次 API 收敛也为后来统一接口奠定了基础1.0.0PR #9675每个 Mastra 原语agent、MCPServer、workflow、tool、processor、scorer、vector都具备get、list、add方法且每个原语都必须设置id被添加到其他原语中的原语会自动注册到 Mastra 实例1.0.0PR #9706Node.js 最低版本提升到22.13.0并在 package.json 的engines字段固化1.0.0commit83d5942正式标记为stablepeer 依赖同步对齐 core 1.0.0。4.2 错误处理体系的标准化0.11.0 → 1.0.1这一主线体现了 Mastra 对可观测、可排障的坚持0.11.0commit0e17048storage 包开始抛出 Mastra 错误Throw mastra errors in storage packages1.0.0PR #10913使用集中式辅助函数createStorageErrorId与createVectorErrorId统一所有存储/向量 store 的错误 ID规范为MASTRA_VECTOR_{STORE}_{OPERATION}_{STATUS}模式。对照源码可见Astra 中的错误 ID 例如MASTRA_VECTOR_ASTRA_CREATE_INDEX_INVALID_DIMENSION、MASTRA_VECTOR_ASTRA_QUERY_DB_ERROR、MASTRA_VECTOR_ASTRA_UPDATE_VECTOR_NO_PAYLOAD等全部遵循该模式1.0.1PR #13286为需要向量的 store 补充queryVector缺失时的结构化错误MastraErrorErrorCategory.USER取代此前令人困惑的 SDK 层报错。配合 错误分类体系可以看到错误被划分为ErrorDomain.MASTRA_VECTOR域下的USER调用方问题、THIRD_PARTYAstra DB 侧问题会附带底层 error 与details.indexName上下文与SYSTEM未实现能力三类极大方便了上层统一捕获与告警归类。4.3 过滤能力与写入能力增强0.11.0 → 1.0.00.11.0MASTRA-3669引入元数据过滤类型系统Metadata Filter Types从类型层面约束过滤器的合法结构1.0.0PR #10408新增deleteVectors与按过滤条件的updateVector。如前所述Astra 的deleteVectors目前仍为占位实现属于接口就位、实现待续的渐进式演进。4.4 工程化与供应链质量0.11.3 → 1.1.10.11.3commit4a406ec修复 TypeScript 声明文件导入问题确保 ESM 兼容性1.0.0PR #11472发布包内置嵌入式文档——npm 包在dist/docs/下附带SKILL.md包用途与能力入口、SOURCE_MAP.json导出与类型/实现文件的机器可读索引以及按特性组织的话题文件夹让编码 Agent 可以直接读取node_modules中的文档来理解并使用框架1.0.4PR #18056针对 2026-06-17 easy-day-js 供应链事件的安全修复重新发布干净版本并将latestdist-tag 前移取代声明了恶意easy-day-js依赖的受影响版本1.1.1PR #22737将CHANGELOG.md从 npm 发布文件中移除缩减包体积同时更新 README 至准确的最新信息PR #22858。五、元数据过滤体系深入支持的操作符与校验规则过滤是向量检索中做精排与范围控制的关键能力。mastra/astra通过 filter.ts 中的AstraFilterTranslator实现它继承BaseFilterTranslator在保持 MongoDB 兼容语法Astra DB 原生采用类 MongoDB 文档过滤语法的同时对操作符白名单与值类型做严格校验。5.1 操作符支持矩阵根据 getSupportedOperators 实现 与内置 ASTRA_PROMPT支持的操作符如下类别支持的操作符说明与示例基础比较$eq$ne$gt$gte$lt$lte数值比较要求数值{ price: { $gte: 100, $lte: 1000 } }数组$in$nin$all值必须是数组空数组用于$in/$nin时返回空结果$all要求非空数组元素$exists判断字段是否存在{ rating: { $exists: true } }特殊Astra 专属$size数组长度检查{ tags: { $size: 2 } }逻辑$and$or$not顶层或嵌套在逻辑操作符内使用明确不支持的操作符包括$regex/$options正则、$elemMatch、$nor。AstraVectorFilter类型通过OmitOperatorValueMap, $elemMatch | $regex | $options与OmitLogicalOperatorValueMap, $nor在类型层面就堵死了这些用法运行时校验则抛出 Unsupported operator 错误见 filter.test.ts 的 operator validation 测试组。5.2 结构约束与陷阱ASTRA_PROMPT用大段规则明确了过滤器的合法结构对实际开发极具参考价值顶层只允许逻辑操作符$and、$or、$not其他操作符必须出现在字段条件内{ field: { $gt: 100 } }合法{ $gt: 100 }非法逻辑操作符内部必须是字段条件而非裸操作符{ $and: [{ field: { $gt: 100 } }] }合法{ $and: [{ $gt: 100 }] }非法$and/$or不能出现在字段级别或嵌套进字段操作符内只能位于顶层或嵌套在逻辑操作符中$not必须为对象且非空可用于字段级{ field: { $not: { $eq: value } } }或顶层{ $not: { field: value } }且允许包含逻辑操作符嵌套字段使用点号路径dot notation如metadata.specs.color同一字段多条件支持隐式或显式$and{ price: { $gt: 100 }, category: electronics }等价于显式$and。此外翻译器会对比较值做归一化——最典型的是Date 会被自动转为 ISO 字符串见 filter.test.ts 的 normalizes dates 用例保证与 Astra DB 的日期比较语义一致。5.3 一个完整的多条件复合过滤示例ASTRA_PROMPT末尾给出了可直接套用的复合查询{ $and: [ { category: { $in: [electronics, computers] } }, { price: { $gte: 100, $lte: 1000 } }, { tags: { $all: [premium] } }, { rating: { $exists: true, $gt: 4 } }, { $or: [ { stock: { $gt: 0 } }, { preorder: true } ]} ] }在集成测试 index.test.ts 的 Complex Filter Combinations 与 Nested Field Queries 测试组中这类$and/$or嵌套、$in/$all/$exists混用、以及对metadata.specs.weight、metadata.author.country等嵌套字段的过滤都被逐条验证。六、接入 Mastra 的工程要点与验证方式6.1 与 Mastra 核心的集成方式AstraVector继承MastraVector并实现其全部抽象方法因此可以直接作为 Agent 的vectorStore为 RAG 检索提供向量底座配合mastra/rag使用——注意 0.2.12 之后各 store 的过滤提示词已内聚到包内ASTRA_PROMPT构造过滤条件时应参考 prompt.ts 而不是依赖 rag 包由于所有原语要求id创建实例时应显式传入唯一id1.0.0 起。6.2 版本与运行前提Node.js ≥ 22.13.0package.jsonengines字段需要 DataStax Astra DB 账号提供ASTRA_DB_TOKEN与ASTRA_DB_ENDPOINTkeyspace 可选对应集成测试 index.test.ts 中读取的环境变量mastra/corepeer 版本需1.0.0-0 2.0.0-0。6.3 本地验证途径仓库内置了两层测试可参考单元测试filter.test.ts不依赖真实数据库覆盖翻译器的基本操作、数组操作、逻辑操作、嵌套字段、特殊值null、Date、空对象以及非法操作符拒绝是最快的本地校验手段集成测试index.test.ts标注为describe.skip的 AstraVector Integration Tests需要真实 Astra DB 环境变量覆盖建索引含 1536 维高维向量、cosine/euclidean/dotproduct 三种度量、upsert、query含includeVector、describeIndex、过滤校验与元数据过滤全场景并给出了轮询等待最终一致性的经典模式——Astra DB 的索引与计数存在短暂延迟测试用waitForCondition轮询集合可见性与文档数。结语从 CHANGELOG 的演进轨迹可以看到mastra/astra在短短几个版本内完成了从位置参数到命名参数、从裸错误到MASTRA_VECTOR_ASTRA_*结构化错误、从无类型过滤到严格操作符白名单的全面工程化。对使用者而言接入的关键结论可以浓缩为三点以AstraVector统一面向 Mastra 上层提供向量能力过滤条件严格限定在$eq/$ne/$gt/$gte/$lt/$lte/$in/$nin/$all/$exists/$size/$and/$or/$not白名单内且嵌套字段使用点号路径在deleteVectors落地前批量清理需按 ID 逐个删除或重建集合。深入 源码 与 测试 阅读是掌握其行为边界最可靠的方式。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考