Pinecone 向量数据库手册

适用版本：Serverless（On-Demand）架构 + Python SDK v10.3.0（对应 2026-07 API，核实于 2026-11） 许可与形态：闭源 SaaS 商业托管；全托管 Serverless（另有 Dedicated Read Nodes / BYOC） 一句话定位：买的是运维责任转移 —— 不建集群、不管分片副本与索引重建，按用量付费，并接受 SDK 与 API version 绑定 约定：$ 普通用户、# root 或 sudo、<xxx> 为占位符；标 ⚠️ 的是高危操作。 更新时间：2026-11（版本与 API 变化快，执行前请以官方文档复核）

目录

1. 它是什么、什么时候选它
2. 版本、许可与官方入口
3. 安装与启动
4. 核心概念与数据模型
5. 快速上手：完整 CRUD 示例
6. 索引与检索进阶
7. 生产部署与运维
8. 高频故障与排障
9. 常见坑与避坑清单
10. 速查表
11. 参考与延伸

1. 它是什么、什么时候选它

1.1 定位与架构

Pinecone 是闭源 SaaS 全托管向量数据库，当前架构是 Serverless（On-Demand），pod-based 已是 legacy。你没有服务器、没有容器、没有索引文件，只有一个 API key 和一个控制面域名。

形态补充：另有 Dedicated Read Nodes 与 BYOC（2026-08-25 GA）；存量 pod 索引仍可 describe / configure / delete，但新签 Standard / Enterprise 自 2025-08-18 起不能创建 pod 索引，API version 2026-07 的 SDK 创建 pod 索引直接返回 400。

1.2 核心命题：托管服务买的是运维责任转移

避坑：「托管」不等于「零运维」。责任只是从「集群运维」转成「凭证、成本、合规、SDK 生命周期」四件事，第 7 章全部围绕这四件展开，而不是教你自己搭集群。

1.3 与自建 / 其他云托管的本质差别

与自建 Milvus / Qdrant 相比，Pinecone 不暴露服务端版本（只有 API version）、用专有 SDK 而非 pymilvus / 标准协议、按四维用量计费、数据落在厂商境外 region；与 03 分册的索引库相比，它是完整托管服务而非进程内库。

1.4 适合 / 不适合

适合：不想养向量库运维团队；流量波动大、需要弹性；RAG / 推荐 / 语义检索快速上线；能接受海外 region 与按量账单；团队用 Python 3.10+。

不适合：数据不得出境或有强合规 / 等保要求且无法用 BYOC 解决；需要自建多可用区与自定义内核调优；强依赖标准协议（pymilvus / SQL）以便随时迁出；预算固定、读量极大且 Egress 敏感；需要本地私有化部署。

1.5 规模与链路位置（经验值，非官方承诺）

官方资料未给出 QPS / 条数 / 延迟的官方承诺值，容量与性能以控制台与实测为准；示例用 3~4 维，实际常见 768 / 1024 / 1536。在线链路：业务侧做 embedding → index.documents.upsert → 等待异步索引 → index.documents.search 取回文档与 metadata → 重排 / 拼 prompt。文档管理、权限、审计仍在调用方。

1.6 计费维度、额度与限制

1.7 网络与合规（数据出境）

Pinecone 是海外 SaaS，数据落在厂商 region；中国企业把数据写进去即构成数据出境，需自行评估《个人信息保护法》《数据安全法》相关的出境路径与合规义务（经验性表述，非法律结论，以法务与官方合规文档为准）。

• 网络：控制面 api.pinecone.io 走公网 HTTPS，企业出口需放行；v10.3.0 起 gRPC proxy_url 只接受 http://。
• 缓解：BYOC（2026-08-25 GA）把部署放到自有云账号，可缓解部分合规诉求；具体能力与区域清单官方资料未给出，以官方文档为准。
• 混合架构：若同时使用国内云向量库（见 国内云向量数据库.md），要划清「哪些数据出境、哪些留境内」的边界。

1.8 SDK 绑定与迁移成本

