跳到主要内容

Pinecone

Deepseek 3.2 中英对照 Pinecone

本节将指导您设置Pinecone VectorStore，用于存储文档嵌入并执行相似性搜索。

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

前提条件​

  1. Pinecone 账户：在开始之前，请注册一个 Pinecone 账户。

  2. Pinecone 项目：注册后，生成一个 API 密钥并创建一个索引。配置时需要这些详细信息。

  3. EmbeddingModel 实例用于计算文档嵌入向量。有几种可选方案：

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

要设置 PineconeVectorStore，请从你的 Pinecone 账户中收集以下详细信息：

  • Pinecone API 密钥

  • Pinecone 索引名称

  • Pinecone 命名空间

备注

这些信息可在 Pinecone UI 门户中查看。命名空间功能在 Pinecone 免费版中不可用。

自动配置​

备注

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

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'
}

:::提示
请参考 依赖管理 部分，将 Spring AI BOM 添加到你的构建文件中。
:::

:::提示
请参考 Artifact 存储库 部分，将 Maven Central 和/或 Snapshot 存储库添加到你的构建文件中。
:::

此外，你需要一个配置好的 EmbeddingModel bean。更多信息请参考 EmbeddingModel 章节。

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

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

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

spring.ai.vectorstore.pinecone.apiKey=<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-keyPinecone API 密钥-
spring.ai.vectorstore.pinecone.index-namePinecone 索引名称-
spring.ai.vectorstore.pinecone.namespacePinecone 命名空间-
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-timeout20 秒

元数据过滤​

你可以利用通用的、可移植的元数据过滤器与 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());
备注

这些过滤表达式会被转换为等效的 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>

:::提示
请参考依赖管理章节，将 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) // the free tier doesn't support namespaces.
            .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.query("Spring").topK(5).build());

如果一切顺利，你应该能取回包含文本 "Spring AI rocks!!" 的文档。

访问原生客户端​

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

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

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

原生客户端为您提供了通过 VectorStore 接口可能无法访问的 Pinecone 特定功能和操作。