lance.LanceDataset.create_index(列: str | list[str], index_type: str, name: str | None = None, metric: str = 'L2', 替换: bool = False, num_partitions: int | None = None, ivf_centroids: np.ndarray | pa.FixedSizeListArray | pa.FixedShapeTensorArray | None = None, pq_codebook: np.ndarray | pa.FixedSizeListArray | pa.FixedShapeTensorArray | None = None, num_sub_vectors: int | None = None, accelerator: str | 'torch.Device' | None = None, index_cache_size: int | None = None, shuffle_partition_batches: int | None = None, shuffle_partition_concurrency: int | None = None, ivf_centroids_file: str | None = None, precomputed_partition_dataset: str | None = None, storage_options: dict[str, str] | None = None, filter_nan: bool = True, one_pass_ivfpq: bool = False, **kwargs) → LanceDataset

在列上创建索引。

实验性API

Parameters:
column : str

要建立索引的列。

index_type : str

索引的类型。 "IVF_PQ, IVF_HNSW_PQ 和 IVF_HNSW_SQ" 目前支持。

name : str, optional

索引名称。如果未提供，将根据列名自动生成。

metric : str

距离度量类型，即“L2”（“euclidean”的别名）、“cosine”或“dot”（点积）。默认为“L2”。

replace : bool

如果索引已存在，则替换现有索引。

num_partitions : int, optional

IVF（倒排文件索引）的分区数量。

ivf_centroids : optional

它可以是np.ndarray、 pyarrow.FixedSizeListArray或 pyarrow.FixedShapeTensorArray。 一个num_partitions x dimension维度的现有K均值中心点数组， 用于IVF聚类。如果未提供，将训练一个新的KMeans模型。

pq_codebook : optional,

它可以是np.ndarray、pyarrow.FixedSizeListArray， 或pyarrow.FixedShapeTensorArray。 一个num_sub_vectors x (2 ^ nbits * dimensions // num_sub_vectors) 数组，表示PQ码本的K均值中心点。

注意：目前nbits始终为8。 如果未提供，将训练一个新的PQ模型。

num_sub_vectors : int, optional

PQ（乘积量化）的子向量数量。

accelerator: str | 'torch.Device' | None = None

如果设置，将使用加速器来加快训练过程。 支持的加速器包括："cuda"（英伟达GPU）和"mps"（苹果硅GPU）。 如果未设置，则使用CPU。

index_cache_size : int, optional

索引缓存的大小，以条目数表示。默认值为256。

shuffle_partition_batches : int, optional

批次数，使用数据集的row group大小，决定每个shuffle分区包含的数量。默认值为10240。

假设row group大小为1024，每个shuffle分区将包含10240 * 1024 = 10,485,760行。减小此值会减少shuffle操作的内存消耗但会增加完成时间，反之亦然。

shuffle_partition_concurrency : int, optional

并发处理的shuffle分区数量。默认值为2

减小该值可以减少shuffle操作的内存消耗，但会增加完成时间，反之亦然。

storage_options : optional, dict

针对特定存储连接的额外选项。这用于存储连接参数，如凭证、端点等。

filter_nan : bool

默认为True。False是不安全的，如果存在任何null/nan值会导致崩溃（否则不会）。禁用用于可空列的空值过滤器。可获得小幅速度提升。

one_pass_ivfpq : bool

默认为False。如果启用，索引类型必须为“IVF_PQ”。可减少磁盘IO。

**kwargs

传递给索引构建过程的参数。

SQ（标量量化）仅适用于IVF_HNSW_SQ索引类型，这种量化方法用于减少索引的内存占用，它将浮点向量映射为整数向量，每个整数占用num_bits位，目前仅支持8位。

If index_type is “IVF_*”, then the following parameters are required:

num_partitions

If index_type is with “PQ”, then the following parameters are required:

子向量数量

IVF_PQ的可选参数：

  • ivf_centroids

    用于IVF聚类的现有K均值中心点。

  • num_bits

    PQ(乘积量化)的位数。默认为8。 仅支持4和8。

Optional parameters for IVF_HNSW_*:
max_level

Int，图中最大层级数。

m

Int，图中每个节点的边数。

ef_construction

Int，构建过程中需要检查的节点数量。

示例

import lance

dataset = lance.dataset("/tmp/sift.lance")
dataset.create_index(
    "vector",
    "IVF_PQ",
    num_partitions=256,
    num_sub_vectors=16
)

import lance

dataset = lance.dataset("/tmp/sift.lance")
dataset.create_index(
    "vector",
    "IVF_HNSW_SQ",
    num_partitions=256,
)

实验性加速器（GPU）支持：

  • accelerate: 使用GPU训练IVF分区。

    目前仅支持CUDA(Nvidia)或MPS(Apple)。 需要安装PyTorch。

import lance

dataset = lance.dataset("/tmp/sift.lance")
dataset.create_index(
    "vector",
    "IVF_PQ",
    num_partitions=256,
    num_sub_vectors=16,
    accelerator="cuda"
)

参考文献