语音助手伊琳娜

伊琳娜是一款可在离线状态下运行的俄语语音助手。需要 Python 3.5 或更高版本（依赖项可能更低，但无论如何都需要 Python 3）。

支持插件（技能）。

Хабр文章 | 第二篇 Хабр 文章 | 第三篇 Хабр 文章 | 第四篇 Хабр 文章 - 关于第 12 版和 AI 插件 | Telegram 群组

通过作者伊琳娜的另一个项目 VseGPT.ru：

• 支持与 ChatGPT、GPT-4、Claude 3 对话。
• 支持使用 Perplexity Online 特殊模型从互联网获取参考信息（“帮助”指令）。
• 支持 OpenAI 的 TTS 功能（如果本地安装有困难）。 (插件设置说明)。（也可以使用任何兼容 OpenAI 的 API 端点）

安装

Windows 下最快的安装方式

访问 https://github.com/janvarev/Irene-VA-win-installer，下载代码（Code/Download ZIP），并按照说明操作。

安装完成后，将可以使用以下命令：“伊琳娜你好”、“伊琳娜抛硬币”、“伊琳娜掷骰子”、“伊琳娜猜大小游戏”、“伊琳娜三分钟计时器”。

如需进一步调整或解决问题，请运行 start-settings-manager.bat 启动设置管理器——您可以在其中调整插件，并了解其他可用命令。

关于此方案的更多配置文档：docs/INSTALL_WIN_COMPACT.md

Windows 下最快的安装方式 2（已过时）

1. 访问发布页面：https://github.com/janvarev/Irene-Voice-Assistant/releases
2. 下载发布包并按照说明操作。Python 和 GIT 已包含在发布包中，无需额外安装。

安装完成后，将提供离线命令（因为这是默认配置）。例如：“伊琳娜你好”、“伊琳娜抛硬币”、“伊琳娜掷骰子”、“伊琳娜猜大小游戏”、“伊琳娜三分钟计时器”。

如何进一步配置此方案：docs/INSTALL_WIN_COMPACT.md

安装 / 快速启动

您需要已安装的 Python（大致为 3.7–3.11）。

1. 要快速安装所有必需的依赖项，可以使用以下命令：

pip install -r requirements.txt

如果您希望安装经过验证的固定版本的依赖项以获得更稳定的工作效果，请使用： pip install -r requirements_fixed.txt

（对于 Linux 和 macOS，请预先安装 audioplayer 所需的软件包）

2. 要启动程序，请运行根目录下的 runva_vosk.py 文件。 默认情况下，它将启动离线语音识别引擎 Vosk 来识别麦克风中的语音， 以及 pyttsx 引擎来为助手配音。 关于 pyttsx 的更多信息请参见此处。

3. 启动后，可以通过简单的命令进行测试——对着麦克风说“伊琳娜，你好！”

首次启动伊琳娜后，将会出现 options 配置文件夹，您可以在其中调整设置。

关于在 Windows 上安装的更详细步骤（尤其是 Windows 7）：docs/INSTALL_WIN.md

关于在 Linux 上安装时遇到的一些问题的解决方案：docs/INSTALL_LINUX.md

关于在 Mac 上安装时遇到的一些问题的解决方案：docs/INSTALL_MAC.md

关于安装过程中出现问题时的调试原则：docs/INSTALL_DEBUG.md

如有错误，请提交至 ISSUES，讨论请加入 Telegram 群组。

设置管理器

自 9.0 版本起，可通过 Gradio 提供基于 Web 的设置管理器。

要启动管理器，请运行根目录下的 runva_settings_manager.py 文件。

AI 插件

自 12.0 版本开始的测试版

- 伊琳娜，帮我设置一个两小时半的计时器
- 我已经设置了 2 小时 30 分钟的计时器

AI 插件允许通过自由格式的文本调用功能。 实现方式是利用 LLM 的 tools 调用功能，详情请参阅 https://vsegpt.ru/Docs/API#tools。简单来说，就是调用像 ChatGPT 这样的大型语言模型，并根据我们提供的自由格式输入，让模型判断应该调用哪个插件以及具体的参数。

您需要具备访问 LLM 的权限：

• 格式应为 OpenAI 兼容
• 并且支持 tools 调用功能

对于远程使用场景，您可以借助作者的项目 https://vsegpt.ru/ ——那里提供了快速的 LLM（OpenAI gpt-4o-mini 等），它们对此类功能的支持较好。每次调用模型都会产生费用，但通常仅需几分钱即可使用默认配置的 openai/gpt-4o-mini。此外，还有一个价值几卢布的免费演示，足以让您试用。

