SmartPi 智能体平台实战：从知识库问答到设备控制的完整闭环

smartpi
9 阅读13分钟

前言

在智能家居和语音交互产品开发中，如何让设备"懂"你的产品？如何让用户通过自然对话完成设备控制？SmartPi 智能体平台提供了一套完整的解决方案——从知识库问答（RAG）到设备控制（MCP），让开发者能够快速打造智能语音交互体验。

平台更新说明（2026）：

  • 智能体平台已升级为统一控制台，支持 API 发布和工作流编排
  • PAT（Personal Access Token）成为推荐鉴权方式
  • MCP 插件支持通过 mcp_tool.yaml 文件一键导入
  • 新增对话流（Workflow）可视化编排能力

本文将带你完成一个完整的实战项目：打造一个能回答设备说明书问题，并能控制灯光亮度的智能语音助手。

一、智能体平台架构概览

在开始实战之前，先理解 SmartPi 智能体平台的整体架构：

┌─────────────────────────────────────────────────────────────────┐
│                         用户交互层                                │
├─────────────────────────────────────────────────────────────────┤
│  语音唤醒  →  ASR识别  →  智能体对话  →  TTS播报  →  设备控制    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      智能体平台 (云端)                            │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐           │
│  │  知识库RAG  │   │   插件/MCP  │   │  自定义LLM  │           │
│  │  (设备问答) │   │  (设备控制) │   │  (扩展能力) │           │
│  └─────────────┘   └─────────────┘   └─────────────┘           │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      SmartPi 平台 (中台)                          │
├─────────────────────────────────────────────────────────────────┤
│  固件配置  →  MCP工具生成  →  二维码绑定  →  小程序控制          │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                        设备端 (本地)                              │
├─────────────────────────────────────────────────────────────────┤
│  语音模块  →  命令执行  →  GPIO控制  →  状态上报                 │
└─────────────────────────────────────────────────────────────────┘

核心组件说明：

组件作用典型应用
知识库 (RAG)让智能体基于你提供的资料回答设备说明书、FAQ、产品规格
MCP/插件让智能体能够调用外部工具控制设备开关控制、参数调节、状态查询
PATAPI 调用鉴权凭证保护智能体接口安全
二维码绑定将云端智能体与本地设备关联一键完成配置同步

二、准备工作

2.1 必备条件

在开始之前，请确认以下资源已准备就绪：

资源说明获取方式
SmartPi 平台账号用于配置固件和生成二维码smartpi.cn 注册
智能体平台地址你们部署的控制台地址由技术团队提供
支持智能体的设备带 "AI 智能体" 菜单的语音模组如 JX-A7T 等在线语音模块
微信小程序"智能公元"小程序微信搜索即可

2.2 检查设备是否支持智能体

  1. 打开"智能公元"微信小程序
  2. 进入设备详情页
  3. 查看是否有 "AI 智能体" 菜单

注意：如果看不到该菜单，说明当前设备/固件不支持智能体功能，需要升级到支持在线语音的固件版本。

三、实战第一步：创建知识库问答智能体

我们的第一个目标是：让智能体能够回答设备说明书中的问题，例如"这款设备怎么配网？"、"如何恢复出厂设置？"等。

3.1 创建智能体

  1. 登录智能体平台控制台
  2. 进入 开发 / Development → 点击 创建 / Create
  3. 填写基本信息：
    • 名称：设备说明书助手（或更具体的场景名，如"客厅灯光助手"）
    • 介绍：回答设备使用问题，并能控制设备
    • 提示词：先用最简版本
# 最小可用提示词（可直接复制）
你是设备的智能语音助手。
你的任务是：
1. 回答用户关于设备使用的各种问题
2. 基于知识库内容回答，找不到答案就说"这个问题我不太清楚"
3. 用简洁的中文回答，每次回答不超过50字

3.2 准备知识库文件

知识库是智能体的"专业大脑"，让它能够回答你们产品/设备的专属问题。

文件格式支持：

  • PDF、Word (.docx)
  • 纯文本 (.txt, .md)
  • Excel/CSV (.xlsx, .csv) —— 适合 Q&A 格式

