lance

环境要求

• Python 环境（需可通过 pip 安装包）
• pip 包管理器
• 使用 DuckDB 查询时需 duckdb v0.7+（否则可能 segfault）
• 会用到 pandas、pyarrow、numpy（示例代码中导入）

安装与启动步骤

1. 1安装 pylance

   README 给出的标准安装方式，用 pip 安装稳定版 pylance 包即可开始使用。

   pip install pylance

   复制

2. 2可选安装预览版

   预览版发布更频繁，包含最新特性和修复；如需固定版本建议优先用稳定版。

   pip install --pre --extra-index-url https://pypi.fury.io/lance-format pylance

   复制

3. 3将 Parquet 转为 Lance

   用 pandas 造一个 DataFrame，先写成 parquet，再用 lance.write_dataset 转成 lance 格式。

   import lance
   import pandas as pd
   import pyarrow as pa
   import pyarrow.dataset
   
   df = pd.DataFrame({"a": [5], "b": [10]})
   uri = "/tmp/test.parquet"
   tbl = pa.Table.from_pandas(df)
   pa.dataset.write_dataset(tbl, uri, format='parquet')
   
   parquet = pa.dataset.dataset(uri, format='parquet')
   lance.write_dataset(parquet, "/tmp/test.lance")

   复制

4. 4读取 Lance 数据

   用 lance.dataset 打开 .lance 目录，返回的是 pyarrow Dataset，可转成 Pandas DataFrame。

   import lance
   import pyarrow as pa
   
   dataset = lance.dataset("/tmp/test.lance")
   assert isinstance(dataset, pa.dataset.Dataset)
   df = dataset.to_table().to_pandas()
   print(df)

   复制

5. 5下载 sift1m 数据

   README 提供的向量检索示例数据集，用 wget 下载后解压得到 sift 目录。

   wget ftp://ftp.irisa.fr/local/texmex/corpus/sift.tar.gz
   tar -xzf sift.tar.gz

   复制

6. 6写入向量数据

   读取 sift_base.fvecs 二进制，转成向量表后写入 vec_data.lance，可设置分组和文件行数。

   import lance
   from lance.vector import vec_to_table
   import numpy as np
   import struct
   
   nvecs = 1000000
   ndims = 128
   with open("sift/sift_base.fvecs", mode="rb") as fobj:
       buf = fobj.read()
       data = np.array(struct.unpack("<128000000f", buf[4 : 4 + 4 * nvecs * ndims])).reshape((nvecs, ndims))
       dd = dict(zip(range(nvecs), data))
   
   table = vec_to_table(dd)
   uri = "vec_data.lance"
   sift1m = lance.write_dataset(table, uri, max_rows_per_group=8192, max_rows_per_file=1024*1024)

   复制

7. 7构建向量索引

   对 vector 列建 IVF_PQ 索引，num_partitions 对应 IVF，num_sub_vectors 对应 PQ。

   sift1m.create_index("vector",
                       index_type="IVF_PQ",
                       num_partitions=256,  # IVF
                       num_sub_vectors=16)  # PQ

   复制

8. 8执行相似性搜索

   用 DuckDB 从数据集中抽样 100 个查询向量，作为后续搜索的输入。

   import duckdb
   import numpy as np
   
   sample = duckdb.query("SELECT vector FROM dataset USING SAMPLE 100").to_df()
   query_vectors = np.array([np.array(x) for x in sample.vector])

   复制

关键配置

如何确认成功

执行 lance.dataset("/tmp/test.lance") 返回 pyarrow Dataset 对象，且可 to_pandas() 打印出数据。

常见问题

注意事项

• README 中的所有示例路径（如 /tmp/test.lance、vec_data.lance、sift/sift_base.fvecs）均为示例，实际使用时替换为自己环境中的路径。
• 预览版通过 --extra-index-url https://pypi.fury.io/lance-format 安装，正式版直接 pip install pylance。
• Lance 兼容 Pandas、DuckDB、Polars、PyArrow、Ray、Spark 等工具，更多集成仍在扩展中。