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

02 - 第一个 Chat 应用

版本说明

本文档基于 LangChain4j 1.10.0 版本编写。

学习目标

通过本章节学习，你将能够：

深入理解 ChatModel 的基本概念
掌握创建和配置 ChatModel 实例的方法
学会发送不同类型的消息
理解如何接收和处理 LLM 响应
构建一个完整的聊天应用示例

前置知识

完成《01 - LangChain4j 简介》章节
理解基本的 LLM 概念
已配置好开发环境和 API Key

核心概念

ChatModel 简介

ChatModel 是 LangChain4j 中最核心的接口之一，用于与大语言模型进行交互。它代表了与大语言模型对话的能力。 类比理解： 如果把 LLM 比作一个智能客服人员，那么 ChatModel 就是你的电话——通过它你可以与客服人员（LLM）进行对话。

ChatModel 接口层次

LangChain4j 提供了多个层级的接口，从简单到复杂：

// 1. 最简单的接口（已废弃，不推荐使用）
interface LanguageModel {
    String chat(String prompt);
}

// 2. 推荐使用的聊天模型接口
interface ChatModel {
    String chat(String userMessage);
}

// 3. 更强大的 ChatModel 接口
interface ChatModel {
    ChatResponse chat(ChatMessage... messages);
    ChatResponse chat(List<ChatMessage> messages);
    ChatResponse chat(ChatRequest chatRequest);
    String chat(String userMessage);  // 便捷方法
}

接口选择建议：

初学者：使用 chatModel.chat(String) 最简单
进阶使用：使用 ChatModel 获得更多控制力
高级用户：使用 chatModel.chat(ChatRequest) 完全控制

ChatMessage 类型

在深入了解 ChatModel 之前，先了解 ChatMessage 的类型：

// 1. 用户消息 - 来自用户或应用的消息
UserMessage userMessage = UserMessage.from("你好");

// 2. AI 消息 - LLM 生成的消息
AiMessage aiMessage = AiMessage.from("你好！有什么可以帮助你的吗？");

// 3. 系统消息 - 设置 LLM 行为的消息
SystemMessage systemMessage = SystemMessage.from("你是一个友好的助手");

// 4. 工具执行结果消息 - 工具执行后返回的消息
ToolExecutionResultMessage toolResult = ToolExecutionResultMessage.from(...);

创建 ChatModel 实例

使用 OpenAI 模型

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;

// 基本配置
ChatModel model = OpenAiChatModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-4o-mini")
        .build();

高级配置

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.model.chat.response.ChatResponse;
import dev.langchain4j.data.message.AiMessage;
import java.time.Duration;

ChatModel model = OpenAiChatModel.builder()
        // 基本配置
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-4o-mini")
        
        // 参数配置（下一章详细讲解）
        .temperature(0.7)              // 创造性：0.0-2.0，越高越有创意
        .topP(0.9)                    // 核采样
        .maxTokens(1000)               // 最大输出 Token 数
        .timeout(Duration.ofSeconds(60)) // 超时时间
        
        // 日志配置（便于调试）
        .logRequests(true)              // 记录请求
        .logResponses(true)             // 记录响应
        
        .build();

使用其他模型提供商

// Anthropic Claude
import dev.langchain4j.model.anthropic.AnthropicChatModel;
ChatModel claudeModel = AnthropicChatModel.builder()
        .apiKey(System.getenv("ANTHROPIC_API_KEY"))
        .modelName("claude-3-5-sonnet-20241022")
        .build();

// Google Gemini
import dev.langchain4j.model.google.GeminiChatModel;
ChatModel geminiModel = GeminiChatModel.builder()
        .apiKey(System.getenv("GOOGLE_API_KEY"))
        .modelName("gemini-1.5-pro")
        .build();

// Ollama 本地模型
import dev.langchain4j.model.ollama.OllamaChatModel;
ChatModel ollamaModel = OllamaChatModel.builder()
        .baseUrl("http://localhost:11434")
        .modelName("llama2")
        .build();

发送消息

方式一：简单的字符串消息

最简单的方式，直接发送字符串：

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;

ChatModel model = OpenAiChatModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-4o-mini")
        .build();

String userMessage = "你好，请介绍一下你自己";
String response = model.chat(userMessage);

System.out.println("用户: " + userMessage);
System.out.println("AI: " + response);

