1. 从零搭建智能灯光控制系统手势识别与语音控制双通道联动智能灯光控制系统这个词听起来像是智能家居展台上的成品但拆开看它其实就是三件事一块能变色的灯带、一个能听懂人话的指令入口、一条把指令翻译成灯光变化的通道。我这次要做的是用 Codex 从零把这个系统搭出来并且同时支持手势识别和语音控制两条输入通道——你对着摄像头比个手势或者直接说一句“把灯调成暖白”灯带都能在几百毫秒内响应。适合谁来跟做如果你写过一点 Python知道 FastAPI 是干嘛的Vue 能看懂模板语法那这篇就是为你准备的。如果你完全没碰过硬件也没关系整个系统默认跑在模拟模式下没有 WS2812 灯带、没有树莓派照样能在浏览器里看到 60 颗 LED 的实时预览。等你确认逻辑跑通了再插上真实硬件改一个配置项就能切换。核心检索词先摆出来Codex 智能灯光控制系统、手势识别控制灯光、语音控制 LED 灯带、WS2812 灯带 Python 控制、FastAPI WebSocket 实时灯光。这几个词基本覆盖了从 AI 辅助编码到硬件驱动再到前后端联调的完整链路。我试过把整个项目拆成“先骨架、再效果、后交互”三段来让 Codex 生成这样比一次性丢一个大需求给它要稳得多。下面按这个节奏走每一步都给出可复制的提示词和关键代码骨架最后用实际请求验证灯光响应准确率。整个系统的数据流是这样的前端 Vue3 通过 WebSocket 连到后端 FastAPI后端持有 LED 灯带实例和效果引擎手势识别模块从摄像头读帧识别到手势后调用效果引擎语音控制模块从麦克风读音频解析出命令后同样调用效果引擎。两条通道最终都汇聚到同一个EffectEngine所以不会出现“手势和语音打架”的情况——谁后触发谁生效冷却时间防止误触。先确认环境。Python 3.10 以上Node 20 以上Codex CLI 能正常跑。如果你还没装 Codex去官网看安装说明这里不展开。环境检查命令python3 --version # 需要 3.10 node -v # 需要 v20 codex --version # 确认 Codex 可用模拟模式的意义在于你不需要先买硬件、焊灯带、调 GPIO就能把 90% 的逻辑验证完。等模拟模式下灯光效果、手势切换、语音命令都跑通了再切硬件模式这时候出问题基本只可能是接线或供电排查范围小很多。2. TaoToken 前置统一 Key 与 API 通道接入模型能力在开始写代码之前先把模型能力的接入通道理清楚。这个项目里 Codex 负责生成代码骨架但手势识别和语音命令的语义解析我建议走统一的 API 通道而不是每个模块各自去配一套 Key。TaoToken 在这里的角色就是统一入口一个 Key、一个 Base URL同时覆盖对话模型和编码模型。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数直接写https://taotoken.net/api就行。为什么要在灯光控制系统里接模型能力因为语音命令的解析如果只靠关键词匹配遇到“把灯光调得温柔一点”这种模糊表达就歇菜了。用模型做一层语义理解可以把自然语言映射到具体的effect、color、brightness参数上。手势识别那边也一样MediaPipe 给出的是关键点坐标但“这个手势到底想表达什么”可以用模型做二次确认降低误触率。接入方式分两种场景。如果你只是想让语音解析走模型用 API Key 模式就够了如果你打算长期用 Codex 做编码和调试那 Coding Plan 更划算。两种方式都从同一个控制台拿 Key。具体操作路径打开 https://taotoken.net/api-keys 创建 API Key然后在项目里通过环境变量注入。不要硬编码在代码里也不要提交到 Git。# .env 文件不要提交到版本库 TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4o-mini如果你用的是 Claude Code 做代码润色和重构配置方式略有不同。Claude Code 需要设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEYBase URL 指向 TaoToken 的 API 端点Key 用同一个。这样你在终端里跑claude命令时请求会走统一通道。对于 Codex 本身如果你想让 Codex CLI 也走 TaoToken 的通道需要配置~/.codex/auth.json和~/.codex/config.toml。auth.json 里放 Keyconfig.toml 里指定 Base URL 和 Model ID。三件套缺一不可Base URL、Key、Model ID。{ api_key: sk-你的实际Key, base_url: https://taotoken.net/api }# ~/.codex/config.toml model gpt-4o-mini provider taotoken [providers.taotoken] base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY配好之后在终端里跑codex进入交互模式输入一句“帮我生成一个 FastAPI 的 WebSocket 端点”如果正常返回代码说明通道通了。如果报 401先检查 Key 有没有多余空格如果报连接失败检查 Base URL 是不是写成了带路径的完整地址。这里要强调一点TaoToken 是模型能力的统一接入通道不是用来替代编辑器或 IDE 的。你还是在 VS Code 或终端里写代码只是模型请求走这个通道。别把它当成“一键生成整个项目”的魔法按钮它解决的是“多个模型、多个 Key 管理混乱”的问题。对于长期做编码和 Agent 开发的场景Coding Plan 比按量付费更省心。你可以在 https://taotoken.net/coding-plan 看到具体方案。如果只是偶尔用一下API Key 按量计费就够了。3. 可复制配置Codex 提示词模板与项目骨架生成这一节给出可以直接复制到 Codex 里的提示词模板以及生成后的项目结构。重点是让 Codex 先搭骨架不要一上来就让它写全部业务逻辑。第一个提示词用来生成项目目录结构和依赖配置请帮我创建一个智能灯光控制系统项目 smart-light-controller使用 Python FastAPI 作为后端Vue3 作为前端。 项目需要支持 WS2812 LED 灯带控制含模拟模式包含 WebSocket 实时通信 目录结构要清晰后端和前端分离。请生成完整的项目结构和依赖配置。 后端依赖fastapi, uvicorn, websockets, numpy, pillow, pydantic, python-dotenv 前端依赖vue3, pinia, socket.io-client, vueuse/coreCodex 执行后会生成类似这样的结构smart-light-controller/ ├── backend/ │ ├── app/ │ │ ├── main.py │ │ ├── controllers/ │ │ ├── services/ │ │ │ ├── led_service.py │ │ │ ├── effect_engine.py │ │ │ ├── gesture_service.py │ │ │ ├── voice_service.py │ │ │ └── music_analyzer.py │ │ ├── models/ │ │ └── utils/ │ │ └── color_utils.py │ ├── config/ │ │ └── settings.py │ ├── pyproject.toml │ └── .env ├── frontend/ │ ├── src/ │ │ ├── components/ │ │ │ ├── LedStrip.vue │ │ │ ├── EffectPanel.vue │ │ │ └── GesturePanel.vue │ │ ├── stores/ │ │ │ └── lightStore.ts │ │ └── App.vue │ └── package.json └── docker-compose.yml初始化命令mkdir -p smart-light-controller/{backend/{app/{controllers,services,models,utils},config},frontend/src/{components,stores}} cd smart-light-controller/backend uv init uv add fastapi uvicorn websockets numpy pillow pydantic python-dotenv cd ../frontend pnpm create vuelatest . --typescript --router --pinia pnpm install pnpm add socket.io-client vueuse/core接下来是 LED 驱动服务的提示词。这里的关键是要求 Codex 同时支持真实硬件和模拟模式并且用单例模式管理灯带实例请实现 LED 灯带驱动服务 led_service.py要求 1. 支持真实 WS2812B 灯带通过 rpi_ws281x 库和模拟模式 2. 模拟模式下在内存中维护一个颜色数组通过 WebSocket 推送到前端显示 3. 支持设置单个 LED 颜色、批量设置、亮度调节 4. 使用单例模式管理灯带实例 5. 所有注释用中文生成的led_service.py核心结构# backend/app/services/led_service.py LED 灯带驱动服务支持真实 WS2812B 硬件和模拟模式 import asyncio import json import logging from typing import List, Tuple, Optional from dataclasses import dataclass logger logging.getLogger(__name__) dataclass class LedConfig: LED 灯带配置 num_leds: int 60 pin: int 18 brightness: int 128 simulate: bool True freq_hz: int 800000 dma: int 10 invert: bool False class LedStrip: LED 灯带控制类支持真实硬件和内存模拟两种模式 _instance: Optional[LedStrip] None def __new__(cls, config: Optional[LedConfig] None): if cls._instance is None: cls._instance super().__new__(cls) return cls._instance def __init__(self, config: Optional[LedConfig] None): if hasattr(self, _initialized): return self._initialized True self.config config or LedConfig() self.num_leds self.config.num_leds self.brightness self.config.brightness self._pixels: List[Tuple[int, int, int]] [(0, 0, 0)] * self.num_leds self._ws_clients: List [] self._strip None if not self.config.simulate: self._init_hardware() else: logger.info(f模拟模式启动LED 数量: {self.num_leds}) def _init_hardware(self): 初始化真实 WS2812B 硬件 try: from rpi_ws281x import PixelStrip, Color self._strip PixelStrip( self.num_leds, self.config.pin, self.config.freq_hz, self.config.dma, self.config.invert, self.config.brightness ) self._strip.begin() logger.info(f硬件模式启动GPIO 引脚: {self.config.pin}) except ImportError: logger.warning(rpi_ws281x 库未安装自动切换到模拟模式) self.config.simulate True def set_pixel(self, index: int, r: int, g: int, b: int): 设置单个 LED 的颜色 if 0 index self.num_leds: self._pixels[index] (r, g, b) if self._strip: from rpi_ws281x import Color self._strip.setPixelColor(index, Color(r, g, b)) def set_all(self, r: int, g: int, b: int): 将所有 LED 设置为同一颜色 for i in range(self.num_leds): self._pixels[i] (r, g, b) if self._strip: from rpi_ws281x import Color for i in range(self.num_leds): self._strip.setPixelColor(i, Color(r, g, b)) def set_pixels_batch(self, colors: List[Tuple[int, int, int]]): 批量设置 LED 颜色 for i, (r, g, b) in enumerate(colors): if i self.num_leds: break self._pixels[i] (r, g, b) if self._strip: from rpi_ws281x import Color self._strip.setPixelColor(i, Color(r, g, b)) def set_brightness(self, brightness: int): 调整整体亮度 self.brightness max(0, min(255, brightness)) if self._strip: self._strip.setBrightness(self.brightness) async def show(self): 刷新显示写入硬件或推送到前端 if self._strip: self._strip.show() state self.get_state() await self._broadcast(state) def get_state(self) - dict: 获取当前灯带完整状态 return { type: led_update, pixels: self._pixels, brightness: self.brightness, num_leds: self.num_leds } def register_client(self, websocket): 注册 WebSocket 客户端 self._ws_clients.append(websocket) def unregister_client(self, websocket): 注销 WebSocket 客户端 if websocket in self._ws_clients: self._ws_clients.remove(websocket) async def _broadcast(self, data: dict): 向所有连接的客户端广播数据 message json.dumps(data) disconnected [] for client in self._ws_clients: try: await client.send_text(message) except Exception: disconnected.append(client) for client in disconnected: self.unregister_client(client) def clear(self): 关闭所有 LED self.set_all(0, 0, 0)这段代码的关键设计点单例模式保证全局只有一个灯带实例模拟模式让无硬件开发成为可能WebSocket 广播实现前端实时预览。set_pixels_batch是效果引擎每帧调用的核心方法批量写入比逐个set_pixel快很多。效果引擎的提示词请实现灯光效果引擎 effect_engine.py包含以下效果 1. 纯色模式solid 2. 呼吸灯breathing- 亮度渐明渐暗 3. 彩虹渐变rainbow- 色相循环 4. 流水灯chase- 颜色从一端流向另一端 5. 频闪strobe 6. 烛光candle- 模拟蜡烛火焰的随机闪烁 7. 极光aurora- 模拟北极光的柔和波动 8. 音乐模式music- 根据音频数据变化 每个效果要可以调节速度和颜色参数用异步生成器实现帧循环。效果引擎的核心是异步生成器模式。每个效果是一个async generator每帧yield一个颜色数组主循环负责把数组写入灯带并控制帧率。这种写法比while True里手动 sleep 更优雅也更容易取消。# backend/app/services/effect_engine.py 核心片段 class EffectEngine: def __init__(self, led_strip: LedStrip): self.strip led_strip self.num_leds led_strip.num_leds self.current_effect: Optional[EffectType] None self.params EffectParams() self._running False self._task: Optional[asyncio.Task] None self._frame_rate 60 async def start(self, effect: EffectType, params: Optional[EffectParams] None): await self.stop() self.current_effect effect if params: self.params params self._running True self._task asyncio.create_task(self._run_effect()) async def _run_effect(self): effect_map { EffectType.SOLID: self._effect_solid, EffectType.BREATHING: self._effect_breathing, EffectType.RAINBOW: self._effect_rainbow, EffectType.CHASE: self._effect_chase, EffectType.STROBE: self._effect_strobe, EffectType.CANDLE: self._effect_candle, EffectType.AURORA: self._effect_aurora, EffectType.MUSIC: self._effect_music, } generator effect_map.get(self.current_effect) if not generator: return frame_interval 1.0 / self._frame_rate try: async for colors in generator(): if not self._running: break self.strip.set_pixels_batch(colors) await self.strip.show() await asyncio.sleep(frame_interval / self.params.speed) except asyncio.CancelledError: pass呼吸灯效果用正弦函数生成平滑的亮度变化async def _effect_breathing(self): 呼吸灯效果亮度按正弦曲线渐明渐暗 t 0.0 while True: factor (math.sin(t) 1) / 2 r, g, b self.params.color colors [(int(r * factor), int(g * factor), int(b * factor))] * self.num_leds t 0.05 * self.params.speed yield colors彩虹效果用 HSV 色相循环每个 LED 的色相偏移不同async def _effect_rainbow(self): 彩虹渐变色相循环均匀分布在灯带上并循环滚动 offset 0.0 while True: colors [] for i in range(self.num_leds): hue (i / self.num_leds offset) % 1.0 r, g, b hsv_to_rgb(hue, 1.0, 1.0) colors.append((r, g, b)) offset 0.005 * self.params.speed yield colors颜色工具函数color_utils.py提供 HSV 到 RGB 的转换、颜色混合、gamma 校正。WS2812 灯珠的亮度响应是非线性的gamma 校正能让亮度变化在人眼看来更线性# backend/app/utils/color_utils.py GAMMA_TABLE [int(pow(i / 255.0, 2.8) * 255 0.5) for i in range(256)] def gamma_correct(r: int, g: int, b: int) - Tuple[int, int, int]: Gamma 校正让亮度变化在人眼看来更线性 return (GAMMA_TABLE[r], GAMMA_TABLE[g], GAMMA_TABLE[b])到这里后端骨架和核心效果引擎就搭好了。下一步是把手势识别和语音控制接进来。4. 验证请求手势识别与语音控制双通道联调这一节把两条输入通道接上并用实际请求验证灯光响应。先看手势识别。手势识别用 MediaPipe Hands从摄像头读帧识别关键点然后映射到灯光命令。提示词请实现手势识别模块使用 MediaPipe 识别以下手势来控制灯光 - 竖起大拇指 → 增加亮度 - 拇指朝下 → 降低亮度 - 张开手掌 → 切换到下一个效果 - 握拳 → 关闭灯光 - 比数字(1-5) → 切换到对应的效果模式 需要包含冷却时间防止误触所有注释用中文。核心逻辑是数伸出的手指数量然后根据手指组合判断手势类型# backend/app/services/gesture_service.py 核心片段 class Gesture(str, Enum): THUMB_UP thumb_up THUMB_DOWN thumb_down OPEN_PALM open_palm FIST fist ONE one TWO two THREE three FOUR four FIVE five UNKNOWN unknown class GestureRecognizer: def __init__(self): self._running False self._callback: Optional[Callable] None self._last_gesture: Optional[Gesture] None self._gesture_cooldown 1.0 def _count_extended_fingers(self, hand_landmarks) - int: 计算伸出的手指数量 tips [8, 12, 16, 20] pips [6, 10, 14, 18] count 0 thumb_tip hand_landmarks.landmark[4] thumb_ip hand_landmarks.landmark[3] if abs(thumb_tip.x - thumb_ip.x) 0.05: count 1 for tip_idx, pip_idx in zip(tips, pips): if hand_landmarks.landmark[tip_idx].y hand_landmarks.landmark[pip_idx].y: count 1 return count def _classify_gesture(self, hand_landmarks) - Gesture: 根据手部关键点判断手势类型 extended self._count_extended_fingers(hand_landmarks) thumb_tip_y hand_landmarks.landmark[4].y thumb_mcp_y hand_landmarks.landmark[2].y thumb_up thumb_tip_y thumb_mcp_y - 0.1 thumb_down thumb_tip_y thumb_mcp_y 0.1 index_extended hand_landmarks.landmark[8].y hand_landmarks.landmark[6].y if extended 0: return Gesture.FIST elif extended 1 and thumb_up and not index_extended: return Gesture.THUMB_UP elif extended 1 and thumb_down and not index_extended: return Gesture.THUMB_DOWN elif extended 1 and index_extended: return Gesture.ONE elif extended 2: return Gesture.TWO elif extended 3: return Gesture.THREE elif extended 4: return Gesture.FOUR elif extended 5: return Gesture.OPEN_PALM return Gesture.UNKNOWN手势识别的主循环从摄像头读帧调用 MediaPipe 处理然后根据冷却时间决定是否触发回调async def start(self, callback: Callable): 启动手势识别 self._callback callback self._running True try: import cv2 import mediapipe as mp mp_hands mp.solutions.hands hands mp_hands.Hands( static_image_modeFalse, max_num_hands1, min_detection_confidence0.7, min_tracking_confidence0.5 ) cap cv2.VideoCapture(0) import time last_trigger_time 0 while self._running and cap.isOpened(): ret, frame cap.read() if not ret: continue frame cv2.flip(frame, 1) rgb_frame cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results hands.process(rgb_frame) if results.multi_hand_landmarks: for hand_landmarks in results.multi_hand_landmarks: gesture self._classify_gesture(hand_landmarks) current_time time.time() if (gesture ! Gesture.UNKNOWN and gesture ! self._last_gesture and current_time - last_trigger_time self._gesture_cooldown): self._last_gesture gesture last_trigger_time current_time if self._callback: await self._callback(gesture) await asyncio.sleep(0.033) cap.release() hands.close() except ImportError as e: logger.warning(f手势识别依赖未安装: {e})语音控制用 SpeechRecognition 库把识别到的文本解析成命令。提示词请实现语音控制模块支持以下语音命令 - 打开灯光 / 开灯 → 打开灯光 - 关闭灯光 / 关灯 → 关闭灯光 - 亮一点 / 暗一点 → 调节亮度 - 彩虹模式 / 呼吸灯 等 → 切换效果 - 红色 / 蓝色 等 → 切换颜色 使用 SpeechRecognition 库支持离线识别。命令解析用关键词匹配加正则表达式# backend/app/services/voice_service.py 核心片段 COLOR_MAP { 红色: (255, 0, 0), 绿色: (0, 255, 0), 蓝色: (0, 0, 255), 黄色: (255, 255, 0), 紫色: (128, 0, 255), 橙色: (255, 165, 0), 粉色: (255, 105, 180), 白色: (255, 255, 255), 暖白: (255, 240, 220), 冷白: (200, 220, 255), } EFFECT_MAP { 纯色: solid, 呼吸灯: breathing, 呼吸: breathing, 彩虹: rainbow, 彩虹模式: rainbow, 流水灯: chase, 流水: chase, 频闪: strobe, 闪烁: strobe, 烛光: candle, 蜡烛: candle, 极光: aurora, 北极光: aurora, 音乐: music, 音乐模式: music, } class VoiceController: def parse_command(self, text: str) - Optional[VoiceCommand]: 解析语音识别结果为具体命令 text text.strip().lower() if any(kw in text for kw in [开灯, 打开灯光, 打开灯, 亮灯]): return VoiceCommand(power_on) if any(kw in text for kw in [关灯, 关闭灯光, 关闭灯, 熄灯]): return VoiceCommand(power_off) if any(kw in text for kw in [亮一点, 更亮, 加亮, 调亮]): return VoiceCommand(brightness_up, step30) if any(kw in text for kw in [暗一点, 更暗, 调暗, 暗一些]): return VoiceCommand(brightness_down, step30) match re.search(r亮度\s*(\d), text) if match: percent int(match.group(1)) return VoiceCommand(set_brightness, brightnessint(percent / 100 * 255)) for color_name, rgb in COLOR_MAP.items(): if color_name in text: return VoiceCommand(set_color, colorrgb) for effect_name, effect_type in EFFECT_MAP.items(): if effect_name in text: return VoiceCommand(set_effect, effecteffect_type) return None语音识别的主循环async def start(self, callback: Callable): 启动语音识别监听 self._callback callback self._running True try: import speech_recognition as sr recognizer sr.Recognizer() recognizer.energy_threshold 300 recognizer.dynamic_energy_threshold True with sr.Microphone() as source: recognizer.adjust_for_ambient_noise(source, duration2) while self._running: try: audio recognizer.listen(source, timeout5, phrase_time_limit5) text recognizer.recognize_google(audio, languagezh-CN) command self.parse_command(text) if command and self._callback: await self._callback(command) except sr.WaitTimeoutError: pass except sr.UnknownValueError: pass except sr.RequestError as e: logger.error(f语音识别服务错误: {e}) await asyncio.sleep(1) except ImportError: logger.warning(speech_recognition 未安装)现在把两条通道接到 FastAPI 主入口。WebSocket 端点负责向前端推送灯光状态REST API 负责接收控制命令# backend/app/main.py 核心片段 asynccontextmanager async def lifespan(app: FastAPI): global led_strip, effect_engine, scene_scheduler config LedConfig(num_leds60, simulateTrue) led_strip LedStrip(config) effect_engine EffectEngine(led_strip) scene_scheduler SceneScheduler(effect_engine) logger.info(智能灯光控制系统启动完成) yield await effect_engine.stop() led_strip.clear() app FastAPI(title智能灯光控制系统, lifespanlifespan) app.add_middleware(CORSMiddleware, allow_origins[*], allow_credentialsTrue, allow_methods[*], allow_headers[*]) app.post(/api/effect) async def set_effect(req: EffectRequest): 切换灯光效果 try: effect_type EffectType(req.effect) except ValueError: raise HTTPException(status_code400, detailf未知效果类型: {req.effect}) params EffectParams( colortuple(req.color) if req.color else (255, 100, 0), speedreq.speed or 1.0, intensityreq.intensity or 1.0, ) await effect_engine.start(effect_type, params) return {message: f效果已切换为: {effect_type.value}, status: ok} app.websocket(/ws) async def websocket_endpoint(websocket: WebSocket): WebSocket 连接端点 await websocket.accept() led_strip.register_client(websocket) try: await websocket.send_json(led_strip.get_state()) while True: data await websocket.receive_json() await _handle_ws_command(data) except WebSocketDisconnect: led_strip.unregister_client(websocket)启动后端cd backend uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload启动前端cd frontend pnpm dev打开浏览器访问http://localhost:5173你应该能看到 LED 灯带预览和效果控制面板。点击“彩虹”按钮灯带预览应该开始滚动彩虹色。打开终端用 curl 验证 REST APIcurl -X POST http://localhost:8000/api/effect \ -H Content-Type: application/json \ -d {effect: breathing, color: [255, 100, 0], speed: 1.5}预期返回{message: 效果已切换为: breathing, status: ok}同时浏览器里的灯带预览应该开始呼吸闪烁。再验证 WebSocket 推送在浏览器控制台里看 Network 面板的 WS 连接应该能看到每帧推送的led_update消息。手势识别和语音控制的验证需要摄像头和麦克风。如果你在无头服务器上跑可以先用模拟数据测试命令解析逻辑# 测试语音命令解析 from app.services.voice_service import VoiceController vc VoiceController() print(vc.parse_command(把灯光调成彩虹模式)) # 预期输出: VoiceCommand(actionset_effect, params{effect: rainbow}) print(vc.parse_command(亮度50)) # 预期输出: VoiceCommand(actionset_brightness, params{brightness: 127})灯光响应准确率的验证方法准备 20 条语音命令和 10 个手势分别测试记录正确响应的次数。语音命令在安静环境下准确率应该在 90% 以上手势识别在光线充足时准确率在 85% 以上。如果低于这个值先检查麦克风增益和摄像头曝光再考虑调整识别阈值。5. 本篇常见错排查401、local proxy failed 与 OAuth 报错这一节列出实际联调中最容易遇到的报错和排查路径。每个报错都给出真实错误信息和解决步骤。报错一401 Unauthorized{error: {message: Invalid API key, type: invalid_request_error}}这个报错说明 Key 不对或没传。排查顺序先确认.env文件里的TAOTOKEN_API_KEY有没有多余空格或换行再确认代码里读取环境变量的方式正确最后确认 Key 没有过期或被撤销。如果你用的是 Codex CLI检查~/.codex/auth.json里的api_key字段。# 快速验证 Key 是否有效 curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model: gpt-4o-mini, messages: [{role: user, content: test}]}如果返回 200 和正常响应说明 Key 没问题问题在代码里的读取逻辑。如果返回 401说明 Key 本身有问题去控制台重新生成一个。报错二local proxy failed / connection refusedError: local proxy failed: dial tcp 127.0.0.1:7890: connect: connection refused这个报错通常出现在你本地配了代理但代理服务没启动。排查检查系统环境变量HTTP_PROXY和HTTPS_PROXY是否指向了一个没运行的端口。如果你不需要代理直接 unset 这两个变量unset HTTP_PROXY unset HTTPS_PROXY然后重新跑请求。如果你确实需要代理才能访问外网确保代理服务在运行并且端口号正确。注意TaoToken 的 API 端点在国内可以直接访问不需要额外代理。报错三reading choices 相关错误KeyError: choices或者TypeError: NoneType object is not subscriptable这个报错说明 API 返回的 JSON 结构和你预期的不一样。常见原因是请求体格式不对或者模型名称写错了。检查你的请求体# 正确的请求体格式 payload { model: gpt-4o-mini, # 确认模型名称正确 messages: [{role: user, content: 你的提示词}], temperature: 0.7 }如果模型名称写成了gpt-4但你的账号没有这个模型的权限API 会返回错误信息而不是choices。先打印完整响应体看看response requests.post(url, headersheaders, jsonpayload) print(response.status_code) print(response.text) # 打印完整响应不要直接 response.json()[choices]报错四OAuth 相关错误Error: OAuth token expired or invalid如果你用的是 Claude Code 或 Codex 的 OAuth 登录模式token 过期后会报这个错。解决方法是重新登录# Claude Code 重新登录 claude login # Codex 重新登录 codex login如果你用的是 API Key 模式而不是 OAuth不会遇到这个报错。建议在自动化脚本里统一用 API Key避免 token 过期导致任务中断。报错五WebSocket 连接失败WebSocket connection to ws://localhost:8000/ws failed: Error during WebSocket handshake排查确认后端服务在运行端口没被占用确认前端配置的 WS URL 和后端一致确认 CORS 中间件允许了 WebSocket 升级请求。FastAPI 的 CORS 中间件默认不处理 WebSocket需要在 WebSocket 端点里手动处理。报错六MediaPipe 导入失败ImportError: cannot import name solutions from mediapipe这个通常是版本不兼容。MediaPipe 的 API 在不同版本间有变化确认你安装的是 0.10 以上版本pip install mediapipe0.10.9如果还是报错检查 Python 版本。MediaPipe 对 Python 3.12 的支持还不完善建议用 3.10 或 3.11。报错七语音识别无响应如果语音识别一直没反应先确认麦克风权限。在 macOS 上终端需要麦克风权限才能录音。去系统设置 → 隐私与安全性 → 麦克风勾选你的终端应用。在 Linux 上用arecord -l确认麦克风设备被识别。如果识别到了文字但命令没触发打印解析结果看看text recognizer.recognize_google(audio, languagezh-CN) print(f识别结果: {text}) command self.parse_command(text) print(f解析命令: {command})常见问题是识别结果里有标点符号或空格导致关键词匹配失败。在parse_command里先做一次清洗text text.strip().lower().replace(, ).replace(。, ).replace( , )报错八灯光效果卡顿如果灯带预览明显卡顿先检查帧率。在效果引擎里加一行日志frame_interval 1.0 / self._frame_rate # 在循环里打印实际帧间隔如果实际帧间隔远大于frame_interval说明set_pixels_batch或show太慢。优化方向减少 WebSocket 推送频率用MessageThrottle限制到 30fps或者把set_pixels_batch里的逐个赋值改成 numpy 批量操作。class MessageThrottle: 消息节流器限制 WebSocket 推送频率 def __init__(self, min_interval_ms: int 33): self.min_interval min_interval_ms / 1000 self._last_send 0 def should_send(self, current_time: float) - bool: if current_time - self._last_send self.min_interval: self._last_send current_time return True return False排查完这些系统应该能稳定运行了。如果还有问题去接入文档里查对应错误码的说明。6. 语义一致 CTA把模型能力接进你的灯光项目到这里智能灯光控制系统的核心链路已经跑通了Codex 生成骨架FastAPI 提供 API 和 WebSocketVue3 做实时预览手势识别和语音控制双通道联动。接下来你可以把模型能力接进来让语音命令支持更自然的表达或者让手势识别有更低的误触率。接入路径很直接去 https://taotoken.net/api-keys 创建一个 Key然后在项目里通过环境变量注入。如果你打算长期用 Codex 做编码和调试Coding Plan 比按量付费更省心具体方案在 https://taotoken.net/coding-plan 。如果你只是想先验证模型对话能力可以直接在 https://taotoken.net/chat 里试几句确认通道通了再写代码。接入文档在 https://taotoken.net/doc 里面有完整的 API 参考和错误码说明。遇到 401 或连接问题先查文档里的排障章节大部分常见问题都有覆盖。最后给一个实用技巧在settings.py里把模型配置做成可切换的这样你可以在不同模型之间快速对比效果而不用改代码。# backend/config/settings.py import os from pydantic_settings import BaseSettings class Settings(BaseSettings): taotoken_api_key: str os.getenv(TAOTOKEN_API_KEY, ) taotoken_base_url: str os.getenv(TAOTOKEN_BASE_URL, https://taotoken.net/api) taotoken_model: str os.getenv(TAOTOKEN_MODEL, gpt-4o-mini) led_num: int 60 led_simulate: bool True log_level: str info settings Settings()把语音命令解析从关键词匹配升级到模型语义理解只需要在parse_command里加一个 fallback关键词没匹配到时调用模型 API 做意图识别。这样“把灯光调得温柔一点”也能映射到breathing效果加暖色调。整个项目从零到跑通核心代码不超过 800 行但覆盖了 AI 辅助编码、硬件驱动、实时通信、手势识别、语音控制五个技术面。你可以在这个骨架上继续加场景调度、音乐联动、多设备同步扩展空间很大。 Codex 100个真实案例 - 用AI做智能灯光控制系统（手势识别+语音控制）
1. 从零搭建智能灯光控制系统手势识别与语音控制双通道联动智能灯光控制系统这个词听起来像是智能家居展台上的成品但拆开看它其实就是三件事一块能变色的灯带、一个能听懂人话的指令入口、一条把指令翻译成灯光变化的通道。我这次要做的是用 Codex 从零把这个系统搭出来并且同时支持手势识别和语音控制两条输入通道——你对着摄像头比个手势或者直接说一句“把灯调成暖白”灯带都能在几百毫秒内响应。适合谁来跟做如果你写过一点 Python知道 FastAPI 是干嘛的Vue 能看懂模板语法那这篇就是为你准备的。如果你完全没碰过硬件也没关系整个系统默认跑在模拟模式下没有 WS2812 灯带、没有树莓派照样能在浏览器里看到 60 颗 LED 的实时预览。等你确认逻辑跑通了再插上真实硬件改一个配置项就能切换。核心检索词先摆出来Codex 智能灯光控制系统、手势识别控制灯光、语音控制 LED 灯带、WS2812 灯带 Python 控制、FastAPI WebSocket 实时灯光。这几个词基本覆盖了从 AI 辅助编码到硬件驱动再到前后端联调的完整链路。我试过把整个项目拆成“先骨架、再效果、后交互”三段来让 Codex 生成这样比一次性丢一个大需求给它要稳得多。下面按这个节奏走每一步都给出可复制的提示词和关键代码骨架最后用实际请求验证灯光响应准确率。整个系统的数据流是这样的前端 Vue3 通过 WebSocket 连到后端 FastAPI后端持有 LED 灯带实例和效果引擎手势识别模块从摄像头读帧识别到手势后调用效果引擎语音控制模块从麦克风读音频解析出命令后同样调用效果引擎。两条通道最终都汇聚到同一个EffectEngine所以不会出现“手势和语音打架”的情况——谁后触发谁生效冷却时间防止误触。先确认环境。Python 3.10 以上Node 20 以上Codex CLI 能正常跑。如果你还没装 Codex去官网看安装说明这里不展开。环境检查命令python3 --version # 需要 3.10 node -v # 需要 v20 codex --version # 确认 Codex 可用模拟模式的意义在于你不需要先买硬件、焊灯带、调 GPIO就能把 90% 的逻辑验证完。等模拟模式下灯光效果、手势切换、语音命令都跑通了再切硬件模式这时候出问题基本只可能是接线或供电排查范围小很多。2. TaoToken 前置统一 Key 与 API 通道接入模型能力在开始写代码之前先把模型能力的接入通道理清楚。这个项目里 Codex 负责生成代码骨架但手势识别和语音命令的语义解析我建议走统一的 API 通道而不是每个模块各自去配一套 Key。TaoToken 在这里的角色就是统一入口一个 Key、一个 Base URL同时覆盖对话模型和编码模型。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数直接写https://taotoken.net/api就行。为什么要在灯光控制系统里接模型能力因为语音命令的解析如果只靠关键词匹配遇到“把灯光调得温柔一点”这种模糊表达就歇菜了。用模型做一层语义理解可以把自然语言映射到具体的effect、color、brightness参数上。手势识别那边也一样MediaPipe 给出的是关键点坐标但“这个手势到底想表达什么”可以用模型做二次确认降低误触率。接入方式分两种场景。如果你只是想让语音解析走模型用 API Key 模式就够了如果你打算长期用 Codex 做编码和调试那 Coding Plan 更划算。两种方式都从同一个控制台拿 Key。具体操作路径打开 https://taotoken.net/api-keys 创建 API Key然后在项目里通过环境变量注入。不要硬编码在代码里也不要提交到 Git。# .env 文件不要提交到版本库 TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4o-mini如果你用的是 Claude Code 做代码润色和重构配置方式略有不同。Claude Code 需要设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEYBase URL 指向 TaoToken 的 API 端点Key 用同一个。这样你在终端里跑claude命令时请求会走统一通道。对于 Codex 本身如果你想让 Codex CLI 也走 TaoToken 的通道需要配置~/.codex/auth.json和~/.codex/config.toml。auth.json 里放 Keyconfig.toml 里指定 Base URL 和 Model ID。三件套缺一不可Base URL、Key、Model ID。{ api_key: sk-你的实际Key, base_url: https://taotoken.net/api }# ~/.codex/config.toml model gpt-4o-mini provider taotoken [providers.taotoken] base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY配好之后在终端里跑codex进入交互模式输入一句“帮我生成一个 FastAPI 的 WebSocket 端点”如果正常返回代码说明通道通了。如果报 401先检查 Key 有没有多余空格如果报连接失败检查 Base URL 是不是写成了带路径的完整地址。这里要强调一点TaoToken 是模型能力的统一接入通道不是用来替代编辑器或 IDE 的。你还是在 VS Code 或终端里写代码只是模型请求走这个通道。别把它当成“一键生成整个项目”的魔法按钮它解决的是“多个模型、多个 Key 管理混乱”的问题。对于长期做编码和 Agent 开发的场景Coding Plan 比按量付费更省心。你可以在 https://taotoken.net/coding-plan 看到具体方案。如果只是偶尔用一下API Key 按量计费就够了。3. 可复制配置Codex 提示词模板与项目骨架生成这一节给出可以直接复制到 Codex 里的提示词模板以及生成后的项目结构。重点是让 Codex 先搭骨架不要一上来就让它写全部业务逻辑。第一个提示词用来生成项目目录结构和依赖配置请帮我创建一个智能灯光控制系统项目 smart-light-controller使用 Python FastAPI 作为后端Vue3 作为前端。 项目需要支持 WS2812 LED 灯带控制含模拟模式包含 WebSocket 实时通信 目录结构要清晰后端和前端分离。请生成完整的项目结构和依赖配置。 后端依赖fastapi, uvicorn, websockets, numpy, pillow, pydantic, python-dotenv 前端依赖vue3, pinia, socket.io-client, vueuse/coreCodex 执行后会生成类似这样的结构smart-light-controller/ ├── backend/ │ ├── app/ │ │ ├── main.py │ │ ├── controllers/ │ │ ├── services/ │ │ │ ├── led_service.py │ │ │ ├── effect_engine.py │ │ │ ├── gesture_service.py │ │ │ ├── voice_service.py │ │ │ └── music_analyzer.py │ │ ├── models/ │ │ └── utils/ │ │ └── color_utils.py │ ├── config/ │ │ └── settings.py │ ├── pyproject.toml │ └── .env ├── frontend/ │ ├── src/ │ │ ├── components/ │ │ │ ├── LedStrip.vue │ │ │ ├── EffectPanel.vue │ │ │ └── GesturePanel.vue │ │ ├── stores/ │ │ │ └── lightStore.ts │ │ └── App.vue │ └── package.json └── docker-compose.yml初始化命令mkdir -p smart-light-controller/{backend/{app/{controllers,services,models,utils},config},frontend/src/{components,stores}} cd smart-light-controller/backend uv init uv add fastapi uvicorn websockets numpy pillow pydantic python-dotenv cd ../frontend pnpm create vuelatest . --typescript --router --pinia pnpm install pnpm add socket.io-client vueuse/core接下来是 LED 驱动服务的提示词。这里的关键是要求 Codex 同时支持真实硬件和模拟模式并且用单例模式管理灯带实例请实现 LED 灯带驱动服务 led_service.py要求 1. 支持真实 WS2812B 灯带通过 rpi_ws281x 库和模拟模式 2. 模拟模式下在内存中维护一个颜色数组通过 WebSocket 推送到前端显示 3. 支持设置单个 LED 颜色、批量设置、亮度调节 4. 使用单例模式管理灯带实例 5. 所有注释用中文生成的led_service.py核心结构# backend/app/services/led_service.py LED 灯带驱动服务支持真实 WS2812B 硬件和模拟模式 import asyncio import json import logging from typing import List, Tuple, Optional from dataclasses import dataclass logger logging.getLogger(__name__) dataclass class LedConfig: LED 灯带配置 num_leds: int 60 pin: int 18 brightness: int 128 simulate: bool True freq_hz: int 800000 dma: int 10 invert: bool False class LedStrip: LED 灯带控制类支持真实硬件和内存模拟两种模式 _instance: Optional[LedStrip] None def __new__(cls, config: Optional[LedConfig] None): if cls._instance is None: cls._instance super().__new__(cls) return cls._instance def __init__(self, config: Optional[LedConfig] None): if hasattr(self, _initialized): return self._initialized True self.config config or LedConfig() self.num_leds self.config.num_leds self.brightness self.config.brightness self._pixels: List[Tuple[int, int, int]] [(0, 0, 0)] * self.num_leds self._ws_clients: List [] self._strip None if not self.config.simulate: self._init_hardware() else: logger.info(f模拟模式启动LED 数量: {self.num_leds}) def _init_hardware(self): 初始化真实 WS2812B 硬件 try: from rpi_ws281x import PixelStrip, Color self._strip PixelStrip( self.num_leds, self.config.pin, self.config.freq_hz, self.config.dma, self.config.invert, self.config.brightness ) self._strip.begin() logger.info(f硬件模式启动GPIO 引脚: {self.config.pin}) except ImportError: logger.warning(rpi_ws281x 库未安装自动切换到模拟模式) self.config.simulate True def set_pixel(self, index: int, r: int, g: int, b: int): 设置单个 LED 的颜色 if 0 index self.num_leds: self._pixels[index] (r, g, b) if self._strip: from rpi_ws281x import Color self._strip.setPixelColor(index, Color(r, g, b)) def set_all(self, r: int, g: int, b: int): 将所有 LED 设置为同一颜色 for i in range(self.num_leds): self._pixels[i] (r, g, b) if self._strip: from rpi_ws281x import Color for i in range(self.num_leds): self._strip.setPixelColor(i, Color(r, g, b)) def set_pixels_batch(self, colors: List[Tuple[int, int, int]]): 批量设置 LED 颜色 for i, (r, g, b) in enumerate(colors): if i self.num_leds: break self._pixels[i] (r, g, b) if self._strip: from rpi_ws281x import Color self._strip.setPixelColor(i, Color(r, g, b)) def set_brightness(self, brightness: int): 调整整体亮度 self.brightness max(0, min(255, brightness)) if self._strip: self._strip.setBrightness(self.brightness) async def show(self): 刷新显示写入硬件或推送到前端 if self._strip: self._strip.show() state self.get_state() await self._broadcast(state) def get_state(self) - dict: 获取当前灯带完整状态 return { type: led_update, pixels: self._pixels, brightness: self.brightness, num_leds: self.num_leds } def register_client(self, websocket): 注册 WebSocket 客户端 self._ws_clients.append(websocket) def unregister_client(self, websocket): 注销 WebSocket 客户端 if websocket in self._ws_clients: self._ws_clients.remove(websocket) async def _broadcast(self, data: dict): 向所有连接的客户端广播数据 message json.dumps(data) disconnected [] for client in self._ws_clients: try: await client.send_text(message) except Exception: disconnected.append(client) for client in disconnected: self.unregister_client(client) def clear(self): 关闭所有 LED self.set_all(0, 0, 0)这段代码的关键设计点单例模式保证全局只有一个灯带实例模拟模式让无硬件开发成为可能WebSocket 广播实现前端实时预览。set_pixels_batch是效果引擎每帧调用的核心方法批量写入比逐个set_pixel快很多。效果引擎的提示词请实现灯光效果引擎 effect_engine.py包含以下效果 1. 纯色模式solid 2. 呼吸灯breathing- 亮度渐明渐暗 3. 彩虹渐变rainbow- 色相循环 4. 流水灯chase- 颜色从一端流向另一端 5. 频闪strobe 6. 烛光candle- 模拟蜡烛火焰的随机闪烁 7. 极光aurora- 模拟北极光的柔和波动 8. 音乐模式music- 根据音频数据变化 每个效果要可以调节速度和颜色参数用异步生成器实现帧循环。效果引擎的核心是异步生成器模式。每个效果是一个async generator每帧yield一个颜色数组主循环负责把数组写入灯带并控制帧率。这种写法比while True里手动 sleep 更优雅也更容易取消。# backend/app/services/effect_engine.py 核心片段 class EffectEngine: def __init__(self, led_strip: LedStrip): self.strip led_strip self.num_leds led_strip.num_leds self.current_effect: Optional[EffectType] None self.params EffectParams() self._running False self._task: Optional[asyncio.Task] None self._frame_rate 60 async def start(self, effect: EffectType, params: Optional[EffectParams] None): await self.stop() self.current_effect effect if params: self.params params self._running True self._task asyncio.create_task(self._run_effect()) async def _run_effect(self): effect_map { EffectType.SOLID: self._effect_solid, EffectType.BREATHING: self._effect_breathing, EffectType.RAINBOW: self._effect_rainbow, EffectType.CHASE: self._effect_chase, EffectType.STROBE: self._effect_strobe, EffectType.CANDLE: self._effect_candle, EffectType.AURORA: self._effect_aurora, EffectType.MUSIC: self._effect_music, } generator effect_map.get(self.current_effect) if not generator: return frame_interval 1.0 / self._frame_rate try: async for colors in generator(): if not self._running: break self.strip.set_pixels_batch(colors) await self.strip.show() await asyncio.sleep(frame_interval / self.params.speed) except asyncio.CancelledError: pass呼吸灯效果用正弦函数生成平滑的亮度变化async def _effect_breathing(self): 呼吸灯效果亮度按正弦曲线渐明渐暗 t 0.0 while True: factor (math.sin(t) 1) / 2 r, g, b self.params.color colors [(int(r * factor), int(g * factor), int(b * factor))] * self.num_leds t 0.05 * self.params.speed yield colors彩虹效果用 HSV 色相循环每个 LED 的色相偏移不同async def _effect_rainbow(self): 彩虹渐变色相循环均匀分布在灯带上并循环滚动 offset 0.0 while True: colors [] for i in range(self.num_leds): hue (i / self.num_leds offset) % 1.0 r, g, b hsv_to_rgb(hue, 1.0, 1.0) colors.append((r, g, b)) offset 0.005 * self.params.speed yield colors颜色工具函数color_utils.py提供 HSV 到 RGB 的转换、颜色混合、gamma 校正。WS2812 灯珠的亮度响应是非线性的gamma 校正能让亮度变化在人眼看来更线性# backend/app/utils/color_utils.py GAMMA_TABLE [int(pow(i / 255.0, 2.8) * 255 0.5) for i in range(256)] def gamma_correct(r: int, g: int, b: int) - Tuple[int, int, int]: Gamma 校正让亮度变化在人眼看来更线性 return (GAMMA_TABLE[r], GAMMA_TABLE[g], GAMMA_TABLE[b])到这里后端骨架和核心效果引擎就搭好了。下一步是把手势识别和语音控制接进来。4. 验证请求手势识别与语音控制双通道联调这一节把两条输入通道接上并用实际请求验证灯光响应。先看手势识别。手势识别用 MediaPipe Hands从摄像头读帧识别关键点然后映射到灯光命令。提示词请实现手势识别模块使用 MediaPipe 识别以下手势来控制灯光 - 竖起大拇指 → 增加亮度 - 拇指朝下 → 降低亮度 - 张开手掌 → 切换到下一个效果 - 握拳 → 关闭灯光 - 比数字(1-5) → 切换到对应的效果模式 需要包含冷却时间防止误触所有注释用中文。核心逻辑是数伸出的手指数量然后根据手指组合判断手势类型# backend/app/services/gesture_service.py 核心片段 class Gesture(str, Enum): THUMB_UP thumb_up THUMB_DOWN thumb_down OPEN_PALM open_palm FIST fist ONE one TWO two THREE three FOUR four FIVE five UNKNOWN unknown class GestureRecognizer: def __init__(self): self._running False self._callback: Optional[Callable] None self._last_gesture: Optional[Gesture] None self._gesture_cooldown 1.0 def _count_extended_fingers(self, hand_landmarks) - int: 计算伸出的手指数量 tips [8, 12, 16, 20] pips [6, 10, 14, 18] count 0 thumb_tip hand_landmarks.landmark[4] thumb_ip hand_landmarks.landmark[3] if abs(thumb_tip.x - thumb_ip.x) 0.05: count 1 for tip_idx, pip_idx in zip(tips, pips): if hand_landmarks.landmark[tip_idx].y hand_landmarks.landmark[pip_idx].y: count 1 return count def _classify_gesture(self, hand_landmarks) - Gesture: 根据手部关键点判断手势类型 extended self._count_extended_fingers(hand_landmarks) thumb_tip_y hand_landmarks.landmark[4].y thumb_mcp_y hand_landmarks.landmark[2].y thumb_up thumb_tip_y thumb_mcp_y - 0.1 thumb_down thumb_tip_y thumb_mcp_y 0.1 index_extended hand_landmarks.landmark[8].y hand_landmarks.landmark[6].y if extended 0: return Gesture.FIST elif extended 1 and thumb_up and not index_extended: return Gesture.THUMB_UP elif extended 1 and thumb_down and not index_extended: return Gesture.THUMB_DOWN elif extended 1 and index_extended: return Gesture.ONE elif extended 2: return Gesture.TWO elif extended 3: return Gesture.THREE elif extended 4: return Gesture.FOUR elif extended 5: return Gesture.OPEN_PALM return Gesture.UNKNOWN手势识别的主循环从摄像头读帧调用 MediaPipe 处理然后根据冷却时间决定是否触发回调async def start(self, callback: Callable): 启动手势识别 self._callback callback self._running True try: import cv2 import mediapipe as mp mp_hands mp.solutions.hands hands mp_hands.Hands( static_image_modeFalse, max_num_hands1, min_detection_confidence0.7, min_tracking_confidence0.5 ) cap cv2.VideoCapture(0) import time last_trigger_time 0 while self._running and cap.isOpened(): ret, frame cap.read() if not ret: continue frame cv2.flip(frame, 1) rgb_frame cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results hands.process(rgb_frame) if results.multi_hand_landmarks: for hand_landmarks in results.multi_hand_landmarks: gesture self._classify_gesture(hand_landmarks) current_time time.time() if (gesture ! Gesture.UNKNOWN and gesture ! self._last_gesture and current_time - last_trigger_time self._gesture_cooldown): self._last_gesture gesture last_trigger_time current_time if self._callback: await self._callback(gesture) await asyncio.sleep(0.033) cap.release() hands.close() except ImportError as e: logger.warning(f手势识别依赖未安装: {e})语音控制用 SpeechRecognition 库把识别到的文本解析成命令。提示词请实现语音控制模块支持以下语音命令 - 打开灯光 / 开灯 → 打开灯光 - 关闭灯光 / 关灯 → 关闭灯光 - 亮一点 / 暗一点 → 调节亮度 - 彩虹模式 / 呼吸灯 等 → 切换效果 - 红色 / 蓝色 等 → 切换颜色 使用 SpeechRecognition 库支持离线识别。命令解析用关键词匹配加正则表达式# backend/app/services/voice_service.py 核心片段 COLOR_MAP { 红色: (255, 0, 0), 绿色: (0, 255, 0), 蓝色: (0, 0, 255), 黄色: (255, 255, 0), 紫色: (128, 0, 255), 橙色: (255, 165, 0), 粉色: (255, 105, 180), 白色: (255, 255, 255), 暖白: (255, 240, 220), 冷白: (200, 220, 255), } EFFECT_MAP { 纯色: solid, 呼吸灯: breathing, 呼吸: breathing, 彩虹: rainbow, 彩虹模式: rainbow, 流水灯: chase, 流水: chase, 频闪: strobe, 闪烁: strobe, 烛光: candle, 蜡烛: candle, 极光: aurora, 北极光: aurora, 音乐: music, 音乐模式: music, } class VoiceController: def parse_command(self, text: str) - Optional[VoiceCommand]: 解析语音识别结果为具体命令 text text.strip().lower() if any(kw in text for kw in [开灯, 打开灯光, 打开灯, 亮灯]): return VoiceCommand(power_on) if any(kw in text for kw in [关灯, 关闭灯光, 关闭灯, 熄灯]): return VoiceCommand(power_off) if any(kw in text for kw in [亮一点, 更亮, 加亮, 调亮]): return VoiceCommand(brightness_up, step30) if any(kw in text for kw in [暗一点, 更暗, 调暗, 暗一些]): return VoiceCommand(brightness_down, step30) match re.search(r亮度\s*(\d), text) if match: percent int(match.group(1)) return VoiceCommand(set_brightness, brightnessint(percent / 100 * 255)) for color_name, rgb in COLOR_MAP.items(): if color_name in text: return VoiceCommand(set_color, colorrgb) for effect_name, effect_type in EFFECT_MAP.items(): if effect_name in text: return VoiceCommand(set_effect, effecteffect_type) return None语音识别的主循环async def start(self, callback: Callable): 启动语音识别监听 self._callback callback self._running True try: import speech_recognition as sr recognizer sr.Recognizer() recognizer.energy_threshold 300 recognizer.dynamic_energy_threshold True with sr.Microphone() as source: recognizer.adjust_for_ambient_noise(source, duration2) while self._running: try: audio recognizer.listen(source, timeout5, phrase_time_limit5) text recognizer.recognize_google(audio, languagezh-CN) command self.parse_command(text) if command and self._callback: await self._callback(command) except sr.WaitTimeoutError: pass except sr.UnknownValueError: pass except sr.RequestError as e: logger.error(f语音识别服务错误: {e}) await asyncio.sleep(1) except ImportError: logger.warning(speech_recognition 未安装)现在把两条通道接到 FastAPI 主入口。WebSocket 端点负责向前端推送灯光状态REST API 负责接收控制命令# backend/app/main.py 核心片段 asynccontextmanager async def lifespan(app: FastAPI): global led_strip, effect_engine, scene_scheduler config LedConfig(num_leds60, simulateTrue) led_strip LedStrip(config) effect_engine EffectEngine(led_strip) scene_scheduler SceneScheduler(effect_engine) logger.info(智能灯光控制系统启动完成) yield await effect_engine.stop() led_strip.clear() app FastAPI(title智能灯光控制系统, lifespanlifespan) app.add_middleware(CORSMiddleware, allow_origins[*], allow_credentialsTrue, allow_methods[*], allow_headers[*]) app.post(/api/effect) async def set_effect(req: EffectRequest): 切换灯光效果 try: effect_type EffectType(req.effect) except ValueError: raise HTTPException(status_code400, detailf未知效果类型: {req.effect}) params EffectParams( colortuple(req.color) if req.color else (255, 100, 0), speedreq.speed or 1.0, intensityreq.intensity or 1.0, ) await effect_engine.start(effect_type, params) return {message: f效果已切换为: {effect_type.value}, status: ok} app.websocket(/ws) async def websocket_endpoint(websocket: WebSocket): WebSocket 连接端点 await websocket.accept() led_strip.register_client(websocket) try: await websocket.send_json(led_strip.get_state()) while True: data await websocket.receive_json() await _handle_ws_command(data) except WebSocketDisconnect: led_strip.unregister_client(websocket)启动后端cd backend uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload启动前端cd frontend pnpm dev打开浏览器访问http://localhost:5173你应该能看到 LED 灯带预览和效果控制面板。点击“彩虹”按钮灯带预览应该开始滚动彩虹色。打开终端用 curl 验证 REST APIcurl -X POST http://localhost:8000/api/effect \ -H Content-Type: application/json \ -d {effect: breathing, color: [255, 100, 0], speed: 1.5}预期返回{message: 效果已切换为: breathing, status: ok}同时浏览器里的灯带预览应该开始呼吸闪烁。再验证 WebSocket 推送在浏览器控制台里看 Network 面板的 WS 连接应该能看到每帧推送的led_update消息。手势识别和语音控制的验证需要摄像头和麦克风。如果你在无头服务器上跑可以先用模拟数据测试命令解析逻辑# 测试语音命令解析 from app.services.voice_service import VoiceController vc VoiceController() print(vc.parse_command(把灯光调成彩虹模式)) # 预期输出: VoiceCommand(actionset_effect, params{effect: rainbow}) print(vc.parse_command(亮度50)) # 预期输出: VoiceCommand(actionset_brightness, params{brightness: 127})灯光响应准确率的验证方法准备 20 条语音命令和 10 个手势分别测试记录正确响应的次数。语音命令在安静环境下准确率应该在 90% 以上手势识别在光线充足时准确率在 85% 以上。如果低于这个值先检查麦克风增益和摄像头曝光再考虑调整识别阈值。5. 本篇常见错排查401、local proxy failed 与 OAuth 报错这一节列出实际联调中最容易遇到的报错和排查路径。每个报错都给出真实错误信息和解决步骤。报错一401 Unauthorized{error: {message: Invalid API key, type: invalid_request_error}}这个报错说明 Key 不对或没传。排查顺序先确认.env文件里的TAOTOKEN_API_KEY有没有多余空格或换行再确认代码里读取环境变量的方式正确最后确认 Key 没有过期或被撤销。如果你用的是 Codex CLI检查~/.codex/auth.json里的api_key字段。# 快速验证 Key 是否有效 curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model: gpt-4o-mini, messages: [{role: user, content: test}]}如果返回 200 和正常响应说明 Key 没问题问题在代码里的读取逻辑。如果返回 401说明 Key 本身有问题去控制台重新生成一个。报错二local proxy failed / connection refusedError: local proxy failed: dial tcp 127.0.0.1:7890: connect: connection refused这个报错通常出现在你本地配了代理但代理服务没启动。排查检查系统环境变量HTTP_PROXY和HTTPS_PROXY是否指向了一个没运行的端口。如果你不需要代理直接 unset 这两个变量unset HTTP_PROXY unset HTTPS_PROXY然后重新跑请求。如果你确实需要代理才能访问外网确保代理服务在运行并且端口号正确。注意TaoToken 的 API 端点在国内可以直接访问不需要额外代理。报错三reading choices 相关错误KeyError: choices或者TypeError: NoneType object is not subscriptable这个报错说明 API 返回的 JSON 结构和你预期的不一样。常见原因是请求体格式不对或者模型名称写错了。检查你的请求体# 正确的请求体格式 payload { model: gpt-4o-mini, # 确认模型名称正确 messages: [{role: user, content: 你的提示词}], temperature: 0.7 }如果模型名称写成了gpt-4但你的账号没有这个模型的权限API 会返回错误信息而不是choices。先打印完整响应体看看response requests.post(url, headersheaders, jsonpayload) print(response.status_code) print(response.text) # 打印完整响应不要直接 response.json()[choices]报错四OAuth 相关错误Error: OAuth token expired or invalid如果你用的是 Claude Code 或 Codex 的 OAuth 登录模式token 过期后会报这个错。解决方法是重新登录# Claude Code 重新登录 claude login # Codex 重新登录 codex login如果你用的是 API Key 模式而不是 OAuth不会遇到这个报错。建议在自动化脚本里统一用 API Key避免 token 过期导致任务中断。报错五WebSocket 连接失败WebSocket connection to ws://localhost:8000/ws failed: Error during WebSocket handshake排查确认后端服务在运行端口没被占用确认前端配置的 WS URL 和后端一致确认 CORS 中间件允许了 WebSocket 升级请求。FastAPI 的 CORS 中间件默认不处理 WebSocket需要在 WebSocket 端点里手动处理。报错六MediaPipe 导入失败ImportError: cannot import name solutions from mediapipe这个通常是版本不兼容。MediaPipe 的 API 在不同版本间有变化确认你安装的是 0.10 以上版本pip install mediapipe0.10.9如果还是报错检查 Python 版本。MediaPipe 对 Python 3.12 的支持还不完善建议用 3.10 或 3.11。报错七语音识别无响应如果语音识别一直没反应先确认麦克风权限。在 macOS 上终端需要麦克风权限才能录音。去系统设置 → 隐私与安全性 → 麦克风勾选你的终端应用。在 Linux 上用arecord -l确认麦克风设备被识别。如果识别到了文字但命令没触发打印解析结果看看text recognizer.recognize_google(audio, languagezh-CN) print(f识别结果: {text}) command self.parse_command(text) print(f解析命令: {command})常见问题是识别结果里有标点符号或空格导致关键词匹配失败。在parse_command里先做一次清洗text text.strip().lower().replace(, ).replace(。, ).replace( , )报错八灯光效果卡顿如果灯带预览明显卡顿先检查帧率。在效果引擎里加一行日志frame_interval 1.0 / self._frame_rate # 在循环里打印实际帧间隔如果实际帧间隔远大于frame_interval说明set_pixels_batch或show太慢。优化方向减少 WebSocket 推送频率用MessageThrottle限制到 30fps或者把set_pixels_batch里的逐个赋值改成 numpy 批量操作。class MessageThrottle: 消息节流器限制 WebSocket 推送频率 def __init__(self, min_interval_ms: int 33): self.min_interval min_interval_ms / 1000 self._last_send 0 def should_send(self, current_time: float) - bool: if current_time - self._last_send self.min_interval: self._last_send current_time return True return False排查完这些系统应该能稳定运行了。如果还有问题去接入文档里查对应错误码的说明。6. 语义一致 CTA把模型能力接进你的灯光项目到这里智能灯光控制系统的核心链路已经跑通了Codex 生成骨架FastAPI 提供 API 和 WebSocketVue3 做实时预览手势识别和语音控制双通道联动。接下来你可以把模型能力接进来让语音命令支持更自然的表达或者让手势识别有更低的误触率。接入路径很直接去 https://taotoken.net/api-keys 创建一个 Key然后在项目里通过环境变量注入。如果你打算长期用 Codex 做编码和调试Coding Plan 比按量付费更省心具体方案在 https://taotoken.net/coding-plan 。如果你只是想先验证模型对话能力可以直接在 https://taotoken.net/chat 里试几句确认通道通了再写代码。接入文档在 https://taotoken.net/doc 里面有完整的 API 参考和错误码说明。遇到 401 或连接问题先查文档里的排障章节大部分常见问题都有覆盖。最后给一个实用技巧在settings.py里把模型配置做成可切换的这样你可以在不同模型之间快速对比效果而不用改代码。# backend/config/settings.py import os from pydantic_settings import BaseSettings class Settings(BaseSettings): taotoken_api_key: str os.getenv(TAOTOKEN_API_KEY, ) taotoken_base_url: str os.getenv(TAOTOKEN_BASE_URL, https://taotoken.net/api) taotoken_model: str os.getenv(TAOTOKEN_MODEL, gpt-4o-mini) led_num: int 60 led_simulate: bool True log_level: str info settings Settings()把语音命令解析从关键词匹配升级到模型语义理解只需要在parse_command里加一个 fallback关键词没匹配到时调用模型 API 做意图识别。这样“把灯光调得温柔一点”也能映射到breathing效果加暖色调。整个项目从零到跑通核心代码不超过 800 行但覆盖了 AI 辅助编码、硬件驱动、实时通信、手势识别、语音控制五个技术面。你可以在这个骨架上继续加场景调度、音乐联动、多设备同步扩展空间很大。