联犀平台内置的小智 AI 能力，设备接入后即可获得语音对话、文字对话、多模态输入（图片/视频/文件）、拍照识图等能力。本文面向嵌入式设备开发者，说明设备端如何接入这些内置能力。

关联文档：

• AI 交互协议（完整版） — 会话管理、语音/文字交互、多模态输入的完整协议
• UDP 音频通道协议 — 实时语音的 UDP 音频传输规范
• 物模型协议 - 设备行为调用 — action 下发与 actionReply 上报
• HTTP 协议接入 - 设备文件上传 — upload-file 文件上传

本文聚焦拍照上传：平台主动下发拍照指令 → 设备拍照并上传文件 → 设备上报图片地址 → 平台识图并回复。这是联犀内置小智 AI 的特色能力，也是设备端需要实现的接入点之一。

1. 能力总览

联犀内置小智 AI 为设备提供以下能力（设备端接入要求各不相同）：

能力	设备端要求	触发方式
语音对话（ASR→LLM→TTS）	采集/播放音频（UDP 通道）	设备主动 sessionCreate + audioStart
文字对话	无（纯协议）	设备 sessionCreate + inputSend
多模态输入（图片/视频/文件）	支持 HTTP 上传文件	设备上传后 inputSend 带 fileUri
拍照识图	实现 takePhoto action + 文件上传	平台主动下发 action，设备被动执行

2. 拍照识图整体流程

拍照识图是平台主动调用设备的能力：LLM 识别到用户需要"看图"时，平台下发拍照指令，设备被动执行。

用户语音/文字："看看我桌上有什么"
  → 平台 LLM 识别意图 → 调用 fuzai 的 deviceTakePhoto MCP 工具
    → 平台下发 takePhoto action（$thing/down/action/{ProductID}/{DeviceName}）
      → 设备拍照 → 上传图片（HTTP upload-file）→ 上报 actionReply（带 fileUri）
    → 平台下载图片转 base64 → 多模态 LLM 识图
  → 平台回复识别结果（语音 TTS / 文字 respTextDone）

关键点：

• 平台主动下发，设备被动执行：设备不主动发图，收到 takePhoto action 才拍照
• 设备只做三件事：拍照 → 上传 → 上报 fileUri，不理解图片内容
• 识别（识图）由平台多模态 LLM 完成，设备零 AI 逻辑

3. 设备端接入步骤

3.1 物模型配置

设备所属产品需在物模型中配置 takePhoto 行为（Action）：

{
  "identifier": "takePhoto",
  "name": "拍照",
  "dir": "down",
  "input": null,
  "output": [
    { "identifier": "fileUri", "name": "图片访问地址", "define": { "type": "string" } }
  ]
}

• dir: "down"：云端 → 设备（平台下发，设备执行）
• 无入参（input: null）：识别引导语由平台 LLM 根据用户原话完成，设备端无需接收 question
• 出参 fileUri：设备上传图片后返回的访问地址

3.2 接收拍照指令

设备订阅 $thing/down/action/{ProductID}/{DeviceName}，收到 method=action 且 actionID=takePhoto 时拍照：

{
  "method": "action",
  "msgToken": "20a4ccfd-d308-11e9-86c6-5254008a4f10",
  "actionID": "takePhoto",
  "timestamp": 1677762028638,
  "params": {}
}

参数	说明
msgToken	消息 ID，上报回复时必须原样带回，用于请求-响应配对
actionID	takePhoto（物模型行为标识符）
params	空对象（takePhoto 无入参）

3.3 拍照并上传图片

设备调用摄像头拍照后，通过 HTTP 上传图片：

项	值
URL	POST /api/v1/things/device/edge/upload-file（也可从 sessionCreated.data.uploadUrl 获取）
Content-Type	multipart/form-data
认证	Basic Auth（MQTT 账号密码）
表单字段	file：图片文件

curl --location --request POST 'https://<平台域名>/api/v1/things/device/edge/upload-file' \
  --header 'Authorization: Basic <base64(mqtt_username:mqtt_password)>' \
  --form 'file=@"/path/to/photo.jpg"'

响应：

{
  "code": 200,
  "msg": "success",
  "data": {
    "filePath": "edge/{productID}/{deviceName}/250806/photo.jpg",
    "fileUri": "https://xxx.oss.com/edge/{productID}/{deviceName}/250806/photo.jpg"
  }
}

data.fileUri 就是后面要上报给平台的图片地址。 注意禁止上传 html/php/svg 等危险文件类型。

3.4 上报拍照结果（actionReply）

设备拍照上传完成后，向 $thing/up/action/{ProductID}/{DeviceName} 发布 actionReply，msgToken 原样带回，data 携带 fileUri：

{
  "method": "actionReply",
  "msgToken": "20a4ccfd-d308-11e9-86c6-5254008a4f10",
  "code": 200,
  "msg": "success",
  "data": {
    "fileUri": "https://xxx.oss.com/edge/{productID}/{deviceName}/250806/photo.jpg"
  }
}

参数	说明
method	actionReply
msgToken	必须与下发时一致（平台按它匹配原请求）
code	200 表示成功
data	物模型 action 出参，必须含 fileUri 字段（平台解析该字段取图）

⚠️ data 必须带 fileUri，否则平台无法获取图片。若拍照/上传失败，code 返回非 200，msg 说明错误。

3.5 平台识图回复

平台收到 actionReply 后，下载图片转 base64，由多模态 LLM 识图，最后：

• 语音场景：audioSpeechStarted → UDP 音频帧 → audioSpeechStopped 播报识别结果
• 文字场景：respTextDelta / respTextDone 下发识别文本

设备端无需特殊处理，与普通 AI 回复完全相同。

4. 设备端上报/上传能力要求汇总

能力	协议/接口	说明
接收拍照指令	MQTT $thing/down/action/{PID}/{DN}	method=action，actionID=takePhoto
上传图片	HTTP POST /api/v1/things/device/edge/upload-file	Basic Auth，multipart file
上报结果	MQTT $thing/up/action/{PID}/{DN}	method=actionReply，msgToken 原样带回，data 带 fileUri

5. 与多模态输入（inputSend）的区别

设备也可以主动上传图片并通过 inputSend 发给 AI（见 AI 交互协议 多模态输入章节）：

	拍照识图（takePhoto）	多模态输入（inputSend）
触发方	平台主动下发	设备主动发送
设备动作	拍照 → 上传 → actionReply	上传 → inputSend 带 fileUri
场景	用户说"看看/拍个照"，平台驱动设备	设备有图片/文件要主动提供给 AI
设备要求	实现 takePhoto action	实现 HTTP 上传 + inputSend

两种方式共用同一套文件上传接口（upload-file），区别在触发方向。

6. 版本说明

版本	时间	说明
v1.0	2026-08-06	首次发布：拍照识图（takePhoto action + 文件上传 + actionReply）接入说明

更新日志

2026/8/8 10:58

查看所有更新日志

• d94c1-Merge #21 into master from docs/xiaozhi-ai-feature于 2026/8/8

贡献者: 杨磊

上一页UDP 音频通道协议

下一页如何快速接入第三方协议