Skip to content

Chroma

Chroma is an open-source vector database for AI applications. It stores embeddings with their documents and metadata, and finds the nearest ones to a query, through a REST API.

Add the following dependency to your project file:

NuGet
1
dotnet add package Testcontainers.Chroma

You can start a Chroma container instance from any .NET application. This example uses xUnit.net's IAsyncLifetime interface to manage the lifecycle of the container. The container is started in the InitializeAsync method before the test method runs, ensuring that the environment is ready for testing. After the test completes, the container is removed in the DisposeAsync method.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
private readonly ChromaContainer _chromaContainer = new ChromaBuilder(TestSession.GetImageFromDockerfile()).Build();

public async ValueTask InitializeAsync()
{
    await _chromaContainer.StartAsync()
        .ConfigureAwait(false);
}

public ValueTask DisposeAsync()
{
    return _chromaContainer.DisposeAsync();
}

[Fact]
[Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]
public async Task QueryReturnsNearestRecord()
{
    // Given
    using var client = new ChromaClient(_chromaContainer.GetConnectionString());

    var collection = await client.CreateCollectionAsync("documents", cancellationToken: TestContext.Current.CancellationToken)
        .ConfigureAwait(true);

    var collectionClient = client.GetCollectionClient(collection);

    await collectionClient.AddAsync(["a", "b"], [new[] { 1f, 0f }, new[] { 0f, 1f }], cancellationToken: TestContext.Current.CancellationToken)
        .ConfigureAwait(true);

    // When
    var results = await collectionClient.QueryAsync(new[] { 0.9f, 0.1f }, nResults: 1, cancellationToken: TestContext.Current.CancellationToken)
        .ConfigureAwait(true);

    // Then
    Assert.Equal("a", Assert.Single(results).Id);
}

The test example uses the following NuGet dependencies:

1
2
3
4
5
<PackageReference Include="Microsoft.NET.Test.Sdk"/>
<PackageReference Include="coverlet.collector"/>
<PackageReference Include="xunit.runner.visualstudio"/>
<PackageReference Include="xunit.v3"/>
<PackageReference Include="ChromaDotNet.Client"/>

To execute the tests, use the command dotnet test from a terminal.

Tip

For the complete source code of this example and additional information, please refer to our test projects.

Chroma versions

The container is ready when the heartbeat of the Chroma API answers. Chroma 0.5.16 and later answer the heartbeat of the v2 API, and the earlier releases have only the v1 API, so the module asks both: it works with any Chroma image, whatever its tag.