Merge pull request #430 from danielrosehill/STT

Speech To Text (STT) Documentation

docs/tutorials/maintenance/_category_.json

@@ -0,0 +1,7 @@
+{
+	"label": "🛠️ Maintenance",
+	"position": 5,
+	"link": {
+		"type": "generated-index"
+	}
+}

docs/tutorials/maintenance/backups.md

@@ -0,0 +1,305 @@
+---
+sidebar_position: 1000
+title: "💾 Backups"
+---
+ 
+ :::warning
+This tutorial is a community contribution and is not supported by the Open WebUI team. It serves only as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
+:::
+
+ #  Backing Up Your Instance
+
+ Nobody likes losing data! 
+
+ If you're self-hosting OpenWebUI, then you may wish to institute some kind of formal backup plan in order to ensure that you retain a second and third copy of parts of your configuration.
+
+ This guide is intended to recommend some basic recommendations for how users might go about doing that. 
+
+ This guide assumes that the user has installed OpenWebUI via Docker (or intends to do so)
+
+ ## Ensuring data persistence
+
+Firstly, before deploying your stack with Docker, ensure that your Docker Compose uses a persistent data store. If you're using the Docker Compose [from the Github repository](https://github.com/open-webui/open-webui/blob/main/docker-compose.yaml) that's already taken care of. But it's easy to cook up your own variations and forget to verify this.
+
+Docker containers are ephemeral and data must be persisted to ensure its survival on the host filesystem.
+
+## Using Docker volumes
+
+If you're using the Docker Compose from the project repository, you will be deploying Open Web UI using Docker volumes. 
+
+For Ollama and OpenWebUI the mounts are:
+
+```yaml
+ollama:
+  volumes:
+    - ollama:/root/.ollama
+```
+
+```yaml
+open-webui:
+  volumes:
+    - open-webui:/app/backend/data
+```
+
+To find the actual bind path on host, run:
+
+`docker volume inspect ollama` 
+
+and
+
+`docker volume inspect open-webui`
+
+## Using direct host binds
+
+Some users deploy Open Web UI with direct (fixed) binds to the host filesystem, like this:
+
+```yaml
+services:
+  ollama:
+    container_name: ollama
+    image: ollama/ollama:${OLLAMA_DOCKER_TAG-latest}
+    volumes:
+      - /opt/ollama:/root/.ollama
+  open-webui:
+    container_name: open-webui
+    image: ghcr.io/open-webui/open-webui:${WEBUI_DOCKER_TAG-main}
+    volumes:
+      - /opt/open-webui:/app/backend/data
+```
+
+If this is how you've deployed your instance, you'll want to note the paths on root. 
+
+## Scripting A Backup Job
+
+However your instance is provisioned, it's worth inspecting the app's data store on your server to understand what data you'll be backing up. You should see something like this:
+
+```
+├── audit.log
+├── cache/
+├── uploads/
+├── vector_db/
+└── webui.db
+```
+
+## Files in persistent data store 
+
+| File/Directory | Description |
+|---|---|
+| `audit.log` | Log file for auditing events. |
+| `cache/` | Directory for storing cached data. |
+| `uploads/` | Directory for storing user-uploaded files. |
+| `vector_db/` | Directory containing the ChromaDB vector database. |
+| `webui.db` | SQLite database for persistent storage of other instance data |
+
+# File Level Backup Approaches
+
+The first way to back up the application data is to take a file level backup approach ensuring that the persistent Open Web UI data is properly backed up.
+
+There's an almost infinite number of ways in which technical services can be backed up, but `rsync` remains a popular favorite for incremental jobs and so will be used as a demonstration.
+
+Users could target the entire `data` directory to back up all the instance data at once or create more selective backup jobs targeting individual components. You could add more descriptive names for the targets also. 
+
+A model rsync job could look like this:
+
+```bash
+#!/bin/bash
+
+# Configuration
+SOURCE_DIR="."  # Current directory (where the file structure resides)
+B2_BUCKET="b2://OpenWebUI-backups" # Your Backblaze B2 bucket
+B2_PROFILE="your_rclone_profile" # Your rclone profile name
+# Ensure rclone is configured with your B2 credentials
+
+# Define source and destination directories
+SOURCE_UPLOADS="$SOURCE_DIR/uploads"
+SOURCE_VECTORDB="$SOURCE_DIR/vector_db"
+SOURCE_WEBUI_DB="$SOURCE_DIR/webui.db"
+
+DEST_UPLOADS="$B2_BUCKET/user_uploads"
+DEST_CHROMADB="$B2_BUCKET/ChromaDB"
+DEST_MAIN_DB="$B2_BUCKET/main_database"
+
+# Exclude cache and audit.log
+EXCLUDE_LIST=(
+    "cache/"
+    "audit.log"
+)
+
+# Construct exclude arguments for rclone
+EXCLUDE_ARGS=""
+for EXCLUDE in "${EXCLUDE_LIST[@]}"; do
+    EXCLUDE_ARGS="$EXCLUDE_ARGS --exclude '$EXCLUDE'"
+done
+
+# Function to perform rclone sync with error checking
+rclone_sync() {
+    SOURCE="$1"
+    DEST="$2"
+    echo "Syncing '$SOURCE' to '$DEST'..."
+    rclone sync "$SOURCE" "$DEST" $EXCLUDE_ARGS --progress --transfers=32 --checkers=16 --profile "$B2_PROFILE"
+    if [ $? -ne 0 ]; then
+        echo "Error: rclone sync failed for '$SOURCE' to '$DEST'"
+        exit 1
+    fi
+}
+
+# Perform rclone sync for each directory/file
+rclone_sync "$SOURCE_UPLOADS" "$DEST_UPLOADS"
+rclone_sync "$SOURCE_VECTORDB" "$DEST_CHROMADB"
+rclone_sync "$SOURCE_WEBUI_DB" "$DEST_MAIN_DB"
+
+echo "Backup completed successfully."
+exit 0
+```
+
+## Rsync Job With Container Interruption
+
+To maintain data integrity, it's generally recommended to run database backups on cold filesystems. Our default model backup job can be modified slightly to bring down the stack before running the backup script and bring it back after. 
+
+The downside of this approach, of course, is that it will entail instance downtime. Consider running the job at times you won't be using the instance or taking "software" dailies (on the running data) and more robust weeklies (on cold data). 
+
+```bash
+#!/bin/bash
+
+# Configuration
+COMPOSE_FILE="docker-compose.yml" # Path to your docker-compose.yml file
+B2_BUCKET="b2://OpenWebUI-backups" # Your Backblaze B2 bucket
+B2_PROFILE="your_rclone_profile" # Your rclone profile name
+SOURCE_DIR="."  # Current directory (where the file structure resides)
+
+# Define source and destination directories
+SOURCE_UPLOADS="$SOURCE_DIR/uploads"
+SOURCE_VECTORDB="$SOURCE_DIR/vector_db"
+SOURCE_WEBUI_DB="$SOURCE_DIR/webui.db"
+
+DEST_UPLOADS="$B2_BUCKET/user_uploads"
+DEST_CHROMADB="$B2_BUCKET/ChromaDB"
+DEST_MAIN_DB="$B2_BUCKET/main_database"
+
+# Exclude cache and audit.log
+EXCLUDE_LIST=(
+    "cache/"
+    "audit.log"
+)
+
+# Construct exclude arguments for rclone
+EXCLUDE_ARGS=""
+for EXCLUDE in "${EXCLUDE_LIST[@]}"; do
+    EXCLUDE_ARGS="$EXCLUDE_ARGS --exclude '$EXCLUDE'"
+done
+
+# Function to perform rclone sync with error checking
+rclone_sync() {
+    SOURCE="$1"
+    DEST="$2"
+    echo "Syncing '$SOURCE' to '$DEST'..."
+    rclone sync "$SOURCE" "$DEST" $EXCLUDE_ARGS --progress --transfers=32 --checkers=16 --profile "$B2_PROFILE"
+    if [ $? -ne 0 ]; then
+        echo "Error: rclone sync failed for '$SOURCE' to '$DEST'"
+        exit 1
+    fi
+}
+
+# 1. Stop the Docker Compose environment
+echo "Stopping Docker Compose environment..."
+docker-compose -f "$COMPOSE_FILE" down
+
+# 2. Perform the backup
+echo "Starting backup..."
+rclone_sync "$SOURCE_UPLOADS" "$DEST_UPLOADS"
+rclone_sync "$SOURCE_VECTORDB" "$DEST_CHROMADB"
+rclone_sync "$SOURCE_WEBUI_DB" "$DEST_MAIN_DB"
+
+# 3. Start the Docker Compose environment
+echo "Starting Docker Compose environment..."
+docker-compose -f "$COMPOSE_FILE" up -d
+
+echo "Backup completed successfully."
+exit 0
+```
+
+## Point In Time Snapshots
+
+In addition taking backups, users may also wish to create point-in-time snapshots which could be stored locally (on the server), remotely, or both.  
+
+```bash
+#!/bin/bash
+
+# Configuration
+SOURCE_DIR="."  # Directory to snapshot (current directory)
+SNAPSHOT_DIR="/snapshots" # Directory to store snapshots
+TIMESTAMP=$(date +%Y%m%d%H%M%S) # Generate timestamp
+
+# Create the snapshot directory if it doesn't exist
+mkdir -p "$SNAPSHOT_DIR"
+
+# Create the snapshot name
+SNAPSHOT_NAME="snapshot_$TIMESTAMP"
+SNAPSHOT_PATH="$SNAPSHOT_DIR/$SNAPSHOT_NAME"
+
+# Perform the rsync snapshot
+echo "Creating snapshot: $SNAPSHOT_PATH"
+rsync -av --delete --link-dest="$SNAPSHOT_DIR/$(ls -t "$SNAPSHOT_DIR" | head -n 1)" "$SOURCE_DIR/" "$SNAPSHOT_PATH"
+
+# Check if rsync was successful
+if [ $? -eq 0 ]; then
+  echo "Snapshot created successfully."
+else
+  echo "Error: Snapshot creation failed."
+  exit 1
+fi
+
+exit 0
+```
+## Crontab For Scheduling
+
+Once you've added your backup script and provisioned your backup storage, you'll want to QA the scripts to make sure that they're running as expected. Logging is highly advisable.
+
+Set your new script(s) up to run using crontabs according to your desired run frequency.
+
+# Commercial Utilities
+
+In addition to scripting your own backup jobs, you can find commercial offerings which generally work by installing agents on your server that will abstract the complexities of running backups. These are beyond the purview of this article but provide convenient solutions.
+
+# Host Level Backups
+
+Your OpenWebUI instance might be provisioned on a host (physical or virtualised) which you control. 
+
+Host level backups involve creating snapshots or backups but of the entire VM rather than running applications. 
+
+Some may wish to leverage them as their primary or only protection while others may wish to layer them in as additional data protections.
+
+# How Many Backups Do I Need?
+
+The amount of backups that you will wish to take depends on your personal level of risk tolerance. However, remember that it's best practice to *not* consider the application itself to be a backup copy (even if it lives in the cloud!). That means that if you've provisioned your instance on a VPS, it's still a reasonable recommendation to keep two (independent) backup copies.
+
+An example backup plan that would cover the needs of many home users:
+
+## Model backup plan 1 (primary + 2 copies)
+
+| Frequency | Target | Technology | Description |
+|---|---|---|---|
+| Daily Incremental | Cloud Storage (S3/B2) | rsync | Daily incremental backup pushed to a cloud storage bucket (S3 or B2). |
+| Weekly Incremental | On-site Storage (Home NAS) | rsync | Weekly incremental backup pulled from the server to on-site storage (e.g., a home NAS). |
+
+## Model backup plan 2 (primary + 3 copies)
+
+This backup plan is a little more complicated but also more comprehensive .. it involves daily pushes to two cloud storage providers for additional redundancy.
+
+| Frequency | Target | Technology | Description |
+|---|---|---|---|
+| Daily Incremental | Cloud Storage (S3) | rsync | Daily incremental backup pushed to an S3 cloud storage bucket. |
+| Daily Incremental | Cloud Storage (B2) | rsync | Daily incremental backup pushed to a Backblaze B2 cloud storage bucket. |
+| Weekly Incremental | On-site Storage (Home NAS) | rsync | Weekly incremental backup pulled from the server to on-site storage (e.g., a home NAS). |
+
+# Additional Topics
+
+In the interest of keeping this guide reasonably thorough these additional subjects were ommitted but may be worth your consideration depending upon how much time you have to dedicate to setting up and maintaining a data protection plan for your instance:
+
+| Topic | Description |
+|---|---|
+| SQLite Built-in Backup | Consider using SQLite's `.backup` command for a consistent database backup solution. |
+| Encryption | Modify backup scripts to incorporate encryption at rest for enhanced security. |
+| Disaster Recovery and Testing | Develop a disaster recovery plan and regularly test the backup and restore process. |
+| Alternative Backup Tools | Explore other command-line backup tools like `borgbackup` or `restic` for advanced features. |
+| Email Notifications and Webhooks | Implement email notifications or webhooks to monitor backup success or failure. |

