开始使用 LangChain4j 集成

创建一个新的 Java 应用程序。

1. 打开您的 IDE 并创建一个新的 Java 项目，设置以下配置：

   • 名称：LangChain4jSampleApp

   • 语言： Java

   • 构建系统： Maven

   • JDK：任何版本大于 8

   您可能会看到一个选项来包含示例代码。选择此选项可能有助于您测试环境是否正常运行，并定位您在以下步骤中编辑的应用程序文件。

添加依赖项。

1. 将以下依赖项添加到项目的 pom.xml 文件中的 dependencies 数组中。这些依赖项将 LangChain4j、Voyage AI API for LangChain4j 和 MongoDB Java Sync Driver 库添加到您的应用程序中：

   pom.xml

   <dependency>
       <groupId>dev.langchain4j</groupId>
       <artifactId>langchain4j-mongodb-atlas</artifactId>
       <version>1.1.0</version>
   </dependency>
   <dependency>
       <groupId>dev.langchain4j</groupId>
       <artifactId>langchain4j-voyage-ai</artifactId>
       <version>1.1.0-beta7</version>
   </dependency>
   <dependency>
       <groupId>org.mongodb</groupId>
       <artifactId>mongodb-driver-sync</artifactId>
       <version>5.4.0</version>
   </dependency>

2. 下一步，在您的依赖项列表下方为 LangChain4j 物料清单（BOM）添加一个 dependencyManagement 条目：

   pom.xml

   <dependencyManagement>
       <dependencies>
           <dependency>
               <groupId>dev.langchain4j</groupId>
               <artifactId>langchain4j-bom</artifactId>
               <version>1.1.0</version>
               <type>pom</type>
               <scope>import</scope>
           </dependency>
       </dependencies>
   </dependencyManagement>

   如要了解有关 LangChain4j BOM 的更多信息，请参阅 LangChain4j 文档中的入门 页面。

   完成编辑 pom.xml 文件后，请重新加载项目以确保依赖项已安装。

导入类和方法。

在您的项目中找到主应用程序文件 Main.java。用以下导入列表替换任何现有导入：

import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import dev.langchain4j.data.document.Metadata;
import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.model.voyageai.VoyageAiEmbeddingModel;
import dev.langchain4j.store.embedding.EmbeddingMatch;
import dev.langchain4j.store.embedding.EmbeddingSearchRequest;
import dev.langchain4j.store.embedding.EmbeddingSearchResult;
import dev.langchain4j.store.embedding.filter.comparison.*;
import dev.langchain4j.store.embedding.mongodb.IndexMapping;
import dev.langchain4j.store.embedding.mongodb.MongoDbEmbeddingStore;
import org.bson.Document;
import java.io.*;
import java.util.*;

在本教程的后面，您将使用这些类和方法来创建向量嵌入和查询数据。

设置环境变量。

根据您的 IDE，可能有多种方法来设置应用程序可以检索的环境变量。如要在 IntelliJ 中设置环境变量，您必须为应用程序创建一个运行配置。如要了解更多信息，请参阅 IntelliJ 文档中运行/调试配置：应用程序页面的操作系统部分。

设置以下环境变量：

• MONGODB_URI：设置为MongoDB连接字符串。

• VOYAGE_AI_KEY：设置为您的 Voyage AI API 密钥。

mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.net/?<settings>

检索环境变量。

通过在应用程序的 Main.java 文件的 main 方法中添加以下代码来检索环境变量：

String embeddingApiKey = System.getenv("VOYAGE_AI_KEY");
String uri = System.getenv("MONGODB_URI");

执行语义搜索。

此代码对短语 "Where do penguins live?" 执行语义搜索查询，并返回三个最相关的结果。它还会打印一个分数，以显示每个结果与查询的匹配程度。

将以下代码添加到您的 Main.java 文件中：

String query = "Where do penguins live?";
Embedding queryEmbedding = embeddingModel.embed(query).content();
EmbeddingSearchRequest searchRequest = EmbeddingSearchRequest.builder()
        .queryEmbedding(queryEmbedding)
        .maxResults(3)
        .build();
