# AI 執事 ミケ

LLM（Large Language Model）と MCP（Model Context Protocol）を組み合わせた AI コミュニケーションツール

## 概要

**AI 執事 ミケ**は、Raspberry Pi 上で動作する音声対話システムです。Julius による音声認識、VOICEVOX による音声合成、LLM による応答生成を統合し、自然な対話を実現します。

MCP を通じた外部ツール連携により、天気情報などの外部知識を活用しながら、ユーザーの質問に対して自然言語で応答します。

### 主な特徴

- **音声対話**: マイクからの音声入力を認識し、スピーカーから音声で応答
- **MCP統合**: Model Context Protocol により外部サービスとの連携が容易
- **LLM統合**: Ollama による効率的な LLM 実行
- **Docker対応**: Raspberry Pi での安定した運用を実現
- **柔軟な構成**: Docker版とアプリ版の2つの導入方式に対応

## システム構成

### 2つの導入方式

#### 1. Docker 版（推奨：本格運用向け）

Raspberry Pi 上で複数の Docker コンテナが連携：

- **mike_client**: 音声入力・認識・ユーザーインタフェース
- **mike_server**: 応答判定・MCP・LLM 処理
- **mike_data**: 音声ファイル生成・管理

**特徴**:
- 機能分離による安定動作
- Raspberry Pi での限定リソース環境に最適化
- PC側での LLM/音声合成処理へのオフロード

#### 2. アプリ版（簡易版：検証・学習向け）

Windows 環境での単一 Python アプリケーション

**特徴**:
- セットアップが簡単
- Docker 環境不要
- すべての処理を Windows PC で実行

## ハードウェア要件

### Raspberry Pi（Docker版）

| 項目 | 仕様 |
|------|------|
| 本体 | Raspberry Pi 4B |
| OS | Raspberry Pi OS Lite (64-bit) |
| メモリ | 8GB推奨 |
| ストレージ | USB メモリ 64GB以上 |
| 音声デバイス | USB スピーカーフォン |
| ネットワーク | 有線LAN（推奨） |

### Windows PC（サーバー側・アプリ版）

| 項目 | 仕様 |
|------|------|
| OS | Windows 11 Pro |
| CPU | AMD Ryzen 5 3600相当以上 |
| メモリ | DDR4 32GB |
| GPU | NVIDIA RTX-3060Ti 12GB |
| ストレージ | NVMe SSD 2TB |

## ソフトウェア要件

### 必須

- **Docker**: 28 以上（Docker版）
- **Python**: 3.13
- **git**: GIT
- **Julius**: 音声認識エンジン
- **VOICEVOX**: 音声合成エンジン
- **Ollama**: LLM実行環境

### Pythonライブラリ

```
SpeechRecognition==3.14.4
fastmcp==2.14.1
numpy==2.3.5
llama-index-core==0.14.10
llama-index-llms-ollama==0.9.0
pyaudio==0.2.14
ffmpeg-python==0.2.0
requests==2.32.5
scipy==1.16.3
```

## クイックスタート

### Windows アプリ版

```bash
# 1. ffmpeg のインストール
winget install --id=Gyan.FFmpeg -e

# 2. インストール実行
./install.ps1

# 3. VOICEVOX と Ollama をサーバモードで起動
# コマンドプロンプトで別々に実行

# 4. 起動
python main.py
```

### Docker版（Raspberry Pi）

```bash
# 1. Raspberry Pi OS のセットアップ
# Raspberry Pi Imager を使用して OS を書き込み

# 2. Docker のインストール
sudo curl -fsSL https://get.docker.com/ | sh
sudo usermod -aG docker ${USER}

# 3. docker network の作成
docker network create mike-net -d bridge

# 4. AI ミケのセットアップ
cd /opt/mike
tar xvzf mike_xxx.tar.gz
tools/build_mike.sh
tools/julius_make.sh
tools/make_data.sh

# 5. 起動
tools/mike_start.sh
```

## 使用方法

### 基本的な会話フロー

```
1. 「みけおはよう」 → ウェイクワード（起動）
2. 「東京の天気を教えて」 → 質問
3. AI ミケが天気情報を取得して応答
4. 「ありがとう」 → 待機モードに戻る
5. 「またね」 → 終了
```

### モード遷移

```
待機モード
    ↓ 「みけおはよう」（ウェイクワード）
コマンドモード
    ├→ 「お話し」で会話モードへ
    └→ 通常はコマンド認識
    
会話モード
    ├→ 自由会話対応https://img.shields.io/badge/License-MIT-yellow.svg
    └→ 「ありがとう」で待機モードへ
```


## 設定

### 主要設定ファイル

#### config.json

システム全体の設定を定義：（設定内容の一部）
下記はインストール時に再設定が必要な項目です

```json
{
  "VOICEVOX": {
    "Host": "localhost",　＜－－ VOICEVOXをインストールしたPCのアドレス
    "Port": 50021,
    "Speaker": 45
  },
  "OLLAMA": {
    "Host": "http://localhost:11434", ＜－－ OLLAMAをインストールしたPCのアドレス
    "Model": "gpt-oss:20b",
    "Content": "You are a wonderful butler."
  },
}
```

#### communication.csv

音声コマンドと応答の対応表：

```csv
番号,音声コマンド,音声応答,スピーカ,ファイル名,問い合わせよみ
wake,みけおはよう,なにかにゃ～,45,wake-mike,みけおはよう
chat,お話ししよう,よろこんでにゃ～,45,chat-ohanashi,お話し
tenki,天気予報,天気を調べてみるにゃ～,45,tenki-tenki,てんきよほう
```

