Qdrant Edge 包构建与发布实战指南Rust/Python 嵌入式向量检索引擎的配方、工作区与发布流程【免费下载链接】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/qdrantQdrant Edge 是 Qdrant 面向嵌入式设备、自动驾驶系统与移动 Agent 场景提供的轻量级进程内向量检索引擎它以库的形式嵌入宿主程序运行不依赖后台服务内存占用极小并可与 Qdrant Cloud 进行可选的数据同步。本文基于 lib/edge/README.md 与 lib/edge/Justfile系统讲解 Qdrant Edge 仓库中 Rust 包与 Python 包的组织方式、完整构建/检查/示例运行流程以及将 Rust 包发布到 crates.io 的操作步骤。读完本文你将能够独立在本地跑通qdrant-edgeRust与qdrant-edge-pyPython两套包的校验与示例程序理解代码合并生成、独立工作区等发布机制并能按官方流程完成版本发布。Qdrant Edge 在仓库中的定位lib/edge目录是 Qdrant 主仓库中专门承载 Edge 相关交付物的一级目录它并非一套传统的单一 Rust crate而是一组围绕如何把 Qdrant 的向量检索能力打包成可嵌入式库而组织的子工程集合。仓库中给出的一手定位描述见 python/README.md 与 publish/README.md是Qdrant Edge is a lightweight, in-process vector search engine designed for embedded devices, autonomous systems, and mobile agents. It enables on-device retrieval with minimal memory footprint, no background services, and optional synchronization with Qdrant Cloud.翻译过来即轻量级、进程内in-process向量检索引擎面向嵌入式设备、自主系统和移动端 Agent 场景实现设备端检索内存占用极小无需后台常驻服务并可选与 Qdrant Cloud 同步。需要特别注意的是如果你的场景是连接远程 Qdrant 实例应改用官方的qdrant-clientPython 侧对应 python/README.md 中说明的 PyPI 包qdrant-clientEdge 包解决的是把检索引擎直接跑在自己进程里的问题。整个lib/edge顶层由一个 Justfile 统一驱动——它为 Rust 与 Python 两套边缘包提供了check/ 构建 / 示例运行等一系列配方recipe。Justfile 是一个任务运行器定义文件使用前需要安装命令运行器just。目录结构速览在深入各配方之前先整体把握lib/edge下各子目录的职责对照lib/edge目录树路径职责lib/edge/Justfile面向 Edge 开发者的统一命令入口覆盖 Rust/Python 的检查、构建、示例运行lib/edge/publishRustqdrant-edge包所在的独立工作区与主工作区解耦专用于 crates.io 发布lib/edge/publish/amalgamate.py自动合并多个主仓库 crate 为单一qdrant-edge包的脚本产物输出到./publish/qdrant-edgegitignore 忽略lib/edge/publish/examplesRust 侧示例程序含demo.rs等若干 bin 目标lib/edge/pythonPythonqdrant-edge-py包属于主工作区的一部分通过 maturin PyO3 构建lib/edge/python/examplesPython 侧示例脚本含demo.py等lib/edge/ffi基于 uniffi 的 FFI 绑定层uniffi.toml、bindgen 等用于向其他语言暴露接口lib/edge/srcEdge 核心 Rust 库源码edge_shard、read_only、read_view、update_only、builders、requests、config等模块其中核心库入口 lib/edge/src/lib.rs 导出了EdgeShard、EdgeShardRead、ReadOnlyEdgeShard、UpdateOnlyEdgeShard、EdgeConfig、QueryRequestBuilder、SearchRequestBuilder等一系列类型与构建器它们是所有 Edge 示例与 API 绑定的公共基础。注意一个设计上的差异Rust 发布包是独立工作区而 Python 包是主工作区的一部分——这一点直接影响下面的构建命令在何处执行。统一命令入口Justfile 配方清单lib/edge/Justfile 将边缘包日常最常用的操作封装为若干配方每个配方都带注释说明用途方便人类阅读与 CI 调用。下面整理各配方及其确切语义均以lib/edge目录为执行起点配方说明关键行为just help打印可用配方just --unsorted --listjust prepare-data准备lib/edge/data下的数据文件先探测本机localhost:6333是否运行了 qdrant随后调用tools/prepare_facet_snapshot.shjust check全量检查并运行全部示例依序执行rs-check、rs-examples-build、rs-examples、py-build、py-examplesjust rs-checkRust 检查在publish目录中先跑./amalgamate.py再cargo nightly fmt -p examples -- --check最后用./cargo clippy -p examples --all-targets --no-deps -- -D warningsjust rs-examples-build构建 Rust 示例可选在publish目录./amalgamate.py后执行./cargo build -p examplesjust rs-examples运行 Rust 示例在publish目录中遍历 examples 的全部 bin 目标逐一cargo run任一失败会汇总并报错退出可用-e demo只跑指定示例just rs-examples-list列出 Rust 示例 bin 名通过cargo metadata配合jq解析出examples包中所有bin目标just py-build构建 Python 包在python目录unset VIRTUAL_ENV后uv venv --allow-existing安装requests再maturin develop --no-default-features --features abi3just py-examples运行 Python 示例在python目录遍历examples/*.py排除__init__.py用uv run --no-project执行可-e examples/demo.py指定单个just py-examples-list列出 Python 示例文件find examples -name *.py -not -name __init__.py几个值得留意的实现细节just rs-check刻意使用--no-depsJustfile 中注释说明了原因自动生成的qdrant-edge包里有大量警告检查范围应限定在示例代码本身。clippy 与 fmt 都只针对examples包说明 Rust 侧示例程序就是一套集成的冒烟测试能覆盖编译与运行两个层面。配方中大量使用./cargo而非cargo这是publish工作区自带的 cargo 包装脚本配合working-directory: publish的目录注解使用。Rust Qdrant Edge 包独立工作区与合并生成机制为什么是独立工作区按 lib/edge/README.md 的说明Rust Qdrant Edge workspace lives in the publish directory. Its a separate workspace, not tied to the main workspace.即publish是一个不挂在主工作区下的独立工作区。这样设计的目的很明确发布到 crates.io 的qdrant-edge需要一张干净、自洽的依赖图不能携带主工作区中的路径依赖、workspace 继承与构建期依赖。amalgamate.py把多个 crate 揉成一个包qdrant-edge包本体是自动生成的生成脚本是 lib/edge/publish/amalgamate.py产物落在./publish/qdrant-edge已被 gitignore不会进版本库。脚本注释对 amalgamation 的解释是The process of combining multiple crates into a single one. Used to prevent namespace pollution when publishing to crates.io.——把多个 crate 合并为单个 crate目的是避免 crates.io 发布时的命名空间污染。脚本头部amalgamate.py明确列出了参与合并的包列表PACKAGES_TO_INCLUDE [ bm25, common, edge, blobstore, posting_list, quantization, segment, shard, sparse, wal, ]也就是说一个功能完整的 Edge 运行时实际是segment向量分段、shard分片逻辑、quantization量化、bm25全文检索、sparse稀疏向量、wal预写日志、blobstore、posting_list、common等主仓库 crate 的有机组合最终在发布时统一收拢成qdrant-edge一个 crate。合并过程中还会剔除构建期依赖例如prost-build、tonic-build见脚本中的EXCLUDED_DEPENDENCIES。这一机制带来一个重要开发约束README 特别强调If you need to make changes in theqdrant-edgepackage, edit the original packages in this repo (/libin the repo root).不要直接修改生成的qdrant-edge包——需要改动时应回到主仓库/lib下的原始 crate即 lib/segment、lib/shard、lib/edge 等中修改再重新跑amalgamate.py重新生成。这正是单一事实来源思想的体现源码头在本仓库发布包只是构建产物。构建与运行 Rust 示例README 给出的最简路径是执行 Justfile 配方just rs-examplesrs-examples会在publish目录中先自动执行./amalgamate.py确保生成包最新再逐个构建并运行全部示例 bin。如果只想跑某个示例使用just rs-examples -e demo也可以完全绕开just手动按步骤执行# 先进入 Rust 发布工作区 cd lib/edge/publish # 1) 重新生成 qdrant-edge 包 ./amalgamate.py # 2) 编译检查 examples cargo check -p examples # 3) 运行某个示例 cargo run -p examples --bin demo # 其他 bin 依此类推 # cargo run -p examples --bin bm25-search # cargo run -p examples --bin add-named-vector # cargo run -p examples --bin fusion-query # …示例程序的完整清单以 lib/edge/publish/examples/src/bin 目录为准当前包含以下 bin 目标bin 目标演示主题demo端到端主流程写入点、query/search/scroll/count、过滤、facet、info、关闭并重开分片bm25-searchBM25 全文检索能力add-named-vector命名向量含稀疏向量的使用fusion-query多路召回融合fusion查询mmr-queryMMR 多样性重排查询load-existing加载已有数据/分片restore-snapshot快照恢复facet_testfacet 聚合测试如果只想做格式与 clippy 检查而不运行可以先执行just rs-checkrs-check等价于手动依次执行./amalgamate.py、cargo nightly fmt -p examples -- --check与./cargo clippy -p examples --all-targets --no-deps -- -D warnings。直接查看 Rust 示例效果以 demo.rs 为例能直观看到 Rust 侧 API 的调用形态。程序先是构造了多种点结构多稠密向量、命名稀疏向量演示转换// 多稠密向量点 PointStruct::new( 10u64, Vectors::try_from(vec![vec![1.0, 2.0, 3.0], vec![3.0, 4.0, 5.0]])?, json!({}), ), // 命名稀疏向量点 PointStruct::new( 11, qdrant_edge::Vectors::new_named([( sparse, Vector::new_sparse(vec![0, 2], vec![1.0, 3.0]).unwrap(), )]), json!({}), ),随后基于EdgeShard完成建分片、upsert、query、search、加过滤的 search、retrieve、scroll含翻页 offset、count、facet、info最后演示EdgeShard::load重新打开分片// 关闭后重新打开验证持久化 drop(shard); let reopened_shard EdgeShard::load(Path::new(TMP_DIR), None)?; println!( Edge shard reopened. Approx Points: {}, reopened_shard.info()?.points_count );示例中的load_new_shard()辅助函数见 publish/examples/src/lib.rs还会先清空并重建data/tmp目录并用EdgeConfig::builder().vector(DEFAULT_VECTOR_NAME, EdgeVectorParams::builder(4, Distance::Dot).build())声明一个 4 维、Dot 距离的向量配置——这是学习EdgeConfig/EdgeVectorParams用法的最佳模板。如何发布 Rust 包到 crates.iolib/edge/README.md 把 Rust 侧的发布流程收敛为两个步骤升级版本号修改 publish/amalgamate.py 中的VERSION常量当前值为0.7.2与 Python 侧 python/Cargo.toml 的version 0.7.2保持一致。因为版本同时写入合并产物改版本必须先改这里再重新合并生成。触发发布工作流运行仓库中的Qdrant Edge Rust Release工作流CI 定义在仓库的 GitHub Actions 配置中由 CI 完成amalgamate.py生成、编译校验并真正推送 crates.io 的完整动作。README 强调版本发布与代码修改解耦日常功能迭代只改/lib原始 crate 并跑just rs-check验证只有要对外发新版本时才动amalgamate.py的VERSION并触发发布工作流。这能最大程度避免手动改发布产物带来的漂移风险。Python Qdrant Edge 包maturin PyO3 构建包结构与构建方式Python 包位于 lib/edge/python与 Rust 发布包相反它是主工作区的一部分直接以路径依赖方式引用edge、segment、shard、sparse等主工作区 crate见 python/Cargo.toml库名为qdrant_edgecrate 类型为cdylib通过 PyO3pyo3 0.29暴露 Python 接口。构建后端采用 maturinpyproject.toml 中build-backend maturin。README 给出的运行路径同样是先走justjust py-build just py-examplespy-build配方的关键动作见 Justfile是unset VIRTUAL_ENV uv venv --allow-existing uv pip install requests maturin develop --no-default-features --features abi3这里启用了abi3feature即 python/Cargo.toml 中abi3 [pyo3/abi3-py310]使生成的扩展模块绑定到 Python 3.10 起的稳定 ABI从而一个 wheel 即可跨多个 Python 小版本使用。手动构建与运行若不想用justREADME 提供了完整的手动流程需自行确保 Python 环境就绪maturin可通过pip install maturin安装# 1) 创建并激活虚拟环境 cd lib/edge/python python -m venv .venv source .venv/bin/activate # 2) 安装构建工具 maturin pip install maturin # 3) 构建并安装到当前环境开发模式 cd lib/edge/python maturin develop --no-default-features # 4) 运行示例 python examples/demo.pymaturin develop会把编译出的扩展就地安装到当前虚拟环境省去每次改代码后重新打包的环节是最适合迭代开发的命令。类型体验pyi 与 py.typedPython 包在 wheel 构建时会附带类型存根 qdrant_edge.pyi 与 py.typed 标记文件见 pyproject.toml 中的include配置从而为 IDE 补全与类型检查提供完整支持。存根文件非常详尽——例如EdgeShard类给出了load(path, configNone)加载已存在分片若传入 config 会做兼容性检查并覆盖磁盘配置与create(path, config)在空路径新建分片两个静态方法以及flush、close、optimize、update、query、search、retrieve、scroll、count、facet等全套方法签名并定义了PointId、Vector、Filter、Query等类型别名。Python 示例与 Rust 示例一一对应。以 demo.py 为例核心流程与 Rust 版demo.rs完全平行用UpdateOperation.upsert_points(...)写入点、用QueryRequest(queryQuery.Nearest(...), limit10, ...)查询、用Filter(must[...])组合文本匹配与范围过滤、用shard.facet(FacetRequest(key..., limit10, ...))做聚合最后shard.close()后调用EdgeShard.load(TMP_DIR)重新打开分片并读取points_count。Python 侧完整示例清单位于 lib/edge/python/examples除demo.py、common.py外还包括add-named-vector.py、bm25-search.py、fusion-query.py、hybrid_search_dbsf.py、load-existing.py、mmr-query.py、optimize.py、repr.py、restore-snapshot.py、sparse-search.py等。其中 common.py 提供load_new_shard()清空data/tmp后用EdgeConfig(vectorsEdgeVectorParams(size4, distanceDistance.Dot))新建分片与fill_dummy_data()写入 10 条带 color/city/rating/tags 等负载的示例数据被多数示例复用是快速体验的起点。check 全量配方一次跑通全部质量门禁日常开发或 CI 中最常用的一条命令是just check它等价于依次执行rs-check→rs-examples-build→rs-examples→py-build→py-examples覆盖了 Rust 侧的格式化/静态检查/示例运行与 Python 侧的构建/示例运行。整个检查链路对just、cargo nightly、uv、maturin、python等工具链有依赖建议在干净环境中一次补齐后再执行。若只想检查其中一侧可按需组合上文列出的子配方例如只做 Python 侧just py-build just py-examples只做 Rust 侧just rs-check just rs-examples。数据准备与周边工具除构建与示例外lib/edge还包含一组服务于开发调试的辅助脚本just prepare-data会在本机localhost:6333未运行 qdrant 时给出提示并通过 tools/prepare_facet_snapshot.sh 准备 facet 快照等测试数据供示例程序消费。tools/shard_query与tools/shard_update分别提供读取主仓库产生的 shard 数据与向 shard 下发更新的独立小工具各自带 SKILL.md 说明便于直接对真实分片目录做查询/更新实验。tools/s3_proxy、tools/download_partial.py用于在快照场景中模拟 S3 代理、按范围下载文件等网络相关调试。lib/edge/ffi存放 uniffi 风格的 FFI 绑定ffi/Cargo.toml、uniffi.toml用于把 Edge 能力桥接到非 Rust 宿主语言。这些工具与 Justfile 一起构成了围绕 Edge 交付物相对完整的开发闭环改源码 →just rs-check静态把关 →just rs-examples/py-examples跑示例 →prepare-data准备数据 → 发布时改VERSION并触发发布工作流。小结与注意事项Qdrant Edge 的工程组织呈现出三个清晰的层次核心库层lib/edge/srcEdgeShard 及读写/只读/仅更新等视图与全部请求构建器是 Rust 与 Python 两侧共享的能力底座发布封装层Rust 侧经 amalgamate.py 将segment、shard、quantization、bm25、sparse、wal等主仓库 crate 合并为独立的qdrant-edgecrate 发布Python 侧以主工作区内 crate 为依赖经 maturin PyO3 打包为qdrant-edge-py开发编排层一份 Justfile 统管两侧的检查、构建与示例运行并配套 publish/examples 与 python/examples 两套互相平行的示例作为冒烟验证。实践中的关键提醒改动生成包没有意义qdrant-edge由脚本生成且被 gitignore任何修改都应落到 lib 下对应的原始 crate否则会在下次amalgamate.py运行时丢失。Rust 与 Python 工作区归属不同Rust 发布工作区在lib/edge/publish独立Python 包在lib/edge/python从属主工作区执行命令时务必进入正确的目录或直接使用just配方配方自带working-directory注解。版本号同步Rust 侧版本以 amalgamate.py 中的VERSION为准发布前更新并触发 Qdrant Edge Rust Release 工作流即可无需手动操作 crates.io。适用边界Edge 面向进程内/设备端检索若需连接远程 Qdrant 实例请使用qdrant-client系列包而非 Edge 包。对于想快速验证的读者建议按 环境准备安装just、Rust 工具链、uv、maturin→just check全量验证→ 阅读 demo.rs / demo.py 及各自 examples 目录的顺序上手即可在数分钟内跑通 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Qdrant Edge 包构建与发布实战指南：Rust/Python 嵌入式向量检索引擎的配方、工作区与发布流程
Qdrant Edge 包构建与发布实战指南Rust/Python 嵌入式向量检索引擎的配方、工作区与发布流程【免费下载链接】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/qdrantQdrant Edge 是 Qdrant 面向嵌入式设备、自动驾驶系统与移动 Agent 场景提供的轻量级进程内向量检索引擎它以库的形式嵌入宿主程序运行不依赖后台服务内存占用极小并可与 Qdrant Cloud 进行可选的数据同步。本文基于 lib/edge/README.md 与 lib/edge/Justfile系统讲解 Qdrant Edge 仓库中 Rust 包与 Python 包的组织方式、完整构建/检查/示例运行流程以及将 Rust 包发布到 crates.io 的操作步骤。读完本文你将能够独立在本地跑通qdrant-edgeRust与qdrant-edge-pyPython两套包的校验与示例程序理解代码合并生成、独立工作区等发布机制并能按官方流程完成版本发布。Qdrant Edge 在仓库中的定位lib/edge目录是 Qdrant 主仓库中专门承载 Edge 相关交付物的一级目录它并非一套传统的单一 Rust crate而是一组围绕如何把 Qdrant 的向量检索能力打包成可嵌入式库而组织的子工程集合。仓库中给出的一手定位描述见 python/README.md 与 publish/README.md是Qdrant Edge is a lightweight, in-process vector search engine designed for embedded devices, autonomous systems, and mobile agents. It enables on-device retrieval with minimal memory footprint, no background services, and optional synchronization with Qdrant Cloud.翻译过来即轻量级、进程内in-process向量检索引擎面向嵌入式设备、自主系统和移动端 Agent 场景实现设备端检索内存占用极小无需后台常驻服务并可选与 Qdrant Cloud 同步。需要特别注意的是如果你的场景是连接远程 Qdrant 实例应改用官方的qdrant-clientPython 侧对应 python/README.md 中说明的 PyPI 包qdrant-clientEdge 包解决的是把检索引擎直接跑在自己进程里的问题。整个lib/edge顶层由一个 Justfile 统一驱动——它为 Rust 与 Python 两套边缘包提供了check/ 构建 / 示例运行等一系列配方recipe。Justfile 是一个任务运行器定义文件使用前需要安装命令运行器just。目录结构速览在深入各配方之前先整体把握lib/edge下各子目录的职责对照lib/edge目录树路径职责lib/edge/Justfile面向 Edge 开发者的统一命令入口覆盖 Rust/Python 的检查、构建、示例运行lib/edge/publishRustqdrant-edge包所在的独立工作区与主工作区解耦专用于 crates.io 发布lib/edge/publish/amalgamate.py自动合并多个主仓库 crate 为单一qdrant-edge包的脚本产物输出到./publish/qdrant-edgegitignore 忽略lib/edge/publish/examplesRust 侧示例程序含demo.rs等若干 bin 目标lib/edge/pythonPythonqdrant-edge-py包属于主工作区的一部分通过 maturin PyO3 构建lib/edge/python/examplesPython 侧示例脚本含demo.py等lib/edge/ffi基于 uniffi 的 FFI 绑定层uniffi.toml、bindgen 等用于向其他语言暴露接口lib/edge/srcEdge 核心 Rust 库源码edge_shard、read_only、read_view、update_only、builders、requests、config等模块其中核心库入口 lib/edge/src/lib.rs 导出了EdgeShard、EdgeShardRead、ReadOnlyEdgeShard、UpdateOnlyEdgeShard、EdgeConfig、QueryRequestBuilder、SearchRequestBuilder等一系列类型与构建器它们是所有 Edge 示例与 API 绑定的公共基础。注意一个设计上的差异Rust 发布包是独立工作区而 Python 包是主工作区的一部分——这一点直接影响下面的构建命令在何处执行。统一命令入口Justfile 配方清单lib/edge/Justfile 将边缘包日常最常用的操作封装为若干配方每个配方都带注释说明用途方便人类阅读与 CI 调用。下面整理各配方及其确切语义均以lib/edge目录为执行起点配方说明关键行为just help打印可用配方just --unsorted --listjust prepare-data准备lib/edge/data下的数据文件先探测本机localhost:6333是否运行了 qdrant随后调用tools/prepare_facet_snapshot.shjust check全量检查并运行全部示例依序执行rs-check、rs-examples-build、rs-examples、py-build、py-examplesjust rs-checkRust 检查在publish目录中先跑./amalgamate.py再cargo nightly fmt -p examples -- --check最后用./cargo clippy -p examples --all-targets --no-deps -- -D warningsjust rs-examples-build构建 Rust 示例可选在publish目录./amalgamate.py后执行./cargo build -p examplesjust rs-examples运行 Rust 示例在publish目录中遍历 examples 的全部 bin 目标逐一cargo run任一失败会汇总并报错退出可用-e demo只跑指定示例just rs-examples-list列出 Rust 示例 bin 名通过cargo metadata配合jq解析出examples包中所有bin目标just py-build构建 Python 包在python目录unset VIRTUAL_ENV后uv venv --allow-existing安装requests再maturin develop --no-default-features --features abi3just py-examples运行 Python 示例在python目录遍历examples/*.py排除__init__.py用uv run --no-project执行可-e examples/demo.py指定单个just py-examples-list列出 Python 示例文件find examples -name *.py -not -name __init__.py几个值得留意的实现细节just rs-check刻意使用--no-depsJustfile 中注释说明了原因自动生成的qdrant-edge包里有大量警告检查范围应限定在示例代码本身。clippy 与 fmt 都只针对examples包说明 Rust 侧示例程序就是一套集成的冒烟测试能覆盖编译与运行两个层面。配方中大量使用./cargo而非cargo这是publish工作区自带的 cargo 包装脚本配合working-directory: publish的目录注解使用。Rust Qdrant Edge 包独立工作区与合并生成机制为什么是独立工作区按 lib/edge/README.md 的说明Rust Qdrant Edge workspace lives in the publish directory. Its a separate workspace, not tied to the main workspace.即publish是一个不挂在主工作区下的独立工作区。这样设计的目的很明确发布到 crates.io 的qdrant-edge需要一张干净、自洽的依赖图不能携带主工作区中的路径依赖、workspace 继承与构建期依赖。amalgamate.py把多个 crate 揉成一个包qdrant-edge包本体是自动生成的生成脚本是 lib/edge/publish/amalgamate.py产物落在./publish/qdrant-edge已被 gitignore不会进版本库。脚本注释对 amalgamation 的解释是The process of combining multiple crates into a single one. Used to prevent namespace pollution when publishing to crates.io.——把多个 crate 合并为单个 crate目的是避免 crates.io 发布时的命名空间污染。脚本头部amalgamate.py明确列出了参与合并的包列表PACKAGES_TO_INCLUDE [ bm25, common, edge, blobstore, posting_list, quantization, segment, shard, sparse, wal, ]也就是说一个功能完整的 Edge 运行时实际是segment向量分段、shard分片逻辑、quantization量化、bm25全文检索、sparse稀疏向量、wal预写日志、blobstore、posting_list、common等主仓库 crate 的有机组合最终在发布时统一收拢成qdrant-edge一个 crate。合并过程中还会剔除构建期依赖例如prost-build、tonic-build见脚本中的EXCLUDED_DEPENDENCIES。这一机制带来一个重要开发约束README 特别强调If you need to make changes in theqdrant-edgepackage, edit the original packages in this repo (/libin the repo root).不要直接修改生成的qdrant-edge包——需要改动时应回到主仓库/lib下的原始 crate即 lib/segment、lib/shard、lib/edge 等中修改再重新跑amalgamate.py重新生成。这正是单一事实来源思想的体现源码头在本仓库发布包只是构建产物。构建与运行 Rust 示例README 给出的最简路径是执行 Justfile 配方just rs-examplesrs-examples会在publish目录中先自动执行./amalgamate.py确保生成包最新再逐个构建并运行全部示例 bin。如果只想跑某个示例使用just rs-examples -e demo也可以完全绕开just手动按步骤执行# 先进入 Rust 发布工作区 cd lib/edge/publish # 1) 重新生成 qdrant-edge 包 ./amalgamate.py # 2) 编译检查 examples cargo check -p examples # 3) 运行某个示例 cargo run -p examples --bin demo # 其他 bin 依此类推 # cargo run -p examples --bin bm25-search # cargo run -p examples --bin add-named-vector # cargo run -p examples --bin fusion-query # …示例程序的完整清单以 lib/edge/publish/examples/src/bin 目录为准当前包含以下 bin 目标bin 目标演示主题demo端到端主流程写入点、query/search/scroll/count、过滤、facet、info、关闭并重开分片bm25-searchBM25 全文检索能力add-named-vector命名向量含稀疏向量的使用fusion-query多路召回融合fusion查询mmr-queryMMR 多样性重排查询load-existing加载已有数据/分片restore-snapshot快照恢复facet_testfacet 聚合测试如果只想做格式与 clippy 检查而不运行可以先执行just rs-checkrs-check等价于手动依次执行./amalgamate.py、cargo nightly fmt -p examples -- --check与./cargo clippy -p examples --all-targets --no-deps -- -D warnings。直接查看 Rust 示例效果以 demo.rs 为例能直观看到 Rust 侧 API 的调用形态。程序先是构造了多种点结构多稠密向量、命名稀疏向量演示转换// 多稠密向量点 PointStruct::new( 10u64, Vectors::try_from(vec![vec![1.0, 2.0, 3.0], vec![3.0, 4.0, 5.0]])?, json!({}), ), // 命名稀疏向量点 PointStruct::new( 11, qdrant_edge::Vectors::new_named([( sparse, Vector::new_sparse(vec![0, 2], vec![1.0, 3.0]).unwrap(), )]), json!({}), ),随后基于EdgeShard完成建分片、upsert、query、search、加过滤的 search、retrieve、scroll含翻页 offset、count、facet、info最后演示EdgeShard::load重新打开分片// 关闭后重新打开验证持久化 drop(shard); let reopened_shard EdgeShard::load(Path::new(TMP_DIR), None)?; println!( Edge shard reopened. Approx Points: {}, reopened_shard.info()?.points_count );示例中的load_new_shard()辅助函数见 publish/examples/src/lib.rs还会先清空并重建data/tmp目录并用EdgeConfig::builder().vector(DEFAULT_VECTOR_NAME, EdgeVectorParams::builder(4, Distance::Dot).build())声明一个 4 维、Dot 距离的向量配置——这是学习EdgeConfig/EdgeVectorParams用法的最佳模板。如何发布 Rust 包到 crates.iolib/edge/README.md 把 Rust 侧的发布流程收敛为两个步骤升级版本号修改 publish/amalgamate.py 中的VERSION常量当前值为0.7.2与 Python 侧 python/Cargo.toml 的version 0.7.2保持一致。因为版本同时写入合并产物改版本必须先改这里再重新合并生成。触发发布工作流运行仓库中的Qdrant Edge Rust Release工作流CI 定义在仓库的 GitHub Actions 配置中由 CI 完成amalgamate.py生成、编译校验并真正推送 crates.io 的完整动作。README 强调版本发布与代码修改解耦日常功能迭代只改/lib原始 crate 并跑just rs-check验证只有要对外发新版本时才动amalgamate.py的VERSION并触发发布工作流。这能最大程度避免手动改发布产物带来的漂移风险。Python Qdrant Edge 包maturin PyO3 构建包结构与构建方式Python 包位于 lib/edge/python与 Rust 发布包相反它是主工作区的一部分直接以路径依赖方式引用edge、segment、shard、sparse等主工作区 crate见 python/Cargo.toml库名为qdrant_edgecrate 类型为cdylib通过 PyO3pyo3 0.29暴露 Python 接口。构建后端采用 maturinpyproject.toml 中build-backend maturin。README 给出的运行路径同样是先走justjust py-build just py-examplespy-build配方的关键动作见 Justfile是unset VIRTUAL_ENV uv venv --allow-existing uv pip install requests maturin develop --no-default-features --features abi3这里启用了abi3feature即 python/Cargo.toml 中abi3 [pyo3/abi3-py310]使生成的扩展模块绑定到 Python 3.10 起的稳定 ABI从而一个 wheel 即可跨多个 Python 小版本使用。手动构建与运行若不想用justREADME 提供了完整的手动流程需自行确保 Python 环境就绪maturin可通过pip install maturin安装# 1) 创建并激活虚拟环境 cd lib/edge/python python -m venv .venv source .venv/bin/activate # 2) 安装构建工具 maturin pip install maturin # 3) 构建并安装到当前环境开发模式 cd lib/edge/python maturin develop --no-default-features # 4) 运行示例 python examples/demo.pymaturin develop会把编译出的扩展就地安装到当前虚拟环境省去每次改代码后重新打包的环节是最适合迭代开发的命令。类型体验pyi 与 py.typedPython 包在 wheel 构建时会附带类型存根 qdrant_edge.pyi 与 py.typed 标记文件见 pyproject.toml 中的include配置从而为 IDE 补全与类型检查提供完整支持。存根文件非常详尽——例如EdgeShard类给出了load(path, configNone)加载已存在分片若传入 config 会做兼容性检查并覆盖磁盘配置与create(path, config)在空路径新建分片两个静态方法以及flush、close、optimize、update、query、search、retrieve、scroll、count、facet等全套方法签名并定义了PointId、Vector、Filter、Query等类型别名。Python 示例与 Rust 示例一一对应。以 demo.py 为例核心流程与 Rust 版demo.rs完全平行用UpdateOperation.upsert_points(...)写入点、用QueryRequest(queryQuery.Nearest(...), limit10, ...)查询、用Filter(must[...])组合文本匹配与范围过滤、用shard.facet(FacetRequest(key..., limit10, ...))做聚合最后shard.close()后调用EdgeShard.load(TMP_DIR)重新打开分片并读取points_count。Python 侧完整示例清单位于 lib/edge/python/examples除demo.py、common.py外还包括add-named-vector.py、bm25-search.py、fusion-query.py、hybrid_search_dbsf.py、load-existing.py、mmr-query.py、optimize.py、repr.py、restore-snapshot.py、sparse-search.py等。其中 common.py 提供load_new_shard()清空data/tmp后用EdgeConfig(vectorsEdgeVectorParams(size4, distanceDistance.Dot))新建分片与fill_dummy_data()写入 10 条带 color/city/rating/tags 等负载的示例数据被多数示例复用是快速体验的起点。check 全量配方一次跑通全部质量门禁日常开发或 CI 中最常用的一条命令是just check它等价于依次执行rs-check→rs-examples-build→rs-examples→py-build→py-examples覆盖了 Rust 侧的格式化/静态检查/示例运行与 Python 侧的构建/示例运行。整个检查链路对just、cargo nightly、uv、maturin、python等工具链有依赖建议在干净环境中一次补齐后再执行。若只想检查其中一侧可按需组合上文列出的子配方例如只做 Python 侧just py-build just py-examples只做 Rust 侧just rs-check just rs-examples。数据准备与周边工具除构建与示例外lib/edge还包含一组服务于开发调试的辅助脚本just prepare-data会在本机localhost:6333未运行 qdrant 时给出提示并通过 tools/prepare_facet_snapshot.sh 准备 facet 快照等测试数据供示例程序消费。tools/shard_query与tools/shard_update分别提供读取主仓库产生的 shard 数据与向 shard 下发更新的独立小工具各自带 SKILL.md 说明便于直接对真实分片目录做查询/更新实验。tools/s3_proxy、tools/download_partial.py用于在快照场景中模拟 S3 代理、按范围下载文件等网络相关调试。lib/edge/ffi存放 uniffi 风格的 FFI 绑定ffi/Cargo.toml、uniffi.toml用于把 Edge 能力桥接到非 Rust 宿主语言。这些工具与 Justfile 一起构成了围绕 Edge 交付物相对完整的开发闭环改源码 →just rs-check静态把关 →just rs-examples/py-examples跑示例 →prepare-data准备数据 → 发布时改VERSION并触发发布工作流。小结与注意事项Qdrant Edge 的工程组织呈现出三个清晰的层次核心库层lib/edge/srcEdgeShard 及读写/只读/仅更新等视图与全部请求构建器是 Rust 与 Python 两侧共享的能力底座发布封装层Rust 侧经 amalgamate.py 将segment、shard、quantization、bm25、sparse、wal等主仓库 crate 合并为独立的qdrant-edgecrate 发布Python 侧以主工作区内 crate 为依赖经 maturin PyO3 打包为qdrant-edge-py开发编排层一份 Justfile 统管两侧的检查、构建与示例运行并配套 publish/examples 与 python/examples 两套互相平行的示例作为冒烟验证。实践中的关键提醒改动生成包没有意义qdrant-edge由脚本生成且被 gitignore任何修改都应落到 lib 下对应的原始 crate否则会在下次amalgamate.py运行时丢失。Rust 与 Python 工作区归属不同Rust 发布工作区在lib/edge/publish独立Python 包在lib/edge/python从属主工作区执行命令时务必进入正确的目录或直接使用just配方配方自带working-directory注解。版本号同步Rust 侧版本以 amalgamate.py 中的VERSION为准发布前更新并触发 Qdrant Edge Rust Release 工作流即可无需手动操作 crates.io。适用边界Edge 面向进程内/设备端检索若需连接远程 Qdrant 实例请使用qdrant-client系列包而非 Edge 包。对于想快速验证的读者建议按 环境准备安装just、Rust 工具链、uv、maturin→just check全量验证→ 阅读 demo.rs / demo.py 及各自 examples 目录的顺序上手即可在数分钟内跑通 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考