docs/tutorials/speech-to-text/_category_.json

@@ -0,0 +1,7 @@
+{
+	"label": "🎤 Speech To Text",
+	"position": 5,
+	"link": {
+		"type": "generated-index"
+	}
+}

docs/tutorials/speech-to-text/env-variables.md

@@ -0,0 +1,25 @@
+---
+sidebar_position: 2
+title: "Environment Variables"
+---
+
+
+# Environment Variables List
+
+
+:::info
+For a complete list of all Open WebUI environment variables, see the [Environment Variable Configuration](/docs/getting-started/env-configuration) page.
+:::
+
+The following is a summary of the environment variables for speech to text (STT).
+
+# Environment Variables For Speech To Text (STT)
+
+| Variable | Description |
+|----------|-------------|
+| `WHISPER_MODEL` | Sets the Whisper model to use for local Speech-to-Text |
+| `WHISPER_MODEL_DIR` | Specifies the directory to store Whisper model files |
+| `AUDIO_STT_ENGINE` | Specifies the Speech-to-Text engine to use (empty for local Whisper, or `openai`) |
+| `AUDIO_STT_MODEL` | Specifies the Speech-to-Text model for OpenAI-compatible endpoints |
+| `AUDIO_STT_OPENAI_API_BASE_URL` | Sets the OpenAI-compatible base URL for Speech-to-Text |
+| `AUDIO_STT_OPENAI_API_KEY` | Sets the OpenAI API key for Speech-to-Text |

