Using the Chroma connector (Preview)

Overview

The Chroma Vector Store connector can be used to access and manage data in Chroma and Chroma Cloud. The connector is provided by the .NET Community Toolkit and is built on the ChromaDotNet.Client library. The connector has the following characteristics.

Limitations

Notable Chroma connector functionality limitations.

Getting started

Add the Chroma Vector Store connector NuGet package to your project.

dotnet add package CommunityToolkit.VectorData.Chroma --prerelease

You can add the vector store to the dependency injection container available on the KernelBuilder or to the IServiceCollection dependency injection container using extension methods provided by the connector package. The connection string is either the URI of the Chroma server, or Endpoint=...;Token=...;Tenant=...;Database=... (for example, for Chroma Cloud).

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel
    .CreateBuilder();
kernelBuilder.Services
    .AddChromaVectorStore("http://localhost:8000");

using Microsoft.Extensions.DependencyInjection;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddChromaVectorStore("http://localhost:8000");

Extension methods that take no parameters are also provided. These require an instance of the ChromaDB.Client.ChromaClient class to be separately registered with the dependency injection container.

using ChromaDB.Client;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<ChromaClient>(sp =>
    new ChromaClient(new ChromaConfigurationOptions("http://localhost:8000")));
kernelBuilder.Services.AddChromaVectorStore();

using ChromaDB.Client;
using Microsoft.Extensions.DependencyInjection;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<ChromaClient>(sp =>
    new ChromaClient(new ChromaConfigurationOptions("http://localhost:8000")));
builder.Services.AddChromaVectorStore();

You can construct a Chroma Vector Store instance directly.

using ChromaDB.Client;
using CommunityToolkit.VectorData.Chroma;

var vectorStore = new ChromaVectorStore(
    new ChromaClient(new ChromaConfigurationOptions("http://localhost:8000")),
    ownsClient: true);

It is possible to construct a direct reference to a named collection.

using ChromaDB.Client;
using CommunityToolkit.VectorData.Chroma;

var collection = new ChromaCollection<string, Hotel>(
    new ChromaClient(new ChromaConfigurationOptions("http://localhost:8000")),
    "skhotels",
    ownsClient: true);

Data mapping

The Chroma connector provides a default mapper when mapping data from the data model to storage. Chroma stores each record as an id, an embedding, optional metadata and an optional document. The default mapper uses the model annotations or record definition to determine the type of each property and to do this mapping.

• The data model property annotated as a key will be mapped to the Chroma record id.
• The data model properties annotated as data will be mapped to the Chroma record metadata. If exactly one string data property has IsFullTextIndexed set, it is also stored as the Chroma record document.
• The data model property annotated as a vector will be mapped to the Chroma record embedding.

Property name override

For data properties, you can provide override field names to use in storage that are different to the property names on the data model. This is not supported for keys and vectors, since they have fixed names in Chroma.

The property name override is done by setting the StorageName option via the data model attributes or record definition.

Here is an example of a data model with StorageName set on its attributes and how that will be represented in Chroma.

using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreKey]
    public string HotelId { get; set; }

    [VectorStoreData(IsIndexed = true, StorageName = "hotel_name")]
    public string HotelName { get; set; }

    [VectorStoreData(IsFullTextIndexed = true, StorageName = "hotel_description")]
    public string Description { get; set; }

    [VectorStoreVector(4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

{
    "id": "1",
    "metadata": { "hotel_name": "Hotel Happy", "hotel_description": "A place where everyone can be happy." },
    "document": "A place where everyone can be happy.",
    "embedding": [0.9, 0.1, 0.1, 0.1]
}

Overview

The Chroma Vector Store connector can be used to access and manage data in Chroma. The connector has the following characteristics.

Limitations

Notable Chroma connector functionality limitations.

Getting Started

Add the Chroma Vector Store connector dependencies to your project.

pip install semantic-kernel[chroma]

You can then create the vector store.

from semantic_kernel.connectors.chroma import ChromaStore

store = ChromaStore()

Alternatively, you can also pass in your own mongodb client if you want to have more control over the client construction:

from chromadb import Client
from semantic_kernel.connectors.chroma import ChromaStore

client = Client(...)
store = ChromaStore(client=client)

You can also create a collection directly, without the store.

from semantic_kernel.connectors.chroma import ChromaCollection

# `hotel` is a class created with the @vectorstoremodel decorator
collection = ChromaCollection(
    record_type=hotel,
    collection_name="my_collection",
)

Serialization

The Chroma client returns both get and search results in tabular form, this means that there are between 3 and 5 lists being returned in a dict, the lists are 'keys', 'documents', 'embeddings', and optionally 'metadatas' and 'distances'. The Semantic Kernel Chroma connector will automatically convert this into a list of dict objects, which are then parsed back to your data model.

It could be very interesting performance wise to do straight serialization from this format into a dataframe-like structure as that saves a lot of rebuilding of the data structure. This is not done for you, even when using container mode, you would have to specify this yourself, for more details on this concept see the serialization documentation.

Not supported

Not supported.