Java 工程师 LLM 工程化

Appearance

L01-07 @Tool 工具调用 ​

全局中心内容：模型不执行代码，它只是说他想调用谁、传什么参数——执行的是你。 全局讲解主线：不给工具会怎样 → 五步链路 → 描述怎么写 → 现场触发一次 → 异常路径。

P1 · 产出页 ​

中心内容：问天气不再是编的，是真实数据。

  • 页面内容

    • 模型主动触发 getWeather("北京")
    • 用真实数据组织回答
    • 工具异常有兜底文案

  • 讲解技巧

    • 先演示编造：关掉工具问一次天气，让学员看模型编得多像真的。这个反差是本节最好的开场。
    • 讲一句狠的：「编造看起来越像真的，越危险」。

  • 时长：20s

P2 · 痛点页：三种撒谎 ​

中心内容：最糟的不是幻觉，是模型说自己已经做了。

  • 页面内容

    • 天气 → 编一个「晴，25 度」
    • 订单 → 编造物流状态
    • 改状态 → 说「已处理」，其实什么也没做

  • 讲解技巧

    • 第三种要重点讲：它会直接造成业务事故。前两种顶多是答案错，第三种是「系统在骗人」。
    • 追问一句：「你的应用里有没有让模型说『已完成』的地方？」——通常一半人会沉默。

  • 时长：2min 30s

P3 · 原理图：五步链路 ​

中心内容：执行发生在你的 JVM 里，用的是你的权限。

  • 页面内容

    • 发问题 + 工具清单 Schema
    • 模型返回「我要调 getWeather，参数 {city: 北京}」
    • 你的 Java 方法执行
    • 结果回填给模型
    • 模型组织最终回答

  • 讲解技巧

    • 把第 3 步单独高亮：这是理解一切工具设计问题的钥匙。权限、超时、异常、审计，全都在这一步。
    • 这句话要念出来：「模型不执行任何代码，它只是输出一段 JSON」。

  • 时长：3min

P4 · 写法表：描述决定准确率 ​

中心内容：把 description 当需求文档写给新同事看。

  • 页面内容

    • 差：「查询天气」
    • 好：能做什么 + 参数格式 + 边界（不支持什么 / 失败时怎样）
    • 三要素缺一，调用就随机

  • 讲解技巧

    • 并排展示两段描述，让学员猜哪个调用更准。答案显而易见，但大多数人写的是前者。
    • 强调「边界」这一条最常被漏：不写边界，模型就会在越界时自己编一个答案。

  • 时长：3min

P5 · 设计表：参数少而确定 ​

中心内容：超过 3 个参数就该拆工具。

  • 页面内容

    • 用枚举限定取值，不要裸 string
    • 字段名用业务语言，不要 p1/p2
    • 只给真正需要的参数

  • 讲解技巧

    • 给一个经验值：参数超过 3 个，模型出错概率指数上升。这是实测结论，不是理论。
    • 举例枚举的威力：status: enum[PENDING, PAID, SHIPPED] 比 status: string 准确率差距明显。

  • 时长：2min

P6 · 编码：@Tool 与异常处理 ​

中心内容：异常必须转成人话返回，不要抛出去。

  • 页面内容

    • @Tool(description = """...""")
    • 查不到 → 返回 NOT_FOUND：...请向用户确认
    • 出错 → 返回 ERROR：...请告知用户稍后重试

  • 讲解技巧

    • 这页是本节最值钱的部分。工具抛异常时不同版本行为不一，最稳的就是统一转文本。
    • 对比演示：抛异常时模型可能照着念堆栈；转文本后模型会去问用户。两个效果天差地别。

  • 时长：5min

P7 · 编码：注册与动态挂载 ​

中心内容：按用户权限动态挂载，别一次性全给。

  • 页面内容

    • .defaultTools(weatherTools)
    • MethodToolCallbackProvider.builder().toolObjects(...)
    • 按角色筛选工具子集

  • 讲解技巧

    • 安全视角切入：把所有工具挂到全局 ChatClient，等于给所有用户开了所有权限。
    • 预告 03B-11 权限沙箱是完整方案，这里只是第一道门。

  • 时长：4min

P8 · 运行：正常 + 边界测试 ​

中心内容：越界参数要答「不支持」，不是编一个。

  • 页面内容

    • 北京天气 → 真实数据
    • 纽约天气 → 「未找到，请确认城市名」
    • 无需工具的问题 → 不触发工具
    • 两城市比较 → 连续调用两次

  • 讲解技巧

    • 四条测试一条条现场跑，不要只跑第一条。边界测试才是区分「跑通了」和「做好了」的地方。
    • 「无需工具时不触发」这条要盯日志看——过度调用会悄悄烧钱。

  • 时长：5min

P9 · 异常路径演示 ​

中心内容：让天气 API 挂掉，看模型说什么。

  • 页面内容

    • 模拟服务不可用
    • 期望：友好提示，不是堆栈
    • 日志里有完整异常，用户看不到

  • 讲解技巧

    • 必须真的模拟一次：把 WeatherApi 改成抛异常跑一遍。
    • 点明这是很多教程不讲、生产一定会遇到的情况。这种「我替你想到了」的细节最能建立信任。

  • 时长：2min 30s

P10 · 避坑与小结 ​

中心内容：工具返回值会进上下文，别返回大对象。

  • 页面内容

    • 不生效先查模型支持度与描述，别急着改框架配置
    • 异常必须转文本返回
    • 给模型看的返回值 ≠ 给前端看的对象

  • 讲解技巧

    • 第一条给出排查顺序：最简工具 → 真实工具 → 调描述。这三步能解决 90% 的「工具不生效」。
    • 第三条的典型反例：直接把 JPA 实体 toString 返回，一次几千 Token。

  • 时长：2min

讲师备忘 ​

项内容
课前必做准备「关闭工具时模型编造天气」的对比输出；准备异常路径演示的开关
最容易超时处P4 的描述写法，学员会要求现场改描述看效果——可以演示一次，控制在 2 分钟内
学员最常问「模型编造了一个不存在的工具名怎么办？」答：执行层必须做白名单校验，03B-11 讲
现场备用天气 API 不通 → 用返回固定值的本地 stub 演示，主线不受影响