Pinecone数据管理指南：索引、命名空间、删除保护与数据操作详解

Pinecone

类型：数据库

简介：实时且性能出色的向量数据库，专门针对大规模向量搜索进行优化。

Pinecone 是目前热门的向量数据库之一，广泛用于 AI 检索、RAG、语义搜索以及大模型知识库等场景。本文将带你系统了解 Pinecone 中的数据管理方式，包括如何正确连接索引（Index）、Serverless 索引管理、删除保护配置、标签（Tags）管理、命名空间（Namespace）管理、备份查看和生产环境最佳实践。

一、如何正确连接 Pinecone 索引

在 Pinecone 中，执行向量写入（Upsert）、查询（Query）等数据操作时，需要先连接目标索引。

Pinecone 提供两种连接方式：

通过索引 Host（推荐）
通过索引名称（仅适合测试）

为什么生产环境不建议通过索引名称连接？

如果你使用索引名称连接：

pc.getIndexConnection("docs-example")

SDK 会先自动调用：

describe_index

获取真实 Host 地址。

这样虽然方便测试，但生产环境会带来两个问题：

额外增加一次网络请求
多一个潜在故障点

因此官方建议：

生产环境中直接使用 Index Host。

推荐方式：通过 Host 连接索引

示例（Java）：

import io.pinecone.clients.Index;
import io.pinecone.configs.PineconeConfig;
import io.pinecone.configs.PineconeConnection;

public class TargetIndexByHostExample {
    public static void main(String[] args) {
        PineconeConfig config = new PineconeConfig("YOUR_API_KEY");

        config.setHost("INDEX_HOST");

        PineconeConnection connection = new PineconeConnection(config);

        Index index = new Index(connection, "INDEX_NAME");
    }
}

如果你使用的是 Private Endpoint（私有网络连接），则必须使用对应的 Private Endpoint Host。

如何获取 Index Host？

方法一：在 Pinecone 控制台查看

进入 Pinecone Console
选择对应项目
打开目标 Index
复制 HOST 地址

方法二：通过 API 获取

Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

IndexModel indexModel = pc.describeIndex("docs-example");

System.out.println(indexModel);

返回结果中：

host: docs-example.svc.us-west2-aws.pinecone.io

就是实际连接地址。

通过索引名称连接（仅测试环境推荐）

Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

Index index = pc.getIndexConnection("docs-example");

虽然简单，但不建议在正式环境使用。

二、Serverless 索引管理

Pinecone 提供 Serverless 模式，可按需扩展，无需自行维护集群。

列出所有索引

使用：

list_indexes

即可查看项目中的全部索引。

Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();

IndexList indexList = pc.listIndexes();

System.out.println(indexList);

获取指定索引详情

使用：

describe_index

IndexModel indexModel = pc.describeIndex("docs-example");

返回信息包括：

索引名称
维度（dimension）
距离算法（metric）
Host 地址
区域
是否开启删除保护
状态信息

删除索引

pc.deleteIndex("docs-example");

删除后：

索引
向量数据
关联资源

都会被永久清除。

删除失败：403 FORBIDDEN

如果看到：

Deletion protection is enabled for this index

说明当前索引开启了删除保护。

必须先关闭删除保护才能删除。

三、为索引绑定 Embedding 模型

Pinecone 支持集成推理（Integrated Inference）。

可以在写入和搜索时自动完成向量嵌入，无需手动生成 Embedding。

配置 Embedding 模型

from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

pc.configure_index(
    name="docs-example",
    embed={
      "model":"llama-text-embed-v2",
      "field_map":{"text": "chunk_text"}
    }
)

需要注意

索引的：

vector_type
metric
dimension

必须与所选 Embedding 模型兼容。

四、删除保护（Deletion Protection）

删除保护可以防止索引被误删。

创建索引时开启删除保护

pc.createServerlessIndex(
    "docs-example",
    "cosine",
    1536,
    "aws",
    "us-east-1",
    DeletionProtection.enabled
);

为现有索引开启删除保护

pc.configureServerlessIndex(
    "docs-example",
    DeletionProtection.ENABLED
);

关闭删除保护

删除索引前需要先关闭：

pc.configureServerlessIndex(
    "docs-example",
    DeletionProtection.DISABLED
);

五、索引标签（Tags）管理

Tags 可以帮助你对索引分类管理。

例如：

production
development
staging

创建索引时添加 Tags

HashMap<String, String> tags = new HashMap<>();

tags.put("environment", "development");

更新已有索引 Tags

pc.configureServerlessIndex(
    "docs-example",
    DeletionProtection.ENABLED,
    tags
);

删除 Tag

将 Tag 值设为空即可：

tags.put("example", "");

六、查看索引备份

Serverless 索引支持备份。

可以使用：

listIndexBackups

查看备份列表。

BackupList backupList = pc.listIndexBackups("docs-example");

返回内容包括：

备份 ID
源索引名称
创建时间
区域
状态
数据大小

七、Namespace（命名空间）管理

Namespace 用于隔离不同数据集。

在 AI 知识库、RAG、多租户系统中非常常见。

创建 Namespace

注意：

该功能仅支持：

2025-10 API 版本

示例：创建 Namespace

NamespaceDescription namespace =
    index.createNamespace("example-namespace", schema);

创建时可定义 Metadata Schema

例如：

document_id
document_title
chunk_number
created_at

并设置：

filterable: true

这样后续查询时可以使用 Metadata Filter。

列出所有 Namespace

ListNamespacesResponse response =
    index.listNamespaces();

默认每次最多返回 100 个。

支持分页。

查看 Namespace 详情

NamespaceDescription description =
    index.describeNamespace("example-namespace");

可查看：

Namespace 名称
向量数量

删除 Namespace

index.deleteNamespace("example-namespace");

注意：

删除 Namespace 不可恢复。

其中所有数据都会永久删除。

Namespace 不支持重命名

Pinecone 当前不支持直接修改 Namespace 名称。

正确做法是：

导出旧 Namespace 数据
重新写入新 Namespace
删除旧 Namespace

Namespace 不支持直接移动数据

如果要迁移数据：

需要重新 Upsert
不能直接 Move

使用默认 Namespace

如果需要使用默认 Namespace：

__default__

示例：

SearchRecordsResponse response =
    index.searchRecordsByText(
        query,
        "__default__",
        fields,
        2,
        null,
        null
    );