Pinecone 向量数据库 Skill
一个 Pinecone index 从建索引那一刻起就锁死在 Vectors / Records / Documents 三套数据平面之一，创建后终身不能迁移也不能混用，选错只能删了重建。另一个最反直觉的发现：query 的 read units 计费只看目标 namespace 的总 GB 数，top_k、include_metadata、include_values 这些参数完全不影响 RU——这和"按返回结果多寡计费"的直觉正好相反。
Api-Key: <PINECONE_API_KEY> 请求头（不是 Bearer），几乎所有请求还要带 X-Pinecone-Api-Version 日期版本头Agent 工具更新 2026-09-21安装
选你用的 Agent，复制命令。
npx -y skills add fxp/skillify --skill pinecone --agent claude-code --yes装到项目的 .claude/skills/；加 -g 装到全局。装完需要你手动执行 /reload-plugins，这一步 Agent 代劳不了。
npx -y skills add fxp/skillify --skill pinecone --agent codex --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill pinecone --agent cursor --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill pinecone --agent opencode --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill pinecone --agent gemini-cli --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill pinecone --agent github-copilot --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill pinecone --agent trae --yes装到项目的 .trae/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill pinecone --agent windsurf --yes装到项目的 .windsurf/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill pinecone --agent qwen-code --yes把 --agent 换成你用的 Agent 标识，可以一次写多个。skills CLI 1.5.25 共支持 79 个，例如 qwen-code、kimi-code-cli、trae-cn、qoder、lingma、cline、roo。
或者让 Agent 自己装
读 https://github.com/fxp/skillify/blob/main/skills/pinecone/prompt.md 并照它执行装对了的标志：references/ 下有 6 份文档。
装好后，可以这样问你的 Agent
这份 Skill 覆盖的典型任务。点一下复制。
6 类能力
每类能力对应一份 reference，Agent 按任务只打开需要的那份。
建索引：三套数据平面选型
Vectors/Records/Documents 三选一且创建后终身不变、serverless 云区域选择、相似度 metric、备份
写入、更新、删除
三套数据平面各自的写入方法、upsert 覆盖写语义、批量限制、从对象存储批量导入
查询与元数据过滤
三套数据平面各自的查询方式、MongoDB 风格操作符全表、Documents API 的 score_by 与 text-match 过滤
混合检索与托管模型
三种混合检索模式怎么选、Pinecone 托管 embedding/rerank 模型、alpha 加权怎么算
命名空间与多租户
命名空间隔离语义与自动创建、namespace-per-tenant vs metadata 过滤的取舍、默认命名空间踩坑
计费、错误与 SDK
RU/WU/存储/egress 四维计费模型、HTTP 错误码表、重试策略、各语言 SDK 包名与版本陷阱
当前事实
整理自官方文档（抓取于 2026-09-21），还没有用真实凭证验证。
| 项 | 值 |
|---|---|
| Base URL 分裂成两个 | 控制面固定 https://api.pinecone.io；数据面没有固定域名，每个索引有自己的 host，必须先 describe_index 拿到 |
| 三选一且终身不变 | Vectors / Records / Documents 三套数据平面创建后不能迁移、不能混用，选错只能删了重建 |
| upsert 语义 | 按 id/_id 覆盖写，不是追加；ID 撞车会静默整条覆盖旧记录，不报错 |
| RU 计费口径 | 1 RU / 1GB 目标 namespace 大小,最低 0.25 RU；top_k/include_metadata/include_values 都不影响 RU |
| Pod-based 索引已停开放 | 自 2025-08 起不再向新客户开放，训练记忆里的 pod_type/replicas/shards 属于遗留能力，新项目一律用 serverless |
照通用经验写容易错的 7 件事
来自官方文档，还没有用真实凭证验证。
- 一个 index 只能属于三套数据平面之一，创建后终身不变。Vectors（经典
dimension/metric）、Records（集成 embedding）、Documents（2026-07 新增，schema 化 + 全文检索）三选一，之后不能迁移也不能混用方法调用。 - upsert 是按 ID 覆盖写，不是追加。用自增/时间戳生成的短 ID、或忘记加租户前缀，会静默覆盖别的记录而不报错。推荐结构化 ID（如
tenant_id#doc_id#chunk_id）。 - 不传
namespace会静默落到默认命名空间，查询查不到数据但不报错。upsert 时忘记传、query 时又显式传了具体 namespace（或反过来），会得到 0 条结果，容易被误判成"索引是空的"或"embedding 没生效"。生产代码永远显式传namespace。 - Read units 的计费只看目标 namespace 的总大小，不看返回了多少结果。
top_k、include_metadata、include_values完全不影响 RU——这和"按返回条数计费"的直觉相反，也是为什么按租户拆分 namespace 通常比单一大 namespace + metadata 过滤更省钱。 - 单索引 dense+sparse 混合检索要求
metric: "dotproduct"，用错 metric 是个静默陷阱。把sparse_valuesupsert 进一个非 dotproduct 索引不会报错，但查询时才会报错——写入阶段完全看不出问题。 cohere-rerank-3.5已于 2026-07-01 标记 deprecated，2026-08-31 起请求被静默路由到cohere-rerank-4-fast。两者返回的相关性分数不可比，如果代码里对 rerank score 设了硬编码阈值要重新校准。- Documents API 的 schema 一旦创建不可修改。不能增删字段，要变更只能建新索引重新灌数据；一次 upsert 请求里只要有一条 document 校验失败,整批都不写入,不是部分成功。