Events
Mar 17, 9 PM - Mar 21, 10 AM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Includes:
Hosting integration and
Client integration
Qdrant is an open-source vector similarity search engine that efficiently stores, indexes, and searches large-scale vector data. It's commonly used in machine learning, artificial intelligence, and data science applications.
Vector data encodes information as mathematical vectors, which are arrays of numbers or coordinates. Machine learning and AI systems often use vectors to represent unstructured objects like images, text, audio, or video. Each dimension in the vector describes a specific characteristic of the object. By comparing them, systems can classify, search, and identify clusters of objects.
In this article, you learn how to use the .NET Aspire Qdrant integration. The .NET Aspire Qdrant integration enables you to connect to existing Qdrant databases or create new instances with the qdrant/qdrant
container image.
The Qdrant hosting integration models the server as the QdrantServerResource type. To access this type and APIs, add the 📦 Aspire.Hosting.Qdrant NuGet package in the app host project.
dotnet add package Aspire.Hosting.Qdrant
For more information, see dotnet add package or Manage package dependencies in .NET applications.
In your app host project, call AddQdrant to add and return a Qdrant resource builder.
var builder = DistributedApplication.CreateBuilder(args);
var qdrant = builder.AddQdrant("qdrant")
.WithLifetime(ContainerLifetime.Persistent);
builder.AddProject<Projects.ExampleProject>()
.WithReference(qdrant)
.WaitFor(qdrant);
// After adding all resources, run the app...
Note
The Qdrant container can be slow to start, so it's best to use a persistent lifetime to avoid unnecessary restarts. For more information, see Container resource lifetime.
When .NET Aspire adds a container image to the app host, as shown in the preceding example with the qdrant/qdrant
image, it creates a new Qdrant instance on your local machine. The resource is named qdrant
and then added to the ExampleProject
.
The WithReference method configures a connection in the ExampleProject
named qdrant
.
Tip
If you'd rather connect to an existing Qdrant server, call AddConnectionString instead. For more information, see Reference existing resources.
Tip
The qdrant/qdrant
container image includes a web UI that you can use to explore your vectors and administer the database. To access this tool, start your .NET Aspire solution and then, in the .NET Aspire dashboard, select the endpoint for the Qdrant resource. In your browser's address bar, append /dashboard and press Enter.
To connect to Qdrant a client must pass the right API key. In the above code, when .NET Aspire adds a Qdrant resource to your solution, it sets the API key to a random string. If you want to use a specific API key instead, you can pass it as an apiKey
parameter:
var apiKey = builder.AddParameter("apiKey", secret: true);
var qdrant = builder.AddQdrant("qdrant", apiKey);
builder.AddProject<Projects.ExampleProject>()
.WithReference(qdrant);
Qdrant supports configuration-based default API keys by using the environment variable QDRANT__SERVICE__API_KEY
.
The preceding code gets a parameter to pass to the AddQdrant
API, and internally assigns the parameter to the QDRANT__SERVICE__API_KEY
environment variable of the Qdrant container. The apiKey
parameter is usually specified as a user secret:
{
"Parameters": {
"apiKey": "Non-default-P@ssw0rd"
}
}
For more information, see External parameters.
To add a data volume to the Qdrant resource, call the WithDataVolume extension method:
var builder = DistributedApplication.CreateBuilder(args);
var qdrant = builder.AddQdrant("qdrant")
.WithLifetime(ContainerLifetime.Persistent)
.WithDataVolume();
builder.AddProject<Projects.ExampleProject>()
.WithReference(qdrant)
.WaitFor(qdrant);
// After adding all resources, run the app...
The data volume is used to persist the Qdrant data outside the lifecycle of its container. The data volume is mounted at the /qdrant/storage
path in the Qdrant container and when a name
parameter isn't provided, the name is generated at random. For more information on data volumes and details on why they're preferred over bind mounts, see Docker docs: Volumes.
To add a data bind mount to the Qdrant resource, call the WithDataBindMount method:
var builder = DistributedApplication.CreateBuilder(args);
var qdrant = builder.AddQdrant("qdrant")
.WithLifetime(ContainerLifetime.Persistent)
.WithDataBindMount(source: @"C:\Qdrant\Data");
builder.AddProject<Projects.ExampleProject>()
.WithReference(qdrant)
.WaitFor(qdrant);
// After adding all resources, run the app...
Important
Data bind mounts have limited functionality compared to volumes, which offer better performance, portability, and security, making them more suitable for production environments. However, bind mounts allow direct access and modification of files on the host system, ideal for development and testing where real-time changes are needed.
Data bind mounts rely on the host machine's filesystem to persist the Qdrant data across container restarts. The data bind mount is mounted at the C:\Qdrant\Data
folder on Windows (or /Qdrant/Data
on Unix) on the host machine in the Qdrant container. For more information on data bind mounts, see Docker docs: Bind mounts.
The Qdrant hosting integration automatically adds a health check for the Qdrant resource. The health check verifies that Qdrant is running and that a connection can be established to it.
To get started with the .NET Aspire Qdrant client integration, install the 📦 Aspire.Qdrant.Client NuGet package in the client-consuming project, that is, the project for the application that uses the Qdrant client. The Qdrant client integration registers a Qdrant.Client.QdrantClient instance that you can use to interact with Qdrant vector data.
dotnet add package Aspire.Qdrant.Client
In the Program.cs file of your client-consuming project, call the AddQdrantClient extension method on any IHostApplicationBuilder to register a QdrantClient
for use through the dependency injection container. The method takes a connection name parameter.
builder.AddQdrantClient("qdrant");
Tip
The connectionName
parameter must match the name used when adding the Qdrant resource in the app host project. In other words, when you call AddQdrant
and provide a name of qdrant
that same name should be used when calling AddQdrantClient
. For more information, see Add Qdrant resource.
You can then retrieve the QdrantClient
instance using dependency injection. For example, to retrieve the connection from an example service:
public class ExampleService(QdrantClient client)
{
// Use client...
}
For more information on dependency injection, see .NET dependency injection.
There might be situations where you want to register multiple QdrantClient
instances with different connection names. To register keyed Qdrant clients, call the AddKeyedQdrantClient method:
builder.AddKeyedQdrantClient(name: "mainQdrant");
builder.AddKeyedQdrantClient(name: "loggingQdrant");
Then you can retrieve the QdrantClient
instances using dependency injection. For example, to retrieve the connections from an example service:
public class ExampleService(
[FromKeyedServices("mainQdrant")] QdrantClient mainQdrantClient,
[FromKeyedServices("loggingQdrant")] QdrantClient loggingQdrantClient)
{
// Use clients...
}
For more information on keyed services, see .NET dependency injection: Keyed services.
The .NET Aspire Qdrant client integration provides multiple options to configure the connection to Qdrant based on the requirements and conventions of your project.
When using a connection string from the ConnectionStrings
configuration section, you can provide the name of the connection string when calling builder.AddQdrantClient()
:
builder.AddQdrantClient("qdrant");
Then .NET Aspire retrieves the connection string from the ConnectionStrings
configuration section:
{
"ConnectionStrings": {
"qdrant": "Endpoint=http://localhost:6334;Key=123456!@#$%"
}
}
By default the QdrantClient
uses the gRPC API endpoint.
The .NET Aspire Qdrant client integration supports Microsoft.Extensions.Configuration. It loads the QdrantClientSettings from configuration by using the Aspire:Qdrant:Client
key. The following is an example of an appsettings.json that configures some of the options:
{
"Aspire": {
"Qdrant": {
"Client": {
"Endpoint": "http://localhost:6334/",
"Key": "123456!@#$%"
}
}
}
}
For the complete Qdrant client integration JSON schema, see Aspire.Qdrant.Client/ConfigurationSchema.json.
You can also pass the Action<QdrantClientSettings> configureSettings
delegate to set up some or all the options inline, for example to set the API key from code:
builder.AddQdrantClient(
"qdrant",
settings => settings.Key = "12345!@#$%");
By default, .NET Aspire integrations enable health checks for all services. For more information, see .NET Aspire integrations overview.
.NET Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. For more information about integration observability and telemetry, see .NET Aspire integrations overview. Depending on the backing service, some integrations may only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the Configuration section.
The .NET Aspire Qdrant integration uses standard .NET logging, and you'll see log entries from the following category:
Qdrant.Client
The .NET Aspire Qdrant integration doesn't currently emit tracing activities because they are not supported by the Qdrant.Client
library.
The .NET Aspire Qdrant integration doesn't currently emit metrics because they are not supported by the Qdrant.Client
library.
.NET Aspire feedback
.NET Aspire is an open source project. Select a link to provide feedback:
Events
Mar 17, 9 PM - Mar 21, 10 AM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowTraining
Module
Customize a .NET Aspire app to use existing Azure resources - Training
In this module, you'll learn how to move backing services for your Azure-hosted .NET Aspire app from containers into native Azure services.
Certification
Microsoft Certified: Azure Cosmos DB Developer Specialty - Certifications
Write efficient queries, create indexing policies, manage, and provision resources in the SQL API and SDK with Microsoft Azure Cosmos DB.
Documentation
.NET Aspire Milvus database integration - .NET Aspire
Learn how to use the .NET Aspire Milvus database integration, which includes both hosting and client integrations.
.NET Aspire NATS integration - .NET Aspire
Learn how to use the .NET Aspire NATS integration to send logs and traces to a NATS Server.
.NET Aspire Seq integration - .NET Aspire
Learn how to use the .NET Aspire Seq integration to add OpenTelemetry Protocol (OTLP) exporters that send logs and traces to a Seq Server.