您也可以使用本地的 LMStudio 或 Ollama，搭配支持 tools 功能的模型。这种方式可能会稍慢一些，但同样可行。有兴趣的用户可以编写相关说明，并将其放入本项目的文档中。

要使 AI 插件正常工作，您需要：

1. 在 core 中设置连接到模型的参数，以及插件列表——例如，“ai”。
2. 如果希望 AI 插件与普通插件协同工作，则使用“classic,ai”。优先级始终是普通插件。

"plugin_types": "default", # 允许的插件类型列表，用逗号分隔，
# 例如：classic, ai，或者 "classic,ai"

"openai_base_url": "https://api.vsegpt.ru/v1",
"openai_key": "",
"openai_tools_model": "openai/gpt-4o-mini",
"openai_tools_system_prompt": "",
"openai_generic_model": "openai/gpt-4o-mini",
"openai_generic_system_prompt": "",

其次，您还需要 AI 插件。 可以从 plugins_inactive 文件夹中复制 demo 插件 plugin_ai_timer。

目前这还处于爱好者阶段，相关信息较少，后续会提供更多细节

使用 Docker 安装

如果您想通过 Docker 启动整个系统：docs/INSTALL_DOCKER.md（其中也包含 Ivan-Firefly 提供的适用于 ARM 架构（如树莓派等）的 Docker 镜像）。

如果您只想通过 Docker 启动复杂的组件：docs/INSTALL_DOCKER_COMP.md

总体逻辑

所有命令的触发都始于助手的名字（可在 options/core.json 中设置，默认为“伊琳娜”）。这样做是为了避免在持续监听麦克风时误触发。接下来描述的命令均不带“伊琳娜”前缀。

该引擎内置了通过 MPC-HC 播放器的本地 Web 界面控制功能，因此在条件允许的情况下，建议使用它。您可以在 options/core.json 中进行配置。

插件

插件支持由自主开发的 Jaa.py 引擎提供——这是一个极简的一文件插件及其设置管理引擎。

插件位于 plugins 文件夹中，且必须以“plugins_”作为前缀。

如果有插件设置，它们将存储在“options”文件夹中（首次启动后创建）。

现成插件/技能（已位于plugins文件夹中）

每个插件都注明是否需要在线连接。 如需禁用，请将其从plugins文件夹中删除。

完整信息：docs/PLUGINS.md

第三方插件

如果您想了解：

• 还有哪些来自其他开发者的插件
• 或者发布您自己开发的插件链接

请访问：https://github.com/janvarev/Irene-Voice-Assistant/issues/1

插件管理器

（自10.0.0版本起） 要启动它，请运行runva_plugin_installer.py。

注意： 推荐的插件由第三方开发者维护，可能会不断更新和修改！伊琳娜的作者对其内容不承担任何责任！

面向开发者：如果您希望将自己的插件加入此列表以便于安装，您需要执行以下步骤：

1. 将插件托管在GitHub上。
2. 根目录下应包含类似plugin_x.py的文件，可以有多个。
3. 如果需要安装额外的依赖模块，则需放置requirements.txt文件。
4. 测试安装功能，运行runva_plugin_installer，选择选项0（手动指定插件的GitHub项目地址），并安装您的插件。
5. 完成后，请在Issue中发布您的链接，或通过修改plugins_catalog.json文件提交Pull Request，该文件包含了已知插件的链接。

插件示例：https://github.com/janvarev/irene_plugin_boltalka2_openai

与Home Assistant集成

有一个优秀的第三方插件，允许通过伊琳娜触发Home Assistant场景： https://github.com/timhok/IreneVA-hassio-script-trigger-plugin

核心配置（core.json）

具体插件的设置建议直接查看相应插件的文档。

