Pinecone Rust SDK

此SDK仍处于alpha状态。虽然它已基本构建并功能齐全，但随着我们继续改进用户体验，它可能还会发生变化。请尝试使用它并给我们反馈，但请注意，更新可能会引入破坏性更改。

文档

文档可以在此处找到。

先决条件

Rust版本：已测试与Rust版本1.78.0兼容

在您可以使用Pinecone SDK之前，您必须注册一个账户，并在https://app.pinecone.io的Pinecone控制台仪表板上找到您的API密钥。

安装

如何安装 - 从crates.io获取包的说明

使用方法

PineconeClient类是Rust SDK的主要入口点。参数可以直接作为Options传入，或者如下通过环境变量读取。更多详情

• API密钥必须作为参数传入，或者作为名为PINECONE_API_KEY的环境变量传入。如果传入为None，客户端将尝试读取环境变量值。
• 控制平面主机，如果传入为None，将尝试读取名为PINECONE_CONTROLLER_HOST的环境变量。如果不是环境变量，它将默认为https://api.pinecone.io。

有两种方法可以实例化客户端，如下详细说明

PineconeClientConfig

使用参数初始化PineconeClientConfig结构体，并使用结构体调用config。

use pinecone_sdk::pinecone::{PineconeClient, PineconeClientConfig};

let config = PineconeClientConfig {
    api_key: Some("INSERT_API_KEY".to_string()),
    control_plane_host: Some("INSERT_CONTROLLER_HOST".to_string()),
    ..Default::default()
};

let pinecone: PineconeClient = config.client().expect("Failed to create Pinecone instance");

默认客户端

使用default_client()函数，这相当于使用所有字段设置为None的PineconeClientConfig结构体构造。API密钥和控制平面主机（可选）将从环境变量中读取。

let pinecone: PineconeClient = pinecone_sdk::pinecone::default_client().expect("Failed to create Pinecone instance");

索引

创建索引

创建无服务器索引

以下示例在AWS的us-east-1区域创建一个无服务器索引。有关无服务器和区域可用性的更多信息，请参阅理解索引

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::control::{Metric, Cloud, WaitPolicy, IndexModel};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;
 
let index_description: IndexModel = pinecone.create_serverless_index(
    "index-name",       // Name of the index
    10,                 // Dimension of the vectors
    Metric::Cosine,     // Distance metric
    Cloud::Aws,         // Cloud provider
    "us-east-1",        // Region
    WaitPolicy::NoWait  // Timeout
).await?;

创建Pod索引

以下示例在AWS的us-east-1区域创建Pod索引。

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::control::{Metric, Cloud, WaitPolicy, IndexModel};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let index_description: IndexModel = pinecone.create_pod_index(
    "index-name",       // Index name
    10,                 // Dimension
    Metric::Cosine,     // Distance metric
    "us-east-1",        // Region
    "p1.x1",            // Pod type
    1,                  // Number of pods
    None,               // Number of replicas
    None,               // Number of shards
    None,               // Metadata to index
    None,               // Source collection
    WaitPolicy::NoWait  // Wait policy
).await?;

Pod索引支持几个可选配置字段。以下示例构建了一个包含这些字段特定设置的Pod索引。

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::control::{Metric, Cloud, WaitPolicy, IndexModel};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let index_description: IndexModel = pinecone.create_pod_index(
    "index-name",       // Index name
    10,                 // Dimension
    Metric::Cosine,     // Distance metric
    "us-east-1",        // Region
    "p1.x1",            // Pod type
    1,                  // Number of pods
    Some(1),            // Number of replicas
    Some(1),            // Number of shards
    Some(               // Metadata fields to index
        &vec!["genre",
            "title",
            "imdb_rating"]),
    Some("collection"), // Source collection
    WaitPolicy::NoWait  // Wait policy
).await?;

列出索引

以下示例列出项目中所有的索引。

use pinecone_sdk::pinecone::{PineconeClientConfig, control::IndexList};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let index_list: IndexList = pinecone.list_indexes().await?;

描述索引

以下示例返回有关索引index-name的信息。

use pinecone_sdk::pinecone::{PineconeClientConfig, control::IndexModel};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let index_description: IndexModel = pinecone.describe_index("index-name").await?;

配置索引

配置索引需要三个可选参数--一个DeletionProtection枚举，副本数量，和Pod类型。删除保护可以更新任何索引类型，而副本数量和Pod类型只能更新Pod索引。

以下示例禁用了索引index-name的删除保护。

use pinecone_sdk::pinecone::{PineconeClientConfig, control::IndexModel};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let index_description: IndexModel = pinecone.configure_index("index-name", Some(DeletionProtection::Disabled), None, None).await?;

以下示例将索引index-name的副本数量更改为6，并设置为Pod类型s1。在这种情况下，删除保护类型不会改变。

use pinecone_sdk::pinecone::{PineconeClientConfig, control::IndexModel};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;
    
