平台与设备准备

先完成下列配置，再选目标场景实现设备程序。界面名称可能随部署的权限和版本调整；没有可用配置入口时由部署管理员配置，不能凭设备报文开启平台未装配的能力。

操作方	操作入口与动作	检查结果
平台管理员	平台管理 → AI 中台 → 模型配置：配置并启用所需模型；串联语音分别需要 ASR、文字模型和 TTS，实时语音需要已装配的 Realtime 模型	实际模型与本次输入／输出模态匹配；密钥仅保存在平台
智能体配置者	在 AI 中台的分组、智能体配置中绑定模型及允许使用的 MCP 服务	分组继承与智能体覆盖后的最终配置可用；工具只开放必要范围
产品与设备管理员	创建产品及设备、设置主人／项目归属和产品物模型；在设备详情的智能体分身页检查绑定，需要时创建分身	产品、设备、主人和分身关系有效，设备具备业务操作权限
部署管理员	确认目标部署已启用对应信令适配、UDP／WebRTC 媒体及上传／存储能力	服务可达且采用部署方提供的 TLS、地址和凭据；不是仅配置模型即可通话
设备开发者	按快速接入完成认证、订阅、真实能力上报与两轮文字闭环	应答、回复和终态关联正确，再增加音频、摄像头或工具

本页下方拍照及能力示例使用 $thing/*/ai；其中字段和 UDP 限制仅适用于该接入契约。signaling/message 的能力上报、WebRTC、附件引用及工具流程请分别使用场景接入与协议参考，不能拼接两种信封。先查能力范围，模型能够收图不表示已实现 AI 视频。

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

关联文档：

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

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

1. 能力总览

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

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

两种语音方案并存，由平台按 Agent 配置选择。设备在 sessionCreate.supportedInteractionModes 报告支持的 halfDuplex / fullDuplex 模式，并通过 aecMode 报告回声处理能力；平台在 sessionCreated.data.interactionMode 返回本次选定模式。旧设备未上报时在流式 ASR + LLM + TTS 配置下保持原有逐轮收音方式；若 Agent 仅启用 Realtime 端到端语音模型，旧设备会话创建将失败。选定全双工后，回复播放期间麦克风仍可通过同一 UDP 通道上行，插话时清空旧回复音频队列。全双工当前要求设备侧 AEC，且只使用 UDP；详细报文字段和时序见 AI 交互协议。拍照识图的 takePhoto / actionReply 设备协议不因语音链路变化。

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/10/17 03:27

查看所有更新日志

• d04e1-docs(AI与音视频): 按公共主线与场景分支整合接入手册于 2026/10/17
• d94c1-Merge #21 into master from docs/xiaozhi-ai-feature于 2026/8/8

贡献者: 杨磊

上一页场景与能力支持范围

下一页AI与音视频快速接入