OddMeta
A place to learn and practice AI
OddMeta
ProjectXL

OddAgent：从0到1打造你自己的智能家居语音助手

by |Published

想不想拥有一个完全属于你自己的”小爱同学”或”小艺”？今天我来教你用开源项目 OddAgent，从零开始搭建一套智能家居意图识别系统。

一、前言

清晨，你刚睁开眼，窗帘自动缓缓拉开，温暖的阳光洒进房间。你随口说一句”我起床了”，灯光从暗淡的夜灯模式切换到柔和的晨光，咖啡机已经启动——这不是科幻电影，而是智能家居正在实现的未来。

然而，当你想要DIY一套完全可控的智能家居系统时，往往面临两难：要么选择米家、HomeKit 等封闭生态，功能受限于平台；要么自研整个系统，从设备协议到AI对话，技术门槛高得离谱。

今天要介绍的 OddAgent 项目，为我们提供了一条中间路线——它专注于意图识别，你可以对接任意品牌的设备，只需专注于实现具体的业务逻辑。

二、方案介绍

2.1 什么是 OddAgent

概念定义
OddAgent一个通用的意图、指令识别框架，基于 LLM 实现自然语言理解
Intent（意图）用户想要完成的操作，如”打开客厅灯”
Slot（槽位）意图中的关键参数，如房间”客厅”、设备”灯”
Tool（工具）实际执行操作的接口，如控制灯的 API

配图 1

展示 OddAgent 识别用户语音/文字指令的流程图

OddAgent 的核心能力可以用一句话概括：“只负责听懂你要什么，不负责具体怎么干。” 它把意图识别做到极致，把功能实现交给开发者。

2.2 核心特性

  • 多轮对话：支持上下文理解，可以追问和确认
  • 流式输出：实时响应，体验流畅
  • 模板化工具：通过 JSON 配置即可定义新功能
  • 多智能体：支持同时运行多个独立的 AI 助手
  • 语音支持：可对接 ASR 实现语音交互

2.3 为什么选择 OddAgent

对比自研 NLU 系统：

维度自研 NLUOddAgent
开发周期3-6 个月1 天配置
识别准确率依赖训练数据依赖 LLM 能力
扩展性需改代码改配置即可
维护成本高低

OddAgent 把”听懂人话”这件事，交给更擅长的大语言模型，让开发者专注在真正有价值的设备控制逻辑上。

三、安装与部署

3.1 环境准备

OddAgent 对环境的要求非常友好：

要求说明
Python3.10+
网络能访问你的 LLM API
虚拟环境推荐使用 conda 或 venv
# 创建虚拟环境
conda create -n oddagent python==3.12
conda activate oddagent

# 安装 oddagent
pip install -i https://pypi.org/simple/ oddagent

3.2 项目初始化

配图 2

展示目录结构截图

# 创建项目目录
mkdir smart_home_agent
cd smart_home_agent

# 下载配置样例
# 项目配置样例
curl -o config.json.sample https://oddmeta.net/tools/oddagent/config.json.sample
# 智能体配置样例
curl -o conference_config.json https://oddmeta.net/tools/oddagent/conference_config.json

3.3 配置大模型

编辑 config.json，这是最重要的配置：

{
  "GPT_URL": "https://your-llm-api.com/v1/chat/completions",
  "MODEL": "your-model-name",
  "API_KEY": "your-api-key-here",

  "BACKEND_HOST": "localhost",
  "BACKEND_PORT": 5050,

  "TOOL_CONFIG_FILE": "smarthome_config.json"
}

支持的 LLM 提供商示例：

提供商URL 示例模型示例
百度千帆https://qianfan.baidubce.com/v2/chat/completionsernie-4.5-turbo-128k
阿里通义https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completionsqwen3-30b-a3b
OpenAIhttps://api.openai.com/v1/chat/completionsgpt-4o

3.4 启动服务

# 在项目目录下启动
oddagent -c config.json

服务启动后，会在 http://localhost:5050 运行。

