デプロイガイド

🚀 デプロイの概要

本ガイドでは、ASR-LLM-TTS 音声対話アシスタントのバックエンドシステムをさまざまな環境にデプロイする方法を、開発環境・テスト環境・本番環境の設定手順を含めて詳しく説明します。

🔧 動作環境

基本環境

コンポーネント	要件	説明
OS	Linux（Ubuntu 18.04 以降を推奨）	オーディオドライバのサポートが必要
Python	3.8+	3.9 または 3.10 を推奨
メモリ	最小 4GB、推奨 8GB 以上	ASR モデルは多くのメモリを必要とします
ディスク	最小 10GB の空き容量	モデルファイルは約 2〜3GB
ネットワーク	安定したインターネット接続	LLM と TTS には API アクセスが必要

システムの依存関係

Ubuntu/Debian

# 更新软件包
sudo apt update && sudo apt upgrade -y

# 安装音频系统依赖
sudo apt install -y \
    pulseaudio \
    pulseaudio-utils \
    alsa-utils \
    libasound2-dev \
    portaudio19-dev \
    ffmpeg

# 安装Python开发环境
sudo apt install -y \
    python3-dev \
    python3-pip \
    python3-venv \
    build-essential \
    pkg-config

CentOS/RHEL

# 安装音频系统依赖
sudo yum install -y \
    pulseaudio \
    pulseaudio-utils \
    alsa-utils \
    alsa-lib-devel \
    portaudio-devel \
    ffmpeg

# 安装Python开发环境
sudo yum install -y \
    python3-devel \
    python3-pip \
    gcc \
    gcc-c++ \
    pkgconfig

📦 インストール手順

1. プロジェクトコードの取得

# 克隆项目仓库
git clone <repository-url> asr-llm-tts
cd asr-llm-tts/Backend

# 或者从压缩包解压
tar -xzf asr-llm-tts.tar.gz
cd asr-llm-tts/Backend

2. Python 仮想環境の作成

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

# 激活虚拟环境
source venv/bin/activate

# 升级pip
pip install --upgrade pip

3. Python 依存パッケージのインストール

# 安装核心依赖
pip install -r requirements.txt

# 如果遇到依赖冲突，可以分步安装
pip install fastapi uvicorn websockets
pip install httpx pyyaml numpy
pip install sounddevice pygame
pip install sherpa-onnx  # ASR功能（可选）

4. モデルファイルのダウンロード

ASR モデル（音声認識機能を有効にする場合）

# 创建模型目录
mkdir -p model/asr model/vad

# 下载Paraformer中文ASR模型
cd model/asr
wget https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-paraformer-zh-2024-03-09.tar.bz2
tar -xjf sherpa-onnx-paraformer-zh-2024-03-09.tar.bz2

# 下载VAD模型
cd ../vad
wget https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/silero_vad.onnx

cd ../..

5. API キーの設定

# 复制环境变量模板
cp .env.example .env

# 编辑.env文件，填入真实的API密钥
nano .env

.env ファイルの内容例：

# 火山引擎LLM API密钥
VOLCENGINE_LLM_API_KEY="ak-your-llm-api-key-here"

# 火山引擎TTS API密钥
VOLCENGINE_TTS_APP_ID="your-tts-app-id"
VOLCENGINE_TTS_ACCESS_TOKEN="your-tts-access-token"

# 可选：MCP相关配置
MCP_DEBUG=false
MCP_CONNECTION_TIMEOUT=30

6. オーディオデバイスの設定

自動設定（推奨）

# 运行音频配置工具
python utils/audio_config/setup_audio_devices.py

手動設定

# 查看可用音频设备
pactl list sources short    # 输入设备
pactl list sinks short      # 输出设备

# 设置默认设备（根据实际设备名称修改）
pactl set-default-sink alsa_output.usb-device-name
pactl set-default-source alsa_input.usb-device-name

7. システムパラメータの設定

config.yaml を編集します：

# 应用全局配置
app:
  input_mode: "keyboard"  # 或 "asr"（如果要启用语音识别）

# LLM配置
llm:
  volcengine:
    api_url: "https://ark.cn-beijing.volces.com"
  model:
    name: "doubao-pro-32k-functioncall-241028"
  parameters:
    temperature: 0.7
    max_tokens: 4096

# TTS配置
tts:
  voice:
    default_speaker: "zh_female_qingxin"