{
    "contextDefaultDuration": 10, # 伊琳娜保持上下文状态的时间（以秒为单位）。上下文用于连续对话、游戏等场景；在上下文中无需再次提及“伊琳娜”。
    "contextRemoteWaitForCall": false, # 伊琳娜是否应等待客户端发出“回复播放结束，开始计算上下文时间”的信号？
    "contextExitCommand": "", # 用于提前退出上下文状态的指令（若为空，则仅在超时后自动退出） 
    # 官方客户端支持contextRemoteWaitForCall，建议设置为true。
    "fuzzyThreshold": 0.5, # （高级）使用模糊命令识别插件时的置信度阈值。
    "isOnline": true, # 设置为false时，会针对需要在线的插件命令返回占位响应。如果仅需离线模式，建议启用。
    "linguaFrancaLang": "ru", # 用于将数字转换为通用语言的语种。若使用其他语种，请更改。
    "logPolicy": "cmd", # all|cmd|none。当麦克风检测到语音时，是始终输出日志、仅在识别为命令时输出，还是完全不输出？
    "mpcHcPath": "C:\\Program Files (x86)\\K-Lite Codec Pack\\MPC-HC64\\mpc-hc64_nvo.exe", # 如果使用MPC HC，则填写其路径。
    "mpcIsUse": true, # 是否使用MPC HC？
    "mpcIsUseHttpRemote": true, # MPC HC是否启用了Web界面远程控制？
    "playWavEngineId": "audioplayer", # 用于播放WAV文件的插件。部分WAV文件可能需要sounddevice库支持。
    "replyNoCommandFound": "对不起，我没听懂", # 当无法理解用户指令时的回复。
    "replyNoCommandFoundInContext": "没明白...", # 在上下文状态下无法理解时的回复。
    "replyOnlineRequired": "需要在线", # 当调用要求在线的插件功能时的回复。
    "tempDir": "temp", # 临时文件存储目录。
    "ttsEngineId": "pyttsx", # 当前使用的TTS引擎。
    "ttsEngineId2": "", # 第二个使用的TTS引擎。仅适用于本地语音合成，例如剪贴板朗读。可通过say2命令调用。
    "useTTSCache": false, # 若设置为true，生成的TTS回复音频文件将被缓存在tts_cache文件夹中。
    "v": "1.7", # 核心插件版本。会自动更新，无需手动修改。
    "voiceAssNames": "伊琳娜|伊琳娜的|给伊琳娜", # 如果语音流中出现这些称呼，则后续内容被视为指令。（助手的不同称呼，建议设置多个。）
    "voiceAssNameRunCmd": { # 如果用户以这些名称呼唤助手，系统会在其指令前自动添加相应的助词。
        "阿尔比娜": "ChatGPT"
    },
    "log_console": True,  # 输出日志到控制台。
    "log_console_level": "WARNING",
    # 只有达到或高于此级别的消息才会被记录：NOTSET | DEBUG | INFO | WARNING | ERROR | CRITICAL。
    "log_file": False,  # 输出日志到文件。
    "log_file_level": "DEBUG",  # NOTSET | DEBUG | INFO | WARNING | ERROR | CRITICAL。
    "log_file_name": "log.txt",  # 日志文件名。

    "normalization_engine": "numbers", # 针对俄语TTS的文本规范化处理。
    # 规范化可将“1, 2, 3”转换为“一、二、三”，这对于不了解数字的VOSK TTS等引擎尤为重要。
    # 此功能由插件实现。推荐使用runorm以获得更好的效果（但runorm处理起来较慢）。
    # 协议规定：每个TTS插件自行决定是否需要预处理。
    # 如需预处理，可调用core.normalize(text_to_speech)，详见plugin_tts_vosk.py中的示例。
  
}

调试与开发（面向开发者）

调试时，可以使用runva_cmdline.py文件来启动系统。

该文件通过命令行界面启动核心（vacore.py中的VACore），相比语音输入更为便捷。

• 您可以通过在**plugins_**目录下创建插件来接入自己的技能。请参考现有示例。
• 您也可以通过插件接入自己的TTS引擎。例如，可参考plugins_tts_console.py和plugins_tts_pyttsx.py。
• 此外，您还可以创建自己的**runva_**文件，根据需求接入自定义的语音转文本引擎。

日志记录

日志记录通过 core.py 模块中的 logging 库实现。

参数在 options/core.json 中设置：

• 如果 log_console=True，则输出到控制台
• 如果 log_file=True，则输出到日志文件

默认值：

• log_console=True
• log_file=False
• log_console_level="WARNING"
• log_file_level="DEBUG"
• log_file_name="log.txt"

日志级别：

• NOTSET = 0
• DEBUG = 10
• INFO = 20
• WARNING = 30
• ERROR = 40
• CRITICAL = 50

默认情况下，日志会以 WARNING 级别输出到控制台，以 DEBUG 级别输出到日志文件。 这意味着所有设置为该级别及更高（更大）级别的消息都会被记录到日志中。 例如，如果设置为 WARNING 级别，则 WARNING、ERROR 和 CRITICAL 级别的消息都会被记录；如果设置为 DEBUG 级别，则 DEBUG、INFO、WARNING、ERROR 和 CRITICAL 级别的消息都会被记录。

推荐用法： 在模块开头，在所有导入语句之后添加以下行：

import logging

logger = logging.getLogger(__name__)

通过调用相应函数将事件添加到日志中：

