Z-Waif二次开发指南:如何修改与扩展你的本地AI女友
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、LMStudioZW_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 主题与提示词
- 界面配色:Configurables/GradioThemeColor.json
- 等待回复时的"垫话":Configurables/Chatpops.json
- 生成模型行为边界:Configurables/StoppingStrings.json
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(游戏指令)、游戏控制等模块检查处理。
添加自定义模块的通用步骤
- 新建模块文件:在
utils/下创建你的功能脚本,写一个可循环运行的入口函数(如my_feature_loop()) - 添加开关:在 utils/settings.py 中定义一个布尔变量,并在 .env 中新增对应的
MODULE_MYFEATURE变量 - 挂载线程:仿照
run_program()中现有模块的写法,添加开关判断 +threading.Thread启动代码 - (可选)接收消息:若功能需要监听 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 二次开发的路径非常平滑:先配置、再换件、后动刀。
- 改 Configurables/CharacterCard.yaml 与 .env → 完成 80% 的个性化
- 替换模型、声音、快捷键 → 完成 95%
- 参照
run_program()与message_checks()的挂载模式 → 扩展全新模块
项目当前仍处于 early access 阶段,README.md 中的 To-Do 列表就是社区路线图。动手改一改,你会发现打造一只真正"懂你"的本地AI女友,并不需要太高的门槛。