Pinecone怎么用 云向量数据库入门教程

Pinecone是一个云端的向量数据库，不用自己部署服务器就能存和搜向量，特别适合给AI应用加记忆和语义搜索。你可以把文本先转换成向量，再交给索引保存；用户提问时，把问题也转换成向量，找出语义最接近的内容。下面用Python走一遍从建索引到查询的基本流程。

第一步：注册并创建索引

先到Pinecone控制台注册账号并创建API Key，把密钥保存到环境变量里，别直接写进公开代码。进入控制台创建索引，选Serverless通常更适合入门和负载变化的应用。给索引起个简短名称，再选云服务商和区域；向量维度、相似度指标要与后续使用的嵌入模型匹配。

例如，嵌入模型输出1536个数字，索引维度就要设为1536；常见相似度指标是cosine。创建后等索引状态显示Ready再开始写数据。还可以规划namespace，把不同用户、语言或环境的数据分开；查询和写入时使用同一个namespace，避免数据写进一处、查询却落到默认空间。

第二步：写入和更新向量

每条向量记录都需要唯一ID、向量值和可选的metadata。metadata适合放标题、类别、来源等筛选信息，但应避免塞入过大的正文。先用嵌入模型把文本转成数字列表，再将记录写入索引。向量长度必须与索引维度一致，否则请求会报错。

写入可用upsert：相同ID再次写入时会覆盖对应记录，因此也能用来更新内容或向量。批量导入时按批次提交，避免一次请求塞入太多数据；记录规模较大时，考虑使用SDK提供的批量导入方式。建议先拿少量样例验证ID、向量和metadata结构，再导入完整数据。

用Python SDK操作

先安装pinecone客户端，再从环境变量读取API Key。下面示例使用传统向量索引接口，假设你已经准备好与索引维度一致的向量：

安装：pip install pinecone

初始化：from pinecone import Pinecone；pc = Pinecone(api_key=os.environ[“PINECONE_API_KEY”])；index = pc.Index(“my-index”)

写入：index.upsert(vectors=[(“doc-1”, [0.1, 0.2, …], {“title”: “入门指南”})], namespace=”docs”)。更新时用相同ID再次upsert；若只改metadata，也可按SDK支持的更新接口操作。实际使用时请把省略号换成完整向量，并确认它的长度正确。

第三步：查询和语义搜索

查询时，先用同一个嵌入模型将用户问题转成向量，再调用query。设置top_k指定返回条数，并传入写入时使用的namespace；需要返回附带信息时开启include_metadata。结果里通常会包含匹配记录的ID、相似度分数和metadata，可按分数排序后取前几条作为上下文。

示例：results = index.query(vector=query_vector, top_k=5, namespace=”docs”, include_metadata=True)。注意，Pinecone负责存储和检索向量，文本转向量通常由嵌入模型完成；两边模型与索引维度要匹配。接入RAG时，可把命中的文本片段交给大语言模型生成回答，并通过metadata过滤版本、分类或权限范围。

排查时优先检查三件事：索引是否Ready、向量维度是否一致、namespace是否相同。也可以先用控制台查看记录并测试检索。若希望比较国内云服务方案，可以了解火山引擎；相关入口：volcengine.cgref.cn。润灭建议先用小规模数据跑通写入、更新和查询，再根据延迟、数据区域、预算及团队已有云资源选择部署方案。

“`