SUSI.AI 在 Linux 上

此仓库包含用于在桌面或无头智能音箱（Headless Smart Speaker）上运行 SUSI.AI 的组件，需配合 SUSI.AI Server。此处实现的功能包括使用麦克风收集语音指令，使用 Deep Speech、Flite、Pocket Sphinx、IBM Watson 或其他组件将语音转换为文本（STT，即 Speech-to-Text），通过语音指令控制音量以及提供简单的 GTK 图形界面。为了使用 SUSI.AI Server（使用 Java 编写）的 JSON（JavaScript Object Notation）输出，我们使用了 SUSI.AI API Python Wrapper。该项目的最终目标是让用户能够在任何地方安装 SUSI.AI，除了桌面和智能音箱外，还包括物联网（IoT）设备、车载系统、洗衣机等。

项目的功能提供方式如下：

• “热词”（Hotword）检测适用于热词"Susi"
• 语音检测用于语音转文本（STT），配合 Google Speech API、IBM Watson Speech to Text API 使用
• 语音输出用于文本转语音（TTS），配合 Google Voice、IBM Watson TTS、Flite TTS 使用
• SUSI.AI 响应通过 SUSI.AI API Python Wrapper 实现

项目概述

SUSI.AI 生态系统由以下部分组成：

 * Web Client and Content Management System for the SUSI.AI Skills - Home of the SUSI.AI community
 |_ susi.ai   (React Application, User Account Management for the CMS, a client for the susi_server at https://api.susi.ai the content management system for susi skills)
 
 * server back-end
 |_ susi_server        (the brain of the infrastructure, a server which computes answers from queries)
 |_ susi_skill_data    (the knowledge of the brain, a large collection of skills provided by the SUSI.AI community)
 
 * android front-end
 |_ susi_android       (Android application which is a client for the susi_server at https://api.susi.ai)
 
 * iOS front-end
 |_ susi_iOS           (iOS application which is a client for the susi_server at https://api.susi.ai)
 
 * Smart Speaker - Software to turn a Raspberry Pi into a Personal Assistant
 | Several sub-projects come together in this device
 |_ susi_installer     (Framework which can install all parts on a RPi and Desktops, and also is able to create SUSIbian disk images)
 |_ susi_python        (Python API for the susi_server at https://api.susi.ai or local instance)
 |_ susi_server        (The same server as on api.susi.ai, hosted locally for maximum privacy. No cloud needed)
 |_ susi_skill_data    (The skills as provided by susi_server on api.susi.ai; pulled from the git repository automatically)
 |_ susi_linux         (a state machine in python which uses susi_python, Speech-to-text and Text-to-speech functions)
 |_ susi.ai            (React Application, the local web front-end with User Account Management, a client for the local deployment of the susi_server, the content management system for susi skills)

安装

susi_linux 通常通过 SUSI Installer 进行安装。 在这种情况下，配置和启动的二进制文件以及其他文件可在 $HOME/SUSI.AI/bin 中找到（默认安装设置下）。

如果是手动安装，wrapper 目录 中的封装程序需要配置为指向各自的安装目录和 config.json 文件的位置。

在 Linux / RaspberryPi 上设置和配置 Susi

配置通过文件 config.json 完成，该文件通常位于 $HOME/.config/SUSI.AI/config.json。

脚本 $HOME/SUSI.AI/bin/susi-config 最适合用于查询、设置和更改 susi_linux 的配置。此外，在 $HOME/SUSI.AI/bin/susi-linux-configure 中还有一个配置的图形用户界面（GUI）。

运行 $HOME/SUSI.AI/bin/susi-config keys 可获取可能的键和值。

一些重要的键和可能的值：

- `stt` is the speech to text service, one of the following choices:
    - `google` - use Google STT service
    - `watson` - IBM/Watson STT
    - `bing` - MS Bing STT
    - `pocketsphinx` - PocketSphinx STT system, working offline
    - `deepspeech-local` - DeepSpeech STT system, offline, WORK IN PROGRESS
- `tts` is the text to speech service, one of the following choices:
    - `google` - use Google TTS
    - `watson` - IBM/Watson TTS (login credential necessary)
    - `flite` - flite TTS service working offline
- `hotword.engine` is the choice if you want to use snowboy detector as the hotword detection or not
    - `Snowboy` to use snowboy
    - `PocketSphinx` to use Pocket Sphinx
- `wakebutton` is the choice if you want to use an external wake button or not
    - `enabled` to use an external wake button
    - `disabled` to disable the external wake button
    - `not available` for systems without dedicated wake button

Android 和 iOS 也有其他配置接口可用。

可以进行手动配置，config.json 中允许的键目前包括：

• device: 当前设备的名称
• wakebutton: 是否有唤醒按钮可用
• stt: 可能设置见上文
• tts: 可能设置见上文
• language: STT 和 TTS 处理的语言
• path.base: 支持文件安装的目录
• path.sound.detection: 检测开始时播放的音频文件，相对于 data_base_dir
• path.sound.problem: 发生一般错误时播放的音频文件，相对于 data_base_dir
• path.sound.error.recognition: 检测出错时播放的音频文件，相对于 data_base_dir
• path.sound.error.timeout: 等待语音指令超时时播放的音频文件
• path.flite_speech: flitevox 语音文件，相对于 data_base_dir
• hotword.engine: 可能设置见上文
• hotword.model: （如果 hotword.engine = Snowboy）选择唤醒词的模型文件
• susi.mode: 访问 accounts.susi.ai 的模式，可以是 anonymous 或 authenticated
• susi.user: （如果 susi.mode = authenticated）要使用的用户名（邮箱）
• susi.pass: （如果 susi.mode = authenticated）要使用的密码
• roomname: 房间的自由描述
• watson.stt.user, watson.stt.pass, watson.tts.user, watson.tts.pass: IBM/Watson 服务器用于 TTS 和 STT 的凭据
• watson.tts.voice: 为 IBM/Watson TTS 选择的语音名称
• bing.api: Bing STT API 密钥

有关在 RaspberryPi 上安装、设置和操作的详细信息，请参阅 SUSI Installer 文档。

开发者信息

本节面向开发者。

重要： 发布新版本前的测试

1. 唤醒词检测应具有合理的准确率
2. SUSI Linux 在从在线切换到离线以及反之切换时不应崩溃（目前此功能失败）
3. 当没有互联网连接时，SUSI Linux 应能够离线启动（目前此功能失败）

路线图

• 离线语音检测（如果可能且结果令人满意）

SUSI 的一般工作原理

• SUSI.AI 的代码架构遵循有限状态系统。
• 默认使用 Google TTS 和 STT 服务，但如果互联网失败，会自动切换到离线服务 PocketSphinx（STT）和 Flite（TTS）

为开发目的运行 SUSI Linux

如果通过 SUSI Installer 安装，则会安装 systemd 单元文件：

• ss-susi-linux.service 用于用户总线，以用户身份使用 systemctl --user start/enable ss-susi-linux
• ss-susi-linux@.service 用于系统总线，以 root 用户身份启动特定用户的任务，与用户是否登录无关：sudo systemctl start/enable ss-susi-linux@USER

默认情况下，它以 生产 模式运行，其中日志消息仅限于 错误 和 警告。 在开发过程中，您可能希望看到更多日志以帮助调试。您可以通过以下两种方式将其切换到“详细”模式：

1. 手动运行

• 通过 sudo systemctl stop ss-susi-linux 停止 systemd 服务
• 使用终端，cd 到 susi_linux 目录并运行

python3 -m susi_linux -v

或者重复 v 以增加详细程度：

python3 -m susi_linux -vv

2. 更改 systemd 运行的命令

• 编辑 /lib/systemd/system/ss-susi-linux.service 并更改 ExecStart 参数中的命令：

ExecStart=/usr/bin/python3 -m susi_linux -v --short-log

• 重新加载 systemd 守护进程：sudo systemctl daemon-reload

• 重启服务：sudo systemctl restart ss-susi-linux

• 现在您可以通过 journalctl 读取日志：

  • journalctl -u ss-susi-linux
  • 或者 journalctl -fu ss-susi-linux 以便在日志持续生成时获取更新。

选项 -v 实际上与第一种方法相同。选项 --short-log 是为了排除一些 journalctl 已经提供的信息。关于 logging 功能的更多信息，请查看此 GitHub 问题。

SUSI.AI Linux 快速上手指南

susi_linux 是一个在 Linux 桌面或无头智能音箱（如树莓派）上运行 SUSI.AI 的开源项目。它支持语音命令采集、语音转文字（STT）、文字转语音（TTS）以及简单的 GTK 界面，旨在让用户在任何地方部署自己的 AI 助手。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐 Ubuntu, Debian 或 Raspberry Pi OS)。
• 硬件: 麦克风、扬声器（或耳机）。
• 依赖组件:
  • Python 3
  • SUSI.AI Server (后端服务，用于处理请求)
  • SUSI.AI API Python Wrapper
• 网络: 初始配置需要联网，部分功能（如离线 STT/TTS）需额外配置。

注意: 官方推荐使用 SUSI Installer 进行自动化安装，以解决大部分依赖问题。

安装步骤

方法一：使用 SUSI Installer（推荐）

这是最简便的安装方式，会自动配置二进制文件和目录结构。

1. 克隆并进入安装器目录：

git clone https://github.com/fossasia/susi_installer.git
cd susi_installer

2. 按照安装器文档执行安装脚本（通常包含自动下载和配置 susi_linux 的逻辑）。
3. 安装完成后，配置文件位于 $HOME/.config/SUSI.AI/config.json。

方法二：手动安装

如果您选择手动安装，需自行配置包装器路径。

1. 克隆项目：

git clone https://github.com/fossasia/susi_linux.git
cd susi_linux

2. 配置 wrapper 目录下的包装器，使其指向正确的安装目录和 config.json 文件位置。
3. 确保 susi_server 正在运行，或者配置为连接云端 API。

基本使用

1. 配置系统

使用命令行工具查询或修改配置：

$HOME/SUSI.AI/bin/susi-config keys

常用配置项说明：

• stt: 语音转文字服务 (例如：google, watson, pocketsphinx)
• tts: 文字转语音服务 (例如：google, flite, watson)
• hotword.engine: 唤醒词引擎 (例如：Snowboy, PocketSphinx)
• language: 处理语言代码

您可以直接运行配置脚本进行修改：

$HOME/SUSI.AI/bin/susi-config

或使用图形界面：

$HOME/SUSI.AI/bin/susi-linux-configure

2. 启动服务

生产模式 (Systemd)

如果是通过安装器安装的，可以使用 systemd 管理：

# 用户模式
systemctl --user start ss-susi-linux

# 系统模式 (root 权限)
sudo systemctl start ss-susi-linux@USER

开发模式 (调试日志)

默认模式下仅显示错误和警告日志。如需查看详细日志以便调试，可切换到“verbose”模式：

方式 A：直接运行 停止服务后，在项目目录下运行：

python3 -m susi_linux -v
# 增加 v 的数量可提高日志详细程度
python3 -m susi_linux -vv

方式 B：修改 Systemd 配置 编辑 /lib/systemd/system/ss-susi-linux.service，修改 ExecStart 参数：

ExecStart=/usr/bin/python3 -m susi_linux -v --short-log

然后重载并重启服务：

sudo systemctl daemon-reload
sudo systemctl restart ss-susi-linux

查看日志：

journalctl -fu ss-susi-linux

3. 切换在线/离线模式

SUSI.AI 默认使用 Google TTS/STT 服务。如果网络断开，系统会自动尝试切换到离线服务（如 PocketSphinx 和 Flite），前提是已在配置中启用相应选项。