✨ 人格引擎 ✨

用AI驱动的语音、动画和个性，释放你的数字角色潜能！

     

---

Persona Engine 是你打造引人入胜、可交互虚拟形象的一站式工具包！它巧妙地融合了：
🎨 Live2D： 实现富有表现力的实时角色动画。
🧠 大型语言模型（LLMs）： 赋予你的角色独特的语音与个性。
🎤 自动语音识别（ASR）： 理解语音指令与对话。
🗣️ 文本转语音（TTS）： 让你的角色自然发声。
🎭 实时语音克隆（RVC，可选）： 模仿特定的语音特征。

非常适合Vtuber 🎬、动态直播 🎮以及创新虚拟助手应用 🤖。
让我们一起将你的角色栩栩如生地呈现出来吧！ ✨

💖 亲眼见证它的神奇之处！ 💖

来看看 Persona Engine 如何创造数字魔法：

（点击上方图片观看演示！）

再来欣赏一段小片段，看看这位友好的引擎还能做什么：

📜 目录

• 🌸 概述：里面有什么？
• 🚀 入门指南：安装说明
• ✨ 丰富功能！
• ⚙️ 架构 / 工作原理
• 💡 潜在应用场景
• 🤝 贡献
• 🎭 Live2D 集成指南
• 💬 加入我们的社区！
• ❓ 支持与联系

🌸 概述：里面有什么？

Persona Engine 可以聆听你的声音 🎤，借助强大的 AI 语言模型 🧠 进行思考（由你定义的性格引导！），并通过合成语音 🔊 回应（还可选择使用 RVC 进行语音克隆！），同时相应地驱动 Live2D 角色动画 🎭。

它通过 Spout 无缝集成到 OBS Studio 等直播软件中，实现高质量的视觉输出。随附的“Aria”模型经过专门适配，以确保最佳性能，但你也可以集成自己的 Live2D 模型（请参阅 Live2D 集成指南）。

[!重要提示]
当 Persona Engine 与 经过特别微调的大型语言模型（LLM） 一起使用时，才能实现最自然、最贴合角色的互动。该模型经过训练，能够理解引擎特有的交流格式。

尽管你 可以 使用标准的 OpenAI 兼容模型（例如来自 Ollama、Groq 或 OpenAI 的模型），但这需要你在 personality.txt 文件中进行细致的 提示工程。我们在仓库中提供了一个模板文件 (personality_example.txt) 来指导你。

关于如何为标准模型配置 personality.txt 的详细说明至关重要，请参阅 安装指南。

👉 想试用微调后的模型或观看现场演示吗？快来加入我们的 Discord 吧！😊

截图展示！

看它作为桌面好友有多贴心吧！😊


快来看看引擎内部舒适的控制室吧！✨

🚀 入门指南：安装说明

➡️ 请按照详细的 安装与设置指南，完成前置条件的安装、模型下载、配置及引擎运行。 ⬅️

涵盖的关键要求：

• 系统： 核心功能（ASR、TTS、RVC）必须配备支持 CUDA 的 NVIDIA 显卡。
• 软件： .NET 运行时、espeak-ng。
• AI 模型： 下载 Whisper ASR 模型。
• Live2D： 设置你的 Live2D 模型（使用 Aria 或自定义模型）。
• （可选）RVC： 实现实时语音克隆的设置。
• LLM： 配置对你所选 LLM 的访问权限（API 密钥、端点）。
• 直播： 设置 Spout 输出，以便与 OBS 等软件配合使用。
• 配置： 理解 appsettings.json 文件。
• 故障排除： 常见问题及解决方案。

✨ 丰富功能！

• 🎭 Live2D 头像集成：

  • 加载并渲染 Live2D 模型（.model3.json）。
  • 内置特别绑定的“Aria”模型。
  • 支持基于情绪的动画（[EMOTION:name]）和 VBridger 标准的口型同步参数。
  • 提供专门的情绪、空闲和眨眼动画服务。
  • 请参阅详细的 Live2D 集成与绑定指南，了解自定义模型的要求！

