311 lines
12 KiB
Markdown
311 lines
12 KiB
Markdown
# NLU 接入设计方案
|
||
|
||
> 状态：**已确认，进入实现阶段**
|
||
> 关联文档：`bert_integration_analysis.md`、`architecture_overview.html`
|
||
|
||
---
|
||
|
||
## 第一部分：概念解释 — 两套术语怎么对应
|
||
|
||
### 1.1 Canvas 设计里用的词
|
||
|
||
在 `architecture_overview.html` 的技术流程视图里，BERT NLU 节点描述为：
|
||
|
||
```
|
||
BERT NLU 意图识别
|
||
输出 domain / intent / slot / confidence 置信度
|
||
```
|
||
|
||
这是一套**面向业务语义**的描述，每个词的含义：
|
||
|
||
| 词 | 含义 | 例子 |
|
||
|---|---|---|
|
||
| `domain` | 所属业务域，意图的分组 | `machine_control`、`equipment_knowledge`、`smalltalk` |
|
||
| `intent` | 用户想做什么，域内的细分动作 | `wirecut_set_speed`、`wirecut_start_run`、`query_alarm` |
|
||
| `slot` | 动作的具体参数，从句子里提取的关键值 | `speed=80`、`voltage=90`、`axis=X` |
|
||
| `confidence` | 模型对这次识别结果的置信程度，0~1 | `0.94`（高）、`0.61`（中）、`0.32`（低）|
|
||
|
||
Canvas 的路由逻辑就是：拿到这四个值之后，判断 `confidence ≥ 阈值 AND domain = machine_control` → 走工具调用路径。
|
||
|
||
---
|
||
|
||
### 1.2 intelligent_cabin NLU 服务里用的词
|
||
|
||
`intelligent_cabin` 后端分两层输出：
|
||
|
||
#### 层 A：JointBertNLU 的原始输出（`joint_nlu.py`）
|
||
|
||
```python
|
||
@dataclass
|
||
class JointNluResult:
|
||
intent_id: str | None # 识别出的意图 id，如 "wirecut_set_speed"
|
||
intent_score: float # softmax 后的概率，就是置信度，0~1
|
||
candidates: list[JointCandidate] # Top-K 候选意图及其概率
|
||
slots: dict[str, Any] # 从句子里提取的 slot，如 {"speed": 80}
|
||
slot_items: list[JointSlot] # slot 在原文中的精确位置和得分
|
||
```
|
||
|
||
这里的 `intent_id + intent_score + slots` 对应 Canvas 描述里的 `intent + confidence + slot`。
|
||
`domain` 不是模型直接输出的，而是根据 `intent_id` 在 `domain.yml` 里查到的（`wirecut_set_speed` → domain `machine_control`）。
|
||
|
||
#### 层 B：Router / FusionGrader 的决策输出（`router.py`）
|
||
|
||
```python
|
||
# MultiStageIntentMatcher._build_fusion_stage() 里
|
||
decision = "execute" | "clarify" | "route_to_cloud" | "reject"
|
||
```
|
||
|
||
这是在原始 NLU 结果基础上做的**二次路由判断**，加入了：
|
||
- 置信度是否够高（`score ≥ execute_score_threshold=0.55`）
|
||
- 头两名候选的分差是否足够大（`margin ≥ execute_margin_threshold=0.18`）
|
||
- 是否有多义性（ambiguous）
|
||
|
||
它告诉上层"这个识别结果能不能直接执行"，而不只是"模型认为是哪个意图"。
|
||
|
||
---
|
||
|
||
### 1.3 两套词汇的完整映射关系
|
||
|
||
```
|
||
Canvas 的描述 ←→ intelligent_cabin 的实际字段
|
||
─────────────────────────────────────────────────────────────
|
||
domain ←→ intent_def.domain (从 domain.yml 查)
|
||
intent ←→ JointNluResult.intent_id
|
||
slot ←→ JointNluResult.slots (dict)
|
||
confidence ←→ JointNluResult.intent_score (0~1)
|
||
|
||
（以上是 NLU 层的概念对应）
|
||
|
||
Canvas 的路由逻辑 ←→ Router 层的 decision 字段
|
||
"高置信 + 设备控制域" ←→ decision="execute" AND domain="machine_control"
|
||
"知识域/低置信兜底" ←→ decision="route_to_cloud" 或 domain="equipment_knowledge"
|
||
"smalltalk" ←→ decision="reject" 或 social_router 处理
|
||
```
|
||
|
||
> **关键点**：Canvas 当前用 Mock NLU（`src/lib/nlu/mock.ts`），它直接输出 `domain + intent + confidence + routeHint`。
|
||
> 接入真实 NLU 后，两个项目**原生打通，当成一个项目**，不做兼容适配层，接口可以随时改。
|
||
|
||
---
|
||
|
||
## 第二部分：Canvas ↔ NLU 服务的统一路由方案
|
||
|
||
### 2.1 两个项目合并为一个项目（已确认）
|
||
|
||
`intelligent_cabin` 不作为独立服务做适配，而是直接作为 `ai-canvas` 的后端子模块。
|
||
原来 `src/lib/nlu/mock.ts` 的格式**可以废弃**，不需要保持向后兼容。
|
||
|
||
### 2.2 真实 NLU 服务的 HTTP 响应
|
||
|
||
调用 `POST /api/v1/agent/chat` 后，服务返回 `ChatResponse`，与路由相关的核心字段：
|
||
|
||
```json
|
||
{
|
||
"session_id": "xxx",
|
||
"intent": "wirecut_set_speed",
|
||
"domain": "machine_control",
|
||
"decision": "execute",
|
||
"status": "completed",
|
||
"filled_slots": { "speed": 80 },
|
||
"routing_debug": {
|
||
"confidence_grade": "high",
|
||
"stages": [
|
||
{ "stage": "classifier", "score": 0.87, "candidates": [...] },
|
||
{
|
||
"stage": "fusion",
|
||
"metadata": { "decision": "execute", "grade": "high",
|
||
"classifier_signal": 0.87, "classifier_margin": 0.34 }
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
> `domain` 字段需要在 intelligent_cabin 的 `ChatResponse` schema 里加上（从 `IntentDefinition.domain` 填充），改动极小。
|
||
|
||
### 2.3 Canvas 侧的 NluResult 类型（替换 mock.ts）
|
||
|
||
```typescript
|
||
// src/lib/nlu/types.ts （新建，替换 mock.ts 里的类型）
|
||
|
||
export type RouteHint =
|
||
| "tool_call" // decision=execute + machine_control 域
|
||
| "knowledge_query" // decision=route_to_cloud 或 equipment_knowledge 域
|
||
| "smalltalk" // decision=reject
|
||
| "fallback";
|
||
|
||
export type NluResult = {
|
||
modelVersion: string;
|
||
domain: string; // 后端直接返回
|
||
intent: string; // intent_id
|
||
confidence: number; // classifier stage score
|
||
slots: Record<string, string | number | boolean>; // filled_slots
|
||
routeHint: RouteHint;
|
||
decisionGrade: "high" | "medium" | "low";
|
||
rawDecision: "execute" | "clarify" | "route_to_cloud" | "reject";
|
||
};
|
||
|
||
export function mapDecisionToRouteHint(
|
||
decision: string,
|
||
domain: string
|
||
): RouteHint {
|
||
if (decision === "execute") {
|
||
if (domain === "machine_control") return "tool_call";
|
||
if (domain === "equipment_knowledge") return "knowledge_query";
|
||
return "tool_call";
|
||
}
|
||
if (decision === "route_to_cloud") return "knowledge_query";
|
||
if (decision === "reject") return "smalltalk";
|
||
return "fallback"; // clarify 等待补槽，暂用 fallback
|
||
}
|
||
```
|
||
|
||
### 2.4 confidence 读取位置
|
||
|
||
`routing_debug.stages` 里找 `stage === "classifier"` 的记录，取其 `score` 字段。
|
||
这是 BERT 分类器 softmax 后的原始概率，等价于 Canvas 描述里的 `confidence`。
|
||
|
||
---
|
||
|
||
## 第三部分：语音处理前置拦截链路（已定稿）
|
||
|
||
### 3.1 设计原则
|
||
|
||
- **所有当前可见 UI 组件的按钮文本都参与语音匹配**，命中则直接触发点击事件，不调 BERT
|
||
- 调机流程（GuidedProcedure）当前**不在实现范围**，相关 1c 拦截逻辑暂不涉及
|
||
- BERT 报错**直接抛出**，不降级，不用 Mock 兜底
|
||
|
||
### 3.2 四阶段处理链路
|
||
|
||
```
|
||
ASR 文本输入
|
||
│
|
||
▼
|
||
[阶段 0] 停止词检测 ← 静态词表，构建时嵌入
|
||
├── 命中 cancel_words → 生成 stop_action，链路终止
|
||
└── 未命中 ↓
|
||
│
|
||
▼
|
||
[阶段 1] UI 可见元素语音点击匹配 ← 纯前端规则，<1ms
|
||
├── 1a. session.status=waiting_confirmation 时的 affirm/deny（最高优先级）
|
||
└── 1b. 当前可见 Artifact 按钮 text 匹配
|
||
│ 命中任意 → 生成 ActionEvent，走 Canvas 状态机，链路终止
|
||
│
|
||
│ 全部未命中
|
||
▼
|
||
[阶段 1.5] waiting_slot + inform 检测
|
||
├── session.status=waiting_slot && 输入为数字/数值类
|
||
└── 命中 → 调 fill_slots 接口，链路终止
|
||
│
|
||
▼
|
||
[阶段 2] BERT NLU（intelligent_cabin /api/v1/agent/chat）
|
||
├── 报错 → 直接抛出，不降级
|
||
├── decision=execute → 工具调用层（DBus）→ Artifact
|
||
├── decision=clarify → 渲染补槽卡，等待 waiting_slot
|
||
├── decision=route_to_cloud → LLM + 知识库 → KnowledgeLessonArtifact
|
||
└── decision=reject → LLM 直接作答，不写 ArtifactStore
|
||
```
|
||
|
||
### 3.3 阶段 1 内部优先级说明
|
||
|
||
```typescript
|
||
// 优先级从高到低（1c 调机 textAliases 暂不实现）
|
||
const PRIORITY_ORDER = [
|
||
"waiting_confirmation_affirm_deny", // 1a
|
||
"visible_artifact_button", // 1b
|
||
];
|
||
```
|
||
|
||
**为什么 1a 最高**：当高风险操作（如"开始加工"）弹出确认卡时，
|
||
操作员说"确认"应当触发确认动作，而不是响应画布上同时存在的其他按钮。
|
||
状态（`session.status`）决定优先级，而非文本本身。
|
||
|
||
### 3.4 阶段 1 匹配实现（pipeline.ts 骨架）
|
||
|
||
```typescript
|
||
// src/lib/nlu/pipeline.ts
|
||
|
||
import { AFFIRM_WORDS, CANCEL_WORDS } from "./voice-aliases.gen"; // 构建时生成
|
||
|
||
type ActionEvent = {
|
||
type: "voice_click_event" | "slot_fill_event" | "stop_action";
|
||
actionId?: string;
|
||
artifactId?: string;
|
||
sourceText: string;
|
||
};
|
||
|
||
export async function processVoiceInput(
|
||
asrText: string,
|
||
session: CanvasSession
|
||
): Promise<NluResult | ActionEvent> {
|
||
|
||
// 阶段 0：停止词
|
||
const norm = normalizeVoice(asrText);
|
||
if (CANCEL_WORDS.some(w => norm.includes(w))) {
|
||
return { type: "stop_action", sourceText: asrText };
|
||
}
|
||
|
||
// 阶段 1a：waiting_confirmation 状态的 affirm/deny
|
||
if (session.status === "waiting_confirmation") {
|
||
if (AFFIRM_WORDS.some(w => norm.includes(w))) {
|
||
return { type: "voice_click_event", actionId: "confirm", sourceText: asrText };
|
||
}
|
||
if (CANCEL_WORDS.some(w => norm.includes(w))) {
|
||
return { type: "voice_click_event", actionId: "cancel", sourceText: asrText };
|
||
}
|
||
}
|
||
|
||
// 阶段 1b：当前 Artifact 按钮匹配
|
||
const voiceClick = matchVoiceToAction(asrText, session.visibleActions);
|
||
if (voiceClick) {
|
||
return {
|
||
type: "voice_click_event",
|
||
actionId: voiceClick.actionId,
|
||
artifactId: voiceClick.artifactId,
|
||
sourceText: asrText,
|
||
};
|
||
}
|
||
|
||
// 阶段 1.5：waiting_slot + 数值输入
|
||
if (session.status === "waiting_slot" && isNumericInput(asrText)) {
|
||
return { type: "slot_fill_event", sourceText: asrText };
|
||
}
|
||
|
||
// 阶段 2：BERT NLU（报错直接抛出）
|
||
const response = await callNluService(asrText, session.sessionId);
|
||
return adaptNluResponse(response);
|
||
}
|
||
```
|
||
|
||
### 3.5 voice_aliases 配置（已确认：静态构建）
|
||
|
||
**词表位置**：`intelligent_cabin/config/voice_aliases.yml`（和 `dialog_acts.yml` 放在一起）
|
||
|
||
```yaml
|
||
# voice_aliases.yml
|
||
affirm_words: ["确认", "好的", "执行", "是", "对", "继续", "好", "ok"]
|
||
cancel_words: ["取消", "算了", "不要", "不用", "停止", "停"]
|
||
|
||
# 工控设备别名（按 intent_id 分组，用于阶段 1b 的 Artifact voiceActions）
|
||
intent_aliases:
|
||
wirecut_start_run: ["开始", "启动", "加工", "跑起来"]
|
||
wirecut_stop_run: ["停", "停机", "急停", "停止"]
|
||
wirecut_home_all: ["回零", "归零", "回原点"]
|
||
wirecut_pause_run: ["暂停", "变频暂停"]
|
||
```
|
||
|
||
**构建时生成**：构建脚本读取 yml → 生成 `src/lib/nlu/voice-aliases.gen.ts`，
|
||
TypeScript 侧直接 import，不需要运行时 HTTP 请求。
|
||
|
||
---
|
||
|
||
## 第四部分：下一步实现计划
|
||
|
||
| 步骤 | 位置 | 内容 |
|
||
|---|---|---|
|
||
| 1 | `intelligent_cabin` Python 侧 | `ChatResponse` schema 加 `domain` 字段，`agent_service.py` 填充 |
|
||
| 2 | `intelligent_cabin/config/` | 创建 `voice_aliases.yml`，补充工控别名 |
|
||
| 3 | `src/lib/nlu/` | 新建 `types.ts`，废弃 `mock.ts` 中旧类型 |
|
||
| 4 | `src/lib/nlu/` | 新建 `pipeline.ts`，实现四阶段处理链路 |
|
||
| 5 | `src/lib/artifacts/types.ts` | 各 Artifact 类型上加 `voiceActions` 字段 |
|
||
| 6 | 构建配置 | 添加 yml → ts 生成脚本（`voice-aliases.gen.ts`） |
|