Pinecone向量库Python客户端中文说明文档

本页面提供安装指南、使用示例以及Pinecone Python客户端的参考。

一、入门指南​

1、安装​

使用以下Shell命令安装Python客户端,适用于Python 3.6+版本:

pip3 install pinecone-client

或者,您可以在Jupyter笔记本中安装Pinecone:

!pip3 install pinecone-client

我们强烈建议在虚拟环境中安装Pinecone。有关使用Python虚拟环境的更多信息,请参见:

  • PyPA Python Packaging User Guide

  • Python Virtual Environments: A Primer

有一个gRPC版本的客户端可用,为了更快的上传速度,需要更多的依赖项。要安装它,请使用以下命令:

pip3 install "pinecone-client[grpc]"

获取最新的开发版本:

pip3 install git+https://[[email protected]](https://docs.pinecone.io/cdn-cgi/l/email-protection)/pinecone-io/pinecone-python-client.git

获取特定的开发版本:

pip3 install git+https://[[email protected]](https://docs.pinecone.io/cdn-cgi/l/email-protection)/pinecone-io/pinecone-python-client.git
pip3 install git+https://[[email protected]](https://docs.pinecone.io/cdn-cgi/l/email-protection)/pinecone-io/[[email protected]](https://docs.pinecone.io/cdn-cgi/l/email-protection)
pip3 install git+https://[[email protected]](https://docs.pinecone.io/cdn-cgi/l/email-protection)/pinecone-io/[[email protected]](https://docs.pinecone.io/cdn-cgi/l/email-protection)

2、使用​

创建索引​

以下示例创建一个没有元数据配置的索引。 默认情况下,Pinecone索引所有元数据。

import pinecone

pinecone.init(api_key="YOUR_API_KEY",
              environment="YOUR_ENVIRONMENT")

pinecone.create_index("example-index", dimension=1024)

以下示例创建一个仅索引"color"元数据字段的索引。 对该索引的查询无法根据任何其他元数据字段进行过滤。

metadata_config = {
    "indexed": ["color"]
}

pinecone.create_index("example-index-2", dimension=1024,
                      metadata_config=metadata_config)

列出索引​

以下示例返回项目中的所有索引。

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")

active_indexes = pinecone.list_indexes()

描述索引​

下面的示例返回有关索引 example-index 的信息。

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")

index_description = pinecone.describe_index("example-index")

删除索引​

下面的示例删除了 example-index 索引。

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")

pinecone.delete_index("example-index")

缩放副本​

下面的示例更改了 example-index 的副本数量。

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")

new_number_of_replicas = 4
pinecone.configure_index("example-index", replicas=new_number_of_replicas)

描述索引统计信息​

下面的示例返回有关索引 example-index 的统计信息。

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")
index = pinecone.Index("example-index")

index_stats_response = index.describe_index_stats()

更新向量​

The following example upserts dense vectors to example-index.

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")
index = pinecone.Index("example-index")

upsert_response = index.upsert(
    vectors=[
        (
         "vec1",                # Vector ID 
         [0.1, 0.2, 0.3, 0.4],  # Dense vector values
         {"genre": "drama"}     # Vector metadata
        ),
        (
         "vec2", 
         [0.2, 0.3, 0.4, 0.5], 
         {"genre": "action"}
        )
    ],
    namespace="example-namespace"
)

查询索引​

下面的示例查询带有元数据过滤的索引 example-index

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")
index = pinecone.Index("example-index")

query_response = index.query(
    namespace="example-namespace",
    top_k=10,
    include_values=True,
    include_metadata=True,
    vector=[0.1, 0.2, 0.3, 0.4],
    filter={
        "genre": {"$in": ["comedy", "documentary", "drama"]}
    }
)

删除向量​

以下示例按 ID 删除向量。

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")
index = pinecone.Index("example-index")

delete_response = index.delete(ids=["vec1", "vec2"], namespace="example-namespace")

获取向量​

以下示例按 ID 获取向量。

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")
index = pinecone.Index("example-index")

fetch_response = index.fetch(ids=["vec1", "vec2"], namespace="example-namespace")