四、智能家居功能配置

4.1 配置文件结构

OddAgent 的核心魔法在于 agent_tool_list 字段。让我用智能家居场景来演示：

{
  "global_variants": [],
  "agent_tool_list": [
    {
      "tool_name": "light_control",
      "name": "灯光控制",
      "description": "控制智能灯光的开关、亮度、颜色等",
      "example": "JSON：[{'name': 'action', 'desc': '操作类型，开或关', 'value': ''}, ...]",
      "slots": [
        {"name": "action", "desc": "操作类型，开或关", "value": "", "required": false},
        {"name": "room", "desc": "房间名称", "value": "", "required": false},
        {"name": "brightness", "desc": "亮度百分比(0-100)", "value": "", "required": false},
        {"name": "color", "desc": "灯光颜色", "value": "", "required": false}
      ],
      "enabled": true,
      "tool_api_url": ""
    }
  ]
}

4.2 完整的智能家居功能列表

功能tool_name支持的操作关键槽位
灯光控制light_control开/关、调亮度、调颜色room, brightness, color
空调控制ac_control开/关、调温度、调模式room, temperature, mode, fan_speed
电视控制tv_control开/关、调音量、换频道room, volume, channel, source
窗帘控制curtain_control开/关、调位置room, position
温湿度查询temperature_query查询温湿度room, sensor_type
热水器控制water_heater_control开/关、调温度、调模式temperature, mode
扫地机器人robot_vacuum_control开始/暂停/回充room, mode
空气净化器air_purifier_control开/关、调模式room, mode
门锁控制door_lock_control解锁/上锁/查询lock_name
安防模式security_mode布防/撤防mode
场景控制scene_control执行场景模式scene, action
插座控制power_outlet_control开/关、定时outlet_name, timer
设备查询device_status_query查询设备状态room, device_type
智能音箱speaker_control播放/暂停speaker_name, content

4.3 实战：完整配置文件

以下是我为智能家居场景准备的完整配置，可直接使用：

