LangChain4j实战：从注解到对话，SystemMessage与UserMessage的协同设计

1. 理解LangChain4j中的消息注解在LangChain4j框架中SystemMessage和UserMessage是两个核心注解它们就像对话系统中的两个不同角色。想象一下你在和一个智能助手对话SystemMessage就像是给这个助手设定性格和规则的导演而UserMessage则是你作为用户实际说出的每句话。我刚开始接触这两个注解时也犯过迷糊后来发现其实很好理解。SystemMessage通常用在接口或类级别它定义了AI的固定行为模式。比如你可以用它来告诉AI你现在是一个专业的法律顾问回答问题时要引用具体的法律条文。这个设定会一直有效直到你改变它。而UserMessage则是标注在方法参数上的它代表用户每次对话时实际输入的内容。比如用户问劳动合同解除需要哪些条件这句话就会被UserMessage标注然后AI会根据之前SystemMessage设定的角色来回答这个问题。2. 注解的核心功能对比2.1 角色定位差异SystemMessage和UserMessage最根本的区别在于它们的角色定位。让我用一个实际项目中的例子来说明SystemMessage({ 你是一位专业的营养师, 回答问题时要考虑用户的BMI指数, 给出的建议必须符合中国居民膳食指南 }) interface NutritionConsultant { String advise(UserMessage String question); }在这个例子中SystemMessage做了三件事设定了AI的角色是营养师规定了回答时要考虑的因素限定了建议的标准而UserMessage标注的question参数则是用户实际提出的问题比如我该怎么减肥2.2 技术特性对比这两个注解在技术实现上也有明显差异我整理了一个对比表格特性SystemMessageUserMessage作用域通常全局有效单次调用有效变量注入需要V注解配合可以直接使用{{it}}引用第一个参数内存管理不会被对话内存清除可能被内存管理策略清除多消息支持同一对话中只保留最后一条可以累积形成对话历史底层类型生成SystemMessage类型的ChatMessage生成UserMessage类型的ChatMessage在实际使用中我发现内存管理这个特性特别重要。SystemMessage的内容会一直保留而UserMessage的内容可能会被清理掉这在设计长时间对话系统时要特别注意。3. 实战应用场景3.1 构建专业领域助手我在开发一个法律咨询助手时是这样使用这两个注解的SystemMessage({ 你是一名专业律师熟悉《中华人民共和国劳动法》, 回答必须准确引用法律条文, 格式要求根据《劳动法》第XX条... }) interface LegalAdvisor { String answerQuestion( UserMessage String question, V(userLocation) String location ); }这里有几个实用技巧在SystemMessage中明确设定了AI的专业领域规定了回答的格式要求UserMessage标注了用户的问题还通过V注解注入了用户位置这个额外参数3.2 动态内容生成对于内容生成类的应用这两个注解的组合尤其强大SystemMessage(根据以下要求生成一篇关于{{topic}}的文章) interface ContentGenerator { String generateArticle( V(topic) String topic, UserMessage String styleRequirements ); }在这个例子中SystemMessage定义了基本任务框架topic参数通过V注解注入到系统消息中UserMessage则接收用户对文章风格的具体要求4. 高级使用技巧4.1 变量注入的灵活运用LangChain4j提供了多种变量注入方式我总结了几种最实用的直接注入SystemMessage(你好{{name}}) String greet(V(name) String userName);使用默认参数SystemMessage(当前用户{{user}}角色{{role}}) String getUserInfo( V(user) String username, V(valuerole, defaultValueguest) String role );集合参数SystemMessage(关键词{{#each keywords}}{{this}} {{/each}}) String analyze(V(keywords) ListString keywords);4.2 内存管理策略对话内存管理是实际项目中最容易出问题的地方。根据我的经验有几点特别需要注意对于重要的系统消息可以使用SystemMessage配合MessageWindowChatMemory来确保不会被意外清除。对于多轮对话要合理配置内存大小ChatMemory chatMemory MessageWindowChatMemory.withCapacity(10);如果某些用户消息特别重要可以考虑手动将其标记为持久化chatMemory.add(new PersistentUserMessage(重要信息));5. 常见问题与解决方案在实际开发中我遇到过不少坑这里分享几个典型问题的解决方法5.1 注解冲突问题有时候会在不同层级定义SystemMessage这时要记住方法级别的注解会覆盖接口级别的最近的注解定义优先级最高比如SystemMessage(默认系统消息) interface MyService { SystemMessage(特殊系统消息) String method(); }在这个例子中调用method()时会使用特殊系统消息。5.2 变量绑定失败当看到VariableNotFoundException时通常是因为模板中使用了未定义的变量变量名拼写错误忘记添加V注解解决方法使用debug模式检查生成的提示词确保所有模板变量都有对应的参数AiService.builder(MyService.class) .debug(true) .build();5.3 性能优化建议对于高性能场景我有几个实用建议将复杂的系统提示存储在外部文件中SystemMessage(file:prompts/legal.txt)对频繁使用的提示进行预编译PromptTemplate template PromptTemplate.from(你好{{name}});合理使用缓存避免重复生成相同提示6. 最佳实践总结经过多个项目的实践我总结出以下几点最佳实践角色定义要清晰明确 在SystemMessage中对AI角色的描述越具体回答质量通常越好。比如SystemMessage({ 你是一位有10年经验的Java架构师, 回答问题时要考虑性能、可维护性和团队协作, 给出的方案要符合阿里巴巴Java开发规范 })合理划分系统消息和用户消息把固定不变的规则放在SystemMessage中把每次调用可能变化的内容放在UserMessage中善用变量注入 通过V注解和模板语法可以创建非常灵活的提示词SystemMessage(根据{{style}}风格写一篇关于{{topic}}的文章) String writeArticle( V(topic) String topic, V(style) String style, UserMessage String additionalRequirements );注意内存管理 根据对话长度和重要性选择合适的ChatMemory实现短对话MessageWindowChatMemory长对话TokenWindowChatMemory重要对话PersistentChatMemory调试技巧 遇到问题时可以启用debug模式查看完整提示词检查变量绑定是否正确验证内存中的消息内容在实际项目中我发现合理使用SystemMessage和UserMessage可以大幅提升AI服务的可控性和用户体验。刚开始可能需要一些练习来掌握两者的平衡但一旦熟悉了它们的特性就能设计出既灵活又稳定的对话系统。