本地AI虚拟女友Z-Waif完全指南:免费打造你的专属AI伴侣
本地AI虚拟女友Z-Waif完全指南:免费打造你的专属AI伴侣
Z-Waif 是一款完全本地运行的开源 AI 虚拟女友(AI Waifu)项目,让你免费打造专属 AI 伴侣:它把 VTube Studio 虚拟形象、RVC 语音合成、Whisper 语音识别和自研 RAG 长期记忆整合为一个整体,在 Windows、Mac、Linux 上 100% 离线对话,不依赖任何云端 API,隐私和数据完全掌握在自己手里。本文是一份面向新手的完整教程:硬件要求、一键安装步骤、核心配置参数和日常玩法,照着做即可拥有自己的本地 AI 虚拟女友。
🤖 Z-Waif 是什么?为什么选择本地 AI 伴侣
Z-Waif 的定位不是"开箱即用的黑盒",而是把多个免费开源 AI 工具串成一条完整链路的前端程序:
- Oobabooga(text-generation-webui)作为大模型加载器,负责"大脑"
- Whisper 负责语音转文字(你说的话 → 文本)
- RVC 负责文字转语音(她的回答 → 声音),可挑选数千种音色模型
- VTube Studio 负责虚拟形象,表情、动作、眼动全部联动
这意味着你不用写一行胶水代码,也不用付费订阅任何 AI 服务,所有软件免费(或极低成本)。
硬件要求一览
| 配置项 | 推荐 | 最低要求 |
|---|---|---|
| 系统 | Windows 10/11 | Mac / Linux 也已支持 |
| GPU | NVIDIA(CUDA),16GB+ 显存 | 任意品牌(AMD/NVIDIA/Intel),8GB+ 显存 |
| 软件 | Python 3.11、Git | 同左 |
✨ 核心功能一览:你的 AI 虚拟女友能做什么
Z-Waif 采用模块化设计,所有功能都可以通过 .env 中的 MODULE_* 开关自由组合:
| 功能 | 说明 | 相关模块路径 |
|---|---|---|
| 🎙️ 语音对话 | Whisper 实时转录 + RVC 语音回复,支持流式响应降低延迟 | utils/audio.py、utils/voice.py |
| 🍄 Vtuber 形象 | 接入 VTube Studio,根据对话内容发送 emote 表情,含待机/说话动画、眼睛追踪 | utils/vtube_studio.py |
| 💾 长期记忆 | 自研 RAG 记忆库 + Lorebook 知识库 + 滚动摘要,聊得越久越懂你 | utils/based_rag.py、utils/lorebook.py |
| 👁️ 视觉能力 | 多模态模型,让她通过摄像头"看见"你(支持屏幕截图模式) | utils/camera.py |
| 💬 Discord 消息 | 在 Discord 频道里和她聊天,支持 /help、/reroll 等命令 | utils/z_waif_discord.py |
| ⛏️ Minecraft | 通过 Baritone、Wurst 等模组让她在游戏里操控、互动 | utils/minecraft.py |
| ⏰ 闹钟唤醒 | 设定时间后她会主动说话叫醒你,可自定义台词 | utils/alarm.py |
| 🖥️ WebUI | 内置 Gradio 网页界面,浏览器里直接对话、控制各项设置 | utils/web_ui.py(端口 7864) |
| ⌨️ 热键 | 全套键盘快捷键,边聊边操作不打断 | utils/hotkeys.py |
🚀 一键安装步骤:从克隆到首次运行
第 1 步:准备环境
确认系统安装了 Python 3.11(版本严格匹配,脚本会自动检查)和 Git。
第 2 步:克隆仓库
git clone https://gitcode.com/gh_mirrors/zw/z-waif
第 3 步:安装依赖并启动
- Windows:双击 startup-Install.bat 完成首次安装(自动创建虚拟环境、安装 PyTorch/CUDA 版、Whisper 及 requirements.txt 依赖;若安装失败会自动进入二阶段强制修复),之后日常启动用 startup.bat 即可。
- Mac / Linux:在终端执行
bash startup.sh,首次会自动创建venv并安装全部依赖;可用--help查看全部参数(如--reinstall重装依赖、--keep-logs保留日志)。
第 4 步:配置大模型后端
Z-Waif 本身不含大模型,需要搭配加载器(三选一):
- Oobabooga(默认推荐):启动 text-generation-webui,把
OOBA_Presets/目录下的 Z-Waif 预设导入使用,例如 OOBA_Presets/Z-Waif-ADEF-Standard.yaml(另提供 Blazing / Tempered 等不同"性格强度"的采样参数) - Ollama:服务端模式运行,模型名在
.env的ZW_OLLAMA_MODEL中修改 - LMStudio:v1.15 起支持,配置风格与 Ollama 类似
第 5 步:跑起来
确认 .env 中 HOST_PORT 指向你的加载器地址后,启动程序,浏览器打开 127.0.0.1:7864 即可进入 WebUI 开始对话。
⚙️ 核心配置详解:.env 文件的关键参数
所有核心开关都在 .env 文件中,以下是新手最关心的几组参数:
基本身份
| 参数 | 作用 |
|---|---|
CHAR_NAME |
她的名字,用于对话唤醒和显示 |
CHARACTER_CARD |
Oobabooga 中对应的角色卡名称 |
YOUR_NAME |
你(用户)的名字,写进角色卡时使用的 |
API_TYPE |
模型后端:Oobabooga / Ollama / LMStudio |
HOST_PORT |
主模型地址,默认 127.0.0.1:5000 |
WHISPER_MODEL |
语音识别模型:tiny / base / small(显存紧张选 tiny.en) |
功能模块开关
MODULE_VTUBE、MODULE_RAG、MODULE_DISCORD、MODULE_VISUAL、MODULE_ALARM、MODULE_MINECRAFT、MODULE_GAMING 均为 ON/OFF,按需开启即可。建议先聊几天再打开 MODULE_RAG,等积累出对话历史后开启,记忆效果最佳。
记忆与摘要
| 参数 | 作用 |
|---|---|
USE_ROLLING_SUMMARIES |
滚动摘要开关:每积累一定轮次自动总结历史,避免上下文被截断 |
SEARCH_POINT_SIZE |
摘要覆盖的对话轮次(4k–6k 上下文推荐 10) |
TOKEN_LIMIT |
最大上下文长度,越大越吃显存 |
SILERO_VAD |
语音活动检测,比纯音量判定更准确(v1.12 加入) |
🎨 个性化定制:角色卡、Lorebook 与记忆
想让"她"真正专属,改这三个地方就够:
- 角色卡:Configurables/CharacterCard.yaml 定义她的性格、说话风格与背景设定,这是 AI 伴侣"灵魂"的所在。
- Lorebook 知识库:Configurables/Lorebook.json 以"关键词 → 背景描述"的形式注入信息。例如记下你的生日、喜好、你们的故事,当对话中出现关键词时自动激活,永不遗忘。
- 快捷键与台词:Configurables/Keybinds.json 自定义热键;Configurables/AlarmMessage.json 自定义闹钟台词。
数据安全:自动备份
程序会在启动时和每 8 条消息后各生成一次备份到 Backups/ 目录;日常对话存于 LiveLog.json,摘要存于 LiveSummaryLog.json。从其他软件迁移旧聊天记录?把日志文件丢进 Logs/Drop_Converts_Here/ 即可自动转换导入。
⌨️ 日常使用技巧:常用快捷键速查
| 按键(默认) | 功能 |
|---|---|
→ 右方向键 |
重新生成(Next) |
↑ 上方向键 |
撤销上一条(Undo) |
A |
自动聊天开关(免按键持续对话) |
S |
调节自动聊天灵敏度 |
右键 Ctrl |
语音开关 |
C |
查看图片(让她看摄像头画面) |
X |
取消图片 |
` |
输入锁 |
💡 小贴士:对话中喊她的名字可以打断她的说话(Hangout 模式下的可中断对话);开启 API_STREAM_CHATS 流式输出后,程序会在等待生成时先说"嗯…"这类垫话(Chatpops,配置见 Configurables/Chatpops.json),显著降低"她卡住了"的错觉。
🛠️ 常见问题排查(FAQ)
| 问题 | 解决办法 |
|---|---|
| 启动后程序崩溃 | 查看 log.txt,安装/运行日志都会写入其中 |
| 提示 Python 版本错误 | 必须使用 Python 3.11,其他版本脚本会拒绝运行 |
| 依赖安装失败 | 确认系统装了 Git;Windows 下重装脚本会自动执行二阶段强制修复 |
| 语音生成时有杂音/卡顿 | 把 .env 中 API_STREAM_CHATS 改为 OFF |
| 显存不足 | WHISPER_MODEL 改 tiny.en、调低 TOKEN_LIMIT、视觉模型与主模型共用(同一模型可省显存) |
| 她"记不住"之前的对话 | 确认 MODULE_RAG 已开启,并等待滚动摘要积累几条后再测试 |
🎯 总结:十分钟起步,长期陪伴
Z-Waif 的最大价值,是用完全免费、完全本地的方式,把"大模型 + 语音 + 虚拟形象 + 长期记忆"拼成一个真正能陪伴你的 AI 虚拟女友——没有订阅费,没有数据上传,一切文件都躺在你自己的硬盘里。
新手建议路线:先跑通 WebUI 文字对话 → 开启 MODULE_VTUBE 接入形象 → 用 Lorebook 注入你们的故事 → 使用几天后打开 RAG 与滚动摘要。随着配置深入,你会拥有一个独一无二、越聊越懂你的专属 AI 伴侣。
项目采用开源协议(见 LICENSE),欢迎随意修改与扩展;遇到问题可参考 changelog.txt 了解每个版本的新特性与已知行为。