快速开始

本文带你从克隆仓库到第一次向量搜索,全程不超过 5 分钟。

1. 编译原生库

C 核心没有外部依赖——只需要 C 编译器和 CMake 3.15+。

Windows (MSVC)

scripts\windows\build.bat Release

Linux (GCC/Clang)

bash scripts/linux/build.sh Release

macOS (Apple Clang)

bash scripts/macos/build.sh Release

脚本会自动识别主机架构,并将产物拷贝到 libs/<os>/<arch>/ (例如 libs/linux/x86_64/libpistadb.so)。产出的库零运行时依赖。

2. 安装 Python 绑定

pip install -e wrap/python/

包装器在导入时会自动从 libs/<os>/<arch>/ 查找原生库,在仓库内开发时无需设置环境变量。

想在独立的 Python 项目里使用 PistaDB?参见仓库根目录的 INTEGRATION.md: 库文件 vendoring、PISTADB_LIB_DIR / PISTADB_LIB_PATH、以及 Docker 部署方案。

3. 你的第一次搜索

import numpy as np
from pistadb import PistaDB, Metric, Index, Params

# 1536 维 HNSW 索引 + 余弦距离 —— 文本嵌入的良好默认配置
params = Params(hnsw_M=16, hnsw_ef_construction=200, hnsw_ef_search=50)

with PistaDB("mydb.pst", dim=1536,
             metric=Metric.COSINE, index=Index.HNSW, params=params) as db:

    # 插入一条向量,附带可选的人类可读 label
    vec = np.random.rand(1536).astype("float32")
    db.insert(1, vec, label="chunk_0001")

    # k-NN 搜索
    query = np.random.rand(1536).astype("float32")
    results = db.search(query, k=10)
    for r in results:
        print(f"id={r.id}  dist={r.distance:.4f}  label={r.label!r}")

    db.save()  # 落盘

完整循环就是这三步:insert、search、save。没有服务端,也不强制 schema。

4. 运行测试套件

确认链接正确:

Windows

set PISTADB_LIB_DIR=build\Release
pytest tests\ -v

Linux / macOS

PISTADB_LIB_DIR=build pytest tests/ -v

你应该看到 148 / 148 全部通过。

接下来

• 为你的工作负载选择合适的索引算法。
• 当单个 label 不够用时,使用 Schema / Collection API。
• 查看 Go、Rust、Swift、Kotlin、C#、Julia、WASM 的语言绑定。