#### mcp_servers.json

MCP サーバの接続設定（アプリ版/Docker版で異なる）

詳細は各セクションを参照してください。

### ファイル構成

- **APP版**: 単一ディレクトリに集
- **Docker版**: 3つのコンテナ構成

## ディレクトリ構造

### Docker版

```
.
├── mike_client/          # クライアント側コンテナ（Docker版）
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── opt_mike/
│       ├── bin/          # 実行ファイル群
│       ├── config/       # 設定ファイル群
│       └── snd/          # 音声ファイル群
├── mike_server/          # サーバ側コンテナ（Docker版）
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── opt_mike/
│       ├── bin/          # 実行ファイル群
│       ├── config/       # 設定ファイル
│       └── cache/        # キャッシュ
├── mike_data/            # データ生成コンテナ（Docker版）
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── opt_mike/
│       ├── bin/
│       ├── config/
│       ├── input/        # 入力ファイル群
│       └── voice/        # 出力音声ファイル群
└── tools/                # ユーティリティスクリプト群

```

### APP版（Windows）

```
mike_app/
├── README.txt                          # プロジェクト説明文書
├── install.ps1                         # インストールスクリプト
├── main.py                             # エントリーポイント
├── mike_server.py                      # サーバプログラム
├── weather_mcp_server.py               # 天気MCP サーバ
├── bin/                                # バイナリ・実行ファイル群
├── config/                             # 設定ファイル
├── mike/                               # コアモジュール群
├── cache/                              # 実行時キャッシュ
├── docs/                               # ドキュメント
└── snd/                                # 音声ファイル
```

## プログラム構成

### コアコンポーネント

| ファイル | 役割 | 説明 |
|---------|------|------|
| `mike_client.py` | クライアント | 音声入力・認識・対話制御を統括 |
| `mike_server.py` | サーバ | 応答生成・MCP・LLM処理を管理 |
| `mike_mcp_client.py` | MCP | 外部ツール連携を実現 |
| `weather_mcp_server.py` | MCP | 天気情報提供サーバ |
| `voicevox_handler.py` | 音声合成 | VOICEVOX との連携 |
| `julius_handler.py` | 音声認識 | Julius による短文認識 |
| `speech_recognition_handler.py` | 音声認識 | Google API による自由会話認識 |
| `audio_stream_manager.py` | 音声I/O | PyAudio による統合管理 |

### サポートツール（Docker版）

| スクリプト | 目的 |
|-----------|------|
| `build_mike.sh` | Docker環境の構築 |
| `julius_make.sh` | Julius のビルド・テスト |
| `make_data.sh` | 音声データの生成 |
| `mike_start.sh` | AI ミケの起動 |
| `mike_stop.sh` | AI ミケの停止 |



## トラブルシューティング

### 音声が認識されない

**確認項目**:
- USB マイクが正しく接続されているか
- `config.json` の `DeviceIndex` が正しいか
- マイク音量が設定されているか

**対処方法**:
```bash
# マイクデバイスの確認
arecord -l

# 音量の確認・調整
alsamixer
```

### AI ミケが応答しない

**確認項目**:
- VOICEVOX が起動しているか
- Ollama が起動しているか
- ネットワーク接続の確認

**対処方法**:
```bash
# VOICEVOX の接続確認
wget http://voicevox-host:50021/

# Ollama の確認
ollama list
```

### 音声が大音量のノイズになる

**対処方法**:
```bash
# 1. AI ミケを停止
tools/mike_stop.sh

# 2. USB デバイスを再接続
# USB ケーブルを抜いて接続し直す

# 3. 音量確認後に再起動
tools/mike_start.sh
```

### 終了できない

**確認項目**:
- 「またね」コマンドが認識されたか確認
- ログを参照して認識状態をチェック

**強制終了**:
```bash
tools/mike_stop.sh
```

## 開発・カスタマイズ

### 音声コマンドの追加

`communication.csv` に新しい行を追加：

```csv
新番号,新コマンド,応答テキスト,45,ファイル名,よみ
```

その後、`make_data.sh` で音声データを再生成。

### キャラクター設定の変更

`config.json` の OLLAMA.Content を編集：

```json
"Content": "あなたは○○です。××で答えてください。"
```

### 新しい MCP サーバの追加

1. MCP サーバを実装
2. `mcp_servers.json` に追加
3. `mike_mcp_client.py` でツール一覧を取得して確認

詳細は補足資料（PDF）を参照してください。

## ライセンス
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)

MIT License

Copyright (c) 2025 Takashi Ujimori

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

## 注記

### VOICEVOX について

VOICEVOX は個別のライセンス条件が適用されます。詳細は公式ドキュメントを確認してください。

### Ollama/LLM モデルについて

使用する LLM モデル（Llama、Code Llama など）にはモデルごとに異なるライセンスが適用されます。実運用の際は必ず各モデルのライセンス条件を確認してください。

## 参考資料

- [Julius 公式ドキュメント](https://julius.osdn.jp/)
- [VOICEVOX 公式サイト](https://voicevox.hiroshiba.jp/)
- [Ollama 公式サイト](https://ollama.ai/)
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)

## サポート・問い合わせ

詳細な環境構築手順・開発メモについては、付属の PDF ドキュメント（AI執事ミケ補足資料.pdf）を参照してください。

本プロジェクトについてのご質問やフィードバックは、ドキュメント内に記載されている参考情報をご活用ください。

---

**作成者**: 氏森 充  
**最終更新**: 2025年11月29日
