ESP-AI

English

简体中文

English

简体中文

Appearance

服务端配置

About 3073 wordsAbout 10 min

2024-11-7

基础配置

port

  • 类型: number
  • 默认值: 8080
  • 必填：否
  • 说明: 服务端口号

使用案例

const serverConfig = {
  port: 8080, // 设置服务端口号
};

api_key

  • 类型: string
  • 默认值: -
  • 必填：否
  • 说明: ESP-AI的秘钥，在一些需要进行AI服务时使用

使用案例

const serverConfig = {
  api_key: "xxx", // 获取方式： 打开 https://espai.fun -> 创建超体 -> 左下角 api_key
};

devLog

  • 类型: number
  • 默认值: 1
  • 必填：否
  • 说明: 日志输出模式
    • 0: 不输出(线上模式)
    • 1: 普通输出
    • 2: 详细输出

使用案例

const serverConfig = {
  devLog: 1,  // 设置日志输出模式为普通输出
};

iatDu

  • 类型: string | boolean
  • 默认值: false
  • 必填：否
  • 说明: 语音识别开始前"嘟"的提示音音频流地址,只支持本地 mp3 文件, 请使用 16k 或者 24k 音频，推荐 16k

为 true 时使用默认的嘟提示音，为文件地址时使用文件地址的音频，为false时不播放提示音。

使用案例

import path from 'path' 

// 下面地址是在你的项目根目录放一个 ./du.mp3，你也可以根据情况自行修改地址
const serverConfig = {
  iatDu: path.join(__dirname, './du.mp3'), // 设置语音识别开始前的音频流地址
};

llm_qa_number

  • 类型: number
  • 默认值: 5
  • 必填：否
  • 说明: LLM 对话历史保留回合数,一问一答为一回合

使用案例

const serverConfig = {
  llm_qa_number: 5, // 设置LLM对话历史保留回合数
};

客户端配置生成

gen_client_config

  • 类型: (params: Record<string, any>) => Promise<ConfigResponse>
  • 必填：是
  • 说明: 生成客户端配置,包括语音识别、TTS、LLM等服务配置
  • 参数:
    • params.send_error_to_client: 向客户端发送错误信息的函数
    • params.ws: WebSocket对象
    • params.client_params: 客户端配置参数
  • 返回值:
    • 成功时返回配置对象
    • 失败时返回 { success: false, message: string }

详细内置接入的平台见：内置的各平台使用教程

使用案例

