Pinecone：它是什么以及如何使用

我们的利益几乎为零，但还是值得声明：我们是 Geonode，卖代理，这与向量数据库毫无关系。唯一相邻之处是：检索系统需要有东西可检索；如果内容来自公开网络，总得有人去采集——那是我们这条流水线的一端，与数据库完全分开。本文没有任何内容要求你向我们购买产品；反对托管向量数据库的那一节之所以写进去，是因为它常常才是正确答案。

向量数据库做什么

普通数据库做精确匹配。向量数据库按相似度匹配。

机制是：embedding 模型把文本、图像或其他内容转换成一串数字——一个向量——并摆放得让相似的东西彼此靠近。找相关结果就变成找邻近的点，是几何问题，而不是字符串匹配。

Pinecone 自称是 “the vector database for AI agents and applications, built for semantic search, knowledge retrieval, and long-term memory at scale”，能力被表述为在毫秒级 “through billions of items for similar matches to any object”。

它从库变成基础设施的原因是规模。用暴力法把查询与一百万个向量比较既直接又慢；要在毫秒内完成，需要近似最近邻 indexes，而在规模上可靠地运行这些 indexes 是运维问题。托管服务卖的就是这个。

主导用例是检索增强生成：给定用户的问题，从你自己的文档中找出最相关的段落，交给语言模型当上下文。数据库提供的是“找出相关段落”这一步。

Indexes、文档与 records

Pinecone 的数据模型已经改过形状，值得按当前形态来理解。

Index 是数据所在之处。 文档 解释道：“a serverless index holds your data as documents or records, depending on how the index was created: an index created with a document schema holds documents, while an index created with a dense or sparse vector type holds records”。

文档 schema 让一个 index 能干几件事。 文档写道：“a single index with a document schema can mix multiple ranking field types: a dense_vector field for semantic search, a sparse_vector field for sparse-vector retrieval, and one or more string fields with full_text_search enabled for full-text search with BM25 and Lucene queries.”

元数据无需声明。 “Any other fields you upsert are stored as metadata, automatically indexed for filtering — no schema declaration required.”

设计指导说得很直白：“One index per use case is the typical pattern. Because a document can combine vectors, text, and metadata in the same record, a single index often covers what previously required two — pick the ranking signal per query with score_by.”

最后这一点才关键。全文检索可以和向量检索放在同一个 index 里——“BM25 token matching with Lucene query syntax over text fields in your schema”，由 Pinecone 处理 “tokenization, IDF, and length normalization at index time and BM25 scoring at query time”。不需要单独的搜索引擎，关键词那一半也不需要模型。

实际后果是：混合检索——把语义相似度与精确关键词匹配结合起来——是查询时的选择，而不是架构选择。这很重要，因为纯向量检索在精确标识符、产品代码和罕见专有名词上出了名地弱，而 BM25 恰恰擅长这些。

Namespaces

这个功能对多租户应用的设计影响最大。

文档：“Within an index, records are partitioned into namespaces, and all upserts, queries, and other data read and write operations always target one namespace.”

它点出两个好处。多租户 — “when you need to isolate data between customers, you can use one namespace per customer and target each customer's writes and queries to their dedicated namespace.” 以及 更快的查询 — “when you divide records into namespaces in a logical way, you speed up queries by ensuring only relevant records are scanned.”

三条运维注意事项。

它们是隐式创建的。 “Namespaces are created automatically during upsert. If a namespace doesn't exist, it is created implicitly.” 很方便，但也意味着 namespace 名称打错会得到一次静默的空搜索，而不是报错。

上限取决于套餐。 “Namespaces per serverless index vary by plan. On the Standard and Enterprise plans, Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, contact Support.”

隔离才是重点。 凡是存放多个客户数据的场景，一个客户一个 namespace 就是模式；跨租户泄漏于是变成把一个参数写对，而不是把过滤器写对。

Embeddings：用你的还是他们的

两种做法，选择有真实后果。

集成 embedding。 文档用四步描述：“Create an index that is integrated with one of Pinecone's hosted embedding models. Upsert your source text. Pinecone uses the integrated model to convert the text to vectors automatically. Search with a query text. Again, Pinecone uses the integrated model to convert the text to a vector automatically.”

更简单——你发文本、收结果，不必自建 embedding 流水线。一条写明的限制：“Indexes with integrated embedding do not support updating or importing with text.”

自带向量。 你自己跑 embedding 模型，创建与其特性匹配的 index，直接 upsert 向量，并用 “the same external embedding model to convert a query to a vector”。