logger.debug("调试信息")  # 用于调试时的详细信息
logger.info("信息性消息")  # 当一切按计划进行时的信息性消息
logger.warning("警告信息")  # 当出现问题但工作仍在继续时的警告
logger.error("错误信息")  # 用于报告错误和功能损失的消息
logger.critical("严重错误信息")  # 用于报告无法继续工作的严重错误

在 try/except 块中输出日志时，可以使用以下结构：

try:
  ...
except Exception as e:
  logger.exception(e)

或者这样：

try:
  import some_library
except ImportError as e:
  logger.exception(e)
  logger.error("未安装 'some_library' 库。请使用 'pip install some_library' 进行安装")

建议采用后一种方式，以便处理特定异常，而不是整个 Exception 类。 使用 logger.exception(e) 可确保输出堆栈跟踪信息。

插件开发

开发文档

远程工作（客户端-服务器、多麦克风/多机器部署）

多机“客户端-服务器”模式稍显复杂，但允许从多个方面管理伊琳娜：

• 使用多个麦克风
• 在不同机器上操作
• 通过 Telegram（借助 Telegram 机器人）

关于配置客户端-服务器模式的更多信息

WEB API 文档

通过 VOSK remote 进行语音转文本

如果您在安装 VOSK 时遇到问题（例如在 Mac 上），可以使用通过 Docker 启动的 VOSK 自动语音识别服务器。

• 运行 docker run -d -p 2700:2700 alphacep/kaldi-ru:latest （详情：https://alphacephei.com/vosk/server）
  • 或者，您也可以运行 vosk_asr_server.py，并在其中重新定义参数：

    args.interface = os.environ.get('VOSK_SERVER_INTERFACE', "0.0.0.0")
    args.port = int(os.environ.get('VOSK_SERVER_PORT', 2700))

• 运行 runva_voskrem.py。它将从麦克风读取数据并发送到服务器进行识别。

如果需要在另一台机器上启动识别， 请使用 -u 参数（--uri）：runva_voskrem.py -u=ws://100.100.100.100:2700 以指定服务器地址。

通过 SpeechRecognition 进行语音转文本

SpeechRecognition 是一个经典的引擎，可通过 Google 及其他一些服务启动语音识别。 要启动此识别，请通过文件 runva_speechrecognition.py 运行系统。

所需依赖：

pip install PyAudio

pip install SpeechRecognition

如果在安装 PyAudio 时遇到问题，请参阅 EnjiRouz 的说明。

特点：数字的识别。同样的短语会被识别为：

• VOSK：计时器十秒钟
• SpeechRecognition（Google）：计时器10秒

多语言支持

该项目整体并不预设多语言支持，因为它在插件中使用自定义的单词解析。 然而，核心部分（vacore.py）完全与语言无关，您可以仅需重写插件即可用其他语言构建自己的安装版本。

若干用于定义核心语言助手行为的语言短语（其名称以及“我不明白”之类的短语）可在插件 core 的配置文件中进行设置。

不精确的短语处理

自版本 7.5 起，支持对用户输入进行不精确处理。

用于设定识别阈值的是 core.json 中的全局参数 fuzzyThreshold， 其取值范围为 0 到 1（1 表示对短语有完全的把握）。

已知支持此功能的插件包括：

• https://github.com/janvarev/irene_plugin_fuzzy_thefuzz - 通过 thefuzz 进行字符串模糊比较
• https://github.com/modos189/irene_plugin_fuzzy_sklearn - 通过 scikit-learn
• https://github.com/janvarev/irene_plugin_fuzzy_ai_sentence - 基于神经网络的语义字符串比较（sentence_transformers）

来自语音助手瓦西苏阿利的插件

自版本 8.1 起，在测试模式下增加了对语音助手瓦西的核心插件的支持： https://github.com/Oknolaz/vasisualy

添加步骤：

1. 插件应放入 plugins_vasi/skills 目录中（可从 https://github.com/Oknolaz/vasisualy/tree/master/vasisualy/skills 获取）。
2. 每个插件的模块中都应包含 triggers，以此生成命令列表。若无，则需对该插件进行改进。

目前在最简单的情况下运行正常——已在 coin 和 crystall_ball 插件上进行了测试。 若无法正常工作，请查看代码。支持是通过 plugin_vasi.py 插件实现的。

贡献

如果您想为项目做出贡献，建议仔细阅读 CONTRIBUTING.md 政策。

简而言之：

