Kotlin AI 示例项目：Spring AI 工具调用机制深度解析

工具调用机制概述

在现代AI应用中，工具调用(Tool Calling)是一项关键技术，它允许大型语言模型(LLMs)与外部系统进行交互。Spring AI框架为Kotlin开发者提供了优雅的工具调用实现方式，使AI应用能够突破纯文本处理的限制，实现更丰富的功能。

工具调用的核心原理是让LLM能够：

1. 识别用户请求中需要调用外部工具的场景
2. 将必要参数转换为结构化数据格式(如JSON)
3. 触发外部系统执行相应功能
4. 将执行结果整合到模型响应中

这种机制极大地扩展了AI应用的能力边界，使其不仅能回答问题，还能执行实际任务，如查询数据库、获取实时天气、控制智能设备等。

环境配置与基础设置

在开始工具调用开发前，我们需要完成基础环境配置：

%useLatestDescriptors
%use spring-ai-openai

val apiKey = System.getenv("OPENAI_API_KEY") ?: "YOUR_OPENAI_API_KEY"

val openAiApi = OpenAiApi.builder().apiKey(apiKey).build()
val openAiOptions = OpenAiChatOptions.builder()
    .model(OpenAiApi.ChatModel.GPT_4_O_MINI)
    .temperature(0.7)
    .build()

val chatClient = ChatClient.create(
    OpenAiChatModel.builder()
        .openAiApi(openAiApi)
        .defaultOptions(openAiOptions)
        .build()
)

这段代码完成了：

1. 引入必要的Spring AI依赖
2. 配置OpenAI API密钥
3. 设置模型参数(GPT-4模型，温度为0.7)
4. 创建ChatClient实例

基于注解的工具实现

Spring AI提供了简洁的注解方式来定义工具。我们以一个园艺工具集为例，展示如何实现工具调用：

class GardenTools {

    @Tool(description = "根据视觉特征(如颜色、形状和纹理)识别植物")
    fun identifyPlant(
        @ToolParam(description = "花或叶的主要颜色") color: String,
        @ToolParam(description = "独特特征，如毛茸茸的叶子、刺等") features: String
    ): String = when {
        color == "purple" && features.contains("fuzzy") ->
            """{"name": "Lamb's Ear", "scientificName": "Stachys byzantina", "isInvasive": false}"""

        color == "yellow" && features.contains("tall") ->
            """{"name": "Sunflower", "scientificName": "Helianthus annuus", "isInvasive": false}"""

        else ->
            """{"name": "Unknown plant", "recommendation": "Describe the color and features of the plant in more detail."}"""
    }

    @Tool(description = "根据植物类型和生长区域提供最佳种植日期")
    fun getPlantingDates(
        @ToolParam(description = "植物类型(如番茄、辣椒)") plant: String,
        @ToolParam(description = "USDA耐寒区(如7b、8a)") zone: String
    ): String = when {
        plant.contains("tomato") && zone == "7b" ->
            """{"startDate": "April 15", "endDate": "May 30", "notes": "Wait until soil temperature reaches 60°F"}"""

        plant.contains("pepper") && zone == "7b" ->
            """{"startDate": "May 1", "endDate": "June 15", "notes": "These plants prefer warm soil"}"""

        else ->
            """{"error": "Planting information not available for this combination"}"""
    }

    @Tool(description = "分析土壤特性并提供建议")
    fun analyzeSoil(
        @ToolParam(description = "土壤类型(黏土、沙土、壤土)") soilType: String,
        @ToolParam(description = "种植的植物类型") plantType: String
    ): String = when (soilType) {
        "clay" -> """{"pH": 7.2, "drainage": "poor", "amendments": ["compost", "perlite"]}"""
        "sandy" -> """{"pH": 6.5, "drainage": "excessive", "amendments": ["compost", "coconut coir"]}"""
        "loam" -> """{"pH": 6.8, "drainage": "good", "amendments": ["compost"]}"""
        else -> """{"error": "Unknown soil type"}"""
    }
}

关键注解说明：

• @Tool: 标记方法为可调用工具，需提供功能描述
• @ToolParam: 定义方法参数的描述，帮助LLM理解参数含义

工具调用实战

定义好工具后，我们可以通过ChatClient轻松调用：

chatClient
    .prompt("我在花园里发现了一种紫色花朵、毛茸茸叶子的植物。另外，7b区什么时候最适合种植番茄？")
    .tools(GardenTools())
    .call()
    .content()

系统会自动识别需要调用的工具，并返回整合后的自然语言响应。

函数式工具实现

除了注解方式，Spring AI还支持函数式工具定义。我们以食谱推荐服务为例：

enum class MealType { BREAKFAST, LUNCH, DINNER }

data class RecipeRequest(
    val ingredients: List<String>,
    val mealType: MealType = MealType.DINNER,
    val timeAvailable: Int = 50.minutes.toInt(DurationUnit.MINUTES)
)

data class RecipeResponse(
    val name: String,
    val ingredients: List<String>,
    val instructions: List<String>,
    val cookTime: Duration
)

class RecipeService : (RecipeRequest) -> RecipeResponse {
    override fun invoke(request: RecipeRequest): RecipeResponse {
        return when {
            request.ingredients.containsAll(listOf("pasta", "tomato")) -> {
                RecipeResponse(
                    name = "Quick Pasta Pomodoro",
                    ingredients = listOf("pasta", "tomatoes", "garlic", "olive oil", "basil"),
                    instructions = listOf(
                        "按照包装说明煮意大利面。",
                        "用橄榄油炒香大蒜，加入切碎的西红柿煮5分钟。",
                        "与沥干的面条混合，用罗勒装饰。"
                    ),
                    cookTime = 20.minutes
                )
            }
            // 其他食谱逻辑...
        }
    }
}

创建工具回调：

val recipeToolCallback = FunctionToolCallback
    .builder("recipeRecommender", RecipeService())
    .description("根据可用食材和时间推荐食谱")
    .inputType(RecipeRequest::class.java)
    .build()

使用方式与注解方式类似：

chatClient.prompt("我有意大利面和番茄，晚餐可以做什么？")
    .tools(recipeToolCallback)
    .call()
    .content()

最佳实践与注意事项

1. 工具描述清晰：工具和参数的描述要准确详细，帮助LLM正确理解使用场景

2. 错误处理：工具实现中应考虑各种边界情况，返回结构化的错误信息

3. 性能考量：工具调用会增加延迟，对于实时性要求高的场景要谨慎使用

4. 安全性：暴露给LLM的工具应进行权限控制，避免敏感操作被滥用

5. 结果格式化：工具返回的数据应结构清晰，便于LLM解析和整合到自然语言响应中

通过Spring AI的工具调用机制，Kotlin开发者可以轻松构建功能丰富的AI应用，将语言模型的文本理解能力与实际业务功能完美结合。