{
  "global_variants": [],
  "agent_tool_list": [
    {
      "tool_name": "light_control",
      "name": "灯光控制",
      "description": "控制智能灯光的开关、亮度、颜色等",
      "example": "JSON：[{'name': 'action', 'desc': '操作类型，开或关', 'value': ''}, {'name': 'room', 'desc': '房间名称', 'value': ''}, {'name': 'brightness', 'desc': '亮度百分比(0-100)', 'value': ''}, {'name': 'color', 'desc': '灯光颜色', 'value': ''}]",
      "slots": [
        {"name": "action", "desc": "操作类型，开或关", "value": "", "required": false},
        {"name": "room", "desc": "房间名称，如客厅、卧室、厨房等", "value": "", "required": false},
        {"name": "brightness", "desc": "亮度百分比(0-100)", "value": "", "required": false},
        {"name": "color", "desc": "灯光颜色，如暖白、冷白、红色等", "value": "", "required": false}
      ],
      "enabled": true,
      "tool_api_url": ""
    },
    {
      "tool_name": "ac_control",
      "name": "空调控制",
      "description": "控制空调的开关、温度、风速、模式等",
      "example": "JSON：[{'name': 'action', 'desc': '操作类型，开或关', 'value': ''}, {'name': 'room', 'desc': '房间名称', 'value': ''}, {'name': 'temperature', 'desc': '目标温度', 'value': ''}, {'name': 'mode', 'desc': '空调模式', 'value': ''}, {'name': 'fan_speed', 'desc': '风速', 'value': ''}]",
      "slots": [
        {"name": "action", "desc": "操作类型，开或关", "value": "", "required": false},
        {"name": "room", "desc": "房间名称，如客厅、卧室等", "value": "", "required": false},
        {"name": "temperature", "desc": "目标温度，范围16-30度", "value": "", "required": false},
        {"name": "mode", "desc": "空调模式：制冷、制热、送风、除湿、自动", "value": "", "required": false},
        {"name": "fan_speed", "desc": "风速：低、中、高、自动", "value": "", "required": false}
      ],
      "enabled": true,
      "tool_api_url": ""
    },
    {
      "tool_name": "tv_control",
      "name": "电视控制",
      "description": "控制智能电视的开关、音量、频道等",
      "example": "JSON：[{'name': 'action', 'desc': '操作类型，开或关', 'value': ''}, {'name': 'room', 'desc': '房间名称', 'value': ''}, {'name': 'volume', 'desc': '音量调节', 'value': ''}, {'name': 'channel', 'desc': '频道名称或编号', 'value': ''}]",
      "slots": [
        {"name": "action", "desc": "操作类型，开或关", "value": "", "required": false},
        {"name": "room", "desc": "房间名称，如客厅、卧室等", "value": "", "required": false},
        {"name": "volume", "desc": "音量调节，可为具体数值或增减操作", "value": "", "required": false},
        {"name": "channel", "desc": "频道名称或编号", "value": "", "required": false}
      ],
      "enabled": true,
      "tool_api_url": ""
    },
    {
      "tool_name": "curtain_control",
      "name": "窗帘控制",
      "description": "控制智能窗帘的开关和开合程度",
      "example": "JSON：[{'name': 'action', 'desc': '操作类型，开或关', 'value': ''}, {'name': 'room', 'desc': '房间名称', 'value': ''}, {'name': 'position', 'desc': '开合程度百分比', 'value': ''}]",
      "slots": [
        {"name": "action", "desc": "操作类型，开、关、暂停", "value": "", "required": false},
        {"name": "room", "desc": "房间名称，如客厅、卧室、主卧等", "value": "", "required": false},
        {"name": "position", "desc": "开合程度百分比(0-100)", "value": "", "required": false}
      ],
      "enabled": true,
      "tool_api_url": ""
    },
    {
      "tool_name": "scene_control",
      "name": "场景控制",
      "description": "执行或切换智能家居场景模式",
      "example": "JSON：[{'name': 'scene', 'desc': '场景名称', 'value': ''}, {'name': 'action', 'desc': '操作类型', 'value': ''}]",
      "slots": [
        {"name": "scene", "desc": "场景名称：离家模式、回家模式、睡眠模式、观影模式、用餐模式、晨起模式等", "value": "", "required": false},
        {"name": "action", "desc": "操作类型：开启、关闭、切换", "value": "", "required": false}
      ],
      "enabled": true,
      "tool_api_url": ""
    },
    {
      "tool_name": "door_lock_control",
      "name": "门锁控制",
      "description": "控制智能门锁的状态和查看门锁信息",
      "example": "JSON：[{'name': 'action', 'desc': '操作类型', 'value': ''}, {'name': 'lock_name', 'desc': '门锁名称', 'value': ''}]",
      "slots": [
        {"name": "action", "desc": "操作类型：解锁、上锁、查询状态", "value": "", "required": false},
        {"name": "lock_name", "desc": "门锁名称或位置，如前门、后门等", "value": "", "required": false}
      ],
      "enabled": true,
      "tool_api_url": ""
    },
    {
      "tool_name": "security_mode",
      "name": "安防模式控制",
      "description": "设置和切换家庭安防模式",
      "example": "JSON：[{'name': 'mode', 'desc': '安防模式', 'value': ''}, {'name': 'action', 'desc': '操作类型', 'value': ''}]",
      "slots": [
        {"name": "mode", "desc": "安防模式：在家布防、外出布防、睡眠布防、撤防", "value": "", "required": false},
        {"name": "action", "desc": "操作类型：启动、关闭、查询状态", "value": "", "required": false}
      ],
      "enabled": true,
      "tool_api_url": ""
    },
    {
      "tool_name": "temperature_query",
      "name": "温湿度查询",
      "description": "查询室内温湿度传感器数据",
      "example": "JSON：[{'name': 'room', 'desc': '房间名称', 'value': ''}, {'name': 'sensor_type', 'desc': '传感器类型', 'value': ''}]",
      "slots": [
        {"name": "room", "desc": "房间名称，不指定则查询全屋", "value": "", "required": false},
        {"name": "sensor_type", "desc": "传感器类型：温度、湿度、全部", "value": "", "required": false}
      ],
      "enabled": true,
      "tool_api_url": ""
    }
  ]
}

