Pinecone：全托管向量数据库服务

bash pip install pinecone-client

更高性能的异步客户端：

```bash
pip install pinecone-client[v3]

3. 连接并创建索引

使用新版本语法初始化客户端，创建索引。

from pinecone import Pinecone, ServerlessSpec

pc = Pinecone(api_key="YOUR_API_KEY")

# 创建一个名为 "quickstart" 的索引，维度 384，采用余弦相似度
pc.create_index(
    name="quickstart",
    dimension=384,
    metric="cosine",
    spec=ServerlessSpec(
        cloud="aws",
        region="us-east-1"
    )
)

索引创建可能需要几秒钟，随后你可以在控制台看到索引状态变为“Ready”。

4. 连接索引并插入向量

获取索引对象，然后使用 upsert 批量插入向量。

index = pc.Index("quickstart")

# 示例：插入三条向量
vectors = [
    {
        "id": "vec1",
        "values": [0.1, 0.2, 0.3, ...],  # 384 维浮点数列表
        "metadata": {"genre": "action", "year": 2023}
    },
    {
        "id": "vec2",
        "values": [0.4, 0.5, 0.6, ...],
        "metadata": {"genre": "comedy", "year": 2022}
    },
    {
        "id": "vec3",
        "values": [0.7, 0.8, 0.9, ...],
        "metadata": {"genre": "action", "year": 2021}
    }
]

index.upsert(vectors=vectors)

5. 执行相似度查询

提供查询向量，检索最相似的 top_k 个结果。

query_vector = [0.15, 0.25, 0.35, ...]  # 查询用向量

results = index.query(
    namespace="default",        # 可选命名空间
    vector=query_vector,
    top_k=2,
    include_values=False,
    include_metadata=True
)

for match in results.matches:
    print(f"ID: {match.id}, Score: {match.score}, Metadata: {match.metadata}")

查询返回的 score 对于余弦相似度而言就是相似度值（-1 到 1，越高越相似）。

高级特性详解

命名空间管理

利用命名空间实现多租户隔离或数据版本控制。插入和查询时只需指定 namespace 参数。

# 在命名空间 "tenant-a" 中插入
index.upsert(vectors=vecs, namespace="tenant-a")

# 仅在 "tenant-a" 中搜索
results = index.query(vector=query_vec, top_k=5, namespace="tenant-a")

# 列出所有命名空间
print(index.describe_index_stats().namespaces)

元数据过滤

结合 filter 参数，在搜索时限定元数据条件，实现混合搜索。支持以下操作符：

• 等值过滤：{"genre": {"$eq": "action"}}
• 列表包含：{"genre": {"$in": ["action", "comedy"]}}
• 数值比较：{"year": {"$gte": 2022}}
• 逻辑组合：{"$and": [{"genre": "action"}, {"year": {"$gte": 2022}}]}

示例：

results = index.query(
    vector=query_vec,
    top_k=3,
    filter={
        "genre": "action",
        "year": {"$gte": 2022}
    },
    include_metadata=True
)

更新与删除

• 更新：使用 update 单条修改向量的元数据或向量值。需要提供向量 ID。
• 删除：可以按 ID 删除单条或多条，也可以按元数据过滤条件批量删除。

# 更新元数据
index.update(id="vec1", set_metadata={"genre": "thriller", "rating": 4.5})

# 按 ID 删除多条
index.delete(ids=["vec2", "vec3"])

# 按过滤条件删除（例如删除所有 year < 2020 的向量）
index.delete(filter={"year": {"$lt": 2020}})

检索与获取

不进行搜索，仅通过 ID 获取向量数据，使用 fetch 方法。

fetched = index.fetch(ids=["vec1"])
print(fetched.vectors["vec1"])

索引状态与统计

describe_index_stats 可以查看向量总数、维度数和命名空间信息，对监控很有帮助。

stats = index.describe_index_stats()
print(stats.total_vector_count)