摘要在既有「架构巡检 → 问题落库」链路中第一次引入大模型能力对单条 issue 做「解读 修复建议」要求输出可解析的结构化 JSON 并落库可追溯。本文记录选型、配置、HTTP 客户端、Prompt 约束与踩坑便于同类业务快速复用。工程ArchitectureGovernance· Spring Boot 4.x · Java 17 · MyBatis-Plus一、业务目标与整体思路输入数据库中的巡检问题InspectionIssue及关联任务InspectionJob上的事实字段。输出固定 schema 的 JSON摘要、影响、可能原因、分步行动、待人工确认问题、置信度。工程要求不绑死某一云厂商采用OpenAI 兼容的POST /v1/chat/completions默认对接硅基流动国内站支持演示模式不调外网支持可选 HTTP 代理接境外 API 时使用。数据流巡检 Issue Job组装 facts JSONSystem User PromptRestClient chat/completions解析 choices.message.content规范化 JSONinspection_ai_suggestion二、依赖与配置2.1 依赖使用spring-boot-starter-web即可使用 Spring 6 的RestClient。2.2 硅基流动对接要点参考硅基流动文档在 Kilo Code 中配置硅基流动。项说明Base URL须包含/v1例如https://api.siliconflow.cn/v1API Key控制台密钥中文站与国际站账号不互通模型模型广场完整名称如Qwen/Qwen2.5-7B-Instruct2.3application.yml核心片段inspection:ai:enabled:truedemo-mode:falsebase-url:https://api.siliconflow.cn/v1chat-path:/chat/completionsapi-key:${SILICONFLOW_API_KEY:${INSPECTION_AI_API_KEY:}}model:Qwen/Qwen2.5-7B-Instructtemperature:0.3connect-timeout-ms:20000read-timeout-ms:180000json-object-response-format:trueproxy-host:proxy-port:0json-object-response-format为true时在请求体中携带response_format: { type: json_object }。若网关返回 400可改为false并在 Prompt 中强调仅输出 JSON。代理国内直连.cn通常留空改接 OpenAI 等境外地址时配置proxy-host/proxy-port如127.0.0.1/7890。2.4 演示模式使用spring.profiles.activedemo加载application-demo.yml并将其中inspection.ai.demo-mode设为true服务将使用本地拼接的 JSON 模拟大模型结果实现见AiIssueAssistantService.buildDemoOutputJson无需外网与密钥。2.5 Profilesiliconflowapplication-siliconflow.yml可与主配置合并用于脚本或文档中统一写profilessiliconflow启动字段与主配置应对齐。三、HTTP 客户端RestClient 可选代理使用独立命名的RestClient.BuilderBeanaiRestClientBuilder避免与业务其他 HTTP 客户端混用。需要代理时使用java.net.http.HttpClientProxySelectorJdkClientHttpRequestFactoryHTTPS 经 HTTP 代理走 CONNECT。ConfigurationEnableConfigurationProperties(AiProperties.class)publicclassAiClientConfig{Bean(nameaiRestClientBuilder)publicRestClient.BuilderaiRestClientBuilder(AiPropertiesproperties){returnRestClient.builder().requestFactory(buildRequestFactory(properties)).baseUrl(trimTrailingSlash(properties.getBaseUrl()));}privatestaticClientHttpRequestFactorybuildRequestFactory(AiPropertiesp){DurationconnectDuration.ofMillis(p.getConnectTimeoutMs());DurationreadDuration.ofMillis(p.getReadTimeoutMs());Stringhostp.getProxyHost();if(host!null!host.isBlank()p.getProxyPort()0){StringproxyHostjava.util.Objects.requireNonNull(host).trim();HttpClienthttpClientHttpClient.newBuilder().connectTimeout(connect).proxy(ProxySelector.of(newInetSocketAddress(proxyHost,p.getProxyPort()))).build();JdkClientHttpRequestFactoryfactorynewJdkClientHttpRequestFactory(httpClient);factory.setReadTimeout(read);returnfactory;}SimpleClientHttpRequestFactorysimplenewSimpleClientHttpRequestFactory();simple.setConnectTimeout(connect);simple.setReadTimeout(read);returnsimple;}privatestaticStringtrimTrailingSlash(Stringurl){if(urlnull||url.isEmpty()){returnurl;}returnurl.endsWith(/)?url.substring(0,url.length()-1):url;}}调用封装OpenAiChatClient对配置的chat-path发起 POST设置Authorization: Bearer api-key与Content-Type: application/json。ComponentpublicclassOpenAiChatClient{publicStringchatCompletions(StringrequestBodyJson){StringpathnormalizePath(properties.getChatPath());returnrestClientBuilder.build().post().uri(path).header(Authorization,Bearer properties.getApiKey()).header(Content-Type,application/json).body(requestBodyJson).retrieve().body(String.class);}privatestaticStringnormalizePath(Stringp){if(pnull||p.isEmpty()){return/chat/completions;}returnp.startsWith(/)?p:/p;}}源码路径src/main/java/org/example/inspect/config/AiClientConfig.java、.../ai/OpenAiChatClient.java。四、业务核心Prompt、请求体、解析与落库4.1 System Prompt在AiIssueAssistantService中通过常量SYSTEM_PROMPT约定仅根据「事实 JSON」与用户补充作答禁止编造事实中不存在的字段输出单个 JSON 对象不要 Markdown 代码块字段summary、why_it_matters、likely_causes、recommended_actions含step/action/owner_hint、questions_for_humans、confidence使用简体中文。4.2 事实与用户载荷buildFacts将InspectionIssue与可选的InspectionJob转为 JSON。buildUserPayload拼接「事实 JSON」与「用户补充说明」。4.3 请求体OpenAI 兼容JSONObjectrequestnewJSONObject();request.put(model,aiProperties.getModel());request.put(temperature,aiProperties.getTemperature());// messages: system SYSTEM_PROMPT, user userContentrequest.put(messages,messages);if(aiProperties.isJsonObjectResponseFormat()){JSONObjectfmtnewJSONObject();fmt.put(type,json_object);request.put(response_format,fmt);}StringhttpResponsechatClient.chatCompletions(request.toJSONString());4.4 响应处理extractAssistantContent从choices[0].message.content读取助手正文。normalizeToJsonObjectString去除可能的 json 围栏后解析失败则写入带parse_error的兜底 JSON避免整条链路失败。4.5 落库与 REST API表/实体AiSuggestion如kind EXPLAIN_FIX保存outputJson、durationMs、哈希等。生成POST /inspection/issues/{issueId}/ai/suggest请求体可选userNote。查询最新GET /inspection/issues/{issueId}/ai/latest?kindEXPLAIN_FIX。控制器IssueAiController。五、输出示例字段含义成功时outputJson为字符串形式的 JSON解析后典型字段字段含义summary一句话结论why_it_matters为何重要数组likely_causes可能原因数组带不确定性表述recommended_actions分步行动与owner_hintquestions_for_humans需人工确认的问题confidencehigh/medium/low前端可对outputJson二次反序列化后绑定 UI。六、踩坑与经验连接超时直连境外域名在国内易超时接 OpenAI 需代理或改用国内可访问的 Base URL如硅基流动.cn。401 / invalid_api_key密钥必须与Base URL 所属平台一致勿将 A 平台密钥用于 B 平台域名。response_format部分兼容网关不支持json_object需关闭配置并加强 Prompt。可观测性记录durationMs、截断后的原始回复便于排障注意脱敏与长度。安全API Key 仅通过环境变量或密钥管理注入勿提交仓库。七、小结用OpenAI 兼容协议统一对接硅基流动及其他兼容网关用强约束 Prompt 可选response_format 解析兜底保证结构化落地用独立RestClientBean ConfigurationProperties保持配置清晰。适合作为「规则引擎 LLM 解读」第一期的工程模板。附录相关源码路径内容路径AI 配置属性src/main/java/org/example/inspect/config/AiProperties.javaRestClient 与代理src/main/java/org/example/inspect/config/AiClientConfig.javaChat Completions 调用src/main/java/org/example/inspect/ai/OpenAiChatClient.java业务与 Promptsrc/main/java/org/example/inspect/service/AiIssueAssistantService.javaREST APIsrc/main/java/org/example/inspect/controller/IssueAiController.java主配置src/main/resources/application.yml演示 / 硅基流动 Profileapplication-demo.yml、application-siliconflow.yml