LangChain4j Quick-Start: Build AI Apps with Java in Minutes

1. Environment Setup

1.1 Add Dependencies

Provide Maven dependencies for the core library, OpenAI support, and optional Chinese model support, all at version 0.35.0.

<dependencies>
    <!-- LangChain4j core -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j</artifactId>
        <version>0.35.0</version>
    </dependency>

    <!-- OpenAI model support -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-open-ai</artifactId>
        <version>0.35.0</version>
    </dependency>

    <!-- Optional domestic model support -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-qianfan</artifactId>
        <version>0.35.0</version>
    </dependency>
</dependencies>

1.2 Configure API Key

Two methods are shown: (1) environment variable (recommended) and (2) application.properties file.

# Linux/Mac
export OPENAI_API_KEY=your_api_key

# Windows
set OPENAI_API_KEY=your_api_key

# application.properties
openai.api.key=your_api_key

1.3 First Hello World

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

public class HelloWorld {
    public static void main(String[] args) {
        // Create model instance
        ChatLanguageModel model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o")
                .build();

        // Send message
        String response = model.generate("你好，请用一句话介绍你自己");
        System.out.println(response);
    }
}

2. Core Components

2.1 Model

The model component is responsible for interacting with large language models (LLMs). Common model types include:

ChatLanguageModel – conversational model (most common)

StreamingChatLanguageModel – streaming conversational model

EmbeddingModel – vectorization model

ImageModel – image generation model

Key configuration parameters:

apiKey – required API key

modelName – e.g., gpt-4o temperature – creativity level, recommended 0.7 timeout – request timeout, recommended 60 seconds

maxTokens – maximum output length, recommended 2000 Example of switching between models:

// GPT‑4
ChatLanguageModel gpt4 = OpenAiChatModel.builder()
        .apiKey(apiKey)
        .modelName("gpt-4o")
        .build();

// GPT‑3.5 (cheaper, faster)
ChatLanguageModel gpt35 = OpenAiChatModel.builder()
        .apiKey(apiKey)
        .modelName("gpt-3.5-turbo")
        .build();

2.2 Prompt

A good prompt is critical. The example shows how to set a system message that defines the AI’s role and a user message that carries the query. Prompt best practices are listed: define role, clear task, format requirements, provide examples.

import dev.langchain4j.data.message.SystemMessage;
import dev.langchain4j.data.message.UserMessage;

// System prompt (role)
SystemMessage systemMessage = SystemMessage.from(
    "你是一位资深的 Java 开发专家，擅长用简洁清晰的方式解答问题."
);

// User question
UserMessage userMessage = UserMessage.from("请解释一下什么是依赖注入");

// Send dialogue
String response = model.generate(systemMessage, userMessage);

2.3 Structured Output

Define a Java class to receive structured data instead of raw strings.

public class CodeReview {
    private List<String> issues;      // discovered issues
    private List<String> suggestions; // improvement suggestions
    private int score;               // 1‑10 rating
    private String summary;          // summary
    // getters and setters omitted
}

Generate a structured result and print fields:

String code = "public class Hello {...}";
CodeReview review = model.generate(
        "请 Review 以下 Java 代码：" + code,
        CodeReview.class
);
System.out.println("发现问题：" + review.getIssues());
System.out.println("评分：" + review.getScore());

2.4 Function Calling

Define tools that the LLM can invoke via annotations.

import dev.langchain4j.agent.tool.Tool;
import dev.langchain4j.agent.tool.P;

public class WeatherTool {
    @Tool("查询指定城市的天气信息")
    public String getWeather(@P("城市名称，如：北京、上海") String city) {
        // Call weather API
        return "北京：晴，25°C";
    }

    @Tool("计算两个数的和")
    public int add(@P("第一个数") int a, @P("第二个数") int b) {
        return a + b;
    }
}

Register the tool and invoke it through an AI service:

WeatherTool weatherTool = new WeatherTool();

ChatLanguageModel model = OpenAiChatModel.builder()
        .apiKey(apiKey)
        .modelName("gpt-4o") // supports function calling
        .build();

Assistant assistant = AiServices.builder(Assistant.class)
        .chatLanguageModel(model)
        .tools(weatherTool)
        .build();

String response = assistant.chat("北京今天天气怎么样？");

2.5 Memory

