🕌

【実践編】音声チャットボットを初めて作る人のためのガイド

に公開

音声応答付きチャットボットをClaude Codeで作成した記録


📌 はじめに:モチベーション

Project AIRI を試していて、音声応答のあるチャットボットの可能性を感じました。純粋に楽しかったんです。「AITuberを作ってみたら生成AIプログラミングがよくわかった件」という書籍をベースに、音声応答ありのチャットボットが作れるんじゃないかと考えました。

そこで生まれたのが、**16歳の栄養オタク女子高校生「ななか」**とのチャットボットです。

この記事のゴール: 初心者の方でも音声チャットボットの作成体験を理解できるように、実際の開発プロセスとハマりポイントを解説します。


📖 事前準備:必要なもの

💻 必要なツール

ツール 用途 備考
Python 3.x バックエンド開発 慣れているので採用
Node.js フロントエンド開発 Vue 3 を動かすため
VOICEVOX 音声合成 無料の日本語TTS
Z.ai API AI応答生成 無料APIキー取得

🔑 APIキーの取得

  1. Z.ai API
    Z.aiのAPIキー取得方法は以下の通り。公式ページも参考にしてください。

    Z.aiのAPIキーは、Z.aiの公式サイト(Open Platform)から取得できます。主にGLM-4.7やGLM-5といったモデルをAPI経由で利用するためのキーです。
    Z.ai APIキーの取得手順
    公式サイトにアクセス
    Z.aiのOpen Platformにアクセスします。
    ログインまたは登録
    アカウントを作成(Register)またはログインします。
    管理画面(API Keys)へ移動
    ダッシュボード画面にて「API Keys」または「API Keys management」ページに移動します。
    APIキーの作成
    「Create new secret key」または「+ Create Key」ボタンをクリックし、名前(ラベル)を入力して生成します。

https://docs.z.ai/guides/overview/quick-start

  1. APIキー:
    APIキーの設定方法は、Z.aiのCline連携のページがわかりやすいです。

設定情報を入力する
以下の設定に従って関連情報を入力します。
APIプロバイダー:選択OpenAI Compatible
ベースURL : 入力https://api.z.ai/api/coding/paas/v4
APIキー: Z.AI APIキーを入力してください
モデル:「カスタムを使用」を選択し、モデル名を入力します(例glm-4.7:)

https://docs.z.ai/devpack/tool/cline

🎯 想定読者レベル

  • 🔰 HTML/CSSは分かる
  • 🔰 Pythonの基礎は分かる
  • 🔰 Gitは使ったことがある

🏗️ アーキテクチャ解説(全体像)

Claude Code との対話で、フロントエンドとバックエンドを分けて実装するプランを採用しました。

システム構成図

┌─────────────────┐
│  フロントエンド  │  Vue 3 + TypeScript + Tailwind CSS
│   (localhost:3000)  │  ユーザー画面・チャット履歴
└────────┬────────┘
         │ HTTP (REST API)
         ↓
┌─────────────────┐
│  バックエンド   │  Python + FastAPI
│   (localhost:8000)  │  AI応答生成・音声合成
└────────┬────────┘
         │
         ├─→ Z.ai API (glm-4.7) ← AI脳みそ
         └─→ VOICEVOX (やよい)   ← 音声合成

選定理由

  • フロントエンド(Vue 3): Reactより学習コストが低く、既存知識を活用
  • バックエンド(Python + FastAPI): 慣れている言語、高速開発
  • AI(Z.ai GLM-4.7): APIキーで高性能、OpenAI互換
  • 音声(VOICEVOX): 無料で日本語女性の声(やよい)が使用可能

🎯 キャラクター設定:ななか

キャラクター設定

「AITuberを作ってみたら生成AIプログラミングがよくわかった件」のキャラクター設定を基に、16歳の女の子のキャラクターを考えました。

📋 プロフィールカード

項目 設定
名前 ななか
年齢 16歳
職業 高校生
特技 栄養オタク
大好物 ステーキ(高タンパク・低脂肪)
嫌いなもの 甘い飲み物(エンプティカロリー)
関係 ユーザーの幼馴染
一人称 私
相手への呼び方 あんた

💬 口調設定

  • タメ口調(「〜じゃない?」「〜でしょ?」「〜わよ!」)
  • 栄養指導熱心
  • 面倒見が良い姉御肌

🧠 システムプロンプト

# キャラクター制約
- 「ずんだもん」ではない
- 一人称は「私」
- 相手を「あんた」と呼ぶ
- 語尾に「〜じゃない?」「〜でしょ?」「〜わよ!」
- 100文字以内で収めること
- 必ず栄養・健康に関するアドバイスを含める

最初ずんだもんキャラクタでチャットボットを設定していました。
後に設定をオリジナルキャラクターへと変更したのですが、
当初ずんだもんの口調が抜けず、Claude Codeの執拗な「No ずんだもん」指示が発生しました。


🔨 実装ステップ

Step 1: フロントエンドの作成

フロントエンドの作成

