Milvus integration

Milvus is an open-source vector database system 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.

Hosting integration

The Milvus database hosting integration models the server as the MilvusServerResource type and the database as the MilvusDatabaseResource type. To access these types and APIs, add the 📦 Aspire.Hosting.Milvus NuGet package in your AppHost project:

Aspire CLI

Aspire CLI — Add Aspire.Hosting.Milvus package

aspire add milvus

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Aspire CLI — Example output prompt

Select an integration to add:

> milvus (Aspire.Hosting.Milvus)
> Other results listed as selectable options...

Note

If there's only one result, the CLI selects it automatically. You'll still need to confirm the version.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.Milvus@*

PackageReference (*.csproj)

XML — Add Aspire.Hosting.Milvus package reference

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

Add Milvus server and database resources

In your AppHost project, call AddMilvus to add and return a Milvus resource builder. Chain a call to the returned resource builder to AddDatabase, to add a Milvus database resource:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithLifetime(ContainerLifetime.Persistent);

var milvusdb = milvus.AddDatabase("milvusdb");

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

Note

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

The WithReference method configures a connection in the ExampleProject named milvusdb.

Tip

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

Handling credentials and parameters

The Milvus resource includes default credentials with a username of root and the password Milvus. To change the default password in the container, pass an apiKey parameter:

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

var milvus = builder.AddMilvus("milvus", apiKey);

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

For more information, see External parameters.

Add a Milvus resource with a data volume

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

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithDataVolume();

var milvusdb = milvus.AddDatabase("milvusdb");

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

The data volume is used to persist the Milvus data outside the lifecycle of its container. The data volume is mounted at the /var/lib/milvus path.

Add a Milvus resource with a data bind mount

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

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithDataBindMount(source: @"C:\Milvus\Data");

var milvusdb = milvus.AddDatabase("milvusdb");

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

Note

Data bind mounts have limited functionality compared to volumes, and when you use a bind mount, a file or directory on the host machine is mounted into a container.

Create an Attu resource

Attu is a graphical user interface (GUI) and management tool designed to interact with Milvus and its databases. To use Attu, call the WithAttu extension method:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var milvus = builder.AddMilvus("milvus")
                    .WithAttu()
                    .WithLifetime(ContainerLifetime.Persistent);

var milvusdb = milvus.AddDatabase("milvusdb");

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

When you debug the Aspire solution, you’ll see an Attu container listed in the resources. Select the resource’s endpoint to open the GUI.

Connection properties

When you reference a Milvus resource using WithReference, the following connection properties are made available to the consuming project:

Milvus server

The Milvus server resource exposes the following connection properties:

Property Name	Description
Host	The hostname or IP address of the Milvus server
Port	The gRPC port exposed by the Milvus server
Token	The authentication token, with the format root:{ApiKey}
Uri	The gRPC endpoint URI, with the format http://{Host}:{Port}

Example connection strings:

Uri: http://localhost:19530
Token: root:Milvus

Milvus database

The Milvus database resource combines the server properties above and adds the following connection property:

Property Name	Description
Database	The Milvus database name

Note

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

Client integration

Caution

The client integration is currently in preview.

To get started with the Aspire Milvus client integration, install the 📦 Aspire.Milvus.Client NuGet package in the client-consuming project:

.NET CLI

.NET CLI — Add Aspire.Milvus.Client package

dotnet add package Aspire.Milvus.Client

Program.cs (C# file-based app)

Program.cs

#:package Aspire.Milvus.Client@*

PackageReference (*.csproj)

XML — Add Aspire.Milvus.Client package reference

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

Add a Milvus client

In the Program.cs file, call the AddMilvusClient extension method to register a MilvusClient:

builder.AddMilvusClient("milvusdb");

Tip

The connectionName parameter must match the name used when adding the Milvus database resource in the AppHost project.

You can then retrieve the MilvusClient instance using dependency injection:

public class ExampleService(MilvusClient client)
{
    // Use the Milvus Client...
}

Add a keyed Milvus client

There might be situations where you want to register multiple MilvusClient instances. To register keyed Milvus clients, call the AddKeyedMilvusClient method:

builder.AddKeyedMilvusClient(name: "mainDb");
builder.AddKeyedMilvusClient(name: "loggingDb");

Then retrieve the instances:

public class ExampleService(
    [FromKeyedServices("mainDb")] MilvusClient mainDbClient,
    [FromKeyedServices("loggingDb")] MilvusClient loggingDbClient)
{
    // Use clients...
}

Configuration

Use a connection string

When using a connection string from the ConnectionStrings configuration section:

builder.AddMilvusClient("milvus");

Then the connection string will be retrieved:

{
  "ConnectionStrings": {
    "milvus": "Endpoint=http://localhost:19530/;Key=root:Non-default-P@ssw0rd"
  }
}

Use configuration providers

The Milvus client integration supports Microsoft.Extensions.Configuration. Example appsettings.json:

{
  "Aspire": {
    "Milvus": {
      "Client": {
        "Endpoint": "http://localhost:19530/",
        "Database": "milvusdb",
        "Key": "root:Non-default-P@ssw0rd",
        "DisableHealthChecks": false
      }
    }
  }
}

Use inline delegates

You can pass the delegate to set up options inline:

builder.AddMilvusClient(
    "milvus",
    static settings => settings.Key = "root:Non-default-P@ssw0rd");

Client integration health checks

By default, Aspire integrations enable health checks. The Milvus database integration adds a health check when DisableHealthChecks is false, which attempts to connect to the Milvus server.

Observability and telemetry

Logging

The Milvus integration uses the Milvus.Client log category.

Tracing and Metrics

The Milvus integration doesn’t currently emit tracing activities or metrics because they are not supported by the Milvus.Client library.