向量数据库Pinecone简明教程 - 第三章核心概念与基础操作

原创已于 2025-02-13 13:33:13 修改

· 1.2k 阅读

20 ·

版权

文章标签：

#数据库 #人工智能 #python #embedding

于 2025-02-08 19:51:29 首次发布

向量数据库专栏收录该内容

4 篇文章

订阅专栏

以下内容主要面向对人工智能应用或数据检索感兴趣，同时具备一定编程基础的开发者与技术人员。无论是机器学习工程师，还是从事搜索推荐的产品开发人员，都可能在工作中遇到大量非结构化数据（如文本、图像、音频）需要进行快速相似度检索。Pinecone 作为一款专业的向量数据库，可以帮助我们高效地存储和查询大量向量数据，解决传统数据库无法胜任的语义搜索与推荐问题。

本章节将重点介绍 Pinecone 的核心概念与基础操作，包括索引、命名空间、向量插入、查询、更新、删除，以及如何查看索引的统计信息。我们会结合一些贴近实际工作的示例来进行讲解，并用简单的示意图帮大家理清思路。

一、索引（Index）

1. 索引在 Pinecone 中的地位

在 Pinecone 中，索引（Index）是用于存储向量及其元数据的核心容器，也是实现相似度搜索功能的基础设施。我们可以把它想象成一个“大仓库”或“书架”，所有的向量数据都按照一定的规则存储在其中；后续的插入（Upsert）、查询（Query）、更新（Update）和删除（Delete）等操作，都与该索引直接关联。

示意图：索引与命名空间的关系

        ┌───────────────────────────────┐
        │           Pinecone           │
        │   (全局服务/控制台/管理层)     │
        └───────────────────────────────┘
                    │
             (创建/管理索引)
                    │
      ┌─────────────────────────┐
      │       索引(Index)       │
      │  my-recipes-index 等    │
      └─────────────────────────┘
            ┌─────────┴─────────┐
            ▼                   ▼
  ┌────────────────┐   ┌────────────────┐
  │ Namespace:      │   │ Namespace:      │
  │ recipe-descript.│   │ user-profiles   │
  └────────────────┘   └────────────────┘
        ▲    ▲
        │    │
   (向量数据插入、更新、查询、删除)

在上图中，我们在 Pinecone 中创建了一个名为 "my-recipes-index" 的索引，该索引下可以包含多个命名空间（如 recipe-descriptions、user-profiles 等）。这使得数据逻辑更加清晰，也便于隔离与管理。

2. 如何选择适当的索引类型

Pinecone 提供了多种相似度计算方式，例如 余弦相似度（cosine）、点积（dot product） 等。

余弦相似度：常用于文本、图像等语义层面的相似度场景，更关注向量的方向。
点积（dot product）：在推荐系统场景中比较常见，用户向量与物品向量进行点积以衡量匹配程度。

此外，创建索引还需考虑：

向量大小（维度）：必须与所用的嵌入模型输出尺寸一致，例如 512、768 等。
向量数据类型：一般使用 float32，也可根据需求选择 float64。

建议：如果是初次使用 Pinecone，推荐使用 余弦相似度，并确保向量维度正确匹配您所使用的模型。

二、命名空间（Namespace）

1. 命名空间的作用：数据逻辑分割

一个索引中可以包含多个命名空间，以实现数据的逻辑分隔。就像在同一个仓库里，放置了多个货架区，每个货架区存放不同品类的商品，互不影响。

示例：在一个名为 my-recipes-index 的索引里，可以创建 recipe-descriptions 命名空间专门存放菜谱向量；也可以创建 chef-profiles 命名空间存放厨师个人信息向量。

2. 不同命名空间之间的隔离与管理

隔离：命名空间之间的数据不会混淆。查询时只会在指定命名空间中搜索，减少干扰。
管理：可以针对不同项目或数据类型，按需创建、删除命名空间，保持数据有序管理。

示例应用：假设一个美食推荐平台，需要同时管理菜谱搜索（recipe-descriptions）和用户偏好推荐（user-preferences）。可在同一个索引下设置不同命名空间，并在查询时分别调用。

三、向量插入（Upsert）

1. 向量数据的基本结构：id + 向量 + 元数据

在 Pinecone 中，每条记录（或“向量条目”）至少包括以下三部分：

id：字符串类型，全局唯一。
向量（vector）：如 [0.21, -0.45, 0.88, ...]，长度必须与索引维度一致。
元数据（metadata）：可选的键值对，存放与该向量相关的业务信息，例如菜名、作者、价格等。