文件准备建议：

建议说明
文件大小单文件控制在 5MB 以内，大文件请按章节拆分
内容格式使用清晰的标题和段落结构
Q&A 格式关键信息推荐用问答对方式呈现，便于精准匹配

Q&A 格式示例（Excel）：

问题答案
设备如何配网？打开小程序，点击添加设备，选择设备型号，输入 Wi-Fi 密码即可完成配网
如何恢复出厂设置？长按设备上的复位按钮 5 秒，听到提示音后松开，设备将恢复出厂设置
设备支持哪些语音指令？支持开关控制、亮度调节、颜色切换等指令，具体请查看产品说明书

3.3 创建并关联知识库

  1. 在智能体平台进入 资源库 / Resource Library
  2. 创建 知识库 / Knowledge，命名为 设备说明书-2025Q1
  3. 上传准备好的文件
  4. 等待解析完成（状态从"解析中"变为"完成"）
  5. 回到智能体编辑页，在"知识/Knowledge"区域选择刚创建的知识库
  6. 保存配置

3.4 验证知识库效果

在智能体预览窗口测试以下三类问题：

问题类型示例问题预期结果
资料里有答案的"设备怎么配网？"能准确回答
资料里有步骤的"如何恢复出厂设置？"能按步骤说明
资料里没有的"你们公司上市了吗？"回答"不清楚"或类似内容

如果智能体对资料外的问题也在"胡编"，需要在提示词中加入更强的约束：

## 重要限制
- 只能基于知识库内容回答
- 知识库中没有答案的问题，必须回答"这个问题我不太清楚"
- 不要猜测或编造信息

四、实战第二步：让智能体具备设备控制能力

知识库让智能体"能答"，现在要让它"能做"。我们将通过 MCP（Model Context Protocol）工具让智能体能够控制设备。

4.1 理解 MCP 工具

MCP 是连接大模型与设备控制的桥梁：

┌─────────────┐      语音输入      ┌─────────────┐
│    用户     │ ──────────────────→ │   智能体    │
└─────────────┘                     └─────────────┘
                                              │
                                              │ 调用 MCP 工具
                                              ↓
┌─────────────┐      工具调用      ┌─────────────┐
│   设备      │ ←────────────────── │  MCP 服务   │
│  (GPIO等)   │                     └─────────────┘
└─────────────┘

4.2 配置设备控件

在配置 MCP 工具之前，需要先在小程序平台定义好可控制的"控件"：

  1. 登录 SmartPi 平台 (smartpi.cn)
  2. 选择你的设备和固件版本
  3. 进入 控制面板 / 面板编辑
  4. 添加以下控件示例：
控件类型控件 ID说明
开关switch_light控制灯光开关
滑块slider_brightness调节亮度（0-100）
状态显示text_status显示当前状态

4.3 生成 MCP 工具

  1. 在 SmartPi 平台进入 MCP 工具 菜单
  2. 点击 刷新 按钮，平台会自动根据已配置的控件生成工具
  3. 为每个工具补充清晰的名称和描述（这是智能体理解工具用途的关键）

工具描述示例：

工具名称描述
控制灯光开关打开或关闭灯光，参数：on=开，off=关
调节灯光亮度调节灯光亮度，参数：0-100 的数值，0 为最暗，100 为最亮
查询灯光状态查询灯光当前的状态，包括开关和亮度值

4.4 发布 MCP 工具

  1. 在固件版本发布页面，勾选 发布 MCP 工具
  2. 生成并下载新固件
  3. 将固件烧录到设备

注意：MCP 工具只有在固件发布后才会生效，修改描述后需要重新发布。

4.5 导入插件到智能体（可选方案）

如果你的方案需要通过插件方式调用，可以按以下步骤操作：

  1. 在 SmartPi 平台 MCP 工具页面，点击 预览 → 下载插件
  2. 获得 mcp_tool.yaml 文件
  3. 在智能体平台 资源库 中 添加插件 → 导入 该文件
  4. 将所有工具设置为 启用
  5. 进行 试运行，参数中 token 固定填 Bearer test

