qdrant-edge

基于 Qdrant Edge 构建

Edge 是嵌入到进程中的 Qdrant 引擎（Python 或 Rust），而不是一个可封装的轻量本地向量存储。常见的失败原因是重新实现分片已有的功能：关键词评分、应用快照、分面和计数。在编写这些功能之前，请先检查分片 API。Edge 确实不提供一键云同步，因此了解内置功能可以避免重复实现已有功能，也能避免期待 Edge 不具备的能力。Edge 是单节点的，并与服务器共享数据格式。

• Edge 处于 Beta 阶段：固定版本，因为 API 会随版本变化 Qdrant Edge。

将分片与 Qdrant 服务器同步

适用场景：从服务器初始化分片、保持分片最新、备份分片，或将多台设备的数据汇总到一个集合中。

没有内置的 .sync()。同步是通过分片辅助方法和自定义传输机制组合实现的模式，因此不要寻找一个调用就能完成同步的方法。

• 遵循文档中的双分片模式：使用 mutable 分片进行本地写入，使用从服务器快照恢复的 immutable 分片；同时查询两者，并按计划刷新 Edge 同步指南。
• 你需要自行实现快照下载（通过普通 HTTP 访问分片快照端点），然后使用 unpack_snapshot 和 update_from_snapshot 应用快照。不要手动解压 tar 文件或合并分段 同步模式。
• 使用 snapshot_manifest 构建部分快照进行增量刷新，而不是每个周期都使用完整快照 同步模式。
• 推送需要你自行实现双写：每次本地 upsert 时，将点加入队列，再由后台工作线程将其 upsert 到服务器；离线时进行缓冲 同步模式。

设备端的关键词与混合搜索

适用场景：你需要精确词项匹配或 BM25 匹配，可以单独使用，也可以与向量搭配使用。

• BM25 已内置于 Edge（Bm25、Bm25Config、embed_document、embed_query），通过 EdgeSparseVectorParams 上的 IDF Modifier 配置，并且与服务器的稀疏向量 BM25 模型在线格式上兼容（Edge BM25 文档只介绍稀疏向量变体）：从服务器快照初始化的分片无需重新索引即可响应本地 BM25 查询。不要再引入第二个 BM25 库 Edge BM25
• Edge 不提供稠密嵌入：请使用单独的 fastembed 包在设备端生成 FastEmbed 嵌入
• 对于混合搜索，将稠密和稀疏检索分支作为 prefetches 执行，并在一次 query 调用中使用 Fusion 查询融合结果，而不是在应用代码中合并排名 读取数据

运维 Shard

适用场景：写入不断累积、插入后搜索结果看起来过时，或备份大小超过数据量。

• Edge 没有后台优化器。批量写入后调用 optimize：它会构建索引（包括稀疏索引）并回收已删除的点。不调用它，这些数据就会一直处于未索引状态 Edge quickstart
• 分面、计数和枚举功能均为内置功能（facet、count、scroll）；对于需要筛选或分面的字段，使用 create_field_index 创建索引，而不是在应用代码中进行聚合 Edge quickstart
• 预写日志预分配了 32 MB，因此磁盘占用和备份大小看起来会膨胀。使用 wal_options（Rust）缩小它，不要将原始文件大小视为实际占用 Edge quickstart

不要做的事

• 不要期待双向 .sync() 或内置推送路径：Edge 提供快照应用功能，传输和双写由你负责
• 不要手动解包或合并快照分段，应使用 unpack_snapshot 和 update_from_snapshot
• Edge 已内置 BM25，不要使用自定义或第三方 BM25
• 不要对查询使用 embed_document，也不要对文档使用 embed_query：两者的权重不同，会导致结果出错
• 不要在应用代码中合并稠密和稀疏排序：Edge query 接受 prefetches，并通过 Fusion 查询融合结果
• 不要假设它有类似服务端的后台优化器：在调用 optimize 之前，不会建立索引或进行压缩
• 需要分布式或多节点搜索时，不要选择 Edge：它是单节点的 Qdrant Edge
• 不要声称支持 Python 和 Rust 之外的语言，也不要声称支持 Edge 文档未说明的操作系统或加速器