# aiot-nodejs

**Repository Path**: cdwyyds/aiot-nodejs

## Basic Information

- **Project Name**: aiot-nodejs
- **Description**: nodejs版本的aiot服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-02-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xiaozhi-server 企业级智能家居控制中心架构文档

## 🏗️ 系统架构概览

xiaozhi-server 是一个基于 NestJS 构建的企业级智能家居控制中心，采用模块化微服务架构，提供完整的语音交互、AI对话、设备控制和智能家居管理能力。

### 核心设计理念

- **模块化设计**：每个功能模块独立封装，支持热插拔和动态扩展
- **工厂模式**：统一的提供者创建和管理机制
- **依赖注入**：NestJS原生IoC容器管理所有服务依赖
- **接口抽象**：统一的接口定义，支持多厂商适配
- **企业级特性**：完整的错误处理、日志记录、健康检查、资源清理

## 📊 系统分层架构

```
┌─────────────────────────────────────────────────────────────┐
│                    应用层 (Application Layer)                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   WebSocket网关  │  │   HTTP API网关   │  │    OTA服务      │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                    业务逻辑层 (Business Layer)                │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   对话管理服务   │  │   意图识别服务   │  │   工具调用服务   │ │
│  │   记忆管理服务   │  │   插件管理服务   │  │   声纹识别服务   │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                    AI适配层 (AI Adapter Layer)               │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   ASR提供者池    │  │   TTS提供者池    │  │   LLM提供者池    │ │
│  │  (15个厂商适配)  │  │  (8个厂商适配)   │  │  (6个厂商适配)   │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                    基础设施层 (Infrastructure Layer)          │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   配置管理服务   │  │   日志记录服务   │  │   认证授权服务   │ │
│  │   音频编解码     │  │   会话管理器     │  │   VAD语音检测    │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

## 🎯 核心模块详解

### 1. IoT网关模块 (`modules/iot/`)

**职责**：处理设备连接、音频流传输、协议适配

```typescript
// 核心服务架构
├── gateway/
│   └── iot.gateway.ts              # WebSocket网关入口
├── handlers/                       # 消息处理器
│   ├── connection.handler.ts       # 连接管理
│   ├── audio-receive.handler.ts    # 音频接收处理
│   ├── audio-send.handler.ts       # 音频发送处理
│   ├── intent.handler.ts          # 意图处理
│   └── report.handler.ts          # 数据上报处理
└── services/                      # 核心服务
    ├── session-manager.service.ts  # 会话管理
    ├── audio-codec.service.ts     # 音频编解码
    └── vad.service.ts             # 语音活动检测
```

**关键特性**：
- **实时音频流处理**：支持PCM/Opus格式的实时音频传输
- **会话生命周期管理**：完整的连接建立、维持、断开流程
- **VAD语音检测**：智能语音端点检测，支持手动/自动模式
- **多设备并发**：支持多个IoT设备同时连接和交互

### 2. AI服务模块 (`modules/ai/`)

**职责**：AI能力统一管理、多厂商适配、智能对话

```typescript
// AI服务架构
├── services/                      # 核心AI服务
│   ├── ai-factory.service.ts      # AI提供者工厂
│   ├── intent-factory.service.ts  # 意图识别工厂
│   ├── memory-factory.service.ts  # 记忆管理工厂
│   ├── tool-manager.service.ts    # 工具管理器
│   ├── plugin-registry.service.ts # 插件注册中心
│   ├── voiceprint.service.ts      # 声纹识别服务
│   └── wakeup-word.service.ts     # 唤醒词管理
├── providers/                     # AI提供者实现
│   ├── asr/                       # 语音识别提供者
│   │   ├── aliyun-asr.provider.ts
│   │   ├── baidu-asr.provider.ts
│   │   ├── tencent-asr.provider.ts
│   │   ├── xunfei-asr.provider.ts
│   │   ├── doubao-asr.provider.ts
│   │   ├── fun-local-asr.provider.ts
│   │   └── fun-server-asr.provider.ts
│   ├── tts/                       # 语音合成提供者
│   │   ├── aliyun-tts.provider.ts
│   │   ├── azure-tts.provider.ts
│   │   ├── doubao-tts.provider.ts
│   │   └── volcano-tts.provider.ts
│   ├── llm/                       # 大语言模型提供者
│   │   ├── openai-llm.provider.ts
│   │   ├── ollama-llm.provider.ts
│   │   ├── gemini-llm.provider.ts
│   │   └── dify-llm.provider.ts
│   ├── intent/                    # 意图识别提供者
│   │   ├── nointent.provider.ts
│   │   ├── function-call.provider.ts
│   │   └── intent-llm.provider.ts
│   ├── memory/                    # 记忆管理提供者
│   │   ├── nomem.provider.ts
│   │   ├── local-short.provider.ts
│   │   └── mem0ai.provider.ts
│   └── tools/                     # 工具执行器
│       └── device-iot.executor.ts
└── interfaces/                    # 接口定义
    └── ai-provider.interface.ts