完整的配置文件可以在项目仓库中找到（smarthome_config.json）

4.4 场景模式详解

智能家居的核心体验在于场景联动。以下是推荐的预设场景：

场景触发动作执行的设备操作
离家模式启动安防关闭所有灯光、空调、电视，启动安防
回家模式撤防打开玄关灯、客厅灯，关闭安防
睡眠模式夜间关闭所有灯光，关闭窗帘，调低空调
观影模式启动关闭主灯，打开氛围灯，电视打开
用餐模式启动餐厅灯打开，客厅灯调暗
晨起模式定时窗帘打开，播放轻音乐，咖啡机启动

五、API 调用示例

5.1 识别意图

import json
import requests

API_BASE_URL = 'http://127.0.0.1:5050/oddagent/chat'

def recognize_intent(message):
    """调用 oddagent 识别意图"""
    response = requests.post(
        API_BASE_URL,
        json={
            'question': message,
            'api_mode': 1  # 模拟模式，1-模拟，0-真实调用
        }
    )
    return response.json()

# 测试
result = recognize_intent("把客厅空调调到26度")
print(json.dumps(result, ensure_ascii=False, indent=2))

5.2 返回结果解析

{
  "answer": "好的，我已为您将客厅空调温度设置为26度。",
  "intent": {
    "tool_name": "ac_control",
    "name": "空调控制",
    "slots": {
      "action": "开",
      "room": "客厅",
      "temperature": "26"
    }
  },
  "tool_api_url": ""
}

5.3 对接实际设备

识别到意图后，你需要在业务层实现具体的设备控制逻辑：

def handle_ac_control(slots):
    """处理空调控制"""
    action = slots.get('action')
    room = slots.get('room', '客厅')
    temperature = slots.get('temperature')

    # 这里调用实际的设备控制 API
    # 例如：米家、小米、天猫精灵等平台的 API
    if action == '开':
        return f"已将{room}空调打开，温度{temperature}度"
    else:
        return f"已将{room}空调关闭"

六、使用场景与案例

6.1 案例一：早晨起床

用户输入： “早上好”

识别结果：

{
  "intent": {
    "tool_name": "scene_control",
    "name": "场景控制",
    "slots": {"scene": "晨起模式", "action": "开启"}
  }
}

执行流程：

  1. OddAgent 识别为”晨起模式”场景
  2. 业务层解析场景配置
  3. 并行执行：打开窗帘、播放音乐、启动咖啡机
  4. 返回完成状态给用户

6.2 案例二：离家检查

用户输入： “我要出门了，帮我检查一下”

识别结果：

{
  "intent": {
    "tool_name": "device_status_query",
    "name": "设备状态查询",
    "slots": {"device_type": "全部"}
  }
}

执行流程：

  1. OddAgent 识别为查询设备状态
  2. 业务层查询所有设备
  3. 发现客厅灯未关、空调未关
  4. 返回：”检测到客厅灯和空调还开着，是否需要关闭？”

6.3 人机协作分工

阶段AI（OddAgent）负责人类/业务系统负责
语音转文字可对接 ASR–
意图识别✅ 核心能力–
参数提取✅ 核心能力–
设备控制–✅ 业务逻辑
状态反馈✅ 生成自然语言✅ 获取设备状态
异常处理✅ 错误解释✅ 设备故障处理

七、拿走即用

7.1 一行命令安装

pip install -i https://pypi.org/simple/ oddagent

7.2 快速配置清单

步骤操作关键配置项
1安装 oddagentpip install oddagent
2下载配置样例config.json.sample
3填写 LLM 配置GPT_URL, MODEL, API_KEY
4创建智能体配置smarthome_config.json
5启动服务oddagent -c config.json

