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

前言

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

平台更新说明（2026）：

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

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

一、智能体平台架构概览

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

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

核心组件说明：

二、准备工作

2.1 必备条件

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

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 格式

文件准备建议：

Q&A 格式示例（Excel）：

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. 添加以下控件示例：

4.3 生成 MCP 工具

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

工具描述示例：

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 验证完整流程

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

六、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"}
    ]
  }'

流式事件顺序：

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 设备端没有反应？

按以下顺序排查：

7.3 知识库回答不准确？

7.4 MCP 工具调用失败？

7.5 响应延迟过大？

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

常见优化方向：

八、进阶技巧

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 合成：

九、总结

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

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

关键要点回顾：

下一步学习建议：

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

参考资源

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