```

**关键特性**：
- **多厂商AI生态**：支持15个ASR、8个TTS、6个LLM厂商
- **工厂模式管理**：统一的提供者创建和配置机制
- **插件化架构**：支持动态加载和扩展AI能力
- **智能对话能力**：完整的意图理解、记忆管理、工具调用

### 3. 配置管理模块 (`modules/config/`)

**职责**：系统配置管理、环境适配、API客户端

```typescript
// 配置管理架构
├── config.service.ts              # 配置服务
├── manage-api.client.ts          # 管理API客户端
└── interfaces/
    └── config.interface.ts       # 配置接口定义
```

**关键特性**：
- **分层配置管理**：支持环境变量、配置文件、动态配置
- **配置验证**：完整的配置项验证和默认值处理
- **热更新支持**：支持配置的动态更新和生效

### 4. OTA升级模块 (`modules/ota/`)

**职责**：固件管理、版本控制、设备升级

```typescript
// OTA服务架构
├── ota.controller.ts             # OTA控制器
├── ota.service.ts               # OTA服务
└── bin-scanner.service.ts       # 固件扫描服务
```

**关键特性**：
- **固件版本管理**：自动扫描和管理固件文件
- **设备升级支持**：支持IoT设备的远程固件升级
- **升级状态跟踪**：完整的升级进度和状态管理

## 🔧 通用服务层 (`common/`)

### 核心通用服务

```typescript
// 通用服务架构
├── services/
│   ├── auth.service.ts           # 认证授权服务
│   ├── logger.service.ts         # 日志记录服务
│   ├── dialogue.service.ts       # 对话管理服务
│   ├── prompt-manager.service.ts # 提示词管理
│   └── audio-rate-controller.service.ts # 音频速率控制
├── interfaces/
│   └── config.interface.ts      # 通用接口定义
├── decorators/
│   └── config.decorator.ts      # 配置装饰器
└── guards/
    └── auth.guard.ts            # 认证守卫
```

## 🎨 设计模式应用

### 1. 工厂模式 (Factory Pattern)

```typescript
// AI提供者工厂
@Injectable()
export class AiFactoryService {
  async createAsrProvider(type: string): Promise<AsrProvider> {
    switch (type) {
      case 'aliyun': return new AliyunAsrProvider();
      case 'baidu': return new BaiduAsrProvider();
      case 'tencent': return new TencentAsrProvider();
      // ... 其他提供者
    }
  }
}
```

### 2. 策略模式 (Strategy Pattern)

```typescript
// 意图识别策略
export interface IntentProvider {
  recognizeIntent(text: string): Promise<IntentResult>;
}

// 不同的意图识别实现
export class FunctionCallProvider implements IntentProvider { }
export class IntentLlmProvider implements IntentProvider { }
export class NoIntentProvider implements IntentProvider { }
```

### 3. 观察者模式 (Observer Pattern)

```typescript
// 事件驱动的音频处理
@Injectable()
export class AudioReceiveHandler {
  async handleAudioMessage(session: Session, audioData: Buffer) {
    // 触发ASR识别
    this.eventEmitter.emit('audio.received', { session, audioData });
  }
}
```

## 🔄 数据流架构

### 语音交互完整流程

```mermaid
graph TD
    A[IoT设备] -->|音频流| B[WebSocket网关]
    B --> C[音频编解码服务]
    C --> D[VAD语音检测]
    D --> E[ASR语音识别]
    E --> F[意图识别服务]
    F --> G[LLM对话生成]
    G --> H[工具调用执行]
    H --> I[TTS语音合成]
    I --> J[音频编码传输]
    J -->|音频响应| A
    
    E --> K[声纹识别]
    K --> L[用户身份验证]
    
    F --> M[记忆管理]
    M --> N[上下文存储]