7.3 相关资源

  • GitHub 仓库：https://github.com/oddmeta/oddagent
  • 配置样例：https://oddmeta.net/tools/oddagent/config.json.sample
  • 智能体配置：https://oddmeta.net/tools/oddagent/conference_config.json
  • 语音支持：https://github.com/oddmeta/oddasr

八、注意事项

8.1 生产环境建议

  1. LLM 选型：建议使用国内可访问的模型（如文心、通义），延迟更低
  2. 会话存储：当前版本话数据存储在内存中，生产环境建议使用 Redis
  3. 安全防护：API_KEY 等敏感信息使用环境变量，而非明文配置
  4. 日志记录：建议接入日志系统，便于排查问题

8.2 常见问题

Q: 意图识别不准怎么办？

A: 可以通过优化配置文件的 description 和 example 字段来提升准确率。如果仍不满意，考虑使用更强的模型。

Q: 如何支持更多设备？

A: 在 agent_tool_list 中添加新的工具定义即可，无需修改核心代码。

Q: 能实现多轮对话追问吗？

A: 可以，OddAgent 本身支持多轮对话，但追问逻辑需要在业务层实现。

Q: 语音输入怎么实现？

A: 需要额外部署 OddAsr 项目，然后修改配置中的 ODD_ASR_URL 地址。

九、写在最后

通过今天的教程，你应该已经掌握了：

  1. ✅ OddAgent 的核心设计理念
  2. ✅ 从零部署一个意图识别服务
  3. ✅ 配置智能家居场景的完整方案
  4. ✅ 与实际设备对接的思路

OddAgent 的价值在于：把”听懂人话”这件事做到极简，让开发者专注在真正有价值的业务逻辑上。

如果你有更好的想法，欢迎在评论区交流！

关注我的公众号：奥德元

一起学习AI，一起追赶时代！

新建了一个AI技术交流群，欢迎大家一起加入讨论。
扫码加入AI技术交流群（微信）
若需联系作者，请加微信：oddmeta

You may also like

Published

OpenClaw养成：不花钱的本地化持久记忆方案 lily-memory

序言 想象这样一个场景：你花了半小时向 AI 助手解释你的项目架构、编码偏好和团队规范，得到了一次满意的协作体验。第二天你带着新问题回来，它却一脸茫然——「请问您的项目使用什么技术栈？」 这不是科幻，这是无数 OpenClaw「养成」过程中最常见的阵痛。 这不是科幻，这是无数 OpenClaw 用户每天都在经历的现实。 「OpenClaw 又忘了！」——这是 GitHub Issue 区最常见的抱怨。就在今年 1 月，一位开发者在 Issue #5429 中诉说了自己的遭遇：他花 45 小时与 Agent […]

Published

Three.js:经过一番痛苦的思想斗争，我还是放弃了3D虚拟，转投2D

