# ai-minion

**Repository Path**: godY/ai-minion

## Basic Information

- **Project Name**: ai-minion
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-06
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🟡 AI小黄人 (AI-Minion)

一个专为小朋友设计的**本地语音对话助手**，全部运行在您的电脑上，无需联网（除语音合成外，可选离线方案）。

> 🌐 **模型来源**：本项目所有模型均通过 **ModelScope（魔搭社区）** 或其官方镜像站下载，无需访问 HuggingFace。

## 硬件环境

| 组件 | 配置 |
|------|------|
| GPU | NVIDIA RTX 2060 — 6GB 显存 |
| CPU | Intel i5-12400F — 6核 |
| 内存 | 16 GB |
| 磁盘 | 200GB+ 可用空间 |
| OS | Linux (也兼容 Windows/macOS，命令需微调) |

## 整体架构

```
小朋友说话 → [录音] → [Whisper 语音识别] → [文字]
                                              ↓
[播放语音] ← [edge-tts 语音合成] ← [Qwen3-4B-Instruct 大模型]
```

| 模块 | 选用方案 | 显存占用 |
|------|----------|----------|
| LLM (大脑) | Qwen3-4B-Instruct | ~4 GB |
| ASR (耳朵) | faster-whisper-small | ~1 GB |
| TTS (嘴巴) | edge-tts (在线/免费) | 0 GB |
| **合计** | | **~5 GB** ✅ 6GB 卡刚好装下 |

---

## 📁 项目结构

```
ai-minion/
├── README.md                  # 本文件
├── requirements.txt           # Python 依赖
├── config/
│   └── system_prompt.txt      # AI 性格设定（可修改）
├── src/
│   └── main.py                # 主程序
├── scripts/
│   └── setup.sh               # 一键安装脚本（Linux）
└── temp/                      # 运行时临时文件（自动创建）
```

---

## 🚀 部署步骤（一步一步跟着做）

### 第 1 步：安装 Ollama（大模型引擎）

Ollama 是在本地运行大模型的最简方式。

```bash
# Linux 安装
curl -fsSL https://ollama.com/install.sh | sh

# 安装完成后，确认服务已启动
ollama --version
```

> Windows 用户请去 https://ollama.com/download 下载安装包。

### 第 2 步：下载对话模型

```bash
# 下载 Qwen3-4B-Instruct（默认量化，最方便）
ollama pull qwen3:4b

# 验证模型是否存在
ollama list
```

> 💡 **关于 Q8_0**：Ollama 官方 `qwen3:4b` 默认量化即可流畅对话。如果您坚持要表格中的 **Q8_0 高精度版本**，请跳到文末【附录：通过 ModelScope 导入 Q8_0 GGUF】。

### 第 3 步：创建 Python 虚拟环境

```bash
# 进入项目目录
cd /data/agent/ai-minion

# 创建虚拟环境
python3 -m venv venv

# 激活环境
source venv/bin/activate

# (Windows 用户用: venv\Scripts\activate)
```

### 第 4 步：安装 Python 依赖

确保虚拟环境已激活（命令行前面有 `(venv)` 字样），然后：

```bash
pip install -r requirements.txt
```

> 如果安装 `pygame` 报错，可以跳过它，程序会自动使用系统播放器（mpv/ffplay）。

### 第 5 步：测试各组件是否正常

**5.1 测试 Ollama**
```bash
ollama run qwen3:4b
# 如果能对话，说明模型正常。按 /bye 退出。
```

**5.2 测试 edge-tts**
```bash
edge-tts --voice zh-CN-XiaoxiaoNeural --text "你好呀小朋友" --write-media test.mp3
# 如果生成了 test.mp3 文件，说明 TTS 正常
```

**5.3 测试音频播放**
```bash
# 如果有 mpv
mpv test.mp3

# 或者 ffplay
ffplay -nodisp -autoexit test.mp3

# 如果都没有，试试系统默认播放器
xdg-open test.mp3
```

### 第 6 步：运行 AI小黄人

**方式一：CMD 语音模式**
```bash
# 确保虚拟环境已激活
source venv/bin/activate

# 运行主程序
python src/main.py
```

看到 `🟡 AI小黄人 启动成功！` 后，按 **Enter** 开始录音，对着麦克风说话，说完等待 5 秒，AI 就会回答啦！

按 **Ctrl+C** 退出程序。

**方式二：桌面 GUI 模式（推荐）**

```powershell
# Windows (PowerShell)
venv\Scripts\python.exe src\desktop\main.py
```

```bash
# Linux/macOS
source venv/bin/activate
python src/desktop/main.py
```

看到暖粉色窗口后：

