此版本仍在开发中，尚未被视为稳定版。如需最新的快照版本，请使用 Spring AI 1.1.3！spring-doc.cadn.net.cn

Chroma

本节将引导您设置 Chroma VectorStore 以存储文档嵌入并执行相似性搜索。spring-doc.cadn.net.cn

Chroma 是开源的嵌入数据库。它为您提供存储文档嵌入、内容和元数据的工具，并支持通过这些嵌入进行搜索，包括元数据过滤。spring-doc.cadn.net.cn

前置条件

  1. 访问 ChromaDB。兼容 Chroma Cloud，或附录中的 本地设置 ChromaDB 展示了如何使用 Docker 容器在本地设置数据库。spring-doc.cadn.net.cn

    • 对于 Chroma Cloud：您需要从 Chroma Cloud 控制台获取您的 API 密钥、租户名称和数据库名称。spring-doc.cadn.net.cn

    • 对于本地 ChromaDB：除了启动容器外，无需额外配置。spring-doc.cadn.net.cn

  2. EmbeddingModel 实例用于计算文档嵌入。有几种选项可供选择：spring-doc.cadn.net.cn

在启动时，如果尚未提供所需的集合，ChromaVectorStore 将创建该集合。spring-doc.cadn.net.cn

Auto-configuration

Spring AI自动配置和starter模块的artifact名称有了重大变化。 请参阅升级说明获取更多信息。spring-doc.cadn.net.cn

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

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

请将以下内容添加到您的Gradle build.gradle 构建文件中。spring-doc.cadn.net.cn

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

向量存储实现可以为您初始化所需的架构，但您必须通过在适当的构造函数中指定 initializeSchema 布尔值或在 application.properties 文件中设置 …​initialize-schema=true 来选择加入。spring-doc.cadn.net.cn

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

此外，您还需要一个已配置的 EmbeddingModel bean。有关更多信息，请参阅 EmbeddingModel 部分。spring-doc.cadn.net.cn

这是所需 bean 的示例：spring-doc.cadn.net.cn

@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 提供简单的配置，spring-doc.cadn.net.cn

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

请查看 向量存储的配置参数 列表，以了解默认值和配置选项。spring-doc.cadn.net.cn

现在您可以在您的应用程序中自动装配 Chroma 向量存储并使用它spring-doc.cadn.net.cn

@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-doc.cadn.net.cn

<property> </property> <description> </description> 默认值

spring.ai.vectorstore.chroma.client.hostspring-doc.cadn.net.cn

服务器连接主机spring-doc.cadn.net.cn

http://localhostspring-doc.cadn.net.cn

spring.ai.vectorstore.chroma.client.portspring-doc.cadn.net.cn

服务器连接端口spring-doc.cadn.net.cn

8000spring-doc.cadn.net.cn

spring.ai.vectorstore.chroma.client.key-tokenspring-doc.cadn.net.cn

访问Tokens（如果已配置）spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.vectorstore.chroma.client.usernamespring-doc.cadn.net.cn

访问用户名（如果已配置）spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.vectorstore.chroma.client.passwordspring-doc.cadn.net.cn

访问密码（如果已配置）spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.vectorstore.chroma.tenant-namespring-doc.cadn.net.cn

租户（Chroma Cloud 必需）spring-doc.cadn.net.cn

SpringAiTenantspring-doc.cadn.net.cn

spring.ai.vectorstore.chroma.database-namespring-doc.cadn.net.cn

数据库名称（Chroma Cloud 必需）spring-doc.cadn.net.cn

SpringAiDatabasespring-doc.cadn.net.cn

spring.ai.vectorstore.chroma.collection-namespring-doc.cadn.net.cn

集合名称spring-doc.cadn.net.cn

SpringAiCollectionspring-doc.cadn.net.cn

spring.ai.vectorstore.chroma.initialize-schemaspring-doc.cadn.net.cn

是否初始化所需的模式（如果租户/数据库/集合不存在，则创建它们）spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

对于使用 静态 API Tokens身份验证 的 ChromaDB，请使用 ChromaApi#withKeyToken(<Your Token Credentials>) 方法设置您的凭据。查看 ChromaWhereIT 以获取示例。spring-doc.cadn.net.cn

对于使用 基本身份验证 保护的 ChromaDB，请使用 ChromaApi#withBasicAuth(<your user>, <your password>) 方法设置您的凭据。请查看 BasicAuthChromaWhereIT 以获取示例。spring-doc.cadn.net.cn

Chroma 云配置

对于 Chroma Cloud，你需要从你的 Chroma Cloud 实例中提供租户和数据库名称。这是一个示例配置：spring-doc.cadn.net.cn

# 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

对于 Chroma Cloud： - 主机应为 api.trychroma.com - 端口应为 443 (HTTPS) - 您必须通过 key-token 提供您的 API 密钥 - 租户和数据库名称必须与您的 Chroma Cloud 配置匹配 - 设置 initialize-schema=true 以在集合不存在时自动创建（不会重新创建现有的租户/数据库）spring-doc.cadn.net.cn

元数据过滤

您也可以在 ChromaVector 存储中利用通用、可移植的 元数据过滤器。spring-doc.cadn.net.cn

例如，您可以使用文本表达式语言：spring-doc.cadn.net.cn

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：spring-doc.cadn.net.cn

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

例如，此可移植的过滤器表达式：spring-doc.cadn.net.cn

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

被转换为专有的 Chroma 格式spring-doc.cadn.net.cn

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

手动配置

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

将以下依赖项添加到您的项目中： * Chroma VectorStore。spring-doc.cadn.net.cn

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

示例代码

创建一个具有适当 ChromaDB 授权配置的 RestClient.Builder 实例，并使用它来创建一个 ChromaApi 实例：spring-doc.cadn.net.cn

@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 的嵌入功能。这为您提供了嵌入客户端的实现：spring-doc.cadn.net.cn

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

在您的主代码中，创建一些文档：spring-doc.cadn.net.cn

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

将文档添加到您的向量存储中：spring-doc.cadn.net.cn

vectorStore.add(documents);

最后，检索与查询相似的文档：spring-doc.cadn.net.cn

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

如果一切顺利，您应该能检索到包含文本"Spring AI rocks!!"的文档。spring-doc.cadn.net.cn

本地运行 Chroma

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

在 localhost:8000/api/v1 启动一个 chroma storespring-doc.cadn.net.cn