# ASR配置（如启用语音识别）
asr:
  sample_rate: 16000
  channels: 1
  model_dir: "./model/asr/sherpa-onnx-paraformer-zh-2024-03-09"
  vad_model_path: "./model/vad/silero_vad.onnx"
  target_microphone_keyword: "UGREEN"  # 根据实际麦克风调整

# 音频播放器配置
audio_player:
  device: null  # null表示使用默认设备
  volume: 1.0

🎯 特定環境へのデプロイ

RDKX5 開発ボードへのデプロイ

RDKX5 はよく使われる組込み開発ボードで、特別な設定が必要です：

1. オーディオデバイスの設定

# 使用专用的音频修复脚本
./scripts/fix_rdkx5_audio.sh

# 或者手动配置
pactl set-default-sink alsa_output.usb-Jieli_Technology_UACDemoV1.0_*
pactl set-default-source alsa_input.usb-BlueTrm_UGREEN_CM564_*

2. システムの最適化

# 增加系统音量
amixer set Master 100%

# 调整音频缓冲区（如遇到音频卡顿）
echo "default-fragments = 8" >> ~/.pulse/daemon.conf
echo "default-fragment-size-msec = 25" >> ~/.pulse/daemon.conf

# 重启PulseAudio
pulseaudio -k
pulseaudio --start

3. 設定ファイルの調整

# config.yaml - RDKX5特定配置
audio_player:
  device_keyword: "UACDemoV1.0"  # RDKX5 USB喇叭关键词
  blocksize: 2048                # 增大块大小提高稳定性
  buffer_size: 100               # 增大缓冲区
  min_prebuffer: 5               # 增加预缓冲

asr:
  target_microphone_keyword: "UGREEN"  # RDKX5常用USB麦克风
  num_threads: 4                       # RDKX5 CPU线程数优化

Docker コンテナへのデプロイ

1. Dockerfile の作成

# Dockerfile
FROM ubuntu:20.04

# 避免交互式安装
ENV DEBIAN_FRONTEND=noninteractive

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    python3-dev \
    build-essential \
    pulseaudio \
    alsa-utils \
    portaudio19-dev \
    ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# 设置工作目录
WORKDIR /app

# 复制依赖文件
COPY requirements.txt .

# 安装Python依赖
RUN pip3 install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 创建必要目录
RUN mkdir -p model/asr model/vad resource

# 暴露端口
EXPOSE 8000

# 启动命令
CMD ["python3", "server.py"]

2. docker-compose.yml の作成

version: '3.8'

services:
  asr-llm-tts:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./model:/app/model
      - ./resource:/app/resource
      - ./config.yaml:/app/config.yaml
      - ./.env:/app/.env
    environment:
      - PULSE_SERVER=unix:${XDG_RUNTIME_DIR}/pulse/native
    volumes:
      - ${XDG_RUNTIME_DIR}/pulse:${XDG_RUNTIME_DIR}/pulse
    devices:
      - /dev/snd:/dev/snd  # 音频设备访问
    privileged: true       # 需要音频设备权限

3. ビルドと実行

# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

クラウドサーバーへのデプロイ

1. 推奨サーバー構成

インスタンス仕様：2vCPU、4GB RAM 以上
ネットワーク：グローバル IP、8000 番ポートを開放
ストレージ：SSD、20GB 以上

2. セキュリティ設定

# 配置防火墙
sudo ufw allow 8000/tcp
sudo ufw enable

# 创建专用用户
sudo useradd -m -s /bin/bash asr-user
sudo usermod -aG audio asr-user

# 设置文件权限
sudo chown -R asr-user:asr-user /path/to/asr-llm-tts

3. システムサービスの設定

# /etc/systemd/system/asr-llm-tts.service
[Unit]
Description=ASR-LLM-TTS Voice Assistant
After=network.target

[Service]
Type=simple
User=asr-user
WorkingDirectory=/home/asr-user/asr-llm-tts/Backend
Environment=PATH=/home/asr-user/asr-llm-tts/Backend/venv/bin
ExecStart=/home/asr-user/asr-llm-tts/Backend/venv/bin/python server.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# 启用服务
sudo systemctl daemon-reload
sudo systemctl enable asr-llm-tts
sudo systemctl start asr-llm-tts

# 查看状态
sudo systemctl status asr-llm-tts

🔍 テストと検証

1. 基本機能のテスト

