以下将逐行解释，并提供完整的、标准的主机本地部署流程。

一、环境前提

• Python 3.12+（务必用新版）
• uv 包管理器（不是pip，uv官方文档）

二、详细步骤

1. 安装 Python 3.12+ （按需）

Ubuntu 用户可这样安装最新版 Python（如未自带3.12）：

sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y python3.12 python3.12-venv python3.12-dev

2. 安装 uv 包管理器

uv 是一个高速的 Python 包管理工具，比 pip 更快更现代。

sudo apt install pip
sudo pip install uv
uv --version

3. 克隆 Speaches 源码

git clone https://github.com/speaches-ai/speaches.git
cd speaches

4. 创建虚拟环境

官方用法：

uv venv

这会自动创建 .venv 虚拟环境目录。

5. 激活虚拟环境

source .venv/bin/activate

6. 安装所有依赖（含所有扩展）

uv sync --all-extras

> 这一步会自动解析 pyproject.toml，安装所有依赖，等价于 pip install -e .[all]。

7. 启动服务

uvicorn --factory --host 0.0.0.0 speaches.main:create_app

• 这会监听所有网卡8000端口（可用 --port 8000 指定端口）
• 默认可以直接访问 http://localhost:8000/docs 查看API文档

三、模型下载与管理

激活虚拟环境后，也可以用官方 CLI 下载模型：

查询可用模型

uvx speaches-cli registry ls --task automatic-speech-recognition

下载模型

uvx speaches-cli model download Systran/faster-whisper-medium 或查上一步输出的模型ID下载

查看已安装模型

uvx speaches-cli model ls --task automatic-speech-recognition

四、实现开机时自动启动

大多数现代 Linux 发行版（如 Ubuntu, Debian, CentOS, Fedora）都使用 systemd 来管理系统服务。这是最稳定和推荐的方法。

第 1 步：创建服务文件

首先，我们需要创建一个 systemd 服务单元文件。

使用您喜欢的文本编辑器（如 nano 或 vim）创建一个新文件：

sudo nano /etc/systemd/system/speaches.service

然后，将以下内容复制并粘贴到文件中。

[Unit]
Description=Speaches OpenAI Compatible Server
After=network.target

[Service]
# 运行服务的用户和用户组，建议使用您的普通用户名
User=your_username
Group=your_username
# 替换为您的项目实际所在的目录
WorkingDirectory=/path/to/your/project/speaches

# 服务的启动命令。注意这里使用的是虚拟环境中的uvicorn
ExecStart=/path/to/your/project/speaches/.venv/bin/uvicorn --factory --host 0.0.0.0 speaches.main:create_app
# 避免实时转写报错
Environment="LOOPBACK_HOST_URL=http://localhost:8000"

# 确保服务在失败时会自动重启
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

重要：

• User 和 Group: 将 your_username 替换为你登录 Linux 系统的用户名。
• WorkingDirectory: 将 /path/to/your/project/speaches 替换为 speaches 项目的 绝对路径。
• ExecStart: 同样，将 /path/to/your/project/speaches 替换为项目的绝对路径。这里我们直接指定了虚拟环境 .venv/bin/ 中的 uvicorn 可执行文件，这样可以确保使用了正确的 Python 环境和依赖。

第 2 步：重载、启用并启动服务

保存并关闭 编辑器 (在 nano 中，按 Ctrl+X，然后按 Y，再按 Enter)。

重载 systemd，使其识别到新的服务文件：

sudo systemctl daemon-reload

启用服务，这样它就会在开机时自动启动：

sudo systemctl enable speaches.service

立即启动服务，无需重启电脑：

sudo systemctl start speaches.service

第 3 步：检查服务状态

你可以随时检查服务的运行状态，看看是否有错误：

sudo systemctl status speaches.service

如果看到 active (running)，说明服务已成功运行。还可以使用 journalctl -u speaches.service -f 来实时查看服务的日志输出。

附录：关于硬件配置与类似工具