const config = {
  gen_client_config: async (params) => {
    // 生成客户端配置
    return {
      api_key: "xxx", // 用户`ESP-AI`的秘钥，在一些需要进行AI服务时使用。 权重比全局高，这里配置后优先使用这里的
      iat_server: "xun_fei",
      iat_config: {
        appid: "xxx",
        apiSecret: "xxx",
        apiKey: "xxx",
        vad_eos: 1500,
        // iat_server 中可配置的其他配置项...
      },
      llm_server: "xun_fei",
      llm_config: {
        appid: "xxx",
        apiSecret: "xxx",
        apiKey: "xxx",
        llm: "v4.0",
        // llm_server 中可配置的其他配置项...
      },
      tts_server: "xun_fei",
      tts_config: {
        appid: "xxx",
        apiSecret: "xxx",
        apiKey: "xxx",
        is_clone: false, // 是否为克隆的音色
        // tts_server 中可配置的其他配置项...
      },
      connected_reply: "已成功连接服务器",  // 设置为 false 则关闭
      f_reply: "你好", // 设置为 false 则关闭提示音
      sleep_reply: "我先休息了哦，有需要再叫我", // 设置为 false 则关闭
      llm_init_messages: [
        { role: 'system', content: '你是小明同学，是一个无所不能的智能助手。' },
      ],

      // 指令配置
      intention: [
        {
            // 关键词
            key: ["帮我开灯", "开灯", "打开灯"],
            // 向客户端发送的指令
            instruct: "device_open_001",
            message: "开啦！还有什么需要帮助的吗？", 
            // 配置开放平台 api_key 后字符串类型的指令会进行NLP推理。
            api_key: "xxx",
        },
        {
            // 关键词
            key: ["帮我关灯", "关灯", "关闭灯"],
            // 向客户端发送的指令
            instruct: "device_close_001",
            message: "关啦！还有什么需要帮助的吗？",
            // 配置开放平台 api_key 后字符串类型的指令会进行NLP推理。
            api_key: "xxx",
        },
        // 远程开关， 具体教程见： https://espai.fun/example/switch/
        {
            // 关键词
            key: ["帮我关灯", "关灯", "关闭灯"],
            // 向客户端发送的指令
            instruct: "device_close_001",
            message: "关啦！还有什么需要帮助的吗？",
            // 目标设备ID
            target_device_id:"xxx",
            // 超体 api_key
            api_key:"xxx",
        },
        {
            // 关键词
            key: ["退下吧", "退下"],
            // 内置的睡眠指令
            instruct: "__sleep__",
            message: "我先退下了，有需要再叫我。",
            // 配置开放平台 api_key 后字符串类型的指令会进行NLP推理。
            api_key: "xxx",
        }, 
        {
            // 调到指定音量
            key: async (text = "") => {
                const pattern = /音量调到(\d+)\%/;
                // 查找匹配项
                const match = text.match(pattern);
                if (match) { 
                    return true;
                }
            },
            instruct: ({ text }) => {
                const pattern = /音量调到(\d+)\%/;
                const match = text.match(pattern);
                const volumeLevel = match[1];
                console.log("音量设置为:", volumeLevel);
                // 直接传给业务服务，业务服务可再传给硬件，这样硬件就可以进行调整音量了
                // ... 
            },
            message: "好的"
        },
        {
            /**
             * 正则匹配
             * 如：播放音乐最后的倔强  
             * 返回匹配的字符串为匹配成功
            */
            key: async (text = "", llm_historys) => {
                const regex = /^(播放音乐)(.*)$/;
                const match = text.match(regex);
                if (match) {
                    const songName = match[2];
                    console.log("音乐名称:", songName);
                    return songName;
                } else {
                    return false;
                }
            },
            // 向客户端发送的指令
            instruct: "__play_music__",
            message: "好的！",
            /**
             * 用于返回音频地址和播放进度
             * 目前只支持 mp3、wav 格式
             * @param {String} name 是歌曲名称
             * @return {number} seek 进度： （以秒为单位）
             * @return {message} 找不到数据时的TTS
            */ 
            music_server: async (name, { user_config, signal, sendToClient }) => { 
                return {
                    url:"https://xiaomingio.top/music.mp3",
                    seek: 0,
                    message: message
                };
            },
            /**
             * 当音频结束后的回调
             * @param {object} arg.break_second  停止时的进度，单位秒。也就是用户播放了到了多少秒（seek+play_time）
             * @param {object} arg.play_time     实际播放音频的时间，单位秒。
             * @param {object} arg.seek          音频开始播放时间，其实也就是 music_server 函数中返回的 seek 值
             * @param {object} arg.start_time    开始播放音频的 Unix 毫秒数时间戳
             * @param {object} arg.end_time      结束播放音频的 Unix 毫秒数时间戳
             * @param {object} arg.event         结束原因： "user_break" 用户打断 | play_end 播放完毕 | foo 未知事件 
            */
            on_end: (arg) => {
                // 请求业务服务器保存进度信息 ...
                console.log(arg);
            }
        },
        /**
         * 独立为本设备设置语音识别开始前"嘟"的音频流，默认为 false，也就是不开启提示音
         * 只能播放本地 mp3 地址： iatDu: path.join(__dirname, `./du.mp3`) // nodejs 写法
         * 为 false 时关闭提示音，为 true 时使用默认提示音。
         * 目前仅仅能设置为 false 以关闭设备提示音
        */
        iatDu?: string | boolean;

        // 其他...

      ],
    };
  },
};

鉴权配置

auth

  • 类型: (params: AuthParams) => Promise<AuthResponse>
  • 必填：否
  • 说明: 客户端鉴权函数，client_params 是客户端在服务配置中的params。 每个对话都会走一次，所以一定要保证速度，建议使用缓存技术解决。
  • 参数:
    {
  type: "connect" | "start_session"; // 鉴权场景
  send_error_to_client: (code: number, message: string) => void;
  ws: WebSocket;
  client_params: {
    api_key: string;
    ext1: string; 
    ext2: string;
  }
}
  • 返回值:
    • 成功: { success: true }
    • 失败: { success: false, message: string }

使用案例

const config = {
  auth: async (params) => {
    if (params.client_params.api_key === "valid_api_key") {
      return { success: true }; // 鉴权成功
    } else {
      params.send_error_to_client(401, "无效的API密钥");
      return { success: false, message: "无效的API密钥" }; // 鉴权失败
    }
  },
};

参数控制

llm_params_set

  • 类型: (params: Record<string, any>) => Record<string, any>
  • 必填：否
  • 说明: 控制 LLM 参数,如温度等

使用案例

const config = {
  llm_params_set: (params) => {
    // 修改默认的 LLM 参数, 必须返回 params 数据
    return { ...params, temperature: 0.8 };
  },
};

tts_params_set

  • 类型: (params: Record<string, any>) => Record<string, any>
  • 必填：否
  • 说明: 控制 TTS 参数,如说话人、音量、语速等

使用案例

const config = {
  tts_params_set: (params) => {
    // 修改默认的 TTS 参数, 必须返回 params 数据
    return { ...params, volume: 5, speed: 1.0 };
  },
};

事件回调

