# ai-girlfriend-web

**Repository Path**: PhiloKun/ai-girlfriend-web

## Basic Information

- **Project Name**: ai-girlfriend-web
- **Description**: AI 女友 · Web 端：实时对话 + 真人视频(talking-head)，Go 后端 + 原生前端，edge-tts 真实中文女声
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-08-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 💕 AI 女友 · Web 端

一个 Web 端的 AI 女友，支持**实时文字流式对话**与**完整语音对话**（浏览器原生语音输入 + 语音播报）。
后端用 Go 代理大模型流式接口（密钥只在后端，安全），前端无构建步骤，打开即用。

## ✨ 功能
- 实时文字流式对话（打字机效果，SSE）
- 语音输入（STT，说给她听）+ 后端 TTS（她念给你听）
- **真人视频（talking-head）**：开启视频模式后，她会一边说话一边「动嘴」，像在和你视频通话
- 可插拔多厂商大模型：OpenAI / DeepSeek / 通义千问 / 本地 Ollama
- 可配置人设：名字、性格、关系、口头禅、禁忌（改 `internal/persona/persona.yaml`）
- 会话记忆：短期上下文 + 长期记忆，落盘在 `data/`

## 🚀 快速开始

**想一条命令跑起来？** 直接 `./start.sh`（自动编译、起 Ollama 与视频服务），详见 [QUICKSTART.md](./QUICKSTART.md)。

```bash
# 1. 安装依赖（Go 1.22+）
go mod tidy

# 2. 准备配置
cp config.example.yaml config.yaml
cp .env.example .env
# 编辑 config.yaml 选 provider、开启 tts/video；编辑 .env 填对应 API Key
# 编辑 internal/persona/persona.yaml 设定你想要的她
# 把 static/avatar.png 换成你想用的真人照片（jpg/png）

# 3. 启动视频微服务（另一个终端）
cd video && python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
uvicorn service:app --host 0.0.0.0 --port 8000   # 默认 mock，无需 GPU

# 4. 启动 Go 主服务
go run main.go
# 或编译后运行： go build -o ai-girlfriend . && ./ai-girlfriend

# 5. 打开浏览器，点 📹 开启视频模式
open http://localhost:8080
```

没填 Key 也能跑：默认 `provider.active: ollama`，本地起一个 Ollama（`ollama run qwen2.5:7b`）即可对话。

## 🎥 真人视频模式
- 点界面右上角 **📹** 开启视频模式。每次她回复，后端会：
  `LLM 文本 → 视频微服务用 edge-tts 合成真实中文女声 → ffmpeg 把真人照片合成为说话视频 → 前端播放`。
- **声音是真实的**：采用微软 edge-tts（Neural 神经网络音色，默认晓晓 `zh-CN-XiaoxiaoNeural`），**免费、无需 API Key，仅需联网**。视频文件本身就带她的人声；可在 `config.yaml` 的 `video.tts_voice` 换音色（如 `zh-CN-XiaoyiNeural` 女 / `zh-CN-YunjianNeural` 男）。
- 浏览器若拦截带声音视频的自动播放，会自动降级为「静音画面 + 浏览器 TTS 念人话」兜底（不会双音）。
- 本机 `mock` 模式用 ffmpeg 把照片 + 音频合成可播放视频（无 GPU 即可跑通整条链路）。
- 想要**真正对口型的真人脸**：用 GPU 机器/容器跑 `docker build -t ai-gf-video ./video && docker run --gpus all -p 8000:8000 -e TALKER=musetalk -v /你的模型:/models ai-gf-video`，
  在 `video/talker.py` 里接入 MuseTalk / EchoMimic（已留骨架）。
- 一句话编排（Go + 视频服务）：`docker compose up`。

## 🔌 切换模型
编辑 `config.yaml` 的 `provider.active`：
- `openai` → 填 `OPENAI_API_KEY`
- `deepseek` → 填 `DEEPSEEK_API_KEY`（默认，便宜好用）
- `tongyi` → 填 `TONGYI_API_KEY`
- `ollama` → 本地部署，无需 Key

## 🎙️ 语音说明
- 语音输入用浏览器原生 Web Speech API，**零成本、零配置**，支持中英文。
- 语音播报（TTS）走**后端**：`tts.provider` 可选 `openai`（自然，需 Key）或 `mock`（联调用）。
- 推荐用 **Chrome / Edge** 体验（部分 Safari 桌面版不支持语音输入）。
- 若浏览器不支持，麦克风按钮会自动置灰，仍可纯文字聊天。

## 🗂️ 目录结构
```
main.go                  入口
internal/config          配置 + .env 加载
internal/llm             多厂商适配器（统一 OpenAI 流式协议）
internal/persona         人设配置与 system prompt 拼装
internal/memory          会话/长期记忆落盘
internal/handler         HTTP 接口（SSE 流式对话）
static/                  前端（index.html / style.css / app.js）
```

## 🔒 安全
- API Key 只存在于后端（`.env`，已 gitignore），前端永远拿不到。
- 会话数据写在 `data/`（已 gitignore）。

## 📌 说明
本项目为情感陪伴/娱乐向 demo，人设与内容均由配置文件约束，内置底线（不输出色情露骨内容、不扮演其他角色）。