Skip to main content

LangChain4j 学习路径测试代码库

版权归属于 LangChat Team
官网:https://langchat.cn

项目介绍

这是一个独立的 Java 项目,用于存放 LangChain4j 学习路径中所有文档涉及的测试代码和示例,让开发人员能够快速运行和测试 LangChain4j 的各种功能。

项目定位

  • 可运行性 - 所有代码都是完整的 Maven 项目,可以直接运行
  • 测试覆盖 - 每个学习文档都有对应的测试代码
  • 配置统一 - 使用 .env 文件统一管理配置
  • 快速上手 - 开发人员可以快速克隆并运行测试
  • 模块化设计 - 每个学习主题对应独立的测试模块

快速开始

前置要求

  • JDK 17+
  • Maven 3.9+

⚠️ 配置 API Key

在运行测试之前,必须先配置 API Key。本项目使用 .env 文件管理配置。

步骤 1:复制配置文件

# 从模板复制配置文件
cp .env.example .env

步骤 2:编辑 .env 文件

# API 配置
LANGCHAT_API_KEY=your-api-key-here
LANGCHAT_BASE_URL=https://api.openai.com/v1

# 模型配置
LANGCHAT_MODEL_NAME=gpt-4o-mini
LANGCHAT_EMBEDDING_MODEL_NAME=text-embedding-ada-002

# 模型参数
LANGCHAT_TEMPERATURE=0.7
LANGCHAT_MAX_TOKENS=1000

配置优先级

配置按以下优先级加载(从高到低):
  1. 系统环境变量(最高优先级)
  2. .env.local 文件
  3. .env 文件
  4. 默认值(最低优先级)

使用系统环境变量

# Mac/Linux
export LANGCHAT_API_KEY="your-api-key"
export LANGCHAT_BASE_URL="https://api.openai.com/v1"

# Windows CMD
set LANGCHAT_API_KEY=your-api-key
set LANGCHAT_BASE_URL=https://api.openai.com/v1

# Windows PowerShell
$env:LANGCHAT_API_KEY="your-api-key"
$env:LANGCHAT_BASE_URL="https://api.openai.com/v1"

运行测试

# 编译项目
mvn clean compile

# 运行所有测试
mvn test

# 运行特定测试类
mvn test -Dtest=LangChain4jBasicTest

# 运行特定测试方法
mvn test -Dtest=LangChain4jBasicTest#shouldGenerateSimpleResponse

运行示例

在 IntelliJ IDEA 中直接运行示例类的 main 方法,例如:
  • src/test/java/cn/langchat/learning/tutorial/introduction/HelloWorldExample.java

打印配置信息

# 查看当前配置(已遮盖敏感信息)
mvn test -Dtest=PrintConfigTest

项目结构

langchain4j-learning/
├── .env                      # 环境配置文件(已忽略)
├── .env.example              # 环境配置模板
├── .env.local               # 本地覆盖配置(已忽略)
├── .gitignore               # Git 忽略配置
├── pom.xml                 # Maven 配置文件
├── README.md               # 项目说明文档(本文件)

├── docs/                   # 学习文档
│   ├── 01-introduction-to-langchain4j.md
│   ├── 02-your-first-chat-application.md
│   └── ... (40 篇文档)

├── src/
│   ├── main/
│   │   └── java/
│   │       └── cn/langchat/learning/
│   │           └── LearningTestsApplication.java    # 主应用类
│   │
│   └── test/
│       └── java/
│           └── cn/langchat/learning/
│               ├── util/                   # 工具类
│               │   ├── EnvConfig.java    # 配置加载器
│               │   └── TestModelProvider.java  # 模型提供者
│               │
│               └── tutorial/              # 教程测试包
│                   ├── introduction/      # 01 - 简介
│                   │   ├── HelloWorldExample.java
│                   │   ├── LangChain4jBasicTest.java
│                   │   └── VersionTest.java
│                   ├── firstchat/        # 02 - 第一个聊天应用
│                   ├── chatmodel/        # 03 - ChatModel 深入
│                   ├── embedding/        # 07 - Embedding 模型
│                   ├── embeddingstore/  # 08 - 向量存储
│                   ├── rag/             # 10 - RAG
│                   ├── aiservices/      # 11 - AI Services
│                   └── ... (其他主题)

技术栈

核心框架

技术版本用途
Java17开发语言
Maven3.9+构建工具
JUnit Jupiter5.10.0测试库
Lombok1.18.24简化代码

LangChain4j 依赖

依赖版本说明
langchain4j1.10.0核心框架
langchain4j-open-ai-OpenAI 集成

可选依赖

依赖版本说明
SLF4J2.0.9日志框架

配置说明

环境变量配置

支持以下配置项(通过 .env 文件或系统环境变量):
配置项说明默认值
LANGCHAT_API_KEYAPI Key必需
LANGCHAT_BASE_URLAPI 地址https://api.openai.com/v1
LANGCHAT_MODEL_NAME模型名称gpt-4o-mini
LANGCHAT_EMBEDDING_MODEL_NAME嵌入模型名称text-embedding-ada-002
LANGCHAT_TEMPERATURE温度参数0.7
LANGCHAT_MAX_TOKENS最大 Token 数1000

