跳到主要内容

在 OPL 数据空间中使用 Mistral Voxtral 做语音转文字

本指南介绍如何把 Mistral 的 Voxtral 模型用于 OPL 数据空间的 Speech-to-Text。

需要 TTS？

对应的语音合成说明见 Using Mistral for Text-to-Speech。

前提​

  • 一个可用的 Mistral API Key
  • 正在运行的 OPL 数据空间

快速配置（UI）​

  1. 点击左下角头像
  2. 进入 管理员面板
  3. 打开 设置 → 语音
  4. 设置：
设置项值
Speech-to-Text EngineMistralAI
API Key你的 Mistral API Key
STT Modelvoxtral-mini-latest，也可留空使用默认值
  1. 点击 Save

可用模型​

模型说明
voxtral-mini-latest推荐的默认转写模型

环境变量配置​

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    environment:
      - AUDIO_STT_ENGINE=mistral
      - AUDIO_STT_MISTRAL_API_KEY=your-mistral-api-key
      - AUDIO_STT_MODEL=voxtral-mini-latest

常用变量​

变量说明默认值
AUDIO_STT_ENGINE设为 mistral空
AUDIO_STT_MISTRAL_API_KEYMistral API Key空
AUDIO_STT_MISTRAL_API_BASE_URLMistral API 地址https://api.mistral.ai/v1
AUDIO_STT_MISTRAL_USE_CHAT_COMPLETIONS是否走 chat completionsfalse
AUDIO_STT_MODELSTT 模型voxtral-mini-latest

转写方式​

Mistral 支持两种方式：

标准转写（默认）​

使用专门的 transcription endpoint，通常是推荐方式。

Chat Completions 方式​

如果设置 AUDIO_STT_MISTRAL_USE_CHAT_COMPLETIONS=true，就会通过 chat completions 做转写：

  • 要求音频为 mp3 或 wav（系统会尝试自动转换）
  • 输出结果可能与标准接口略有不同

使用方式​

  1. 点击聊天输入框旁的麦克风图标
  2. 说话
  3. 再次点击麦克风，或等待静音检测
  4. 转写结果会填入输入框

支持的音频格式​

默认接受 audio/* 和 video/webm。如果走 chat completions 方式，系统会自动尝试转成 mp3。

故障排查​

API Key 错误​

如果看到 “Mistral API key is required”：

  1. 检查 API Key 是否填对
  2. 检查 Key 是否已过期
  3. 确认账号具备 API 访问权限

转写无结果​

  1. 查看容器日志：docker logs open-webui -f
  2. 确认 STT 引擎确实设置为 MistralAI
  3. 优先尝试标准转写方式

音频格式问题​

如果 chat completions 方式下转换失败：

  • 确认容器内有 FFmpeg
  • 尝试录制成 wav 或 mp3
  • 或切回标准转写方式

更多问题见 音频排障指南。