Langchain4j框架-注解篇

核心注解

LangChain4j 作为 Java 生态中集成大语言模型（LLM）的框架，通过注解机制简化了 AI 服务的开发流程。以下是其核心注解及其作用的详细说明：

1. AI 服务定义与模型绑定

• @AiService

  • 作用：标记接口为 AI 服务，框架会动态实现接口方法，将方法调用转发至绑定的 LLM。
  • 示例：

    @AiService
    public interface ChatAiService {
        String chat(String question); // 方法由 LLM 动态实现
    }
    

  • 场景：快速创建聊天机器人、文本生成等基础 AI 服务。

• @Ai.ChatModel / @Ai.StreamingChatModel

  • 作用：指定 AI 服务使用的 LLM 模型（如 ChatModel 或流式输出模型 StreamingChatModel）。
  • 配置：需与 @AiService 配合使用，从服务注册表中选择模型实现。
  • 示例：

    @AiService
    @Ai.ChatModel("gpt-4-turbo") // 指定模型名称
    public interface AdvancedChatService {
        String complexChat(String input);
    }
    

2. 提示词模板管理

• @SystemMessage

  • 作用：定义系统级提示词，设定 AI 助手的角色和行为规则（仅首次对话生效）。
  • 示例：

    public interface Assistant {
        @SystemMessage("你是一个专业助手，擅长技术问题解答。")
        String answerQuestion(String userInput);
    }
    

• @UserMessage

  • 作用：标记用户输入参数，支持动态变量注入（如 {topic}）。
  • 示例：

    public interface StoryGenerator {
        @UserMessage("帮我写一个关于 {{topic}} 的故事。")
        String generateStory(@V("topic") String topic); // @V 注解指定参数名
    }
    

• @P

  • 作用：在 @UserMessage 中标注参数，提供描述和必填校验。
  • 示例：

    @UserMessage("计算 {price} 元商品的 {count} 件总价。")
    String calculateTotal(
        @P(value = "单价", required = true) double price,
        @P(value = "数量", required = true) int count
    );
    

3. 工具调用与外部集成

• @Tool
  • 作用：将 Java 方法暴露为 LLM 可调用的工具，实现动态任务处理（如调用 API、数据库查询）。
  • 示例：

    public class MathTools {
        @Tool(name = "计算器", description = "执行数学运算")
        public double calculate(String expression) {
            return new ScriptEngineManager().getEngineByName("js").eval(expression);
        }
    }
    

  • 场景：扩展 LLM 能力，如访问实时数据、执行复杂计算。

4. 记忆管理（多轮对话）

• @MemoryId
  • 作用：标识会话记忆的唯一键，支持持久化存储（如 Redis）或临时内存。
  • 示例：

    @AiService
    @MemoryId("user_123") // 绑定会话记忆到用户 ID
    public interface PersonalizedChatService {
        String chat(String input); // 方法可访问历史对话上下文
    }
    

5. 链式工作流（Chains）

• @Chain
  • 作用：组合模型、提示词、记忆和检索器，构建复杂工作流（如 RAG 检索增强生成）。
  • 示例：

    @Chain(
        model = "gpt-4",
        memory = @MemoryId("session_1"),
        retriever = "document_retriever" // 关联检索器
    )
    public interface RagChainService {
        String answerWithContext(String query);
    }
    

6. 代理（Agents）与动态决策

• @Agent
  • 作用：定义代理逻辑，允许 LLM 根据任务动态选择工具或推理步骤。
  • 示例：

    @Agent(
        tools = {MathTools.class, WebSearchTool.class}, // 可用工具列表
        strategy = "ReAct" // 使用 ReAct 推理模式
    )
    public interface SmartAgent {
        String solveTask(String taskDescription);
    }
    

注解组合应用示例