# 启动服务器
python server.py

# 在另一个终端测试API
curl http://localhost:8000/

# 预期输出：
# {"message": "ASR-LLM-TTS Backend is running and core components are initialized."}

2. WebSocket 接続のテスト

# 使用测试脚本
python test/test_websocket_client.py

3. 音声機能のテスト

# 测试音频播放器
python test/audio_tests/test_audio_player_new.py

# 测试设备检测
python utils/audio_config/check_audio_devices.py

# 测试录音功能（ASR模式）
python test/audio_tests/test_recording_simple.py

4. コンポーネントの統合テスト

# 测试LLM客户端
python test/test_llm.py

# 测试TTS合成
python test/test_tts_integration.py

# 测试Function Calling
python test/test_function_call.py

📊 パフォーマンスの監視

1. システムリソースの監視

# CPU和内存使用
htop

# 磁盘I/O
iotop

# 网络连接
netstat -tulpn | grep :8000

2. アプリケーションログの監視

# 实时查看日志
tail -f backend.log

# 过滤特定组件日志
grep "LLM" backend.log
grep "TTS" backend.log  
grep "ASR" backend.log

3. パフォーマンス指標の収集

# 在server.py中添加性能监控
import psutil
import time

class PerformanceMonitor:
    def __init__(self):
        self.start_time = time.time()

    def get_system_stats(self):
        return {
            "uptime": time.time() - self.start_time,
            "cpu_percent": psutil.cpu_percent(),
            "memory_percent": psutil.virtual_memory().percent,
            "disk_usage": psutil.disk_usage('/').percent
        }

# 添加监控端点
@app.get("/metrics")
async def metrics():
    monitor = PerformanceMonitor()
    return monitor.get_system_stats()

🛠️ トラブルシューティング

よくある問題と解決方法

1. サービスが起動しない

# 检查端口占用
sudo netstat -tulpn | grep :8000

# 检查Python环境
which python
python --version

# 检查依赖安装
pip list | grep fastapi

2. 音声の問題

# 重启音频服务
pulseaudio -k && pulseaudio --start

# 检查音频设备权限
groups $USER | grep audio

# 测试音频输出
speaker-test -c 2 -t wav

3. API 接続の問題

# 测试网络连接
curl -v https://ark.cn-beijing.volces.com

# 检查API密钥
grep VOLCENGINE .env

# 验证配置文件语法
python -c "import yaml; yaml.safe_load(open('config.yaml'))"

4. メモリ不足

# 查看内存使用
free -h

# 查看进程内存
ps aux --sort=-%mem | head

# 清理系统缓存
sudo sync && echo 3 | sudo tee /proc/sys/vm/drop_caches

🔧 最適化の推奨事項

1. パフォーマンスの最適化

CPU の最適化

# config.yaml
asr:
  num_threads: 4  # 根据CPU核心数调整

llm:
  parameters:
    max_tokens: 2048  # 减小以降低处理时间

メモリの最適化

# 在server.py中添加内存管理
import gc

# 定期清理内存
async def cleanup_memory():
    gc.collect()
    await asyncio.sleep(300)  # 每5分钟清理一次

asyncio.create_task(cleanup_memory())

ネットワークの最適化

# config.yaml
llm:
  timeout: 15  # 调整API超时时间

tts:
  connection_timeout: 10
  read_timeout: 30

2. セキュリティの強化

# 设置文件权限
chmod 600 .env
chmod 644 config.yaml

# 限制网络访问（生产环境）
sudo ufw deny from any to any port 8000
sudo ufw allow from 192.168.1.0/24 to any port 8000  # 仅允许内网访问

3. 高可用性の設定

Nginx リバースプロキシの使用

# /etc/nginx/sites-available/asr-llm-tts
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

プロセスの常駐化

# 安装supervisor
sudo apt install supervisor

# 配置文件 /etc/supervisor/conf.d/asr-llm-tts.conf
[program:asr-llm-tts]
command=/home/asr-user/asr-llm-tts/Backend/venv/bin/python server.py
directory=/home/asr-user/asr-llm-tts/Backend
user=asr-user
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/var/log/asr-llm-tts.log

本デプロイガイドに従うことで、さまざまな環境に ASR-LLM-TTS 音声対話アシスタントシステムを正常にデプロイできます。問題がある場合は、トラブルシューティングの項を参照するか、詳細なログ情報を確認してください。