Qdrant 怎么搭建本地开发环境？Rust 工具链与 protoc 依赖安装及首次编译运行

Qdrant 怎么搭建本地开发环境？Rust 工具链与 protoc 依赖安装及首次编译运行

【免费下载链接】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 源码、验证自己的改动，或想在没有 Docker 的环境下运行一个自己编译的向量数据库实例，就要先搭好本地开发环境。Qdrant 的官方开发文档 docs/DEVELOPMENT.md 给出的本地开发路径适用于 Linux/Debian/MacOS：安装 Rust 工具链与protoc（Protocol Buffers 编译器）后，用cargo build --release从源码编译出qdrant二进制并直接运行，服务会监听在localhost:6333。本文按文档中的顺序走完这条路径。

安装 Rust 工具链

开发环境的第一项要求是 Rust。按 Rust 官方安装指引（rustup 方式）安装 Rust 后，再补装rustfmt组件，项目代码格式检查依赖它：

rustup component add rustfmt

安装系统依赖

在 Linux/Debian 环境下，文档要求用apt-get安装一组构建依赖，包括curl、unzip、gcc-multilib、clang、cmake、jq，以及 aarch64 交叉工具链包：

sudo apt-get update -y sudo apt-get upgrade -y sudo apt-get install -y curl unzip gcc-multilib \ clang cmake jq \ g++-9-aarch64-linux-gnu \ gcc-9-aarch64-linux-gnu

这条命令来自 docs/DEVELOPMENT.md 的原文，文档没有为 x86_64 与 aarch64 分别给出不同的包列表，照原文执行即可。macOS 下文档没有给出等价的包管理命令，对应的替代方式是下文介绍 Nix 环境。

安装 protoc

Qdrant 的 gRPC 协议定义在 lib/api/src/grpc/proto 下，cargo build时通过 tonic/prost 生成 Rust 类型，而这一步依赖系统里存在protoc。文档要求安装 22.2 版本：

PROTOC_VERSION=22.2 PKG_NAME=$(uname -s | awk '{print ($1 == "Darwin") ? "osx-universal_binary" : (($1 == "Linux") ? "linux-x86_64" : "")}') # 下载 protoc 发布包 curl -LO https://github.com/protocolbuffers/protobuf/releases/download/v$PROTOC_VERSION/protoc-$PROTOC_VERSION-$PKG_NAME.zip unzip protoc-$PROTOC_VERSION-$PKG_NAME.zip -d $HOME/.local export PATH="$PATH:$HOME/.local/bin" # 删除下载的压缩包（可选） rm protoc-$PROTOC_VERSION-$PKG_NAME.zip # 验证安装 protoc --version

两个需要注意的点：

• export PATH只对当前 shell 生效。如果关闭终端后重新打开，protoc会找不到，需要再次执行这一行或把它写入你的 shell 配置文件。
• 文档给出的验证方式就是protoc --version，能打印出版本号即说明protoc已可用，后续cargo build会用到它。

首次编译

依赖就绪后，在仓库根目录执行：

cargo build --release --bin qdrant

这是 release 构建，首次编译会拉取并编译整个 workspace 的依赖，耗时较长。构建成功后二进制位于./target/release/qdrant。

运行与验证

在仓库根目录启动编译出的服务：

./target/release/qdrant

启动后终端会打印一段欢迎横幅（见 src/greeting.rs），其中包含当前版本号、git 构建提交号，以及一行Access web UI at http://localhost:6333/dashboard，说明 HTTP 服务已在本机 6333 端口就绪。

服务起来之后，有两种由仓库文档直接给出的验证方式：

1. 跑一遍基础 API 测试。仓库自带 tests/basic_api_test.sh，脚本头部注释写明它检查 Qdrant 是否按预期响应 README 中列出的全部 API，QDRANT_HOST默认就是localhost:6333：

   ./tests/basic_api_test.sh

2. 手动发一个创建集合的请求。下面的 payload 取自上述脚本中的真实请求（文档示例）：

   curl -X PUT "http://localhost:6333/collections/test_collection" \ -H 'Content-Type: application/json' \ --fail -s \ --data-raw '{ "vectors": { "size": 4, "distance": "Dot" }, "optimizers_config": { "default_segment_number": 2 }, "replication_factor": 2 }' | jq

   带--fail的 curl 在请求失败时会非零退出，返回的 JSON 中result.status为created/exists说明集合 API 工作正常。验证完成后可用DELETE /collections/test_collection清理。

可选替代路径：Nix 环境

如果你使用 Nix 包管理器（Linux、macOS 或 WWSL2 均可），可以跳过上面手动装依赖的步骤：在仓库根目录运行nix-shell，即可进入一个装好 Rust 构建依赖、Python 测试和./tools脚本所需工具的 shell。仓库的 shell.nix 里列明了这套环境包含的组件（cmake、protobuf、ccache/sccache 缓存、uv 等）。文档说明该 shell 同时覆盖 Rust 代码构建与 Python 测试两类依赖。

编译通过后接着做什么

本地环境跑通之后，docs/DEVELOPMENT.md 还给出了两条与开发直接相关的后续操作：

• 跑集成测试：安装 uv 后，用uv --project tests run pytest tests/openapi或uv --project tests run pytest tests/consensus_tests分别跑 OpenAPI 与共识测试。
• 同步 Web UI：Web UI 在独立仓库中，可用./tools/sync-web-ui.sh把它同步到本仓库的static目录，启动后就能通过http://localhost:6333/dashboard访问界面。

另外提醒：如果要给上游提 PR，docs/CONTRIBUTING.md 要求 PR 必须指向dev分支（master只用于发版），并在提交前执行cargo +nightly fmt --all和cargo clippy --workspace --all-features保证格式与 lint 通过。

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