[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"$f1b300lqgtfmoj":3,"$f250wz8h39yydc":8,"$f2vt9fti1g7q8r":29,"toc-1687696579-5-5":39},{"description":4,"domain":5,"id":6,"keywords":4,"title":7},"","api.kongjs.com",1,"默认",[9,20,24],{"children":10,"icon":4,"id":11,"linkType":12,"linkUrl":13,"parentId":14,"sort":15,"status":16,"target":17,"title":18,"visible":19},null,"447369447469600768","URL","\u002F","0",0,"1","_self","首页",true,{"children":10,"icon":4,"id":21,"linkType":12,"linkUrl":22,"parentId":14,"sort":15,"status":16,"target":17,"title":23,"visible":19},"447369693859794944","\u002Fnotes","笔记",{"children":10,"icon":4,"id":25,"linkType":26,"linkUrl":27,"parentId":14,"sort":15,"status":16,"target":17,"title":28,"visible":19},"447369977960976384","PAGE","\u002Fabout","关于我",{"allowComment":19,"category":30,"categoryId":31,"collectCount":15,"commentCount":15,"content":34,"contentType":35,"cover":10,"description":4,"fileId":10,"id":36,"likeCount":15,"publishAt":10,"rating":15,"source":10,"sourceUrl":10,"tags":37,"title":38,"viewCount":15,"wordCount":15},{"articleCount":10,"children":10,"cover":10,"description":4,"fileId":10,"icon":4,"id":31,"parentId":14,"slug":32,"sort":15,"title":33},"453164804731838464","ai","人工智能","## 一、概述\n\n### 1\\.1 类定位与核心价值\n\n`AiServices` 是 LangChain4j 框架的**高层核心API**，用于封装底层 LLM 交互的复杂逻辑，彻底规避底层 `ChatModel`、`ChatMessage`、`ChatMemory` 等组件的样板代码开发。\n\n其核心设计理念借鉴 Spring Data JPA、Retrofit 声明式编程思想：**开发者只需定义Java接口，框架自动生成代理实现类**，专注业务逻辑而非底层组件编排。\n\n相较于框架早期的 Chains（遗留链路），AiServices 具备更高的灵活性、可定制性，是官方主推的 LLM 应用开发方案，全面支持对话记忆、工具调用、RAG、结构化输出、流式响应等核心能力。\n\n### 1\\.2 核心特性总览\n\nAiServices 一站式支持以下 LLM 应用核心能力：\n\n- 声明式消息模板（静态\u002F动态系统提示、用户提示）\n\n- 会话记忆管理（全局共享记忆、多用户独立记忆）\n\n- 工具调用（静态工具、动态工具、并发工具执行、异常容错）\n\n- RAG 检索增强（基础检索、高阶检索增强器）\n\n- 流式响应、结构化输出（POJO\u002F枚举\u002F布尔值自动解析）\n\n- 内容自动审核、输入\u002F输出防护栅格\n\n- 事件监听、链路可观测、工具补偿机制\n\n## 二、核心设计架构\n\n### 2\\.1 类结构与核心成员\n\n`AiServices` 为**抽象构建器类**，采用 Builder 设计模式，所有配置方法支持链式调用，最终通过`build()` 生成代理实例。\n\n#### 核心成员变量\n\n- `AiServiceContext context`：核心上下文，存储所有配置信息（模型、记忆、工具、RAG、防护规则等）\n\n- `contentRetrieverSet\u002FretrievalAugmentorSet`：RAG 配置互斥标记，保证同一实例仅配置一种RAG模式\n\n#### 工厂机制\n\n通过静态内部类 `FactoryHolder` 实现 SPI 工厂加载，默认使用 `DefaultAiServices` 实现，支持自定义工厂扩展：\n\n- 优先加载 SPI 配置的 `AiServicesFactory`\n\n- 无自定义工厂时，使用框架默认实现 `DefaultAiServices`\n\n### 2\\.2 核心工作原理\n\n1. **接口定义**：开发者定义纯Java接口，通过注解\u002F方法参数声明AI能力\n\n2. **上下文初始化**：通过 `builder()` 初始化上下文，承载所有组件配置\n\n3. **代理生成**：框架通过反射生成接口代理类，封装底层调用逻辑\n\n4. **请求编排**：自动完成提示词渲染、记忆拼接、RAG检索、工具调用、参数转换\n\n5. **结果解析**：自动将LLM原始响应解析为声明的返回类型（字符串、POJO、枚举等）\n\n## 三、快速创建AI服务实例\n\nAiServices 提供两种实例创建方式，适配简单\u002F复杂场景\n\n### 3\\.1 极简创建方式（静态方法）\n\n适用于无复杂配置的基础对话场景，支持普通模型和流式模型\n\n```java\n\u002F\u002F 1. 普通对话模型\ninterface Assistant {\n    String chat(String userMessage);\n}\n\u002F\u002F 快速创建实例\nAssistant assistant = AiServices.create(Assistant.class, chatModel);\n\n\u002F\u002F 2. 流式对话模型（返回值必须为TokenStream）\ninterface StreamAssistant {\n    TokenStream chat(String userMessage);\n}\nStreamAssistant streamAssistant = AiServices.create(StreamAssistant.class, streamingChatModel);\n\n```\n\n### 3\\.2 构建器创建方式（推荐）\n\n适用于需要配置记忆、工具、RAG、防护规则的复杂场景，支持全量自定义配置\n\n```java\nAssistant assistant = AiServices.builder(Assistant.class)\n        .chatModel(chatModel) \u002F\u002F 绑定模型\n        .chatMemory(memory) \u002F\u002F 绑定会话记忆\n        .tools(new UserTools()) \u002F\u002F 绑定工具\n        .contentRetriever(retriever) \u002F\u002F 绑定RAG检索器\n        .moderationModel(moderationModel) \u002F\u002F 绑定内容审核\n        .build();\n\n```\n\n## 四、核心配置能力详解\n\n### 4\\.1 模型配置\n\nAiServices 严格限制**同一实例只能配置一种模型**（普通对话模型\u002F流式对话模型二选一）\n\n- `chatModel(ChatModel)`：配置普通LLM模型，用于同步对话\n\n- `streamingChatModel(StreamingChatModel)`：配置流式LLM模型，接口返回值必须为 `TokenStream`\n\n基础校验规则：构建时会校验模型非空，未配置模型将抛出 `illegalConfiguration` 异常\n\n### 4\\.2 提示词配置体系\n\n支持**静态注解、动态函数、消息转换器**三级提示词配置，优先级：注解 \\> 动态提供者 \\> 转换器\n\n#### 4\\.2\\.1 系统提示配置\n\n- **静态系统提示**：`systemMessage(String)` 固定系统提示词\n\n- **动态系统提示（按记忆ID）**：`systemMessageProvider(Function)` 根据会话ID动态生成提示\n\n- **动态系统提示（全上下文）**：`systemMessageProviderWithContext(Function)` 可感知模型、请求参数上下文\n\n- **系统提示转换器**：`systemMessageTransformer` 全局后置修改系统提示，支持追加\u002F覆盖内容\n\n#### 4\\.2\\.2 用户提示配置\n\n支持动态用户提示模板，可通过 `{{it}}` 或 `@V` 注解绑定方法参数，实现动态Prompt渲染\n\n### 4\\.3 会话记忆配置\n\n解决LLM无状态问题，支持两种记忆模式，**互斥配置**\n\n- **全局共享记忆**：`chatMemory(ChatMemory)` 所有请求共用一个记忆实例，适用于单会话场景\n\n- **多用户独立记忆**：`chatMemoryProvider(ChatMemoryProvider)`配合 `@MemoryId` 注解，按会话ID隔离记忆，适用于多用户场景\n\n重要注意事项：同一 `@MemoryId` 不支持并发调用，会导致记忆数据错乱，框架无并发防护机制，需业务层控制\n\n### 4\\.4 请求转换器配置\n\n`chatRequestTransformer` 支持在请求发送至LLM前，动态修改完整 `ChatRequest`，适用场景：追加全局上下文、动态修改请求参数、统一消息预处理\n\n- 单参数转换器：仅感知请求对象\n\n- 双参数转换器：同时感知请求对象和会话记忆ID\n\n### 4\\.5 内容审核配置\n\n通过 `moderationModel(ModerationModel)` 配置审核模型，配合 `@Moderate` 注解实现方法级内容审核，检测到违规内容抛出 `ModerationException`\n\n## 五、工具调用核心机制\n\nAiServices 提供业界完善的工具调用能力，支持静态注册、动态工具、并发执行、异常容错、工具搜索优化\n\n### 5\\.1 工具注册方式\n\n- **注解式静态工具**：注册带 `@Tool` 注解的Java对象，自动解析工具方法\n\n- **编程式工具**：手动绑定 `ToolSpecification` 和 `ToolExecutor`\n\n- **动态工具提供者**：`ToolProvider` 每次请求动态返回工具列表，适配动态场景\n\n### 5\\.2 工具执行优化\n\n- **并发执行**：`executeToolsConcurrently()` 开启多工具并发执行，支持自定义线程池\n\n- **最大轮次限制**：`maxToolCallingRoundTrips()` 限制LLM工具调用轮次，防止死循环（默认100轮）\n\n- **工具搜索策略**：`toolSearchStrategy` 延迟加载工具，减少每次请求的Token消耗\n\n### 5\\.3 工具异常容错机制\n\n针对工具调用全流程异常提供自定义处理器，解决LLM幻觉、参数错误、执行失败问题\n\n- **幻觉工具处理**：`hallucinatedToolNameStrategy` 处理LLM调用不存在工具的场景\n\n- **参数异常处理**：`toolArgumentsErrorHandler` 处理参数解析失败、缺失参数等问题，支持LLM自动重试\n\n- **执行异常处理**：`toolExecutionErrorHandler` 处理工具业务执行异常，支持脱敏错误信息，避免敏感数据泄露\n\n### 5\\.4 工具补偿机制\n\n`compensateOnToolErrors(boolean)` 开启工具故障补偿，工具执行失败时，反向执行已成功工具的补偿方法（`@CompensateFor`），实现事务回滚能力\n\n### 5\\.5 工具执行回调\n\n- `beforeToolExecution`：工具执行前回调，可做参数校验、日志记录\n\n- `afterToolExecution`：工具执行后回调，可做结果统计、异常监控\n\n## 六、RAG检索增强能力\n\nAiServices 原生集成RAG能力，提供两种配置模式，**互斥生效**，满足简单\u002F复杂检索场景\n\n### 6\\.1 基础检索模式\n\n`contentRetriever(ContentRetriever)`：快速配置检索器，框架自动封装为 `DefaultRetrievalAugmentor`，适用于简单的向量检索场景\n\n### 6\\.2 高阶检索模式\n\n`retrievalAugmentor(RetrievalAugmentor)`：自定义检索增强器，支持查询改写、路由、重排序、内容聚合、注入等全流程自定义，适配复杂企业级RAG场景\n\n### 6\\.3 记忆存储优化\n\n`storeRetrievedContentInChatMemory(boolean)` 配置是否将RAG检索后的增强消息存入会话记忆：\n\n- true（默认）：存储增强后消息，上下文连贯，但记忆体积更大\n\n- false：仅存储原始用户消息，减小内存占用，避免检索内容冗余堆积\n\n## 七、防护栅格机制（Guardrail）\n\n框架提供输入\u002F输出双层防护栅格，用于风险校验、prompt注入防御、输出合规校验，优先级低于注解配置\n\n### 7\\.1 输入防护栅格\n\n作用于用户原始输入，校验失败直接抛出 `GuardrailException`，不支持重试，适用于prompt注入、非法内容拦截\n\n支持三种配置方式：批量类配置、实例配置、数组\u002F列表批量注入\n\n### 7\\.2 输出防护栅格\n\n作用于LLM最终输出，支持**重试、重prompt**机制，校验失败可自动重试生成合规结果，适用于输出脱敏、格式校验、内容合规检测\n\n多防护栅格叠加时，任意一个触发重试\u002F重prompt，所有栅格将重新校验新响应结果\n\n## 八、可观测与事件监听\n\n支持AI服务全链路事件监听，实现日志统计、链路追踪、自定义监控能力\n\n- `registerListener\u002FregisterListeners`：注册单\u002F多个事件监听器\n\n- `unregisterListener\u002FunregisterListeners`：注销监听器，支持动态启停\n\n可监听事件包含：服务调用开始\u002F结束、工具执行、RAG检索、异常报错等全生命周期事件\n\n## 九、工具类静态方法\n\n### 9\\.1 消息过滤\n\n`removeToolMessages()`：过滤对话消息列表中的工具执行消息、工具调用请求消息，仅保留纯对话消息，用于上下文清理\n\n### 9\\.2 审核结果校验\n\n`verifyModerationIfNeeded()`：异步审核结果校验，捕获审核异常，统一抛出内容违规异常，适配异步审核场景\n\n## 十、核心约束与最佳实践\n\n### 10\\.1 配置互斥约束\n\n- 普通模型与流式模型二选一，不可同时配置\n\n- 基础检索器（contentRetriever）与高阶检索增强器（retrievalAugmentor）二选一\n\n- 全局记忆与多用户记忆提供者二选一\n\n### 10\\.2 并发约束\n\n同一 `@MemoryId` 禁止并发调用，框架无并发锁控制，需业务层加锁或限流，避免记忆数据错乱\n\n### 10\\.3 版本兼容说明\n\n- `maxSequentialToolsInvocations` 已废弃，推荐使用`maxToolCallingRoundTrips`\n\n- 旧版工具映射方法废弃，推荐使用 `tools(List\u003CAiServiceTool>)` 支持返回行为配置\n\n- 2\\.0版本将调整工具异常默认处理策略，由「抛出异常」改为「返回错误信息允许LLM重试」\n\n## 十一、核心能力落地示例\n\n### 11\\.1 多用户记忆示例\n\n```java\n\u002F\u002F 定义带会话ID的AI接口\ninterface UserAssistant {\n    String chat(@MemoryId Long userId, @UserMessage String message);\n}\n\n\u002F\u002F 构建多用户记忆AI服务\nUserAssistant assistant = AiServices.builder(UserAssistant.class)\n        .chatModel(model)\n        .chatMemoryProvider(id -> MessageWindowChatMemory.withMaxMessages(10))\n        .build();\n\n\u002F\u002F 不同用户独立会话\nassistant.chat(1L, \"我叫张三\");\nassistant.chat(2L, \"我叫李四\");\n\n```\n\n### 11\\.2 工具调用异常容错示例\n\n```java\nAiServices.builder(Assistant.class)\n        .chatModel(model)\n        .tools(new MathTools())\n        \u002F\u002F 工具参数异常返回友好提示，允许LLM重试\n        .toolArgumentsErrorHandler((error, ctx) -> ToolErrorHandlerResult.text(\"参数格式错误，请重新输入\"))\n        \u002F\u002F 执行异常脱敏，避免泄露内部信息\n        .toolExecutionErrorHandler((error, ctx) -> ToolErrorHandlerResult.text(\"工具执行失败，请稍后重试\"))\n        .build();\n\n```\n","markdown","453164986844323840",[],"LangChain4j AiServices 源码分析文档",{"frontmatter":40,"meta":41,"nodes":187},{},{"toc":42},{"title":4,"searchDepth":43,"depth":43,"links":44},5,[45,56,74,83,109,128,141,151,154,164,177],{"id":4,"depth":46,"text":47,"children":48},2,"一、概述",[49,53],{"id":50,"depth":51,"text":52},"-_11",3,"1.1 类定位与核心价值",{"id":54,"depth":51,"text":55},"-_12","1.2 核心特性总览",{"id":57,"depth":46,"text":58,"children":59},"-1","二、核心设计架构",[60,71],{"id":61,"depth":51,"text":62,"children":63},"-_21","2.1 类结构与核心成员",[64,68],{"id":65,"depth":66,"text":67},"-_21-",4,"核心成员变量",{"id":69,"depth":66,"text":70},"-_21--1","工厂机制",{"id":72,"depth":51,"text":73},"-_22","2.2 核心工作原理",{"id":32,"depth":46,"text":75,"children":76},"三、快速创建AI服务实例",[77,80],{"id":78,"depth":51,"text":79},"ai-_31","3.1 极简创建方式（静态方法）",{"id":81,"depth":51,"text":82},"ai-_32","3.2 构建器创建方式（推荐）",{"id":84,"depth":46,"text":85,"children":86},"-2","四、核心配置能力详解",[87,90,100,103,106],{"id":88,"depth":51,"text":89},"-_41","4.1 模型配置",{"id":91,"depth":51,"text":92,"children":93},"-_42","4.2 提示词配置体系",[94,97],{"id":95,"depth":66,"text":96},"-_42-_421","4.2.1 系统提示配置",{"id":98,"depth":66,"text":99},"-_42-_422","4.2.2 用户提示配置",{"id":101,"depth":51,"text":102},"-_43","4.3 会话记忆配置",{"id":104,"depth":51,"text":105},"-_44","4.4 请求转换器配置",{"id":107,"depth":51,"text":108},"-_45","4.5 内容审核配置",{"id":110,"depth":46,"text":111,"children":112},"-3","五、工具调用核心机制",[113,116,119,122,125],{"id":114,"depth":51,"text":115},"-_51","5.1 工具注册方式",{"id":117,"depth":51,"text":118},"-_52","5.2 工具执行优化",{"id":120,"depth":51,"text":121},"-_53","5.3 工具异常容错机制",{"id":123,"depth":51,"text":124},"-_54","5.4 工具补偿机制",{"id":126,"depth":51,"text":127},"-_55","5.5 工具执行回调",{"id":129,"depth":46,"text":130,"children":131},"rag","六、RAG检索增强能力",[132,135,138],{"id":133,"depth":51,"text":134},"rag-_61","6.1 基础检索模式",{"id":136,"depth":51,"text":137},"rag-_62","6.2 高阶检索模式",{"id":139,"depth":51,"text":140},"rag-_63","6.3 记忆存储优化",{"id":142,"depth":46,"text":143,"children":144},"guardrail","七、防护栅格机制（Guardrail）",[145,148],{"id":146,"depth":51,"text":147},"guardrail-_71","7.1 输入防护栅格",{"id":149,"depth":51,"text":150},"guardrail-_72","7.2 输出防护栅格",{"id":152,"depth":46,"text":153},"-4","八、可观测与事件监听",{"id":155,"depth":46,"text":156,"children":157},"-5","九、工具类静态方法",[158,161],{"id":159,"depth":51,"text":160},"-_91","9.1 消息过滤",{"id":162,"depth":51,"text":163},"-_92","9.2 审核结果校验",{"id":165,"depth":46,"text":166,"children":167},"-6","十、核心约束与最佳实践",[168,171,174],{"id":169,"depth":51,"text":170},"-_101","10.1 配置互斥约束",{"id":172,"depth":51,"text":173},"-_102","10.2 并发约束",{"id":175,"depth":51,"text":176},"-_103","10.3 版本兼容说明",{"id":178,"depth":46,"text":179,"children":180},"-7","十一、核心能力落地示例",[181,184],{"id":182,"depth":51,"text":183},"-_111","11.1 多用户记忆示例",{"id":185,"depth":51,"text":186},"-_112","11.2 工具调用异常容错示例",[188,191,194,218,225,228,230,233,258,260,262,275,278,292,294,305,318,320,357,359,362,364,367,375,377,380,385,387,389,396,413,420,422,429,431,470,472,483,485,491,515,521,523,533,541,543,557,559,562,564,598,600,629,631,634,663,665,675,677,691,693,700,702,712,714,720,722,728,736,738,741,743,750,753,755,762,765,767,770,784,787,789,791,797,799,805,807,809,820,822,828,830,851,853,855,860,862],[189,190,47],"h2",{"id":4},[192,193,52],"h3",{"id":50},[195,196,197,201,202,206,207,210,211,210,214,217],"p",{},[198,199,200],"code",{},"AiServices"," 是 LangChain4j 框架的",[203,204,205],"strong",{},"高层核心API","，用于封装底层 LLM 交互的复杂逻辑，彻底规避底层 ",[198,208,209],{},"ChatModel","、",[198,212,213],{},"ChatMessage",[198,215,216],{},"ChatMemory"," 等组件的样板代码开发。",[195,219,220,221,224],{},"其核心设计理念借鉴 Spring Data JPA、Retrofit 声明式编程思想：",[203,222,223],{},"开发者只需定义Java接口，框架自动生成代理实现类","，专注业务逻辑而非底层组件编排。",[195,226,227],{},"相较于框架早期的 Chains（遗留链路），AiServices 具备更高的灵活性、可定制性，是官方主推的 LLM 应用开发方案，全面支持对话记忆、工具调用、RAG、结构化输出、流式响应等核心能力。",[192,229,55],{"id":54},[195,231,232],{},"AiServices 一站式支持以下 LLM 应用核心能力：",[234,235,236,240,243,246,249,252,255],"ul",{},[237,238,239],"li",{},"声明式消息模板（静态\u002F动态系统提示、用户提示）",[237,241,242],{},"会话记忆管理（全局共享记忆、多用户独立记忆）",[237,244,245],{},"工具调用（静态工具、动态工具、并发工具执行、异常容错）",[237,247,248],{},"RAG 检索增强（基础检索、高阶检索增强器）",[237,250,251],{},"流式响应、结构化输出（POJO\u002F枚举\u002F布尔值自动解析）",[237,253,254],{},"内容自动审核、输入\u002F输出防护栅格",[237,256,257],{},"事件监听、链路可观测、工具补偿机制",[189,259,58],{"id":57},[192,261,62],{"id":61},[195,263,264,266,267,270,271,274],{},[198,265,200],{}," 为",[203,268,269],{},"抽象构建器类","，采用 Builder 设计模式，所有配置方法支持链式调用，最终通过",[198,272,273],{},"build()"," 生成代理实例。",[276,277,67],"h4",{"id":65},[234,279,280,286],{},[237,281,282,285],{},[198,283,284],{},"AiServiceContext context","：核心上下文，存储所有配置信息（模型、记忆、工具、RAG、防护规则等）",[237,287,288,291],{},[198,289,290],{},"contentRetrieverSet\u002FretrievalAugmentorSet","：RAG 配置互斥标记，保证同一实例仅配置一种RAG模式",[276,293,70],{"id":69},[195,295,296,297,300,301,304],{},"通过静态内部类 ",[198,298,299],{},"FactoryHolder"," 实现 SPI 工厂加载，默认使用 ",[198,302,303],{},"DefaultAiServices"," 实现，支持自定义工厂扩展：",[234,306,307,313],{},[237,308,309,310],{},"优先加载 SPI 配置的 ",[198,311,312],{},"AiServicesFactory",[237,314,315,316],{},"无自定义工厂时，使用框架默认实现 ",[198,317,303],{},[192,319,73],{"id":72},[321,322,323,329,339,345,351],"ol",{},[237,324,325,328],{},[203,326,327],{},"接口定义","：开发者定义纯Java接口，通过注解\u002F方法参数声明AI能力",[237,330,331,334,335,338],{},[203,332,333],{},"上下文初始化","：通过 ",[198,336,337],{},"builder()"," 初始化上下文，承载所有组件配置",[237,340,341,344],{},[203,342,343],{},"代理生成","：框架通过反射生成接口代理类，封装底层调用逻辑",[237,346,347,350],{},[203,348,349],{},"请求编排","：自动完成提示词渲染、记忆拼接、RAG检索、工具调用、参数转换",[237,352,353,356],{},[203,354,355],{},"结果解析","：自动将LLM原始响应解析为声明的返回类型（字符串、POJO、枚举等）",[189,358,75],{"id":32},[195,360,361],{},"AiServices 提供两种实例创建方式，适配简单\u002F复杂场景",[192,363,79],{"id":78},[195,365,366],{},"适用于无复杂配置的基础对话场景，支持普通模型和流式模型",[368,369,371],"pre",{"language":370},"java",[198,372,374],{"class":373},"language-java","\u002F\u002F 1. 普通对话模型\ninterface Assistant {\n    String chat(String userMessage);\n}\n\u002F\u002F 快速创建实例\nAssistant assistant = AiServices.create(Assistant.class, chatModel);\n\n\u002F\u002F 2. 流式对话模型（返回值必须为TokenStream）\ninterface StreamAssistant {\n    TokenStream chat(String userMessage);\n}\nStreamAssistant streamAssistant = AiServices.create(StreamAssistant.class, streamingChatModel);\n",[192,376,82],{"id":81},[195,378,379],{},"适用于需要配置记忆、工具、RAG、防护规则的复杂场景，支持全量自定义配置",[368,381,382],{"language":370},[198,383,384],{"class":373},"Assistant assistant = AiServices.builder(Assistant.class)\n        .chatModel(chatModel) \u002F\u002F 绑定模型\n        .chatMemory(memory) \u002F\u002F 绑定会话记忆\n        .tools(new UserTools()) \u002F\u002F 绑定工具\n        .contentRetriever(retriever) \u002F\u002F 绑定RAG检索器\n        .moderationModel(moderationModel) \u002F\u002F 绑定内容审核\n        .build();\n",[189,386,85],{"id":84},[192,388,89],{"id":88},[195,390,391,392,395],{},"AiServices 严格限制",[203,393,394],{},"同一实例只能配置一种模型","（普通对话模型\u002F流式对话模型二选一）",[234,397,398,404],{},[237,399,400,403],{},[198,401,402],{},"chatModel(ChatModel)","：配置普通LLM模型，用于同步对话",[237,405,406,409,410],{},[198,407,408],{},"streamingChatModel(StreamingChatModel)","：配置流式LLM模型，接口返回值必须为 ",[198,411,412],{},"TokenStream",[195,414,415,416,419],{},"基础校验规则：构建时会校验模型非空，未配置模型将抛出 ",[198,417,418],{},"illegalConfiguration"," 异常",[192,421,92],{"id":91},[195,423,424,425,428],{},"支持",[203,426,427],{},"静态注解、动态函数、消息转换器","三级提示词配置，优先级：注解 > 动态提供者 > 转换器",[276,430,96],{"id":95},[234,432,433,443,452,461],{},[237,434,435,438,439,442],{},[203,436,437],{},"静态系统提示","：",[198,440,441],{},"systemMessage(String)"," 固定系统提示词",[237,444,445,438,448,451],{},[203,446,447],{},"动态系统提示（按记忆ID）",[198,449,450],{},"systemMessageProvider(Function)"," 根据会话ID动态生成提示",[237,453,454,438,457,460],{},[203,455,456],{},"动态系统提示（全上下文）",[198,458,459],{},"systemMessageProviderWithContext(Function)"," 可感知模型、请求参数上下文",[237,462,463,438,466,469],{},[203,464,465],{},"系统提示转换器",[198,467,468],{},"systemMessageTransformer"," 全局后置修改系统提示，支持追加\u002F覆盖内容",[276,471,99],{"id":98},[195,473,474,475,478,479,482],{},"支持动态用户提示模板，可通过 ",[198,476,477],{},"{{it}}"," 或 ",[198,480,481],{},"@V"," 注解绑定方法参数，实现动态Prompt渲染",[192,484,102],{"id":101},[195,486,487,488],{},"解决LLM无状态问题，支持两种记忆模式，",[203,489,490],{},"互斥配置",[234,492,493,502],{},[237,494,495,438,498,501],{},[203,496,497],{},"全局共享记忆",[198,499,500],{},"chatMemory(ChatMemory)"," 所有请求共用一个记忆实例，适用于单会话场景",[237,503,504,438,507,510,511,514],{},[203,505,506],{},"多用户独立记忆",[198,508,509],{},"chatMemoryProvider(ChatMemoryProvider)","配合 ",[198,512,513],{},"@MemoryId"," 注解，按会话ID隔离记忆，适用于多用户场景",[195,516,517,518,520],{},"重要注意事项：同一 ",[198,519,513],{}," 不支持并发调用，会导致记忆数据错乱，框架无并发防护机制，需业务层控制",[192,522,105],{"id":104},[195,524,525,528,529,532],{},[198,526,527],{},"chatRequestTransformer"," 支持在请求发送至LLM前，动态修改完整 ",[198,530,531],{},"ChatRequest","，适用场景：追加全局上下文、动态修改请求参数、统一消息预处理",[234,534,535,538],{},[237,536,537],{},"单参数转换器：仅感知请求对象",[237,539,540],{},"双参数转换器：同时感知请求对象和会话记忆ID",[192,542,108],{"id":107},[195,544,545,546,549,550,553,554],{},"通过 ",[198,547,548],{},"moderationModel(ModerationModel)"," 配置审核模型，配合 ",[198,551,552],{},"@Moderate"," 注解实现方法级内容审核，检测到违规内容抛出 ",[198,555,556],{},"ModerationException",[189,558,111],{"id":110},[195,560,561],{},"AiServices 提供业界完善的工具调用能力，支持静态注册、动态工具、并发执行、异常容错、工具搜索优化",[192,563,115],{"id":114},[234,565,566,576,589],{},[237,567,568,571,572,575],{},[203,569,570],{},"注解式静态工具","：注册带 ",[198,573,574],{},"@Tool"," 注解的Java对象，自动解析工具方法",[237,577,578,581,582,585,586],{},[203,579,580],{},"编程式工具","：手动绑定 ",[198,583,584],{},"ToolSpecification"," 和 ",[198,587,588],{},"ToolExecutor",[237,590,591,438,594,597],{},[203,592,593],{},"动态工具提供者",[198,595,596],{},"ToolProvider"," 每次请求动态返回工具列表，适配动态场景",[192,599,118],{"id":117},[234,601,602,611,620],{},[237,603,604,438,607,610],{},[203,605,606],{},"并发执行",[198,608,609],{},"executeToolsConcurrently()"," 开启多工具并发执行，支持自定义线程池",[237,612,613,438,616,619],{},[203,614,615],{},"最大轮次限制",[198,617,618],{},"maxToolCallingRoundTrips()"," 限制LLM工具调用轮次，防止死循环（默认100轮）",[237,621,622,438,625,628],{},[203,623,624],{},"工具搜索策略",[198,626,627],{},"toolSearchStrategy"," 延迟加载工具，减少每次请求的Token消耗",[192,630,121],{"id":120},[195,632,633],{},"针对工具调用全流程异常提供自定义处理器，解决LLM幻觉、参数错误、执行失败问题",[234,635,636,645,654],{},[237,637,638,438,641,644],{},[203,639,640],{},"幻觉工具处理",[198,642,643],{},"hallucinatedToolNameStrategy"," 处理LLM调用不存在工具的场景",[237,646,647,438,650,653],{},[203,648,649],{},"参数异常处理",[198,651,652],{},"toolArgumentsErrorHandler"," 处理参数解析失败、缺失参数等问题，支持LLM自动重试",[237,655,656,438,659,662],{},[203,657,658],{},"执行异常处理",[198,660,661],{},"toolExecutionErrorHandler"," 处理工具业务执行异常，支持脱敏错误信息，避免敏感数据泄露",[192,664,124],{"id":123},[195,666,667,670,671,674],{},[198,668,669],{},"compensateOnToolErrors(boolean)"," 开启工具故障补偿，工具执行失败时，反向执行已成功工具的补偿方法（",[198,672,673],{},"@CompensateFor","），实现事务回滚能力",[192,676,127],{"id":126},[234,678,679,685],{},[237,680,681,684],{},[198,682,683],{},"beforeToolExecution","：工具执行前回调，可做参数校验、日志记录",[237,686,687,690],{},[198,688,689],{},"afterToolExecution","：工具执行后回调，可做结果统计、异常监控",[189,692,130],{"id":129},[195,694,695,696,699],{},"AiServices 原生集成RAG能力，提供两种配置模式，",[203,697,698],{},"互斥生效","，满足简单\u002F复杂检索场景",[192,701,134],{"id":133},[195,703,704,707,708,711],{},[198,705,706],{},"contentRetriever(ContentRetriever)","：快速配置检索器，框架自动封装为 ",[198,709,710],{},"DefaultRetrievalAugmentor","，适用于简单的向量检索场景",[192,713,137],{"id":136},[195,715,716,719],{},[198,717,718],{},"retrievalAugmentor(RetrievalAugmentor)","：自定义检索增强器，支持查询改写、路由、重排序、内容聚合、注入等全流程自定义，适配复杂企业级RAG场景",[192,721,140],{"id":139},[195,723,724,727],{},[198,725,726],{},"storeRetrievedContentInChatMemory(boolean)"," 配置是否将RAG检索后的增强消息存入会话记忆：",[234,729,730,733],{},[237,731,732],{},"true（默认）：存储增强后消息，上下文连贯，但记忆体积更大",[237,734,735],{},"false：仅存储原始用户消息，减小内存占用，避免检索内容冗余堆积",[189,737,143],{"id":142},[195,739,740],{},"框架提供输入\u002F输出双层防护栅格，用于风险校验、prompt注入防御、输出合规校验，优先级低于注解配置",[192,742,147],{"id":146},[195,744,745,746,749],{},"作用于用户原始输入，校验失败直接抛出 ",[198,747,748],{},"GuardrailException","，不支持重试，适用于prompt注入、非法内容拦截",[195,751,752],{},"支持三种配置方式：批量类配置、实例配置、数组\u002F列表批量注入",[192,754,150],{"id":149},[195,756,757,758,761],{},"作用于LLM最终输出，支持",[203,759,760],{},"重试、重prompt","机制，校验失败可自动重试生成合规结果，适用于输出脱敏、格式校验、内容合规检测",[195,763,764],{},"多防护栅格叠加时，任意一个触发重试\u002F重prompt，所有栅格将重新校验新响应结果",[189,766,153],{"id":152},[195,768,769],{},"支持AI服务全链路事件监听，实现日志统计、链路追踪、自定义监控能力",[234,771,772,778],{},[237,773,774,777],{},[198,775,776],{},"registerListener\u002FregisterListeners","：注册单\u002F多个事件监听器",[237,779,780,783],{},[198,781,782],{},"unregisterListener\u002FunregisterListeners","：注销监听器，支持动态启停",[195,785,786],{},"可监听事件包含：服务调用开始\u002F结束、工具执行、RAG检索、异常报错等全生命周期事件",[189,788,156],{"id":155},[192,790,160],{"id":159},[195,792,793,796],{},[198,794,795],{},"removeToolMessages()","：过滤对话消息列表中的工具执行消息、工具调用请求消息，仅保留纯对话消息，用于上下文清理",[192,798,163],{"id":162},[195,800,801,804],{},[198,802,803],{},"verifyModerationIfNeeded()","：异步审核结果校验，捕获审核异常，统一抛出内容违规异常，适配异步审核场景",[189,806,166],{"id":165},[192,808,170],{"id":169},[234,810,811,814,817],{},[237,812,813],{},"普通模型与流式模型二选一，不可同时配置",[237,815,816],{},"基础检索器（contentRetriever）与高阶检索增强器（retrievalAugmentor）二选一",[237,818,819],{},"全局记忆与多用户记忆提供者二选一",[192,821,173],{"id":172},[195,823,824,825,827],{},"同一 ",[198,826,513],{}," 禁止并发调用，框架无并发锁控制，需业务层加锁或限流，避免记忆数据错乱",[192,829,176],{"id":175},[234,831,832,841,848],{},[237,833,834,837,838],{},[198,835,836],{},"maxSequentialToolsInvocations"," 已废弃，推荐使用",[198,839,840],{},"maxToolCallingRoundTrips",[237,842,843,844,847],{},"旧版工具映射方法废弃，推荐使用 ",[198,845,846],{},"tools(List\u003CAiServiceTool>)"," 支持返回行为配置",[237,849,850],{},"2.0版本将调整工具异常默认处理策略，由「抛出异常」改为「返回错误信息允许LLM重试」",[189,852,179],{"id":178},[192,854,183],{"id":182},[368,856,857],{"language":370},[198,858,859],{"class":373},"\u002F\u002F 定义带会话ID的AI接口\ninterface UserAssistant {\n    String chat(@MemoryId Long userId, @UserMessage String message);\n}\n\n\u002F\u002F 构建多用户记忆AI服务\nUserAssistant assistant = AiServices.builder(UserAssistant.class)\n        .chatModel(model)\n        .chatMemoryProvider(id -> MessageWindowChatMemory.withMaxMessages(10))\n        .build();\n\n\u002F\u002F 不同用户独立会话\nassistant.chat(1L, \"我叫张三\");\nassistant.chat(2L, \"我叫李四\");\n",[192,861,186],{"id":185},[368,863,864],{"language":370},[198,865,866],{"class":373},"AiServices.builder(Assistant.class)\n        .chatModel(model)\n        .tools(new MathTools())\n        \u002F\u002F 工具参数异常返回友好提示，允许LLM重试\n        .toolArgumentsErrorHandler((error, ctx) -> ToolErrorHandlerResult.text(\"参数格式错误，请重新输入\"))\n        \u002F\u002F 执行异常脱敏，避免泄露内部信息\n        .toolExecutionErrorHandler((error, ctx) -> ToolErrorHandlerResult.text(\"工具执行失败，请稍后重试\"))\n        .build();\n"]