onDeviceConnect

  • 类型: (arg: DeviceConnectArg) => void
  • 必填：否
  • 说明: 新设备连接时的回调
  • 参数:
    {
  device_id: string;      // 设备ID 
  client_version: string; // 客户端版本
  instance: Instance      // ESP-AI 实例
  client_params           //  配网页面配置的客户端参数
}

使用案例

const config = {
  onDeviceConnect: (arg) => {
    console.log(`设备 ${arg.device_id} 已连接，客户端版本：${arg.client_version}`);
  },
};

onDeviceDisConnect

  • 类型: (arg: DeviceConnectArg) => void
  • 必填：否
  • 说明: 设备断开连接的回调
  • 参数:
    {
  device_id: string;      // 设备ID  
  instance: Instance      // ESP-AI 实例
  client_params           //  配网页面配置的客户端参数
}

使用案例

const config = {
  onDeviceDisConnect: (arg) => {
    console.log(`设备 ${arg.device_id} 已断开连接`);
  },
};

onSleep

  • 类型: (arg: DeviceConnectArg) => void
  • 必填：否
  • 说明: 设备断开连接的回调
  • 参数:
    {
  device_id: string;      // 设备ID  
  instance: Instance      // ESP-AI 实例
  client_params           //  配网页面配置的客户端参数
}

使用案例

const config = {
  onSleep: (arg) => {
    console.log(`设备 ${arg.device_id} 已休眠`);
  },
};

onIAT

  • 类型: (arg: IATArg) => void
  • 必填：否
  • 说明: 语音识别请求前的回调(注意，这是转换前，所以什么都拿不到，只能获取到麦克风pcm)

使用案例

const config = {
  onIAT: (arg) => {
    console.log(`设备 ${arg.device_id} 发起语音识别请求`);
  },
};

onIATcb

  • 类型: (arg: IATCallbackArg) => void
  • 必填：否
  • 说明: 语音识别过程中的回调
  • 参数:
    {
  device_id: string;    // 设备ID
  text: string;         // 识别文本
  instance: Instance      // ESP-AI 实例
  sendToClient: (diy_text?: string) => void; // 发送到客户端的函数, 默认发送 text 到客户端，如果你要自定义就传入 diy_text 即可
}

/**
 * iat 回调: 语音识别过程中的回调
 * @param {string}    device_id     设备id
 * @param {string}    text          语音转的文字 
 * @param {()=>void}  sendToClient  调用这个方法后可以直接将文字发送到客户端，客户端使用 onEvent 接收、 
 * 
 * *****  调用 sendToClient() 后，客户端代码向下面这样写即可接收到音频流 **** 
 * void on_command(String command_id, String data) {
 *      if (command_id == "on_iat_cb") {
 *          // some code...
 *      }
 * } 
 * void setup() {
 *      ...
 *      esp_ai.onEvent(on_command);
 * }
*/

使用案例

const config = {
  onIATcb: (arg) => {
    console.log(`设备 ${arg.device_id} 识别到文本：${arg.text}`);
    arg.sendToClient();
  },
};

onTTS

  • 类型: (arg: TTSArg) => void
  • 必填：否
  • 说明: TTS 转换前的回调
  • 参数:
    {
  device_id: string;     // 设备ID
  tts_task_id: string;   // TTS任务ID
  text: string;          // 待转换文本
  instance: Instance      // ESP-AI 实例
  sendToClient: (diy_text?: string) => void; // 发送到客户端的函数, 默认发送 text 到客户端，如果你要自定义就传入 diy_text 即可
}

onTTScb

  • 类型: (arg: TTSCallbackArg) => void
  • 必填：否
  • 说明: TTS 转换完成的回调
  • 参数:
    {
  device_id: string;     // 设备ID
  is_over: boolean;      // 是否完成
  audio: Buffer;         // 音频流, mp3 格式, 使用 base64 格式进行封装。自行解码为二进制即可。
  instance: Instance      // ESP-AI 实例
  sendToClient: () => void; // 发送到客户端的函数
}

使用案例

const config = {
  onTTScb: (arg) => { 
    console.log(arg.audio)

    // 调用这个方法后可以直接将文字发送到客户端，客户端使用 onEvent 接收、 
    // arg.sendToClient();
    //
    // 客户端接收代码如下：
    // void on_command(String command_id, String data) {
    //      if (command_id == "on_tts_cb") {
    //          // some code...
    //      }
    // } 
    // void setup() {
    //      ...
    //      esp_ai.onEvent(on_command);
    // }
  },
};

onLLM

  • 类型: (arg: LLMArg) => void
  • 必填：否
  • 说明: LLM 服务调用前的回调