更新向量​

以下示例按 ID 更新向量。

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")
index = pinecone.Index("example-index")

update_response = index.update(
    id="vec1",
    values=[0.1, 0.2, 0.3, 0.4],
    set_metadata={"genre": "drama"},
    namespace="example-namespace"
)

创建集合​

下面的示例从索引example-index创建集合example-collection

import pinecone

pinecone.init(api_key="YOUR_API_KEY",
              environment="YOUR_ENVIRONMENT")

pinecone.create_collection("example-collection", "example-index")

列举集合​

以下示例返回当前项目中的集合列表。

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")

active_collections = pinecone.list_collections()

描述集合​

下面的示例返回example-collection集合的描述信息。

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")

collection_description = pinecone.describe_collection("example-collection")

删除集合​

下面的示例删除集合example-collection

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")

pinecone.delete_collection("example-collection")

二、参考文献​

有关REST API或其他客户端,请参阅API参考。

初始化()​

pinecone.init(**kwargs)

初始化Pinecone。

Parameters Type Description
api_key str Your Pinecone API key.
environment str The cloud environment of your Pinecone project.

示例:

import pinecone
pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")

configure_index()​

pinecone.configure_index(index_name, **kwargs)

配置一个索引以更改 pod 类型和副本数量。

Parameters Type Description
index_name str The name of the index
replicas int (Optional) The number of replicas to configure for this index.
pod_type str (Optional) The new pod type for the index. One of s1p1, or p2 appended with . and one of x1x2x4, or x8.

示例:

import pinecone

pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')

new_number_of_replicas = 4
pinecone.configure_index('example-index', replicas=new_number_of_replicas)

create_collection()​

pinecone.create_collection(**kwargs)

从索引创建一个集合。

Parameters Type Description
name str The name of the collection to be created.
source str The name of the source index to be used as the source for the collection.

示例:

import pinecone

pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')

pinecone.create_collection('example-collection', 'example-index')

create_index()​

pinecone.create_index(**kwargs)

创建一个索引。

Parameters Type Description
name str The name of the index to be created. The maximum length is 45 characters.
dimension integer The dimensions of the vectors to be inserted in the index.
metric str (Optional) The distance metric to be used for similarity search: 'euclidean', 'cosine', or 'dotproduct'.
pods int (Optional) The number of pods for the index to use, including replicas.
replicas int (Optional) The number of replicas.
pod_type str (Optional) The new pod type for the index. One of s1p1, or p2 appended with . and one of x1x2x4, or x8.
metadata_config object (Optional) Configuration for the behavior of Pinecone's internal metadata index. By default, all metadata is indexed; when metadata_config is present, only specified metadata fields are indexed. To specify metadata fields to index, provide a JSON object of the following form: {"indexed": ["example_metadata_field"]}
source_collection str (Optional) The name of the collection to create an index from.

示例:

import pinecone

pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')

## The following example creates an index without a metadata
## configuration. By default, Pinecone indexes all metadata.

pinecone.create_index('example-index', dimension=1024)

## The following example creates an index that only indexes
## the 'color' metadata field. Queries against this index
## cannot filter based on any other metadata field.

metadata_config = {
    'indexed': ['color']
}

pinecone.create_index('example-index-2', dimension=1024,
                      metadata_config=metadata_config)

删除集合()​

pinecone.delete_collection('example-collection')

删除现有集合。

Parameters Type Description
collectionName str The name of the collection to delete.

示例:

import pinecone

pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')
pinecone.delete_collection('example-collection')

删除索引()​

pinecone.delete_index(indexName)

删除现有索引。

Parameters Type Description
index_name str The name of the index.

示例:

import pinecone

pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')

pinecone.delete_index('example-index')

描述集合()​

pinecone.describe_collection(collectionName)

获取集合的描述。

Parameters Type Description
collection_name str The name of the collection.

示例:

import pinecone

pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')

collection_description = pinecone.describe_collection('example-collection')

返回:

  • collectionMeta : object 集合的配置信息和部署状态。
    • name : string 集合的名称。
    • sizeinteger 集合的大小,单位为字节。
    • statusstring 集合的状态。

