Qdrant Hosting integration reference

To get started with the Aspire Qdrant integrations, follow the Get started with Qdrant integrations guide.

This article includes full details about the Aspire Qdrant Hosting integration, which models Qdrant server resources as the QdrantServerResource type.

Installation

The Aspire Qdrant hosting integration models the Qdrant vector database server as the QdrantServerResource type.

To access these types and APIs for expressing them as resources in your AppHost project, install the 📦 Aspire.Hosting.Qdrant NuGet package:

Aspire CLI

Aspire CLI — Додати пакет Aspire.Hosting.Qdrant

aspire add qdrant

Aspire CLI інтерактивний; оберіть відповідний результат пошуку:

Aspire CLI — Приклад виводу

Select an integration to add:

> qdrant (Aspire.Hosting.Qdrant)
> Other results listed as selectable options...

Заувага

Якщо лише один результат — він вибирається автоматично. Потрібно підтвердити версію.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.Qdrant@*

PackageReference (*.csproj)

XML — Додати посилання на пакет Aspire.Hosting.Qdrant

<PackageReference Include="Aspire.Hosting.Qdrant" Version="*" />

Add Qdrant resource

In the AppHost project, call AddQdrant to add and return a Qdrant server resource builder:

C# — AppHost.cs

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...

Заувага

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 Aspire adds a container image to the AppHost, as shown in the preceding example with the qdrant/qdrant image, it creates a new Qdrant server on your local machine. A reference to your Qdrant resource builder (the qdrant variable) is used to connect your application.

The WithReference method configures a connection in the ExampleProject named "qdrant". For more information, see Container resource lifecycle.

Порада

If you’d rather connect to an existing Qdrant server, call AddConnectionString instead. For more information, see Reference existing resources.

Add Qdrant resource with API key parameter

The Qdrant resource includes a default, randomly generated API key. Qdrant supports configuration-based API keys. When you want to provide an API key explicitly, you can provide it as a parameter:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var apiKey = builder.AddParameter("apiKey", secret: true);

var qdrant = builder.AddQdrant("qdrant", apiKey)
                    .WithLifetime(ContainerLifetime.Persistent);

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(qdrant)
                       .WaitFor(qdrant);

The preceding code gets a parameter to pass to the AddQdrant API, and internally assigns the parameter to the Qdrant container configuration. The apiKey parameter is usually specified as a user secret:

JSON — secrets.json

{
  "Parameters": {
    "apiKey": "your-secure-api-key"
  }
}

For more information, see External parameters.

Add Qdrant resource with data volume

To add a data volume to the Qdrant resource, call the WithDataVolume method:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var qdrant = builder.AddQdrant("qdrant")
                    .WithDataVolume()
                    .WithLifetime(ContainerLifetime.Persistent);

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.

Add Qdrant resource with data bind mount

To add a data bind mount to the Qdrant resource, call the WithDataBindMount method:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var qdrant = builder.AddQdrant("qdrant")
                    .WithDataBindMount(source: @"C:\Qdrant\Data")
                    .WithLifetime(ContainerLifetime.Persistent);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(qdrant)
       .WaitFor(qdrant);

// After adding all resources, run the app...

Заувага

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 on Windows (or /Qdrant/Data on Unix) path on the host machine in the Qdrant container. For more information on data bind mounts, see Docker docs: Bind mounts.

Using with non-.NET applications

When you use the WithReference method to pass a Qdrant resource to a non-.NET application (such as Python or JavaScript), Aspire automatically injects environment variables that describe the connection information.

For example, if you reference a Qdrant resource named qdrant:

C# — AppHost.cs

var qdrant = builder.AddQdrant("qdrant");

var pythonApp = builder.AddUvicornApp("api", "./api", "main.app")
    .WithReference(qdrant);

The following environment variables are available in the Python application:

• ConnectionStrings__qdrant - The connection string for the Qdrant server
• QDRANT_GRPCHOST - The gRPC hostname of the Qdrant server
• QDRANT_GRPCPORT - The gRPC port number
• QDRANT_HTTPHOST - The HTTP hostname of the Qdrant server
• QDRANT_HTTPPORT - The HTTP port number
• QDRANT_APIKEY - The API key for authentication
• QDRANT_URI - The gRPC connection URI
• QDRANT_HTTPURI - The HTTP connection URI

You can access these environment variables in your application code:

Python example

from qdrant_client import QdrantClient
import os

# Get connection properties
grpc_host = os.getenv("QDRANT_GRPCHOST")
grpc_port = os.getenv("QDRANT_GRPCPORT")
api_key = os.getenv("QDRANT_APIKEY")

# Create Qdrant client
client = QdrantClient(
    host=grpc_host,
    port=int(grpc_port),
    api_key=api_key,
    prefer_grpc=True
)

JavaScript example

const { QdrantClient } = require('@qdrant/js-client-rest');

// Get connection properties
const httpHost = process.env.QDRANT_HTTPHOST;
const httpPort = process.env.QDRANT_HTTPPORT;
const apiKey = process.env.QDRANT_APIKEY;

// Create Qdrant client
const client = new QdrantClient({
  url: `http://${httpHost}:${httpPort}`,
  apiKey: apiKey
});

Hosting integration health checks

The Qdrant hosting integration automatically adds a health check for the Qdrant resource. The health check verifies that the Qdrant server is running and that a connection can be established to it.