```

### 会话生命周期管理

```typescript
// 会话状态流转
enum SessionState {
  CONNECTING = 'connecting',
  CONNECTED = 'connected',
  LISTENING = 'listening',
  PROCESSING = 'processing',
  RESPONDING = 'responding',
  DISCONNECTED = 'disconnected'
}
```

## 🛡️ 企业级特性

### 1. 错误处理与恢复

```typescript
// 统一错误处理
@Catch()
export class GlobalExceptionFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    // 统一错误日志记录
    // 错误分类和处理
    // 优雅降级策略
  }
}
```

### 2. 健康检查机制

```typescript
// 服务健康检查
@Injectable()
export class HealthCheckService {
  async checkAiProviders(): Promise<HealthStatus> {
    // 检查ASR/TTS/LLM提供者状态
    // 返回详细健康报告
  }
}
```

### 3. 资源管理与清理

```typescript
// 自动资源清理
@Injectable()
export class ResourceManager {
  async cleanup(): Promise<void> {
    // 清理临时文件
    // 释放网络连接
    // 停止后台任务
  }
}
```

### 4. 性能监控

```typescript
// 性能指标收集
@Injectable()
export class MetricsService {
  recordAsrLatency(duration: number): void { }
  recordTtsLatency(duration: number): void { }
  recordMemoryUsage(): void { }
}
```

## 🔌 扩展性设计

### 1. 插件系统

```typescript
// 插件接口定义
export interface Plugin {
  name: string;
  version: string;
  initialize(): Promise<void>;
  execute(params: any): Promise<any>;
  cleanup(): Promise<void>;
}

// 插件注册中心
@Injectable()
export class PluginRegistry {
  registerPlugin(plugin: Plugin): void { }
  executePlugin(name: string, params: any): Promise<any> { }
}
```

### 2. 动态配置

```typescript
// 配置热更新
@Injectable()
export class ConfigService {
  @ConfigProperty('ai.asr.provider')
  asrProvider: string;
  
  updateConfig(key: string, value: any): void {
    // 动态更新配置
    // 触发相关服务重新初始化
  }
}
```

## 📈 系统能力总览

### AI服务生态

| 类型 | 支持厂商 | 数量 | 特性 |
|------|----------|------|------|
| **ASR** | 阿里云、百度、腾讯、讯飞、豆包、FunASR | 15个 | 实时识别、离线模型、多语言 |
| **TTS** | 阿里云、Azure、豆包、火山引擎、CosyVoice | 8个 | 多音色、情感合成、流式输出 |
| **LLM** | OpenAI、Ollama、Gemini、Dify、Coze、FastGPT | 6个 | 对话生成、函数调用、知识问答 |

### 智能功能

| 功能模块 | 实现方案 | 特性描述 |
|----------|----------|----------|
| **意图识别** | NoIntent/FunctionCall/IntentLLM | 3种识别策略，支持自定义意图 |
| **记忆管理** | NoMem/LocalShort/Mem0AI | 3种存储方案，支持长短期记忆 |
| **工具调用** | IoT设备控制/MCP协议 | 统一工具管理，支持设备控制 |
| **声纹识别** | 用户身份验证 | 多用户支持，说话人识别 |
| **唤醒词管理** | 动态配置 | 个性化唤醒，智能回复 |
| **插件系统** | 音乐/天气/智能家居 | 完整插件生态，动态扩展 |

### 企业级特性

- ✅ **高可用性**：完整的错误处理和恢复机制
- ✅ **可扩展性**：模块化设计，支持水平扩展
- ✅ **可观测性**：全链路日志记录和性能监控
- ✅ **安全性**：认证授权、数据加密、访问控制
- ✅ **易维护性**：统一的配置管理和部署流程

## 🚀 部署架构

### 容器化部署

```dockerfile
# 多阶段构建
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:18-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["npm", "run", "start:prod"]
```

### 服务发现与负载均衡

```yaml
# Kubernetes部署配置
apiVersion: apps/v1
kind: Deployment
metadata:
  name: xiaozhi-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: xiaozhi-server
  template:
    spec:
      containers:
      - name: xiaozhi-server
        image: xiaozhi-server:latest
        ports:
        - containerPort: 3000
        env:
        - name: NODE_ENV
          value: "production"
```

## 📋 总结

xiaozhi-server 是一个**真正的企业级智能家居控制中心**，具备：

- **完整的AI服务生态**：29个厂商适配，覆盖ASR/TTS/LLM全栈
- **企业级架构设计**：模块化、可扩展、高可用
- **丰富的智能功能**：意图识别、记忆管理、工具调用、声纹识别
- **生产就绪特性**：完整的监控、日志、错误处理、资源管理
- **灵活的扩展能力**：插件系统、动态配置、热更新支持

这是一个从AI对话系统全面升级为**企业级智能家居控制中心**的完整解决方案！🎉