SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场pinecone

pinecone

数据与分析

查看项目

更新于 10-16 10:47

技能介绍

Pinecone 向量数据库 API 技能用于存储、查询和管理向量嵌入，适用于需要向量检索能力的场景。当用户提到 "Pinecone"、"vector database"、"vector search" 等内容时可以考虑使用本技能。

认证方式 所有请求都需要在请求头中携带 API key：Api-Key: $PINECONE_TOKEN。官方文档地址为 https://docs.pinecone.io/reference/api/。

前置条件 需要先在 app.vm0.ai/connectors 连接 Pinecone connector。如果请求失败，可运行以下命令进行排查：zero doctor check-connector --env-name PINECONE_TOKEN，或 zero doctor check-connector --url https://api.pinecone.io/indexes --method GET。

索引管理（控制平面，使用 https://api.pinecone.io）

  • 列举索引：GET https://api.pinecone.io/indexes
  • 描述索引：GET https://api.pinecone.io/indexes/<index-name>
  • 创建索引用（Serverless）：POST https://api.pinecone.io/indexes，请求体包含 name、dimension、metric 和 spec（serverless 下指定 cloud 与 region）。支持的度量（metric）有 cosine、euclidean、dotproduct；常见维度包括 1536（OpenAI text-embedding-3-small）、3072（text-embedding-3-large）、768（许多开源模型）。
  • 删除索引：DELETE https://api.pinecone.io/indexes/<index-name> 上述请求均需携带 X-Pinecone-API-Version: 2025-04 请求头。

向量操作（数据平面） Pinecone 数据平面操作针对索引的 host URL 执行，该 URL 在描述索引（Describe Index）时于 host 字段返回，形如 https://<index-name>-<project-id>.svc.<environment>.pinecone.io。需先描述索引获取 host，再在所有数据平面请求中使用该 host。

  • 写入向量（Upsert）：POST <index-host>/vectors/upsert，请求体包含 vectors 数组（每个元素含 id、values 以及可选 metadata）和可选 namespace。values 数组必须与索引维度完全一致；单次 upsert 最多 100 个向量；namespace 可选，省略时使用默认命名空间。
  • 查询向量：POST <index-host>/query，请求体包含 vector、topK、includeMetadata、includeValues 以及可选 namespace。返回 matches 数组，包含 id、score，可选 values 与 metadata。分数为余弦相似度（越高越相似）。
  • 按向量 ID 查询：POST <index-host>/query，请求体使用 id 而非 vector。
  • 按 ID 获取向量：GET <index-host>/vectors/fetch?ids=<id1>&ids=<id2>&namespace=<namespace>。
  • 按 ID 删除向量：POST <index-host>/vectors/delete，请求体包含 ids 数组和可选 namespace。
  • 删除命名空间内全部向量：POST <index-host>/vectors/delete，请求体为 {"deleteAll": true, "namespace": "<namespace>"}。
  • 描述索引统计：GET <index-host>/describe_index_stats，返回总向量数及按命名空间的分布。
  • 列举向量 ID：GET <index-host>/vectors/list?namespace=<namespace>&limit=100，可使用响应中的 pagination_token 翻页。 以上数据平面请求均需携带 Api-Key 与 X-Pinecone-API-Version: 2025-04 请求头。

集合（备份）操作（使用 https://api.pinecone.io）

  • 列举集合：GET https://api.pinecone.io/collections
  • 从索引创建集合：POST https://api.pinecone.io/collections，请求体包含 name 与 source（源索引名）。
  • 描述集合：GET https://api.pinecone.io/collections/<collection-name>
  • 删除集合：DELETE https://api.pinecone.io/collections/<collection-name>

使用指引与限制

  • 索引 host 与控制平面：使用 https://api.pinecone.io 进行索引管理（创建、列举、删除）；使用每个索引的 host URL 进行向量操作（upsert、query、fetch、delete vectors）。
  • 命名空间：命名空间用于在索引内对向量进行分区，默认命名空间为 ""（空字符串）。多租户场景应始终指定命名空间。
  • 维度匹配：每次 upsert 的 values 数组必须与索引维度完全一致，不匹配会返回 400 错误。
  • Upsert 限制：单次 upsert 请求最多 100 个向量，总载荷不超过 2 MB。
  • API 版本头：始终包含 X-Pinecone-API-Version: 2025-04 以固定 API 版本。
  • 索引就绪：创建索引后，需等待 status.ready == true 再进行 upsert，可通过描述索引进行轮询。