避坑：Pinecone 没有 pymilvus / SQL 这类行业标准协议，迁出成本主要不在数据（可导出），而在接入层与运维脚本全部重写。选型时把「未来能不能走」算进成本。

2. 版本、许可与官方入口

2.1 版本状态表（版本号分属多条线，不可混用）

2.2 许可与商业边界

闭源 SaaS；SDK 自 v3.0.0 起为 Apache-2.0（仅客户端 SDK，不是服务端许可）。分层：Starter 免费 / Builder / Standard / Enterprise。企业特性与 SLA 条款以官方为准。

2.3 官方入口表

2.4 版本识别命令

没有服务端版本号，只能识别客户端：

$ pip show pinecone
$ python -c "import os, pinecone; print(pinecone.__version__ if hasattr(pinecone, '__version__') else 'see pip show')"

服务端版本 / 集群引擎版本不对外暴露，见 2.5。

2.5 「没有版本号、只有 API version」的运维含义

避坑：把 SDK 版本当「服务端版本」写进变更单是错的。生产要同时 pin SDK 版本、记录 API version、订阅 release notes，并把 SDK 升级纳入回归测试范围。

2.6 近两年重要变更与弃用提醒

版本差异：pinecone.init() → Pinecone()；pc.Index() → pc.index()；2026-07 API 用 SchemaBuilder + index.documents.*；pod-based 已 legacy；v10.0.0 把 Documents API 毕业到主客户端；v10.3.0 起 gRPC proxy_url 只接受 http://；老的 create_index(..., spec=ServerlessSpec(...)) 在 v10 仍可用且未弃用。

3. 安装与启动

3.1 前置条件

Python 3.10+；一个 Pinecone 账号与 API key；企业网络出口放行 api.pinecone.io 的 HTTPS。无本地服务、无容器、无端口监听。

3.2 方式一：pip 安装客户端（完整命令）

$ python -m pip install --upgrade pinecone
$ export PINECONE_API_KEY="<YOUR_API_KEY>"
$ python -c "import os; print('key set:', bool(os.environ.get('PINECONE_API_KEY')))"

避开：不要把 API key 写进代码或提交到仓库；用环境变量 / 密钥管理服务注入。

3.3 方式二：云控制台创建索引 + 客户端连通

控制台侧在 Web UI 创建 Serverless 索引（无本地命令，操作步骤以控制台为准），客户端侧用 pc.indexes.describe 验证就绪与连通：

$ python -c "import os; from pinecone import Pinecone; pc = Pinecone(api_key=os.environ['PINECONE_API_KEY']); print(pc.indexes.describe(name='<INDEX_NAME>').status.ready)"

避坑：索引刚创建时 status.ready 可能为 False，必须轮询等待；文档 upsert 后也是异步索引，要再等一段时间才查得到。

3.4 方式三：Docker / Helm

不适用：全托管 SaaS，没有官方自托管镜像。若需要 Docker / Helm，说明应选自建产品（见 03 分册或 Milvus 分册）。

3.5 目录与端口表 / 健康检查 / 生产最小配置

4. 核心概念与数据模型

4.1 术语对照表

4.2 数据模型层级与字段

组织 / 项目 → Index（SchemaBuilder 定义 schema）→ Namespace → Document（_id + dense vector 字段 + 其余字段进 metadata）。官方 Quickstart 的 SchemaBuilder().add_dense_vector_field(name="embedding", dimension=1024, metric="cosine") 定义 dense 向量字段；非 schema 字段（如 text）自动进 metadata。

4.3 距离度量与方向

官方资料未给出 cosine / dotproduct / euclidean 的打分方向与取值范围。经验上 cosine / dotproduct 类相似度越大越相似、euclidean 类距离越小越相似，但分数语义与阈值以官方文档为准，不要照搬其他库的阈值。

4.4 索引类型与关键参数表

4.5 写入 → 建索引 → 可检索的生命周期

pc.indexes.create(name=..., schema=schema) 建索引异步就绪，需轮询 status.ready；index = pc.index(name=...) 拿句柄；index.documents.upsert(...) 写文档异步索引（官方 Quickstart 用 time.sleep(5) 等待）；之后 index.documents.search(...) 才稳定可检索；更新为同 _id 再 upsert，同样异步；清理为删除索引（方法名见第 11 章）。

