Go 客户端通过 gRPC 连接 Qdrant 向量搜索引擎，实现向量集合创建、写入与相似度检索

方案简介

本方案基于官方 Go 客户端库 qdrant/go-client，在 Go 应用中接入 Qdrant 向量搜索引擎。客户端内部使用低层 gRPC 客户端与 Qdrant 通信，并提供创建集合、写入向量、按相似度查询、条件过滤检索等高层工具函数。适合需要在 Go 服务中构建向量搜索能力（如相似内容检索、语义搜索）的开发者。项目同时提供 API Key + TLS 的安全连接配置，可对接 Qdrant Cloud。

亮点与能力

• 创建向量集合，可配置向量维度与距离度量（如 Cosine）
• 批量 Upsert 写入向量点及 payload 元数据
• 相似向量查询（Query）
• 带过滤条件的相似度检索（Filter/Must/Match）
• 查询时返回指定 payload
• 通过 Config 配置 gRPC 连接参数（连接池、KeepAlive、TLS、自定义 DialOption）
• 支持 API Key 认证与 TLS 加密连接

组成与分工

• Go：开发语言，通过 go get 引入客户端库
• qdrant/go-client：官方 Go 客户端库，提供高层工具函数封装
• gRPC：客户端内部低层通信协议，负责与 Qdrant 服务端交互
• Qdrant：向量搜索引擎，存储向量并提供检索服务，默认监听 6334 端口
• TLS：为连接提供加密与最低版本 1.3 的安全配置

前置要求

• Go 开发环境
• 可访问的 Qdrant 服务实例（本地或云端）
• 安装客户端库：

bash
go get -u github.com/qdrant/go-client

实施步骤

1. 安装客户端库

bash
go get -u github.com/qdrant/go-client

2. 创建客户端

go
import "github.com/qdrant/go-client/qdrant"

client, err := qdrant.NewClient(&qdrant.Config{
Host: "localhost",
Port: 6334,

这将创建连接到 的客户端。如需安全连接，可配置 API Key 与 TLS：

go
client, err := qdrant.NewClient(&qdrant.Config{
Host: "xyz-example.eu-central.aws.cloud.qdrant.io",
Port: 6334,
APIKey: "",
UseTLS: true,

3. 创建集合

go
client.CreateCollection(context.Background(), &qdrant.CreateCollection{
CollectionName: "{collection_name}",
VectorsConfig: qdrant.NewVectorsConfig(&qdrant.VectorParams{
Size: 4,
Distance: qdrant.Distance_Cosine,
}),

4. 写入向量

使用 Upsert 写入带 payload 的向量点，例如：

go
operationInfo, err := client.Upsert(context.Background(), &qdrant.UpsertPoints{
CollectionName: "{collection_name}",
Points: []*qdrant.PointStruct{
{
Id: qdrant.NewIDNum(1),
Vectors: qdrant.NewVectors(0.05, 0.61, 0.76, 0.74),
Payload: qdrant.NewValueMap(map[string]any{"city": "London"}),
},

5. 查询相似向量

go
searchResult, err := client.Query(context.Background(), &qdrant.QueryPoints{
CollectionName: "{collection_name}",
Query: qdrant.NewQuery(0.2, 0.1, 0.9, 0.7),

6. 带过滤条件查询

go
searchResult, err := client.Query(context.Background(), &qdrant.QueryPoints{
CollectionName: "{collection_name}",
Query: qdrant.NewQuery(0.2, 0.1, 0.9, 0.7),
Filter: &qdrant.Filter{
Must: []*qdrant.Condition{
qdrant.NewMatch("city", "London"),

并通过 WithPayload: qdrant.NewWithPayload(true) 返回 payload。

使用与配置要点

• 连接配置集中在 qdrant.Config，可选参数包括：

go
// PoolSize: 3,
// KeepAliveTime: 10,
// KeepAliveTimeout: 2,
// TLSConfig: &tls.Config{...},
// GrpcOptions: []grpc.DialOption{},

• UseTLS: true 使用默认配置，最低 TLS 版本为 1.3
• 更多用法参见 Qdrant 官方文档与 API Reference

注意事项与常见问题

• 客户端默认连接 localhost:6334
• 对接 Qdrant Cloud 时需同时设置 APIKey 并开启 UseTLS
• 依赖清单未提供时，gRPC 相关依赖随客户端库一并引入

优缺点

• ✓ 提供便捷的高层工具函数
• ✓ 支持 TLS 与 API Key 认证
• ✕ README 示例较简略

出处

本方案挖掘自开源项目 qdrant/go-client，方案内容与实施命令均来自其 README 原文。