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 s1, p1, or p2 appended with . and one of x1, x2, x4, 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 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. |
示例：
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集合的名称。size:integer集合的大小，单位为字节。status:string集合的状态。
describe_index()
pinecone.describe_index(indexName)
获取索引的描述。
| Parameters | Type | Description |
|---|---|---|
index_name |
str | The name of the index. |
返回值：
database:objectname: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:objectPinecone 内部元数据索引行为的配置。默认情况下，会对所有元数据进行索引；当出现 metadata_config 时，只有指定的元数据字段会被索引。要指定要索引的元数据字段，请提供以下形式的 JSON 对象：{"indexed": ["example_metadata_field"]}。status:objectready:boolean索引是否准备好用于查询。state:string以下之一：Initializing,ScalingUp,ScalingDown,Terminating,Ready。 示例：
import pinecone
pinecone.init(api_key='YOUR_API_KEY', environment='YOUR_ENVIRONMENT')
index_description = pinecone.describe_index('example-index')
list_collections()
pinecone.list_collections()
返回项目中集合的列表。
返回值：
arrayofstrings项目中集合的名称。
示例：
import pinecone
pinecone.init(api_key='YOUR_API_KEY', environment='us-east1-gcp')
active_collections = pinecone.list_collections()
list_indexes()
pinecone.list_indexes()
返回您的Pinecone索引列表。
返回值：
arrayofstrings项目中索引的名称。
示例：
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:int64upsert的向量数量。
示例：
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'
)