Pinecone

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

Pinecone 是一个流行的云端向量数据库，让你能高效地存储并搜索向量。

前置条件

1. Pinecone 账户：开始之前，注册一个 Pinecone 账户。
2. Pinecone 项目：注册后，生成一个 API 密钥并创建一个索引。你会在配置中需要这些详情。
3. 用于计算文档嵌入的 EmbeddingModel 实例。有多个可选方案：

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

要设置 PineconeVectorStore，请从你的 Pinecone 账户收集以下详情：

• Pinecone API 密钥
• Pinecone 索引名
• Pinecone 命名空间

NOTE

这些信息你都可以在 Pinecone UI 门户中获得。 所有当前的 Pinecone 套餐（包括免费的 Starter 套餐）都支持命名空间；每个无服务器索引中命名空间的最大数量取决于你的套餐。

自动配置

NOTE

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

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

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

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

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

TIP

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

TIP

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

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

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

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

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

spring.ai.vectorstore.pinecone.api-key=<your api key>
spring.ai.vectorstore.pinecone.index-name=<your index name>

# API key if needed, e.g. OpenAI
spring.ai.openai.api.key=<api-key>

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

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

@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 配置中使用以下属性来定制 Pinecone 向量库。

属性
描述
默认值
spring.ai.vectorstore.pinecone.api-key
Pinecone API 密钥
-
spring.ai.vectorstore.pinecone.index-name
Pinecone 索引名
-
spring.ai.vectorstore.pinecone.namespace
Pinecone 命名空间
-
spring.ai.vectorstore.pinecone.content-field-name
用于存储原始文本内容的 Pinecone 元数据字段名。
document_content
spring.ai.vectorstore.pinecone.distance-metadata-field-name
用于存储所计算距离的 Pinecone 元数据字段名。
distance
spring.ai.vectorstore.pinecone.server-side-timeout
20 sec.

元数据过滤

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

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

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

NOTE

这些过滤表达式会被转换为等价的 Pinecone 过滤器。

手动配置

如果你更喜欢手动配置 PineconeVectorStore，可以通过 PineconeVectorStore#Builder 来做。

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

• OpenAI：计算嵌入所必需。

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

• Pinecone

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

TIP

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

示例代码

要在你的应用中配置 Pinecone，可以使用以下设置：

@Bean
public VectorStore pineconeVectorStore(EmbeddingModel embeddingModel) {
    return PineconeVectorStore.builder(embeddingModel)
            .apiKey(PINECONE_API_KEY)
            .indexName(PINECONE_INDEX_NAME)
            .namespace(PINECONE_NAMESPACE)
            .contentFieldName(CUSTOM_CONTENT_FIELD_NAME) // optional field to store the original content. Defaults to `document_content`
            .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")));

把文档添加到 Pinecone：

vectorStore.add(documents);

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

List<Document> results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());

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

访问原生客户端

Pinecone 向量库实现通过 getNativeClient() 方法提供对底层原生 Pinecone 客户端（Pinecone）的访问：

PineconeVectorStore vectorStore = context.getBean(PineconeVectorStore.class);
Optional<Pinecone> nativeClient = vectorStore.getNativeClient();

if (nativeClient.isPresent()) {
    Pinecone client = nativeClient.get();
    // Use the native client for Pinecone-specific operations
}

原生客户端让你得以访问那些可能未通过 VectorStore 接口暴露的 Pinecone 特定功能与操作。