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