2. 批量插入与单条插入示例

最常见的操作是批量插入。以下示例为 Python 伪代码，展示如何使用 Pinecone 新版客户端 向索引中插入多条向量数据：

from pinecone import Pinecone, Index, ServerlessSpec

# 1. 实例化 Pinecone 对象
# environment 对应你在 Pinecone 控制台上设置的区域，如 "us-east1-gcp"
pc = Pinecone(
    api_key="Your_API_Key",
    environment="us-east-1"
)


# 2. 如果索引不存在，则创建索引 (维度需与向量一致)
index_name = "my-recipes-index"

# 列出已存在的索引
index_list = pc.list_indexes().names()
print("当前已有索引：", index_list)

if index_name not in index_list:
    print(f"索引 {index_name} 不存在，即将创建...")
    pc.create_index(
        name=index_name,
        dimension=3,
        metric='cosine',
        spec=ServerlessSpec(
            cloud='aws',
            region='us-east-1'
        )
    )
else:
    print(f"索引 {index_name} 已存在。")

# 3. 获取索引对象
# To get the unique host for an index,
# see https://docs.pinecone.io/guides/data/target-an-index
index = pc.Index(host="INDEX_SERVER")


# 4. 构建待插入的向量列表 (id, 向量, 元数据)
vectors = [
    (
        "recipe_001",
        [0.21, -0.45, 0.88],
        {"name": "Spaghetti Carbonara", "cuisine": "Italian"}
    ),
    (
        "recipe_002",
        [0.14, 0.39, -0.27],
        {"name": "Sushi Roll", "cuisine": "Japanese"}
    ),
]

# 5. 批量插入（upsert）
index.upsert(
    vectors=vectors,
    namespace="recipe-descriptions"
)
print("Data upsert completed!")

如果是单条插入，只需往 vectors 列表中放一条数据即可。

Pinecone控制台示例：
在这里插入图片描述

3. 数据插入的常见注意点

向量维度一致：所有插入到同一索引的向量必须拥有相同维度（如上例的 3）。
批量大小：一次 upsert 的数量尽量不超出 Pinecone 文档建议范围，否则会增加请求延时。
元数据格式：可以是任意键值对，务必确保可被 JSON 序列化。

四、查询（Query）

1. 相似度搜索的原理（K近邻搜索）

当我们对 Pinecone 发送查询时，底层会根据向量之间的相似度（或距离）进行排序。最常见的是 K 近邻搜索（KNN），即在所有向量中找到与查询向量最接近（或相似度最高）的 K 条结果。

示例：若输入一个菜谱描述向量，Pinecone 将返回与该描述最“相似”的其他菜谱，方便做相似菜品推荐或语义检索。

2. 基本查询与高级查询

基本查询：只需传入一个向量以及想要返回的结果数量 top_k。
高级查询：可在查询时附加过滤条件（如 cuisine='Italian'），或限制返回元数据字段，实现更精准的搜索。

示例 Python 伪代码：


from pinecone import Pinecone, Index, ServerlessSpec

# 实例化 Pinecone 对象
# environment 对应你在 Pinecone 控制台上设置的区域，如 "us-east1-gcp"
pc = Pinecone(
    api_key="Your_API_Key",
    environment="us-east-1"
)

# 获取索引对象
# To get the unique host for an index,
# see https://docs.pinecone.io/guides/data/target-an-index
index = pc.Index(host="INDEX_SERVER")

query_vector = [0.22, -0.44, 0.86]  # 用户输入的向量

# 简单查询：找出最相近的5条记录
result = index.query(
    vector=query_vector,
    top_k=5,
    namespace="recipe-descriptions"
)
print("简单查询结果:", result)

# 带过滤的高级查询：只搜索意大利菜
filtered_result = index.query(
    vector=query_vector,
    top_k=5,
    namespace="recipe-descriptions",
    filter={"cuisine": "Italian"}
)
print("带过滤查询到的结果:", filtered_result)

运行结果示例：

简单查询结果: {'matches': [{'id': 'recipe_001', 'score': 0.999893785, 'values': []},
             {'id': 'recipe_002', 'score': -0.761225522, 'values': []}],
 'namespace': 'recipe-descriptions',
 'usage': {'read_units': 5}}
带过滤查询到的结果: {'matches': [{'id': 'recipe_001', 'score': 0.999893785, 'values': []}],
 'namespace': 'recipe-descriptions',
 'usage': {'read_units': 5}}

