Pinecone 向量库怎么接入：建索引、写入与查询

知识分享

2026-10-30 20:00

27 阅读

Pinecone 是托管式向量数据库，你不需要自己部署服务，核心工作是在控制台建好索引，然后用 API Key 和索引主机地址在代码里写入、查询向量。
本文按“建索引 → 拿连接信息 → 写入 → 查询 → 排错”的顺序走一遍，适合刚开始把向量检索接进项目的读者。

先确认索引参数再动手

Pinecone 的索引在创建时就确定了向量维度和相似度度量，后面写入的向量必须与维度完全一致，否则会直接报错。
动手前先确认三件事：

嵌入模型输出的维度，例如常见模型输出 768、1024 或 1536 维，必须与索引维度一致。
相似度度量选 cosine、dotproduct 或 euclidean，文本检索通常用 cosine。
是否使用 serverless 索引：serverless 需要指定云厂商和区域，适合大多数新项目；pod 模式适合对资源有明确控制需求的场景。

在 Pinecone 控制台点击 Create Index，
填写索引名、
维度、
度量方式，
选择 serverless 后指定云与区域，
创建完成后在索引详情页可以看到 Host 地址，
这个地址后面要填进代码。

安装 SDK 并配置连接

Python 环境建议使用 3.8 及以上版本，先安装官方 SDK：

pip install pinecone

连接时用 API Key 初始化客户端，API Key 在控制台的 API Keys 页面创建。
不要把 Key 硬编码进代码仓库，放到环境变量里：

export PINECONE_API_KEY="你的_api_key"

import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.Index("my-index")
print(index.describe_index_stats())

如果初始化时报认证失败，优先检查 Key 是否复制完整、是否属于当前项目；
如果连接超时，检查本机网络能否正常访问 Pinecone 的接口域名。

写入向量与 metadata

写入时每条记录包含一个唯一 id、一个向量和可选的 metadata。
metadata 用来做过滤和展示，例如存原文、来源、分类。
下面写入两条三维示例向量：

index.upsert(
    vectors=[
        {"id": "doc-1", "values": [0.12, 0.34, 0.56], "metadata": {"source": "faq", "lang": "zh"}},
        {"id": "doc-2", "values": [0.98, 0.11, 0.02], "metadata": {"source": "blog", "lang": "zh"}},
    ],
    namespace="demo"
)

注意 values 的长度必须等于索引维度，示例里是 3 维，实际项目要换成你模型的真实维度。
写入后可以用 describe_index_stats() 查看向量数量是否增加，确认数据已进入指定 namespace。

查询相似向量并验证结果

查询同样要传一个与索引维度一致的向量，可以带 top_k 和 metadata 过滤条件：

result = index.query(
    vector=[0.10, 0.30, 0.52],
    top_k=2,
    include_metadata=True,
    filter={"source": {"$eq": "faq"}},
    namespace="demo"
)
for match in result["matches"]:
    print(match["id"], match["score"], match["metadata"])

验证时看三点：返回条数是否等于 top_k（数据不足时会少于 top_k）、score 是否按从高到低排列、metadata 是否符合过滤条件。
如果结果为空，先确认 namespace 是否写对，再确认过滤字段在写入时确实存在。

常见报错与避坑

维度不匹配是最常见的错误，报错信息通常包含 dimension 字样。
处理方式是打印嵌入向量的长度，与索引维度逐一核对，不要靠猜。

namespace 写混会导致查不到数据：写入用了一个 namespace，查询用了另一个，看起来像“数据丢了”。
建议在配置里统一管理 namespace 常量。

metadata 过滤过严会让查询返回空结果，调试时先去掉 filter 验证基础查询是否正常，再逐步加条件。

另外，批量写入时注意控制单次请求的向量数量，数据量大时分批 upsert，并在每批后检查返回结果，避免一次性提交过多导致超时。
删除或覆盖数据前确认 id 规则，Pinecone 中相同 id 的 upsert 会覆盖旧记录。

上线前的检查清单

API Key 只放在服务端环境变量中，不暴露到前端代码。
索引维度、度量方式与嵌入模型保持一致，并在配置文件中集中定义。
写入和查询使用同一 namespace，过滤字段在写入时已填充。
用 describe_index_stats() 核对向量数量，用一次真实查询核对返回顺序和 metadata。
为请求设置重试和超时处理，网络抖动时不要让业务直接失败。

按以上步骤执行后，你已经完成一次完整的 Pinecone 使用流程：建索引、连接、写入、查询和验证。
后续接入真实业务时，重点是把嵌入模型输出维度、namespace 和 metadata 结构固定下来，减少后期返工。

Chroma 向量数据库怎么用：Python 本地写入与查询验证

Faiss 向量检索怎么上手：Python 建索引与相似度查询