工作更多，控制也更多。你可以用 Pinecone 未托管的模型，出于隐私或成本在本地做 embedding，并且——关键是——按自己的节奏换模型。

对很多人起决定作用的考量： 更换 embedding 模型意味着把一切重新 embedding。不同模型的向量不可比，所以切换等于全量重建 index。集成 embedding 让初次搭建变容易，也把决策绑在供应商的模型目录上；自带向量让搭建更难，但选择权在你。两者都没错，值得有意识地决定，而不是跟着你看到的第一个教程走。

大规模加载数据

一条容易漏掉、发现时很贵的成本提示。

文档写得很具体：“To control costs when ingesting large datasets (10,000,000+ records), use import instead of upsert.”

有两条摄入路径。Upsert 通过 API 发送 records。Import 从对象存储读取 Parquet 文件，文档称之为 “the most efficient and cost-effective way to load large numbers of records into an index”。

既然写入按百万 write units 计费，大规模初次加载时这两条路径的差额是真实数字，不是四舍五入误差。如果你要在数百万 records 上建 index，从一开始就规划 import 路径——在一次昂贵的首次加载后再改造，是没人需要付两次的教训。

实践入门

第一次实现的形态，以及嵌在其中的决策。

创建 index 并 upsert。 使用集成 embedding 时流程很短——你根本碰不到向量：

from pinecone import Pinecone

pc = Pinecone(api_key=API_KEY)

index = pc.Index(host=INDEX_HOST)

index.upsert_records(
    namespace="customer-42",
    records=[
        {"_id": "doc-1", "chunk_text": "Refunds are processed within 14 days.",
         "source": "policy.pdf", "page": 3},
        {"_id": "doc-2", "chunk_text": "Shipping to the EU takes 3-5 working days.",
         "source": "shipping.pdf", "page": 1},
    ],
)

注意 source 和 page 从未声明。排名字段以外的任何东西都会作为元数据存储并自动为过滤建立索引，这意味着以后可以加字段，不必迁移。

带过滤器查询：

results = index.search(
    namespace="customer-42",
    query={"inputs": {"text": "how long do refunds take?"}, "top_k": 5,
           "filter": {"source": {"$eq": "policy.pdf"}}},
)

这段代码里有三个决策值得有意识地做。

Chunk 大小。 你 upsert 的文本就是返回的单位，所以切分方式决定模型看到什么。太小会丢掉让内容有意义的上下文；太大则在相关句子旁边带回大量无关文本。没有万能答案——几百词并带一点重叠是合理起点，测量胜过猜测。

元数据就是你的过滤面。 存下以后可能用来收窄的任何东西：来源文档、日期、章节、语言、访问级别。upsert 时加上不花钱；事后再加意味着重新 upsert。

从一开始就按租户一个 namespace。 事后往单 namespace 的 index 里补隔离，意味着按正确目标把一切重新 upsert。一开始就用 namespaces 只多一个参数，却去掉整整一类未来事故。

并保留源文本。 把原始文档存在你控制的地方，连同切分代码一起。如果你更换 embedding 模型、chunk 大小或切分策略——而你一定会——重建 index 就是再跑一遍，而不是考古。

定价，已核实

来自 Pinecone 自己的 定价页，核对于 2026 年 9 月。做预算前请再核实。

规划时有四点值得注意。

免费档确实够用来评估。 两 GB 存储和每月一百万 read units，足以在相当规模的文档集上做出真正的原型。

Builder 是一口价，不是最低消费。 每月 20 美元、上限固定，可预测性是按量套餐没有的——适合小型生产应用，你更想要一张能预估的账单。

Standard 和 Enterprise 是带超量的最低消费。 50 美元和 500 美元是下限，不是上限。实际费用在此之上按用量计。

每百万 units，读大约是写的四倍价。 读是每百万 16–18 美元，写是 4–4.50 美元，读多的应用——大多数检索系统都是——会发现查询主导账单。因此缓存高频查询是直接的成本杠杆，而不只是延迟优化。

Enterprise 增加 99.95% 可用性 SLA、bring-your-own-cloud 部署、private endpoints 和审计日志——采购流程通常在意的那一套，对原型毫无意义。

何时不需要托管向量数据库

供应商不会写的一节，写进去是因为它常常就是答案。

当语料很小。 大约十万向量以下，内存里的暴力相似度搜索在普通硬件上已经够快。一个 NumPy 数组加一次点积就能在毫秒内给出答案，零成本，还从架构里去掉一个外部依赖。需要近似索引的门槛比多数人以为的更高。