Memory lets the model retain conversation context. Types include MessageWindowChatMemory (last N messages), TokenWindowChatMemory (last N tokens), and PersistentChatMemory (persistent storage).

ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10);

Assistant assistant = AiServices.builder(Assistant.class)
        .chatLanguageModel(model)
        .chatMemory(memory)
        .build();

assistant.chat("我叫小明，今年 25 岁");
assistant.chat("我住在哪里？"); // AI replies "我不知道"
assistant.chat("记住，我住在上海");
assistant.chat("我住在哪里？"); // AI replies "你住在上海"

Best practices: choose memory size based on scenario, regularly clean expired memory, avoid storing sensitive information, consider persistent storage for long‑term use.

3. Hands‑On Projects

3.1 Smart Assistant

Goal: create an assistant that answers questions.

public class SmartAssistant {
    private final Assistant assistant;

    public SmartAssistant() {
        ChatLanguageModel model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o")
                .build();

        SystemMessage systemMessage = SystemMessage.from(
                "你是一位友好的智能助手，擅长解答各种问题。请用简洁清晰的语言回答，必要时提供示例."
        );

        this.assistant = AiServices.builder(Assistant.class)
                .chatLanguageModel(model)
                .systemMessageProvider(chatId -> systemMessage.text())
                .build();
    }

    public String ask(String question) {
        return assistant.chat(question);
    }

    public static void main(String[] args) {
        SmartAssistant bot = new SmartAssistant();
        Scanner scanner = new Scanner(System.in);
        while (true) {
            System.out.print("你：");
            String input = scanner.nextLine();
            if ("exit".equals(input)) break;
            String response = bot.ask(input);
            System.out.println("助手：" + response);
        }
    }
}

3.2 Document Summarizer

Goal: automatically summarize long documents.

public class DocumentSummarizer {
    private final ChatLanguageModel model;

    public DocumentSummarizer() {
        this.model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o")
                .maxTokens(2000)
                .build();
    }

    public static class Summary {
        private String title;               // title
        private List<String> keyPoints;      // key points
        private String conclusion;          // conclusion
    }

    public Summary summarize(String document) {
        String prompt = String.format(
                "请总结以下文档内容：

%s

要求：
1. 提取一个简洁的标题
2. 列出 3-5 个关键点
3. 给出一个总结论",
                document
        );
        return model.generate(prompt, Summary.class);
    }
}

3.3 Code Generator

Goal: generate code from a natural‑language description.

public class CodeGenerator {
    private final ChatLanguageModel model;

    public CodeGenerator() {
        this.model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o")
                .build();
    }

    public static class GeneratedCode {
        private String code;        // generated code
        private String explanation; // code explanation
        private List<String> usage;   // usage examples
    }

    public GeneratedCode generate(String description, String language) {
        String prompt = String.format(
                "请生成%s代码，实现以下功能：%s
要求：
1. 代码规范、可运行
2. 添加必要注释
3. 提供使用示例",
                language, description
        );
        return model.generate(prompt, GeneratedCode.class);
    }
}

4. Frequently Asked Questions

4.1 API Call Failures

Possible reasons: invalid API key, network problems, insufficient balance.

Solution: add a retry policy.

RetryPolicy retryPolicy = RetryPolicy.builder()
        .maxRetries(3)
        .delay(1, TimeUnit.SECONDS)
        .build();

4.2 Slow Responses

Optimization suggestions: use a smaller model such as GPT‑3.5, reduce maxTokens, or enable streaming output.

StreamingChatLanguageModel streamingModel = ...;
streamingModel.generate("你好", new StreamingResponseHandler() {
    @Override
    public void onNext(String token) {
        System.out.print(token); // real‑time output
    }
});

4.3 Unstable Output

Solutions: lower temperature (e.g., 0.3), provide a more detailed prompt, or use few‑shot examples.

5. Learning Resources

Official documentation – https://docs.langchain4j.dev

GitHub repository – https://github.com/langchain4j/langchain4j

Example projects – https://github.com/langchain4j/langchain4j-examples

Bilibili LangChain4j tutorial

YouTube official channel

ZhiHu LangChain4j column

Conclusion

Key takeaways: environment setup and configuration, basic model invocation, structured output, function calling, and conversation memory management enable rapid development of AI‑powered Java applications with LangChain4j.