langchain4j-ai-services-patterns

LangChain4j AI Services 模式

本技能介绍如何使用基于接口的模式、系统消息和用户消息注解、记忆管理、工具集成以及高级 AI 应用模式，构建声明式 LangChain4j AI Services，从而抽象底层 LLM 交互。

概述

LangChain4j AI Services 使用带注解的 Java 接口定义 AI 功能，以最少的样板代码提供类型安全的声明式 AI。

适用场景

在以下情况下使用本技能：

• 使用 Java 接口以最少的样板代码构建声明式 AI 服务
• 创建具备记忆管理功能的类型安全对话式 AI
• 实现具备函数／工具调用能力的 AI Agent
• 设计返回结构化数据（枚举、POJO、列表）的 AI 服务
• 以声明式方式集成 RAG 模式

操作说明

按照以下步骤使用 LangChain4j 创建声明式 AI Services：

1. 定义 AI Service 接口

创建带有 AI 交互方法签名的 Java 接口：

interface Assistant {
    String chat(String userMessage);
}

2. 添加系统消息和用户消息注解

使用 @SystemMessage 和 @UserMessage 注解定义提示词：

interface CustomerSupportBot {
    @SystemMessage("You are a helpful customer support agent for TechCorp")
    String handleInquiry(String customerMessage);

    @UserMessage("Analyze sentiment: {{it}}")
    Sentiment analyzeSentiment(String feedback);
}

3. 创建 AI Service 实例

使用 AiServices 构建器或 create 方法实例化服务：

// Simple creation
Assistant assistant = AiServices.create(Assistant.class, chatModel);

// Or with builder for advanced configuration
Assistant assistant = AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .build();

4. 配置多轮对话的记忆

使用 @MemoryId 添加记忆管理，以支持多用户场景：

interface MultiUserAssistant {
    String chat(@MemoryId String userId, String userMessage);
}

Assistant assistant = AiServices.builder(MultiUserAssistant.class)
    .chatModel(model)
    .chatMemoryProvider(userId -> MessageWindowChatMemory.withMaxMessages(10))
    .build();

5. 集成函数调用工具

使用 @Tool 注解注册工具，以启用 AI 函数执行：

class Calculator {
    @Tool("Add two numbers") double add(double a, double b) { return a + b; }
}

interface MathGenius {
    String ask(String question);
}

MathGenius mathGenius = AiServices.builder(MathGenius.class)
    .chatModel(model)
    .tools(new Calculator())
    .build();

6. 验证和测试

使用具体的验证模式测试 AI 服务：

// 1. Test with sample inputs
String response = assistant.chat("Hello, how are you?");
assert response != null && !response.isEmpty();

// 2. Validate structured outputs with assertions
Sentiment result = bot.analyzeSentiment("Great product!");
assert result == Sentiment.POSITIVE;

// 3. Log tool calls with side effects for audit
MathGenius math = AiServices.builder(MathGenius.class)
    .chatModel(model)
    .tools(new Calculator())
    .build();

// 4. Test memory isolation between users
String userA = assistant.chat("User A message", "session-a");
String userB = assistant.chat("User B message", "session-b");
assert !userA.equals(userB); // Verify memory isolation

示例

请参阅 examples.md，其中包含全面的实用示例，包括：

• 基本聊天接口
• 带记忆的有状态助手
• 多用户场景
• 结构化输出提取
• 工具调用和函数执行
• 流式响应
• 错误处理
• RAG 集成
• 生产环境模式

API 参考

完整的 API 文档、注解、接口和配置模式请参阅 references.md。

最佳实践

1. 使用类型安全的接口，而不是基于字符串的提示词
2. 实施适当的记忆管理，并设置合理的限制
3. 设计清晰的工具描述，并提供参数文档
4. 妥善处理错误，使用自定义错误处理器
5. 使用结构化输出，以获得可预测的响应
6. 对用户输入实施验证
7. 监控生产部署的性能

依赖项

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

// Gradle
implementation 'dev.langchain4j:langchain4j:1.8.0'
implementation 'dev.langchain4j:langchain4j-open-ai:1.8.0'

参考资料

• LangChain4j 文档
• LangChain4j AI Services - API 参考
• LangChain4j AI Services - 实用示例

限制和警告

• AI Services 依赖非确定性的 LLM 响应；测试应考虑这种变化。
• 记忆提供程序会存储对话历史；请确保在多用户场景中进行适当清理。
• 工具执行可能成本高昂；请实施速率限制和超时处理。
• 切勿在系统消息或用户消息中传递敏感数据（API 密钥、密码）。
• 较大的上下文窗口可能导致较高的 token 成本；请实施消息裁剪策略。
• 流式响应需要妥善处理部分失败。
• 在生产系统中使用前，应验证 AI 生成的输出。
• 对具有副作用的工具保持谨慎；AI 模型可能会意外调用它们。
• 不同模型的 token 限制各不相同；请确保提示词和上下文符合模型限制。