如何从零开始打造属于自己的智能家居语音助手OddAgent？
摘要：> 想不想拥有一个完全属于你自己的'小爱同学'或'小艺'？今天我来教你用开源项目 OddAgent，从零开始搭建一套智能家居意图识别系统。 ---
想不想拥有一个完全属于你自己的"小爱同学"或"小艺"？今天我来教你用开源项目 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 系统：
维度
自研 NLU
OddAgent
开发周期
3-6 个月
1 天配置
识别准确率
依赖训练数据
依赖 LLM 能力
扩展性
需改代码
改配置即可
维护成本
高
低
OddAgent 把"听懂人话"这件事，交给更擅长的大语言模型，让开发者专注在真正有价值的设备控制逻辑上。
三、安装与部署
3.1 环境准备
OddAgent 对环境的要求非常友好：
要求
说明
Python
3.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/completions
ernie-4.5-turbo-128k
阿里通义
https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
qwen3-30b-a3b
OpenAI
https://api.openai.com/v1/chat/completions
gpt-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": "开启"}
}
}
执行流程：
OddAgent 识别为"晨起模式"场景
业务层解析场景配置
并行执行：打开窗帘、播放音乐、启动咖啡机
返回完成状态给用户
6.2 案例二：离家检查
用户输入： "我要出门了，帮我检查一下"
识别结果：
{
"intent": {
"tool_name": "device_status_query",
"name": "设备状态查询",
"slots": {"device_type": "全部"}
}
}
执行流程：
OddAgent 识别为查询设备状态
业务层查询所有设备
发现客厅灯未关、空调未关
返回："检测到客厅灯和空调还开着，是否需要关闭？"
6.3 人机协作分工
阶段
AI（OddAgent）负责
人类/业务系统负责
语音转文字
可对接 ASR
-
意图识别
✅ 核心能力
-
参数提取
✅ 核心能力
-
设备控制
-
✅ 业务逻辑
状态反馈
✅ 生成自然语言
✅ 获取设备状态
异常处理
✅ 错误解释
✅ 设备故障处理
七、拿走即用
7.1 一行命令安装
pip install -i https://pypi.org/simple/ oddagent
7.2 快速配置清单
步骤
操作
关键配置项
1
安装 oddagent
pip 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 生产环境建议
LLM 选型：建议使用国内可访问的模型（如文心、通义），延迟更低
会话存储：当前版本话数据存储在内存中，生产环境建议使用 Redis
安全防护：API_KEY 等敏感信息使用环境变量，而非明文配置
日志记录：建议接入日志系统，便于排查问题
8.2 常见问题
Q: 意图识别不准怎么办？
A: 可以通过优化配置文件的 description 和 example 字段来提升准确率。如果仍不满意，考虑使用更强的模型。
Q: 如何支持更多设备？
A: 在 agent_tool_list 中添加新的工具定义即可，无需修改核心代码。
Q: 能实现多轮对话追问吗？
A: 可以，OddAgent 本身支持多轮对话，但追问逻辑需要在业务层实现。
Q: 语音输入怎么实现？
A: 需要额外部署 OddAsr 项目，然后修改配置中的 ODD_ASR_URL 地址。
九、写在最后
通过今天的教程，你应该已经掌握了：
✅ OddAgent 的核心设计理念
✅ 从零部署一个意图识别服务
✅ 配置智能家居场景的完整方案
✅ 与实际设备对接的思路
OddAgent 的价值在于：把"听懂人话"这件事做到极简，让开发者专注在真正有价值的业务逻辑上。
如果你有更好的想法，欢迎在评论区交流！
关注我的公众号：奥德元
一起学习AI，一起追赶时代！
新建了一个AI技术交流群，欢迎大家一起加入讨论。
扫码加入AI技术交流群（微信）
若需联系作者，请加微信：oddmeta