五、实战第三步：发布智能体并绑定设备

现在我们已经有了：

  • 一个能回答问题的知识库
  • 一套能控制设备的 MCP 工具

最后一步是将智能体发布为 API 服务，并绑定到具体设备。

5.1 生成个人访问令牌 (PAT)

PAT（Personal Access Token）是调用智能体 API 的安全凭证。

  1. 在智能体平台点击左下角头像
  2. 进入 API Authorization / API 授权
  3. 点击 Add New Token / 新建令牌
  4. 填写名称和过期时间
  5. 立即复制并保存 —— PAT 只展示一次！

调用 API 时需要在请求头中携带：

Authorization: Bearer pat_xxxxx

5.2 发布智能体为 API 服务

  1. 在智能体页面右上角点击 发布 / Publish
  2. 选择 API 发布方式
  3. 发布后记录两个关键信息：
    • bot_id：浏览器地址栏 bot/ 后的数字
    • PAT：上一步生成的令牌

5.3 在 SmartPi 平台创建智能体配置

  1. 打开 SmartPi 平台 (smartpi.cn)
  2. 进入 智能体 → 配置
  3. 创建新配置并填写：
    • 名称：如"客厅灯光智能体"
    • 平台选择：Coze 或其他支持的智能体平台
    • 智能体 ID（bot_id）：从上一步复制
    • 个人访问令牌（PAT）：从上一步复制
  4. 保存后，平台会生成一个 绑定二维码

5.4 使用小程序扫码绑定

  1. 打开"智能公元"微信小程序
  2. 进入设备详情页
  3. 点击 AI 智能体 菜单
  4. 扫描上一步生成的二维码

注意：二维码有效期为 10 分钟，超时需重新生成。

5.5 验证完整流程

绑定成功后，可以进行端到端测试：

测试指令预期行为
"你好"智能体正常回复
"设备怎么配网？"基于知识库回答配网步骤
"把灯打开"调用 MCP 工具，设备灯光开启
"把亮度调到 50"调用 MCP 工具，亮度变为 50%
"现在灯什么状态？"调用查询工具，播报当前状态

六、OpenAPI 调用速查

对于需要通过代码调用智能体的场景，智能体平台提供了标准的 REST API。

6.1 请求头配置

所有 API 调用都需要携带以下请求头：

Authorization: Bearer pat_xxxxx
Content-Type: application/json

6.2 创建会话（Conversation）

在发起对话之前，需要先创建一个会话：

curl --location '{{host}}/v1/conversation/create' \
  --header 'Authorization: Bearer pat_xxxxx' \
  --header 'Content-Type: application/json' \
  --data '{"bot_id":"<bot_id>"}'

响应示例：

{
  "code": 0,
  "data": {
    "conversation_id": "conv_xxxxx",
    "created_at": 1234567890
  }
}

6.3 发起对话（Chat v3，流式 SSE）

使用流式输出可以获得更好的用户体验：

curl --location --request POST '{{host}}/v3/chat?conversation_id=<conversation_id>' \
  --header 'Authorization: Bearer pat_xxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "bot_id": "<bot_id>",
    "user_id": "<your_user_id>",
    "stream": true,
    "auto_save_history": true,
    "additional_messages": [
      {"role":"user","content":"你好","content_type":"text"}
    ]
  }'

流式事件顺序：

事件说明
conversation.chat.created对话创建
conversation.chat.in_progress对话进行中
conversation.message.delta消息增量（流式返回内容）
conversation.message.completed消息完成
conversation.chat.completed对话完成
done流结束

6.4 消息列表与清理上下文

# 获取消息列表
POST {{host}}/v1/conversation/message/list?conversation_id=<conversation_id>

# 清理对话上下文
POST {{host}}/v1/conversations/<conversation_id>/clear

6.5 执行工作流（Workflow）

如果使用对话流/工作流，可以直接执行：

curl --location --request POST '{{host}}/v1/workflow/run' \
  --header 'Authorization: Bearer pat_xxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "workflow_id": "<workflow_id>",
    "parameters": "{\"user_id\":\"12345\"}"
  }'

