「本文目标」：带你完整走一遍在 .NET 中集成 Qdrant 向量数据库的全流程，包括环境搭建、集合管理、使用 OpenAI Embeddings 生成向量、写入与语义检索，最终实现一个可用的 RAG（检索增强生成）知识库问答系统。
❞
一、什么是向量数据库？为什么选 Qdrant？
在 LLM 应用（如 RAG、语义搜索、推荐系统）中，核心问题是：「如何在海量文本中快速找到语义上最相近的内容？」
传统数据库擅长精确匹配（WHERE title = '...'），但对"语义相似"毫无概念。向量数据库的出现正是为了解决这个问题：它将文本转换为高维向量（Embedding），并通过近似最近邻算法（ANN）在毫秒级别完成相似度检索。
「Qdrant」 是目前 .NET 生态中最佳的向量数据库选择之一，理由如下：
「用 Rust 编写」，性能极高，内存效率出色 「提供官方 .NET SDK」（ Qdrant.Client），基于 gRPC，类型安全「支持丰富的过滤条件」，可在向量搜索的同时附加标量过滤（如按日期、分类筛选） 「支持 Payload」，每个向量可携带任意 JSON 元数据 「Docker 一行启动」，本地开发零门槛 「云服务可用」（Qdrant Cloud），生产环境无需自维护
二、环境准备
2.1 启动 Qdrant
最简单的方式是用 Docker：
「6333」：REST API 端口（可通过浏览器访问 Dashboard： http://localhost:6333/dashboard）「6334」：gRPC 端口（.NET SDK 默认使用此端口） 挂载 qdrant_storage目录确保数据持久化
启动后访问 http://localhost:6333/dashboard，如果看到 Qdrant 的 Web UI，说明服务运行正常。
2.2 创建 .NET 项目并安装依赖
安装完成后，QdrantDemo.csproj 中应包含：
2.3 配置 API Key
在 appsettings.json 中添加：
❝⚠️ 生产环境请使用
❞dotnet user-secrets或环境变量存储 API Key，切勿提交到代码仓库。
三、Qdrant 核心概念速览
在写代码之前，先了解几个关键术语，有助于理解后续 API 的设计逻辑：
| 「Collection（集合）」 | |
| 「Point（点）」 | |
| 「Vector（向量）」 | |
| 「Payload（载荷）」 | { "source": "document.pdf", "page": 3 } |
| 「Distance（距离函数）」 |
四、连接 Qdrant 并管理集合
4.1 创建客户端
QdrantClient 是线程安全的，建议在 DI 容器中注册为单例：
4.2 创建集合
集合在创建时必须指定向量维度和距离函数。text-embedding-3-small 模型输出 「1536 维」向量，使用余弦相似度：
4.3 查看集合信息
五、使用 OpenAI 生成 Embeddings
Embedding 是将文本转换为向量的关键步骤。OpenAI 的 text-embedding-3-small 模型是目前性价比最高的选择：每百万 Token 仅需 $0.02，中文支持良好。
5.1 创建 Embedding 服务
注册到 DI 容器：
六、写入文档向量
6.1 定义文档模型
6.2 批量写入向量
UpsertAsync 支持"插入或更新"语义，相同 ID 的 Point 会被覆盖，非常适合文档重新索引的场景。
七、语义搜索
7.1 基础向量搜索
7.2 带过滤条件的混合搜索
Qdrant 的强大之处在于可以在向量搜索的同时施加精确过滤，这是纯向量数据库做不到的：
Qdrant 支持复杂的组合过滤，例如同时匹配多个条件：
八、构建完整的 RAG 问答系统
现在将所有组件组合起来，实现一个"基于知识库的问答"功能：用户提问 → 语义搜索相关文档 → 将文档作为上下文喂给 GPT → 生成答案。
8.1 注册服务并暴露 API
九、文档分块策略
实际项目中，文档通常很长，需要分块后再写入。以下是一个简单的固定长度分块实现：
使用示例：
十、删除与更新操作
十一、性能优化建议
「1. 启用 Payload 索引加速过滤」
如果你频繁按某个字段过滤，为该字段创建索引可以大幅提升过滤速度：
「2. 批量写入而非逐条写入」
Qdrant 的 UpsertAsync 支持一次传入多个 Point，建议每批 100~500 条，避免频繁的网络往返。
「3. 调整 scoreThreshold 控制结果质量」
相似度阈值（scoreThreshold）是 RAG 效果的重要参数：
设置过低：噪音数据进入上下文，影响 GPT 回答质量 设置过高：召回率下降，可能找不到相关文档 建议从 0.70开始调优，根据实际效果微调
「4. 使用量化压缩降低内存占用」
对于超大规模的向量集合，可启用标量量化（Scalar Quantization）将内存占用降低 4 倍：
十二、总结
本文带你走完了在 .NET 中使用 Qdrant 的完整链路：
「Docker 启动 Qdrant」 —— 本地开发零门槛 「安装 Qdrant.Client和OpenAI」 —— 官方 SDK，类型安全「使用 text-embedding-3-small」 将文本转换为 1536 维向量「创建集合、批量写入 PointStruct」，Payload 携带元数据「 SearchAsync+scoreThreshold」 实现语义检索「结合 Qdrant 的过滤语法」 实现向量 + 标量的混合搜索 「将检索结果作为上下文传给 GPT-4o-mini」，完成 RAG 问答闭环
向量数据库是构建 AI Native 应用的基础设施。Qdrant 在性能、API 设计和 .NET 集成上都表现出色，是目前 .NET 生态中接入向量能力的首选方案。掌握它，你就拥有了构建企业级知识库、语义搜索和 AI 助手的核心能力。
❝📎 「参考资源」
Qdrant 官方文档：https://qdrant.org.cn/documentation/overview/ Qdrant .NET SDK：https://github.com/qdrant/qdrant-dotnet OpenAI .NET SDK：https://github.com/openai/openai-dotnet NuGet： Qdrant.Client 1.17.0|OpenAI 2.10.0
