使用 Pinecone 的第一步是在你的开发环境中安装官方 Python SDK。打开终端，执行 pip install pinecone-client，该命令会从 PyPI 获取最新版本的客户端库。安装完成后，你需要在 Pinecone 官网注册账号并获取 API 密钥。在代码中导入 pinecone 模块，调用 pinecone.init(api_key="你的密钥", environment="你的环境名称") 完成初始化。环境名称通常是你创建项目时指定的地区，例如 "us-west1-gcp" 或 "gcp-starter"。初始化成功后，SDK 会自动建立与云端服务的连接，后续所有操作都基于这个连接。
索引是 Pinecone 中存储向量数据的核心容器。创建索引前需要明确两个参数：维度（dimension）和度量方式（metric）。维度必须与你将要插入的向量长度一致，例如使用 OpenAI 的 text-embedding-ada-002 模型生成 1536 维向量，则维度设为 1536。度量方式决定了向量间相似度的计算方法，常用选项包括余弦相似度（cosine）、欧氏距离（euclidean）和点积（dotproduct）。调用 pinecone.create_index(name="你的索引名", dimension=1536, metric="cosine") 即可创建索引。创建过程需要几秒钟到几分钟不等，你可以通过 pinecone.describe_index("索引名") 确认索引状态是否变为 Ready。
向索引中写入数据时，每个向量需要附带唯一的 ID 以及可选的元数据（metadata）。首先获取索引对象：index = pinecone.Index("索引名")。然后准备数据列表，每个元素是一个字典，包含 id、values 和 metadata 字段。例如：data = [{"id": "vec1", "values": [0.1, 0.2, ...], "metadata": {"category": "science", "source": "arxiv"}}]。调用 index.upsert(vectors=data) 将数据插入索引。如果你需要分批插入大量数据，可以设置 batch_size 参数（默认 100），Pinecone 会自动处理分片和写入负载。upsert 操作支持幂等性，重复插入相同 ID 的向量会覆盖原有记录。
查询是 Pinecone 最常用的操作。构建一个查询向量，通常来自用户输入经过 embedding 模型转换后的结果。调用 index.query(vector=你的查询向量, top_k=10, include_metadata=True)，返回结果是一个字典，包含匹配到的向量 ID、相似度分数以及对应的元数据。你可以通过 include_values=False 禁止返回原始向量以节省带宽。如果需要基于元数据过滤，使用 filter 参数传入一个字典，例如 filter={"category": "science"}。Pinecone 支持丰富的过滤表达式，包括等于、不等于、大于、小于、存在性判断等。查询结果默认按相似度降序排列，分数越高代表越相似。
实际使用中你可能需要动态调整索引容量或删除旧数据。Pinecone 提供 index.describe_index_stats() 查看当前索引的向量总数、维度、总占用空间等信息。若要删除特定 ID 的向量，调用 index.delete(ids=["vec1", "vec2"])；若想清空整个索引，使用 index.delete(delete_all=True)。更改索引的 pod 规格（如升配或降配）可以通过 pinecone.configure_index("索引名", replicas=2, pod_type="p1.x2") 实现，注意修改配置后需要等待几分钟生效。对于不再使用的索引，直接调用 pinecone.delete_index("索引名") 释放资源。官方文档建议在生产环境中定期监控索引的请求延迟和错误率，以便及时扩容。
将 Pinecone 与常见的 embedding 模型结合使用是典型场景。例如配合 OpenAI 的 Embedding API：先通过 openai.Embedding.create(input="你的文本", model="text-embedding-ada-002") 得到向量，再将该向量插入 Pinecone。查询时同样将用户问题转为向量，然后调用 index.query 获得最相似的文本 ID，最后根据 ID 从原始数据存储中取出完整内容。需要注意的是，插入和查询必须使用同一个 embedding 模型，否则维度不一致或语义空间不匹配会导致结果错误。你可以在预处理阶段将文本切片为合适长度，并为每个切片生成单独向量，这样能提高检索颗粒度。一些高级用法还包括使用命名空间（namespace）来隔离不同业务的数据，只需在 upsert 和 query 时指定 namespace="your_namespace" 即可。
使用过程中可能遇到 API 密钥过期、请求超时、索引不存在等异常。Pinecone 客户端会抛出 pinecone.exceptions.PineconeException 或其子类，建议捕获后根据错误码处理。例如 401 错误表示密钥无效，需要重新初始化；404 表示索引名称错误或未就绪。如果出现超时，可以调大 timeout 参数，或检查网络连接是否稳定。向量维度不匹配的错误通常发生在创建索引时维度与插入数据不一致，请务必保持统一。另外，Pinecone 免费版有每小时请求次数上限和索引大小限制，超出后会返回 429 状态码，此时可考虑升级付费计划或降低调用频率。官方提供了详细的错误码文档，建议开发时开启日志记录：pinecone.init(..., log_level="DEBUG") 便于排查问题。
