TensorDB 快速上手：从安装到检索验证
TensorDB 是一个轻量级嵌入式向量数据库，不需要单独启动服务进程，安装 Python 包后就能在代码里直接建库、写入向量和执行相似度检索。
下面按实际使用顺序说明安装、初始化、数据写入、查询验证和常见问题处理，适合想快速验证向量检索效果的开发者。
安装与环境确认
TensorDB 通过 pip 分发，建议在 Python 3.8 及以上版本的虚拟环境中操作，避免污染系统环境。
先创建并激活虚拟环境（以 Linux/macOS 为例）：
python3 -m venv tensordb-env
source tensordb-env/bin/activateWindows 用户激活命令为 tensordb-env\Scripts\activate。
然后安装 TensorDB：
pip install tensordb安装完成后执行 pip show tensordb，能看到版本号和安装路径即表示成功。
如果提示找不到包，先检查 pip 源是否可用，必要时更换为国内镜像源再重试。
初始化数据库与集合
TensorDB 的数据以本地文件形式保存，初始化时需要指定存储目录和向量维度。
维度必须与后续写入的向量长度一致，否则会报维度不匹配错误。
import tensordb
client = tensordb.Client(path="./tensordb_data")
collection = client.create_collection(
name="demo",
dimension=4,
metric="cosine"
)path 是数据目录，不存在时会自动创建；metric 支持余弦相似度、内积等常见度量方式，按实际业务选择即可。
创建集合后不要重复执行 create_collection，如果集合已存在，应改用 client.get_collection("demo") 获取。
写入向量与元数据
写入时每条记录包含一个唯一 id、一个固定维度的向量和可选的元数据字典。
元数据用于后续过滤，不是必填项。
collection.add(
ids=["doc1", "doc2"],
vectors=[[0.1, 0.2, 0.3, 0.4], [0.9, 0.8, 0.7, 0.6]],
metadatas=[{"source": "faq"}, {"source": "manual"}]
)写入后可以用 collection.count() 检查记录数是否与预期一致。
如果数量不对，优先检查 id 是否重复，以及向量维度是否与创建集合时声明的维度相同。
执行相似度检索
查询时传入一个查询向量，TensorDB 会返回最相似的若干条记录及其距离分数。
results = collection.query(
query_vector=[0.1, 0.2, 0.3, 0.4],
top_k=2
)
print(results)返回结果通常包含 id、距离和元数据。
余弦相似度场景下，分数越接近 1 表示越相似；
内积场景则按具体度量解释。
第一次查询如果结果为空，先确认集合中已有数据，再检查查询向量维度是否与集合维度一致。
常见问题与避坑
- 导入报错
ModuleNotFoundError：确认虚拟环境已激活，且pip install tensordb是在同一环境中执行。 - 维度不匹配：创建集合时的
dimension必须等于每次写入和查询向量的长度，修改维度只能新建集合。 - 重复创建集合：
create_collection对已存在的集合可能抛出异常，代码中应先判断或改用get_collection。 - 数据目录权限不足：
path指向的目录需要当前用户有读写权限，生产环境建议使用独立数据盘并做好备份。
验证是否可用
完成写入和查询后，可以用一个已知相似的向量做一次小规模验证：写入两条内容相近的向量，查询其中一条，观察返回结果中另一条是否排在前面。
如果排序符合预期，说明度量方式和数据写入均正常。
对于批量导入场景，建议分批写入并定期用 count() 核对数量，避免一次性写入过多导致内存占用过高。
TensorDB 使用教程的核心在于先确认维度和度量方式，再按“建集合—写数据—查结果”的顺序操作。
遇到报错时优先检查环境、维度和集合是否存在，多数问题都能快速定位。
