langchain4j DefaultAiServices源码解析

版本

0.28.0

源码

使用langchain4j，可以通过AiServices来封装聊天模型API，实现会话记忆，工具调用，搜索增强，内容审查等功能，并提供简单灵活的用户接口
DefaultAiServices是其默认实现类型，通过动态代理的方式实现用户定义的服务接口

class DefaultAiServices<T> extends AiServices<T> {


    private static final int MAX_SEQUENTIAL_TOOL_EXECUTIONS = 10;

    DefaultAiServices(AiServiceContext context) {
        super(context);
    }
	// 校验使用提示词模板发送消息的方法参数
    static void validateParameters(Method method) {
    	// 如果只有一个参数或者没有参数跳过检查（参数直接作为内容发送的方法/其他非发送内容的方法）
        Parameter[] parameters = method.getParameters();
        if (parameters == null || parameters.length < 2) {
            return;
        }
        for (Parameter parameter : parameters) {
        	// 获取应用于提示词模板的参数（带有V注解）
            V v = parameter.getAnnotation(V.class);
            // 获取用户消息模板参数
            dev.langchain4j.service.UserMessage userMessage = parameter.getAnnotation(dev.langchain4j.service.UserMessage.class);
            // 获取记忆ID参数
            MemoryId memoryId = parameter.getAnnotation(MemoryId.class);
            // 获取用户名参数
            UserName userName = parameter.getAnnotation(UserName.class);
            // 如果没有任何模板参数则报错
            if (v == null && userMessage == null && memoryId == null && userName == null) {
                throw illegalConfiguration(
                        "Parameter '%s' of method '%s' should be annotated with @V or @UserMessage or @UserName or @MemoryId",
                        parameter.getName(), method.getName()
                );
            }
        }
    }