3. 查询性能优化的建议

合理规划索引配置：如相似度类型、向量维度等，要符合实际业务场景。
分片与副本：在海量数据或高并发场景下，设置合适的分片（shards）和副本（replicas）可加速查询。
批量查询：如需同时对多个向量做相似度检索，可考虑支持批量查询方式，减少多次网络请求开销。

五、更新与删除（Update & Delete）

1. 更新（Update）

在 Pinecone 中，对向量或其元数据的更新通常通过再次 upsert 相同的 id 来实现。只要 id 和 namespace 相同，新的向量或元数据就会覆盖（或替换）原有记录。


from pinecone import Pinecone, Index, ServerlessSpec

# 实例化 Pinecone 对象
# environment 对应你在 Pinecone 控制台上设置的区域，如 "us-east1-gcp"
pc = Pinecone(
    api_key="Your_API_Key",
    environment="us-east-1"
)

# 获取索引对象
# To get the unique host for an index,
# see https://docs.pinecone.io/guides/data/target-an-index
index = pc.Index(host="INDEX_SERVER")

# 更新 "recipe_001" 的向量和元数据
index.upsert(
    vectors=[
        (
            "recipe_001",
            [0.22, -0.41, 0.87],  # 新的向量
            {"name": "Spaghetti Carbonara (Updated)", "cuisine": "Italian"}
        )
    ],
    namespace="recipe-descriptions"
)
print("recipe_001 updated!")

仅更新元数据：可以传入与原向量相同的值，只改变元数据部分。
仅更新向量：可以保留元数据不变，只替换向量。

局部更新 vs. 全量更新

局部更新：只对部分记录进行 upsert。
全量更新：重新插入整个数据集，通常在数据完全重构或大规模变动时使用。

2. 删除（Delete）

Pinecone 提供 delete 方法来清理索引中的指定向量条目或整个命名空间。

删除单条或多条向量：

# 删除一条向量
index.delete(
    ids=["recipe_001"],
    namespace="recipe-descriptions"
)
print("recipe_001 deleted!")

# 删除多条向量
index.delete(
    ids=["recipe_002", "recipe_003"],
    namespace="recipe-descriptions"
)
print("recipe_002 and recipe_003 deleted!")

删除整个命名空间：

# 一次性清空该命名空间下的所有数据
index.delete(
    deleteAll=True,
    namespace="recipe-descriptions"
)
print("Namespace 'recipe-descriptions' cleared!")

删除索引：
如果索引已经不再使用，可以调用客户端的删除方法（操作不可逆）：

client.delete_index("my-recipes-index")
print("Index 'my-recipes-index' deleted!")

六、查看索引与统计信息

1. 查看索引状态、大小、向量数等

Pinecone 提供了查看当前索引状态的方法，例如 describe_index_stats()。该方法能返回索引的维度、命名空间、向量数量、副本等信息，让我们了解索引健康状态与规模。

stats = index.describe_index_stats()
print(stats)

通常包含：

index_name：索引名称
namespaces：各命名空间下的向量数目
dimension：向量维度
replicas：副本数
shards：分片数

输出示例：

{'dimension': 3,
 'index_fullness': 0.0,
 'namespaces': {'recipe-descriptions': {'vector_count': 2}},
 'total_vector_count': 2}

2. 监控与日志

请求监控：在 Pinecone 控制台上可以查看请求总数、平均延迟、成功率等指标。
日志：若出现错误或查询结果异常，可结合 Pinecone 提供的日志及自身应用日志进行排查。

小结

在本节中，我们探讨了 Pinecone 最核心的几个概念与操作，包括索引、命名空间、向量插入（Upsert）、查询（Query）、更新（Update）、删除（Delete） 以及如何查看索引状态的方式。借由这些操作，我们能在 Pinecone 中高效地管理和检索向量数据，满足从文本搜索到图像搜索再到推荐系统的多种需求。

结合示例代码与图示，大家可以在实际项目中快速上手。在后续的章节或学习中，可进一步了解 Pinecone 的高级功能（如元数据过滤、分片配置、向量压缩等），并探索如何与其他机器学习框架或数据库生态进行整合，构建更强大的检索或推荐系统。

欢迎你动手实验，通过把文本或图像转换成向量，实测 Pinecone 在插入、查询、更新和删除方面的便捷与高效。祝你在工作中取得好成绩、在学习中收获满满！