Aspire 集成 Qdrant 向量数据库：Aspire.Hosting.Qdrant 实战指南

Aspire 集成 Qdrant 向量数据库Aspire.Hosting.Qdrant 实战指南【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspireAspire 的 Qdrant 托管集成Hosting Integration允许你在 Aspire 应用模型中以代码优先的方式建模、配置并编排一个 Qdrant 向量数据库容器资源并通过WithReference将连接信息注入到任意消费方.NET 项目、Node.js 应用、其他容器。本文基于src/Aspire.Hosting.Qdrant模块的源码与文档完整讲解从安装、声明资源、连接属性到客户端消费、数据持久化与部署清单的端到端用法。集成概览它在 Aspire 解决方案中扮演什么角色Qdrant 是一个面向 AI/机器学习场景的向量数据库常被用于语义检索、RAG检索增强生成等应用。在 Aspire 中Aspire.Hosting.Qdrant集成的作用是模型化将 Qdrant 服务器抽象为一个QdrantServerResource资源对象纳入 Aspire 的应用模型配置自动处理容器镜像、gRPC/HTTP 双端点、API Key 参数、健康检查等基础设施细节编排在本地开发时以 Docker 容器方式启动 Qdrant在发布时生成可部署的 manifest。该集成由两部分协同工作位于 src/Aspire.Hosting.Qdrant 的托管集成AppHost 侧负责编排服务器以及 src/Components/Aspire.Qdrant.Client 的客户端组件业务服务侧负责注入QdrantClient供 DI 消费。快速开始将集成添加到 AppHost从 AppHost 项目目录执行以下 Aspire CLI 命令即可将Aspire.Hosting.Qdrant集成加入当前解决方案aspire add Aspire.Hosting.Qdrant该命令会完成包引用与必要的项目配置。也可以手动通过dotnet add package Aspire.Hosting.Qdrant在 AppHost 项目中添加包引用参见 src/Components/Aspire.Qdrant.Client/README.md 中的 AppHost extensions 一节。声明 Qdrant 资源并建立引用C#.NET AppHost在 AppHost 的Program.cs中调用AddQdrant声明资源再通过WithReference让其他资源引用它var qdrant builder.AddQdrant(qdrant); var myService builder.AddProjectProjects.MyService() .WithReference(qdrant);TypeScriptPolyglot AppHost在 TypeScript 版 AppHost 中用法等价使用小驼峰的addQdrant与withReferenceconst qdrant await builder.addQdrant(qdrant); const myService await builder.addNodeApp(myService, ../my-service, server.js) .withReference(qdrant);业务服务侧消费连接在被引用的MyService项目中安装Aspire.Qdrant.Client后调用AddQdrantClient注册QdrantClientbuilder.AddQdrantClient(qdrant);之后即可通过依赖注入获取QdrantClient执行向量集合、点point的增删改查等操作。AddQdrant 方法签名与底层实现细节AddQdrant定义在 src/Aspire.Hosting.Qdrant/QdrantBuilderExtensions.cs其完整签名如下public static IResourceBuilderQdrantServerResource AddQdrant( this IDistributedApplicationBuilder builder, string name, IResourceBuilderParameterResource? apiKey null, int? grpcPort null, int? httpPort null)各参数说明参数类型含义namestring资源名称同时用作被引用方连接字符串的名称apiKeyIResourceBuilderParameterResource?用于提供 Qdrant API Key 的参数传null时自动生成名为{name}-Key的随机密码参数grpcPortint?gRPC 端点在宿主机上的端口容器内固定为 6334httpPortint?HTTP 端点在宿主机上的端口容器内固定为 6333源码中硬编码的两个容器端口常量QdrantBuilderExtensions.cs为QdrantPortGrpc 6334Qdrant gRPC 接口.NET 客户端默认走此通道QdrantPortHttp 6333Qdrant REST/HTTP 接口。默认使用的容器镜像定义在 src/Aspire.Hosting.Qdrant/QdrantContainerImageTags.csRegistrydocker.ioImageqdrant/qdrantTagv1.18.0当前仓库锁定版本端点与传输协议AddQdrant内部通过WithHttpEndpoint暴露两个命名端点资源类QdrantServerResource中定义了端点常量QdrantServerResource.cs端点名用途容器端口传输协议grpc主端点gRPC 数据通道6334http2httpREST/HTTP 接口及 Web UI6333httpgRPC 端点被显式标记为http2传输同时集成会为 HTTP 端点注册两个便于访问的仪表盘入口Qdrant (GRPC)显示在详情页Qdrant (HTTP)与Qdrant Dashboard指向/dashboard作为资源链接显示。API Key 的自动生成与环境注入当不显式传入apiKey参数时AddQdrant会调用CreateDefaultPasswordParameter自动生成{name}-Key随机密码参数。随后该密钥通过环境变量QDRANT__SERVICE__API_KEY注入容器QdrantBuilderExtensions.cscontext.EnvironmentVariables[ApiKeyEnvVarName] qdrant.ApiKeyParameter; // QDRANT__SERVICE__API_KEY在发布模式IsPublishMode下还会额外注入QDRANT__SERVICE__ENABLE_STATIC_CONTENT0以关闭 Qdrant 内置的 Dashboard Web UI避免在生产部署中暴露不必要的静态内容。连接属性详解Connection Properties当消费方通过WithReference引用 Qdrant 资源时以下连接属性会暴露给消费项目表格来自 src/Aspire.Hosting.Qdrant/README.md底层实现在 QdrantServerResource.cs 的GetConnectionProperties属性名说明GrpcHostQdrant 服务器的 gRPC 主机名GrpcPortQdrant 服务器的 gRPC 端口HttpHostQdrant 服务器的 HTTP 主机名HttpPortQdrant 服务器的 HTTP 端口ApiKey用于认证的 API KeyUrigRPC 连接 URI格式为http://{GrpcHost}:{GrpcPort}HttpUriHTTP 连接 URI格式为http://{HttpHost}:{HttpPort}环境变量命名规则Aspire 将上述每个属性以[RESOURCE]_[PROPERTY]的命名规则暴露为环境变量。例如名为db1的资源的Uri属性会变成环境变量DB1_URIHttpUri则对应DB1_HTTPURI。这组连接属性测试的期望值可参见 tests/Aspire.Hosting.Qdrant.Tests/ConnectionPropertiesTests.cs其中验证了每个属性的表达式形态如Uri对应{qdrant.bindings.grpc.url}。WithReference 注入的连接字符串除了按属性展开的环境变量外WithReferenceQdrantBuilderExtensions.cs还会向消费方注入两套连接字符串ConnectionStrings__{connectionName}gRPC 连接字符串形如Endpointhttp://localhost:6334;Key...ConnectionStrings__{connectionName}_httpHTTP 连接字符串形如Endpointhttp://localhost:6333;Key...。连接字符串格式由 QdrantServerResource.cs 定义为Endpoint{uri};Key{apiKey}。测试 tests/Aspire.Hosting.Qdrant.Tests/AddQdrantTests.cs 验证了容器内引用时端点会解析为my-qdrant.dev.internal内部网络地址且项目与容器两类消费方均能获得正确注入。客户端组件Aspire.Qdrant.Client 的三种配置方式Aspire.Qdrant.Client源码见 src/Components/Aspire.Qdrant.Client将QdrantClient注册为单例并默认附带健康检查。注册入口为AddQdrantClient(connectionName, configureSettings?)与键控版本AddKeyedQdrantClient(name, configureSettings?)AspireQdrantExtensions.cs。方式一使用连接字符串通过ConnectionStrings配置节提供连接字符串键名与AddQdrantClient传入的名称一致{ ConnectionStrings: { qdrant: Endpointhttp://localhost:6334;Key123456!#$% } }builder.AddQdrantClient(qdrant);默认情况下QdrantClient使用 gRPC API 端点即连接字符串中的Endpoint指向 6334 端口。连接字符串的解析逻辑ParseConnectionString在 QdrantClientSettings.cs既支持裸 URIhttp://...也支持Endpoint...;Key...键值对形式。方式二使用配置提供程序组件从Aspire:Qdrant:Client配置节加载设置也支持按连接名命名的子节Aspire:Qdrant:Client:{connectionName}{ Aspire: { Qdrant: { Client: { Key: 123456!#$% } } } }方式三使用内联委托通过ActionQdrantClientSettings configureSettings在代码中直接设置选项例如builder.AddQdrantClient(qdrant, settings settings.Key 12345!#$%);QdrantClientSettings支持的设置项QdrantClientSettings.cs属性默认值说明EndpointnullQdrant 服务器端点 URIKeynull连接所需的 API KeyDisableHealthChecksfalse是否禁用客户端健康检查HealthCheckTimeoutnull健康检查超时时间数据持久化数据卷与绑定挂载Qdrant 的数据存储在容器内的/qdrant/storage目录。集成提供两个持久化扩展方法QdrantBuilderExtensions.csWithDataVolume(name?, isReadOnly?)—— 命名卷名称缺省时自动生成基于资源名var qdrant builder.AddQdrant(qdrant) .WithDataVolume(); // 可选.WithDataVolume(qdrant-data, isReadOnly: false)WithDataBindMount(source, isReadOnly?)—— 绑定挂载将宿主机目录映射进容器var qdrant builder.AddQdrant(qdrant) .WithDataBindMount(/data/qdrant, isReadOnly: false);两者都挂载到容器内的/qdrant/storage保证容器重建后向量数据不丢失。健康检查与可观测性集成在服务器侧与客户端侧各注册了一个健康检查服务器侧AddQdrant订阅ConnectionStringAvailableEvent在连接字符串就绪后创建QdrantClient并注册名为{name}_check的健康检查QdrantBuilderExtensions.cs客户端侧AddQdrantClient默认注册Qdrant.Client键控场景为Qdrant.Client_{connectionName}健康检查实现类 QdrantHealthCheck.cs 通过调用QdrantClient.HealthAsync验证服务器返回的Title字段来判断健康状态失败或异常时报告Unhealthy。这些健康检查会参与 Aspire 的资源状态展示与依赖就绪判断是本地开发与部署时资源可观测能力的一部分。部署与 Manifest在发布Publish模式下AddQdrant生成的资源会产出container.v0类型的 manifest。测试 tests/Aspire.Hosting.Qdrant.Tests/AddQdrantTests.cs 给出了两种典型形态自动生成 API Key 时{ type: container.v0, connectionString: Endpoint{qdrant.bindings.grpc.url};Key{qdrant-Key.value}, image: docker.io/qdrant/qdrant:v1.18.0, env: { QDRANT__SERVICE__API_KEY: {qdrant-Key.value}, QDRANT__SERVICE__ENABLE_STATIC_CONTENT: 0 }, bindings: { grpc: { scheme: http, protocol: tcp, transport: http2, targetPort: 6334 }, http: { scheme: http, protocol: tcp, transport: http, targetPort: 6333 } } }显式传入QdrantApiKey参数时连接字符串与环境变量中的密钥引用变为{QdrantApiKey.value}密钥由外部参数源在部署时提供避免硬编码。这也印证了发布模式下QDRANT__SERVICE__ENABLE_STATIC_CONTENT会被置为0以关闭 Dashboard。指定宿主机端口需要固定宿主机端口时通过AddQdrant的grpcPort与httpPort参数指定容器内目标端口仍为 6334/6333var qdrant builder.AddQdrant(my-qdrant, grpcPort: 5503, httpPort: 5504);该行为由测试 AddQdrantTests.cs 验证宿主机端口变为 5503/5504而TargetPort保持 6334/6333 不变两个端点均为非外部IsExternal falseTCP 端点。深入阅读指引托管集成源码src/Aspire.Hosting.Qdrant/QdrantBuilderExtensions.cs、src/Aspire.Hosting.Qdrant/QdrantServerResource.cs、src/Aspire.Hosting.Qdrant/QdrantContainerImageTags.cs客户端组件源码src/Components/Aspire.Qdrant.Client/AspireQdrantExtensions.cs、src/Components/Aspire.Qdrant.Client/QdrantClientSettings.cs、src/Components/Aspire.Qdrant.Client/QdrantHealthCheck.cs测试用例tests/Aspire.Hosting.Qdrant.Tests/AddQdrantTests.cs、tests/Aspire.Hosting.Qdrant.Tests/ConnectionPropertiesTests.cs客户端组件 READMEsrc/Components/Aspire.Qdrant.Client/README.md注Qdrant 及 Qdrant 标志为德国 Qdrant Solutions GmbH 的商标或注册商标经许可使用。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考