Chroma

本节将引导你设置 Chroma 向量数据库，用于存储文档向量（embeddings）并执行相似性搜索。

Chroma 是一个开源的向量嵌入数据库。它提供了存储文档向量、内容和元数据的工具，并支持通过这些向量进行搜索，包括元数据过滤功能。

前提条件

访问 ChromaDB。它兼容 Chroma Cloud，也可以在附录中查看如何使用 Docker 容器在本地搭建 ChromaDB。
- 对于 Chroma Cloud：你需要从 Chroma Cloud 控制面板获取 API Key、租户名（tenant name）和数据库名。
- 对于本地 ChromaDB：除了启动容器外，无需额外配置。
需要一个 EmbeddingModel 实例来计算文档的向量嵌入（embeddings），有多种选项可供选择：
- 如果需要，还需为 EmbeddingModel 提供 API Key，用于生成存储在 ChromaVectorStore 中的向量嵌入。

启动时，如果 ChromaVectorStore 中尚未创建所需的 collection，它会自动创建。

自动配置

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

Spring AI 为 Chroma 向量存储提供了 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 添加到你的构建文件中。

请参考 artifact 仓库部分，将 Maven Central 和/或 Snapshot 仓库添加到构建文件中。

向量存储实现可以为你初始化所需的 schema，但你必须显式选择启用，通过在相应构造函数中指定 initializeSchema 布尔值，或在 application.properties 文件中设置：

spring.ai.vectorstore.chroma.initialize-schema=true

这是一个破坏性变更！在早期版本的 Spring AI 中，这个 schema 初始化是默认启用的。

此外，你需要配置一个 EmbeddingModel Bean，具体信息请参考 EmbeddingModel 章节。示例如下：

@Bean
public EmbeddingModel embeddingModel() {
    // 可以使用任何其他 EmbeddingModel 实现
    return new OpenAiEmbeddingModel(
        OpenAiApi.builder()
                 .apiKey(System.getenv("OPENAI_API_KEY"))
                 .build()
    );
}

要连接 Chroma，你需要提供实例的访问信息。可以通过 Spring Boot 的 application.properties 进行简单配置：

# Chroma Vector Store 连接属性
spring.ai.vectorstore.chroma.client.host=<你的 Chroma 实例 host>      # Chroma Cloud: api.trychroma.com
spring.ai.vectorstore.chroma.client.port=<你的 Chroma 实例端口>       # Chroma Cloud: 443
spring.ai.vectorstore.chroma.client.key-token=<访问令牌，如果有配置>   # Chroma Cloud: 使用 API Key
spring.ai.vectorstore.chroma.client.username=<用户名，如果有配置>
spring.ai.vectorstore.chroma.client.password=<密码，如果有配置>

# Chroma Vector Store 租户和数据库属性（Chroma Cloud 必需）
spring.ai.vectorstore.chroma.tenant-name=<租户名>       # 默认: SpringAiTenant
spring.ai.vectorstore.chroma.database-name=<数据库名>   # 默认: SpringAiDatabase

# Chroma Vector Store collection 属性
spring.ai.vectorstore.chroma.initialize-schema=<true 或 false>
spring.ai.vectorstore.chroma.collection-name=<你的 collection 名称>

# Chroma Vector Store 配置属性

# 如果使用 OpenAI 自动配置，需要提供 OpenAI API Key
spring.ai.openai.api.key=<OpenAI API Key>

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

现在，你可以在应用中自动注入 Chroma Vector Store 并使用它：

@Autowired
VectorStore vectorStore;

// ...

List<Document> documents = List.of(
    new Document("Spring AI 很棒！！Spring AI 很棒！！Spring AI 很棒！！", Map.of("meta1", "meta1")),
    new Document("世界很大，救赎就在拐角处"),
    new Document("你向前走面向过去，同时回望未来", Map.of("meta2", "meta2"))
);

// 添加文档
vectorStore.add(documents);

// 根据查询检索相似文档
List<Document> results = 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.tenant-name`	租户（Chroma Cloud 必需）	`SpringAiTenant`
`spring.ai.vectorstore.chroma.database-name`	数据库名（Chroma Cloud 必需）	`SpringAiDatabase`
`spring.ai.vectorstore.chroma.collection-name`	集合名	`SpringAiCollection`
`spring.ai.vectorstore.chroma.initialize-schema`	是否初始化所需的 schema（如果不存在则创建租户/数据库/集合）	`false`

对于使用静态 API Token 认证保护的 ChromaDB，可使用 ChromaApi#withKeyToken(<你的 Token 凭证>) 方法设置凭证。示例请参考 ChromaWhereIT。对于使用基本认证保护的 ChromaDB，可使用 ChromaApi#withBasicAuth(<用户名>, <密码>) 方法设置凭证。示例请参考 BasicAuthChromaWhereIT。

Chroma 云配置

对于 Chroma Cloud，你需要提供 Chroma Cloud 实例中的租户名和数据库名。以下是示例配置：

# Chroma Cloud 连接
spring.ai.vectorstore.chroma.client.host=api.trychroma.com
spring.ai.vectorstore.chroma.client.port=443
spring.ai.vectorstore.chroma.client.key-token=<你的 Chroma Cloud API Key>

# Chroma Cloud 租户和数据库（必填）
spring.ai.vectorstore.chroma.tenant-name=<你的租户 ID>
spring.ai.vectorstore.chroma.database-name=<你的数据库名称>

# Collection 配置
spring.ai.vectorstore.chroma.collection-name=my-collection
spring.ai.vectorstore.chroma.initialize-schema=true

Chroma Cloud 注意事项：

host 应为 api.trychroma.com
端口应为 443（HTTPS）
必须通过 key-token 提供你的 API Key
租户名和数据库名必须与 Chroma Cloud 配置一致
将 initialize-schema=true 可在集合不存在时自动创建集合（不会重新创建已存在的租户或数据库）

元数据过滤

你也可以在 ChromaVectorStore 中使用通用、可移植的元数据过滤器。

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

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("author", "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 向量存储（Chroma Vector Store），可以在 Spring Boot 应用中创建一个 ChromaVectorStore Bean。

首先，将以下依赖添加到你的项目中：

Chroma VectorStore

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

OpenAI（用于计算向量嵌入，可替换为其他 EmbeddingModel 实现）

<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)
    .tenantName("your-tenant-name")       // 默认: SpringAiTenant
    .databaseName("your-database-name")   // 默认: SpringAiDatabase
    .collectionName("TestCollection")
    .initializeSchema(true)
    .build();
}

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

List<Document> documents = List.of(
 new Document("Spring AI 很棒！！Spring AI 很棒！！Spring AI 很棒！！Spring AI 很棒！！Spring AI 很棒！！", Map.of("meta1", "meta1")),
 new Document("世界很大，救赎就在拐角处"),
 new Document("你向前走面向过去，同时回望未来", Map.of("meta2", "meta2"))
);

将文档添加到向量存储：

vectorStore.add(documents);

最后，根据查询检索相似文档：

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

如果配置正确，你将检索到包含文本 "Spring AI 很棒！！" 的文档。

本地运行 Chroma

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

这将在 localhost:8000/api/v1 启动一个 Chroma 存储实例。

Apache Cassandra Vector Store

Couchbase