Spring AI Alibaba工具调用机制：Python脚本与外部API集成指南

施业任Luna

602人浏览 · 2025-10-04 02:20:39

施业任Luna · 2025-10-04 02:20:39 发布

Spring AI Alibaba工具调用机制：Python脚本与外部API集成指南

你是否在开发AI应用时遇到工具调用复杂、外部API集成繁琐的问题？本文将带你深入了解Spring AI Alibaba的工具调用机制，通过实际案例演示如何轻松集成Python脚本与外部API，让你的AI应用能力倍增。读完本文，你将掌握工具注册、函数调用、结果处理的全流程，以及Python脚本执行和MCP服务调用的实战技巧。

核心架构与工具调用流程

Spring AI Alibaba提供了强大的工具调用框架，支持Python脚本执行、外部API调用等多种能力。其核心架构如图所示：

工具调用流程主要涉及以下几个关键组件：

工具定义：通过DashScopeChatOptions类配置工具信息，包括工具名称、参数等
调用决策：模型根据用户请求和工具定义决定是否调用工具
执行引擎：通过SandboxManager执行Python脚本或调用外部API
结果处理：将工具返回结果整理后返回给用户或作为下一步输入

快速开始：集成依赖

要使用Spring AI Alibaba的工具调用功能，首先需要在项目中添加相关依赖。在pom.xml中加入以下配置：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.alibaba.cloud.ai</groupId>
      <artifactId>spring-ai-alibaba-bom</artifactId>
      <version>1.0.0.3</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
  </dependency>
</dependencies>

Python脚本执行机制

Spring AI Alibaba通过SandboxManager类提供Python脚本执行能力，支持GraalVM Python环境。核心实现位于spring-ai-alibaba-studio/spring-ai-alibaba-studio-server/spring-ai-alibaba-studio-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/base/manager/SandboxManager.java。

Python脚本执行示例

以下是一个简单的Python脚本执行示例：

// 获取SandboxManager实例
@Autowired
private SandboxManager sandboxManager;

// 执行Python脚本
public void runPythonScript() {
    String scriptContent = "result = 1 + 2\nprint(result)";
    Map<String, Object> variables = new HashMap<>();
    Result<String> result = sandboxManager.executePython3Script(scriptContent, variables, "request-id-123");
    
    if (result.isSuccess()) {
        System.out.println("Script execution result: " + result.getData());
    } else {
        System.err.println("Script execution failed: " + result.getErrorMsg());
    }
}

脚本执行流程

环境准备：创建GraalVM Python上下文，配置执行选项
变量注入：将Java变量映射到Python环境中
脚本执行：通过context.eval("python", scriptContent)执行脚本
结果处理：捕获并转换Python执行结果为Java对象

外部API集成方案

Spring AI Alibaba通过MCP（Model Control Plane）实现外部API的集成与管理。MCP注册和路由功能由Nacos MCP Registry提供支持，实现了分布式环境下的服务发现和负载均衡。

MCP服务调用示例

以下是调用MCP服务的基本示例：

// 配置MCP服务
DashScopeChatOptions options = DashScopeChatOptions.builder()
    .withModel("qwen-plus")
    .withToolNames(Set.of("weather-api"))
    .build();

// 创建聊天客户端
DashScopeChatClient chatClient = new DashScopeChatClient(dashScopeApi, options);

// 发送包含工具调用的请求
ChatResponse response = chatClient.call(
    new Prompt("What's the weather in Beijing today?", 
        ChatOptions.create(options)));

// 处理工具调用结果
if (response.getMetadata().containsKey("tool_calls")) {
    List<ToolCall> toolCalls = response.getMetadata().get("tool_calls");
    // 处理工具调用结果...
}

工具调用核心配置

工具调用的核心配置通过DashScopeChatOptions类实现，位于spring-ai-alibaba-core/src/main/java/com/alibaba/cloud/ai/dashscope/chat/DashScopeChatOptions.java。主要配置项包括：

配置项	说明	默认值
`tools`	可用工具列表	null
`toolChoice`	工具选择策略	"auto"
`parallelToolCalls`	是否允许并行工具调用	false
`internalToolExecutionEnabled`	是否启用内部工具执行生命周期	false

工具调用配置示例

DashScopeChatOptions options = DashScopeChatOptions.builder()
    .withModel("qwen-plus")
    .withTools(Arrays.asList(
        new FunctionTool("weather-api", "Get weather information", 
            Arrays.asList(new Parameter("city", "string", "City name")))
    ))
    .withToolChoice("auto")
    .withParallelToolCalls(true)
    .build();

实战案例：天气查询应用

下面我们通过一个完整案例，展示如何使用Spring AI Alibaba集成Python脚本和外部API。

案例需求

创建一个天气查询应用，支持：

接收用户的自然语言查询（如"北京天气如何？"）
调用天气API获取实时数据
使用Python脚本处理数据，生成自然语言回答

实现步骤

定义工具：注册天气API工具
配置模型：设置工具调用参数
处理请求：解析用户查询，调用工具
结果处理：执行Python脚本处理API返回结果

核心代码

// 1. 定义天气API工具
FunctionTool weatherTool = new FunctionTool(
    "weather-api", 
    "Get current weather information for a city",
    Arrays.asList(new Parameter("city", "string", "City name to query weather"))
);

// 2. 配置模型和工具
DashScopeChatOptions options = DashScopeChatOptions.builder()
    .withModel("qwen-plus")
    .withTools(Arrays.asList(weatherTool))
    .withToolChoice("auto")
    .build();

// 3. 创建聊天客户端并发送请求
DashScopeChatClient chatClient = new DashScopeChatClient(dashScopeApi, options);
ChatResponse response = chatClient.call(new Prompt("What's the weather in Beijing today?"));

// 4. 处理工具调用结果
if (response.getMetadata().containsKey("tool_calls")) {
    // 获取工具调用结果
    String weatherData = handleToolCalls(response.getMetadata().get("tool_calls"));
    
    // 执行Python脚本处理数据
    String script = "def format_weather(data):\n" +
                   "    return f\"Current weather in {data['city']}: {data['temperature']}°C, {data['condition']}\"\n" +
                   "result = format_weather(" + weatherData + ")";
    Result<String> scriptResult = sandboxManager.executePython3Script(script, new HashMap<>(), "weather-request-1");
    
    // 将处理结果返回给用户
    System.out.println(scriptResult.getData());
}