qdrant-edge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building on Qdrant Edge

基于Qdrant Edge开发

Edge is the Qdrant engine embedded in your process (Python or Rust), not a thin local vector store to wrap. The failure mode is rebuilding what the shard already ships: keyword scoring, snapshot apply, faceting, counting. Before writing any of that, check the shard API. Two things Edge does NOT give you are a one-call cloud sync and query-time fusion, so knowing which is which keeps you from both reinventing built-ins and expecting capabilities Edge lacks. Edge is single-node and shares the server's data format.

Edge is in beta: pin your version, the API drifts between releases Qdrant Edge.

Edge是嵌入到您进程（Python或Rust）中的Qdrant引擎，而非用于封装的轻量本地向量存储。常见误区是重复开发分片已内置的功能：关键词评分、快照应用、分面搜索、计数等。在编写任何代码前，请先查看分片API。Edge不提供两项功能：一键云同步和查询时融合，了解这一点既能避免重复造轮子，也不会对Edge抱有超出其能力的期望。Edge为单节点架构，与服务器的数据格式兼容。

Edge目前处于测试版：请固定您使用的版本，不同版本间API可能存在差异 Qdrant Edge。

Syncing a Shard with a Qdrant Server

将分片与Qdrant服务器同步

Use when: seeding a shard from a server, keeping it fresh, backing it up, or aggregating many devices into one collection.

There is no built-in

.sync()

. Sync is a pattern you assemble from shard helpers plus your own transport, so do not go looking for one call.

Follow the documented dual-shard pattern: a
```
mutable
```
shard for local writes plus an
```
immutable
```
shard restored from a server snapshot, query both, refresh on a schedule Edge synchronization guide.
You write the snapshot download (plain HTTP to the shard snapshot endpoint), then apply it with
```
unpack_snapshot
```
and
```
update_from_snapshot
```
. Do not untar or merge segments by hand Synchronization patterns.
Refresh incrementally with a partial snapshot built from
```
snapshot_manifest
```
, not a full snapshot every cycle Synchronization patterns.
Push is your own dual-write: on each local upsert, enqueue the point and let a background worker upsert it to the server, buffering while offline Synchronization patterns.

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

Edge没有内置的

.sync()

方法。同步是一种需要您结合分片辅助工具与自定义传输逻辑来实现的模式，因此不要寻找一键同步的方法。

遵循文档中记录的双分片模式：一个用于本地写入的
```
mutable
```
分片，加上一个从服务器快照恢复的
```
immutable
```
分片，同时查询这两个分片，并按计划刷新数据 Edge同步指南。
您需要自行实现快照下载（通过普通HTTP请求访问分片快照端点），然后使用
```
unpack_snapshot
```
和
```
update_from_snapshot
```
来应用快照。请勿手动解压或合并分片段同步模式。
使用
```
snapshot_manifest
```
生成的部分快照进行增量刷新，而非每次周期都使用完整快照同步模式。
推送功能需要您自行实现双写逻辑：每次本地插入数据时，将该点加入队列，由后台工作线程将其插入到服务器，离线时可进行缓冲同步模式。

Keyword and Hybrid Search on Device

设备端关键词与混合搜索

Use when: you need exact-term or BM25 matching, alone or alongside vectors.

BM25 is built into Edge (
```
Bm25
```
,
```
Bm25Config
```
,
```
embed_document
```
,
```
embed_query
```
) with the IDF
```
Modifier
```
on
```
EdgeSparseVectorParams
```
, and is wire-compatible with server BM25: a shard seeded from a server snapshot answers local BM25 queries without re-indexing. Do not ship a second BM25 library Edge BM25
Dense embeddings are NOT in Edge: generate them on device with the separate
```
fastembed
```
package FastEmbed embeddings
Edge queries one vector field per request (
```
using
```
) and does not fuse dense and sparse at query time. Run each leg separately and combine the rankings in application code Edge quickstart

适用场景：您需要精确术语匹配或BM25匹配，无论是单独使用还是与向量搜索结合。

