Z-Waif二次开发指南:如何修改与扩展你的本地AI女友

原创2026-11-15 12:39:161,848 阅读

Z-Waif二次开发指南:如何修改与扩展你的本地AI女友

Z-Waif 是一款完全本地运行的开源 AI 女友(AI Waifu)项目,支持 VTube Studio 虚拟形象、语音合成、长期记忆与多模块扩展。本指南带你完成 Z-Waif 二次开发:从改人设卡、换模型,到动手添加自定义模块,快速打造属于你的本地AI女友。

为什么 Z-Waif 适合二次开发?

Z-Waif 的设计目标不是"开箱即用的一体化工具",而是把工具和方法交到你手里:它本身是一个前端框架,用 main.py 把 Oobabooga(大模型)、RVC(声音)、Whisper(听写)、VTube Studio(形象)等程序串成一个整体。

这意味着:

  • 配置与代码分离:大量行为由 .env 和 Configurables/ 目录控制,零代码即可定制
  • 模块化解耦:Discord、Minecraft、闹钟、摄像头等能力各自独立成文件,可自由开关
  • 完全本地开源:所有数据留在本机,可自由修改,源码即文档

如果你只是普通用户,先看"零代码改造"部分;想真正扩展功能,直接跳到"动手改代码"部分。

快速认识项目结构

建议先克隆仓库到本地再动手:

git clone https://gitcode.com/gh_mirrors/zw/z-waif

核心目录速览(详细项目介绍见 README.md):

目录/文件 作用 二次开发关注度
main.py 主循环、消息分发、模块挂载入口 ⭐⭐⭐
.env 全局环境变量:模型、端口、模块开关 ⭐⭐⭐
Configurables/ 人设卡、快捷键、Lorebook 等运行期配置 ⭐⭐⭐
API/ 对接 Oobabooga / Ollama / LMStudio ⭐⭐
utils/ 各功能模块(语音、闹钟、Discord、摄像头等) ⭐⭐
OOBA_Presets/ Oobabooga 模型预设参数 ⭐
requirements.txt Python 依赖清单 ⭐

启动方式很简单:Windows 双击 startup.bat,Linux/macOS 运行 startup.sh,脚本会自动创建虚拟环境并安装依赖。

零代码改造:用 .env 和配置文件定制人设

第一步:修改人设卡(Character Card)

你的 AI 女友"是谁",主要由 Configurables/CharacterCard.yaml 决定。用任意文本编辑器打开它,在 Character Card: 字段下直接写提示词即可,例如名字、性格、口头禅、说话风格。

加载逻辑在 API/character_card.py 中:程序启动时读取该 YAML 文件并注入对话上下文,因此改完文件重启程序即可生效。

第二步:在 .env 中调整性格与能力开关

.env 是 Z-Waif 最核心的配置文件,常用的二次开发项包括:

  • CHAR_NAME:她的名字,会出现在对话与打断指令中
  • API_TYPE:选择大模型后端,支持 Oobabooga、Ollama、LMStudio
  • ZW_OLLAMA_MODEL / ZW_LMSTUDIO_MODEL:指定具体使用的模型,换模型=换"大脑"
  • TOKEN_LIMIT / MESSAGE_PAIR_LIMIT:上下文长度与记忆深度,显存不足时调小
  • MODULE_VTUBE、MODULE_DISCORD、MODULE_ALARM、MODULE_RAG 等:各功能模块的总开关(ON/OFF)

模块开关的读取位置在 main.py 的 run_program() 中,每个 MODULE_* 变量对应 utils/settings.py 里的一个布尔量。

第三步:补充长期记忆 Lorebook

Configurables/Lorebook.json 用于让她"记住"固定知识(比如你俩的纪念日)。格式是 JSON 数组,每一项包含"关键词"、"内容"、"激活条件"三个字段,照着现有条目复制一份修改即可。

进阶定制:换声音、换快捷键、换界面

修改全局快捷键