Vue 3 プロジェクト作成

npm create vue@latest frontend
cd frontend
npm install

Tailwind CSS 導入

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

コンポーネント構成

src/
├── components/
│   ├── CharacterDisplay.vue  # キャラクター表示(感情切り替え)
│   ├── ChatHistory.vue       # チャット履歴
│   ├── ChatInput.vue         # 入力フォーム
│   └── ChatMessage.vue       # チャットメッセージ
├── composables/
│   └── useChat.ts            # チャットロジック
└── App.vue                    # メインレイアウト

Step 2: バックエンドの作成

バックエンドの作成

FastAPI プロジェクト作成

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install fastapi uvicorn python-dotenv openai requests

ディレクトリ構成

backend/
├── adapters/
│   ├── openai_adapter.py   # Z.ai API 連携
│   └── voicevox_adapter.py # VOICEVOX 連携
├── models/
│   └── chat.py             # データモデル
├── prompts/
│   └── nanaka_system_prompt.txt  # ななかの設定
├── main.py                  # FastAPI メイン
└── .env                    # 環境変数

Step 3: つなぎ合わせ

つなぎ合わせ

CORS 設定

# main.py
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

API エンドポイント実装

@app.post("/api/chat", response_model=ChatResponse)
async def chat(request: ChatRequest):
    # 1. AI応答生成
    ai_response = openai_adapter.generate_response(
        user_message=request.message,
        chat_history=history
    )
    
    # 2. 音声合成
    audio_base64 = voicevox_adapter.synthesis_to_base64(ai_response)
    
    # 3. レスポンス返却
    return ChatResponse(
        text=ai_response,
        audio_base64=audio_base64,
        emotion="normal"
    )
)

🎨 UI/UX ハイライト

UI/UX ハイライト

1. 感情表示システム

キャラクターの感情状態によって画像を自動切り替え:

😊 normal  → 通常時
🗣️ talking → 喋り中
😲 surprised → 驚いた時

実装ロジック:

// CharacterDisplay.vue
const currentEmotion = ref<CharacterEmotion>('normal')

watch(() => props.isSpeaking, (speaking) => {
  if (speaking) {
    currentEmotion.value = 'talking'
  } else {
    currentEmotion.value = props.emotion || 'normal'
  }
})

2. プロフィール詳細表示

折りたたみ可能なUIで、以下の情報を表示:

🎓 高校生 - 日々の勉強とトレーニングを両立
💪 栄養オタク - PFCバランスを徹底管理
🥩 大好物はステーキ - 高タンパク・低脂肪を信条
🥤 甘い飲み物は敵視 - 「エンプティカロリーの塊!」
💕 あんたの幼馴染 - 面倒見が良い姉御肌

実装(Vue 3):

<details class="mt-3 bg-orange-50 rounded-lg overflow-hidden">
  <summary class="px-4 py-2 text-sm font-medium text-orange-700 cursor-pointer">
    👤 プロフィール詳細
  </summary>
  <div class="px-4 pb-4 text-left text-sm space-y-2">
    <!-- プロフィール内容 -->
  </div>
</details>

3. キャラクター画像切り替え

感情状態に応じて自動判定:

const images: Record<CharacterEmotion, string> = {
  normal: '/images/normal.png',
  talking: '/images/talking.png',
  surprised: '/images/surprised.png'
}

const currentImage = computed(() => images[currentEmotion.value])

⚠️ トラブルシューティング(学びポイント)

一番苦労したのは、バックエンドとフロントエンドのサーバーを立ち上げて画面の表示をするものの画面が真っ白だったことです。

ブラウザのコンソールには「データが読み込まれていない」というトラブルの解消に一番引っ掛かりました。画面のインターフェースを思ったような形式にするためにClaude Codeに指示を出すのも難しく、スクリーンショットを撮って指示をスクショの画面に記入して送ったりしましたが、なかなかこちらの意図を伝えるのが難しかったです。

画面が真っ白から音声応答付きチャットボットを実装できるまで

Claude Codeで作成したスクリプトは一度では成功しませんでした。
画面が真っ白になったので、
「最初は"Nuxt 3" → 問題が改善できず、Nuxt 3に問題があるため、Vue 3 + Viteに切り替え」
という経緯をたどりました。
エラーからの実装までの流れとしては、
まずは「完全にシンプルなHTMLでテスト」

次に、音声応答を実装。

音声応答はすぐに反応しましたが、チャットの機能は何度もやり取りして実装できました。

その後、キャラクタ設定がずんだもんから直らないや、
Z.aiのAPIが不安定になってちゃっとの応答が来ない、
などのトラブルを乗り越えてローカルで動く音声チャットが完成しました!

ななかチャットボットデモ動画

https://youtu.be/OGeYcCLoBYE

25秒くらいからしゃべります。

主要な問題と解決策