    public T build() {
		// 基本校验
		// 1. 校验chatModel/streamingChatModel是否有值
		// 2. 校验toolSpecifications有值时上下文是否启用记忆（使用工具调用至少需要在记忆中保存3个消息）
        performBasicValidation();
		// 校验方法使用了Moderate时是否同时指定了审查模型（moderationModel）
        for (Method method : context.aiServiceClass.getMethods()) {
            if (method.isAnnotationPresent(Moderate.class) && context.moderationModel == null) {
                throw illegalConfiguration("The @Moderate annotation is present, but the moderationModel is not set up. " +
                        "Please ensure a valid moderationModel is configured before using the @Moderate annotation.");
            }
        }
		// 构造动态代理
        Object proxyInstance = Proxy.newProxyInstance(
                context.aiServiceClass.getClassLoader(),
                new Class<?>[]{context.aiServiceClass},
                new InvocationHandler() {

                    private final ExecutorService executor = Executors.newCachedThreadPool();

                    @Override
                    public Object invoke(Object proxy, Method method, Object[] args) throws Exception {
						// 直接执行Object类定义的方法
                        if (method.getDeclaringClass() == Object.class) {
                            // methods like equals(), hashCode() and toString() should not be handled by this proxy
                            return method.invoke(this, args);
                        }
						// 校验提示词模板参数
                        validateParameters(method);
						// 获取系统消息
                        Optional<SystemMessage> systemMessage = prepareSystemMessage(method, args);
                        // 获取用户消息
                        UserMessage userMessage = prepareUserMessage(method, args);
						// 获取记忆ID参数值，如果没有记忆ID参数则使用默认值“default”
                        Object memoryId = memoryId(method, args).orElse(DEFAULT);
						// 使用检索增强生成（RAG），将检索结果内容与用户原始消息文本整合作为用户消息
                        if (context.retrievalAugmentor != null) {
                            List<ChatMessage> chatMemory = context.hasChatMemory()
                                    ? context.chatMemory(memoryId).messages()
                                    : null;
                            Metadata metadata = Metadata.from(userMessage, memoryId, chatMemory);
                            userMessage = context.retrievalAugmentor.augment(userMessage, metadata);
                        }

                        // 用于提供客制化的输出解析，根据函数返回类型生成需要返回的消息格式的相关提示词，追加到用户消息里面
                        // 如果返回类型为String，AiMessage，TokenStream，Response则不追加格式提示词
                       	// 如果返回类型为void则报错
                       	// 如果返回类型为enum枚举类型，则追加提示词“\nYou must answer strictly in the following format: one of value1,value2,value3...,valueN”
                       	// 如果返回类型是 boolean/byte/short/int/long/BigInteger/float/double/BigDecimal/Date/LocalDate/LocalTime/LocalDateTime 或其对应包装类型，则追加对应值类型提示词，例如“\nYou must answer strictly in the following format: one of [true, false]” ,“...format: integer number in range [-128, 127]”
                       	// 如果返回类型是List/Set，则追加提示词“You must put every item on a separate line.”
                       	// 否则追加提示词，以json形式返回 “You must answer strictly in the following JSON format: {...}”
                        String outputFormatInstructions = outputFormatInstructions(method.getReturnType());
                        userMessage = UserMessage.from(userMessage.text() + outputFormatInstructions);
						// 如果包含聊天记忆，则在聊天记忆中追加系统消息和用户消息
                        if (context.hasChatMemory()) {
                            ChatMemory chatMemory = context.chatMemory(memoryId);
                            systemMessage.ifPresent(chatMemory::add);
                            chatMemory.add(userMessage);
                        }
						// 从记忆中获取消息清单或构建新的消息清单
                        List<ChatMessage> messages;
                        if (context.hasChatMemory()) {
                            messages = context.chatMemory(memoryId).messages();
                        } else {
                            messages = new ArrayList<>();
                            systemMessage.ifPresent(messages::add);
                            messages.add(userMessage);
                        }
						// 执行审查
                        Future<Moderation> moderationFuture = triggerModerationIfNeeded(method, messages);
						// 以流式处理消息
                        if (method.getReturnType() == TokenStream.class) {
                            return new AiServiceTokenStream(messages, context, memoryId); // 尚未实现响应内容审查，也不支持工具调用
                        }
						// 调用chatModel生成响应
                        Response<AiMessage> response = context.toolSpecifications == null
                                ? context.chatModel.generate(messages)
                                : context.chatModel.generate(messages, context.toolSpecifications);
                        // 获取token用量
                        TokenUsage tokenUsageAccumulator = response.tokenUsage();
						// 校验审查结果
                        verifyModerationIfNeeded(moderationFuture);
                        // 执行工具调用
						// 工具调用的最大执行次数（10）
                        int executionsLeft = MAX_SEQUENTIAL_TOOL_EXECUTIONS;
                        while (true) {
                            if (executionsLeft-- == 0) {
                                throw runtime("Something is wrong, exceeded %s sequential tool executions",
                                        MAX_SEQUENTIAL_TOOL_EXECUTIONS);
                            }
                            // 获取AI响应消息，添加到记忆中
                            AiMessage aiMessage = response.content();
                            if (context.hasChatMemory()) {
                                context.chatMemory(memoryId).add(aiMessage);
                            }
							// 如果不存在工具调用请求则中断
                            if (!aiMessage.hasToolExecutionRequests()) {
                                break;
                            }
							// 根据工具调用请求，依次调用工具，并将工具执行结果消息添加到记忆中
                            ChatMemory chatMemory = context.chatMemory(memoryId);							
                            for (ToolExecutionRequest toolExecutionRequest : aiMessage.toolExecutionRequests()) {
                                ToolExecutor toolExecutor = context.toolExecutors.get(toolExecutionRequest.name());
                                String toolExecutionResult = toolExecutor.execute(toolExecutionRequest, memoryId);
                                ToolExecutionResultMessage toolExecutionResultMessage = ToolExecutionResultMessage.from(
                                        toolExecutionRequest,
                                        toolExecutionResult
                                );
                                chatMemory.add(toolExecutionResultMessage);
                            }
							// 根据添加了工具执行结果的记忆再次调用模型生成
                            response = context.chatModel.generate(chatMemory.messages(), context.toolSpecifications);
                            // 累计token用量
                            tokenUsageAccumulator = tokenUsageAccumulator.add(response.tokenUsage());
                        }
						// 返回最终的响应
                        response = Response.from(response.content(), tokenUsageAccumulator, response.finishReason());
                        // 将响应解析为方法对应的返回类型对象
                        return parse(response, method.getReturnType());
                    }

                    private Future<Moderation> triggerModerationIfNeeded(Method method, List<ChatMessage> messages) {
                        if (method.isAnnotationPresent(Moderate.class)) {
                            return executor.submit(() -> {
                                List<ChatMessage> messagesToModerate = removeToolMessages(messages);
                                return context.moderationModel.moderate(messagesToModerate).content();
                            });
                        }
                        return null;
                    }
                });

        return (T) proxyInstance;
    }
	// 准备系统消息
    private Optional<SystemMessage> prepareSystemMessage(Method method, Object[] args) {
		// 获取提示词模板变量
        Parameter[] parameters = method.getParameters();
        Map<String, Object> variables = getPromptTemplateVariables(args, parameters);
		
        dev.langchain4j.service.SystemMessage annotation = method.getAnnotation(dev.langchain4j.service.SystemMessage.class);
        if (annotation != null) {
        	// 获取 SystemMessage 注解的系统消息提示词模板
            String systemMessageTemplate = getPromptText(
                    method,
                    "System",
                    annotation.fromResource(), // 提示词资源文件，如果没有则取value值
                    annotation.value(), // 提示词文本
                    annotation.delimiter() // 换行符
            );
			// 根据模板和变量获取提示词
            Prompt prompt = PromptTemplate.from(systemMessageTemplate).apply(variables);
            return Optional.of(prompt.toSystemMessage());
        }

        return Optional.empty();
    }
	// 准备用户消息
    private static UserMessage prepareUserMessage(Method method, Object[] args) {
        Parameter[] parameters = method.getParameters();
        Map<String, Object> variables = getPromptTemplateVariables(args, parameters);
        // 获取用户名参数
        String userName = getUserName(parameters, args);
        dev.langchain4j.service.UserMessage annotation = method.getAnnotation(dev.langchain4j.service.UserMessage.class);
        if (annotation != null) {
            String userMessageTemplate = getPromptText(
                    method,
                    "User",
                    annotation.fromResource(),
                    annotation.value(),
                    annotation.delimiter()
            );
			// 如果模板中使用了{{it}}占位符，则只允许使用一个模板参数
            if (userMessageTemplate.contains("{{it}}")) {
                if (parameters.length != 1) {
                    throw illegalConfiguration("Error: The {{it}} placeholder is present but the method does not have exactly one parameter. " +
                            "Please ensure that methods using the {{it}} placeholder have exactly one parameter.");
                }
                variables = singletonMap("it", toString(args[0]));
            }
            Prompt prompt = PromptTemplate.from(userMessageTemplate).apply(variables);
            if (userName != null) {
            	// 使用用户名构造用户消息
                return userMessage(userName, prompt.text());
            } else {
                return prompt.toUserMessage();
            }
        }
        // 方法如果没有UserMessage注解，查找使用UserMessage注解的参数，作为消息内容
        for (int i = 0; i < parameters.length; i++) {
            if (parameters[i].isAnnotationPresent(dev.langchain4j.service.UserMessage.class)) {
                String text = toString(args[i]);
                if (userName != null) {
                    return userMessage(userName, text);
                } else {
                    return userMessage(text);
                }
            }
        }
		// 如果完全没有参数则报错
        if (args == null || args.length == 0) {
            throw illegalConfiguration("Method should have at least one argument");
        }
		// 如果只有一个没有注解的参数，则作为消息内容
        if (args.length == 1) {
            String text = toString(args[0]);
            if (userName != null) {
                return userMessage(userName, text);
            } else {
                return userMessage(text);
            }
        }
        throw illegalConfiguration("For methods with multiple parameters, each parameter must be annotated with @V, @UserMessage, @UserName or @MemoryId");
    }
    // 根据方法提示词注解获取提示词文本
	// resource 提示词资源文件，如果没有则取value值
    // value 提示词文本
    // delimiter 分隔符（换行符）
    private static String getPromptText(Method method, String type, String resource, String[] value, String delimiter) {
        String messageTemplate;
        if (!resource.trim().isEmpty()) {
            messageTemplate = getResourceText(method.getDeclaringClass(), resource);
            if (messageTemplate == null) {
                throw illegalConfiguration("@%sMessage's resource '%s' not found", type, resource);
            }
        } else {
            messageTemplate = String.join(delimiter, value);
        }
        if (messageTemplate.trim().isEmpty()) {
            throw illegalConfiguration("@%sMessage's template cannot be empty", type);
        }
        return messageTemplate;
    }

