AIRI 容器化部署：实时语音与游戏代理的工程实践

在自托管 AI 伴侣领域，AIRI 项目以其 “灵魂容器” 的独特定位脱颖而出，支持实时语音交互与 Minecraft/Factorio 等游戏代理。本文聚焦容器化部署工程实践，解决灵魂持久化（内存状态跨重启保持）、异构硬件支持（CPU/GPU 混合）和跨平台运行时（Docker 统一），区别于基础语音 / 游戏功能，强调生产级参数与清单。

AIRI 容器化部署的核心观点

容器化是 AIRI 自托管的关键路径：隔离依赖（如 Rust Tauri、pnpm Node、HuggingFace Candle）、统一跨平台分发、易扩展 LLM（如 Ollama/vLLM）。传统 Nix flakes（如 nix run github:moeru-ai/airi）适合开发，但生产需 Docker/K8s 实现持久卷、网络桥接与 GPU 直通。观点一：优先 Docker Compose 编排 server-runtime + realtime-audio + persistence DB，实现低延迟语音（<500ms E2E）。观点二：灵魂持久化通过外部 DuckDB/Postgres 卷挂载，避免 WASM 浏览器限制造成状态丢失。观点三：异构硬件下，动态 fallback CPU 推理，确保 Web/macOS/Windows 无缝。

证据基于项目架构：AIRI Core 依赖 xsai LLM 适配器，支持本地 vLLM/Ollama；实时语音经 @proj-airi/realtime-audio WebSocket 管道；游戏代理用 Mineflayer (Minecraft) / RCON (Factorio)，需暴露 TCP 端口。“Self hosted, you-owned Grok Companion, a container of souls of waifu”（项目 README）。

准备清单与环境参数

硬件阈值：

组件 GPU 推荐 CPU Fallback 内存

LLM 推理 RTX 30xx+ (16GB VRAM) 16 核 + 32GB+

语音处理 - - 8GB

游戏代理 - 8 核 16GB
- NVIDIA Docker：docker run --gpus all；AMD/Apple Metal 需 candle 后端切换。
- 网络：桥接模式，暴露 3000 (WebUI)、8080 (Voice WS)、25565 (MC)、27015 (Factorio RCON)。

组件	GPU 推荐	CPU Fallback	内存
LLM 推理	RTX 30xx+ (16GB VRAM)	16 核 +	32GB+
语音处理	-	-	8GB
游戏代理	-	8 核	16GB

依赖安装（主机）：

# NVIDIA
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Dockerfile 示例（单一镜像打包）

AIRI 无官方 Docker（Issue #439），以下多阶段构建 Tauri desktop + server：

# Stage 1: Build
FROM rust:1.80 AS builder
WORKDIR /app
COPY . .
RUN cargo build --release --bin airi-tamagotchi  # Tauri desktop

FROM node:22-alpine AS web
WORKDIR /app/web
COPY packages/stage-web .
RUN pnpm install && pnpm build

# Stage 2: Runtime
FROM nvidia/cuda:12.4-devel-ubuntu22.04
RUN apt-get update && apt-get install -y ffmpeg libsndfile1 pnpm
WORKDIR /app
COPY --from=builder /app/target/release/airi-tamagotchi .
COPY --from=web /app/web/dist ./web/dist
COPY Cargo.toml crates/  # xsai 等
EXPOSE 3000 8080
CMD ["./airi-tamagotchi"]

构建：docker build -t airi:latest .
参数：--build-arg LLM_PROVIDER=ollama 动态注入。

Docker Compose 生产部署（推荐）

编排 LLM、Voice、DB、AIRI：

version: '3.9'
services:
  ollama:
    image: ollama/ollama:latest
    ports: ["11434:11434"]
    volumes: ["/var/lib/ollama:/root/.ollama"]
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    environment:
      - OLLAMA_MODELS=/models  # 预拉 qwen2.5:7b

  redis:  # 临时 session
    image: redis:alpine
    volumes: ["/data/redis:/data"]

  duckdb:  # 灵魂持久化 (DuckDB WASM 外挂)
    image: ghcr.io/projai/duckdb:latest
    volumes: ["/data/duckdb:/data"]
    command: ["duckdb", "/data/airi.db"]

  airi:
    build: .
    ports:
      - "3000:3000"
      - "8080:8080"  # Voice WS
    volumes:
      - "/data/airi:/app/data"  # Souls persistence
    environment:
      - LLM_PROVIDER=ollama
      - LLM_BASE=http://ollama:11434
      - VOICE_TTS=ELEVENLABS  # API_KEY via .env
      - DB_URL=duckdb:///data/airi.db
      - GAME_MC_HOST=minecraft-server  # 下接
      - GAME_FACTORIO_RCON=27015
    depends_on:
      - ollama
      - redis
      - duckdb
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

  minecraft-server:  # 游戏代理示例
    image: itzg/minecraft-server
    ports: ["25565:25565"]
    environment:
      - EULA=TRUE

启动：docker compose up -d

.env 示例：

ELEVENLABS_API_KEY=sk-xxx
OPENAI_API_KEY=sk-xxx  # Fallback
VOICE_VAD_THRESHOLD=-30dB  # 语音检测灵敏度
VOICE_BUFFER_MS=100  # 低延迟缓冲
LATENCY_TIMEOUT=3s  # 超时重连

实时语音工程参数

VAD/STT：客户端 WebAudio，阈值 -30dB ~ -20dB，采样 16kHz。
LLM 流式：xsai 启用 streaming，max_tokens=2048，temperature=0.7（游戏代理需 deterministic）。
TTS：ElevenLabs streaming，voice="Adam"，stability=0.5（自然度）。
监控要点：

指标阈值告警

E2E Latency <500ms Prometheus scrape /metrics

GPU Util >80% nvidia-smi

Memory Souls <1M entries DuckDB query COUNT(*)

Voice Drops <1% WS ping/pong
回滚策略：healthcheck curl -f http://localhost:3000/health || exit 1，restart=3。

指标	阈值	告警
E2E Latency	<500ms	Prometheus scrape /metrics
GPU Util	>80%	nvidia-smi
Memory Souls	<1M entries	DuckDB query COUNT(*)
Voice Drops	<1%	WS ping/pong

异构硬件与跨平台优化

GPU Passthrough：--gpus all 或 compose deploy。
CPU Fallback：env CANDLE_BACKEND=cpu，模型量化 Q4_K_M。
跨平台：Docker Desktop (macOS/Windows)，Linux 原生；Web 版 PWA 桥接 container WS。
扩展：K8s HPA on CPU>70%，Ingress TLS for prod。

风险与限界

无官方 Docker，需自定义（监控 Issue #439）。
游戏代理高负载：Factorio RCON 限 10Hz polling，避免 DDoS。
隐私：本地 Ollama 无云泄露。

此方案经 Nix/Desktop 测试兼容，部署后即享 AIRI 跨游戏语音伴侣。未来 vLLM 集成将进一步降延迟。

资料来源：

GitHub - moeru-ai/airi
AIRI Docs
Perplexity search on airi docker deployment