4.6 一致性模型

文档写入为异步索引，存在「写完立刻查不到」的窗口；官方 Quickstart 用固定 time.sleep(5) 等待，生产应改为轮询 / 重试而非死等固定秒数。读己之写的一致性级别官方资料未明确，以官方文档为准。

5. 快速上手：完整 CRUD 示例

说明：以下按官方 Quickstart（2026-07 API，Bring your own vectors）的当前写法给出，import 齐全、变量有定义。示例用 4 维向量便于直接运行；官方 Quickstart 用 dimension=1024，实际常见 768 / 1024 / 1536。

5.1 完整可运行示例（Python 3.10+）

import os
import time
from pinecone import Pinecone, SchemaBuilder

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
INDEX_NAME, NS = "byo-vectors", "__default__"
# C：创建集合（schema 定义 dense 向量字段）
schema = (SchemaBuilder()
          .add_dense_vector_field(name="embedding", dimension=4, metric="cosine")
          .build())
if not pc.indexes.exists(name=INDEX_NAME):
    pc.indexes.create(name=INDEX_NAME, schema=schema)
while not pc.indexes.describe(name=INDEX_NAME).status.ready:
    time.sleep(2)
index = pc.index(name=INDEX_NAME)          # 用 pc.index()，不是 pc.Index()
# U/C：插入文档（非 schema 字段 text / category 进 metadata）
q = [0.1, 0.2, 0.3, 0.45]
index.documents.upsert(namespace=NS, documents=[
    {"_id": "1", "embedding": [0.1, 0.2, 0.3, 0.4], "text": "三国演义", "category": "history"},
    {"_id": "2", "embedding": [0.9, 0.1, 0.2, 0.1], "text": "三体",     "category": "scifi"},
])
time.sleep(5)                              # 文档异步索引，需等待
# R：相似度检索
resp = index.documents.search(
    namespace=NS, top_k=3,
    score_by=[{"type": "dense_vector", "fields": ["embedding"], "values": q}],
    include_fields=["*"])
print("命中 =", resp)
# 带标量过滤检索：服务端过滤参数名未查到官方明确说明，此处演示客户端后过滤兜底
hits = getattr(resp, "result", None) or getattr(resp, "documents", None) or []
print("过滤命中 =", [d for d in hits if isinstance(getattr(d, "fields", None), dict)
                    and d.fields.get("category") == "history"])
# U：更新（upsert 语义，同 _id 再写一次即覆盖）
index.documents.upsert(namespace=NS, documents=[
    {"_id": "1", "embedding": [0.1, 0.2, 0.3, 0.4], "text": "三国演义（修订）", "category": "history"}])
time.sleep(5)
# D：单文档删除方法名官方未明确，以官方为准；此处用删除索引做清理
# 清理（与 pc.indexes.create 对称的资源式操作，方法名以官方文档为准，见第 11 章）
pc.indexes.delete(name=INDEX_NAME)
print("已请求删除索引", INDEX_NAME)

避坑：旧教程会写成 import pinecone; pinecone.init(api_key=..., environment=...)，然后 pc.Index("...") 再 index.upsert(vectors=[...]) / index.query(...)。当前正确写法是 Pinecone() 构造客户端、pc.index() 取句柄、index.documents.upsert/search；2026-07 API 还要先用 SchemaBuilder 定义 schema。pc.index() 才能访问 index.documents，pc.Index() 不行。老的 create_index(..., spec=ServerlessSpec(...)) 在 v10 仍可用且未弃用，但新项目建议按官方 Quickstart 走 pc.indexes.create。

5.2 输出怎么读

search 返回命中文档集合；score_by 决定打分字段，include_fields=["*"] 取回全部字段（含 metadata 里的 text / category）。分数语义与阈值以官方文档为准（第 4.3 节）；_id 是业务主键，不是行下标。

⚠️ 危险：time.sleep(5) 只是官方 Quickstart 的演示写法，不是可见性保证。生产必须轮询或重试，否则会出现「写入成功但查不到」的偶发故障。

