Spring AI智能体开发避坑：中文工具名导致qwen3-max工具调用失败解析

项目背景概述。

在当前的AI智能体（Agent）开发领域，Python生态占据主导地位，TypeScript次之。而作为企业级应用的主流语言，Java在此领域的存在感相对较弱。为了复用既有的Java生态工具与运维经验，我近期启动了一个实验性项目：将一个智能体平台从Python框架迁移至Spring AI框架。

技术栈选型上，我使用了较新的SpringBoot 4以及Spring AI 2.0.0-SNAPSHOT版本。选择SNAPSHOT版本主要基于几点考量：项目功能复杂度不高，技术栈基于通用的OpenAI兼容模型和PgVector；考虑到后续版本升级，提前使用SNAPSHOT版本进行适配；以过往经验看，Spring项目的SNAPSHOT版本通常比较稳定。目前，Spring AI已发布2.0.0-M1版本。

迁移过程整体顺利，主要挑战在于AI对新代码的偶尔“不理解”。然而，在测试智能体自主执行能力时，后端反复报错：“工具名称不能为空”。

问题定位与分析

基于对Java异步编程的理解，我梳理了交互流程：

1. 客户端发送消息。
2. 服务端检索知识库，生成初步方案。
3. 调用工具进行处理与分析。
4. 重复步骤2-3，直至满足条件。
5. 返回最终结果给客户端。

问题出现在第二次工具调用环节：系统会同时发起一个有名称的工具调用，以及一个没有名称但包含参数的工具调用。我的第一反应是忽略无名称的调用，但由于对Spring AI框架内部机制不够熟悉，且相关类不允许轻易重写，未能找到合适的自定义切入点。

我一度认为是Spring AI框架或自身代码逻辑存在缺陷。为此，我反复调整提示词让AI修改代码，并进行手动调试，但问题依旧。由于项目处于Demo阶段，且Java在AI可观测性方面的生态尚不完善，未接入专门的LLM追踪工具，增加了排查难度。

当时我使用的是qwen3-max模型，未曾怀疑问题根源在模型本身，原因如下：

• 出于对头部模型能力的信任。
• 测试场景（知识库文档与问题）相对简单且固定。
• 错误每次复现且表现一致，不符合大模型固有的随机性特点。
• 早在2023年底，同类场景在GLM等模型上已运行稳定，按理说经过两年发展，基础的工具调用能力应更为可靠。

问题解决与反思

在尝试LLM追踪未果后，我更换了推理模型。将模型切换为deepseek-v3.2后重新测试，问题竟然消失了。

回顾整个调试过程，问题的根源很可能在于：我定义的工具名称是中文，这可能导致qwen3-max模型在解析时出现偏差。而每次错误都稳定复现，极大地误导了我的排查方向，让我在框架和代码层面浪费了大量时间。

这不禁让我联想到上半年的一次类似经历：重构智能体时也出现每次调用都失败的情况，当时归咎于框架上下文传递问题。如今看来，那或许也是特定模型对中文工具名支持不佳所致，甚至可能与模型服务提供商的缓存机制有关。

通过这次实践，一个深刻的体会是：在大模型智能体开发中，模型选型至关重要。DeepSeek模型在此次工具调用场景下的稳定表现，印证了其优秀的能力。对于企业级智能体开发，建议优先考虑DeepSeek系列模型（无论是官方API还是第三方部署版本）。

此外，GLM、Kimi（K2）、Minimax等国内模型据称也对工具调用有良好支持，但在复杂企业场景下的具体表现，还需进一步实测验证。