语义理解与工具调用：一句话怎么变成一次接口调用

01目标：一句话变成一次可执行的调用

上面这个 JSON 是板上真跑出来的。它有两个地方值得盯住： ① 结构是对的（intent + slots 两个键）；② 内容是残缺的（「红色的盒子」没有出现在任何字段里）。

学完你该能做出这三件事

• 跑出一个结构化意图：给一句中文，拿到 intent 与 slots。
• 说出为什么必须自己做 JSON 提取与白名单校验，而不是直接 eval 模型输出。
• 指出一次解析“看起来成功、其实漏了信息”的具体破绽。

🔑 一句话：这一页的产物不是“能解析”，是“解析完敢不敢直接执行”。

02问题：会聊天的模型，为什么不能让车动起来

导航指令、抓取指令、停止指令 —— 机器人的每个动作都对应一个确定的接口。 而模型只会输出一段文本，中间这段落差就是这一页要填的沟。

🔑 一句话：模型的输出是“建议”，能不能执行由代码的边界决定。

03现象：真跑到的那一个 JSON

JSON: {'intent': 'navigate_to', 'slots': {'location': 'kitchen'}}
intent = navigate_to | slots = {'location': 'kitchen'}

再看这套映射表（真源 car1_llm/config/skills.yaml）里的五个技能：

怎么跑出来

用项目自带的 LLM 客户端，一句提示词就要一个 JSON：

终端一 · 意图解析

cd ~/ros2_ws/src/xflz_eai_car1/app/elderly_companion
python3 -c "
from common.config import load_config
from fall.config_schema import REQUIRED
from llm.server_manager import LLMServerManager
from llm.llm_client import LLMClient
cfg=load_config('config/fall_config.yaml',REQUIRED)
m=LLMServerManager(cfg['llm']); c=LLMClient(endpoint=m.ensure_running())
print(c.chat_json('只输出JSON：{\"intent\":\"navigate_to|grasp_object|stop|chat\",\"slots\":{}}。用户说：去厨房把红色的盒子拿过来'))
m.stop()"

🔍 看什么：三处。

• 看键名是否与提示词一致 —— 是 intent 与 slots，说明约束生效了。
• 看 slots 里有什么 —— 只有 location，没有颜色、没有物体名。
• 看有没有多余文字 —— 这次没有；但模型经常加一层 ```json 围栏，所以提取代码必须能剥。

🔑 一句话：现象里最值钱的不是“跑通了”，而是“跑通了却漏了一半”。

04原理：从句子到接口的六格

1为什么不让模型直接说“执行 navigate_to”？

吃什么：用户中文。做什么：先想清“允许它说哪几个词”。吐什么：一个封闭集合。 动参数会怎样：集合越窄越安全，但越容易“听不懂”；越宽越灵活，越容易乱执行。

2提示词里到底要写清几件事？

吃什么：句子 + 任务说明。做什么：三件事必须写清：只输出 JSON、intent 的候选值、 slots 里各字段的含义与可选地点。吐什么：请求体。

动参数会怎样：少写候选值，模型会自己发明动作名（比如 go_kitchen），第 5 格直接拒绝。

3模型为什么爱加 ```json 围栏？

吃什么：请求体。做什么：生成。吐什么：字符串 —— 常见三种脏数据： 前面一句“好的，结果如下”；包一层围栏；JSON 后面再补一句解释。动参数会怎样：直接 json.loads 会当场炸。

4提取 JSON 为什么要“括号平衡扫描”？

吃什么：脏字符串。做什么：先剥围栏，再从第一个 { 开始数字符：遇到 { 加一、} 减一， 计数归零处截断；字符串里的括号要跳过。吐什么：一个 dict。 动参数会怎样：用正则 \{.*\} 贪心匹配，遇到嵌套对象会被截错。

5校验这一步在拦什么？

吃什么：解析出的 dict。做什么：三件事：intent 必须在白名单； slots 里的地点必须能在 skills.yaml 的 mapping 里查到坐标；缺参就拒绝执行并追问。 吐什么：可执行参数，或一句“没听懂，请再说一遍”。

6调用那一层现在能跑吗？

吃什么：intent + 已映射参数。做什么：按类型走 action / service / topic。 吐什么：一次调用结果。

必须说清：本仓 car1_llm/car1_llm/skill_executor.py 里， _call_service / _call_action / _publish_topic 三个方法只打了 TODO 日志，没有真正调用。 这一格是契约清楚、实现待补。别照它去指望机器人真的动。

每格答全的五列表

🔑 一句话：模型负责“听懂”，代码负责“不许乱来” —— 五格在管后者。

05实践：三步把意图变成接口

1. 看一眼技能表 约 10 分钟 打开 skills.yaml，确认五个技能名、类型与接口名 —— 这就是第 5 格的白名单来源。
2. 跑一次意图解析 约 20 分钟 用 chat_json 要一个 JSON，记录键名与 slots 内容，对照提示词看约束是否生效。
3. 手工做一次映射 约 15 分钟 拿 location: kitchen 去 mapping 里查坐标，写出这条指令最终会调哪个接口。

对账表：命令 → 函数 → 文件

踩坑速查

🧪 Vibe Coding 复盘

🔑 一句话：先确认“它说的词在表里吗”，再谈“它说得对不对”。

06交互：工具清单与输出长度

📌 掌握检查：把 max_tokens 拖到 60，JSON 会先坏在哪一处？先说出答案再拖。

三个观察点：

• max_tokens 太小 → JSON 右括号缺失 → 第 4 格抛异常，宁可失败也不猜。
• 工具条数变少 → 候选集变窄，模型更容易选对，但支持的说法也变少。
• 句子复杂度升到 3 → 仍只出一个 intent，缺口暴露在“第二个动作”上。

可信度说明：台子按实测那次输出（1 intent + 1 slot）与上面三条规则推演，不编造新的识别内容。

🔑 一句话：token 短了会截断，schema 窄了会丢意图 —— 两个限制方向相反。

07验证：三道题

✅ 目标对账

🔑 一句话：三题分别考「边界 / 脏数据 / 结构上限」。

08总结：模型出意图，代码管边界

知识点关系表

两个反直觉

• 直觉是“JSON 合法就成功了”，实际是结构合法但语义残缺时，执行层会做出半件事（跑过去、不拿东西）。
• 直觉是“模型越强越不需要校验”，实际是模型越强说法越多，白名单越重要。

注意事项

• 数值陷阱：max_tokens 是输出上限，不是“越长越好”—— 太短会截断 JSON，太长会拖慢响应。
• 第 6 格在本仓是骨架（TODO），演示前先讲清，别让学员以为机器人真会动。
• 一句话多意图必须改 schema；靠调提示词解决不了。
• 地点不在 mapping 里时，正确行为是拒绝执行并追问，不是默认一个坐标。

前置依赖

这套东西用在哪儿

• 仓储机器人调度：仓管员说“去 A 区把蓝色托盘送来”，系统转成导航 + 抓取两条任务。
• 服务机器人点单：客人说“来杯热水”，转成一个取水动作而不是聊天回复。
• 产线语音调试：工程师说“回原点”“停”，直接映射到固定 service。

🔑 记忆点：模型可以幻觉，代码不能 —— 白名单、映射、拒绝执行，三件事一件都不能省。