Chroma

本节引导你设置 Chroma VectorStore 以存储文档嵌入并执行相似度搜索。

Chroma 是一个开源的嵌入数据库。它提供工具让你存储文档的嵌入、内容和元数据，并在这些嵌入上进行搜索，包括元数据过滤。

前置条件

可访问的 ChromaDB。兼容 Chroma Cloud，或在附录中演示如何用 Docker 容器在本地搭建 ChromaDB。

对于 Chroma Cloud：你需要从 Chroma Cloud 控制面板获取 API 密钥、租户名和数据库名。
对于本地 ChromaDB：除了启动容器外无需额外配置。

用于计算文档嵌入的 EmbeddingModel 实例。有多个可选方案：

如有需要，为 EmbeddingModel 配置一个 API 密钥，以生成 ChromaVectorStore 所存储的嵌入。

启动时，若尚未提供所需的集合，ChromaVectorStore 会创建它。

自动配置

NOTE

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

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

xml

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

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

groovy

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

TIP

参见依赖管理一节，把 Spring AI BOM 添加到你的构建文件。

TIP

参见制品仓库一节，把 Maven Central 和/或 Snapshot 仓库添加到你的构建文件。

向量库实现可以为你初始化所需的模式，但你必须显式开启——在相应的构造器中指定 initializeSchema 布尔值，或在 application.properties 文件中设置 ...initialize-schema=true。

NOTE

这是一处破坏性变更！在较早的 Spring AI 版本中，此模式初始化默认进行。

此外，你还需要一个已配置的 EmbeddingModel bean。更多信息参见 EmbeddingModel 一节。

以下是所需 bean 的一个示例：

java

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

要连接到 Chroma，你需要提供实例的访问详情。一个简单的配置可以通过 Spring Boot 的 application.properties 提供，

properties

# Chroma Vector Store connection properties
spring.ai.vectorstore.chroma.client.host=<your Chroma instance host>  // for Chroma Cloud: api.trychroma.com
spring.ai.vectorstore.chroma.client.port=<your Chroma instance port> // for Chroma Cloud: 443
spring.ai.vectorstore.chroma.client.key-token=<your access token (if configure)> // for Chroma Cloud: use the API key
spring.ai.vectorstore.chroma.client.username=<your username (if configure)>
spring.ai.vectorstore.chroma.client.password=<your password (if configure)>

# Chroma Vector Store tenant and database properties (required for Chroma Cloud)
spring.ai.vectorstore.chroma.tenant-name=<your tenant name> // default: SpringAiTenant
spring.ai.vectorstore.chroma.database-name=<your database name> // default: SpringAiDatabase

# 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>

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

现在你可以在应用中自动装配并使用 Chroma 向量库

java

@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.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`
是否初始化所需的模式（若不存在则创建租户/数据库/集合）
`false`

NOTE

对于使用静态 API 令牌认证保护的 ChromaDB，使用 ChromaApi#withKeyToken(<Your Token Credentials>) 方法来设置你的凭据。可参见 ChromaWhereIT 的示例。

对于使用基本认证保护的 ChromaDB，使用 ChromaApi#withBasicAuth(<your user>, <your password>) 方法来设置你的凭据。可参见 BasicAuthChromaWhereIT 的示例。

Chroma Cloud 配置

对于 Chroma Cloud，你需要提供来自你 Chroma Cloud 实例的租户名和数据库名。这里是一个配置示例：

properties

# Chroma Cloud connection
spring.ai.vectorstore.chroma.client.host=api.trychroma.com
spring.ai.vectorstore.chroma.client.port=443
spring.ai.vectorstore.chroma.client.key-token=<your-chroma-cloud-api-key>

# Chroma Cloud tenant and database (required)
spring.ai.vectorstore.chroma.tenant-name=<your-tenant-id>
spring.ai.vectorstore.chroma.database-name=<your-database-name>

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

NOTE

对于 Chroma Cloud：

主机应为 api.trychroma.com
端口应为 443（HTTPS）
你必须通过 key-token 提供你的 API 密钥
租户名和数据库名必须与你的 Chroma Cloud 配置匹配
设置 initialize-schema=true 以在集合不存在时自动创建它（它不会重建已存在的租户/数据库）

元数据过滤

你也可以在 Chroma 向量库上利用通用、可移植的元数据过滤器。

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

java

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：

java

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

NOTE

这些（可移植的）过滤表达式会被自动转换为 Chroma 专有的 where 过滤表达式。

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

sql

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

会被转换为 Chroma 专有的格式

json

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

手动配置

如果你更喜欢手动配置 Chroma 向量库，可以在 Spring Boot 应用中创建一个 ChromaVectorStore bean 来做。

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

Chroma VectorStore。

xml

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

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

xml

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

TIP

参见依赖管理一节，把 Spring AI BOM 添加到你的构建文件。

示例代码

创建一个带恰当 ChromaDB 授权配置的 RestClient.Builder 实例，并用它创建一个 ChromaApi 实例：

java

@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 客户端的实现：

java

@Bean
public VectorStore chromaVectorStore(EmbeddingModel embeddingModel, ChromaApi chromaApi) {
 return ChromaVectorStore.builder(chromaApi, embeddingModel)
    .tenantName("your-tenant-name") // default: SpringAiTenant
    .databaseName("your-database-name") // default: SpringAiDatabase
    .collectionName("TestCollection")
    .initializeSchema(true)
    .build();
}

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

java

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

把文档添加到你的向量库：

java

vectorStore.add(documents);

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

java

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

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

在本地运行 Chroma

shell

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

启动一个位于 http://localhost:8000/api/v1 的 chroma 存储

Chat Client API

顾问（Advisor）API

结构化输出

模型

聊天模型 API

嵌入模型 API

Amazon Bedrock

VertexAI

图像模型 API

音频模型

转录 API

文本转语音（TTS）API

审核模型

工具调用

Model Context Protocol (MCP)

MCP 服务端 Boot Starter

MCP 注解

检索增强生成

向量数据库

Chroma

前置条件

自动配置

配置属性

Chroma Cloud 配置

元数据过滤

手动配置

示例代码

在本地运行 Chroma

友情链接