Edge内置了BM25功能（
```
Bm25
```
、
```
Bm25Config
```
、
```
embed_document
```
、
```
embed_query
```
），在
```
EdgeSparseVectorParams
```
上支持IDF
```
Modifier
```
，且与服务器端BM25兼容：从服务器快照初始化的分片无需重新索引即可响应本地BM25查询。请勿引入第二个BM25库 Edge BM25
Edge不包含密集嵌入向量生成功能：需使用单独的
```
fastembed
```
包在设备端生成 FastEmbed嵌入向量
Edge每次请求仅能查询一个向量字段（通过
```
using
```
参数指定），且不支持查询时融合密集向量与稀疏向量。需分别执行两种查询，然后在应用代码中合并排名结果 Edge快速入门

Operating the Shard

分片运维

Use when: writes have accumulated, search looks stale after inserts, or a backup is larger than the data.

Edge has NO background optimizer. Call
```
optimize
```
after bulk writes: it builds indexes (including the sparse index) and reclaims deleted points. Skip it and that data stays unindexed Edge quickstart
Faceting, counting, and enumeration are built in (
```
facet
```
,
```
count
```
,
```
scroll
```
); index the fields you filter or facet with
```
create_field_index
```
rather than aggregating in application code Edge quickstart
The write-ahead log is pre-allocated to 32 MB and inflates apparent disk and backup size. Shrink it with
```
wal_options
```
(Rust), and do not treat raw file size as real usage Edge quickstart

适用场景：写入数据累积、插入后搜索结果显示过时，或是备份文件大于实际数据量。

Edge没有后台优化器。批量写入后请调用
```
optimize
```
方法：该方法会构建索引（包括稀疏索引）并回收已删除的数据点。若跳过此步骤，数据将不会被索引 Edge快速入门
分面搜索、计数和枚举功能均已内置（
```
facet
```
、
```
count
```
、
```
scroll
```
）；请使用
```
create_field_index
```
为需要过滤或分面的字段创建索引，而非在应用代码中进行聚合 Edge快速入门
预写日志（write-ahead log）预分配了32MB空间，会增大磁盘占用和备份文件的表观大小。可通过
```
wal_options
```
（Rust）缩小其大小，请勿将原始文件大小视为实际使用量 Edge快速入门

What NOT to Do

请勿执行以下操作

Expect a bidirectional
```
.sync()
```
or a built-in push path: Edge gives you snapshot apply, you own the transport and the dual-write
Untar or merge snapshot segments by hand instead of using
```
unpack_snapshot
```
and
```
update_from_snapshot
```
Ship a custom or third-party BM25 when Edge has one built in
Use
```
embed_document
```
for queries or
```
embed_query
```
for documents: the weighting differs and results go wrong
Assume Edge fuses dense and sparse or consumes Prefetch: combine the rankings in application code
Assume a background optimizer like the server's: nothing is indexed or compacted until you call
```
optimize
```
Reach for Edge when you need distributed or multi-node search: it is single-node Qdrant Edge
Claim support for a language beyond Python and Rust, or an OS or accelerator the Edge docs do not state

期望Edge提供双向
```
.sync()
```
方法或内置推送路径：Edge仅提供快照应用功能，传输逻辑和双写逻辑需由您自行实现
手动解压或合并快照分片段，而非使用
```
unpack_snapshot
```
和
```
update_from_snapshot
```
在Edge已内置BM25功能的情况下，使用自定义或第三方BM25库
将
```
embed_document
```
用于查询或
```
embed_query
```
用于文档：两者的权重计算不同，会导致结果错误
假设Edge支持密集向量与稀疏向量融合或Prefetch功能：需在应用代码中合并排名结果
假设Edge具备与服务器类似的后台优化器：在调用
```
optimize
```
前，数据不会被索引或压缩
在需要分布式或多节点搜索时使用Edge：它是单节点架构 Qdrant Edge
声称支持Python和Rust之外的语言，或是Edge文档未提及的操作系统或加速器