一、前言 在过去的一段时间里，我花费了大量精力钻研three.js技术，期望能将小落同学的形象塑造为3D虚拟人，实现与用户的交互功能。为此，我对vrm/obj/fbx模型进行了反复调整，还结合mixamo的动作资源进行适配。然而，无论我如何努力，始终无法达到理想的效果。在实际展示中，模型与动作之间总是存在各种问题，比如部分动作出现模型撕裂现象，或是动作呈现出不自然的颤抖，这让我十分苦恼。经过五一假期的深思熟虑，我决定暂时搁置3D方案，转向2D领域寻求解决办法。这意味着之前为three.js所做的模型构建、动作设计、表情制作等工作可能要暂时搁置，虽然心中满是遗憾，但也只能期待未来有机会能让它们重新发挥作用。 二、选定2D解决方案 对于2D虚拟人的实现，其实有多种方案可供选择。在大型商业化直播场景中，许多虚拟人采用VTuber的解决方案。不过，该方案对硬件配置要求较高，以我目前使用的每年仅需99元的阿里云ECS服务器而言，难以满足其运行需求。综合各方面因素考虑，我最终选定了Live2D技术。它不仅技术成熟度高，而且非常适合用于基于Web的虚拟人项目开发，能够很好地满足我的需求。 三、Live2D练手 在Github平台上，有众多关于Live2D的开源项目。其中，目前仍保持活跃状态的项目之一是https://github.com/stevenjoezhang/live2d-widget。我按照该项目提供的步骤进行安装实践，发现当使用远程CDN上的配置时，系统能够正常运行。但当我尝试配置本地的autoload.js时，却始终遭遇“initWidget is not defined”的报错。尽管多次排查尝试，依然未能找到问题的根源，无奈之下只能放弃该项目。 最终，我成功运行了https://github.com/JokerPan12/live2d项目。接下来，我计划先将这个Live2D看板安装到网站上，积累经验后再应用到小落同学的项目中。 四、将Live2D看板安装到wordpress网站上 以下是详细的操作步骤： 1. 下载代码 通过执行以下命令克隆项目代码： 2. 安装SDK代码及live2D模型 从克隆的仓库中，选取live2d、asteroids、icons这三个目录，并上传至网站服务器。我的服务器目录结构如下： 3. 修改wordpress的theme 上传完SDK和模型后，需要对wordpress的主题进行修改，以启用live2d功能。进入wordpress的主题目录：wp-content/themes/{正在使用的主题名}，找到其中的header.php以及footer.php文件。 修改header.php […]

Published

OpenClaw养成：实测可用的免费API Token – OpenCode Zen

一、前言 养了三个星期的龙虾，由于可以在手机上就能指挥它干活，相比电脑上用ClaudeCode/OpenCode或者其它IDE带来了很大的便利，但是带来便利的同时就是这家伙的胃口太好，太吃token了。 前天3月18日，阿里云与百度智能云同一天宣布涨价。阿里云涨幅最高达34%；百度智能云则上调约5%—30%，并行文件存储等价格上调约30%。两家云厂商均将涨价归因于“全球AI需求爆发”。 腾讯云一周前已宣布上调两款自研模型Tencent HY2.0 Instruct和Tencent HY2.0 Think的价格，上涨463%。同时，腾讯云结束对GLM 5、MiniMax 2.5、Kimi 2.5 三款模型的免费公测，转为正式商用服务。 1、阿里云百炼 阿里云百炼 Coding plan套餐：https://bailian.console.aliyun.com/cn-beijing 前两天还有7.9元和39.9元的coding plan套餐，当时只是没抢到。 现在你再打开阿里云百炼的 Coding plan，会发现原先的7.9元和39.9元的两个套餐已经没有了，只剩下那个200元的套餐了。 2、百度云 […]

Published

20250111 聊天机器人学习小记

1. 春考情况 春考结束了，希望是春考后不用再看英语了，但是这次春考的题目感觉比之前做过的每一个模拟卷都难，尤其是星期一的听力，上午和下午两套题差异明显，众多同学都普遍认为下午的比较简单，都是之前练习时涉及比较广泛的，而上午的则是一些新的、之前未涉及的一些内容，我参加的是上午的，心理有一些忐忑。但我知道这个时候我应该放下，不管怎么样，考完了就是考完了，一切等1月21日见分晓。 今天把聊天机器人在老爸的指导下，照着教程改了一下，主要学习的是django框架下的一些数据库操作，修改涉及内容： 2. 学习笔记 为后端加了数据库 共三个model1）agent model （希望可以做成多个智能体）2）session model（会话模型）3）message model（聊天消息模型） 照着文心一言给生成的数据库，并生成了这三个model的代码。然后再：1）python manage.py makemigrations 生成迁移文件2）python manage.py migrate 更新到数据库 并学习和了解了在用户认证中的token, 聊天中的session等等一些概念、名词及意义。token: 用户登录到后端后，后端会为这个用户生成一个独一无二的字符串，来代表这个用户，登录成功拿到这个token后，前端再与后端做交互的话，可以用这个token代表他自己，不需要每个交互请求都认证一遍。session: […]