企业官网建设流程全解析

Qdrant Edge Python 包怎么从源码构建？maturin 环境搭建与示例运行

【免费下载链接】qdrantQdrant - High-performance, massive-scale Vector Database and Vector Search Engine for the next generation of AI. Also available in the cloud https://cloud.qdrant.io/项目地址: https://gitcode.com/GitHub_Trending/qd/qdrant

如果你需要把 Qdrant Edge 以 Python 库的形式集成到自己的项目里，而不是依赖 PyPI 上发布好的 wheel，就需要从源码构建 Python 包qdrant-edge-py。这个包位于仓库的 lib/edge/python 目录，它是主 Cargo workspace 的成员（见根目录 Cargo.toml 的members列表），构建工具是 maturin，构建完成后可直接运行examples/下的示例脚本验证结果。

下面给出仓库文档中两条真实存在的路径：手动搭建 venv + maturin 的主路径，以及仓库自带的 Justfile 快捷路径。

准备条件

开始构建前确认以下几点，均对应仓库中的实际文件：

• 已 checkout qdrant 仓库源码，且 Rust 工具链可用。根目录 Cargo.toml 声明rust-version = "1.97"，Python 包及其路径依赖（segment、shard、sparse等，见 lib/edge/python/Cargo.toml）都依赖这套工具链编译。
• 本机有可用的python命令用于创建虚拟环境。
• 包元数据：crate 名为qdrant-edge-py，当前版本0.7.2，Python 导入名是qdrant_edge（[lib] name = "qdrant_edge"）。
• lib/edge/python/pyproject.toml 声明构建后端为maturin，要求版本maturin>=1.0,<2.0。

另外注意：Rust 端的qdrant-edgecrate 是另一个独立产物，放在 lib/edge/publish 目录、由amalgamate.py自动生成，与本文的 Python 包构建互不干扰。本文只覆盖 Python 包。

主路径：手动搭建 venv 并用 maturin 构建

以下是 lib/edge/README.md 给出的手动步骤：

# Setup environment cd lib/edge/python python -m venv .venv source .venv/bin/activate pip install --user maturin # Build and install the package: maturin develop --no-default-features # Run example: python examples/demo.py

各步骤的作用：

• python -m venv .venv在lib/edge/python下创建虚拟环境；source .venv/bin/activate激活它，后续命令都在这个环境中执行。
• pip install --user maturin安装构建工具。maturin 是 pyproject 指定的 build backend，版本需落在>=1.0,<2.0区间内。
• maturin develop --no-default-features编译 Rust 侧代码并把qdrant_edge模块开发安装进当前虚拟环境。--no-default-features是 README 中固定的写法（该 crate 的defaultfeature 本身就是空列表，见 lib/edge/python/Cargo.toml）。
• python examples/demo.py运行示例，作为构建结果的验证。

maturin develop首次编译会构建较多 Rust 依赖，耗时较长属于正常现象；命令结束且后续import qdrant_edge可用，说明构建成功。

可选路径：用仓库 Justfile 构建

lib/edge/README.md 同时提供了基于 lib/edge/Justfile 的快捷方式。Justfile 需要安装just工具，README 指出其来自https://github.com/casey/just（外部地址，自行安装即可）。安装后在仓库根目录执行：

just py-build just py-examples -e examples/demo.py

对照 Justfile 源码，这两条 recipe 实际执行的内容与手动路径有差异：

• py-build会先unset VIRTUAL_ENV，然后用uv venv --allow-existing创建/复用虚拟环境，uv pip install requests，最后执行maturin develop --no-default-features --features abi3。也就是说 Justfile 路径额外启用了abi3feature，对应 lib/edge/python/Cargo.toml 中的abi3 = ["pyo3/abi3-py310"]。该路径依赖uv和maturin都在 PATH 中可用。
• py-examples不带参数时会遍历examples/下所有非__init__.py的脚本并逐一用uv run --no-project执行；用-e examples/demo.py可以只跑指定的 demo，避免把示例全部执行一遍。

如果你不想管理 venv，可以直接走这条路径；如果你希望构建环境与仓库 CI 行为一致，推荐这条路径，否则按主路径手动执行即可。

运行示例并判断结果

examples/demo.py（完整源码见 lib/edge/python/examples/demo.py）覆盖了 Python 绑定的基本操作链：

1. 打印Point的转换结果（稠密向量与SparseVector）；
2. load_new_shard()创建一个 4 维、Distance.Dot的新 shard，随后执行 upsert、query、search、带Filter的 search、retrieve、scroll、count、facet、info；
3. 最后shard.close()，再用EdgeShard.load(TMP_DIR)重新打开，并打印Approx Points: {points_count}，用于确认关闭后重新打开的 shard 仍持有数据。

执行完成后，终端按顺序打印各阶段的分节标题（如---- Upsert ----、---- Query ----、---- Count ----等），脚本无异常退出即为通过。脚本没有失败时抛错或打印错误信息，因此以"跑完整段输出、最后打印 reopened 的点数"作为判断依据，不要把某个具体点数当作固定预期。

一个必须知道的副作用：示例通过 lib/edge/python/examples/common.py 把数据写入仓库内的lib/edge/data/tmp目录，且load_new_shard()每次都会先删除并重建该目录（源码注释写明 "clears DATA_DIRECTORY first"）。运行示例会修改这个目录下的内容，重复运行会清空上一次的临时 shard 数据；prepare-data等其它 recipe 也围绕lib/edge/data工作，注意不要在里面存放重要文件。

构建产物的使用与限制

• maturin develop把模块装进你激活的虚拟环境，直接import qdrant_edge使用；仓库中同时提供 lib/edge/python/qdrant_edge.pyi 类型桩和py.typed标记，pyproject 会把它们打进 wheel，供 IDE 使用。
• examples/下还有bm25-search.py、hybrid_search_dbsf.py、restore-snapshot.py、optimize.py等其它示例，可用just py-examples -e <脚本名>或激活环境后python <脚本名>单独运行。
• 要修改包内代码时，直接编辑lib/edge/python/src/及lib/下的原始 crate 即可；README 明确说 Rust 端publish/目录下的qdrant-edge包是自动生成的，Python 包则不存在这一层。
• 本文只覆盖本地源码构建与示例验证。要连接远程 Qdrant 实例应使用qdrant-client包（见 lib/edge/python/README.md），与 Edge 的嵌入式定位不同，不属于本文路径。

【免费下载链接】qdrantQdrant - High-performance, massive-scale Vector Database and Vector Search Engine for the next generation of AI. Also available in the cloud https://cloud.qdrant.io/项目地址: https://gitcode.com/GitHub_Trending/qd/qdrant