Document turning off websocket frame compression

Chat responses stream as one very small frame per token, and the websocket server compresses each of them separately for every subscriber, which costs processor time while saving almost nothing at that size. UVICORN_WS_PER_MESSAGE_DEFLATE=false declines the extension, and the default keeps the previous behaviour so nothing changes until an operator turns it off.

The reference entry describes the trade, namely that the frames which did compress well are the rare large ones and even a very long reply is only a few hundred kilobytes uncompressed. The scaling guide, the performance troubleshooting page and the multi-replica guide each carry it beside their existing advice on HTTP response compression, which all three already noted does not apply to websocket traffic, and the production checklist lists it alongside the other per-worker savings.

Author: Classic298

docs/getting-started/advanced-topics/scaling.md

@@ -163,6 +163,14 @@ By default every Open WebUI worker compresses its own HTTP responses (JSON API r
 
 WebSocket traffic and streaming chat responses (SSE) are never compressed by this middleware anyway, so disabling it has no effect on the chat streaming path. If nothing in front of Open WebUI compresses responses, the main cost of disabling is a larger first (uncached) page load, several megabytes of JavaScript/CSS, and larger big-JSON payloads (long chat histories, large model lists), which matters mostly on slow or mobile links. See [`ENABLE_COMPRESSION_MIDDLEWARE`](/reference/env-configuration#enable_compression_middleware) for the full trade-off discussion.
 
+WebSocket frames are compressed separately, by the websocket server itself, and that is worth switching off under heavy streaming:
+
+```
+UVICORN_WS_PER_MESSAGE_DEFLATE=false
+```
+
+Chat responses stream as a very small frame per token, so compressing each one costs processor time for every subscriber and saves almost nothing at that size. The frames that did benefit, a finished message or a set of sources, are a few hundred kilobytes at most even for a very long reply. See [`UVICORN_WS_PER_MESSAGE_DEFLATE`](/reference/env-configuration#uvicorn_ws_per_message_deflate).
+
 #### Pair It with Static Asset Caching at the Proxy
 
 Disabling app-side compression works best when the proxy also **caches the static assets aggressively**, so the "larger first page load" downside effectively disappears: each browser downloads the (proxy-compressed) bundles once and then never asks for them again.

docs/reference/env-configuration.mdx

@@ -8283,6 +8283,13 @@ It is recommended to use the `ENABLE_DB_MIGRATIONS` variable to designate a spec
 
 ### Cache Settings
 
+#### `UVICORN_WS_PER_MESSAGE_DEFLATE`
+
+- Type: `bool`
+- Default: `True`
+- Description: Whether the websocket server negotiates per-message compression with the browser. Chat responses arrive as a stream of very small frames, one per token, and compressing each of them costs processor time on the server for every subscriber while saving almost nothing, since there is little to compress in a fragment that size. Setting this to `false` declines the compression extension, so frames go out uncompressed. The large frames that did benefit, a finished message or a set of sources, are only a few hundred kilobytes even for a very long reply, which any network carries without a noticeable delay. Worth turning off on instances under heavy streaming load, where it shows up as measurable processor use. The default preserves the previous behaviour.
+- Persistence: No
+
 #### `CACHE_CONTROL`
 
 - Type: `str`

docs/troubleshooting/multi-replica.mdx

@@ -309,6 +309,8 @@ While Open WebUI is designed to be stateless with proper Redis configuration, en
 
 By default each Open WebUI worker compresses its own HTTP responses, which profiling shows costs roughly 3–4% CPU per worker, multiplied across all replicas. In multi-replica deployments there is always a load balancer or ingress in front, so enable compression there and disable it in the app with `ENABLE_COMPRESSION_MIDDLEWARE=false`. WebSocket and SSE streaming traffic is never compressed by this middleware, so chat streaming is unaffected. Pair this with proxy-side caching of the content-hashed static bundles under `/_app/immutable/` so they are served from the proxy cache instead of the workers. See [`ENABLE_COMPRESSION_MIDDLEWARE`](/reference/env-configuration#enable_compression_middleware) and [Scaling → Offload HTTP Compression](/getting-started/advanced-topics/scaling#offload-http-compression-to-the-load-balancer).
 
+WebSocket frames are compressed by the WebSocket server rather than that middleware, and under streaming load that is worth switching off with `UVICORN_WS_PER_MESSAGE_DEFLATE=false`. Every replica pays it, since chat responses arrive as one small frame per token and each is compressed separately for every subscriber. See [`UVICORN_WS_PER_MESSAGE_DEFLATE`](/reference/env-configuration#uvicorn_ws_per_message_deflate).
+
 ### Use the Faster JSON Encoder
 
 ```bash

docs/troubleshooting/performance.md

@@ -220,6 +220,16 @@ By default, Open WebUI compresses HTTP responses (JSON API responses and the sta
 
 See [`ENABLE_COMPRESSION_MIDDLEWARE`](/reference/env-configuration#enable_compression_middleware) for the full trade-off discussion.
 
+#### WebSocket Frame Compression
+The HTTP middleware above never touches WebSocket traffic, but the WebSocket server compresses frames on its own, and that is the one worth disabling under streaming load. Chat responses arrive as a very small frame per token, so each is compressed separately, for every subscriber, with almost nothing to gain at that size. Under heavy streaming this shows up as measurable worker CPU.
+
+- **Env Var**: `UVICORN_WS_PER_MESSAGE_DEFLATE=false`
+
+*   **What you give up**: the frames that did compress well are the rare large ones, a finished message or a set of sources, and even a very long reply is only a few hundred kilobytes uncompressed, which any network carries without a noticeable delay.
+*   **Default**: enabled, matching the behaviour before the setting existed, so nothing changes until you turn it off.
+
+See [`UVICORN_WS_PER_MESSAGE_DEFLATE`](/reference/env-configuration#uvicorn_ws_per_message_deflate) for the full description.
+
 #### JSON Encoder
 
 Open WebUI encodes and decodes JSON constantly: every request body, every API response, every chat saved and opened again, every request sent on to a provider, every chunk of a streamed completion arriving back and every Socket.IO event, including the ones published over Redis when you run multiple workers or replicas. By default all of that goes through Python's standard-library `json` module. Setting `ENABLE_ORJSON=True` switches the whole application to [orjson](https://pypi.org/project/orjson/), a Rust implementation that is several times faster. It is already installed as a dependency, so this is a one-line change.
@@ -563,7 +573,8 @@ For multi-user or growing deployments the durable fix is **PostgreSQL**, not SQL
 10. **Caching**: `ENABLE_BASE_MODELS_CACHE=True`, `MODELS_CACHE_TTL=300`, `ENABLE_QUERIES_CACHE=True`.
 11. **Redis**: Single instance with `timeout 1800` and high `maxclients` (10000+). See [Redis Tuning](#redis-tuning) below.
 12. **Compression**: `ENABLE_COMPRESSION_MIDDLEWARE=False` **if** your load balancer / ingress / CDN compresses responses (enable it there instead). Saves ~3–4% CPU on every worker. See [HTTP Response Compression](#http-response-compression).
-13. **JSON Encoder**: `ENABLE_ORJSON=True` (v0.11.0+). Cuts the cost of the heaviest JSON work in a clustered deployment: encoding Socket.IO events, parsing streamed provider chunks and saving and opening whole chats. See [JSON Encoder](#json-encoder).
+13. **WebSocket Compression**: `UVICORN_WS_PER_MESSAGE_DEFLATE=false`. Streaming sends one tiny frame per token, and compressing each of them costs CPU per subscriber for almost no saving. See [WebSocket Frame Compression](#websocket-frame-compression).
+14. **JSON Encoder**: `ENABLE_ORJSON=True` (v0.11.0+). Cuts the cost of the heaviest JSON work in a clustered deployment: encoding Socket.IO events, parsing streamed provider chunks and saving and opening whole chats. See [JSON Encoder](#json-encoder).
 
 #### Redis Tuning