• 🧠 AI 驱动的对话：

  • 连接到兼容 OpenAI 的大型语言模型（LLM）API（本地或云端）。
  • 受您的自定义 personality.txt 文件指导。
  • 具有改进的对话上下文和会话管理，使交互更加稳健。
  • 针对可选的特殊微调模型进行了优化（见概述）。

• 🗣️ 语音交互（需要 NVIDIA GPU）：

  • 通过麦克风监听（使用 NAudio/PortAudio）。
  • 使用 Silero VAD 检测语音片段。
  • 使用 Whisper ASR 理解语音（通过 Whisper.NET）。
  • 包含专门的打断检测功能，以更优雅地处理用户打断。
  • 使用小型快速的 Whisper 模型进行打断检测，而使用更大更准确的模型进行转录。

• 🔊 高级文本到语音合成（TTS，需要 NVIDIA GPU）：

  • 复杂的流程：文本规范化 -> 句子分割 -> 音素化 -> ONNX 合成。
  • 使用自定义的 kokoro 语音模型将文本变为生动的声音。
  • 对于未知单词或符号，会回退到 espeak-ng。

• 👤 可选的实时语音克隆（RVC，需要 NVIDIA GPU）：

  • 集成 RVC ONNX 模型。
  • 实时修改 TTS 语音输出，使其听起来像特定的目标声音。
  • 为提升性能，可选择关闭此功能。

• 📜 可定制字幕：

  • 通过 UI 显示口语文本，并提供可配置的样式选项。

• 💬 控制 UI 和聊天查看器：

  • 专用的 UI 窗口用于监控引擎状态。
  • 查看延迟指标（LLM、TTS、音频）。
  • 实时调整 TTS 参数（音高、语速）以及轮盘赌设置。
  • 查看并编辑对话历史。

• 👀 屏幕感知（实验性）：

  • 可选的视觉模块允许 AI“看到”并读取指定应用程序窗口中的文本。

• 🎡 交互式轮盘赌（实验性）：

  • 一个可配置的屏幕上的轮盘赌，用于互动娱乐。

• 📺 流媒体输出（Spout）：

  • 将视觉内容（头像、字幕、轮盘赌）直接发送到 OBS Studio 或其他兼容 Spout 的软件。
  • 使用独立且可配置的 Spout 流，无需捕获窗口！

• 🎶 音频输出：

  • 通过 PortAudio 清晰播放生成的语音。

• ⚙️ 配置：

  • 主要通过 appsettings.json 进行设置（详情请参阅安装指南）。
  • 部分设置可通过控制 UI 进行实时调整。

• 🤬 脏话过滤：

  • 基本关键词列表 + 可选的基于机器学习（ML）的过滤功能，用于 LLM 回答。

⚙️ 架构 / 工作原理

Persona Engine 在一个连续循环中运行，通过以下步骤让您的角色栩栩如生：

1. 聆听： 🎤

   • 麦克风捕捉音频。
   • 语音活动检测器（VAD）识别语音片段。

2. 理解： 👂

   • 一个快速的 Whisper 模型检测潜在的用户打断。
   • 一旦语音结束，更准确的 Whisper 模型会转录完整的发言内容。

3. 情境化（可选）： 👀

   • 如果启用，视觉模块会从指定的应用程序窗口中捕获文本内容。

4. 思考： 🧠

   • 转录后的文本、对话历史、可选的屏幕上下文以及 personality.txt 中的规则会被发送到配置好的大型语言模型（LLM）。

5. 回应： 💬

   • LLM 生成一段文本回复。
   • 该回复可能包含情绪标签（例如 [EMOTION:😊]）或指令。

6. 过滤（可选）： 🤬

   • 回复会经过脏话过滤器检查。

7. 说话： 🔊

   • 文本到语音合成系统（TTS）将过滤后的文本转换成音频。
   • 主要使用 kokoro 语音模型。
   • 对于未知内容，则回退到 espeak-ng。

8. 克隆（可选）： 👤

   • 如果启用了实时语音克隆（RVC），它会实时修改 TTS 音频。
   • 这一过程使用 ONNX 模型来匹配目标语音特征。

9. 动画： 🎭

   • TTS 过程中提取的音素驱动口型同步参数（VBridger 标准）。
   • LLM 回复中的情绪标签会触发相应的 Live2D 表情或动作。
   • 当角色不说话时，会播放空闲动画以保持自然外观。
   • （详情请参阅 Live2D 集成与绑定指南！）