問題 原因 解決策
画面が真っ白 フロントエンドとバックエンドの通信エラー ブラウザコンソールでAPIリクエストを確認
キャラクターが応答しない Z.ai APIのreasoning_contentが空 日本語応答抽出ロジックを実装(正規表現で抽出)
音声が再生されない VOICEVOXが起動していない localhost:50021 でVOICEVOXを起動
CORSエラー フロントエンドが許可されていない allow_origins に localhost:3000 を追加

Z.ai APIの特殊対応(重要)

GLM-4.7 では、AI応答が content フィールドではなく reasoning_content フィールドに含まれる問題がありました。

実装コード:

# reasoning_content から日本語応答を抽出
if hasattr(message, 'reasoning_content') and message.reasoning_content:
    reasoning_text = message.reasoning_content
    
    # パターン1: 最後の「」で囲まれた部分を抽出
    matches = re.findall(r'「([^」]+)」', reasoning_text)
    if matches:
        ai_response = matches[-1]  # 最後の一致を使用

💡 Claude Code への指示出しのコツ

AIアシスタント(Claude Code)と協業して開発を進める際、効果的なコミュニケーションが重要です。

🎯 指示出しの基本パターン

  1. スクリーンショット活用

❌ 「動かないので直して」
✅ 「この画面の真っ白な状態を直したい(スクショ添付)」

  1. 具体的なファイル指定

❌ 「設定ファイルを修正」
✅ 「backend/.env ファイルの ZAI_API_KEY を 'your_key_here' に変更」

  1. エラーメッセージ全文共有

❌ 「エラーが出た」
✅ 「ブラウザコンソールに以下のエラー: POST http://localhost:8000/api/chat 500」

  1. 段階的な指示

❌ 「チャットボット全体を作成」
✅ 「まず CharacterDisplay.vue の感情切り替え機能を実装して」

🔄 イテレーション workflows

  1. 確認 → 変更 → 確認

Step 1: 「現在の main.py を確認」
Step 2: 「この部分を修正」
Step 3: 「変更後のコードをレビュー」

  1. 小さく分解して実装

❌ 「音声合成全般を実装」
✅ 「VOICEVOX API キックを実装」
→ 「base64 エンコードを追加」
→ 「エラーハンドリングを実装」

📸 視覚的コミュニケーション

スクリーンショットには以下を含める

画面全体(レイアウト把握)
エラーメッセージ(詳細把握)
開発者ツール(デバッグ情報)
キャプチャに図解を追加

✅ 「キャラクター画像をここ(左側)に配置したい」
(スクショに赤枠で場所を指定)

🔧 技術的なトラブル時

ログの共有

✅ 「バックエンドログ: [DEBUG] AI response is None or empty」
✅ 「フロントエンドコンソール: useChat.ts:28 POST http://localhost:8000/api/chat 500」

環境情報の提供

✅ 「OS: Windows 11」
✅ 「Python: 3.11.5」
✅ 「Node.js: v20.10.0」
✅ 「ブラウザ: Chrome 121」

💬 コミュニケーションのベストプラクティス

行うべき 避けるべき
✅ 具体的なファイルパス指定 ❌ 「あのファイル」
✅ エラーメッセージ全文コピー ❌ 「エラーが出た」
✅ スクリーンショット添付 ❌ 文字だけの説明
✅ 目的と期待結果を明記 ❌ 「直して」のみ
✅ 段階的な依頼 ❌ 一括依頼

🚀 デプロイ挑戦記

挑戦したこと

デプロイを簡単に考えていました。一番簡単にできそうな Google Cloud の Cloud Run を利用することにしたので、すぐにできるだろうと思っていました。

起こった問題

1. VOICEVOXがCloud Runで使用不可

  • VOICEVOXはローカルアプリ(localhost:50021)
  • Cloud Run(クラウド環境)からアクセス不可

2. GCP TTS実装に失敗

  • Google Text-to-Speech APIを試す
  • OAuth認証で 400 Bad Request エラー
  • APIキー方式でも取得に手間取る

3. 断念
音声なし版(テキストのみ返却)でデプロイする予定ですが、今日は一旦停止です。

教訓

  • ローカルで完結する機能を選定すべき
  • クラウドデプロイは事前調査が重要
  • 音声合成はローカル限定で良い(まずは動くものを作る)

📚 今後の展望

  • 🎯 Graph RAG実装: 知識グラフ追加で専門知識に強化
  • 💾 会話履歴の保存: LocalStorageやIndexedDBで実装
  • 🎭 感情検出の自動化: ユーザーメッセージから感情を推測

✅ まとめ

音声チャットボットは思ったより簡単!キャラクター設定が肝心です。ローカル環境で手軽に試せます。

この記事で伝えたかったこと:

  1. フロントエンドとバックエンドを分けて実装するアプローチ
  2. Z.ai API + VOICEVOX の組み合わせで音声チャットが実現可能
  3. トラブルシューティングの学びポイント(真っ白画面、reasoning_content対応)
  4. デプロイの難しさとローカル開発の重要性

次回: デプロイ編(Firebase Hosting + Cloud Run)または Graph RAG実装編

お読みいただきありがとうございました!🎊

Discussion