LangChain4j 常用注解速查表

说明：按开发场景分类，标注核心用途+极简示例，适配打印，重点注解标红，便于快速检索

一、AI服务核心注解（基础必用）

• @AiService - 标记接口为AI服务，框架自动生成实现类（入口注解）
  示例：@AiService public interface ChatAssistant { … }

• @SystemMessage - 设定AI角色、规则、语气（可加在接口/方法上）
  示例：@SystemMessage(“专业Java助手，回答简洁带代码”)

• @UserMessage - 定义用户提示词模板，配合@V注入变量
  示例：@UserMessage(“解释：{{topic}}”) String explain(…)

二、提示词模板注解（变量填充）

• @V（Variable） - 绑定方法参数到提示词模板{{变量}}（给框架用）
  示例：@V(“text”) String content

三、对话记忆/会话注解（多轮对话必用）

• @MemoryId - 标记会话ID，实现多用户对话隔离
  示例：String chat(@MemoryId Long userId, String msg)

• @Moderate - 开启内容审核，过滤违规输入/输出
  示例：@Moderate String chat(String msg)

四、AI工具（函数调用）注解

• @Tool - 标记方法为AI可调用工具，需写清晰描述
  示例：@Tool(“查询当前天气”) String getWeather(…)

• @P（Parameter） - 描述工具参数，让AI理解参数含义（给AI用）
  示例：@P(“城市名称”) String city

五、RAG检索增强注解（知识库必用）

• @Retrieval - 开启检索增强，从知识库查询资料（可设检索条件）
  示例：@Retrieval(maxResults = 3) String ask(String question)

• @NeedsMemory - 检索时携带对话历史，提升回答连贯性
  示例：@NeedsMemory @Retrieval String chat(String question)

六、文档/嵌入（Embedding）注解

• @FromDocument - 标记参数为文档内容，用于向量嵌入
  示例：void embed(@FromDocument String content)

• @EmbeddingModel - 指定使用的嵌入模型（多模型场景）
  示例：@EmbeddingModel(“bge-small”) Embedding embed(String text)

七、高级控制注解（优化AI生成）

• @Timeout - 设置AI响应超时时间（单位：秒）
  示例：@Timeout(30) String chat(String msg)

• @Temperature - 控制AI生成随机性（0=严谨，1=创意）
  示例：@Temperature(0.2) String writeCode(String task)

• @TopK - 控制生成结果的候选数量，影响随机性
  示例：@TopK(50) String story(String theme)

八、Spring整合专用注解

• @LangChain4jAiService - Spring中注册AI Service为Bean
  示例：@LangChain4jAiService(chatModel = “openAiChatModel”)

• @ChatModel / @EmbeddingModel - 注入指定的模型Bean
  示例：@Autowired @ChatModel(“openAi”) ChatModel chatModel

核心8个必背注解（重点标注）

1. @AiService（AI服务入口） 2. @SystemMessage（设定角色） 3. @UserMessage（提示词模板） 4. @V（模板填充）
2. @MemoryId（会话隔离） 6. @Tool（定义工具） 7. @P（工具参数描述） 8. @Retrieval（知识库检索）

关键区别速记

• @V：给框架用，填充提示词模板变量
• @P：给AI用，描述工具参数含义