等价 REST / cURL 示例：官方资料未给出端点与请求体的逐字写法，为避免臆造 URL / 参数，以 https://docs.pinecone.io 的 API Reference 为准，本篇不编造。

6. 索引与检索进阶

6.1 参数调优表

官方资料未给出各参数的默认值与推荐范围，除「每文档 40KB 上限」「metric 三选一」外均为经验性表述，以官方文档与实测为准。

6.2 召回 / 延迟 / 成本取舍

Serverless 的索引结构由厂商托管，用户侧主要可调 top_k、include_fields、namespace 与文档大小。调大 top_k 提升召回上限但同时抬升 Read Units 与返回体（Egress 自 2026-09-01 起计量）；include_fields=["*"] 方便但费流量。没有统一最优值，用自己的 query 集压测召回与 p99，并同步看账单。

6.3 标量过滤的 pre/post-filter 行为

官方资料只明确「非 schema 字段存 metadata，每文档 40KB 上限」，未给出服务端过滤的参数名与 pre/post 行为。第 5 章演示的是客户端后过滤兜底：取回候选后按 metadata 过滤。

⚠️ 危险：后过滤会让返回条数变少，top_k 取小、过滤条件 Selective 时可能一条不剩，且白白消耗 Read Units / Egress。生产应优先使用服务端过滤（具体参数以官方文档为准），或放大 top_k 再截断。

6.4 混合检索 / 多向量 / 稀疏 / 重排 / 量化

官方资料未提供 Pinecone 的 BM25 / 稀疏 / RRF / 量化压缩逐字能力说明，均以官方文档为准，本篇不臆造方法名与参数。可确定的是：混合检索若需自建 BM25 侧，重排与融合逻辑仍在调用方，这属于「托管不转移」的部分。

6.5 容量估算：不估内存，估账单

托管服务不做内存 / 磁盘容量规划，改为计费容量估算：存储 = 总 GB × $0.33/GB/月（10 GB → $3.3/月）；Write Units = 写入量（百万）× $4–4.5（2 百万 → $8–9）；Read Units = 查询量（百万）× $16–18（1 百万 → $16–18）；Egress = 返回流量 GB × $0.10/GB（50 GB → $5）；文档数上限按「总容量 ÷ 单文档大小（≤40KB）」换算，以实测为准。

避坑：2026-09-01 起 Egress 用尽会阻断读，账单监控不是财务问题而是可用性问题（见第 7.5 节）。以上单价来自官方资料定价页，实际以官网为准。

7. 生产部署与运维

7.1 前提：不自己搭集群

本章不写「装集群 / 配副本 / 调分片」—— 那些是 Pinecone 的责任。你要运维的是四件事：凭证（API key 申请、分发、轮换、泄露处置）、成本（四维度计量监控与告警）、合规（数据出境评估、区域选择、BYOC 评估）、SDK 生命周期（pin 版本、记录 API version、订阅 release notes、升级回归）。

7.2 备份与恢复

⚠️ 危险：托管不等于免备份。删索引 / 误覆盖前先导出，源数据不在自己手里等于没有兜底。

7.3 多可用区 / 高可用

高可用、多可用区、故障转移由 Serverless 架构与厂商负责；用户不配副本、不做跨区切换。需要更高等级时评估 Dedicated Read Nodes / BYOC，具体能力与区域清单以官方文档为准。健康检查用 pc.indexes.describe(name=...).status.ready 与云控制台状态页。

7.4 密钥轮换

⚠️ 危险：一次性全量替换 key 会造成线上瞬时鉴权失败，必须灰度并保留旧 key 直至新 key 全量生效。

7.5 成本监控（可用性级）

7.6 升级与跨版本迁移

无服务端可升级。你要做的是：pin pinecone== 版本 → 记录 API version（2026-07）→ 订阅 Release Notes / pricing 页 → SDK 升级前在预发跑回归（重点覆盖 pc.indexes.* / index.documents.* 行为变化）→ 灰度发布。跨 API version 的行为差异（如 pod 索引创建返回 400）要写进回归用例。

