Chroma

  • 配置 ChromaVectorStore，包括设置 OpenAI API 密钥。

  • 将必要的依赖项添加到项目中。

  • 使用示例代码创建文档、将其添加到向量存储并检索与查询相似的文档。

  • 利用通用和可移植的元数据过滤器。

  • 在本地运行 ChromaDB。

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

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

What is Chroma?

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. OpenAI Account: Create an account at OpenAI Signup and generate the token at API Keys.

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

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

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

Configuration

要设置 ChromaVectorStore，你需要提供你的 OpenAI API 密钥。可以像这样将其设置为环境变量：

To set up ChromaVectorStore, you’ll need to provide your OpenAI API Key. Set it as an environment variable like so:

export SPRING_AI_OPENAI_API_KEY='Your_OpenAI_API_Key'

Dependencies

将这些依赖项添加到你的项目中：

Add these dependencies to your project:

  • OpenAI: Required for calculating embeddings.

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

  • Chroma VectorStore.

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-chroma-store</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 授权配置创建一个 RestTemplate 实例，然后使用它创建一个 ChromaApi 实例：

Create a RestTemplate instance with proper ChromaDB authorization configurations and Use it to create a ChromaApi instance:

@Bean
public RestTemplate restTemplate() {
   return new RestTemplate();
}

@Bean
public ChromaApi chromaApi(RestTemplate restTemplate) {
   String chromaUrl = "http://localhost:8000";
   ChromaApi chromaApi = new ChromaApi(chromaUrl, restTemplate);
   return chromaApi;
}

对于使用 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.

通过将 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(EmbeddingClient embeddingClient, ChromaApi chromaApi) {
 return new ChromaVectorStore(embeddingClient, chromaApi, "TestCollection");
}

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

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!!".

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.defaults()
                            .withQuery("The World")
                            .withTopK(TOP_K)
                            .withSimilarityThreshold(SIMILARITY_THRESHOLD)
                            .withFilterExpression("author in ['john', 'jill'] && article_type == 'blog'"));

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

or programmatically using the Filter.Expression DSL:

FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.similaritySearch(SearchRequest.defaults()
                    .withQuery("The World")
                    .withTopK(TOP_K)
                    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
                    .withFilterExpression(b.and(
                            b.in("john", "jill"),
                            b.eq("article_type", "blog")).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"}}]
}

Run Chroma Locally

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

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

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