深入解析：LLM - Spring AI × Anthropic Skills

文章目录

Pre
概述
整体思路概览
1. 封装 Skill 的 Java DTO 与 Tool
- 1.1 定义请求/响应模型
- 1.2 Tool 实现：调用 Python Skill 脚本
2. 把 Tool 注册成 Spring AI Function
3. ChatClient：让 Agent 自己选用 Skill
- 3.1 定义一个「数据分析 Agent」服务
- 3.2 控制器层简单暴露 HTTP 接口
4. Python 侧：包装 Skill 为统一入口（可选但推荐）
5. 同理挂载其它 Skill（如代码评审）
扩展阅读

在这里插入图片描述

Pre

概述

可以把前面那两个 Skill（代码评审 / 内部数据分析）理解为「外部可执行能力」，再用 Spring AI 的 Function/Tool Calling 把它们挂到 Agent 上，让模型自己决定何时调用哪一个脚本，然后再基于脚本结果继续对话。

下面给一个端到端的集成示例，假设你用的是 Spring Boot + Spring AI + OpenAI/Mistral 等支持函数调用的模型。

整体思路概览

Skill 本身：仍然是文件夹 + SKILL.md + scripts/*.py，部署在应用服务器旁（或者挂载到容器）。
Spring AI 这边做三件事：
- 用 Java 封装「运行某个 Skill 的脚本」为一个 Function/Tool（例如 runCodeReviewSkill、runDataAnalysisSkill）。
- 在 Function 内部，通过 ProcessBuilder 调 Python 脚本，并把结果（评审报告 / 分析报告）作为字符串返回给模型。
- 在 ChatClient 中声明这些函数为可调用工具，让 LLM 自己选用。

下面示例以「内部数据分析 Skill」为主，同时顺带演示代码评审 Skill 的挂载方式。

1. 封装 Skill 的 Java DTO 与 Tool

1.1 定义请求/响应模型

// DataAnalysisSkillRequest.java
public record DataAnalysisSkillRequest(
String analysisRequest,
String constraints
) { }
// DataAnalysisSkillResponse.java
public record DataAnalysisSkillResponse(
String reportText
) { }
// CodeReviewSkillRequest.java
public record CodeReviewSkillRequest(
String diffOrFiles,
String context
) { }
// CodeReviewSkillResponse.java
public record CodeReviewSkillResponse(
String reviewReport
) { }

Spring AI 会用这些类型自动生成函数的 JSON Schema，帮助 LLM 正确构造调用参数。

1.2 Tool 实现：调用 Python Skill 脚本

这里用「内部数据分析 Skill」举例，调用的是 run_query.py + clean_and_aggregate.py，然后再调用一个「汇总为报告」的小脚本，或者直接把 CSV 路径返回给 LLM 让它读内容（取决于你怎么暴露数据）。示例里用最简单的方式：把「分析意图」传给一个 Python wrapper 脚本，由它内部使用前面那两个脚本并生成最终报告文本。

// DataAnalysisSkillTool.java
package com.example.ai.tools;
import org.springframework.stereotype.Service;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
@Service
public class DataAnalysisSkillTool {
// 假设你的 Skill 目录在服务器上的路径
private static final String SKILL_BASE_DIR = "/opt/skills/internal-data-analysis-skill";
public DataAnalysisSkillResponse run(DataAnalysisSkillRequest request) {
try {
// 这里调用一个 Python wrapper，例如 scripts/run_analysis_skill.py
ProcessBuilder pb = new ProcessBuilder(
"python",
SKILL_BASE_DIR + "/scripts/run_analysis_skill.py",
"--request", request.analysisRequest(),
"--constraints", request.constraints() == null ? "" : request.constraints()
);
pb.redirectErrorStream(true);
Process process = pb.start();
StringBuilder output = new StringBuilder();
try (BufferedReader reader = new BufferedReader(
new InputStreamReader(process.getInputStream(), StandardCharsets.UTF_8))) {
String line;
while ((line = reader.readLine()) != null) {
output.append(line).append("\n");
}
}
int exitCode = process.waitFor();
if (exitCode != 0) {
return new DataAnalysisSkillResponse(
"分析脚本执行失败，退出码：" + exitCode + "，输出：\n" + output
);
}
return new DataAnalysisSkillResponse(output.toString());
} catch (Exception e) {
return new DataAnalysisSkillResponse("执行内部数据分析 Skill 时出现异常：" + e.getMessage());
}
}
}

代码评审 Skill 同理：调用 code-review-skill/scripts/... 并返回报告文本即可。

2. 把 Tool 注册成 Spring AI Function

Spring AI 推荐通过 @Bean Function<Req,Resp> 或 @Tool 暴露工具，让 ChatClient / ChatModel 知道有哪些函数可用。

// SkillsConfig.java
package com.example.ai.config;
import com.example.ai.tools.DataAnalysisSkillTool;
import com.example.ai.tools.CodeReviewSkillTool;
import com.example.ai.tools.dto.*;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.function.Function;
@Configuration(proxyBeanMethods = false)
public class SkillsConfig {
@Bean
public Function<DataAnalysisSkillRequest, DataAnalysisSkillResponse> internalDataAnalysis(DataAnalysisSkillTool tool) {
  return tool::run; // 函数名 internalDataAnalysis = Skill 名
  }
  @Bean
  public Function<CodeReviewSkillRequest, CodeReviewSkillResponse> codeReviewAssistant(CodeReviewSkillTool tool) {
    return tool::run;
    }
    }

在 Spring AI 里，这两个 Bean 名（internalDataAnalysis / codeReviewAssistant）就是 LLM 能看到的工具名，你可以在 prompt 中让模型了解它们的用途，也可以只靠 JSON Schema 自动推断。

3. ChatClient：让 Agent 自己选用 Skill

3.1 定义一个「数据分析 Agent」服务

// DataAnalysisAgentService.java
package com.example.ai.agent;
import com.example.ai.tools.dto.DataAnalysisSkillRequest;
import com.example.ai.tools.dto.DataAnalysisSkillResponse;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;
@Service
public class DataAnalysisAgentService {
private final ChatClient chatClient;
public DataAnalysisAgentService(ChatClient.Builder chatClientBuilder) {
this.chatClient = chatClientBuilder.build();
}
public String analyze(String userQuestion, String constraints) {
var sysPrompt = """
你是公司内部的数据分析助手。
你可以使用名为 internalDataAnalysis 的工具，它会基于数据仓库执行查询和分析，并返回一份结构化的中文报告草稿。
当用户的问题涉及具体的数据指标、时间范围、渠道/地区对比时，应优先调用该工具，而不是凭空猜测。
""";
// 这里不直接 new DataAnalysisSkillRequest，而是让 LLM 自己构造参数并调用工具
return chatClient
.prompt()
.system(sysPrompt)
.user(userSpec -> userSpec
.text("用户问题：{q}\n约束条件（可为空）：{c}")
.param("q", userQuestion)
.param("c", constraints == null ? "" : constraints)
)
// 关键：声明允许使用的函数名，Spring AI 会把函数 Schema 一起发给模型
.functions("internalDataAnalysis")
.call()
.content(); // 最终答案：模型在工具结果基础上生成的回答
}
}

模型流程示意：

收到用户问题 → 判断需要具体数据 → 选择调用 internalDataAnalysis。
构造 DataAnalysisSkillRequest 的 JSON 入参。
Spring AI 执行 Java Function → 调 Python Skill 脚本 → 拿到报告文本。
Spring AI 把报告作为新一轮对话上下文喂回模型。
模型基于报告，生成最终面向业务同学的自然语言回答。

3.2 控制器层简单暴露 HTTP 接口

// DataAnalysisController.java
package com.example.ai.web;
import com.example.ai.agent.DataAnalysisAgentService;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/analysis")
public class DataAnalysisController {
private final DataAnalysisAgentService agentService;
public DataAnalysisController(DataAnalysisAgentService agentService) {
this.agentService = agentService;
}
@PostMapping
public String analyze(@RequestParam("question") String question,
@RequestParam(value = "constraints", required = false) String constraints) {
return agentService.analyze(question, constraints);
}
}

4. Python 侧：包装 Skill 为统一入口（可选但推荐）

上面的 Java Tool 调用了一个假想的 run_analysis_skill.py，它可以作为 Skill 的统一入口，内部再去调用 run_query.py 和 clean_and_aggregate.py，并基于结果拼出完整报告文本（按照你在 SKILL.md 中定义的结构）。

伪代码示例：

# internal-data-analysis-skill/scripts/run_analysis_skill.py
import argparse
import textwrap
# 这里导入或复用 run_query.py / clean_and_aggregate.py 中的逻辑
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--request", required=True)
parser.add_argument("--constraints", default="")
args = parser.parse_args()
# 1. 解析 request / constraints -> 决定查询模板
# 2. 生成 SQL，调用 run_query.py 获得 result.csv
# 3. 调用 clean_and_aggregate.py 做清洗与聚合
# 4. 按 SKILL.md 中的报告结构拼出一份文本，print 到 stdout
report = textwrap.dedent(f"""
内部数据分析报告（示例）
一、分析诉求
- {args.request}
- 约束条件：{args.constraints or "无"}
二、关键指标（示例说明）
- ...
三、主要发现
- ...
四、风险与局限
- ...
五、后续建议
- ...
""").strip()
print(report)
if __name__ == "__main__":
main()

这样有三个好处：

Java 只关心「给脚本字符串 → 拿报告字符串」，无需理解 SQL 细节。
Skill 的演进主要在 Python + SKILL.md 里完成，不影响 Java 侧接口。
以后如果换成 MCP / 远程服务，也可以保持 Java 侧函数签名不变，只调整内部实现。

5. 同理挂载其它 Skill（如代码评审）

代码评审 Skill 的集成方式完全相同，只是：

DTO 换成 CodeReviewSkillRequest/Response；
Tool 内部调用的是 code-review-skill/scripts/...；
Agent 的 system prompt 改成「你是代码评审助手，可以调用 codeReviewAssistant 工具……」。

Spring AI 会自动把两个工具的 Schema 一起发给模型，这样一个更通用的「工程生产力 Agent」就可以根据用户问题自动选择是「查数据」还是「审代码」了。

下一步可以一起细化两点：

根据当前用的具体模型（OpenAI、Anthropic 代理、Mistral 等），调整 application.yml 中 Spring AI 的模型配置和函数调用选项。
把「Skill 元数据（目录扫描） + MCP」结合起来，让 Spring AI 在运行时动态发现新的 Skill，而不仅仅是写死在配置中的两个函数。

扩展阅读

Spring AI 官方主页
https://spring.io/ai
Spring AI 官方文档：Tools API
https://docs.spring.io/spring-ai/reference/api/tools.html
Spring AI GitHub 仓库
https://github.com/spring-projects/spring-ai
Spring AI 1.0 GA 官方发布（Azure 场景）
https://techcommunity.microsoft.com/blog/appsonazureblog/spring-ai-1-0-ga-is-here—build-java-ai-apps-end-to-end-on-azure-today/4414763

在这里插入图片描述

posted on 2026-01-13 16:05 ljbguanli 阅读(3) 评论(0) 收藏举报

深入解析：LLM - Spring AI × Anthropic Skills

文章目录

Pre

概述

整体思路概览

1. 封装 Skill 的 Java DTO 与 Tool

1.1 定义请求/响应模型

1.2 Tool 实现：调用 Python Skill 脚本

2. 把 Tool 注册成 Spring AI Function

3. ChatClient：让 Agent 自己选用 Skill

3.1 定义一个「数据分析 Agent」服务

3.2 控制器层简单暴露 HTTP 接口

4. Python 侧：包装 Skill 为统一入口（可选但推荐）

5. 同理挂载其它 Skill（如代码评审）

扩展阅读

Function Calling / Tool Calling 核心能力

Tool / MCP / 动态能力扩展

架构实践 / 综合教程

Java × Python / 跨语言协作（Agent 常见落地形态）

Agent / Claude / 外部参照体系

视频资源