onLLMcb

  • 类型: (arg: LLMCallbackArg) => void
  • 必填：否
  • 说明: LLM 推理完成的回调
  • 参数:
    {
  device_id: string;     // 设备ID
  text: string;          // 大语言模型推理出来的文本片段
  user_text: string;     // 用户问题 
  llm_text: string;      // 大模型推理出来的完整文本  
  is_over: boolean;      // 是否推理完毕
  llm_historys: Record<string, any>[]; // 对话历史
  instance: Instance      // ESP-AI 实例
  sendToClient: (diy_text?: string) => void; // 发送到客户端的函数, 默认发送 text 到客户端，如果你要自定义就传入 diy_text 即可
}

使用案例

const config = {
  onLLMcb: (arg) => { 
    console.log(arg.text)

    // 调用这个方法后可以直接将文字发送到客户端，客户端使用 onEvent 接收、 
    // arg.sendToClient();
    //
    // 客户端接收代码如下：
    // void on_command(String command_id, String data) {
    //      if (command_id == "on_llm_cb") {
    //          // some code...
    //      }
    // } 
    // void setup() {
    //      ...
    //      esp_ai.onEvent(on_command);
    // }
  },
};

插件系统

plugins

  • 类型: Plugin[]
  • 必填：否
  • 说明: 插件配置

使用案例

const config = {
  plugins: [
    // 引入插件，注意：使用插件时必须按插件文档中要求的配置项来配置插件
    // 如这个插件：https://github.com/wangzongming/esp-ai-plugin-tts-aliyun
    require("esp-ai-plugin-tts-aliyun")
  ],
};

日志配置

logs

  • 类型: LogConfig
  • 必填：否
  • 说明: 自定义日志输出配置
  • 配置结构:
    {
  info?: () => void;  // 普通消息
  error?: () => void; // 错误消息
}

使用案例

const config = {
  logs: {
    info: () => {
      console.log("普通日志信息");
    },
    error: () => {
      console.error("错误日志信息");
    },
  },
};

服务压力测试数据

测试环境:

  • 服务商: 腾讯云
  • CPU: 2核
  • 内存: 2G
  • 带宽: 4MB
  • 硬盘: SSD 50GB

连接测试结果

连接数量成功量失败量并发瞬间服务情况连接后服务情况
100010000CPU:100%, MEM:1.5GBCPU:4%, MEM:1.5GB
200020000CPU:100%, MEM:1.5GBCPU:4%, MEM:1.5GB
300030000CPU:100%, MEM:1.5GBCPU:4%, MEM:1.5GB
40003806194(5%)CPU:100%, MEM:1.5GBCPU:4%, MEM:1.5GB
50004685315(6.7%)CPU:100%, MEM:1.5GBCPU:4%, MEM:1.5GB
600040301970(32%)CPU:100%, MEM:1.6GBCPU:4%, MEM:1.5GB
1000052服务崩溃--

音频流测试结果

测试条件:

  • 音频大小: 10KB
  • 分片大小: 2048字节
  • 每连接消息数: 6次
连接数量连接成功量应发消息实发消息失败量并发瞬间服务情况连接后服务情况
1009226006000CPU:100%, MEM:1.5GBCPU:4%, MEM:1.5GB
500500300030000CPU:100%, MEM:1.5GBCPU:4%, MEM:1.5GB
10001000600060000CPU:100%, MEM:1.5GBCPU:4%, MEM:1.5GB
2000200012000120000CPU:100%, MEM:1.5GBCPU:4%, MEM:1.5GB
300029821800029820CPU:100%, MEM:1.5GBCPU:4%, MEM:1.5GB
Powered by VuePress & vuepress-theme-plume
Apache 2.0 Licensed | Copyright © ESP-AI 地址：深圳市福田区汉国中心1206

🎉 ESP-AI 公告 🎉


📢 2025 年 6 月 2 日

近期，ESP-AI 服务器及开源仓库遭受大规模恶意攻击。

我们始终坚持将自主研发的代码完全开源，这一行动虽触及部分群体利益，但我们始终坚信技术价值高于一切。

开源不仅是代码的共享，更是极客精神的践行 —— 我们以技术为信仰，以开放为武器，直面行业沉疴。

我们是一群笃信技术力量的极客。 我们确信，唯有通过真正的技术创新与实力角逐，才能打破 “闭源垄断 + 手段竞争” 的行业怪圈。那些企图以非技术手段维系优势的落后模式，终将在开放协作的浪潮中被颠覆。

技术的战场，从不应由 “围墙” 决定胜负。我们将继续以开源为旗，让代码质量与创新能力成为唯一的竞争标准。

极客不死，开源不止。



📢 2025/6/1 公告

ESP-AI 新版已发布：升级日志

open api提供音乐生成接口：OPEN API

open api天气查询接口：OPEN API



QQ qr_code

QQ 交流群： 952051286

您在使用过程中遇到任何问题，欢迎通过 issue 反馈。
也欢迎加入我们的 QQ 交流群一起讨论。