Chroma

本节将指导您设置 Chroma VectorStore 以存储文档嵌入并执行相似性搜索。

This section will walk you through setting up the Chroma VectorStore to store document embeddings and perform similarity searches.

Chroma 是开源嵌入数据库。它为您提供了存储文档嵌入、内容和元数据以及搜索这些嵌入（包括元数据过滤）的工具。

Chroma is the open-source embedding database. It gives you the tools to store document embeddings, content, and metadata and to search through those embeddings, including metadata filtering.

Prerequisites

  1. 访问 ChromeDB。 setup local ChromaDB 附录展示了如何使用 Docker 容器在本地设置数据库。

  2. Access to ChromeDB. The _run_chroma_locally appendix shows how to set up a DB locally with a Docker container.

  3. 以下是使用Gemini将这段文本翻译成中文的结果：实例来计算文档嵌入。有几个选项可供选择：

    • 如果需要， EmbeddingModel 的 API 密钥用于生成由 ChromaVectorStore 存储的嵌入。

    • If required, an API key for the EmbeddingModel to generate the embeddings stored by the ChromaVectorStore.

  1. EmbeddingModel instance to compute the document embeddings. Several options are available:

    • 如果需要， EmbeddingModel 的 API 密钥用于生成由 ChromaVectorStore 存储的嵌入。

    • If required, an API key for the EmbeddingModel to generate the embeddings stored by the ChromaVectorStore.

在启动时，ChromaVectorStore 会在尚未配置的情况下创建必要的集合。

On startup, the ChromaVectorStore creates the required collection if one is not provisioned already.

Auto-configuration

Spring AI 自动配置、启动器模块的工件名称发生了重大变化。请参阅 upgrade notes 以获取更多信息。

There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the upgrade notes for more information.

Spring AI 为 Chroma 向量存储提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到您的项目的 Maven pom.xml 文件中：

Spring AI provides Spring Boot auto-configuration for the Chroma Vector Store. To enable it, add the following dependency to your project’s Maven pom.xml file:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-chroma</artifactId>
</dependency>

或添加到 Gradle build.gradle 构建文件中。

or to your Gradle build.gradle build file.

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-chroma'
}

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

Refer to the Dependency Management section to add the Spring AI BOM to your build file.

将Maven Central和/或Snapshot存储库添加到您的构建文件中，请参阅 Artifact Repositories 部分。

Refer to the Artifact Repositories section to add Maven Central and/or Snapshot Repositories to your build file.

向量存储实现可以为你初始化所需模式，但你必须通过在适当的构造函数中指定 @s15 布尔值或在 @s17 文件中设置 @s16 来选择加入。

The vector store implementation can initialize the requisite schema for you, but you must opt-in by specifying the initializeSchema boolean in the appropriate constructor or by setting …​initialize-schema=true in the application.properties file.

这是一个重大更改！在早期版本的Spring AI中，此架构初始化是默认发生的。

this is a breaking change! In earlier versions of Spring AI, this schema initialization happened by default.

此外，您还需要一个配置好的 EmbeddingModel bean。有关更多信息，请参阅 EmbeddingModel 部分。

Additionally, you will need a configured EmbeddingModel bean. Refer to the EmbeddingModel section for more information.

以下是所需 bean 的示例：

Here is an example of the needed bean:

@Bean
public EmbeddingModel embeddingModel() {
    // Can be any other EmbeddingModel implementation.
    return new OpenAiEmbeddingModel(OpenAiApi.builder().apiKey(System.getenv("OPENAI_API_KEY")).build());
}

要连接到 Chroma，您需要提供实例的访问详细信息。可以通过 Spring Boot 的 application.properties 提供简单的配置，

To connect to Chroma you need to provide access details for your instance. A simple configuration can either be provided via Spring Boot’s application.properties,

# Chroma Vector Store connection properties
spring.ai.vectorstore.chroma.client.host=<your Chroma instance host>
spring.ai.vectorstore.chroma.client.port=<your Chroma instance port>
spring.ai.vectorstore.chroma.client.key-token=<your access token (if configure)>
spring.ai.vectorstore.chroma.client.username=<your username (if configure)>
spring.ai.vectorstore.chroma.client.password=<your password (if configure)>

# Chroma Vector Store collection properties
spring.ai.vectorstore.chroma.initialize-schema=<true or false>
spring.ai.vectorstore.chroma.collection-name=<your collection name>

# Chroma Vector Store configuration properties

# OpenAI API key if the OpenAI auto-configuration is used.
spring.ai.openai.api.key=<OpenAI Api-key>

请查看矢量存储的 configuration parameters 列表，了解默认值和配置选项。

Please have a look at the list of _configuration_properties for the vector store to learn about the default values and configuration options.

现在您可以在应用程序中自动装配 Chroma 向量存储并使用它

Now you can auto-wire the Chroma Vector Store in your application and use it

@Autowired VectorStore vectorStore;

// ...

List <Document> documents = List.of(
    new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
    new Document("The World is Big and Salvation Lurks Around the Corner"),
    new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));

// Add the documents
vectorStore.add(documents);

// Retrieve documents similar to a query
List<Document> results = this.vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());

Configuration properties

您可以使用 Spring Boot 配置中的以下属性来自定义向量存储。

You can use the following properties in your Spring Boot configuration to customize the vector store.

Property Description Default value

spring.ai.vectorstore.chroma.client.host

Server connection host

http://localhost

spring.ai.vectorstore.chroma.client.port

Server connection port

8000

spring.ai.vectorstore.chroma.client.key-token

Access token (if configured)