let index_description: IndexModel = pinecone.configure_index("index-name", None, Some(6), Some("s1")).await?;

删除索引

以下示例删除索引index-name。

use pinecone_sdk::pinecone::PineconeClientConfig;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;
    
pinecone.delete_index("index-name").await?;

描述索引统计信息

以下示例返回具有主机index-host的索引的统计信息。无过滤器

use std::collections::BTreeMap;
use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::data::DescribeIndexStatsResponse;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let response: DescribeIndexStatsResponse = index.describe_index_stats(None).await?;

有过滤器

use std::collections::BTreeMap;
use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::data::{Value, Kind, Metadata, DescribeIndexStatsResponse};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let mut fields = BTreeMap::new();
let kind = Some(Kind::StringValue("value".to_string()));
fields.insert("field".to_string(), Value { kind });

let response: DescribeIndexStatsResponse = index.describe_index_stats(Some(Metadata { fields })).await?;

更新向量

以下示例将两个向量更新到具有主机index-host的索引中。

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::data::{Vector, UpsertResponse};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let vectors = [Vector {
    id: "id1".to_string(),
    values: vec![1.0, 2.0, 3.0, 4.0],
    sparse_values: None,
    metadata: None,
}, Vector {
    id: "id2".to_string(),
    values: vec1![2.0, 3.0, 4.0, 5.0],
    sparse_values: None,
    metadata: None,
}];

let response: UpsertResponse = index.upsert(&vectors, &"namespace".into()).await?;

查询向量

查询索引有两种支持的方式。

按索引查询

以下示例按主机index-host的索引查询ID为vector-id的向量，并返回前10个匹配项。

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::data::{Namespace, QueryResponse};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

// Connect to index at host "index-host"
let mut index = pinecone.index("index-host").await?;

// Query the vector with id "vector-id" in the namespace "namespace"
let response: QueryResponse = index.query_by_id(
    "vector-id".to_string(),
    10,
    &Namespace::default(),
    None,
    None,
    None
).await?;

按值查询

以下示例按主机index-host的索引查询值为[1.0, 2.0, 3.0, 4.0]的向量，并返回前10个匹配项。

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::data::{Namespace, QueryResponse};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let vector = vec![1.0, 2.0, 3.0, 4.0];

let response: QueryResponse = index.query_by_value(
    vector,
    None,
    10,
    &Namespace::default(),
    None,
    None,
    None
).await?;

删除向量

删除向量的支持有三种方式。

按ID删除

以下示例在命名空间namespace中删除ID为vector-id的向量。

use pinecone_sdk::pinecone::PineconeClientConfig;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let ids = ["vector-id"]

index.delete_by_id(&ids, &"namespace".into()).await?;

按过滤器删除

以下示例在命名空间namespace中删除满足过滤器的向量。

use std::collections::BTreeMap;
use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::data::{Metadata, Value, Kind, Namespace};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut fields = BTreeMap::new();
let kind = Some(Kind::StringValue("value".to_string()));
fields.insert("field".to_string(), Value { kind });

index.delete_by_filter(Metadata { fields }, &"namespace".into()).await?;

全部删除

以下示例在命名空间namespace中删除所有向量。

use pinecone_sdk::pinecone::PineconeClientConfig;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

index.delete_all(&"namespace".into()).await?;

获取向量

以下示例从默认命名空间获取ID为1和2的向量。

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::data::FetchResponse;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let vectors = &["1", "2"];

let response: FetchResponse = index.fetch(vectors, &Default::default()).await?;

更新向量

以下示例将命名空间namespace中ID为vector-id的向量更新为值[1.0, 2.0, 3.0, 4.0]。

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::data::UpdateResponse;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let response: UpdateResponse = index.update("vector-id", vec![1.0, 2.0, 3.0, 4.0], None, None, &"namespace".into()).await?;

列出向量

以下示例列出命名空间namespace中的向量。

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::data::{Namespace, ListResponse};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let response: ListResponse = index.list(&"namespace".into(), None, None, None).await?;

集合

创建集合

以下示例在索引index-name中创建一个名为collection-name的集合。

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::control::CollectionModel;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let collection: CollectionModel = pinecone.create_collection("collection-name", "index-name").await?;

列出集合

以下示例列出了项目中的所有集合。

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::control::CollectionList;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let collection_list: CollectionList = pinecone.list_collections().await?;

描述集合

以下示例描述了集合 collection-name。

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::pinecone::control::CollectionModel;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let collection: CollectionModel = pinecone.describe_collection("collection-name").await?;

删除集合

以下示例删除了集合 collection-name。

use pinecone_sdk::pinecone::PineconeClientConfig;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

pinecone.delete_collection("collection-name").await?;

贡献

如果您想做出贡献，或者在本地上配置以开发 Pinecone Rust 客户端，请参阅我们的贡献指南