Get started with the Qdrant integrations

Este conteúdo não está disponível em sua língua ainda.

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. The Aspire Qdrant integration enables you to connect to existing Qdrant servers or create new servers from Aspire with the qdrant/qdrant container image.

In this introduction, you’ll see how to install and use the Aspire Qdrant integrations in a simple configuration. If you already have this knowledge, see Qdrant Hosting integration for full reference details.

Set up hosting integration

To begin, install the Aspire Qdrant Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Qdrant vector database instances from your Aspire hosting projects:

aspire add qdrant

A Aspire CLI é interativa; escolha o resultado adequado quando solicitado:

Select an integration to add:

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

#:package Aspire.Hosting.Qdrant@*

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

Next, in the AppHost project, create instances of Qdrant server resources, then pass the server to the consuming client projects:

Select your programming language to get started

var builder = DistributedApplication.CreateBuilder(args);

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

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
                            .WaitFor(qdrant)
                            .WithReference(qdrant);

var builder = DistributedApplication.CreateBuilder(args);

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

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

var builder = DistributedApplication.CreateBuilder(args);

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

var api = builder.AddNodeApp("api", "./api", scriptPath: "index.js")
                 .WithExternalHttpEndpoints()
                 .WaitFor(qdrant)
                 .WithReference(qdrant);

Use the integration in client projects

Now that the hosting integration is ready, the next step is to install and configure the client integration in any projects that need to use it.

Set up client projects

In each of these consuming client projects, install the Aspire Qdrant client integration:

dotnet add package Aspire.Qdrant.Client

#:package Aspire.Qdrant.Client@*

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

In the Program.cs file of your client-consuming project, call the AddQdrantClient extension method on any IHostApplicationBuilder to register a QdrantClient for use via the dependency injection container. The method takes a connection name parameter.

builder.AddQdrantClient(connectionName: "qdrant");

To interact with Qdrant vector databases in your Python consuming projects, you need to include a Qdrant client library. The official option is qdrant-client, which is Qdrant’s Python SDK. You can install this library using pip:

pip install qdrant-client

Ensure that you import the QdrantClient in code files that interact with the vector database. You should also import the os module to access environment variables:

from qdrant_client import QdrantClient
import os

To interact with Qdrant vector databases in your JavaScript consuming projects, you need to include a Qdrant client library. The official option is @qdrant/js-client-rest, which is Qdrant’s JavaScript/TypeScript SDK. You can install this library using npm:

npm install @qdrant/js-client-rest

Ensure that you import the QdrantClient in code files that interact with the vector database:

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

Use injected Qdrant properties

In the AppHost, when you used the WithReference method to pass a Qdrant resource to a consuming client project, Aspire injects several configuration properties that you can use in the consuming project.

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Uri property of a resource called qdrant becomes QDRANT_URI.

Use the GetValue() method to obtain these environment variables in consuming projects:

string connectionString = builder.Configuration.GetValue<string>("ConnectionStrings__qdrant");
string apiKey = builder.Configuration.GetValue<string>("QDRANT_APIKEY");

Use the os.getenv() method to obtain these environment variables in consuming projects:

connection_string = os.getenv("ConnectionStrings__qdrant")
api_key = os.getenv("QDRANT_APIKEY")
grpc_host = os.getenv("QDRANT_GRPCHOST")
grpc_port = os.getenv("QDRANT_GRPCPORT")

Use the process.env property to obtain these environment variables in consuming projects:

const connectionString = process.env.ConnectionStrings__qdrant;
const apiKey = process.env.QDRANT_APIKEY;
const grpcHost = process.env.QDRANT_GRPCHOST;
const grpcPort = process.env.QDRANT_GRPCPORT;

Use Qdrant resources in client code

Now that you’ve added the QdrantClient to the builder in the consuming project, you can use the Qdrant vector database to store and search vector data. Get the QdrantClient instance using dependency injection. For example, to retrieve your client object from an example service, define it as a constructor parameter and ensure the ExampleService class is registered with the dependency injection container:

public class ExampleService(QdrantClient client)
{
    // Use Qdrant client...
}

Having obtained the client, you can work with the Qdrant vector database as you would in any other C# application.

Use the information you have obtained about the Qdrant resource to connect to the vector database. Here is an example of how to connect using qdrant-client:

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

# Verify connection
print(client.get_collections())

Having obtained the client, you can work with the Qdrant vector database as you would in any other Python application.

Use the information you have obtained about the Qdrant resource to connect to the vector database. Here is an example of how to connect using @qdrant/js-client-rest:

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

// Verify connection
const collections = await client.getCollections();
console.log('Collections:', collections);

Having obtained the client, you can work with the Qdrant vector database as you would in any other JavaScript application.

Next steps

Now that you have an Aspire app with Qdrant integrations up and running, you can use the following reference documents to learn how to configure and interact with the Qdrant resources:

Understand the Qdrant hosting integration Discover how to configure data volumes, API keys, and more.

Understand the Qdrant client integration Learn about the Qdrant client integration, including connection strings and observability.