LanceDB 怎么用：Python 本地向量库写入与相似度检索
LanceDB 是一个嵌入式向量数据库，不需要单独启动服务端，装好 Python 包后直接在本机目录里建库、建表、写数据。
如果你的需求是本地跑 RAG 原型、做小规模语义检索，它比 Milvus、Weaviate 这类需要 Docker 部署的方案更省事。
下面按安装、写入、查询、排错的顺序走一遍。
安装前确认 Python 环境和依赖
LanceDB 通过 pip 分发，建议 Python 3.9 以上。
先确认版本：
python3 --version
pip3 --version然后安装：
pip3 install lancedb如果同时要用到向量模型生成 embedding，再装 sentence-transformers 或你选用的模型库。
LanceDB 本身不负责把文本转成向量，它只存向量和做检索，这一点新手容易误解。
安装完成后用一行命令验证是否可用：
import lancedb
print(lancedb.__version__)能打印出版本号就说明环境没问题。
建库、建表和写入第一批数据
LanceDB 的数据组织方式是“库目录 + 表”。
库就是一个本地路径，表对应一组结构一致的记录。
示例代码如下：
import lancedb
import numpy as np
db = lancedb.connect("./lancedb_data")
data = [
{"id": 1, "text": "服务器磁盘满了怎么排查", "vector": np.random.rand(4).tolist()},
{"id": 2, "text": "Nginx 反向代理配置方法", "vector": np.random.rand(4).tolist()},
{"id": 3, "text": "MySQL 连接超时的处理", "vector": np.random.rand(4).tolist()},
]
table = db.create_table("docs", data=data)
print(table.count_rows())几个关键点：
connect的路径不存在时会自动创建，不需要提前mkdir。- 每条记录的
vector维度必须一致，这里是 4 维，实际使用中要和你的 embedding 模型输出维度对齐。 create_table如果表已存在会报错，重复运行时改用db.open_table("docs")或先删表。- 除向量外可以带任意标量字段，比如
text、id、category，后续可以用来过滤。
写入后执行 table.count_rows()，返回 3 说明数据已经落盘。
做一次相似度查询并验证结果
查询的核心是给一个查询向量，让 LanceDB 返回最接近的若干条记录：
query_vec = np.random.rand(4).tolist()
results = table.search(query_vec).limit(2).to_pandas()
print(results[["id", "text", "_distance"]])_distance 是距离值，数值越小表示越相似。
验证是否正常，可以看两点：返回条数是否等于 limit，以及 _distance 是否按升序排列。
如果不是升序，检查是否误用了其他距离度量。
需要按字段筛选时，在 search 后加 where：
results = table.search(query_vec).where("id > 1").limit(5).to_pandas()这样只会在满足条件的记录里做向量检索，适合按分类、时间范围缩小候选集的场景。
容易踩的坑和报错处理
维度不一致是最常见的报错，通常表现为写入或查询时提示向量长度不匹配。
处理方式是打印第一条记录的向量长度和查询向量长度做对比，确保两者一致。
重复建表会抛出表已存在的错误。
调试阶段可以每次运行前删除目录，生产环境则用 open_table 打开已有表再追加数据。
路径写错导致数据“消失”。connect 用的是相对路径时，结果取决于当前工作目录，建议在脚本里用绝对路径，避免换目录运行后读不到数据。
把文本直接当向量传入。
LanceDB 不会自动把字符串转成向量，必须先用模型生成 embedding 再写入，否则查询结果没有语义意义。
适用边界和下一步
LanceDB 适合单机、中小数据量、快速验证的场景，比如本地知识库原型、桌面应用内嵌检索。
它的优势是不用维护独立服务，数据以文件形式存在本地目录，备份和迁移就是拷贝目录。
如果数据量增长到需要多节点、高并发或集中运维，再考虑服务端向量数据库。
建议先按上面的代码在临时目录跑通一次写入和查询，确认 _distance 排序正确，再替换成真实 embedding 模型。
遇到异常时优先检查向量维度、表是否已存在、当前工作目录这三个点。