配置加载顺序

  1. 系统环境变量 - 优先级最高,用于 CI/CD 或特殊场景
  2. .env.local - 本地开发时覆盖 .env 配置
  3. .env - 默认配置文件
  4. 默认值 - 代码中的默认值

安全性

  • .env.env.local 已在 .gitignore
  • ✅ API Key 等敏感信息不会提交到版本控制
  • ✅ 日志输出自动遮盖敏感信息
  • ✅ 支持通过系统环境变量覆盖配置

测试覆盖

文档编号文档主题测试包测试文件
01Introductionintroduction/HelloWorldExample, LangChain4jBasicTest, VersionTest
02First Chatfirstchat/FirstChatApplicationTest, SimpleChatApp
03ChatModelchatmodel/ChatModelDeepDiveTest, StreamingChatExample
07Embedding Modelembedding/EmbeddingModelTest, TextSimilarityExample
08Embedding Storeembeddingstore/EmbeddingStoreTest
10RAGrag/RagTest
11AI Servicesaiservices/AiServicesTest
完整的文档列表请参考 docs/ 目录。

开发指南

添加新的测试

  1. src/test/java/cn/langchat/learning/tutorial/<文档编号>/ 创建测试包
  2. 使用 JUnit 5 和 Lombok 编写测试
  3. 使用 TestModelProvider 获取配置好的模型

代码规范

  • 使用 Lombok 注解减少样板代码(@Slf4j, @Data, @Builder 等)
  • 遵循 Java 命名规范
  • 测试方法使用 @DisplayName 添加中文描述
  • 使用 TestModelProvider.getChatModel() 获取模型实例

测试代码示例

import cn.langchat.learning.util.TestModelProvider;
import dev.langchain4j.model.chat.ChatLanguageModel;
import org.junit.jupiter.api.Test;
import lombok.extern.slf4j.Slf4j;

@Slf4j
class YourTest {

    @Test
    @DisplayName("应该生成正确的响应")
    void shouldGenerateCorrectResponse() {
        // 使用 TestModelProvider 获取配置好的模型
        ChatLanguageModel chatModel = TestModelProvider.getChatModel();
        
        // 测试代码
        String response = chatModel.generate("测试输入");
        
        log.info("响应: {}", response);
    }
}

配置获取示例

import cn.langchat.learning.util.EnvConfig;

// 获取 API Key
String apiKey = EnvConfig.getApiKey();

// 获取模型名称
String modelName = EnvConfig.getModelName();

// 获取 Base URL
String baseUrl = EnvConfig.getBaseUrl();

// 获取温度参数
Double temperature = EnvConfig.getTemperature();

// 打印配置信息
EnvConfig.printConfig();

常见问题

Q1: 如何获取 API Key?

访问相应模型提供商的官网注册并创建 API Key:

Q2: 测试失败怎么办?

检查以下项目:
  1. ✅ API Key 是否在 .env 文件中正确配置
  2. ✅ 网络连接是否正常
  3. ✅ API 额度是否充足
  4. ✅ 查看日志中的错误信息

Q3: 如何切换到其他模型?

编辑 .env 文件中的模型配置:
LANGCHAT_BASE_URL=https://api.siliconflow.cn/v1
LANGCHAT_MODEL_NAME=Qwen/Qwen2.5-72B-Instruct

Q4: 如何在本地覆盖配置?

创建 .env.local 文件,设置需要覆盖的配置项:
# .env.local 会覆盖 .env 中的对应配置
LANGCHAT_API_KEY=your-local-api-key
LANGCHAT_MODEL_NAME=your-local-model

Q5: 为什么使用 .env 文件而不是系统环境变量?

使用 .env 文件的优点:
  • ✅ 配置集中管理,易于维护
  • ✅ 支持本地覆盖(.env.local)
  • ✅ 不同环境可以有不同的 .env 文件
  • ✅ 避免在 CI/CD 中硬编码配置
  • ✅ .env 文件被 .gitignore 忽略,安全可靠

项目特点

1. 环境配置管理

  • 使用 .env 文件统一管理配置
  • 支持多级配置覆盖(环境变量 > .env.local > .env)
  • 自动加载和类型转换
  • 敏感信息遮盖

2. 统一的模型提供者

  • TestModelProvider 提供统一的模型获取接口
  • EnvConfig 负责配置加载和管理
  • 测试代码无需关心配置细节

3. 模块化设计

  • 每个学习主题对应独立的测试包
  • 测试类和示例类分离
  • 工具类独立管理

4. 安全性

  • API Key 通过环境变量或 .env 文件管理
  • 敏感配置文件被 .gitignore 忽略
  • 日志输出自动遮盖敏感信息

参考资料

许可证

本项目版权归 LangChat Team 所有。

贡献指南

欢迎贡献代码、报告问题或提出改进建议!
Happy Learning! 🚀