开始使用 LangChain4j 集成

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

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

   • 名称：LangChain4jSampleApp

   • 语言： Java

   • 构建系统： Maven

   • JDK：任何大于 8

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

添加依赖项。

1. 将以下依赖项添加到项目的 pom.xml文件的 dependencies大量中。这些依赖项将 LangChain4j、适用于 LangChain4j 的 Voyage AI API和MongoDB Java同步驱动程序库添加到您的应用程序：

   pom.xml

   <dependency>
       <groupId>dev.langchain4j</groupId>
       <artifactId>langchain4j-mongodb-atlas</artifactId>
       <version>1.0.0-beta1</version>
   </dependency>
   <dependency>
       <groupId>dev.langchain4j</groupId>
       <artifactId>langchain4j-voyage-ai</artifactId>
       <version>1.0.0-beta1</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.0.0-beta1</version>
               <type>pom</type>
               <scope>import</scope>
           </dependency>
       </dependencies>
   </dependencyManagement>

   要学习；了解有关 LangChain4 j BOM 的详情，请参阅 LangChain4 j 文档中的入门页面。

   完成编辑 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：设置为Atlas连接字符串。

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

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

检索环境变量。

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

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

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

为 RAG 设置项目。

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

   pom.xml

   <dependency>
       <groupId>dev.langchain4j</groupId>
       <artifactId>langchain4j-open-ai</artifactId>
       <version>1.0.0-beta1</version>
   </dependency>
   <dependency>
       <groupId>dev.langchain4j</groupId>
       <artifactId>langchain4j</artifactId>
       <version>1.0.0-beta1</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-examplesGitHub存储库下载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 Services API 。创建一个名为 Assistant.java 的接口文件，其级别与 Main.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.