Configurables/Keybinds.json 是快捷键映射表,结构为 <a href="https://link.gitcode.com/i/bf40cdc30435f775a90095af96b7a03b" target="_blank">"按键", "功能"],例如 RIGHT_ARROW 对应 Next(换一条回复)。想改成鼠标手势或其他键位,直接修改第一个元素即可。绑定逻辑在 [utils/hotkeys.py 中。

更换语音方案

声音由外部 RVC 系统驱动,主程序侧的录音、播放与 VAD 断句逻辑在 utils/voice.py 与 utils/audio.py。替换 RVC 模型即可换声音,而 WHISPER_MODEL(.env 中)决定听写精度与显存占用,低显存可改为 tiny。

调整 WebUI 主题与提示词

WebUI 本身由 utils/web_ui.py(Gradio 实现)提供,启动函数 launch_demo() 以独立线程运行,方便单独修改界面。

动手改代码:扩展一个新模块

理解模块挂载机制

Z-Waif 的多线程架构很清晰:main.py 的 run_program() 中,每个模块都是"开关 + 独立线程"的模式,例如:

  • 闹钟模块:开关为 MODULE_ALARM,启动 utils/alarm.py 的 alarm_loop() 线程
  • Discord 模块:开关为 MODULE_DISCORD,启动 utils/z_waif_discord.py 的 run_z_waif_discord() 线程

消息侧的扩展点在 message_checks()(main.py):每收到一条 AI 回复后,会依次把消息交给 VTube(表情动画)、Minecraft(游戏指令)、游戏控制等模块检查处理。

添加自定义模块的通用步骤

  1. 新建模块文件:在 utils/ 下创建你的功能脚本,写一个可循环运行的入口函数(如 my_feature_loop())
  2. 添加开关:在 utils/settings.py 中定义一个布尔变量,并在 .env 中新增对应的 MODULE_MYFEATURE 变量
  3. 挂载线程:仿照 run_program() 中现有模块的写法,添加开关判断 + threading.Thread 启动代码
  4. (可选)接收消息:若功能需要监听 AI 回复,在 message_checks() 中加一个 if utils.settings.myfeature_enabled: 分支

这种"照葫芦画瓢"式的接入方式,正是 Z-Waif 模块化设计的价值所在——你不需要理解整个主循环,只需找到对应挂载点。

对接不同大模型后端

API/ 目录封装了三种后端:API/oobaooga_api.py、API/ollama_api.py、API/lmstudio_api.py,统一由 API/api_controller.py 调度。想接入其他 OpenAI 兼容服务,按 .env 注释说明配置 HOST_PORT 指向对应端口即可。

调试技巧与常见问题

  • 看日志:运行输出写入 log.txt,startup.sh 支持 --keep-logs 参数追加历史日志
  • 显存不足:调小 TOKEN_LIMIT,把 WHISPER_MODEL 改为 tiny,或将视觉模型 API_TYPE_VISUAL 指向更小的模型
  • 语音断续/卡顿:关闭 API_STREAM_CHATS(.env)通常能解决流式生成的语音毛刺
  • 人设不生效:确认修改的是 Configurables/CharacterCard.yaml 并已重启程序,而不是 Oobabooga 内部的旧角色卡
  • 功能优先级:修改行为时优先改 .env 和 Configurables/ 下的配置,源码改动尽量小而集中,方便后续升级

总结

Z-Waif 二次开发的路径非常平滑:先配置、再换件、后动刀。

  1. 改 Configurables/CharacterCard.yaml 与 .env → 完成 80% 的个性化
  2. 替换模型、声音、快捷键 → 完成 95%
  3. 参照 run_program() 与 message_checks() 的挂载模式 → 扩展全新模块

项目当前仍处于 early access 阶段,README.md 中的 To-Do 列表就是社区路线图。动手改一改,你会发现打造一只真正"懂你"的本地AI女友,并不需要太高的门槛。

登录后查看全文
z-waif