10. 显示：

    • 📜 根据口语文本生成字幕。
    • 📺 动画头像、字幕以及可选的轮盘赌内容会通过专用的 Spout 流发送到 OBS 或其他软件。
    • 🎶 合成的（以及可选克隆的）音频会通过选定的输出设备播放。

11. 循环：

    • 引擎返回到监听状态，准备迎接下一次交互。

💡 潜在应用场景：尽情发挥创意吧！

• 🎬 VTuber 与直播： 创建一个 AI 合作主持人、一个能响应聊天的互动角色，甚至是一个完全由 AI 驱动的 VTuber 角色。
• 🤖 虚拟助手： 打造一个个性化的、会说话的桌面伴侣。
• 🏪 互动信息亭： 开发引人入胜的虚拟导览员，适用于博物馆、展会、零售环境或信息咨询点。
• 🎓 教育工具： 设计一个 AI 语言练习伙伴、一个互动的历史人物问答机器人，或者一位动态的辅导老师。
• 🎮 游戏： 在游戏中实现更具动态性和对话性的非玩家角色（NPC）或伙伴角色。
• 💬 角色聊天机器人： 让用户与他们喜爱的虚构角色进行沉浸式的对话，让这些角色真正“活”起来。

🤝 贡献

我们非常欢迎你的贡献！如果你有改进建议、Bug 修复或新功能的想法，请按照以下步骤操作：

1. 讨论（可选但推荐）： 对于重大更改，请先在 GitHub Issues 上提出讨论。
2. Fork： 将仓库 Fork 到你自己的 GitHub 账号。
3. 分支： 为你的更改创建一个新的功能分支（git checkout -b feature/YourAmazingFeature）。
4. 代码： 进行修改。请尽量遵循现有的代码风格，并在必要时添加注释。
5. 提交： 使用清晰的提交信息提交你的更改（git commit -m '添加一些AmazingFeature'）。
6. 推送： 将你的分支推送到你 Fork 的仓库中（git push origin feature/YourAmazingFeature）。
7. Pull Request： 向原仓库的 main 分支发起 Pull Request。在 PR 中清楚地描述你的更改。

非常感谢你帮助我们让 Persona Engine 变得更好！😊

💬 加入我们的社区！

刚开始使用遇到困难吗？有问题或者绝妙的想法吗？💡 想看实时演示、试用特别微调过的模型，或是直接与 Persona Engine 中的角色聊天吗？在转换 RVC 模型或搭建自己的 Live2D 模型时遇到麻烦了吗？来 Discord 上打个招呼吧！👋

 

你也可以通过 GitHub Issues 报告 Bug 或请求功能。

❓ 支持与联系

• 主要支持与社区： 请加入我们的 Discord 服务器，获取帮助、参与讨论并观看演示。
• Bug 报告与功能请求： 请使用 GitHub Issues。
• 直接联系： 你也可以通过 Twitter/X 联系我们。

[!TIP] 请务必查阅 Live2D 集成与绑定指南，了解如何准备自定义头像。 有关详细的设置步骤，请参阅 安装与设置指南。

handcrafted-persona-engine 快速上手指南

Persona Engine 是一个一体化 toolkit，用于创建具有 AI 驱动语音、动画和个性的交互式虚拟角色。它结合了 Live2D 动画、大语言模型 (LLM)、自动语音识别 (ASR) 和文本转语音 (TTS)，非常适合 VTuber、直播互动及虚拟助手应用。

🌸 环境准备

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

1. 系统要求

• 操作系统: Windows (推荐) 或 Linux。
• GPU (必需): 必须配备支持 CUDA 的 NVIDIA 显卡。核心功能（ASR, TTS, RVC）依赖 GPU 加速。
• 内存: 建议 16GB 或以上。

2. 前置依赖软件

• .NET Runtime: 安装最新版本的 .NET 运行时环境。
• espeak-ng: 用于 TTS 的发音引擎 fallback。
  • Windows: 下载并安装 espeak-ng installer。
  • Linux: sudo apt-get install espeak-ng