方式二：使用 ChatMessage

使用 ChatMessage 类型发送消息，获得更多控制：

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.data.message.AiMessage;

ChatModel model = OpenAiChatModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-4o-mini")
        .build();

// 创建用户消息
UserMessage userMessage = UserMessage.from("你好，请介绍一下你自己");

// 发送消息并接收完整响应
ChatResponse response = model.chat(userMessage);

// 获取 AI 消息
AiMessage aiMessage = response.aiMessage();

System.out.println("用户: " + userMessage.text());
System.out.println("AI: " + aiMessage.text());

方式三：多消息对话

发送多个消息，构建完整对话上下文：

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.data.message.*;
import java.util.ArrayList;
import java.util.List;

ChatModel model = OpenAiChatModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-4o-mini")
        .build();

// 构建对话历史
List<ChatMessage> messages = new ArrayList<>();

// 添加系统消息
messages.add(SystemMessage.from("你是一个专业的 Java 编程助手"));

// 添加用户消息
messages.add(UserMessage.from("什么是 Java？"));

// 发送对话
ChatResponse response1 = model.chat(messages);
messages.add(response1.aiMessage());

System.out.println("AI: " + response1.aiMessage().text());

// 继续对话
messages.add(UserMessage.from("Java 有哪些特点？"));
ChatResponse response2 = model.chat(messages);

System.out.println("AI: " + response2.aiMessage().text());

方式四：使用 ChatRequest 完全控制

使用 ChatRequest 对象进行完全控制：

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.chat.request.ChatRequest;
import dev.langchain4j.model.chat.request.ChatRequestParameters;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.data.message.*;
import java.util.List;

ChatModel model = OpenAiChatModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-4o-mini")
        .build();

// 构建请求参数
ChatRequestParameters parameters = ChatRequestParameters.builder()
        .temperature(0.7)
        .topP(0.9)
        .maxOutputTokens(500)
        .build();

// 构建完整请求
ChatRequest request = ChatRequest.builder()
        .messages(
            SystemMessage.from("你是一个专业的助手"),
            UserMessage.from("什么是机器学习？")
        )
        .parameters(parameters)
        .build();

// 发送请求
ChatResponse response = model.chat(request);

System.out.println("AI: " + response.aiMessage().text());

接收响应

获取响应文本

最简单的获取响应文本的方式：

ChatModel model = ...;
String response = model.chat("你好");
System.out.println(response);

获取完整响应信息

获取响应的详细信息，包括元数据：

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.chat.response.ChatResponse;
import dev.langchain4j.model.chat.response.ChatResponseMetadata;
import dev.langchain4j.model.output.TokenUsage;

ChatModel model = ...;
ChatResponse response = model.chat("你好");

// 获取 AI 消息
AiMessage aiMessage = response.aiMessage();
String text = aiMessage.text();

// 获取响应元数据
ChatResponseMetadata metadata = response.metadata();
String modelId = metadata.modelName();           // 使用的模型
String responseId = metadata.id();               // 响应 ID
TokenUsage tokenUsage = metadata.tokenUsage();    // Token 使用情况

// Token 使用详情
int inputTokens = tokenUsage.inputTokenCount();    // 输入 Token 数
int outputTokens = tokenUsage.outputTokenCount();  // 输出 Token 数
int totalTokens = tokenUsage.totalTokenCount();    // 总 Token 数

System.out.println("响应文本: " + text);
System.out.println("模型: " + modelId);
System.out.println("输入 Token: " + inputTokens);
System.out.println("输出 Token: " + outputTokens);
System.out.println("总 Token: " + totalTokens);

获取完成原因

了解为什么 LLM 停止生成：

import dev.langchain4j.model.output.FinishReason;

ChatResponse response = model.chat("讲一个故事");
FinishReason finishReason = response.metadata().finishReason();

switch (finishReason) {
    case STOP:
        System.out.println("正常结束");
        break;
    case LENGTH:
        System.out.println("达到最大 Token 限制");
        break;
    case CONTENT_FILTER:
        System.out.println("内容被过滤");
        break;
    case TOOL_EXECUTIONS:
        System.out.println("等待工具执行");
        break;
    default:
        System.out.println("其他原因: " + finishReason);
}

完整示例：简单的聊天应用

示例代码

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import java.util.Scanner;

