质量保障接口测试测试后端前端AI 应用DevOps【免费下载链接】metersphereMeterSphere 是新一代的开源持续测试工具内置 AI 助手让软件测试工作更简单、更高效不再成为持续交付的瓶颈。项目地址https://gitcode.com/gh_mirrors/me/metersphere点击查看免费下载MeterSphere 新一代开源持续测试工具内置了 AI 助手而支撑其对话能力的技术底座就是位于backend/framework/ai-engine的metersphere-ai-engine模块。它是一套可扩展的多模型 AI 聊天引擎负责屏蔽不同大模型厂商 API 的差异为上层业务提供统一的聊天调用入口并附带对话记忆、工具调用、日志顾问、文本清洗与摘要等实用能力。读完本文你将掌握该引擎的模块划分、模型注册与动态路由原理、AIChatOptions全部配置项及其取值范围并能基于ChatToolEngine的 Builder 链式 API 写出可运行的流式/结构化聊天代码同时理解引擎内置的提示词工程思路链 CoT设计思路。一、引擎定位为 MeterSphere 接入多种 AI 聊天模型metersphere-ai-engineMaven 坐标见 backend/framework/ai-engine/pom.xml是一个用于实现多种 AI 聊天模型的引擎提供与不同 AI 聊天服务的集成支持从多种聊天服务获取响应。它采用模块化设计便于扩展和集成不同的 AI 聊天模型。引擎的设计目标可以归纳为三点可扩展提供统一的抽象框架支持不同聊天模型OpenAI、DeepSeek、ZhiPu AI 等的接入利用不同的 AI 接口实现聊天功能可复用在聊天过程中提供各种实用工具——文本清理、关键词去重、TextRank 摘要、日志记录等避免各业务模块重复造轮子可观测通过 Advisor顾问机制在请求前后插入日志记录逻辑方便调试与监控。从依赖上看该模块基于 Spring AI 生态构建pom.xml 中引入了spring-ai-client-chat、spring-ai-openai、spring-ai-zhipuai以及spring-ai-starter-model-chat-memory-repository-jdbcJDBC 对话记忆仓库同时引入ansj_seg作为中文分词组件、flexmark-all作为 Markdown 解析组件并依赖同仓库的metersphere-sdk提供日志、JSON 等基础能力。二、整体架构与模块划分引擎代码位于包io.metersphere.ai.engine下目录结构如下与实际源码一致backend/framework/ai-engine/src/main/java/io/metersphere/ai/engine/ ├── ChatToolEngine.java # 核心引擎处理聊天请求与响应支持工具、记忆、流式与结构化输出 ├── advisor/ │ ├── LoggingCallAdvisor.java # 非流式请求的日志顾问 │ └── LoggingStreamAdvisor.java # 流式请求的日志顾问 ├── common/ │ ├── AIChatClient.java # AI 聊天客户端抽象基类 │ ├── AIChatOptions.java # 聊天选项配置类 │ ├── AIModelParamType.java # 模型参数类型定义 │ ├── AIModelType.java # AI 模型类型常量 │ └── AIRegister.java # 模型注册注解 ├── holder/ │ └── ChatClientHolder.java # 模型客户端注册表与分发器 ├── models/ │ ├── AIDeepSeekChatClient.java # DeepSeek 客户端实现 │ ├── AIOpenAIChatClient.java # OpenAI 客户端实现 │ └── AIZhiPuAiChatClient.java # ZhiPu AI 客户端实现 ├── tools/ │ ├── DateTimeTool.java # 获取当前时间的工具 │ ├── IntegrateTool.java # 工具结果集成工具 │ └── JvmTool.java # JVM 信息查询工具 └── utils/ ├── KeywordDeduplication.java # 基于关键词覆盖的文本去重 ├── TextCleaner.java # 文本清理HTML/URL/表情/控制字符等 └── TextRankSummarizer.java # 基于 TextRank 的自动摘要各模块职责可以概括为下表模块核心类职责核心引擎ChatToolEngine负责处理聊天请求与响应集成记忆、工具、系统角色提供同步/流式/结构化四种执行方式顾问层LoggingCallAdvisor、LoggingStreamAdvisor记录请求与响应日志帮助开发人员在调试和监控中跟踪分析数据公共层AIChatClient、AIChatOptions、AIModelType、AIRegister定义客户端抽象、配置模型、模型类型常量与注册注解持有层ChatClientHolder扫描并注册各模型客户端按模型类型动态分发模型层AIDeepSeekChatClient等各厂商 API 的具体实现工具层DateTimeTool、JvmTool、IntegrateTool供大模型调用的外部工具Function Calling工具类TextCleaner、KeywordDeduplication、TextRankSummarizer聊天文本的后处理能力说明engine.md原文档结构图中提到的FileReaderTool.java文件读取工具与AIQianFanChatClient.java千帆客户端在当前仓库源码中暂未出现从源码结构看当前 models 包只包含 DeepSeek、OpenAI、ZhiPu 三个实现但AIModelType仍保留了QIAN_FAN常量为后续接入千帆预留了位置。三、核心引擎 ChatToolEngineBuilder 模式的链式调用ChatToolEngine源码见 ChatToolEngine.java是引擎的对外门面采用经典的 Builder 模式。静态入口方法签名为public static Builder builder(String modelType, AIChatOptions options)modelType对应 AIModelType 中的常量如AIModelType.OPEN_AIoptions则承载 API Key、模型名、采样参数等配置。3.1 四种执行方式Builder 内部持有 Spring AI 的ChatClient并提供四种执行方式源码 ChatToolEngine.java方法返回类型适用场景execute()String同步调用直接返回响应文本executeChatResponse()ChatResponse同步调用返回包含元数据与用量信息的完整响应对象executeStream()FluxString流式调用适合打字机效果的实时输出executeStructured(ClassT)/executeStructured(ParameterizedTypeReferenceT)T将模型输出结构化解析为指定 Java 类型// 同步文本 String answer ChatToolEngine.builder(modelType, options) .addPrompt(介绍一下 MeterSphere) .execute(); // 流式输出 FluxString stream ChatToolEngine.builder(modelType, options) .addPrompt(写一首诗) .executeStream(); // 结构化输出把响应直接映射为对象 BugReport report ChatToolEngine.builder(modelType, options) .addPrompt(根据测试结果生成缺陷报告) .executeStructured(BugReport.class);3.2 对话记忆Builder 默认内置了对话记忆ChatToolEngine.javaChatMemory chatMemory MessageWindowChatMemory.builder() .chatMemoryRepository(new InMemoryChatMemoryRepository()) .maxMessages(10) .build();即默认使用内存型仓库、窗口最多保留 10 条消息同时 pom.xml 引入了spring-ai-starter-model-chat-memory-repository-jdbc说明生产环境可以替换为 JDBC 持久化仓库。通过addMemory(conversationId, msg)可以将用户消息写入指定会话的记忆中多个请求间复用同一会话 ID 即可实现多轮上下文对话。3.3 工具调用tools(Object... tools)支持传入任意数量的工具对象引擎会在请求构建阶段通过request.tools(...)将它们注册给模型Function Calling例如.tools(new DateTimeTool(), new JvmTool())3.4 系统角色与请求构建顺序system(String system)用于设定系统角色System Prompt例如 你是一位资深测试工程师。prompt(String)/addPrompt(...)设置用户提示。最终请求的构建顺序源码 ChatToolEngine.java为若配置了聊天记忆添加PromptChatMemoryAdvisor记忆顾问若存在系统消息添加系统级提示system为空或空白时自动忽略添加用户提示若配置了工具列表启用对应工具。3.5 参数校验规则引擎对输入有明确的校验逻辑写代码时需注意prompt未设置或为空时执行会抛出IllegalStateException(Prompt must be set before execution.)buildRequest用户提示为 null 或仅含空白字符时RequestBuilder会抛出IllegalArgumentException(Prompt cannot be empty)工具列表与记忆为 null/空时自动忽略对应配置不会报错。四、模型注册与动态路由AIRegister ChatClientHolder引擎的多模型支持建立在「注解注册 运行时扫描」的机制之上。4.1 模型类型常量AIModelType 定义了引擎支持的模型类型字符串常量public static final String DEEP_SEEK DeepSeek; public static final String OPEN_AI Open AI; public static final String ZHI_PU_AI ZhiPu AI; public static final String QIAN_FAN QianFan; public static final String OLLAMA Ollama;注意这些常量是提供商类型Provider而AIChatOptions.modelType是具体模型名如gpt-3.5-turbo、deepseek-chat。4.2 注册注解与客户端分发AIRegister 是一个作用于类上的运行时注解用value()声明模型类型键Retention(RetentionPolicy.RUNTIME) Target(ElementType.TYPE) public interface AIRegister { String value(); }各模型实现类通过AIRegister(...)Component双重标注完成注册例如AIRegister(AIModelType.OPEN_AI)→AIOpenAIChatClientAIRegister(AIModelType.DEEP_SEEK)→AIDeepSeekChatClientAIRegister(AIModelType.ZHI_PU_AI)→AIZhiPuAiChatClientChatClientHolder 在构造时通过 SpringApplicationContext.getBeansOfType(AIChatClient.class)扫描所有AIChatClient类型的 Bean读取AIRegister注解的 value 作为 key构建MapString, AIChatClient MODEL_MAP。分发入口getChatClient(modelType, options)负责两件事按模型类型从映射中取出对应客户端实现查不到时抛出IllegalArgumentException(不支持的聊天模型类型: modelType)调用该实现的chatClient(options)生成并返回配置完成的ChatClient。这意味着要接入一个新的模型提供商只需新增一个继承AIChatClient的类打上AIRegister与Component注解即可引擎无需任何改动——这正是模块化设计的核心价值。4.3 三个模型实现类的差异三个实现类都继承抽象基类AIChatClientAIChatClient.java并实现chatClient(AIChatOptions)与chatModel(AIChatOptions)两个抽象方法AIOpenAIChatClient源码通过OpenAiApi.builder().apiKey(...).baseUrl(...)构建 API 客户端并额外向请求头注入Accept-Encoding: gzip, deflate以启用压缩传输AIDeepSeekChatClient源码复用 OpenAI 协议栈同样基于OpenAiApi/OpenAiChatModel构建仅模型名不同——这解释了为什么 DeepSeek 客户端与 OpenAI 客户端的实现如此相似AIZhiPuAiChatClient源码使用 Spring AI 专门的ZhiPuAiApi/ZhiPuAiChatModel其chatClient中直接把topP、temperature、maxTokens三个参数写入ZhiPuAiChatOptions。五、配置体系 AIChatOptions 详解AIChatOptions 使用 LombokData注解提供 builder 与 getter/setter。完整字段及说明如下字段类型含义与取值约束baseUrlStringAPI 接口地址如 OpenAI/DeepSeek 的端点apiKeyString调用密钥modelTypeString具体模型名如deepseek-chat、gpt-3.5-turbodisableLoggingAdvisorboolean是否关闭日志顾问默认false开启置true关闭temperaturedouble采样温度控制输出随机性取值0 ~ 2.0frequencyPenaltydouble频率惩罚正值降低模型逐字重复同一行的可能取值-2.0 ~ 2.0maxTokensInteger生成的最大 token 数受模型上下文长度限制topPdouble核采样参数0.1 表示只考虑概率质量排名前 10% 的 token取值0.1 ~ 1参数校验发生在抽象基类 AIChatClient.builderChatOptions 中// 温度仅 0~2.0 范围内的值会被应用 Optional.of(options.getTemperature()) .filter(temperature - temperature 0 temperature 2.0) .ifPresent(optionsBuilder::temperature); // frequencyPenalty仅 -2.0~2.0 范围内生效 // maxTokens非 null 即生效 // topP仅 0.1~1 范围内生效超出范围的采样参数会被静默忽略因此建议在业务层先做好入参校验。另外官方建议不要同时修改 temperature 与 topP二者相互作用难以预测该说明直接保留在AIChatOptions的字段注释中。六、日志顾问Advisor请求全链路可观测AIChatClient.addAdvisor源码统一为每个 ChatClient 注册两个默认顾问Optional.of(options) .filter(opt - !opt.isDisableLoggingAdvisor()) .ifPresent(opt - builder.defaultAdvisors(new LoggingStreamAdvisor(), new LoggingCallAdvisor()));LoggingCallAdvisor源码实现CallAdvisor在adviseCall中先把ChatClientRequest序列化为格式化 JSON 打印LogUtils.info(Request: {})再放行到拦截器链getOrder()返回 0 表示较高优先级LoggingStreamAdvisor实现StreamAdvisor对流式请求做同样的日志记录。想要关闭日志例如生产环境避免敏感 Prompt 落盘只需在AIChatOptions中设置disableLoggingAdvisor true。七、内置工具集 tools让模型调用系统能力工具层用于把引擎运行时的系统能力暴露给大模型Function Calling三个工具都使用 Spring AI 的Tool注解声明DateTimeTool源码提供getCurrentDateTime()返回当前时区的时间戳System.currentTimeMillis()用于回答现在几点明天是什么时候这类时间问题JvmTool源码通过ManagementFactory与Runtime收集 JVM 信息——包括 JVM 名称/版本/启动与运行时长/JVM 参数、堆内存初始化/最大/已用量、可用处理器数、操作系统名称与架构并以格式化的文本块返回适合运维问答类场景IntegrateTool源码注意其Tool注解带有returnDirect true表示工具返回结果直接作为最终答案输出不再交给模型二次加工例如把DateTimeTool与JvmTool的结果拼接后直接返回。八、文本处理工具箱 utils这三个工具类为聊天文本的输入清洗 - 去重 - 摘要提供完整链路TextCleaner源码提供分层清理 API方法功能basicClean清除控制字符、符号、格式字符及零宽字符advancedClean仅保留字母/数字/空白与白名单符号-_%/:#.,;!?()[]{}removeHtmlTags/removeUrls/removeEmojis移除 HTML 标签、URL 与 emojiunifySymbols中文引号/书名号转英文符号removeDuplicateLines/deduplicateText删除重复行/重复文本prepareForSummarization为摘要准备的清洗保留句子标点结构fullClean组合上述步骤的完整清理流程processLargeText逐行流式处理大文本降低内存占用truncate截断到指定长度KeywordDeduplication源码使用 Ansj 分词仅提取名词与动词作为关键词再依据关键词集合包含关系判断冗余——若文本 A 的关键词完全覆盖文本 B则判定 B 为重复并剔除。deduplicateText先按中英文逗号/句号切分段落再逐段去重。TextRankSummarizer源码实现了经典的 TextRank 摘要算法完整流水线为按。!?分句用 Ansj 分词后计算句子间Jaccard 相似度构建相似度矩阵以阻尼系数d 0.85、迭代 20 次计算每个句子的 TextRank 分数选取分数最高的 N 个句子按原文顺序拼接成摘要。调用方式TextRankSummarizer.summarize(text, sentenceCount)默认提取 1 句。这些工具类在引擎中被TextCleaner.fullClean / prepareForSummarization直接串联调用构成清洗 → 去重 → 摘要的文本后处理管线。九、从引擎到业务在 system-setting 中的实际接入引擎并非孤立的框架模块MeterSphere 的 AI 服务层已经直接消费它。以 AiChatBaseService.java 为例业务侧的核心调用链是private ChatClient getClient(AiModelSourceDTO model) { return ChatToolEngine.builder(model.getProviderName(), getAiChatOptions(model)) .getChatClient(); }其中getAiChatOptions(model)把用户在系统设置中配置的模型来源信息映射为引擎的AIChatOptionsaiChatOptions.setModelType(model.getBaseName()); // 具体模型名 aiChatOptions.setApiKey(model.getAppKey()); // 密钥 aiChatOptions.setBaseUrl(model.getApiUrl()); // 接口地址同时该服务还实现了两种聊天模式chat(aiChatOption)不记忆对话直接prompt().user(...).call()chatWithMemory(aiChatOption)带记忆聊天通过MessageChatMemoryAdvisor并传入conversationId实现多轮上下文且可选system系统提示。此外服务层还通过AiConversationContentMapper将用户/助手的对话内容持久化到数据库saveUserConversationContent/saveAssistantConversationContent形成AI 引擎 会话记忆 落库的完整闭环。由此可见引擎只负责怎么调模型而记忆策略、会话持久化、模型来源管理由上层业务服务编排职责边界清晰。十、完整实战示例下面给出一个可直接对照引擎 API 运行的完整示例与原文档使用说明一致仅将示例中的AiChatOptions修正为源码中的实际类名AIChatOptionsChatResponse response ChatToolEngine.builder(AIModelType.OPEN_AI, AIChatOptions.builder() .modelType(deepseek-chat) // 具体模型名可与提供商不同 .apiKey(sk-xxx) // API 密钥 .baseUrl(url) // 接口地址 .temperature(0.7) // 采样温度0~2.0 .maxTokens(1024) // 最大输出 token 数 .topP(0.9) // 核采样0.1~1 .build()) .system(你是一名资深的软件测试工程师请用简洁专业的中文回答。) .addPrompt(明天时间是多少) .tools(new DateTimeTool()) // 注册时间工具模型可调用 .executeChatResponse(); // 返回完整 ChatResponse 对象再给出一个带记忆的多轮对话示例String conversationId conv-001; // 第一轮写入记忆并提问 ChatToolEngine.builder(AIModelType.DEEP_SEEK, options) .addMemory(conversationId, 我的项目是 MeterSphere) .addPrompt(请记住我刚才说的项目名) .execute(); // 第二轮同一会话 ID模型能回忆起上文 String answer ChatToolEngine.builder(AIModelType.DEEP_SEEK, options) .addPrompt(我刚刚说的是哪个项目) .execute();流式输出示例Reactor Flux前端可订阅逐字渲染FluxString flux ChatToolEngine.builder(AIModelType.ZHI_PU_AI, options) .addPrompt(请用流式方式回答什么是持续测试) .executeStream(); flux.subscribe(System.out::print);十一、提示词工程思路链CoT引擎文档专门开辟了提示词工程章节强调思路链Chain-of-ThoughtCoT技巧思路链提示鼓励模型逐步推理问题从而提高复杂推理任务的准确性。通过明确要求模型展示其工作成果或以逻辑步骤思考问题可以显著提高需要多步骤推理的任务的性能。CoT 的工作原理是鼓励模型在得出最终答案之前生成中间推理步骤类似于人类解决复杂问题的方式这使得模型的思维过程更加清晰并有助于其得出更准确的结论。典型的 Prompt 句式是让我们一步步解决这个问题配合结构化编号让推理过程显性化。原文档给出的完整示例经典年龄差问题让我们一步步解决这个问题 1. **确定过去年龄** 当我3岁时我的伙伴的年龄是我的三倍即 3 * 3 9岁。 2. **计算年龄差** 当时我的伙伴比我大 9 - 3 6岁。这个年龄差是固定的因为我们都以相同的速度变老。 3. **当前年龄** 现在我20岁。因为年龄差保持不变我的伙伴的年龄是 20 6 26岁。 4. **验证** 从我3岁到20岁过去了 20 - 3 17年。 我的伙伴当时的年龄是9岁17年后9 17 26岁与计算一致。 **答案**我的伙伴现在26岁。在实际使用引擎时可以将 CoT 模板放进system()或prompt()String cotPrompt 让我们一步步解决这个问题 1. 明确已知条件 2. 列出计算步骤 3. 给出验证过程 4. 输出最终答案 ;结合引擎的system()设置角色约束、tools()挂载可计算的工具如DateTimeToolCoT 可以与 Function Calling 协同工作——模型先调用工具拿到事实数据再按步骤推理能进一步降低幻觉概率。十二、扩展新模型与注意事项12.1 如何接入一个新的模型提供商基于前文分析接入新模型只需四步仓库只读此处仅说明扩展思路在 AIModelType 中新增提供商常量如OLLAMA已预置新增一个类继承AIChatClient实现chatClient与chatModel两个方法在类上标注AIRegister(AIModelType.XXX)与Component若厂商协议兼容 OpenAI可直接复用OpenAiApi/OpenAiChatModel参考AIDeepSeekChatClient的做法。ChatClientHolder的构造器会自动扫描注册业务侧无需修改任何调用代码。12.2 使用注意事项AIModelType与modelType是两个概念前者是提供商类型Builder 的第一个参数后者是具体模型名AIChatOptions.modelType二者可以不同如官方示例中 Provider 用 OPEN_AI、模型名用 deepseek-chat采样参数有取值范围约束越界会被静默忽略temperature 0~2.0、frequencyPenalty -2.0~2.0、topP 0.1~1建议业务层先行校验默认记忆为内存实现且窗口上限 10 条消息生产环境多实例部署时应替换为 JDBC 等持久化记忆仓库disableLoggingAdvisor true可以关闭请求日志包含敏感 Prompt 的业务场景建议评估是否开启原文档提到的FileReaderTool与AIQianFanChatClient在当前源码中尚未落地以 models 与 tools 目录下实际存在的类为准。总而言之metersphere-ai-engine以抽象基类 注解注册 Builder 门面的三层设计把多厂商大模型接入成本压缩到了极致上层业务只需关心AIChatOptions配置与ChatToolEngine的链式调用即可获得同步、流式、结构化、带记忆、带工具的完整聊天能力这也是 MeterSphere AI 助手能够快速集成 DeepSeek、OpenAI、ZhiPu AI 等多家模型的技术基础。赞分享质量保障接口测试测试后端前端AI 应用DevOps【免费下载链接】metersphereMeterSphere 是新一代的开源持续测试工具内置 AI 助手让软件测试工作更简单、更高效不再成为持续交付的瓶颈。项目地址https://gitcode.com/gh_mirrors/me/metersphere点击查看免费下载相关推荐SafeEyes核心功能大揭秘智能休息提醒、多屏幕支持与自定义界面SafeEyes核心功能大揭秘智能休息提醒、多屏幕支持与自定义界面 SafeEyes是一款简单而美观的开源护眼工具通过智能休息提醒帮助用户预防眼疲劳。它不仅桌面应用koboldcpp技术深度解析跨平台AI模型推理引擎架构设计与实现koboldcpp技术深度解析跨平台AI模型推理引擎架构设计与实现 GGML/GGUF模型的高效部署一直是AI开发者的痛点koboldcpp通过创新的跨平台人工智能大模型本地部署模型推理服务PromptX框架深度解析AI提示词管理的架构设计与核心原理PromptX框架深度解析AI提示词管理的架构设计与核心原理 PromptX是一个模式驱动的AI提示词管理框架它通过元提示词技术让开发者能够快速构建领域专用人工智能大模型AI 应用提示工程MCP 服务AI 插件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
质量保障接口测试测试后端前端AI 应用DevOps【免费下载链接】metersphereMeterSphere 是新一代的开源持续测试工具内置 AI 助手让软件测试工作更简单、更高效不再成为持续交付的瓶颈。项目地址https://gitcode.com/gh_mirrors/me/metersphere点击查看免费下载MeterSphere 新一代开源持续测试工具内置了 AI 助手而支撑其对话能力的技术底座就是位于backend/framework/ai-engine的metersphere-ai-engine模块。它是一套可扩展的多模型 AI 聊天引擎负责屏蔽不同大模型厂商 API 的差异为上层业务提供统一的聊天调用入口并附带对话记忆、工具调用、日志顾问、文本清洗与摘要等实用能力。读完本文你将掌握该引擎的模块划分、模型注册与动态路由原理、AIChatOptions全部配置项及其取值范围并能基于ChatToolEngine的 Builder 链式 API 写出可运行的流式/结构化聊天代码同时理解引擎内置的提示词工程思路链 CoT设计思路。一、引擎定位为 MeterSphere 接入多种 AI 聊天模型metersphere-ai-engineMaven 坐标见 backend/framework/ai-engine/pom.xml是一个用于实现多种 AI 聊天模型的引擎提供与不同 AI 聊天服务的集成支持从多种聊天服务获取响应。它采用模块化设计便于扩展和集成不同的 AI 聊天模型。引擎的设计目标可以归纳为三点可扩展提供统一的抽象框架支持不同聊天模型OpenAI、DeepSeek、ZhiPu AI 等的接入利用不同的 AI 接口实现聊天功能可复用在聊天过程中提供各种实用工具——文本清理、关键词去重、TextRank 摘要、日志记录等避免各业务模块重复造轮子可观测通过 Advisor顾问机制在请求前后插入日志记录逻辑方便调试与监控。从依赖上看该模块基于 Spring AI 生态构建pom.xml 中引入了spring-ai-client-chat、spring-ai-openai、spring-ai-zhipuai以及spring-ai-starter-model-chat-memory-repository-jdbcJDBC 对话记忆仓库同时引入ansj_seg作为中文分词组件、flexmark-all作为 Markdown 解析组件并依赖同仓库的metersphere-sdk提供日志、JSON 等基础能力。二、整体架构与模块划分引擎代码位于包io.metersphere.ai.engine下目录结构如下与实际源码一致backend/framework/ai-engine/src/main/java/io/metersphere/ai/engine/ ├── ChatToolEngine.java # 核心引擎处理聊天请求与响应支持工具、记忆、流式与结构化输出 ├── advisor/ │ ├── LoggingCallAdvisor.java # 非流式请求的日志顾问 │ └── LoggingStreamAdvisor.java # 流式请求的日志顾问 ├── common/ │ ├── AIChatClient.java # AI 聊天客户端抽象基类 │ ├── AIChatOptions.java # 聊天选项配置类 │ ├── AIModelParamType.java # 模型参数类型定义 │ ├── AIModelType.java # AI 模型类型常量 │ └── AIRegister.java # 模型注册注解 ├── holder/ │ └── ChatClientHolder.java # 模型客户端注册表与分发器 ├── models/ │ ├── AIDeepSeekChatClient.java # DeepSeek 客户端实现 │ ├── AIOpenAIChatClient.java # OpenAI 客户端实现 │ └── AIZhiPuAiChatClient.java # ZhiPu AI 客户端实现 ├── tools/ │ ├── DateTimeTool.java # 获取当前时间的工具 │ ├── IntegrateTool.java # 工具结果集成工具 │ └── JvmTool.java # JVM 信息查询工具 └── utils/ ├── KeywordDeduplication.java # 基于关键词覆盖的文本去重 ├── TextCleaner.java # 文本清理HTML/URL/表情/控制字符等 └── TextRankSummarizer.java # 基于 TextRank 的自动摘要各模块职责可以概括为下表模块核心类职责核心引擎ChatToolEngine负责处理聊天请求与响应集成记忆、工具、系统角色提供同步/流式/结构化四种执行方式顾问层LoggingCallAdvisor、LoggingStreamAdvisor记录请求与响应日志帮助开发人员在调试和监控中跟踪分析数据公共层AIChatClient、AIChatOptions、AIModelType、AIRegister定义客户端抽象、配置模型、模型类型常量与注册注解持有层ChatClientHolder扫描并注册各模型客户端按模型类型动态分发模型层AIDeepSeekChatClient等各厂商 API 的具体实现工具层DateTimeTool、JvmTool、IntegrateTool供大模型调用的外部工具Function Calling工具类TextCleaner、KeywordDeduplication、TextRankSummarizer聊天文本的后处理能力说明engine.md原文档结构图中提到的FileReaderTool.java文件读取工具与AIQianFanChatClient.java千帆客户端在当前仓库源码中暂未出现从源码结构看当前 models 包只包含 DeepSeek、OpenAI、ZhiPu 三个实现但AIModelType仍保留了QIAN_FAN常量为后续接入千帆预留了位置。三、核心引擎 ChatToolEngineBuilder 模式的链式调用ChatToolEngine源码见 ChatToolEngine.java是引擎的对外门面采用经典的 Builder 模式。静态入口方法签名为public static Builder builder(String modelType, AIChatOptions options)modelType对应 AIModelType 中的常量如AIModelType.OPEN_AIoptions则承载 API Key、模型名、采样参数等配置。3.1 四种执行方式Builder 内部持有 Spring AI 的ChatClient并提供四种执行方式源码 ChatToolEngine.java方法返回类型适用场景execute()String同步调用直接返回响应文本executeChatResponse()ChatResponse同步调用返回包含元数据与用量信息的完整响应对象executeStream()FluxString流式调用适合打字机效果的实时输出executeStructured(ClassT)/executeStructured(ParameterizedTypeReferenceT)T将模型输出结构化解析为指定 Java 类型// 同步文本 String answer ChatToolEngine.builder(modelType, options) .addPrompt(介绍一下 MeterSphere) .execute(); // 流式输出 FluxString stream ChatToolEngine.builder(modelType, options) .addPrompt(写一首诗) .executeStream(); // 结构化输出把响应直接映射为对象 BugReport report ChatToolEngine.builder(modelType, options) .addPrompt(根据测试结果生成缺陷报告) .executeStructured(BugReport.class);3.2 对话记忆Builder 默认内置了对话记忆ChatToolEngine.javaChatMemory chatMemory MessageWindowChatMemory.builder() .chatMemoryRepository(new InMemoryChatMemoryRepository()) .maxMessages(10) .build();即默认使用内存型仓库、窗口最多保留 10 条消息同时 pom.xml 引入了spring-ai-starter-model-chat-memory-repository-jdbc说明生产环境可以替换为 JDBC 持久化仓库。通过addMemory(conversationId, msg)可以将用户消息写入指定会话的记忆中多个请求间复用同一会话 ID 即可实现多轮上下文对话。3.3 工具调用tools(Object... tools)支持传入任意数量的工具对象引擎会在请求构建阶段通过request.tools(...)将它们注册给模型Function Calling例如.tools(new DateTimeTool(), new JvmTool())3.4 系统角色与请求构建顺序system(String system)用于设定系统角色System Prompt例如 你是一位资深测试工程师。prompt(String)/addPrompt(...)设置用户提示。最终请求的构建顺序源码 ChatToolEngine.java为若配置了聊天记忆添加PromptChatMemoryAdvisor记忆顾问若存在系统消息添加系统级提示system为空或空白时自动忽略添加用户提示若配置了工具列表启用对应工具。3.5 参数校验规则引擎对输入有明确的校验逻辑写代码时需注意prompt未设置或为空时执行会抛出IllegalStateException(Prompt must be set before execution.)buildRequest用户提示为 null 或仅含空白字符时RequestBuilder会抛出IllegalArgumentException(Prompt cannot be empty)工具列表与记忆为 null/空时自动忽略对应配置不会报错。四、模型注册与动态路由AIRegister ChatClientHolder引擎的多模型支持建立在「注解注册 运行时扫描」的机制之上。4.1 模型类型常量AIModelType 定义了引擎支持的模型类型字符串常量public static final String DEEP_SEEK DeepSeek; public static final String OPEN_AI Open AI; public static final String ZHI_PU_AI ZhiPu AI; public static final String QIAN_FAN QianFan; public static final String OLLAMA Ollama;注意这些常量是提供商类型Provider而AIChatOptions.modelType是具体模型名如gpt-3.5-turbo、deepseek-chat。4.2 注册注解与客户端分发AIRegister 是一个作用于类上的运行时注解用value()声明模型类型键Retention(RetentionPolicy.RUNTIME) Target(ElementType.TYPE) public interface AIRegister { String value(); }各模型实现类通过AIRegister(...)Component双重标注完成注册例如AIRegister(AIModelType.OPEN_AI)→AIOpenAIChatClientAIRegister(AIModelType.DEEP_SEEK)→AIDeepSeekChatClientAIRegister(AIModelType.ZHI_PU_AI)→AIZhiPuAiChatClientChatClientHolder 在构造时通过 SpringApplicationContext.getBeansOfType(AIChatClient.class)扫描所有AIChatClient类型的 Bean读取AIRegister注解的 value 作为 key构建MapString, AIChatClient MODEL_MAP。分发入口getChatClient(modelType, options)负责两件事按模型类型从映射中取出对应客户端实现查不到时抛出IllegalArgumentException(不支持的聊天模型类型: modelType)调用该实现的chatClient(options)生成并返回配置完成的ChatClient。这意味着要接入一个新的模型提供商只需新增一个继承AIChatClient的类打上AIRegister与Component注解即可引擎无需任何改动——这正是模块化设计的核心价值。4.3 三个模型实现类的差异三个实现类都继承抽象基类AIChatClientAIChatClient.java并实现chatClient(AIChatOptions)与chatModel(AIChatOptions)两个抽象方法AIOpenAIChatClient源码通过OpenAiApi.builder().apiKey(...).baseUrl(...)构建 API 客户端并额外向请求头注入Accept-Encoding: gzip, deflate以启用压缩传输AIDeepSeekChatClient源码复用 OpenAI 协议栈同样基于OpenAiApi/OpenAiChatModel构建仅模型名不同——这解释了为什么 DeepSeek 客户端与 OpenAI 客户端的实现如此相似AIZhiPuAiChatClient源码使用 Spring AI 专门的ZhiPuAiApi/ZhiPuAiChatModel其chatClient中直接把topP、temperature、maxTokens三个参数写入ZhiPuAiChatOptions。五、配置体系 AIChatOptions 详解AIChatOptions 使用 LombokData注解提供 builder 与 getter/setter。完整字段及说明如下字段类型含义与取值约束baseUrlStringAPI 接口地址如 OpenAI/DeepSeek 的端点apiKeyString调用密钥modelTypeString具体模型名如deepseek-chat、gpt-3.5-turbodisableLoggingAdvisorboolean是否关闭日志顾问默认false开启置true关闭temperaturedouble采样温度控制输出随机性取值0 ~ 2.0frequencyPenaltydouble频率惩罚正值降低模型逐字重复同一行的可能取值-2.0 ~ 2.0maxTokensInteger生成的最大 token 数受模型上下文长度限制topPdouble核采样参数0.1 表示只考虑概率质量排名前 10% 的 token取值0.1 ~ 1参数校验发生在抽象基类 AIChatClient.builderChatOptions 中// 温度仅 0~2.0 范围内的值会被应用 Optional.of(options.getTemperature()) .filter(temperature - temperature 0 temperature 2.0) .ifPresent(optionsBuilder::temperature); // frequencyPenalty仅 -2.0~2.0 范围内生效 // maxTokens非 null 即生效 // topP仅 0.1~1 范围内生效超出范围的采样参数会被静默忽略因此建议在业务层先做好入参校验。另外官方建议不要同时修改 temperature 与 topP二者相互作用难以预测该说明直接保留在AIChatOptions的字段注释中。六、日志顾问Advisor请求全链路可观测AIChatClient.addAdvisor源码统一为每个 ChatClient 注册两个默认顾问Optional.of(options) .filter(opt - !opt.isDisableLoggingAdvisor()) .ifPresent(opt - builder.defaultAdvisors(new LoggingStreamAdvisor(), new LoggingCallAdvisor()));LoggingCallAdvisor源码实现CallAdvisor在adviseCall中先把ChatClientRequest序列化为格式化 JSON 打印LogUtils.info(Request: {})再放行到拦截器链getOrder()返回 0 表示较高优先级LoggingStreamAdvisor实现StreamAdvisor对流式请求做同样的日志记录。想要关闭日志例如生产环境避免敏感 Prompt 落盘只需在AIChatOptions中设置disableLoggingAdvisor true。七、内置工具集 tools让模型调用系统能力工具层用于把引擎运行时的系统能力暴露给大模型Function Calling三个工具都使用 Spring AI 的Tool注解声明DateTimeTool源码提供getCurrentDateTime()返回当前时区的时间戳System.currentTimeMillis()用于回答现在几点明天是什么时候这类时间问题JvmTool源码通过ManagementFactory与Runtime收集 JVM 信息——包括 JVM 名称/版本/启动与运行时长/JVM 参数、堆内存初始化/最大/已用量、可用处理器数、操作系统名称与架构并以格式化的文本块返回适合运维问答类场景IntegrateTool源码注意其Tool注解带有returnDirect true表示工具返回结果直接作为最终答案输出不再交给模型二次加工例如把DateTimeTool与JvmTool的结果拼接后直接返回。八、文本处理工具箱 utils这三个工具类为聊天文本的输入清洗 - 去重 - 摘要提供完整链路TextCleaner源码提供分层清理 API方法功能basicClean清除控制字符、符号、格式字符及零宽字符advancedClean仅保留字母/数字/空白与白名单符号-_%/:#.,;!?()[]{}removeHtmlTags/removeUrls/removeEmojis移除 HTML 标签、URL 与 emojiunifySymbols中文引号/书名号转英文符号removeDuplicateLines/deduplicateText删除重复行/重复文本prepareForSummarization为摘要准备的清洗保留句子标点结构fullClean组合上述步骤的完整清理流程processLargeText逐行流式处理大文本降低内存占用truncate截断到指定长度KeywordDeduplication源码使用 Ansj 分词仅提取名词与动词作为关键词再依据关键词集合包含关系判断冗余——若文本 A 的关键词完全覆盖文本 B则判定 B 为重复并剔除。deduplicateText先按中英文逗号/句号切分段落再逐段去重。TextRankSummarizer源码实现了经典的 TextRank 摘要算法完整流水线为按。!?分句用 Ansj 分词后计算句子间Jaccard 相似度构建相似度矩阵以阻尼系数d 0.85、迭代 20 次计算每个句子的 TextRank 分数选取分数最高的 N 个句子按原文顺序拼接成摘要。调用方式TextRankSummarizer.summarize(text, sentenceCount)默认提取 1 句。这些工具类在引擎中被TextCleaner.fullClean / prepareForSummarization直接串联调用构成清洗 → 去重 → 摘要的文本后处理管线。九、从引擎到业务在 system-setting 中的实际接入引擎并非孤立的框架模块MeterSphere 的 AI 服务层已经直接消费它。以 AiChatBaseService.java 为例业务侧的核心调用链是private ChatClient getClient(AiModelSourceDTO model) { return ChatToolEngine.builder(model.getProviderName(), getAiChatOptions(model)) .getChatClient(); }其中getAiChatOptions(model)把用户在系统设置中配置的模型来源信息映射为引擎的AIChatOptionsaiChatOptions.setModelType(model.getBaseName()); // 具体模型名 aiChatOptions.setApiKey(model.getAppKey()); // 密钥 aiChatOptions.setBaseUrl(model.getApiUrl()); // 接口地址同时该服务还实现了两种聊天模式chat(aiChatOption)不记忆对话直接prompt().user(...).call()chatWithMemory(aiChatOption)带记忆聊天通过MessageChatMemoryAdvisor并传入conversationId实现多轮上下文且可选system系统提示。此外服务层还通过AiConversationContentMapper将用户/助手的对话内容持久化到数据库saveUserConversationContent/saveAssistantConversationContent形成AI 引擎 会话记忆 落库的完整闭环。由此可见引擎只负责怎么调模型而记忆策略、会话持久化、模型来源管理由上层业务服务编排职责边界清晰。十、完整实战示例下面给出一个可直接对照引擎 API 运行的完整示例与原文档使用说明一致仅将示例中的AiChatOptions修正为源码中的实际类名AIChatOptionsChatResponse response ChatToolEngine.builder(AIModelType.OPEN_AI, AIChatOptions.builder() .modelType(deepseek-chat) // 具体模型名可与提供商不同 .apiKey(sk-xxx) // API 密钥 .baseUrl(url) // 接口地址 .temperature(0.7) // 采样温度0~2.0 .maxTokens(1024) // 最大输出 token 数 .topP(0.9) // 核采样0.1~1 .build()) .system(你是一名资深的软件测试工程师请用简洁专业的中文回答。) .addPrompt(明天时间是多少) .tools(new DateTimeTool()) // 注册时间工具模型可调用 .executeChatResponse(); // 返回完整 ChatResponse 对象再给出一个带记忆的多轮对话示例String conversationId conv-001; // 第一轮写入记忆并提问 ChatToolEngine.builder(AIModelType.DEEP_SEEK, options) .addMemory(conversationId, 我的项目是 MeterSphere) .addPrompt(请记住我刚才说的项目名) .execute(); // 第二轮同一会话 ID模型能回忆起上文 String answer ChatToolEngine.builder(AIModelType.DEEP_SEEK, options) .addPrompt(我刚刚说的是哪个项目) .execute();流式输出示例Reactor Flux前端可订阅逐字渲染FluxString flux ChatToolEngine.builder(AIModelType.ZHI_PU_AI, options) .addPrompt(请用流式方式回答什么是持续测试) .executeStream(); flux.subscribe(System.out::print);十一、提示词工程思路链CoT引擎文档专门开辟了提示词工程章节强调思路链Chain-of-ThoughtCoT技巧思路链提示鼓励模型逐步推理问题从而提高复杂推理任务的准确性。通过明确要求模型展示其工作成果或以逻辑步骤思考问题可以显著提高需要多步骤推理的任务的性能。CoT 的工作原理是鼓励模型在得出最终答案之前生成中间推理步骤类似于人类解决复杂问题的方式这使得模型的思维过程更加清晰并有助于其得出更准确的结论。典型的 Prompt 句式是让我们一步步解决这个问题配合结构化编号让推理过程显性化。原文档给出的完整示例经典年龄差问题让我们一步步解决这个问题 1. **确定过去年龄** 当我3岁时我的伙伴的年龄是我的三倍即 3 * 3 9岁。 2. **计算年龄差** 当时我的伙伴比我大 9 - 3 6岁。这个年龄差是固定的因为我们都以相同的速度变老。 3. **当前年龄** 现在我20岁。因为年龄差保持不变我的伙伴的年龄是 20 6 26岁。 4. **验证** 从我3岁到20岁过去了 20 - 3 17年。 我的伙伴当时的年龄是9岁17年后9 17 26岁与计算一致。 **答案**我的伙伴现在26岁。在实际使用引擎时可以将 CoT 模板放进system()或prompt()String cotPrompt 让我们一步步解决这个问题 1. 明确已知条件 2. 列出计算步骤 3. 给出验证过程 4. 输出最终答案 ;结合引擎的system()设置角色约束、tools()挂载可计算的工具如DateTimeToolCoT 可以与 Function Calling 协同工作——模型先调用工具拿到事实数据再按步骤推理能进一步降低幻觉概率。十二、扩展新模型与注意事项12.1 如何接入一个新的模型提供商基于前文分析接入新模型只需四步仓库只读此处仅说明扩展思路在 AIModelType 中新增提供商常量如OLLAMA已预置新增一个类继承AIChatClient实现chatClient与chatModel两个方法在类上标注AIRegister(AIModelType.XXX)与Component若厂商协议兼容 OpenAI可直接复用OpenAiApi/OpenAiChatModel参考AIDeepSeekChatClient的做法。ChatClientHolder的构造器会自动扫描注册业务侧无需修改任何调用代码。12.2 使用注意事项AIModelType与modelType是两个概念前者是提供商类型Builder 的第一个参数后者是具体模型名AIChatOptions.modelType二者可以不同如官方示例中 Provider 用 OPEN_AI、模型名用 deepseek-chat采样参数有取值范围约束越界会被静默忽略temperature 0~2.0、frequencyPenalty -2.0~2.0、topP 0.1~1建议业务层先行校验默认记忆为内存实现且窗口上限 10 条消息生产环境多实例部署时应替换为 JDBC 等持久化记忆仓库disableLoggingAdvisor true可以关闭请求日志包含敏感 Prompt 的业务场景建议评估是否开启原文档提到的FileReaderTool与AIQianFanChatClient在当前源码中尚未落地以 models 与 tools 目录下实际存在的类为准。总而言之metersphere-ai-engine以抽象基类 注解注册 Builder 门面的三层设计把多厂商大模型接入成本压缩到了极致上层业务只需关心AIChatOptions配置与ChatToolEngine的链式调用即可获得同步、流式、结构化、带记忆、带工具的完整聊天能力这也是 MeterSphere AI 助手能够快速集成 DeepSeek、OpenAI、ZhiPu AI 等多家模型的技术基础。赞分享质量保障接口测试测试后端前端AI 应用DevOps【免费下载链接】metersphereMeterSphere 是新一代的开源持续测试工具内置 AI 助手让软件测试工作更简单、更高效不再成为持续交付的瓶颈。项目地址https://gitcode.com/gh_mirrors/me/metersphere点击查看免费下载相关推荐SafeEyes核心功能大揭秘智能休息提醒、多屏幕支持与自定义界面SafeEyes核心功能大揭秘智能休息提醒、多屏幕支持与自定义界面 SafeEyes是一款简单而美观的开源护眼工具通过智能休息提醒帮助用户预防眼疲劳。它不仅桌面应用koboldcpp技术深度解析跨平台AI模型推理引擎架构设计与实现koboldcpp技术深度解析跨平台AI模型推理引擎架构设计与实现 GGML/GGUF模型的高效部署一直是AI开发者的痛点koboldcpp通过创新的跨平台人工智能大模型本地部署模型推理服务PromptX框架深度解析AI提示词管理的架构设计与核心原理PromptX框架深度解析AI提示词管理的架构设计与核心原理 PromptX是一个模式驱动的AI提示词管理框架它通过元提示词技术让开发者能够快速构建领域专用人工智能大模型AI 应用提示工程MCP 服务AI 插件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
