Python客户端

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

入门指南

安装

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

Python

pip3 install pinecone-client

或者，您可以在Jupyter笔记本中安装Pinecone：

Python

!pip3 install pinecone-client

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

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

Python

pip3 install "pinecone-client[grpc]"

获取最新的开发版本：

Python

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

获取特定的开发版本：

Python

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)

使用

创建索引

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

Python

import pinecone

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

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

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

Python

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

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

列出索引

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

Python

import pinecone

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

active_indexes = pinecone.list_indexes()

描述索引

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

Python

import pinecone

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

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

删除索引

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

Python

import pinecone

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

pinecone.delete_index("example-index")

缩放副本

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

Python

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 的统计信息。

Python

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.

Python

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。

Python

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 删除向量。

Python

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 获取向量。

Python

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 更新向量。

Python

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。

Python

import pinecone

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

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

列举集合

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

Python

import pinecone

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

active_collections = pinecone.list_collections()

描述集合

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

Python

import pinecone

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

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

删除集合

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

Python

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.

示例：

Python

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 `s1`, `p1`, or `p2` appended with `.` and one of `x1`, `x2`, `x4`, or `x8`.

示例：

Python

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.

示例：

Python

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 `s1`, `p1`, or `p2` appended with `.` and one of `x1`, `x2`, `x4`, 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.

示例：

Python

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.

示例：

Python

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.

示例：

Python

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.

示例：

Python

import pinecone

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

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

collectionMeta : object 集合的配置信息和部署状态。
- name : string 集合的名称。
- size: integer 集合的大小，单位为字节。
- status: string 集合的状态。

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 类型。可为 s1、p1 或 p2 之一，后面跟 . 和 x1、x2、x4 或 x8 中的一个。
metadata_config: object Pinecone 内部元数据索引行为的配置。默认情况下，会对所有元数据进行索引；当出现 metadata_config 时，只有指定的元数据字段会被索引。要指定要索引的元数据字段，请提供以下形式的 JSON 对象： {"indexed": ["example_metadata_field"]}。
status : object
ready : boolean 索引是否准备好用于查询。
state : string 以下之一：Initializing, ScalingUp, ScalingDown, Terminating, Ready。示例：

Python

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 项目中集合的名称。

示例：

Python

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 项目中索引的名称。

示例：

Python

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.

示例：

Python

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 https://www.pinecone.io/docs/metadata-filtering/.

示例：

Python

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 索引中向量的总数。

示例：

Python

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 向量所在的命名空间。示例：

Python

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	（可选）要应用的过滤器。您可以使用向量元数据限制搜索范围。请参见 https://www.pinecone.io/docs/metadata-filtering/。
`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` 参数之一。

示例：

Python

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。

Python

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	(可选) 包含向量的命名空间。

示例：

Python

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的向量数量。

示例：

Python

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中。

Python

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'
)

更新时间 3个月前

Python客户端

入门指南​

安装​

使用​

创建索引​

列出索引​

描述索引​

删除索引​

缩放副本​

描述索引统计信息​

更新向量​

查询索引​

删除向量​

获取向量​

更新向量​

创建集合​

列举集合​

描述集合​

删除集合​

参考文献​

初始化()​

configure_index()​

create_collection()​

create_index()​

删除集合()​

删除索引()​

描述集合()​

describe_index()​

list_collections()​

list_indexes()​

索引()​

Index.delete()​

Index.describe_index_stats()​

Index.fetch()​

Index.query()​

Index.update()​

Index.upsert()​

入门指南

安装

使用

创建索引

列出索引

描述索引

删除索引

缩放副本

描述索引统计信息

更新向量

查询索引

删除向量

获取向量

更新向量

创建集合

列举集合

描述集合

删除集合

参考文献

初始化()

configure_index()

create_collection()

create_index()

删除集合()

删除索引()

描述集合()

describe_index()

list_collections()

list_indexes()

索引()

Index.delete()

Index.describe_index_stats()

Index.fetch()

Index.query()

Index.update()

Index.upsert()