| 操作 | 说明 |
|------|------|
| **文字聊天** | 底部输入框打字 → Enter |
| **语音聊天** | 点击 🎤 按钮 → 说话 → 静音自动结束 → AI 回复 |
| **唤醒/隐藏** | `Ctrl+Space` 全局快捷键切换窗口 |
| **系统托盘** | 右下角小黄人图标，右键菜单 |
| **查看记忆** | 托盘右键 → 「🧠 查看记忆」 |
| **设置** | 托盘右键 → 「⚙️ 设置」（快捷键、语音模型等） |
| **悬浮模式** | 点击窗口右上角 ⤢ 切换迷你悬浮窗 |
| **退出** | 托盘右键 → 「退出」 |

> 💡 首次启动后，窗口默认显示。最小化或关闭会隐藏到系统托盘，不会退出。

---

## 🎮 使用方式

1. 程序启动后，显示 `按 Enter 开始录音`
2. 按 **Enter**，看到 `🎤 开始录音` 后开始说话
3. 说完后等待 5 秒，录音自动结束
4. 程序会自动：识别 → 思考 → 生成语音 → 播放
5. 一轮对话结束，再次按 **Enter** 开始下一轮

---

## ⚙️ 自定义配置

### 修改 AI 的性格 / 说话方式

编辑 `config/system_prompt.txt`，修改后重启程序即可生效。

### 调整录音时长

编辑 `src/main.py`，找到 `RECORD_SECONDS = 5`，改成您想要的秒数。

### 更换语音音色

编辑 `src/main.py`，找到 `--voice zh-CN-XiaoxiaoNeural`，可替换为：
- `zh-CN-XiaoyiNeural` — 温柔女声（晓伊）
- `zh-CN-YunjianNeural` — 男声（云健）
- `zh-CN-YunxiNeural` — 年轻男声（云希）

完整列表：`edge-tts --list-voices | grep zh-CN`

---

## 🛠️ 常见问题

| 问题 | 解决方法 |
|------|----------|
| `CUDA out of memory` | 确认 Ollama 和 Whisper 都在用 GPU，显存是否超过 6GB。可改 Whisper 模型为 `base` |
| 录音没声音 | 检查系统默认麦克风是否选对，`arecord -l` 查看设备 |
| 语音不播放 | 安装 `mpv`：`sudo apt install mpv`，或安装 `pygame`：`pip install pygame` |
| AI 回答太长 | 改 `num_predict` 为更小的值（如 100），或修改系统提示词要求简短 |
| 识别不准确 | 换 Whisper `small` 为 `medium`（需更多显存），或确保普通话清晰 |

---

## 📎 附录：通过 ModelScope 导入 Q8_0 GGUF（可选）

如果您想要表格中的 **Q8_0 高精度版本**，而 Ollama 官方没有提供，可通过 **ModelScope** 下载并导入：

### 方式一：通过 ModelScope 提供的 HF 镜像（推荐）

```bash
# 1. 设置环境变量，所有 HuggingFace 下载走 ModelScope 镜像
export HF_ENDPOINT=https://hf-mirror.com

# 2. 安装 huggingface-cli
pip install huggingface-hub

# 3. 下载 GGUF 文件
mkdir -p /data/agent/ai-minion/models
cd /data/agent/ai-minion/models

# 下载 Qwen3-4B-Instruct Q8_0 GGUF
huggingface-cli download Qwen/Qwen3-4B-Instruct-GGUF \
    --include "*q8_0*" \
    --local-dir ./ \
    --local-dir-use-symlinks False

# 4. 创建 Modelfile
cat > Modelfile << 'EOF'
FROM ./qwen3-4b-instruct-q8_0.gguf
PARAMETER temperature 0.7
SYSTEM """你是一个温柔有爱心的好朋友，正在和一个年幼的小朋友聊天。"""
EOF

# 5. 导入 Ollama
ollama create qwen3-4b-instruct-q8_0 -f Modelfile

# 6. 修改 src/main.py 里的 OLLAMA_MODEL = "qwen3:4b-instruct-q8_0"
```

### 方式二：通过 ModelScope SDK（原生）

```bash
# 1. 安装 modelscope
pip install modelscope

# 2. 下载模型
mkdir -p /data/agent/ai-minion/models
cd /data/agent/ai-minion/models

modelscope download --model qwen/Qwen3-4B-Instruct-GGUF \
    --local_dir ./

# 3. 后续步骤同上（创建 Modelfile 并导入 Ollama）
```

> 💡 `hf-mirror.com` 是 **ModelScope 社区** 官方维护的 HuggingFace 镜像站，国内访问速度极快，模型与 HF 原站完全同步。