Open-LLM-VTuber 是一个开源的 AI 虚拟伴侣项目，让你能够通过语音与大语言模型实时对话，并搭配 Live2D 动态形象进行互动。由于项目目前正处于向 v2.0 过渡的开发阶段，本教程将根据其主仓库及社区指南，为你整理一套兼容当前主流版本（v1.x 及以上）的详细部署指南。

重要提示：项目从 v1.0.0 版本开始有破坏性变更，如果从更早的版本升级，旧的 conf.yaml 配置文件不兼容，大部分依赖也需要用 uv 重新安装。开发者强烈建议在部署新版本时，参考本文档全新部署一次。

一、核心功能与准备工作

在你开始部署之前，可以先了解它的核心功能和准备工作，以便选择合适的部署方式。

1.1 核心功能概览

Open-LLM-VTuber 整合了多项前沿的 AI 技术，让虚拟角色“活”起来：

  • 🎤 语音交互与打断：支持免提语音对话，并可以用声音随时打断 AI。
  • 👁️ 视觉感知（部分版本）：支持接入摄像头或屏幕录制，让 AI 能够“看到”你。
  • 😊 Live2D 动态表情：后端可以控制模型的表情变化，增强互动感。
  • 🐱 桌面宠物模式：支持透明背景、窗口置顶和鼠标穿透，让 AI 形象常驻屏幕。
  • 💬 其他交互细节：能显示AI内心想法、支持主动说话、聊天记录持久化等。

1.2 部署方式选择

根据你的使用场景，可以选择以下两种方式：

部署方式 特点 适用场景
本地桌面端 功能最完整，支持桌面宠物、窗口置顶等深度本地交互 主要在个人电脑上使用，追求最佳体验和隐私
Web 服务端 部署灵活，可通过浏览器跨设备访问，适合服务器远程部署 需要在多设备（如手机、平板）或远程访问

选择建议：如果你希望这个 AI 伴侣不仅能在电脑前使用，还能在外出时通过手机访问，建议选择 Web 服务端 部署方式。

1.3 基础环境要求

无论选择哪种方式，都需要满足以下基础条件：

  • 操作系统：Windows、macOS 或 Linux 均可。
  • Python版本：需要 Python >= 3.10, < 3.13。注意 Python 3.13 可能存在依赖安装问题。
  • FFmpeg：必须在系统中安装 FFmpeg。
  • 包管理工具：v1.0.0 之后，项目推荐使用 uv 作为包管理器。

二、详细部署步骤（Web服务端推荐）

下面的步骤以部署 Web 版本为主要示例，这种方式最灵活，也便于远程访问。

第1步：克隆仓库与准备环境

  1. 克隆项目：

    1
    2
    git clone https://github.com/Open-LLM-VTuber/Open-LLM-VTuber.git
    cd Open-LLM-VTuber

  2. 创建虚拟环境（强烈推荐）：这可以避免依赖冲突。

    1
    2
    3
    4
    5
    6
    7
    # 使用 Python 内置的 venv
    python -m venv open-llm-vtuber

    # 激活环境 (Windows)
    open-llm-vtuber\Scripts\activate
    # 激活环境 (macOS/Linux)
    source open-llm-vtuber/bin/activate

第2步：安装依赖与配置

  1. 安装 uv 和项目依赖：v1.0.0 后推荐使用 uv 进行更快的依赖管理。

    1
    2
    pip install uv
    uv pip install -r requirements.txt

  2. 配置核心模块 (conf.yaml)：所有主要设置都在项目根目录的 conf.yaml 文件中。你需要根据选择的服务，至少配置一个 LLM（大语言模型）、ASR（语音识别）和 TTS（语音合成）模块。

    • LLM 配置示例 (以 Ollama 为例)：

      1
      2
      3
      4
      5
      6
      7
      8
      9
      agent_config:
        agent_settings:
          basic_memory_agent:
            llm_provider: 'ollama_llm' # 指定使用 Ollama

      llm_configs:
        ollama_llm:
          model: 'llama3' # 你安装的模型名
          api_base: 'http://localhost:11434' # Ollama 默认地址

    • ASR 配置示例 (以 FunASR 本地模型为例)：

      1
      2
      3
      4
      5
      asr_config:
        asr_model: 'fun_asr' 
        fun_asr:
          model_name: 'iic/SenseVoiceSmall' # 轻量级模型
          device: 'auto' # 自动选择 CPU/CUDA

    • TTS 配置示例 (以免费的 Edge TTS 为例)：

      1
      2
      3
      4
      tts_config:
        tts_model: 'edge_tts'
        edge_tts:
          voice: 'zh-CN-XiaoxiaoNeural' # 选择你喜欢的语音

第3步：启动服务

  • 运行 Web 服务：

    1
    python run_server.py

    默认情况下，Web 界面会运行在 http://127.0.0.1:12393。

第4步：实现远程访问（可选）

如果你需要从外网（如手机移动网络）访问这个 Web 服务，可以通过内网穿透工具（如 cpolar）将本地端口映射到一个公网地址。

  • 重要安全提示：由于浏览器麦克风权限要求，若要从非 localhost 的远程地址访问，必须为你的服务配置 HTTPS，否则无法使用语音输入功能。

三、进阶配置与知识

3.1 多角色切换配置

项目支持在 characters/ 目录下创建多个 YAML 配置文件，实现角色快速切换。你可以轻松定义角色的名字、人设提示词，甚至为不同角色指定不同的 TTS 音色或 LLM 模型。

  • 示例：创建一个 my_character.yaml 文件，只需定义你想覆盖的配置项，其他则会继承自 conf.yaml。

3.2 更新、卸载与重要版本提示

  • 更新：对于 v1.0.0 之后的版本，可使用 uv run update.py 进行更新。
  • 卸载：大部分文件都存储在项目文件夹中，直接删除项目目录即可。但请注意检查 MODELSCOPE_CACHE 或 HF_HOME 等环境变量指向的路径，下载的模型可能存储在那里。
  • v2.0 开发状态：项目团队目前正全力投入 v2.0 的完全重写工作，v1.x 分支将主要进行错误修复。新功能讨论和开发贡献主要在其开发者社区（Zulip）进行。

总结

部署 Open-LLM-VTuber 的核心步骤是：准备 Python 3.10/3.11 环境 → 克隆项目并用 uv 安装依赖 → 编辑 conf.yaml 配置 LLM/ASR/TTS 模块 → 运行 run_server.py。推荐使用虚拟环境隔离依赖，并根据使用场景选择本地桌面端或灵活的 Web 服务端。如果遇到 v1.x 版本的问题，可查阅官方提供的常见问题文档。