Voice Assistant

语音助手

一个使用 LiveKit、Cartesia、OpenAI、Silero 和多内容处理器 (MCP) 进行 WhatsApp 集成的简单语音助手。

前置要求

• Python >=3.13
• uv（Python 包管理器和虚拟环境管理器）

设置

1. 克隆仓库：

   git clone <your-repo-url>
   cd voice-assistant
   

2. 创建并激活虚拟环境（使用 uv）：

   uv venv
   source .venv/bin/activate  # 在 Linux/macOS 上
   # .\.venv\Scripts\activate    # 在 Windows 上
   

3. 安装依赖：

   uv sync
   

4. 设置环境变量：

   在项目根目录创建名为 .env 的文件，并添加以下环境变量及其实际值。 你可以复制下面的示例：

   LIVEKIT_URL=
   LIVEKIT_API_KEY=
   LIVEKIT_API_SECRET=
   CARTESIA_API_KEY=
   OPENAI_API_KEY=
   

   • LIVEKIT_URL：你的 LiveKit 服务器 URL。
   • LIVEKIT_API_KEY：你的 LiveKit API 密钥。
   • LIVEKIT_API_SECRET：你的 LiveKit API 密钥。
   • CARTESIA_API_KEY：你的 Cartesia API 密钥，用于文本转语音。
   • OPENAI_API_KEY：你的 OpenAI API 密钥，用于语音转文本和大模型操作。

5. 配置 WhatsApp MCP（多内容处理器）：

   此项目使用 MCP 与 WhatsApp 交互。你需要运行并配置 WhatsApp MCP 服务。

   使用正确的路径更新项目根目录中的 mcp_config.json 文件以进行 MCP 设置：

   {
     "mcpServers": {
       "whatsapp": {
         "command": "{{PATH_TO_UV}}",
         "args": [
           "--directory",
           "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server",
           "run",
           "main.py"
         ]
       }
     }
   }
   

   • 将 {{PATH_TO_UV}} 替换为 uv 可执行文件的绝对路径。你可以在终端上运行 which uv（Linux/macOS）或 where uv（Windows）找到此路径。
   • 将 {{PATH_TO_SRC}} 替换为包含 whatsapp-mcp 项目的目录的绝对路径。例如，如果你的 whatsapp-mcp 项目在 /Users/me/dev/whatsapp-mcp，那么此值应为 /Users/me/dev。配置中的最终路径为 /Users/me/dev/whatsapp-mcp/whatsapp-mcp-server。

运行助手

1. （可选）下载必要的模型文件（例如 Silero VAD）： voice.py 脚本可能有一个命令或在首次运行时自动下载必要的模型。下面的示例显示一个假设的命令，如果你的 voice.py 支持该命令。

   # 如果你的 voice.py 有下载命令，例如：
   # uv run python voice.py download-files
   

   目前，voice.py 脚本使用 livekit.agents.cli.run_app，它通常为 Silero 等插件处理自己的设置。

2. 启动语音助手：

   uv run voice-assistant-cli
   

   这使用 pyproject.toml 中定义的 voice-assistant-cli 脚本。

连接到 Playground

助手运行后，你可以在浏览器中加载 LiveKit Agents Playground，并连接到本地 Agent。

---

注意：此 README 假设你已在系统 PATH 中安装并配置了 uv。