---

Lance 是一种面向多模态 AI 的开放湖仓格式。它包含文件格式、表格式和目录规范，允许您在对象存储之上构建完整的湖仓，以驱动您的 AI 工作流。Lance 非常适合：

1. 构建具有混合搜索能力的搜索引擎和特征存储。
2. 需要高性能 IO 和随机访问的大规模 ML 训练。
3. 存储、查询和管理多模态数据，包括图像、视频、音频、文本和嵌入。

Lance 的关键特性包括：

• 表达力强的混合搜索： 在同一数据集上结合向量相似度搜索、全文搜索（BM25）和 SQL 分析，并支持加速的二级索引。

• 极速随机访问： 在不牺牲扫描性能的情况下，随机访问速度比 Parquet 或 Iceberg 快 100 倍。

• 原生多模态数据支持： 使用高效的 blob 编码和延迟加载，在单一统一格式中存储图像、视频、音频、文本和嵌入。

• 数据演化： 高效地添加带有回填值的列，无需全表重写，非常适合 ML 特征工程。

• 零拷贝版本控制： 自动版本控制，支持 ACID 事务、时间旅行、标签和分支——无需额外基础设施。

• 丰富的生态系统集成： Apache Arrow、Pandas、Polars、DuckDB、Apache Spark、Ray、Trino、Apache Flink 以及开放目录（Apache Polaris、Unity Catalog、Apache Gravitino）。

有关更多详细信息，请参阅完整的 Lance 格式规范。

[!TIP] Lance 正处于积极开发阶段，我们欢迎贡献。请参阅我们的贡献指南以获取更多信息。

文件格式稳定性

Lance 发布频繁，因为 SDK、集成和性能工作进展迅速。这并不意味着 Lance 文件格式在每个版本中都会发生不兼容的变更。Lance 文件格式由存储在每个数据集中的 data_storage_version 标识，稳定的存储版本是长期兼容性契约。

• 一旦数据集使用稳定的 data_storage_version 写入，未来的 Lance 版本将继续支持读取该存储版本。
• SDK 和 API 兼容性与文件格式兼容性是分开的。SDK/API 变更遵循语义化版本控制，并在迁移指南中记录。
• 较旧的 Lance 版本可能无法理解后来引入的文件格式版本。如果您运行混合的 Lance 版本，请固定 data_storage_version 以实现确定性写入。
• next 文件格式别名是不稳定的，仅应用于实验，切勿用于生产数据。

对于生产环境，请使用稳定的 data_storage_version 写入数据。请参阅格式版本控制指南以获取当前的兼容性矩阵。

快速入门

安装

pip install pylance

要安装预览版：

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

[!TIP] 预览版发布频率高于正式版，并包含 最新的功能和错误修复。它们接受与正式版相同级别的测试。 我们保证它们将保持发布状态并可供下载，至少 持续 6 个月。当您希望固定到特定版本时，请优先选择稳定版。

转换为 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")

读取 Lance 数据

dataset = lance.dataset("/tmp/test.lance")
assert isinstance(dataset, pa.dataset.Dataset)

Pandas

df = dataset.to_table().to_pandas()
df

DuckDB

import duckdb

# If this segfaults, make sure you have duckdb v0.7+ installed
duckdb.query("SELECT * FROM dataset LIMIT 10").to_df()

向量搜索

下载 sift1m 子集

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

将其转换为 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)

构建索引

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

搜索数据集

# Get top 10 similar vectors
import duckdb

dataset = lance.dataset(uri)

# Sample 100 query vectors. If this segfaults, make sure you have duckdb v0.7+ installed
sample = duckdb.query("SELECT vector FROM dataset USING SAMPLE 100").to_df()
query_vectors = np.array([np.array(x) for x in sample.vector])

# Get nearest neighbors for all of them
rs = [dataset.to_table(nearest={"column": "vector", "k": 10, "q": q})
      for q in query_vectors]

目录结构

目录	描述
rust	核心 Rust 实现
python	Python 绑定 (PyO3)
java	Java 绑定 (JNI)
docs	文档源

基准测试

向量搜索

我们使用 SIFT 数据集对 1M 个 128D 向量进行了基准测试

1. 对于 100 个随机采样的查询向量，我们获得了 <1ms 的平均响应时间（在 2023 款 m2 MacBook Air 上）

2. ANNs 始终是召回率与性能之间的权衡

对比 Parquet

我们使用 Oxford Pet 数据集创建了一个 Lance 数据集，以进行 Lance 与 Parquet 及原始图像/XML 的初步性能测试。对于分析查询，Lance 比读取原始元数据快 50-100 倍。对于批量随机访问，Lance 比 Parquet 和原始文件都快 100 倍。

为什么在 AI/ML 工作流中选择 Lance？

机器学习开发周期包含多个阶段：

graph LR
    A[Collection] --> B[Exploration];
    B --> C[Analytics];
    C --> D[Feature Engineer];
    D --> E[Training];
    E --> F[Evaluation];
    F --> C;
    E --> G[Deployment];
    G --> H[Monitoring];
    H --> A;

传统湖仓格式专为 SQL 分析而设计，难以应对需要以下能力的 AI/ML 工作负载：

• 向量搜索 用于相似性和语义检索
• 快速随机访问 用于采样和交互式探索
• 多模态数据 存储（图像、视频、音频与嵌入向量并存）
• 数据演化 用于无需全表重写的特征工程
• 混合搜索 结合向量、全文和 SQL 谓词

尽管现有格式（Parquet、Iceberg、Delta Lake）在 SQL 分析方面表现出色，但它们需要额外的专用系统来支持 AI 能力。Lance 将这些 AI 优先的特性直接引入湖仓格式。

不同格式在 ML 开发各阶段的对比：

	Lance	Parquet & ORC	JSON & XML	TFRecord	Database	Warehouse
Analytics	Fast	Fast	Slow	Slow	Decent	Fast
Feature Engineering	Fast	Fast	Decent	Slow	Decent	Good
Training	Fast	Decent	Slow	Fast	N/A	N/A
Exploration	Fast	Slow	Fast	Slow	Fast	Decent
Infra Support	Rich	Rich	Decent	Limited	Rich	Rich