• OBS Studio (可选): 如果需要推流或使用 Spout 输出画面，请安装 OBS Studio 并确保安装了 Spout2 插件。

3. AI 模型与配置

• LLM 访问权限: 准备好 OpenAI 兼容的 API Key（如 OpenAI, Groq, 或本地 Ollama 服务地址）。
• Live2D 模型: 项目自带 "Aria" 模型，也可使用自定义 .model3.json 模型。

🚀 安装步骤

1. 获取源码

从 GitHub 下载最新发布的版本或克隆仓库：

git clone https://github.com/fagenorn/handcrafted-persona-engine.git
cd handcrafted-persona-engine

注：国内用户若下载缓慢，可使用镜像源加速：

git clone https://ghp.ci/https://github.com/fagenorn/handcrafted-persona-engine.git
cd handcrafted-persona-engine

或者直接前往 Releases 页面 下载预编译的压缩包并解压。

2. 下载 ASR 模型

引擎需要 Whisper 模型进行语音识别。首次运行时通常会自动下载，若需手动放置，请将 Whisper 模型文件放入指定的 models 目录（具体路径参考 appsettings.json 配置）。

3. 配置文件设置

复制并编辑主配置文件 appsettings.json：

cp appsettings.json.example appsettings.json
# 使用编辑器打开 appsettings.json 进行如下关键配置

关键配置项说明：

• LLM 配置: 填入你的 ApiKey 和 Endpoint。

  "Llm": {
    "Provider": "OpenAI", 
    "ApiKey": "YOUR_API_KEY_HERE",
    "Model": "gpt-4o-mini" 
  }
  

• 人格设定: 编辑 personality.txt 文件。
  • 重要: 如果使用标准大模型（非微调版），必须在此文件中精心编写 Prompt，定义角色的行为准则和输出格式（特别是情感标签 [EMOTION:name]）。参考仓库中的 personality_example.txt。
• Spout 输出: 如果需要使用 OBS，确保 Spout 相关选项启用。

4. 运行引擎

在项目根目录下运行程序：

dotnet run

如果是下载的预编译包，直接运行对应的 .exe (Windows) 或可执行文件。

✨ 基本使用

启动成功后，您将看到控制 UI 窗口，并按以下流程与角色互动：

1. 启动与监控

• 程序启动后，会加载 Live2D 模型（默认为 Aria）。
• 在 Control UI 中，您可以实时监控 LLM 延迟、TTS 状态和音频电平。
• 确保麦克风权限已开启，引擎会通过 Silero VAD 自动检测语音活动。

2. 与角色对话

• 说话: 对着麦克风说话。引擎会自动识别语音结束，将其转录为文本。
• 思考: 文本被发送至 LLM，结合 personality.txt 中的人格设定生成回复。
• 反馈:
  • 视觉: 角色会根据回复内容做出表情（如 [EMOTION:happy]）和口型同步动画。
  • 听觉: 通过 TTS (Kokoro 模型) 播放语音，若开启了 RVC，声音会被克隆为特定音色。
  • 推流: 画面和字幕会通过 Spout 自动发送到 OBS（需在 OBS 中添加 "Spout2 Capture" 源）。

3. 简单示例场景

假设您想创建一个简单的桌面陪伴助手：

1. 修改 personality.txt，设定角色为一个“热情友好的桌面小助手”。
2. 运行 dotnet run。
3. 对着麦克风说：“你好，今天天气怎么样？”
4. 观察屏幕上的 Live2D 角色眨眼、微笑，并听到它用合成的声音回答您，同时屏幕上显示字幕。

4. 进阶调整

• 更换模型: 将您的 Live2D 模型文件放入指定文件夹，并在配置中指向新的 .model3.json 路径（详见 Live2D.md）。
• 开启变声 (RVC): 在 appsettings.json 中启用 RVC 模块并加载对应的 ONNX 模型，即可让角色拥有特定的声音特征。
• 屏幕感知: 启用 Vision 模块，让 AI 能够“看到”并读取您指定窗口中的文字内容。

提示: 为了获得最佳体验，强烈建议加入项目的 Discord 社区获取微调后的 LLM 模型推荐及更多配置模板。