-

spring.ai.vectorstore.chroma.client.username

Access username (if configured)

-

spring.ai.vectorstore.chroma.client.password

Access password (if configured)

-

spring.ai.vectorstore.chroma.collection-name

Collection name

SpringAiCollection

spring.ai.vectorstore.chroma.initialize-schema

Whether to initialize the required schema

false

对于使用 Static API Token Authentication 保护的 ChromaDB，使用 ChromaApi#withKeyToken(<Your Token Credentials>) 方法设置您的凭据。查看 ChromaWhereIT 以获取示例。

For ChromaDB secured with Static API Token Authentication use the ChromaApi#withKeyToken(<Your Token Credentials>) method to set your credentials. Check the ChromaWhereIT for an example.

对于使用 Basic Authentication 保护的 ChromaDB，使用 ChromaApi#withBasicAuth(<your user>, <your password>) 方法设置您的凭据。查看 BasicAuthChromaWhereIT 以获取示例。

For ChromaDB secured with Basic Authentication use the ChromaApi#withBasicAuth(<your user>, <your password>) method to set your credentials. Check the BasicAuthChromaWhereIT for an example.

Metadata filtering

您也可以将通用便携式 metadata filters 与 ChromaVector 存储一起使用。

You can leverage the generic, portable metadata filters with ChromaVector store as well.

例如，你可以使用文本表达式语言：

For example, you can use either the text expression language:

vectorStore.similaritySearch(
                    SearchRequest.builder()
                            .query("The World")
                            .topK(TOP_K)
                            .similarityThreshold(SIMILARITY_THRESHOLD)
                            .filterExpression("author in ['john', 'jill'] && article_type == 'blog'").build());

或使用 Filter.Expression DSL 以编程方式：

or programmatically using the Filter.Expression DSL:

FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.similaritySearch(SearchRequest.builder()
                    .query("The World")
                    .topK(TOP_K)
                    .similarityThreshold(SIMILARITY_THRESHOLD)
                    .filterExpression(b.and(
                            b.in("john", "jill"),
                            b.eq("article_type", "blog")).build()).build());

这些（可移植）筛选表达式将自动转换为专有 Chroma where filter expressions。

Those (portable) filter expressions get automatically converted into the proprietary Chroma where filter expressions.

例如，此可移植的筛选器表达式：

For example, this portable filter expression:

author in ['john', 'jill'] && article_type == 'blog'

转换为专有 Chroma 格式

is converted into the proprietary Chroma format

{"$and":[
	{"author": {"$in": ["john", "jill"]}},
	{"article_type":{"$eq":"blog"}}]
}

Manual Configuration

如果您更喜欢手动配置 Chroma 向量存储，可以通过在 Spring Boot 应用程序中创建 ChromaVectorStore bean 来实现。

If you prefer to configure the Chroma Vector Store manually, you can do so by creating a ChromaVectorStore bean in your Spring Boot application.

将以下依赖项添加到您的项目中：* Chroma 向量存储。

Add these dependencies to your project: * Chroma VectorStore.

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-chroma-store</artifactId>
</dependency>

  • OpenAI：计算嵌入所需。您可以使用任何其他嵌入模型实现。

  • OpenAI: Required for calculating embeddings. You can use any other embedding model implementation.

<dependency>
 <groupId>org.springframework.ai</groupId>
 <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

Refer to the Dependency Management section to add the Spring AI BOM to your build file.

Sample Code

使用正确的 ChromaDB 授权配置创建一个 RestClient.Builder 实例，并使用它创建一个 ChromaApi 实例：

Create a RestClient.Builder instance with proper ChromaDB authorization configurations and Use it to create a ChromaApi instance:

@Bean
public RestClient.Builder builder() {
    return RestClient.builder().requestFactory(new SimpleClientHttpRequestFactory());
}


@Bean
public ChromaApi chromaApi(RestClient.Builder restClientBuilder) {
   String chromaUrl = "http://localhost:8000";
   ChromaApi chromaApi = new ChromaApi(chromaUrl, restClientBuilder);
   return chromaApi;
}

通过将 Spring Boot OpenAI 启动器添加到你的项目中，与 OpenAI 的嵌入集成。这为你提供了嵌入客户端的实现：

Integrate with OpenAI’s embeddings by adding the Spring Boot OpenAI starter to your project. This provides you with an implementation of the Embeddings client:

@Bean
public VectorStore chromaVectorStore(EmbeddingModel embeddingModel, ChromaApi chromaApi) {
 return ChromaVectorStore.builder(chromaApi, embeddingModel)
    .collectionName("TestCollection")
    .initializeSchema(true)
    .build();
}

在你的主代码中，创建一些文档：

In your main code, create some documents:

List<Document> documents = List.of(
 new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
 new Document("The World is Big and Salvation Lurks Around the Corner"),
 new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));

将文档添加到你的向量存储：

Add the documents to your vector store:

vectorStore.add(documents);

最后，检索与查询类似的文档：

And finally, retrieve documents similar to a query:

List<Document> results = vectorStore.similaritySearch("Spring");

如果一切都顺利，你应该检索包含文本 “Spring AI rocks!!” 的文档。

If all goes well, you should retrieve the document containing the text "Spring AI rocks!!".

Run Chroma Locally

docker run -it --rm --name chroma -p 8000:8000 ghcr.io/chroma-core/chroma:1.0.0

使用 [role="bare"][role="bare"]http://localhost:8000/api/v1 启动一个 Chroma 存储。

Starts a chroma store at [role="bare"]http://localhost:8000/api/v1