/**
 * 简单的聊天应用示例
 */
public class SimpleChatApp {

    private final ChatModel model;
    private final Scanner scanner;

    public SimpleChatApp() {
        this.model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o-mini")
                .logRequests(true)
                .logResponses(true)
                .build();
        this.scanner = new Scanner(System.in);
    }

    public void start() {
        System.out.println("╔══════════════════════════════════════╗");
        System.out.println("║   LangChain4j 简单聊天应用 v1.0    ║");
        System.out.println("╚══════════════════════════════════════╝");
        System.out.println();
        System.out.println("使用提示:");
        System.out.println("  - 直接输入消息与 AI 对话");
        System.out.println("  - 输入 'clear' 清屏");
        System.out.println("  - 输入 'exit' 退出");
        System.out.println();

        int messageCount = 0;

        while (true) {
            System.out.print("[" + (++messageCount) + "] 你: ");
            String input = scanner.nextLine().trim();

            // 处理命令
            if ("exit".equalsIgnoreCase(input)) {
                System.out.println("\n再见！感谢使用。");
                break;
            } else if ("clear".equalsIgnoreCase(input)) {
                for (int i = 0; i < 50; i++) {
                    System.out.println();
                }
                continue;
            } else if (input.isEmpty()) {
                continue;
            }

            // 发送消息
            try {
                long startTime = System.currentTimeMillis();
                String response = model.chat(input);
                long endTime = System.currentTimeMillis();

                System.out.println("[" + messageCount + "] AI: " + response);
                System.out.println("        (耗时: " + (endTime - startTime) + "ms)");
                System.out.println();
            } catch (Exception e) {
                System.err.println("错误: " + e.getMessage());
                System.out.println();
            }
        }

        scanner.close();
    }

    public static void main(String[] args) {
        SimpleChatApp app = new SimpleChatApp();
        app.start();
    }
}

运行示例

╔══════════════════════════════════════╗
║   LangChain4j 简单聊天应用 v1.0    ║
╚══════════════════════════════════════╝

使用提示:
  - 直接输入消息与 AI 对话
  - 输入 'clear' 清屏
  - 输入 'exit' 退出

[1] 你: 你好，我是 Java 初学者
[1] AI: 你好！很高兴认识你。作为一个 Java 初学者，你可以从学习 Java 的基础语法开始，比如变量、数据类型、控制流等。有什么具体的问题我可以帮助你吗？
        (耗时: 1234ms)

[2] 你: Java 有哪些特点？
[2] AI: Java 有以下主要特点：

1. 平台无关性：Java 程序可以"一次编写，到处运行"（Write Once, Run Anywhere）
2. 面向对象：Java 是纯面向对象的编程语言
3. 简单易学：语法相对简单，去除了 C++ 中复杂的概念
4. 健壮性：强类型检查、异常处理机制提高了程序的稳定性
5. 安全性：内置安全机制，如字节码验证
6. 多线程：内置多线程支持，便于开发并发程序
7. 高性能：通过 JIT 编译器实现较高的执行效率

有什么具体想了解的吗？
        (耗时: 2345ms)

[3] 你: exit

再见！感谢使用。

测试代码示例

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import org.junit.jupiter.api.*;
import static org.junit.jupiter.api.Assertions.*;

/**
 * Chat 应用测试
 */
class ChatAppTest {

    private ChatModel model;

    @BeforeEach
    void setUp() {
        model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o-mini")
                .build();
    }

    @Test
    void should_respond_to_greeting() {
        String greeting = "你好";
        String response = model.chat(greeting);
        
        assertNotNull(response);
        assertFalse(response.isEmpty());
        System.out.println("问候响应: " + response);
    }

    @Test
    void should_answer_simple_question() {
        String question = "2 + 2 等于几？";
        String response = model.chat(question);
        
        assertNotNull(response);
        assertTrue(response.contains("4") || response.contains("四"));
        System.out.println("数学问题响应: " + response);
    }

    @Test
    void should_generate_code_when_asked() {
        String request = "写一个 Java 的 Hello World 程序";
        String response = model.chat(request);
        
        assertNotNull(response);
        assertTrue(response.contains("public") || response.contains("class"));
        assertTrue(response.contains("System.out.println"));
        System.out.println("代码生成响应:\n" + response);
    }

