8.3 KiB
快速入门指南
只需几分钟即可使用预构建的 Docker 镜像运行 Speakr！本指南将带你了解部署 Speakr 的最快方法，支持使用 OpenAI Whisper API 或自定义 ASR 端点。
注意： 如果你想使用 ASR 端点选项来实现说话人分离功能，你需要运行一个额外的 Docker 容器（
onerahmet/openai-whisper-asr-webservice）。请参阅运行 ASR 服务以支持说话人分离获取详细的设置说明。
前置条件
开始之前，请确保你的系统上已安装 Docker 和 Docker Compose。你还需要一个 API 密钥（OpenAI 或 OpenRouter，或兼容服务），至少 2GB 可用内存，以及约 10GB 可用磁盘空间用于存储录音和转录内容。
步骤 1：创建项目目录
首先，为 Speakr 安装创建一个目录并进入：
mkdir speakr
cd speakr
步骤 2：下载配置文件
下载 Docker Compose 配置，并根据你选择的转录服务选择合适的环境模板：
# Download docker compose example
wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/docker-compose.example.yml -O docker-compose.yml
现在下载环境配置模板。根据你要使用的转录服务，你有两种选择。
使用标准 OpenAI Whisper API（推荐大多数用户使用）：
wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/env.whisper.example -O .env
或使用带说话人分离功能的自定义 ASR 端点（需要额外的 ASR 容器——见下方说明）：
wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/env.asr.example -O .env
重要： ASR 端点选项需要与 Speakr 一起运行一个额外的 Docker 容器（
onerahmet/openai-whisper-asr-webservice）。有关完整的设置说明，包括两个容器的 docker-compose 配置，请参阅运行 ASR 服务以支持说话人分离。
步骤 3：配置你的转录服务
在你喜欢的文本编辑器中打开 .env 文件，并根据你选择的服务进行配置。
选项 A：OpenAI Whisper 配置
如果你使用 OpenAI Whisper，你需要同时设置转录服务和文本生成模型。文本生成模型用于创建摘要、生成标题和驱动聊天功能。
编辑你的 .env 文件并更新以下关键变量：
# For text generation (summaries, chat, titles)
TEXT_MODEL_BASE_URL=https://openrouter.ai/api/v1
TEXT_MODEL_API_KEY=your_openrouter_api_key_here
TEXT_MODEL_NAME=openai/gpt-4o-mini
# For transcription
TRANSCRIPTION_BASE_URL=https://api.openai.com/v1
TRANSCRIPTION_API_KEY=your_openai_api_key_here
WHISPER_MODEL=whisper-1
文本模型可以使用 OpenRouter 来访问各种 AI 模型，或者你可以将其直接指向 OpenAI，使用与转录服务相同的基础 URL 和 API 密钥。OpenRouter 提供对多种模型的访问，包括 GPT-4、Claude 等，对于文本生成任务来说可能更具成本效益。
选项 B：自定义 ASR 端点配置
前置条件： 此选项需要运行一个额外的 ASR 服务容器（
onerahmet/openai-whisper-asr-webservice）。你可以：
- 在同一个 Docker Compose 栈中运行两个容器（推荐）——请参阅完整设置指南
- 在同一台或不同的机器上单独运行 ASR 服务
- 如果你已经部署了现有的 ASR 服务，可以直接使用
如果你使用的是自定义 ASR 服务（如 WhisperX 或自托管的 Whisper 服务器），请配置以下变量：
# For text generation (summaries, chat, titles)
TEXT_MODEL_BASE_URL=https://openrouter.ai/api/v1
TEXT_MODEL_API_KEY=your_openrouter_api_key_here
TEXT_MODEL_NAME=openai/gpt-4o-mini
# Enable ASR endpoint
USE_ASR_ENDPOINT=true
# ASR service URL (use container name if in same docker compose)
ASR_BASE_URL=http://whisper-asr:9000
当使用 ASR 端点时，说话人分离功能会自动启用，使 Speakr 能够识别录音中的不同说话人。转录完成后，你需要识别说话人来构建你的说话人库。ASR_BASE_URL 应指向你的 ASR 服务。如果你在同一个 Docker Compose 栈中运行 ASR 服务，请使用容器名称和内部端口（如 http://whisper-asr:9000）。对于外部服务，请使用带有适当 IP 地址或域名的完整 URL。
步骤 4：配置管理员账户
Speakr 会在首次启动时自动创建一个管理员用户。在启动之前，请在 .env 文件中配置这些凭据：
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=changeme
确保将这些值更改为更安全的值，尤其是密码。当你首次启动 Speakr 时，该管理员账户将自动创建，你将使用这些凭据进行登录。通过此方法创建的第一个用户将成为系统管理员，拥有对所有功能的完全访问权限，包括用户管理和系统设置。
步骤 5：启动 Speakr
配置完成后，使用 Docker Compose 启动 Speakr：
docker compose up -d
首次启动需要几分钟时间，因为 Docker 需要下载预构建镜像（约 3GB）并初始化数据库。你可以通过查看日志来监控启动过程：
docker compose logs -f app
查找表示 Flask 应用程序正在运行并已准备好接受连接的消息。按 Ctrl+C 退出日志视图（这不会停止容器）。
步骤 6：访问 Speakr
容器运行后，打开你的 Web 浏览器并访问：
http://localhost:8899
使用你在步骤 4 中配置的管理员凭据登录。现在你应该能看到 Speakr 仪表盘，已准备好进行你的第一次录音。
你的第一次录音
登录后，你可以立即开始使用 Speakr。点击顶部导航栏中的"New Recording"按钮，上传现有音频文件或开始现场录音。有关详细说明，请参阅录音指南。对于上传文件，Speakr 支持常见音频格式，如 MP3、M4A、WAV 等，默认文件大小限制为 500MB。你可以在系统设置中调整此限制。对于现场录音，你可以从麦克风、系统音频或同时进行录制。
可选功能
启用 Inquire 模式
Inquire 模式允许你使用自然语言问题在所有录音中进行搜索。在功能指南中了解更多关于语义搜索功能的信息。要启用它，请在 .env 文件中设置：
ENABLE_INQUIRE_MODE=true
然后使用 docker compose restart 重启容器以使更改生效。
启用用户注册
默认情况下，只有管理员可以创建新用户。在管理员指南中了解更多关于用户管理的信息。要允许自行注册，请设置：
ALLOW_REGISTRATION=true
配置你的时区
设置本地时区以显示准确的时间戳：
TIMEZONE="America/New_York"
使用 TZ 数据库中的任何有效时区，如"Europe/London"、"Asia/Tokyo"或"UTC"。
停止和启动 Speakr
要停止 Speakr 同时保留所有数据：
docker compose down
要再次启动：
docker compose up -d
你的录音、转录内容和设置将保存在主机系统上的 ./uploads 和 ./instance 目录中。
故障排除
如果 Speakr 无法正常启动，请使用 docker compose logs app 检查日志中的错误信息。有关更详细的帮助，请参阅故障排除指南，特别是安装问题部分。常见问题包括 API 密钥不正确（日志中会显示身份验证错误）或端口冲突（如果其他服务正在使用 8899 端口）。你可以通过编辑 docker-compose.yml 文件并修改 ports 部分来更改端口。
如果转录失败，请验证你的 API 密钥是否正确，并且你选择的服务有足够的额度。日志将显示详细的错误信息，有助于识别问题。
下一步：安装指南（用于生产部署和高级配置）