@AiService
@Ai.ChatModel("gpt-4-turbo")
@MemoryId("user_session_1")
public interface FullFeaturedAssistant {
    @SystemMessage("你是一个全能助手，可调用工具完成任务。")
    @UserMessage("根据上下文回答：{query}")
    String interact(
        @P String query,
        @Chain(retriever = "knowledge_base") String context // 注入检索结果
    );

    @Tool(name = "数据库查询", description = "执行 SQL 查询")
    List<Map<String, Object>> queryDatabase(String sql);
}

@P 和 @V

在 LangChain4j 框架中，@P 和 @V 注解均用于提示词模板中的参数绑定，但二者在参数来源和使用场景上有显著区别：

1. @P 注解：函数调用参数声明

• 作用：标记方法参数为工具调用（Function Call）的输入参数，用于定义工具方法的参数名、描述及是否必填。
• 使用场景：在 @Tool 注解的工具类方法中，声明参数的元信息（如描述、必填性），帮助 LLM 理解参数用途并正确调用工具。
• 示例：

  @Tool("搜索网页内容")
  String search(
      @P("搜索关键词") String query,          // 参数描述
      @P("分页页码", required = false) Integer page  // 可选参数
  );
  

• 关键特性：
  • 仅用于工具方法参数声明。
  • 支持 required 属性控制参数是否必填。
  • 参数名需与 LLM 生成的工具调用请求中的参数名一致。

2. @V 注解：提示词变量绑定

• 作用：将方法参数绑定到提示词模板中的变量（如 {{variable}}），实现动态参数注入。
• 使用场景：在 @UserMessage 或 @SystemMessage 注解的提示词模板中，用变量占位符动态替换用户输入或系统指令。
• 示例：

  @UserMessage("帮我写一个关于 {{topic}} 的故事，字数控制在 {{length}} 以内")
  String generateStory(
      @V("topic") String topic,   // 绑定到 {{topic}}
      @V("length") int length     // 绑定到 {{length}}
  );
  

• 关键特性：
  • 仅用于提示词模板中的变量绑定。
  • 变量名需与模板中的占位符（如 {{topic}}）完全匹配。
  • 支持复杂对象字段绑定（如 @V("user.address.city")）。

核心区别总结

特性	@P	@V
用途	工具方法参数声明	提示词模板变量绑定
绑定目标	工具调用请求参数	提示词模板占位符（如 {{var}}）
使用位置	@Tool 工具类方法	@UserMessage/@SystemMessage
参数控制	支持 required 等元信息	仅绑定变量值，无元信息控制
典型场景	LLM 调用外部工具（如 API、数据库）	动态生成提示词（如用户输入、上下文）

协同使用示例

@Tool("法律条文查询")
String queryLaw(
    @P("法律领域") String area,       // @P 声明工具参数
    @P("条款编号") String section
);

@AiService
public interface LegalAssistant {
    @SystemMessage("你是一名专业法律顾问，仅回答与 {{area}} 法律相关的问题。")
    @UserMessage("查询 {{section}} 条款内容")
    String getLawInfo(
        @V("area") String area,       // @V 绑定到系统提示词
        @V("section") String section  // @V 绑定到用户提示词
    );
}

• 流程：
  1. 用户调用 getLawInfo("劳动法", "第38条")。
  2. @V 将参数注入提示词模板，生成完整提示。
  3. LLM 根据提示调用 queryLaw 工具，@P 确保参数正确传递。

总结

LangChain4j 的注解体系通过声明式编程降低了 AI 服务开发门槛：

• 核心优势：模块化设计、统一 API、支持复杂工作流（如 RAG、代理）。
• 适用场景：聊天机器人、智能助手、自动化任务处理、知识检索系统。
• 学习建议：优先掌握 @AiService、@Tool、@SystemMessage 等基础注解，再逐步探索高级功能（如代理、链式工作流）。

通过合理组合这些注解，开发者可以高效构建高度定制化的 AI 应用，同时保持代码的简洁性和可维护性。