    @Test
    void should_follow_instructions() {
        String instruction = "请用一句话介绍 Java";
        String response = model.chat(instruction);
        
        assertNotNull(response);
        // 检查是否是一句话（简单检查句号数量）
        long sentenceCount = response.chars()
                .filter(ch -> ch == '。' || ch == '.' || ch == '!')
                .count();
        assertTrue(sentenceCount <= 2, "响应应该包含最多2个句子，实际: " + sentenceCount);
        System.out.println("一句话介绍: " + response);
    }

    @Test
    void should_handle_empty_message() {
        String emptyMessage = "";
        String response = model.chat(emptyMessage);
        
        assertNotNull(response);
        System.out.println("空消息响应: " + response);
    }

    @Test
    void should_respond_in_chinese_when_asked_in_chinese() {
        String message = "你是谁？";
        String response = model.chat(message);
        
        assertNotNull(response);
        // 验证响应中包含中文字符
        assertTrue(response.matches(".*[\\u4e00-\\u9fa5].*"));
        System.out.println("中文响应: " + response);
    }
}

实践练习

练习 1：统计 Token 使用

修改聊天应用，显示每次对话的 Token 使用情况：

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.model.chat.response.ChatResponse;
import dev.langchain4j.model.output.TokenUsage;
import java.util.Scanner;

public class TokenTrackingChat {

    private final ChatModel model;
    private final Scanner scanner;
    private int totalInputTokens = 0;
    private int totalOutputTokens = 0;

    public TokenTrackingChat() {
        this.model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o-mini")
                .build();
        this.scanner = new Scanner(System.in);
    }

    public void start() {
        System.out.println("=== Token 统计聊天应用 ===");
        System.out.println();

        while (true) {
            System.out.print("你: ");
            String input = scanner.nextLine();

            if ("exit".equalsIgnoreCase(input.trim())) {
                break;
            }

            ChatResponse response = model.chat(input);
            TokenUsage usage = response.metadata().tokenUsage();

            totalInputTokens += usage.inputTokenCount();
            totalOutputTokens += usage.outputTokenCount();

            System.out.println("AI: " + response.aiMessage().text());
            System.out.println("本次: 输入=" + usage.inputTokenCount() + 
                             ", 输出=" + usage.outputTokenCount());
            System.out.println("累计: 输入=" + totalInputTokens + 
                             ", 输出=" + totalOutputTokens);
            System.out.println();
        }

        System.out.println("=== Token 使用统计 ===");
        System.out.println("总输入 Token: " + totalInputTokens);
        System.out.println("总输出 Token: " + totalOutputTokens);
        System.out.println("总计: " + (totalInputTokens + totalOutputTokens));
        System.out.println("估算费用: $" + estimateCost(totalInputTokens, totalOutputTokens));
        scanner.close();
    }

    private double estimateCost(int inputTokens, int outputTokens) {
        // GPT-4o-mini 价格（示例，实际价格请查询 OpenAI）
        double inputPrice = 0.00015 / 1000.0;  // 每 1000 tokens 价格
        double outputPrice = 0.0006 / 1000.0;
        return (inputTokens * inputPrice) + (outputTokens * outputPrice);
    }

    public static void main(String[] args) {
        new TokenTrackingChat().start();
    }
}

练习 2：添加系统提示

让聊天应用支持自定义系统提示：

public class SystemPromptChat {

    private final ChatModel model;
    private final Scanner scanner;
    private String systemPrompt = "你是一个友好的助手";

    public SystemPromptChat() {
        this.model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o-mini")
                .build();
        this.scanner = new Scanner(System.in);
    }

    public void start() {
        System.out.println("=== 系统提示聊天应用 ===");
        System.out.println("命令:");
        System.out.println("  /set <提示> - 设置系统提示");
        System.out.println("  /show - 显示当前系统提示");
        System.out.println("  /exit - 退出");
        System.out.println();

        while (true) {
            System.out.print("你: ");
            String input = scanner.nextLine().trim();

            if (input.isEmpty()) {
                continue;
            }

            if (input.equals("/exit")) {
                break;
            } else if (input.startsWith("/set ")) {
                systemPrompt = input.substring(5);
                System.out.println("系统提示已更新: " + systemPrompt);
                System.out.println();
                continue;
            } else if (input.equals("/show")) {
                System.out.println("当前系统提示: " + systemPrompt);
                System.out.println();
                continue;
            }

            // 使用系统提示发送消息
            ChatResponse response = model.chat(
                SystemMessage.from(systemPrompt),
                UserMessage.from(input)
            );
            System.out.println("AI: " + response.aiMessage().text());
            System.out.println();
        }
        scanner.close();
    }