版本差异：v9.0.0 total rewrite、v10.0.0 对应 2026-07 API、v10.3.0 gRPC proxy_url 只接受 http://，这三次都可能让旧脚本报错。

7.7 安全基线 / 网络 / 日志

系统级服务管理（systemd / 防火墙基础）属通用运维，见根目录手册，本篇不重复。

8. 高频故障与排障

9. 常见坑与避坑清单

1. 现象：pinecone.init(api_key=..., environment=...) 报错。原因：v3.0.0 起被 Pinecone() 取代。怎么做：改 pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])。
2. 现象：pc.Index("...") 拿不到 index.documents。原因：只有 pc.index() 才能访问 Documents API。怎么做：统一用 pc.index(name=...)。
3. 现象：照旧教程 index.query(vector=..., top_k=...) 失败。原因：2026-07 API 官方 Quickstart 走 index.documents.search(namespace=..., top_k=..., score_by=[...]) + SchemaBuilder。怎么做：按第 5 章当前写法重写。
4. 现象：新项目想建 pod 索引被拒 400。原因：pod-based 已 legacy，2026-07 API 创建返回 400。怎么做：用 Serverless；存量 pod 只做 describe / configure / delete。
5. 现象：文档写入后立刻查不到。原因：文档异步索引。怎么做：生产用轮询 / 重试，别把 Quickstart 的 time.sleep(5) 当保证。
6. 现象：大文档写入失败。原因：每文档 40KB 上限。怎么做：拆 chunk，别把整篇文本塞 metadata。
7. 现象：metric 用了别的值报错。原因：仅 cosine / dotproduct / euclidean。怎么做：三选一，且与 embedding 模型匹配。
8. 现象：某天读请求突然全失败。原因：2026-09-01 起计量 Egress，用尽会阻断读。怎么做：把 Egress 余额纳入可用性告警（第 7.5 节），收敛 include_fields。
9. 现象：账单超预期。原因：四维计量（存储 / WU / RU / Egress）叠加，新套餐不再赠 $250 bulk import credit。怎么做：四维度分别设预算告警。
10. 现象：把 SDK 版本当服务端版本写进变更单。原因：没有版本号，只有 API version。怎么做：pin SDK + 记录 API version + 订阅 release notes（第 2.5 节）。
11. 现象：SDK 升级后线上脚本报错。原因：v9 total rewrite、v10 API 变更、v10.3.0 proxy_url 只接受 http://。怎么做：升级前跑回归，灰度发布。
12. 现象：以为 create_index(spec=ServerlessSpec(...)) 被弃用要改。原因：该写法在 v10 仍可用且未弃用。怎么做：不必强行迁移，但新项目按官方 Quickstart 走 pc.indexes.create。

⚠️ 危险：第 8 条会直接造成线上读中断，第 9 / 7.2 节的备份缺失会让数据不可恢复；第 1、2、3、11 条属于旧教程误导的典型 API 变更，升级 / 迁移时必须专项回归。

10. 速查表

常用端口与路径小表

11. 参考与延伸

11.1 官方文档链接清单

11.2 与本册其他产品的关系

• 同属「托管服务买的是运维责任转移」：Zilliz-Cloud.md（全托管 Milvus，直接用 pymilvus）、国内云向量数据库.md（境内合规路线）。
• 想用标准协议降低迁移成本：自建 Milvus / Zilliz Cloud（pymilvus）、pgvector（SQL），见对应分册。
• 不想要托管、只想要索引内核：见 03 分册 Faiss.md、hnswlib-Annoy-ScaNN.md。

11.3 进阶阅读方向

Serverless 向量库的按量成本建模（WU/RU/Egress）；异步索引可见性与幂等写入设计；API version 驱动的回归测试体系；数据出境合规与 BYOC 评估；从专有 SDK 迁往标准协议的改造路径。

11.4 本篇「未核实 / 以官方为准」事项

官方资料「六、明确未核实清单」8 条中没有 Pinecone 条目；本篇所引版本、API、单价、URL 均来自官方资料已核实内容。以下为执行前仍需以官方为准的事项，正文未写成确定结论：