• 建议为插件创建独立的 GitHub 项目（或将其放置在其他地方），并且您愿意持续维护这些项目。可以将链接提交至 https://github.com/janvarev/Irene-Voice-Assistant/issues/1，以便他人发现您的插件。无需将额外的插件直接添加到本项目中——我没有时间和精力去维护我不熟悉的领域。
• 请进行有针对性的更改，以改善功能或修复错误（例如在某些条件下无法正常工作）。此类 Pull Request 很有可能被接受。
• 大规模的代码更改（如统一代码风格、整理导入语句）将不会被考虑，并会被拒绝。请勿进行此类更改。

致谢

@EnjiRouz 对其语音助手项目的贡献：https://github.com/EnjiRouz/Voice-Assistant-App，该项目成为了本项目的基础（尽管经过了大量修改）。

AlphaCephei 对出色的 Vosk 语音识别库的贡献（https://alphacephei.com/vosk/index.ru）

项目支持

开源项目中最主要的难点，并不是编写代码——编写代码其实挺有趣的。

真正的难点在于，如何长期维护代码和用户社区。

比如回答问题、修复漏洞、撰写文章和文档等。

如果您希望支持我的工作热情，让伊琳娜这位独立于大型公司的语音助手能够持续得到维护和发展，您可以：

• 编写一个新的插件（这总是让我非常高兴！）
• 通过订阅方式捐赠一些资金：https://boosty.to/irene-voice。订阅者越多，我就越能感受到这个项目是有价值的。
• 向他人介绍伊琳娜，或者帮助他们完成安装与配置。
• 只需在本讨论帖中简单地说声“谢谢”：https://github.com/janvarev/Irene-Voice-Assistant/issues/12

Irene 语音助手快速上手指南

Irene 是一款支持离线运行的俄语语音助手，基于 Python 开发，支持插件扩展及大语言模型（LLM）集成。

环境准备

• 操作系统：Windows (推荐), Linux, macOS
• Python 版本：Python 3.7 - 3.11 (最低要求 3.5+)
• 系统依赖：
  • Linux/macOS：需预先安装 audioplayer 相关的系统包。
  • Windows：推荐使用官方提供的整合包，无需手动配置环境。
• 网络需求：基础离线功能无需联网；若使用 AI 插件或在线技能需访问互联网。

安装步骤

方案一：Windows 快速安装（推荐）

这是最简单的部署方式，内置了 Python 和 Git，无需手动配置环境变量。

1. 访问发布页：https://github.com/janvarev/Irene-Voice-Assistant/releases
2. 下载最新的 Release 压缩包并解压。
3. 运行目录中的启动脚本（通常为 runva_vosk.py 或通过安装包生成的快捷方式）。
4. 如需高级配置，运行 start-settings-manager.bat 打开设置管理器。

方案二：通用源码安装 (pip)

适用于所有平台或需要自定义开发的场景。

1. 克隆项目或下载源码至本地目录。

2. 安装依赖库： 打开终端，进入项目根目录，执行以下命令安装最新依赖：

   pip install -r requirements.txt
   

   注：若追求稳定性，可使用固定版本依赖：

   pip install -r requirements_fixed.txt
   

   (国内用户如遇下载慢，可添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 使用清华镜像源)

3. 首次运行： 执行主程序文件：

   python runva_vosk.py
   

   说明：默认使用 vosk 进行离线语音识别，使用 pyttsx3 进行语音合成。

4. 配置生成： 首次运行后，根目录下会自动生成 options 文件夹，内含 core.json 等配置文件，可根据需求修改参数。

基本使用

1. 唤醒助手： 默认唤醒词为 "Ирина" (伊琳娜)。对着麦克风说出唤醒词即可激活监听。

2. 基础指令示例： 激活后，可直接下达以下指令（需使用俄语发音）：

   • Ирина, привет! (你好)
   • Ирина, подбрось монетку (抛硬币)
   • Ирина, подбрось кубик (掷骰子)
   • Ирина, таймер три минуты (设置 3 分钟计时器)
   • Ирина, игра больше меньше (开始“猜大小”游戏)

3. 进阶功能 (AI 插件)： 若需使用自然语言调用复杂功能（如“设置两个半小时的计时器”），需配置 LLM 接口：

   • 编辑 options/core.json，配置 openai_base_url 和 openai_key。
   • 将 plugin_types 设置为 "classic,ai"。
   • 将 plugins_inactive/plugin_ai_timer 移至 plugins 文件夹启用。
   • 支持接入 OpenAI 兼容接口（如 VseGPT.ru、Local LMStudio/Ollama 等）。

4. 设置管理： 运行以下命令启动基于 Web 的图形化设置界面（需 Gradio 支持）：

   python runva_settings_manager.py