七、常见问题排查

7.1 PAT 忘记保存怎么办？

PAT 通常只在创建时展示一次，丢失后需要：

  1. 重新生成新的 PAT
  2. 更新 SmartPi 平台中的智能体配置
  3. 重新生成二维码并绑定设备

7.2 设备端没有反应？

按以下顺序排查：

排查项检查方法
菜单支持小程序中是否有"AI 智能体"菜单
配置正确bot_id 和 PAT 是否正确（多余空格也会导致失败）
API 发布智能体是否已发布为 API 服务
网络连接设备是否正常联网
固件版本是否烧录了包含 MCP 工具的最新固件

7.3 知识库回答不准确？

问题解决方案
回答内容与资料不符检查知识库文件解析是否完成
对资料外问题乱回答在提示词中加入更强的约束规则
找不到答案调整相似度阈值（默认 0.5，可适当降低）

7.4 MCP 工具调用失败？

问题解决方案
工具未启用在插件管理中确认工具已启用
试运行失败确认 token 参数填写正确（Bearer test）
设备无响应检查固件是否正确烧录，MCP 工具是否已发布

7.5 响应延迟过大？

智能体对话的完整链路包括：ASR → 网络传输 → LLM 推理 → 工具调用 → 网络传输 → TTS

常见优化方向：

环节优化建议
网络传输确保设备网络稳定，减少路由跳数
LLM 推理使用更快的模型，或启用流式输出
对话流关闭"深度思考"功能以减少响应时间
缓存对常见问题配置缓存机制

八、进阶技巧

8.1 对话流/工作流 (Workflow) 应用

对于复杂场景，可以使用对话流编排多个工具的调用顺序：

  1. 在智能体平台创建 对话流 / Chatflow
  2. 在开始节点定义输入变量：token、deviceKey
  3. 在大模型节点关闭 深度思考
  4. 添加插件节点，引用输入变量
  5. 在结束节点开启 流式输出
  6. 发布对话流，获得 workflow_id
  7. 在 SmartPi 平台智能体配置中填写该 ID

8.2 自定义大模型接入

如果需要接入自建的大模型服务（如 VLLM、Xinference）：

  1. 在智能体平台进入 模型提供商 管理
  2. 选择对应的模型类型（VLLM/Xinference）
  3. 填写配置参数：
    • 基础 URL：模型服务的 API 地址
    • API Key：认证密钥（如需要）
    • 最大 Token：单次请求限制

VLLM 部署示例：

docker run --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 \
  --name vllm-server \
  vllm/vllm-openai \
  --model your-model-name \
  --trust-remote-code

8.3 方言支持

通过自建 GPU 服务器部署方言识别和 TTS 合成：

方言支持情况
粤语支持 ASR 和 TTS
上海话支持 ASR 和 TTS
四川话支持 ASR 和 TTS

九、总结

通过本文的实战演练，我们完成了一个完整的智能体开发流程：

知识库配置 → MCP 工具生成 → API 发布 → 设备绑定 → 端到端测试

关键要点回顾：

要点说明
知识库是智能体的专业大脑，用 Q&A 格式效果最佳
MCP 工具是连接 AI 与设备的桥梁，描述要清晰准确
PAT只展示一次，务必妥善保存
二维码绑定有效期 10 分钟，需要提前准备设备
提示词优化根据实际效果持续迭代，加入约束规则

下一步学习建议：

  1. 掌握提示词工程，优化智能体的回复质量
  2. 学习对话流编排，处理复杂的多轮对话场景
  3. 了解自定义模型接入，部署专属的大模型服务

参考资源

资源名称链接
SmartPi 平台smartpi.cn
智能体平台快速开始官方文档 /ai-agents/get-started
知识库配置指南官方文档 /ai-agents/knowledge-base-setup
智能体控制台指南官方文档 /ai-agents/platform-guide
智能体实践教程官方文档 /ai-agents/tutorial

本文档基于 SmartPi 官方文档整理，涵盖智能体平台的核心功能和实战操作。

avatar
文章
阅读
粉丝