当你已经在跑 Postgres。 pgvector 扩展把向量相似度搜索加到你已经在运维和备份的数据库上。对许多应用这才是正确答案：少一套系统，与其他数据事务一致，也没有单独账单。

当嵌入式库就够。 FAISS 一类的库或本地 vector store 能在单进程里处理数百万向量。如果数据装得进一台机器、查询量也不大，托管服务解决的是你并没有的运维问题。

当关键词搜索就行。 相当一部分“我们需要语义搜索”，其实 BM25 就能很好满足：更便宜、更快、完全可解释，而且更擅长精确标识符。先试它——并且注意，如果你最终用了 Pinecone，它的全文检索在同一个 index 里就能覆盖这一点。

当你还没测量检索质量。 数据库通常不是检索系统的限制因素。切分策略、embedding 模型选择和查询表述重要得多，这三者都可以用一百行本地代码先测，再做任何基础设施决定。

支持托管服务的理由真实而具体：数千万向量、需要稳定低延迟的查询量、多租户隔离，以及一个宁愿不去运维分布式 index 的团队。如果其中两条或以上成立，它就配得上这笔费用。

常见问题

Pinecone 用来做什么？

面向 AI 应用的语义搜索、知识检索和长期记忆。主导模式是检索增强生成：找出与问题最相关的自有文档段落，作为上下文提供给语言模型。

Pinecone 免费吗？

有免费 Starter 套餐：最多 2 GB 存储、每月 2M write units 与 1M read units，以及 1 GB egress。确实够在承诺付费套餐之前做出并评估真正的原型。

Pinecone 多少钱？

Starter 免费；Builder 每月一口价 20 美元、上限固定；Standard 每月最低用量 50 美元，Enterprise 每月 500 美元；两者存储均为每月每 GB 0.33 美元，写入每百万 units 4–4.50 美元，读取每百万 16–18 美元，egress 在 100 GB 之后每 GB 0.10 美元。

Pinecone 里的 namespace 是什么？

Index 内的分区。每次读写都精确针对一个 namespace，因此它是多租户隔离的标准机制——每客户一个 namespace——也是性能优化，因为查询只扫描相关分区。

该用集成 embedding 还是自己的向量？

集成 embedding 更简单：发文本，Pinecone 来转换。自带向量给你模型选择权和可移植性，这很重要，因为更换 embedding 模型必须把一切重新 embedding。集成 indexes 也不支持用文本做 update 或 import。

Pinecone 能做关键词搜索，而不只是向量搜索吗？

能。启用 full_text_search 的字符串字段支持带 Lucene 查询语法的 BM25 排序，与 dense 和 sparse 向量在同一个 index 中，打分方法按查询选择。这很重要，因为纯向量检索对精确标识符和罕见词处理很差。

如何高效加载数百万 records？

用对象存储的 import，而不是 upsert。文档对超过一千万 records 的数据集明确推荐这条路，并称之为最经济的路径；鉴于写入按百万 units 计费，这一点很重要。

我到底需不需要向量数据库？

常常不需要。大约十万向量以下，内存暴力搜索已经够快且免费。如果你已经在跑 Postgres，pgvector 可以避免另搞一套系统。相当一部分“语义搜索”需求，关键词搜索就能很好满足，而且更便宜、更可解释。

总结

Pinecone 是托管向量数据库，但已经长成更广的东西：一个 index 现在可以同时容纳 dense 向量、sparse 向量和全文字段，排序方法按查询选择。这次合并是最近最有用的变化，因为混合检索不再是架构决策，而成了一个参数。

三件事决定你该如何围绕它设计。Namespaces 是隔离与性能机制，而且是隐式创建的——打错 namespace 会返回空结果而不是报错。Embedding 的选择比看起来更黏：换模型意味着把整个语料重新 embedding。读比写贵好几倍，因此在读多的系统里，查询缓存是直接的成本杠杆。

定价透明，免费档大到足以回答真正的问题：检索质量对你的用例是否够好。这个问题不在数据库上——切分、embedding 选择和查询表述才主导它——而且可以在任何基础设施存在之前在本地回答。

这就是诚实的收尾。托管向量数据库在规模、多租户、或你不愿运维分布式 index 时才站得住。低于这个门槛，内存里的数组，或你已经在跑的 Postgres 上的扩展，就能免费完成工作；在签约任何一边之前，值得先搞清楚自己属于哪种情况。