Chroma

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

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

前提条件

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

  2. EmbeddingModel 实例用于计算文档嵌入。有多种选项可用

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

启动时，如果 ChromaVectorStore 所需的集合尚未提供，它将创建该集合。

自动配置

Spring AI 自动配置、starter 模块的 artifact 名称发生了重大变化。更多信息请参考升级说明。

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

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

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

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-chroma'
}
请参阅依赖管理部分，了解如何将 Spring AI BOM 添加到您的构建文件中。
请参阅仓库部分，了解如何将 Maven Central 和/或 Snapshot Repositories 添加到您的构建文件中。

向量存储实现可以为您初始化所需的 schema，但您必须通过在相应的构造函数中指定 initializeSchema 布尔值或在 application.properties 文件中设置 …​initialize-schema=true 来选择启用此功能。

这是破坏性变更！在早期版本的 Spring AI 中，此 schema 初始化是默认发生的。

此外，您还需要一个已配置的 EmbeddingModel bean。更多信息请参考EmbeddingModel部分。

这里是所需 bean 的示例

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

要连接到 Chroma，您需要提供实例的访问详细信息。可以通过 Spring Boot 的 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>

请查看向量存储的配置参数列表，了解默认值和配置选项。

现在您可以在应用程序中自动装配（auto-wire）Chroma Vector Store 并使用它

@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());

配置属性

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

属性 描述 默认值

spring.ai.vectorstore.chroma.client.host

服务器连接主机

http://localhost

spring.ai.vectorstore.chroma.client.port

服务器连接端口

8000

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

访问令牌（如果已配置）

-

spring.ai.vectorstore.chroma.client.username

访问用户名（如果已配置）

-

spring.ai.vectorstore.chroma.client.password

访问密码（如果已配置）

-

spring.ai.vectorstore.chroma.collection-name

集合名称

SpringAiCollection

spring.ai.vectorstore.chroma.initialize-schema

是否初始化所需的 schema

false

对于使用静态 API Token 认证进行安全加固的 ChromaDB，使用 ChromaApi#withKeyToken(<Your Token Credentials>) 方法设置您的凭据。请查看 ChromaWhereIT 获取示例。

对于使用基本认证进行安全加固的 ChromaDB，使用 ChromaApi#withBasicAuth(<your user>, <your password>) 方法设置您的凭据。请查看 BasicAuthChromaWhereIT 获取示例。

元数据过滤

您也可以在 ChromaVector store 中利用通用、可移植的元数据过滤器。

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

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

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 过滤表达式。

例如，这个可移植的过滤表达式

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

被转换为专有的 Chroma 格式

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

手动配置

如果您更喜欢手动配置 Chroma Vector Store，可以在您的 Spring Boot 应用程序中创建一个 ChromaVectorStore bean。

将这些依赖项添加到您的项目中：* Chroma VectorStore。

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

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

<dependency>
 <groupId>org.springframework.ai</groupId>
 <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
请参阅依赖管理部分，了解如何将 Spring AI BOM 添加到您的构建文件中。

示例代码

创建一个带有适当 ChromaDB 授权配置的 RestClient.Builder 实例，并使用它来创建一个 ChromaApi 实例

@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 starter 添加到您的项目中，与 OpenAI 的嵌入集成。这为您提供了一个 Embeddings 客户端的实现。

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

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

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")));

将文档添加到您的向量存储中

vectorStore.add(documents);

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

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

如果一切顺利，您应该会检索到包含文本 "Spring AI rocks!!" 的文档。

在本地运行 Chroma

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

在 localhost:8000/api/v1 启动 Chroma store