ToolJet 集成 Pinecone 向量数据库Marketplace 插件配置与七大向量操作实战指南【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet本文围绕 ToolJet 官方 Marketplace 中的Pinecone插件展开系统讲解如何在 ToolJet 工作区中安装该插件、使用 API Key 建立数据源连接并逐一剖析插件支持的 7 个向量操作获取索引统计、列出向量 ID、获取/写入/更新/删除/查询向量的参数含义、示例输入与底层实现。读完本文你将能够在 ToolJet 应用中以低代码方式完成基于 Pinecone 向量索引的增删改查与相似度检索为 RAG检索增强生成等 AI 场景搭建数据通路。插件概览Pinecone 与 ToolJet 的集成方式Pinecone 是托管的向量数据库服务用于存储和检索高维向量embedding。ToolJet 通过 Marketplace 插件与其集成从而在应用编辑器中直接执行向量操作更新、查询、管理 Pinecone 索引中的向量数据而无需自己编写 SDK 调用代码。在仓库中该插件以独立 npm 包的形式存在位于 marketplace/plugins/pinecone其包名为tooljet-marketplace/pinecone依赖pinecone-database/pinecone^3.0.3官方 SDK 与tooljet-marketplace/common公共类型见 marketplace/plugins/pinecone/package.json。插件源码结构如下lib/index.ts实现QueryService接口的服务类负责建立连接、分发操作lib/query_operations.ts7 个具体向量操作的实现lib/types.ts数据源选项、查询选项与操作枚举的类型定义lib/manifest.json数据源级配置API Key 字段lib/operations.json查询面板中各操作的 UI 表单定义标签、占位符、说明。前置条件启用 Marketplace 并安装插件Pinecone 插件属于 ToolJet Marketplace 生态。要使用它需先确认 Marketplace 功能已开启。根据 Marketplace 概述文档在.env文件中设置ENABLE_MARKETPLACE_FEATUREtrue随后在本地运行时需要先构建 marketplace 插件再启动服务端且只有Administrator角色可以访问 Marketplace 页面。安装插件的完整流程详见 Using Marketplace Plugins 章节点击仪表盘左下角的设置图标在菜单中选择Marketplace在Marketplace页签中找到 Pinecone 卡片点击Install状态变为Installed进入仪表盘的Data sources页签滚动到Plugins区域即可看到已安装的 Pinecone 插件并进行数据源配置配置完成后在查询面板Query Panel新建查询时即可选择该数据源。:::note 本文以已按上述流程完成插件安装为前提即已经完成使用 Marketplace 插件的全过程。 :::建立连接使用 API Key 配置数据源Pinecone 数据源只需要一项凭证API Key可在 Pinecone Consoleapp.pinecone.io的 API Keys 页面生成。在 ToolJet 中新建数据源时将生成的 API Key 填入API Key字段即可完成连接。该字段在 manifest.json 中被声明为{ apiKey: { label: API Key, key: apiKey, type: password, description: Enter your Pinecone API Key } }注意其中encrypted: true与type: password两个属性API Key 会以密码框形式展示并在存储时加密处理避免明文泄露。源码视角连接与连通性测试从源码看连接与测试逻辑集中在 lib/index.ts 的PineconeService中。getConnection方法接收apiKey缺失时直接抛出QueryError(API key missing, ...)通过后创建new Pinecone({ apiKey })实例并返回async getConnection(sourceOptions: SourceOptions): PromisePinecone { const { apiKey } sourceOptions; if (!apiKey) { throw new QueryError(API key missing, No API key provided in source options, {}); } const pinecone new Pinecone({ apiKey }); return pinecone; }而testConnection则调用pinecone.listIndexes()验证凭证有效性若返回的索引列表非空则判定连接成功否则抛出QueryError(No indexes found, The index list is empty, {})。这解释了为什么在配置数据源时若当前账号下没有任何索引连通性测试会提示 No indexes found——这是插件设计使然可在 Pinecone 控制台先创建至少一个索引后再进行测试。操作分发机制run 方法与 Operation 枚举所有查询最终都会进入PineconeService.run(sourceOptions, queryOptions, dataSourceId)方法。它先通过getConnection获得客户端实例再依据queryOptions.operation进行 switch 分发并将结果统一包装为{ status: ok, data: result }返回给查询面板任何异常都会被转换为QueryError(Query could not be completed, error?.message, {})。操作枚举定义于 lib/types.ts与 operations.json 中的下拉选项一一对应枚举值operations.json 中的 value显示名称对应函数get_index_statsGet Index StatsgetIndexStatslist_vector_idsList Vector IDslistVectorIdsfetch_vectorsFetch VectorsfetchVectorsupsert_vectorsUpsert VectorsupsertVectorsupdate_vectorUpdate a VectorupdateVectordelete_vectorsDelete VectorsdeleteVectorsquery_vectorQuery VectorsquertVectors下面按这 7 个操作逐一展开。操作一Get Index Stats获取索引统计该操作用于检索指定索引的统计信息例如各命名空间namespace的记录数、向量维度、索引饱和度与总记录数。必需参数Index要获取统计信息的索引名称。示例响应{ namespaces: { : { recordCount: 100 } }, dimension: 1024, indexFullness: 0, totalRecordCount: 100 }其中dimension表示索引的向量维度此处为 1024indexFullness为索引饱和程度0 表示远未满totalRecordCount为该索引全部命名空间的向量总数。源码实现在 query_operations.ts 的getIndexStats中若index为空会直接抛出Index name is required否则通过pinecone.index(index).describeIndexStats()获取统计信息const indexClient pinecone.index(index); const stats await indexClient.describeIndexStats(); return stats;操作二List Vector IDs列出向量 ID该操作分页列出指定索引中的向量 ID常用于了解索引内容或为后续的获取/删除操作准备 ID 列表。必需参数Index要列出向量 ID 的索引名称。可选参数Prefix按前缀过滤向量 ID例如只列出document1#开头的 IDLimit最多返回的向量 ID 数量Pagination Token用于获取下一页结果的分页令牌Namespace在索引内指定的命名空间中进行查询。示例响应{ vectors: [ { id: 0 }, { id: 1 }, { id: 10 }, { id: 11 }, { id: 12 }, { id: 13 }, { id: 14 }, { id: 15 }, { id: 16 }, { id: 17 } ], pagination: { next: eyJza2lwX3Bhc3QiOiIxNyIsInByZWZpeCI6bnVsbH0 }, namespace: , usage: { readUnits: 1 } }响应中的pagination.next令牌可继续传入Pagination Token参数获取下一页usage.readUnits表示该次请求消耗的读取单元数。源码实现与默认值listVectorIds使用listPaginated方法其中limit未提供时默认为10见源码limit: limit || 10。prefix、limit、paginationToken会一并透传给 SDK若提供了namespace则先通过indexClient.namespace(namespace)切换到对应命名空间再执行列出操作const listOptions { prefix: prefix, limit: limit || 10, paginationToken: paginationToken, }; const client namespace ? indexClient.namespace(namespace) : indexClient; const vectors await client.listPaginated(listOptions);操作三Fetch Vectors获取向量该操作根据指定的向量 ID 从索引中获取对应向量默认只返回 ID 与元数据可通过查询参数决定是否包含向量数值。必需参数Index要获取向量的索引名称IDs要获取的向量 ID 数组以 JSON 数组形式输入例如[id-1, id-2]。可选参数Namespace从中获取向量的命名空间。示例响应{ records: {}, namespace: , usage: { readUnits: 1 } }当目标 ID 不存在时records为空对象命中记录时records中会按 ID 映射返回每条向量。源码实现fetchVectors在index或ids缺失时抛出Index name and vector IDs are required。由于表单输入的是字符串代码会先JSON.parse(ids)将其转换为数组再调用client.fetch(vectorIds)const vectorIds typeof ids string ? JSON.parse(ids) : ids; const client namespace ? await indexClient.namespace(namespace) : indexClient; const vectors await client.fetch(vectorIds);操作四Upsert Vectors写入/更新向量该操作用于向索引插入新向量或对已存在的 ID 执行覆盖式更新upsert。必需参数Index要写入向量的索引名称Vectors要写入的向量数组每个元素必须包含id与values例如[{id: vec1, values: [0.1, 0.2, 0.3]}]可选参数Namespace写入目标命名空间。示例响应Upsert Successful源码实现与校验逻辑upsertVectors会先对每个向量做结构校验——若任一向量缺少id或values不是数组立即抛出Each vector must have an id and a values arrayparsedVectors.forEach((vector) { if (!vector.id || !Array.isArray(vector.values)) { throw new Error(Each vector must have an id and a values array); } });随后调用client.upsert(parsedVectors)SDK 在成功时返回undefined插件据此判定成功并返回字符串Upsert Successful否则抛出Upsert failed。这一以返回值是否为 undefined 判定成败的模式同样出现在 Update 与 Delete 操作中。操作五Update a Vector更新单个向量该操作针对单个已有向量更新其向量数值values、稀疏向量表示sparse vector或元数据metadata。必需参数Index向量所在的索引名称ID要更新的向量 ID。可选参数Values更新后的向量数值数组例如[4.0, 2.0]Sparse Vector稀疏向量表示JSON 格式例如{indices: [1, 5], values: [0.5, 0.5]}Metadata附加的元数据对象例如{genre: comedy}Namespace向量所在的命名空间。示例响应Update Successful源码实现updateVector的校验较严格除index与id外还要求values与sparse_vector至少提供其一否则抛出Index name, vector ID, and either values or sparse vector are required。随后构造更新请求其中values、metadata、sparse_vector均为 JSON 字符串输入需先解析再透传const updateResponse await client.update({ id, ...(valuesArray { values: valuesArray }), ...(metadata { metadata: JSON.parse(metadata) }), ...(sparse_vector { sparseValues: JSON.parse(sparse_vector) }), });操作六Delete Vectors删除向量该操作从索引中删除向量支持三种删除策略按 ID 列表删除、按过滤器条件删除、或一键清空整个命名空间。必需参数Index要删除向量的索引名称。可选参数IDs要删除的向量 ID 数组JSON 数组格式Delete All布尔标志设为true时删除全部向量默认falseNamespace从中删除向量的命名空间Filter用于选择性删除的过滤条件JSON 格式例如{genre: {$in: [documentary, action]}}示例响应Delete Successful源码实现与删除优先级deleteVectors依据参数按优先级执行三种删除路径query_operations.ts若delete_all的字符串值不区分大小写等于true调用client.deleteAll()否则若提供了filter调用client.deleteMany({ filter: JSON.parse(filter) })按元数据条件删除否则将ids字段表单中 key 为id解析为数组调用client.deleteMany(JSON.parse(id))按 ID 删除。if (delete_all delete_all.toLowerCase() true) { deleteResponse await client.deleteAll(); } else if (filter) { deleteResponse await client.deleteMany({ filter: JSON.parse(filter) }); } else { deleteResponse await client.deleteMany(JSON.parse(id)); }操作七Query Vectors向量相似度查询该操作基于向量相似度检索索引中最接近的 Top K 条记录是 RAG 场景中最核心的检索入口支持稠密检索与混合检索配合稀疏向量。必需参数Index要查询的索引名称Vectors查询向量值例如[0.3, 0.3, 0.3, 0.3, 0.3]注意此处按表单约定以字符串数组形式输入源码中会JSON.parse后作为vector字段Top K返回最相似的向量数量例如3。可选参数Namespace要查询的命名空间Filter查询过滤条件JSON 格式例如{genre: {$in: [documentary, action]}}Include Values布尔值是否在结果中包含向量数值默认falseInclude Metadata布尔值是否在结果中包含元数据默认falseSparse Vector稀疏向量用于混合稠密稀疏检索例如{indices: [1, 5], values: [0.5, 0.5]}。源码实现queryVectors源码函数名拼写为quertVectors将表单输入转换为 Pinecone SDK 的查询参数top_k是字符串需Number()转数值include_values与include_metadata是true/false字符串通过toLowerCase() true转布尔filter、vectors、sparse_vector均为 JSON 字符串需解析const pineconeQueryOptions { topK: Number(top_k), vector: JSON.parse(vectors), ...(filter { filter: JSON.parse(filter) }), ...(include_values { includeValues: include_values.toLowerCase() true }), ...(include_metadata { includeMetadata: include_metadata.toLowerCase() true }), ...(sparse_vector { sparseVector: JSON.parse(sparse_vector) }), }; const queryResponse await client.query(pineconeQueryOptions);实战要点与注意事项综合文档与源码使用该插件时有几点值得留意字符串化的 JSON 与布尔值由于查询面板输入均为字符串插件内部对vectors、ids、metadata、filter、sparse_vector等字段统一使用JSON.parse解析对include_values、include_metadata、delete_all则按true/false字符串比较。输入时必须保证 JSON 语法合法否则操作会以Query could not be completed失败。操作字段 key 与显示名的差异例如 Delete 操作在文档中描述为 IDs但 operations.json 中该字段的 key 实际为id源码也通过options.id读取在编辑器中按表单提示以 JSON 数组形式填写即可。List 的默认分页未填写 Limit 时listPaginated默认返回 10 条数据量大时应配合Pagination Token翻页。Upsert 的向量结构校验写入的每个向量必须同时具备id与values数组缺失会直接报错values的维度必须与索引维度一致。查询索引的依赖连通性测试testConnection依赖账号下存在至少一个索引listIndexes()返回非空而各操作仅需索引名称无需在数据源配置中填写索引。典型的 AI 应用串联在 ToolJet 应用中可先用 Embedding 类插件生成文本向量再通过 Upsert Vectors 写入 Pinecone用户提问时用同一模型生成查询向量经 Query Vectors 检索 Top K 相关片段作为上下文输入给 LLM 完成 RAG 问答。延伸阅读Marketplace 整体安装、启用与移除插件的完整指引docs/docs/marketplace/marketplace_overview.md插件数据源与操作表单定义marketplace/plugins/pinecone/lib/manifest.json、marketplace/plugins/pinecone/lib/operations.json插件服务类与连接管理marketplace/plugins/pinecone/lib/index.ts七大操作实现细节marketplace/plugins/pinecone/lib/query_operations.ts类型与操作枚举定义marketplace/plugins/pinecone/lib/types.ts【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考