docs/tutorials/speech-to-text/stt-config.md

@@ -0,0 +1,62 @@
+---
+sidebar_position: 1
+title: "🗨️  Configuration"
+---
+
+Open Web UI supports both local, browser, and remote speech to text.
+
+![alt text](/images/tutorials/stt/image.png)
+
+![alt text](/images/tutorials/stt/stt-providers.png)
+
+## Cloud / Remote Speech To Text Proivders
+
+The following cloud speech to text providers are currently supported. API keys can be configured as environment variables (OpenAI) or in the admin settings page (both keys).
+
+ | Service  | API Key Required |
+ | ------------- | ------------- |
+ | OpenAI  | ✅ |
+ | DeepGram  | ✅ |
+
+ WebAPI provides STT via the built-in browser STT provider.
+
+## Configuring Your STT Provider
+
+To configure a speech to text provider:
+
+- Navigate to the admin settings  
+- Choose Audio
+- Provider an API key and choose a model from the dropdown  
+
+![alt text](/images/tutorials/stt/stt-config.png)
+
+## User-Level Settings
+
+In addition the instance settings provisioned in the admin panel, there are also a couple of user-level settings that can provide additional functionality.
+
+*   **STT Settings:** Contains settings related to Speech-to-Text functionality.
+*   **Speech-to-Text Engine:** Determines the engine used for speech recognition (Default or Web API).
+ 
+
+![alt text](/images/tutorials/stt/user-settings.png)
+
+## Using STT
+
+Speech to text provides a highly efficient way of "writing" prompts using your voice and it performs robustly from both desktop and mobile devices.
+
+To use STT, simply click on the microphone icon:
+
+![alt text](/images/tutorials/stt/stt-operation.png)
+
+A live audio waveform will indicate successful voice capture:
+
+![alt text](/images/tutorials/stt/stt-in-progress.png)
+
+## STT Mode Operation
+
+Once your recording has begun you can:
+
+- Click on the tick icon to save the recording (if auto send after completion is enabled it will send for completion; otherwise you can manually send)
+- If you wish to abort the recording (for example, you wish to start a fresh recording) you can click on the 'x' icon to scape the recording interface
+
+![alt text](/images/tutorials/stt/endstt.png)