    public static void main(String[] args) {
        new SystemPromptChat().start();
    }
}

练习 3：响应时间对比

对比不同模型的响应时间：

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;

public class ModelComparison {

    public static void main(String[] args) {
        String message = "写一首关于编程的诗";

        // GPT-3.5 Turbo
        ChatModel gpt35 = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-3.5-turbo")
                .build();

        // GPT-4o Mini
        ChatModel gpt4oMini = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o-mini")
                .build();

        System.out.println("=== 模型对比测试 ===");
        System.out.println("消息: " + message);
        System.out.println();

        // 测试 GPT-3.5 Turbo
        long start = System.currentTimeMillis();
        String response35 = gpt35.chat(message);
        long end = System.currentTimeMillis();
        System.out.println("GPT-3.5 Turbo (" + (end - start) + "ms):");
        System.out.println(response35);
        System.out.println();

        // 测试 GPT-4o Mini
        start = System.currentTimeMillis();
        String response4o = gpt4oMini.chat(message);
        end = System.currentTimeMillis();
        System.out.println("GPT-4o Mini (" + (end - start) + "ms):");
        System.out.println(response4o);
    }
}

总结

本章要点

ChatModel 接口层次
- LanguageModel（废弃）
- ChatModel（推荐初学者）
- ChatModel（提供完整控制）
创建 ChatModel
- 基本配置（API Key、模型名称）
- 高级配置（参数、超时、日志）
- 支持多种模型提供商
发送消息的方式
- 简单字符串：model.chat(String)
- ChatMessage：model.chat(ChatMessage)
- 多消息：model.chat(List<ChatMessage>)
- ChatRequest：model.chat(ChatRequest)
接收响应
- 获取响应文本
- 获取完整元数据（模型、Token 使用等）
- 获取完成原因
完整示例
- 构建了一个可运行的聊天应用
- 包含输入输出、命令处理、错误处理

下一步

在下一章节中，我们将深入学习：

ChatModel 接口的详细方法
StreamingChatModel 流式模型
模型选择策略
异常处理和错误管理

常见问题

Q1：ChatModel 和 ChatModel 有什么区别？ A：ChatModel 是简化接口，只接受字符串输入返回字符串输出。ChatModel 是更强大的接口，接受 ChatMessage 对象，返回包含元数据的 ChatResponse。 Q2：如何选择合适的模型？ A：考虑以下因素：

成本：GPT-3.5 更便宜，GPT-4o 更强大
速度：GPT-3.5 更快
任务复杂度：简单任务用便宜的模型，复杂任务用强大模型
下一章我们将详细介绍。

Q3：为什么多轮对话中 AI 不记得之前的内容？ A：LLM 本身是无状态的。要实现多轮对话记忆，需要使用 ChatMemory（将在后续章节介绍）。 Q4：如何处理 API 错误？ A：可以使用 try-catch 捕获异常，或配置重试机制。我们将在后续章节详细介绍错误处理。 Q5：logRequests 和 logResponses 有什么作用？ A：这两个参数会开启请求和响应的日志记录，便于调试和监控。生产环境中可以关闭以提高性能。

参考资料

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

​02 - 第一个 Chat 应用

​版本说明

​学习目标

​前置知识

​核心概念

​ChatModel 简介

​ChatModel 接口层次

​ChatMessage 类型

​创建 ChatModel 实例

​使用 OpenAI 模型

​高级配置

​使用其他模型提供商

​发送消息

​方式一：简单的字符串消息

​方式二：使用 ChatMessage

​方式三：多消息对话

​方式四：使用 ChatRequest 完全控制

​接收响应

​获取响应文本

​获取完整响应信息

​获取完成原因

​完整示例：简单的聊天应用

​示例代码

​运行示例

​测试代码示例

​实践练习

​练习 1：统计 Token 使用

​练习 2：添加系统提示

​练习 3：响应时间对比

​总结

​本章要点

​下一步

​常见问题

​参考资料