    private static String getResourceText(Class<?> clazz, String name) {
        return getText(clazz.getResourceAsStream(name));
    }

    private static String getText(InputStream inputStream) {
        if (inputStream == null) {
            return null;
        }
        try (Scanner scanner = new Scanner(inputStream);
             Scanner s = scanner.useDelimiter("\\A")) {
            return s.hasNext() ? s.next() : "";
        }
    }

    private Optional<Object> memoryId(Method method, Object[] args) {
        Parameter[] parameters = method.getParameters();
        for (int i = 0; i < parameters.length; i++) {
            if (parameters[i].isAnnotationPresent(MemoryId.class)) {
                Object memoryId = args[i];
                if (memoryId == null) {
                    throw illegalArgument("The value of parameter %s annotated with @MemoryId in method %s must not be null",
                            parameters[i].getName(), method.getName());
                }
                return Optional.of(memoryId);
            }
        }
        return Optional.empty();
    }
	// 获取用户名参数
    private static String getUserName(Parameter[] parameters, Object[] args) {
        for (int i = 0; i < parameters.length; i++) {
            if (parameters[i].isAnnotationPresent(UserName.class)) {
                return args[i].toString();
            }
        }
        return null;
    }
	// 获取提示词模板变量
	// 遍历V注解的变量，返回变量名和变量值映射
    private static Map<String, Object> getPromptTemplateVariables(Object[] args, Parameter[] parameters) {
        Map<String, Object> variables = new HashMap<>();
        for (int i = 0; i < parameters.length; i++) {
            V varAnnotation = parameters[i].getAnnotation(V.class);
            if (varAnnotation != null) {
                String variableName = varAnnotation.value();
                Object variableValue = args[i];
                variables.put(variableName, variableValue);
            }
        }
        return variables;
    }

    private static String toString(Object arg) {
        if (arg.getClass().isArray()) {
            return arrayToString(arg);
        } else if (arg.getClass().isAnnotationPresent(StructuredPrompt.class)) {
            return StructuredPromptProcessor.toPrompt(arg).text();
        } else {
            return arg.toString();
        }
    }

    private static String arrayToString(Object arg) {
        StringBuilder sb = new StringBuilder("[");
        int length = Array.getLength(arg);
        for (int i = 0; i < length; i++) {
            sb.append(toString(Array.get(arg, i)));
            if (i < length - 1) {
                sb.append(", ");
            }
        }
        sb.append("]");
        return sb.toString();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344