System.out.println("Performing the query...");
EmbeddingSearchResult<TextSegment> searchResult = embeddingStore.search(searchRequest);
List<EmbeddingMatch<TextSegment>> matches = searchResult.matches();
for (EmbeddingMatch<TextSegment> embeddingMatch : matches) {
    System.out.println("Response: " + embeddingMatch.embedded().text());
    System.out.println("Author: " + embeddingMatch.embedded().metadata().getString("author"));
    System.out.println("Score: " + embeddingMatch.score());
}

Response: Penguins are flightless seabirds that live almost exclusively below the equator. Some island-dwellers can be found in warmer climates.
Author: C
Score: 0.829620897769928
Response: Patagonia is home to five penguin species - Magellanic, Humboldt, Gentoo, Southern Rockhopper and King.
Author: B
Score: 0.7459062337875366
Response: Emperor penguins are the tallest and heaviest of all penguin species, standing up to 4 feet.
Author: D
Score: 0.6908764839172363

（可选）使用元数据过滤执行语义搜索。

如要执行带有元数据过滤的搜索，您可以使用 dev.langchain4j.store.embedding.filter.comparison 包中的类。这些类允许您创建过滤器，将元数据值与指定值进行比较，以缩小搜索返回的结果。

此示例可过滤 author 字段的值为 "B" 或 "C" 的文档。然后，它对短语 "Where do penguins live?" 执行语义搜索查询。

将上一步中实例化 EmbeddingSearchRequest 实例的代码替换为以下代码：

EmbeddingSearchRequest searchRequest = EmbeddingSearchRequest.builder()
        .queryEmbedding(queryEmbedding)
        .filter(new IsIn("author", List.of("B", "C")))
        .maxResults(3)
        .build();

Response: Penguins are flightless seabirds that live almost exclusively below the equator. Some island-dwellers can be found in warmer climates.
Author: C
Score: 0.8520907163619995
Response: Patagonia is home to five penguin species - Magellanic, Humboldt, Gentoo, Southern Rockhopper and King.
Author: B
Score: 0.7666836977005005

要学习；了解有关元数据预过滤的更多信息，请参阅MongoDB Vector Search 预过滤。

为 RAG 设置您的项目。

1. 将以下依赖项添加到项目的 pom.xml 文件的 dependencies 数组中，但不要删除任何您已添加的依赖项。这些依赖项将 LangChain4j AI 服务和适用于 LangChain4j 库的 OpenAI API 添加到应用程序中：

   pom.xml

   <dependency>
       <groupId>dev.langchain4j</groupId>
       <artifactId>langchain4j-open-ai</artifactId>
       <version>1.1.0</version>
   </dependency>
   <dependency>
       <groupId>dev.langchain4j</groupId>
       <artifactId>langchain4j</artifactId>
       <version>1.1.0</version>
   </dependency>

   完成编辑 pom.xml 文件后，请重新加载项目以确保依赖项已安装。

2. 将以下导入添加到 Main.java 文件中的导入列表中：

   import com.fasterxml.jackson.core.type.TypeReference;
   import com.fasterxml.jackson.databind.ObjectMapper;
   import dev.langchain4j.service.AiServices;
   import dev.langchain4j.model.chat.ChatLanguageModel;
   import dev.langchain4j.model.openai.OpenAiChatModel;
   import dev.langchain4j.rag.content.retriever.ContentRetriever;
   import dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever;

3. 将 OPENAI_KEY 环境变量设置为您的 OpenAI API 密钥。您使用此密钥创建一个聊天模型，以生成对您的查询的响应。

加载示例数据。

在此步骤中，您会将外部来源的数据摄取到 Atlas 中。从 docs-code-examples GitHub 存储库下载 rainforest-docs.json 样本数据文件。此文件中的文档包含有关雨林中动植物和天气信息。

将此文件上传到项目中的 resources 目录，该目录与包含您应用程序文件的 java 目录处于同一级别。

您必须将数据处理为可用的格式，以便可以从中创建嵌入并持久化到Atlas。此代码定义了执行以下操作的 loadJsonDocuments() 方法：