describe_index()​

pinecone.describe_index(indexName)

获取索引的描述。

Parameters Type Description
index_name str The name of the index.

返回值:

  • database : object
  • name : string 索引名称。
  • dimension : integer 向量的维度。
  • metric : string 相似性搜索的距离度量方式:'euclidean'、'cosine' 或 'dotproduct'。
  • pods : integer 索引使用的 pod 数量,包括副本。
  • replicas : integer 索引的副本数。
  • pod_type : string 索引的 pod 类型。可为 s1p1 或 p2 之一,后面跟 . 和 x1x2x4 或 x8 中的一个。
  • metadata_configobject Pinecone 内部元数据索引行为的配置。默认情况下,会对所有元数据进行索引;当出现 metadata_config 时,只有指定的元数据字段会被索引。要指定要索引的元数据字段,请提供以下形式的 JSON 对象: {"indexed": ["example_metadata_field"]}
  • status : object
  • ready : boolean 索引是否准备好用于查询。
  • state : string 以下之一:InitializingScalingUpScalingDownTerminatingReady。 示例:
import pinecone

pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')

index_description = pinecone.describe_index('example-index')

list_collections()​

pinecone.list_collections()

返回项目中集合的列表。

返回值:

  • array of strings 项目中集合的名称。

示例:

import pinecone

pinecone.init(api_key='YOUR_API_KEY', environment='us-east1-gcp')

active_collections = pinecone.list_collections()

list_indexes()​

pinecone.list_indexes()

返回您的Pinecone索引列表。

返回值:

  • array of strings 项目中索引的名称。

示例:

import pinecone

pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')

active_indexes = pinecone.list_indexes()

索引()​

pinecone.Index(indexName)

构建一个索引对象。

Parameters Type Description
indexName str The name of the index.

示例:

index = pinecone.Index("example-index")

Index.delete()​

Index.delete(**kwargs)

从单个命名空间中按其ID删除项目。

Parameters Type Description
ids array (Optional) array of strings vectors to delete.
delete_all boolean (Optional) Indicates that all vectors in the index namespace should be deleted.
namespace str (Optional) The namespace to delete vectors from, if applicable.
filter object (Optional) If specified, the metadata filter here will be used to select the vectors to delete. This is mutually exclusive with specifying ids to delete in the ids param or using delete_all=True. See Filtering with metadata.

示例:

import pinecone

pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')
index = pinecone.Index('example-index')

delete_response = index.delete(ids=['vec1', 'vec2'], namespace='example-namespace')

Index.describe_index_stats()​

Index.describe_index_stats()

返回索引内容的统计信息,包括每个命名空间的向量计数和维度数量。

返回:

  • namespaces : object 对索引中每个命名空间的映射,从命名空间名称到其内容摘要。如果存在元数据过滤表达式,则摘要将仅反映匹配该表达式的向量。
  • dimension : int64 索引向量的维度。
  • indexFullness : float 索引的完整度,无论是否传递了元数据过滤表达式。此度量的粒度为10%。
  • totalVectorCount : int64 索引中向量的总数。

示例:

import pinecone

pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')
index = pinecone.Index('example-index')

index_stats_response = index.describe_index_stats()

Index.fetch()​

Index.fetch(ids, **kwargs)

Fetch操作从单个命名空间查找并返回向量。返回的向量包括向量数据和元数据。

参数 类型 描述
ids [str] 要获取的向量的ID。不能接受包含空格的值。
namespace str (可选) 包含向量的命名空间。

返回:

  • vectors : object 包含向量。
  • namespace : string 向量所在的命名空间。 示例:
import pinecone

pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')
index = pinecone.Index('example-index')

fetch_response = index.fetch(ids=['vec1', 'vec2'], namespace='example-namespace')

Index.query()​

Index.query(**kwargs)

使用查询向量搜索命名空间。检索命名空间中最相似项的ID及其相似度分数。

