diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 7916f562..d9017f4a 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -518,7 +518,24 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'KurrentDB', slug: 'integrations/databases/kurrentdb' }, { label: 'Meilisearch', slug: 'integrations/databases/meilisearch' }, - { label: 'Milvus', slug: 'integrations/databases/milvus' }, + { + label: 'Milvus', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/databases/milvus/milvus-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/databases/milvus/milvus-host', + }, + { + label: 'Client integration (Your app)', + slug: 'integrations/databases/milvus/milvus-client', + }, + ], + }, { label: 'MongoDB', collapsed: true, diff --git a/src/frontend/src/content/docs/integrations/databases/milvus.mdx b/src/frontend/src/content/docs/integrations/databases/milvus.mdx deleted file mode 100644 index e0143ae7..00000000 --- a/src/frontend/src/content/docs/integrations/databases/milvus.mdx +++ /dev/null @@ -1,287 +0,0 @@ ---- -title: Milvus integration -description: Learn how to use the Milvus integration, which includes both hosting and client integrations. ---- - -import { Aside } from '@astrojs/starlight/components'; -import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; -import { Image } from 'astro:assets'; -import milvusIcon from '@assets/icons/milvus-icon.png'; - -Milvus logo - -[Milvus](https://milvus.io/) 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](https://www.nuget.org/packages/Aspire.Hosting.Milvus) NuGet package in your AppHost project: - - - -### 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: - -```csharp title="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() - .WithReference(milvusdb) - .WaitFor(milvusdb); -``` - - - -The `WithReference` method configures a connection in the `ExampleProject` named `milvusdb`. - - - -### 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: - -```csharp -var apiKey = builder.AddParameter("apiKey", secret: true); - -var milvus = builder.AddMilvus("milvus", apiKey); - -var myService = builder.AddProject() - .WithReference(milvus); -``` - -For more information, see [External parameters](/get-started/resources/). - -### Add a Milvus resource with a data volume - -To add a data volume to the Milvus service resource, call the `WithDataVolume` method: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var milvus = builder.AddMilvus("milvus") - .WithDataVolume(); - -var milvusdb = milvus.AddDatabase("milvusdb"); - -var myService = builder.AddProject() - .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: - -```csharp title="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() - .WithReference(milvusdb) - .WaitFor(milvusdb); -``` - - - -### Create an Attu resource - -[Attu](https://zilliz.com/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: - -```csharp title="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() - .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 | -| -------------- | ------------------------ | -| `DatabaseName` | The Milvus database name | - - - -## Client integration - - - -To get started with the Aspire Milvus client integration, install the [📦 Aspire.Milvus.Client](https://www.nuget.org/packages/Aspire.Milvus.Client) NuGet package in the client-consuming project: - - - -### Add a Milvus client - -In the `Program.cs` file, call the `AddMilvusClient` extension method to register a `MilvusClient`: - -```csharp -builder.AddMilvusClient("milvusdb"); -``` - - - -You can then retrieve the `MilvusClient` instance using dependency injection: - -```csharp -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: - -```csharp -builder.AddKeyedMilvusClient(name: "mainDb"); -builder.AddKeyedMilvusClient(name: "loggingDb"); -``` - -Then retrieve the instances: - -```csharp -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: - -```csharp -builder.AddMilvusClient("milvus"); -``` - -Then the connection string will be retrieved: - -```json -{ - "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`: - -```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: - -```csharp -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. diff --git a/src/frontend/src/content/docs/integrations/databases/milvus/milvus-client.mdx b/src/frontend/src/content/docs/integrations/databases/milvus/milvus-client.mdx new file mode 100644 index 00000000..d47fed96 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/databases/milvus/milvus-client.mdx @@ -0,0 +1,209 @@ +--- +title: Milvus Client integration reference +description: Learn how to use the Aspire Milvus Client integration to interact with Milvus vector databases from your Aspire projects. +next: false +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import milvusIcon from '@assets/icons/milvus-icon.png'; + +Milvus logo + +To get started with the Aspire Milvus integrations, follow the [Get started with Milvus integrations](../milvus-get-started/) guide. + +This article includes full details about the Aspire Milvus Client integration, which allows you to connect to and interact with Milvus vector databases from your Aspire consuming projects. + +## Installation + + + +You need a Milvus server and connection information for accessing the server. To get started with the Aspire Milvus client integration, install the [📦 Aspire.Milvus.Client](https://www.nuget.org/packages/Aspire.Milvus.Client) NuGet package in the client-consuming project, that is, the project for the application that uses the Milvus client. The Milvus client integration registers a `MilvusClient` instance that you can use to interact with Milvus. + + + +## Add Milvus client + +In the `Program.cs` file of your client-consuming project, call the `AddMilvusClient` extension method on any `IHostApplicationBuilder` to register a `MilvusClient` for use via the dependency injection container. The method takes a connection name parameter. + +```csharp title="C# — Program.cs" +builder.AddMilvusClient(connectionName: "milvusdb"); +``` + + + +You can then retrieve the `MilvusClient` instance using dependency injection. For example, to retrieve the connection from an example service: + +```csharp title="C# — ExampleService.cs" +public class ExampleService(MilvusClient client) +{ + // Use the Milvus Client... +} +``` + +For more information on dependency injection, see [.NET dependency injection](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection). + +## Add keyed Milvus client + +There might be situations where you want to register multiple `MilvusClient` instances with different connection strings. To register keyed Milvus clients, call the `AddKeyedMilvusClient` method: + +```csharp title="C# — Program.cs" +builder.AddKeyedMilvusClient(name: "mainDb"); +builder.AddKeyedMilvusClient(name: "loggingDb"); +``` + +Then retrieve the instances using dependency injection: + +```csharp title="C# — ExampleService.cs" +public class ExampleService( + [FromKeyedServices("mainDb")] MilvusClient mainDbClient, + [FromKeyedServices("loggingDb")] MilvusClient loggingDbClient) +{ + // Use clients... +} +``` + +For more information on keyed services, see [.NET dependency injection: Keyed services](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). + +## Properties of the Milvus resources + +When you use the `WithReference` method to pass a Milvus server or database resource from the AppHost project to a consuming client project, several properties are available to 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 `vectordb` becomes `VECTORDB_URI`. + +### 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 inherits all properties from its parent `MilvusServerResource` and adds: + +| Property Name | Description | +| -------------- | ------------------------ | +| `DatabaseName` | The Milvus database name | + + + +## Configuration + +The Aspire Milvus client integration provides multiple configuration approaches and options to meet the requirements and conventions of your project. + +### Use a connection string + +When using a connection string from the `ConnectionStrings` configuration section, you provide the name of the connection string when calling `builder.AddMilvusClient()`: + +```csharp title="C# — Program.cs" +builder.AddMilvusClient("milvus"); +``` + +The connection string is retrieved from the `ConnectionStrings` configuration section: + +```json title="JSON — appsettings.json" +{ + "ConnectionStrings": { + "milvus": "Endpoint=http://localhost:19530/;Key=root:Non-default-P@ssw0rd" + } +} +``` + +For more information about the Milvus connection string format, see the [Milvus documentation](https://milvus.io/). + +### Use configuration providers + +The Aspire Milvus client integration supports `Microsoft.Extensions.Configuration` from configuration files such as `appsettings.json` by using the `Aspire:Milvus:Client` key. If you have set up your configurations in the `Aspire:Milvus:Client` section you can just call the method without passing any parameter. + +The following is an example of an `appsettings.json` that configures some of the available options: + +```json title="JSON — appsettings.json" +{ + "Aspire": { + "Milvus": { + "Client": { + "Endpoint": "http://localhost:19530/", + "Database": "milvusdb", + "Key": "root:Non-default-P@ssw0rd", + "DisableHealthChecks": false + } + } + } +} +``` + +### Use inline delegates + +You can also pass the `Action` delegate to set up some or all the options inline, for example to set the API key from code: + +```csharp title="C# — Program.cs" +builder.AddMilvusClient( + "milvus", + static settings => settings.Key = "root:Non-default-P@ssw0rd"); +``` + +### Configuration options + +Here are the configurable options with corresponding default values: + +| Name | Description | +|--|--| +| `Endpoint` | The endpoint URI of the Milvus server to connect to. | +| `Database` | The name of the Milvus database. | +| `Key` | The authentication key used for authentication (format: `root:{password}`). | +| `DisableHealthChecks` | A boolean value that indicates whether the health check is disabled or not. | + +## Client integration health checks + +By default, Aspire integrations enable [health checks](/fundamentals/health-checks/) for all services. For more information, see [Aspire integrations overview](/integrations/overview/). + +By default, the Aspire Milvus client integration handles the following: + +- Checks if the `MilvusSettings.DisableHealthChecks` is `true`. +- If not disabled, adds a health check that verifies the Milvus server is reachable and a connection can be established. + +## Observability and telemetry + +Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as *the pillars of observability*. 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](#configuration) section. + +### Logging + +The Aspire Milvus client integration uses the following log categories: + +- `Milvus.Client` + +### Tracing and Metrics + +The Milvus integration doesn't currently emit tracing activities or metrics because they are not supported by the `Milvus.Client` library. + +## See also + +- [Milvus](https://milvus.io/) +- [Milvus Documentation](https://milvus.io/docs) +- [Aspire integrations](/integrations/overview/) +- [Aspire GitHub repo](https://github.com/dotnet/aspire) diff --git a/src/frontend/src/content/docs/integrations/databases/milvus/milvus-get-started.mdx b/src/frontend/src/content/docs/integrations/databases/milvus/milvus-get-started.mdx new file mode 100644 index 00000000..c502d540 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/databases/milvus/milvus-get-started.mdx @@ -0,0 +1,290 @@ +--- +title: Get started with the Milvus integrations +description: Learn how to set up the Aspire Milvus Hosting and Client integrations simply. +prev: false +--- + +import { Image } from 'astro:assets'; +import { Kbd } from 'starlight-kbd/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Aside, CardGrid, LinkCard, Code, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; +import PivotSelector from '@components/PivotSelector.astro'; +import Pivot from '@components/Pivot.astro'; +import ThemeImage from '@components/ThemeImage.astro'; +import milvusIcon from '@assets/icons/milvus-icon.png'; + +Milvus logo + +[Milvus](https://milvus.io/) 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. The Aspire Milvus integration enables you to connect to existing Milvus servers or create new servers from Aspire with the [`milvusdb/milvus` container image](https://hub.docker.com/r/milvusdb/milvus). + +In this introduction, you'll see how to install and use the Aspire Milvus integrations in a simple configuration. If you already have this knowledge, see [Milvus Hosting integration](../milvus-host/) for full reference details. + + + +## Set up hosting integration + +To begin, install the Aspire Milvus Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Milvus vector database instances from your Aspire hosting projects: + + + +Next, in the AppHost project, create instances of Milvus server and database resources, then pass the database to the consuming client projects: + + + + + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var milvus = builder.AddMilvus("milvus") + .WithLifetime(ContainerLifetime.Persistent); + +var milvusdb = milvus.AddDatabase("milvusdb"); + +var exampleProject = builder.AddProject("apiservice") + .WaitFor(milvusdb) + .WithReference(milvusdb); +``` + + + + + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var milvus = builder.AddMilvus("milvus") + .WithLifetime(ContainerLifetime.Persistent); + +var milvusdb = milvus.AddDatabase("milvusdb"); + +var exampleProject = builder.AddUvicornApp("api", "./api", "main.app") + .WithExternalHttpEndpoints() + .WaitFor(milvusdb) + .WithReference(milvusdb); +``` + + + + + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var milvus = builder.AddMilvus("milvus") + .WithLifetime(ContainerLifetime.Persistent); + +var milvusdb = milvus.AddDatabase("milvusdb"); + +var api = builder.AddNodeApp("api", "./api", scriptPath: "index.js") + .WithExternalHttpEndpoints() + .WaitFor(milvusdb) + .WithReference(milvusdb); +``` + + + + + +## 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 Milvus client integration: + + + + + +In the `Program.cs` file of your client-consuming project, call the `AddMilvusClient` extension method on any `IHostApplicationBuilder` to register a `MilvusClient` for use via the dependency injection container. The method takes a connection name parameter. + +```csharp title="C# — Program.cs" +builder.AddMilvusClient(connectionName: "milvusdb"); +``` + + + + + + + +To interact with Milvus vector databases in your Python consuming projects, you need to include a Milvus client library. The official option is `pymilvus`, which is Milvus's Python SDK. You can install this library using pip: + +```bash +pip install pymilvus +``` + +Ensure that you import the `MilvusClient` in code files that interact with the vector database. You should also import the `os` module to access environment variables: + +```python title="Python - Import pymilvus" +from pymilvus import MilvusClient, connections +import os +``` + + + + + +To interact with Milvus vector databases in your JavaScript consuming projects, you need to include a Milvus client library. The official option is `@zilliz/milvus2-sdk-node`, which is Milvus's Node.js SDK. You can install this library using npm: + +```bash +npm install @zilliz/milvus2-sdk-node +``` + +Ensure that you import the `MilvusClient` in code files that interact with the vector database: + +```javascript title="JavaScript - Import @zilliz/milvus2-sdk-node" +const { MilvusClient } = require('@zilliz/milvus2-sdk-node'); +``` + + + +### Use injected Milvus properties + +In the AppHost, when you used the `WithReference` method to pass a Milvus database 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 `milvusdb` becomes `MILVUSDB_URI`. + + + +Use the `GetValue()` method to obtain these environment variables in consuming projects: + +```csharp title="C# - Obtain configuration properties" +string connectionUri = builder.Configuration.GetValue("ConnectionStrings__milvusdb"); +string token = builder.Configuration.GetValue("MILVUSDB_TOKEN"); +``` + + + + + +Use the `os.getenv()` method to obtain these environment variables in consuming projects: + +```python title="Python - Obtain configuration properties" +connection_uri = os.getenv("ConnectionStrings__milvusdb") +host = os.getenv("MILVUSDB_HOST") +port = os.getenv("MILVUSDB_PORT") +token = os.getenv("MILVUSDB_TOKEN") +database_name = os.getenv("MILVUSDB_DATABASENAME") +``` + + + + + +Use the `process.env` method to obtain these environment variables in consuming projects: + +```javascript title="JavaScript - Obtain configuration properties" +const connectionUri = process.env.ConnectionStrings__milvusdb; +const host = process.env.MILVUSDB_HOST; +const port = process.env.MILVUSDB_PORT; +const token = process.env.MILVUSDB_TOKEN; +const databaseName = process.env.MILVUSDB_DATABASENAME; +``` + + + + + +### Use Milvus resources in client code + + + +Now that you've added the `MilvusClient` to the builder in the consuming project, you can use the Milvus vector database to store and search vector data. Get the `MilvusClient` 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: + +```csharp title="C# — ExampleService.cs" +public class ExampleService(MilvusClient client) +{ + // Use Milvus client... +} +``` + +Having obtained the client, you can work with the Milvus vector database as you would in any other C# application. + + + + + +Use the information you have obtained about the Milvus resource to connect to the vector database. Here is an example of how to connect using `pymilvus`: + +```python title="Python - Connect to Milvus" +# Create Milvus client +# The token format is "username:password" +client = MilvusClient( + uri=f"http://{host}:{port}", + token=token, + db_name=database_name +) + +# Verify connection +print(f"Connected to Milvus database: {database_name}") +``` + +Having obtained the client, you can work with the Milvus vector database as you would in any other Python application. + + + + + +Use the information you have obtained about the Milvus resource to connect to the vector database. Here is an example of how to connect using `@zilliz/milvus2-sdk-node`: + +```javascript title="JavaScript - Connect to Milvus" +// Create Milvus client +const client = new MilvusClient({ + address: `${host}:${port}`, + token: token, + database: databaseName +}); + +// Verify connection +console.log(`Connected to Milvus database: ${databaseName}`); +``` + +Having obtained the client, you can work with the Milvus vector database as you would in any other JavaScript application. + + + +## Next steps + +Now, that you have an Aspire app with Milvus integrations up and running, you can use the following reference documents to learn how to configure and interact with the Milvus resources: + + + + + diff --git a/src/frontend/src/content/docs/integrations/databases/milvus/milvus-host.mdx b/src/frontend/src/content/docs/integrations/databases/milvus/milvus-host.mdx new file mode 100644 index 00000000..23883541 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/databases/milvus/milvus-host.mdx @@ -0,0 +1,223 @@ +--- +title: Milvus Hosting integration reference +description: Learn how to use the Aspire Milvus Hosting integration to orchestrate and configure Milvus vector databases in your Aspire projects. +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import { Image } from 'astro:assets'; +import milvusIcon from '@assets/icons/milvus-icon.png'; + +Milvus logo + +To get started with the Aspire Milvus integrations, follow the [Get started with Milvus integrations](../milvus-get-started/) guide. + +This article includes full details about the Aspire Milvus Hosting integration, which models Milvus server and database resources as the `MilvusServerResource` and `MilvusDatabaseResource` types. To access these types and APIs, you need to install the Milvus Hosting integration in your AppHost project. + +## Installation + +The Aspire Milvus hosting integration models the Milvus vector database server as the following types: + +- `MilvusServerResource` +- `MilvusDatabaseResource` + +To access these types and APIs for expressing them as resources in your AppHost project, install the [📦 Aspire.Hosting.Milvus](https://www.nuget.org/packages/Aspire.Hosting.Milvus) NuGet package: + + + +## Add Milvus server and database resources + +In the AppHost project, call `AddMilvus` to add and return a Milvus server resource builder. Chain a call to the returned resource builder to `AddDatabase`, to add a Milvus database to the server resource: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var milvus = builder.AddMilvus("milvus") + .WithLifetime(ContainerLifetime.Persistent); + +var milvusdb = milvus.AddDatabase("milvusdb"); + +builder.AddProject() + .WithReference(milvusdb) + .WaitFor(milvusdb); + +// After adding all resources, run the app... +``` + + + +When Aspire adds a container image to the AppHost, as shown in the preceding example with the `milvusdb/milvus` image, it creates a new Milvus server on your local machine. A reference to your Milvus resource builder (the `milvus` variable) is used to add a database. The database is named `milvusdb` and then added to the `ExampleProject`. + +The `WithReference` method configures a connection in the `ExampleProject` named `"milvusdb"`. For more information, see [Container resource lifecycle](/architecture/resource-model/#built-in-resources-and-lifecycle). + + + +## Add Milvus resource with API key parameter + +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: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var apiKey = builder.AddParameter("apiKey", secret: true); + +var milvus = builder.AddMilvus("milvus", apiKey) + .WithLifetime(ContainerLifetime.Persistent); + +var milvusdb = milvus.AddDatabase("milvusdb"); + +var myService = builder.AddProject() + .WithReference(milvusdb) + .WaitFor(milvusdb); +``` + +The preceding code gets a parameter to pass to the `AddMilvus` API, and internally assigns the parameter to the Milvus container configuration. The `apiKey` parameter is usually specified as a user secret: + +```json title="JSON — secrets.json" +{ + "Parameters": { + "apiKey": "your-secure-password" + } +} +``` + +For more information, see [External parameters](/get-started/resources/). + +## Add Milvus resource with data volume + +To add a data volume to the Milvus resource, call the `WithDataVolume` method: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var milvus = builder.AddMilvus("milvus") + .WithDataVolume() + .WithLifetime(ContainerLifetime.Persistent); + +var milvusdb = milvus.AddDatabase("milvusdb"); + +builder.AddProject() + .WithReference(milvusdb) + .WaitFor(milvusdb); + +// After adding all resources, run the app... +``` + +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 in the Milvus 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](#add-milvus-resource-with-data-bind-mount), see [Docker docs: Volumes](https://docs.docker.com/engine/storage/volumes). + +## Add Milvus resource with data bind mount + +To add a data bind mount to the Milvus resource, call the `WithDataBindMount` method: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var milvus = builder.AddMilvus("milvus") + .WithDataBindMount(source: @"C:\Milvus\Data") + .WithLifetime(ContainerLifetime.Persistent); + +var milvusdb = milvus.AddDatabase("milvusdb"); + +builder.AddProject() + .WithReference(milvusdb) + .WaitFor(milvusdb); + +// After adding all resources, run the app... +``` + + + +## Create an Attu resource + +[Attu](https://zilliz.com/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: + +```csharp title="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() + .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. + +## Using with non-.NET applications + +When you use the `WithReference` method to pass a Milvus database 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 Milvus database resource named `milvusdb`: + +```csharp title="C# — AppHost.cs" +var milvus = builder.AddMilvus("milvus"); +var milvusdb = milvus.AddDatabase("milvusdb"); + +var pythonApp = builder.AddUvicornApp("api", "./api", "main.app") + .WithReference(milvusdb); +``` + +The following environment variables are available in the Python application: + +- `ConnectionStrings__milvusdb` - The connection string for the Milvus database +- `MILVUSDB_HOST` - The hostname of the Milvus server +- `MILVUSDB_PORT` - The gRPC port number +- `MILVUSDB_TOKEN` - The authentication token (format: `root:{password}`) +- `MILVUSDB_URI` - The gRPC connection URI +- `MILVUSDB_DATABASENAME` - The database name + +You can access these environment variables in your application code: + +```python title="Python example" +from pymilvus import MilvusClient +import os + +# Get connection properties +host = os.getenv("MILVUSDB_HOST") +port = os.getenv("MILVUSDB_PORT") +token = os.getenv("MILVUSDB_TOKEN") +database_name = os.getenv("MILVUSDB_DATABASENAME") + +# Create Milvus client +client = MilvusClient( + uri=f"http://{host}:{port}", + token=token, + db_name=database_name +) +``` + +```javascript title="JavaScript example" +const { MilvusClient } = require('@zilliz/milvus2-sdk-node'); + +// Get connection properties +const host = process.env.MILVUSDB_HOST; +const port = process.env.MILVUSDB_PORT; +const token = process.env.MILVUSDB_TOKEN; +const databaseName = process.env.MILVUSDB_DATABASENAME; + +// Create Milvus client +const client = new MilvusClient({ + address: `${host}:${port}`, + token: token, + database: databaseName +}); +``` diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 6d8473c8..5f4d7b1a 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -185,7 +185,7 @@ }, { "match": "Aspire.Hosting.Milvus", - "href": "/integrations/databases/milvus/" + "href": "/integrations/databases/milvus/milvus-get-started/" }, { "match": "Aspire.Hosting.MongoDB", @@ -281,7 +281,7 @@ }, { "match": "Aspire.Milvus.Client", - "href": "/integrations/databases/milvus/" + "href": "/integrations/databases/milvus/milvus-get-started/" }, { "match": "Aspire.MongoDB.Driver",