• 使用 ClassLoader 类从您的 resources 目录中检索样本数据。

• 使用 ObjectMapper 类将 JSON 文档解析为 MongoDB Document 实例的 List。

将以下代码添加到主方法之外的 Main.java 文件中：

private static List<Document> loadJsonDocuments(String resourcePath) throws IOException {
    // Loads file from resources directory using the ClassLoader
    InputStream inputStream = Main.class.getClassLoader().getResourceAsStream(resourcePath);
    if (inputStream == null) {
        throw new FileNotFoundException("Resource not found: " + resourcePath);
    }
    // Parses JSON file to List of MongoDB Documents
    ObjectMapper objectMapper = new ObjectMapper();
    List<Document> documents = objectMapper.readValue(inputStream, new TypeReference<>() {});
    return documents;
}

然后，在主方法体中添加以下代码以调用 loadJsonDocuments() 方法并加载您的文档：

System.out.println("Loading documents from file...");
String resourcePath = "rainforest-docs.json";
List<Document> documents = loadJsonDocuments(resourcePath);

在 Atlas 中存储向量嵌入。

在此步骤中，您将从示例文档创建向量嵌入，并将其持久化到 Atlas。

此代码将示例文档中 text 字段的内容转换为嵌入，并将数据持久化到 Atlas。该代码包含一个延迟，以适应向量转换所需的时间。

将以下代码添加到您的 Main.java 文件中：

System.out.println("Persisting document embeddings...");
for (Document doc : documents) {
    TextSegment segment = TextSegment.from(
            doc.getString("text"),
            new Metadata(doc.get("metadata", Map.class)));
    Embedding embedding = embeddingModel.embed(segment).content();
    embeddingStore.add(embedding, segment);
}
try {
    Thread.sleep(5000);
} catch (InterruptedException e) {
    throw new RuntimeException(e);
}

实例化聊天模型并指定内容检索器。

在此步骤中，您将从 OpenAI 实例化一个聊天模型，以便能够根据您的数据回答问题。您还可以指定一个内容检索器，以便显示相关文档，从而为聊天模型生成的响应提供信息。

此代码执行以下操作：

• 通过使用您的 OpenAI API 密钥实例化聊天模型

• 创建具有以下规格的内容检索器：

  • 最多检索 3 个相关文档

  • 检索文档，相关性分数至少为 0.75

将以下代码添加到主方法正文的 Main.java 文件中：

String chatApiKey = System.getenv("OPENAI_KEY");
ChatLanguageModel chatModel = OpenAiChatModel.builder()
        .apiKey(chatApiKey)
        .modelName("gpt-4")
        .build();
ContentRetriever contentRetriever = EmbeddingStoreContentRetriever.builder()
        .embeddingStore(embeddingStore)
        .embeddingModel(embeddingModel)
        .maxResults(3)
        .minScore(0.75)
        .build();

创建聊天助手。

创建一个简单的 Assistant 接口，以在您的应用程序中实现 AI 服务 API。在与 Main.java 文件相同的级别上创建一个名为 Assistant.java 的接口文件。

定义 Assistant 接口：

package org.example;
public interface Assistant {
    String answer(String question);
}

在您的 Main.java 文件中，实例化 Assistant：

Assistant assistant = AiServices.builder(Assistant.class)
        .chatLanguageModel(chatModel)
        .contentRetriever(contentRetriever)
        .build();

对您的数据执行查询。

最后，执行对示例数据的查询。将以下代码添加到 Main.java 文件中以运行查询并打印输出：

String ragQuery = "What types of insects live in the rainforest?";
String output = assistant.answer(ragQuery);
System.out.println("Response:\n" + output);

Response:
In the rainforest, there are numerous species of insects
such as beetles, butterflies, moths, wasps, bees, flies, and
ants. Of the many insects that live in the rainforest, ants
are particularly important as they play a crucial role in
nutrient recycling and aeration of the soil. Moreover, many
of these insects are involved in the processes of
pollination and decomposition. The adaptations these insects
have developed enable their survival in the rainforest's
specific conditions, characterized by heavy rainfall.