参数 类型 描述
namespace str (可选) 要查询的命名空间。
top_k int64 每个查询返回的结果数量。
filter object (可选)要应用的过滤器。您可以使用向量元数据限制搜索范围。请参见 Filtering with metadata。
include_values boolean (可选)表示响应中是否包含向量值。默认为 false
include_metadata boolean (可选)表示响应中是否包含元数据以及id。默认为 false
vector [floats] (可选)查询向量。其长度应与查询的索引的维度相同。每个 query() 请求只能包含 id 或 vector 参数之一。
sparse_vector dictionary (可选)稀疏查询向量。必须包含一个名为 indices 的整数数组和一个名为 values 的浮点数组。这两个数组的长度必须相同。
id string (可选)要用作查询向量的唯一 ID。每个 query() 请求只能包含 id 或 vector 参数之一。

示例:

import pinecone

 pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')
 index = pinecone.Index('example-index')

 query_response = index.query(
    namespace='example-namespace',
    top_k=10,
    include_values=True,
    include_metadata=True,
    vector=[0.1, 0.2, 0.3, 0.4],
    filter={
        'genre': {'$in': ['comedy', 'documentary', 'drama']}
    }
)

下面的示例使用稀疏-稠密向量查询索引 example-index

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")
index = pinecone.Index("example-index")

query_response = index.query(
    namespace="example-namespace",
    top_k=10,
    include_values=True,
    include_metadata=True,
    vector=[0.1, 0.2, 0.3, 0.4],
    sparse_vector={
        'indices': [10, 45, 16],
        'values':  [0.5, 0.5, 0.2]
    },
    filter={
        "genre": {"$in": ["comedy", "documentary", "drama"]}
    }
)

Index.update()​

Index.update(**kwargs)

更新命名空间中的向量。如果包含值,则会覆盖先前的值。

如果包括 set_metadata,则其中指定的字段的值将添加或覆盖先前的值。

参数 类型 描述
id str 向量的唯一 ID。
values [float] (可选) 向量数据。
set_metadata object (可选) 用于设置向量元数据。
namespace str (可选) 包含向量的命名空间。

示例:

import pinecone

pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')
index = pinecone.Index('example-index')

update_response = index.update(
    id='vec1',
    values=[0.1, 0.2, 0.3, 0.4],
    set_metadata={'genre': 'drama'},
    namespace='example-namespace'
)

Index.upsert()​

Index.upsert(**kwargs)

将向量写入命名空间。如果为现有向量ID更新了新值,则会覆盖先前的值。

参数 类型 描述
vectors [object] 一个包含要upsert的向量的数组。建议批量限制为100个向量。id (str) - 向量的唯一ID。values ([float]) - 向量数据。metadata (object) - (可选) 向量的元数据。sparse_vector (object) - (可选) 包含包含稀疏向量值的索引和值数组的字典。
namespace str (可选) 要upsert向量的命名空间名称。

返回值:

  • upsertedCount : int64 upsert的向量数量。

示例:

import pinecone

pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')
index = pinecone.Index('example-index')

upsert_response = index.upsert(
   vectors=[
       {'id': "vec1", "values":[0.1, 0.2, 0.3, 0.4], "metadata": {'genre': 'drama'}},
       {'id': "vec2", "values":[0.2, 0.3, 0.4, 0.5], "metadata": {'genre': 'action'}},
   ],
   namespace='example-namespace'
)

以下示例将带有稀疏值和密集值的向量upsert到example-index中。

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")
index = pinecone.Index("example-index")

upsert_response = index.upsert(
    vectors=[
        {'id': 'vec1',
         'values': [0.1, 0.2, 0.3, 0.4],
         'metadata': {'genre': 'drama'},
         'sparse_values': {
             'indices': [10, 45, 16],
             'values': [0.5, 0.5, 0.2]
         }},
        {'id': 'vec2',
         'values': [0.2, 0.3, 0.4, 0.5],
         'metadata': {'genre': 'action'},
         'sparse_values': {
             'indices': [15, 40, 11],
             'values': [0.4, 0.5, 0.2]
         }}
    ],
    namespace='example-namespace'
)

你可能感兴趣的:(pinecone,python,pinecone,向量数据库)