企业官网建设流程全解析

如何在 Python 中首次运行 Qdrant Edge？创建 EdgeShard、写入点并查询的完整流程

【免费下载链接】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 Server，Qdrant Edge 就是对应的形态：它运行在应用进程内部，数据本地存储和查询，没有后台服务。下面的流程基于 qdrant 仓库lib/edge目录下的真实文档和示例代码，完成一次完整的首次运行：搭建 Python 环境并构建qdrant-edge-py包，创建EdgeShard，通过update写入点，再用query/search检索并验证结果。

注意区分：如果要连接远程 Qdrant 实例，应使用qdrant-client包而不是 Qdrant Edge。本流程只针对嵌入式/进程内使用场景。

准备条件：环境与构建 qdrant-edge-py

Qdrant Edge 的 Python 包位于 lib/edge/python 目录，它属于主 workspace，需要用 maturin 从 Rust 源码构建（lib/edge/README.md）。

手动构建的最小路径（来自 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

构建成功后，qdrant_edge包就装进了当前 venv，后续import qdrant_edge即可使用。

可选分支：使用 Justfile。仓库在 lib/edge/Justfile 中提供了py-build与py-examples两个 recipe（需要先安装just命令行工具）：

just py-build just py-examples

py-build实际执行的是uv venv --allow-existing、uv pip install requests和maturin develop --no-default-features --features abi3，即基于 uv 的环境创建方式；py-examples会遍历examples/目录下所有*.py示例逐个运行，如果只想跑一个示例，可以用just py-examples -e examples/demo.py指定。

创建 EdgeShard 并写入点

创建分片的核心 API 是EdgeShard.create(存储路径, EdgeConfig)。examples/common.py 中的load_new_shard()是最直接的参考：

config = EdgeConfig( vectors=EdgeVectorParams(size=4, distance=Distance.Dot), ) shard = EdgeShard.create(TMP_DIR, config)

其中两个要点：

• EdgeVectorParams的size决定向量维度，distance指定距离函数（示例用Distance.Dot；根目录 README.md 的 Edge 示例中则使用了Distance.Cosine，两者按你的向量数据选择）。
• 第一个参数是分片数据的存储目录，写入的数据会持久化到该目录，之后可以用EdgeShard.load()重新打开。

示例脚本使用的目录是lib/edge/data/tmp（由 common.py 中Path(__file__).parent.parent.parent / "data"推导）。注意load_new_shard()在创建前会先删除并重建该目录（shutil.rmtree），即会清掉该目录下的旧数据——这是示例为了每次拿到干净分片而做的处理，你自己的项目里应使用独立的存储路径。

创建后用shard.update()写入点，更新操作通过UpdateOperation.upsert_points([...])提交。demo.py 中写入的示例点同时演示了三种 ID 形式：整数 ID、UUID 字符串、uuid.uuid4()对象，payload 可以放嵌套的 JSON 结构：

shard.update( UpdateOperation.upsert_points( [ Point(1, [6.0, 9.0, 4.0, 2.0], {"hello": "world", "price": 42}), Point("e9408f2b-b917-4af1-ab75-d97ac6b2c047", [6.0, 9.0, 3.0, -2.0], {"hello": "world", "price": 199.99}), Point(uuid.uuid4(), [1.0, 6.0, 4.0, 2.0], {"hello": "world", "price": 999.99}), ] ) )

这里 payload 做了精简，字段形式与 demo.py 保持一致（字符串、数值、嵌套对象、数组、None均支持）。

查询：query、search 与过滤

写入之后，两种查询入口：

shard.query()使用QueryRequest：

result = shard.query( QueryRequest( query=Query.Nearest([6.0, 9.0, 4.0, 2.0]), limit=10, with_vector=True, with_payload=True, ) )

shard.search()使用SearchRequest，可以在同一次请求里附加Filter条件（来自 demo.py 的 "Search + Filter" 段）：

search_filter = Filter( must=[ FieldCondition(key="hello", match=MatchTextAny(text_any="world")), FieldCondition(key="price", range=RangeFloat(gte=500.0)), ] ) points = shard.search( SearchRequest( query=Query.Nearest([1.0, 1.0, 1.0, 1.0]), filter=search_filter, limit=10, with_vector=True, with_payload=True, ) )

返回的是点序列，可直接遍历打印，确认命中的 ID、向量和 payload 是否符合预期。

除检索外，shard.retrieve(point_ids=[1], with_vector=True, with_payload=True)可以按 ID 取点；shard.scroll(ScrollRequest(limit=2))返回(points, next_offset)二元组，next_offset不为None时用它继续翻页，直到为None为止。

验证结果：count、info 与重新打开

首次运行是否成功，可以用示例中的三个检查点确认：

1. 点数核对。shard.count(CountRequest(exact=True))返回精确点数，demo.py 会将其打印为Total points count: {count}形式（文档示例，数值取决于你实际写入的量）。
2. 分片信息。shard.info()返回分片元信息，demo.py 直接print(info)输出。
3. 持久化验证。EdgeShard的数据落在磁盘上，关闭后可以用路径重新加载：

shard.close() reopened_shard = EdgeShard.load(TMP_DIR) print(f"Edge shard reopened. Approx Points: {reopened_shard.info().points_count}")

重新打开后points_count与写入量一致，说明 create → upsert → query 的链路和数据落盘都正常。

一次性跑通：运行官方 demo

如果不想自己拼代码，可以直接运行仓库自带的完整示例，它按顺序覆盖 Point 转换、加载分片、upsert、query、search、带过滤 search、retrieve、scroll、count、facet、info 以及 close/reopen 全流程：

# 在 lib/edge/python 目录下（已激活构建时的 venv） python examples/demo.py

运行前提：demo.py顶部from common import *依赖同目录的 common.py，所以要保持在examples/相对关系内运行（即从lib/edge/python以python examples/demo.py方式启动）。再次提醒该脚本会先清空lib/edge/data/tmp目录，因此不要把该目录当作品重要数据存放位置。

脚本正常结束时，最后一段会打印类似Edge shard reopened. Approx Points: N的重开确认，N 与你写入的点数量对应。

下一步

• 分片关闭后用EdgeShard.load(路径)恢复，对应 lib/edge/python/examples/load-existing.py。
• 快照恢复有独立示例 lib/edge/python/examples/restore-snapshot.py。
• 稀疏向量、BM25 检索、命名向量等更多用法，可参考 lib/edge/python/examples 下的其余示例脚本（sparse-search.py、bm25-search.py、add-named-vector.py等）。
• 更完整的 Python API 签名见同目录的 qdrant_edge.pyi 类型存根（构建的 wheel 也会带上，供 IDE 使用）。

【免费下载链接】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