diff --git a/docs/features/analytics/index.mdx b/docs/features/analytics/index.mdx index b9fbe81e6..3a23fad9f 100644 --- a/docs/features/analytics/index.mdx +++ b/docs/features/analytics/index.mdx @@ -44,7 +44,22 @@ At the top right of the Analytics dashboard, you can filter all data by time per - **Last 90 days** - Quarterly trends - **All time** - Complete historical data -All metrics on the page update automatically when you change the time period. +Your selected time period is **automatically saved** and persists across browser sessions. + +### Group Filtering + +If you have [user groups](/features/rbac/groups) configured, the Analytics dashboard allows filtering by group: + +- Use the **group dropdown** next to the time period selector +- Select a specific group to view analytics **only for users in that group** +- Choose "All Users" to see instance-wide analytics + +This is useful for: +- **Department-level reporting** - Track usage for specific teams +- **Cost allocation** - Attribute token consumption to business units +- **Pilot programs** - Monitor adoption within test groups + +All metrics on the page update automatically when you change the time period or group filter. ### Summary Statistics @@ -90,6 +105,7 @@ A detailed breakdown of how each model is being used: - **Sortable columns** - Click column headers to sort by name or message count - **Model icons** - Visual identification with profile images - **Token tracking** - See which models consume the most resources +- **Clickable rows** - Click any model to open the [Model Details Modal](#model-details-modal) **Use cases:** - Identify your most popular models @@ -97,6 +113,42 @@ A detailed breakdown of how each model is being used: - Decide which models to keep or remove - Plan infrastructure upgrades based on usage +### Model Details Modal + +Clicking on any model row opens a detailed modal with two tabs: + +#### Overview Tab + +The Overview tab provides: + +- **Feedback Activity Chart** - Visual history of user feedback (thumbs up/down) over time + - Toggle between **30 days**, **1 year**, or **All time** views + - Weekly aggregation for longer time ranges +- **Tags** - Most common chat tags associated with this model (top 10) + +This helps you understand: +- How users perceive model quality over time +- Which topics/use cases the model is handling +- Trends in user satisfaction + +#### Chats Tab + +:::info Admin Chat Access Required +The Chats tab is only visible when **Admin Chat Access** is enabled in your instance settings. +::: + +The Chats tab shows conversations that used this model: + +- **User info** - Who started each chat +- **Preview** - First message of each conversation +- **Timestamp** - When the chat was last updated +- **Click to open** - Navigate directly to the shared chat view + +This is useful for: +- Understanding how users interact with specific models +- Auditing model usage for quality assurance +- Finding example conversations for training or documentation + ### User Activity Table Track user engagement and token consumption per user: @@ -248,6 +300,7 @@ The following indexes optimize analytics queries: For advanced users and integrations, Analytics provides REST API endpoints: +**Dashboard Endpoints:** ``` GET /api/v1/analytics/summary GET /api/v1/analytics/models @@ -257,13 +310,25 @@ GET /api/v1/analytics/daily GET /api/v1/analytics/tokens ``` -All endpoints support `start_date` and `end_date` parameters (Unix timestamps) for time-range filtering. +**Model Detail Endpoints:** +``` +GET /api/v1/analytics/models/{model_id}/chats # Get chats using this model +GET /api/v1/analytics/models/{model_id}/overview # Get feedback history and tags +``` + +**Common Query Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `start_date` | int | Unix timestamp (epoch seconds) - start of range | +| `end_date` | int | Unix timestamp (epoch seconds) - end of range | +| `group_id` | string | Filter to a specific user group (optional) | :::tip API Access All Analytics endpoints require admin authentication. Include your admin bearer token: ```bash curl -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \ - https://your-instance.com/api/v1/analytics/summary + "https://your-instance.com/api/v1/analytics/summary?group_id=abc123" ``` ::: diff --git a/docs/features/chat-features/message-queue.mdx b/docs/features/chat-features/message-queue.mdx new file mode 100644 index 000000000..93e9e356c --- /dev/null +++ b/docs/features/chat-features/message-queue.mdx @@ -0,0 +1,111 @@ +--- +sidebar_position: 10 +title: "Message Queue" +--- + +# Message Queue + +The **Message Queue** feature allows you to continue composing and sending messages while the AI is still generating a response. Instead of blocking your input until the current response completes, your messages are queued and automatically sent in sequence. + +--- + +## How It Works + +When you send a message while the AI is generating a response: + +1. **Your message is queued** - It appears in a compact queue area just above the input box +2. **You can continue working** - Add more messages, edit queued messages, or delete them +3. **Automatic processing** - Once the current response finishes, all queued messages are combined and sent together + +This creates a seamless workflow where you can capture thoughts as they come without waiting for the AI to finish. + +--- + +## Queue Management + +Each queued message shows three action buttons: + +| Action | Icon | Description | +|--------|------|-------------| +| **Send Now** | โ†‘ | Interrupts the current generation and sends this message immediately | +| **Edit** | โœ๏ธ | Removes the message from the queue and puts it back in the input field | +| **Delete** | ๐Ÿ—‘๏ธ | Removes the message from the queue without sending | + +### Combining Messages + +When the AI finishes generating, all queued messages are **combined into a single prompt** (separated by blank lines) and sent together. This means: + +- Multiple quick thoughts become one coherent message +- Context flows naturally between your queued inputs +- The AI receives everything at once for better understanding + +--- + +## Persistence + +The message queue is preserved when you navigate between chats within the same browser session: + +- **Leaving a chat** - Queue is saved to session storage +- **Returning to the chat** - Queue is restored and processed +- **Closing the browser** - Queue is cleared (session storage only) + +This means you can start a thought, switch to another chat to check something, and return to find your queued messages waiting. + +--- + +## Settings + +You can disable the Message Queue feature if you prefer the traditional behavior: + +1. Go to **Settings** โ†’ **Interface** +2. Find **Enable Message Queue** under the Chat section +3. Toggle it off + +When disabled, sending a message while the AI is generating will: +- **Interrupt** the current generation +- **Send** your new message immediately + +:::tip Default Behavior +Message Queue is **enabled by default**. The toggle allows you to choose between: +- **Queue mode** (default) - Messages queue up until generation completes +- **Interrupt mode** - New messages stop current generation immediately +::: + +--- + +## Use Cases + +### 1. Stream of Consciousness + +You're reading an AI response and have follow-up questions. Instead of waiting: +- Queue your first follow-up +- Queue a clarification +- Queue another thought + +All are sent together when the AI finishes. + +### 2. Adding Context + +The AI is working on a complex response, but you remember additional context: +- Queue the extra information +- The AI receives it as part of the next message + +### 3. Multitasking + +You're in a long conversation and need to capture quick notes: +- Queue messages as reminders +- Edit or delete before they're sent +- Use "Send Now" for urgent interruptions + +--- + +## Summary + +| Feature | Behavior | +|---------|----------| +| **Enabled** | Messages queue during generation, sent together when complete | +| **Disabled** | New messages interrupt current generation immediately | +| **Persistence** | Queue survives navigation within session | +| **Actions** | Send Now, Edit, Delete for each queued item | + +The Message Queue helps you maintain your flow of thought without the friction of waiting for AI responses to complete. diff --git a/docs/features/index.mdx b/docs/features/index.mdx index 9fbc8a058..b7f44d149 100644 --- a/docs/features/index.mdx +++ b/docs/features/index.mdx @@ -168,6 +168,8 @@ import { TopBanners } from "@site/src/components/TopBanners"; - ๐Ÿ”” **Chat Completion Notifications**: Stay updated with instant in-UI notifications when a chat finishes in a non-active tab, ensuring you never miss a completed response. +- ๐Ÿ“ **Message Queue**: Continue composing messages while the AI is generating a response. Your messages are queued and automatically sent together when the current response completes. Edit, delete, or send queued messages immediately. [Learn about Message Queue](/features/chat-features/message-queue). + - ๐ŸŒ **Notification Webhook Integration**: Receive timely updates for long-running chats or external integration needs with configurable webhook notifications, even when your tab is closed. [Learn more about Webhooks](/features/interface/webhooks). - ๐Ÿ“š **Channels (Beta)**: Explore real-time collaboration between users and AIs with Discord/Slack-style chat rooms, build bots for channels, and unlock asynchronous communication for proactive multi-agent workflows. [See Channels](/features/channels). diff --git a/docs/features/plugin/development/events.mdx b/docs/features/plugin/development/events.mdx index 53ccdf6fc..31b141e9a 100644 --- a/docs/features/plugin/development/events.mdx +++ b/docs/features/plugin/development/events.mdx @@ -24,15 +24,26 @@ Think of Events like push notifications and modal dialogs that your plugin can t ## ๐Ÿ Availability -:::important -Events are **only available for native Python Tools and Functions** defined directly in Open WebUI. +### Native Python Tools & Functions -Events are **NOT supported** for: -- **OpenAPI tool servers** (external REST APIs) -- **MCP tool servers** (Model Context Protocol) +Events are **fully available** for native Python Tools and Functions defined directly in Open WebUI using the `__event_emitter__` and `__event_call__` helpers. -These external tools communicate via HTTP request/response and cannot emit real-time UI events. -::: +### External Tools (OpenAPI & MCP) + +External tools can emit events via a **dedicated REST endpoint**. Open WebUI passes the following headers to all external tool requests: + +| Header | Description | +|--------|-------------| +| `X-Open-WebUI-Chat-Id` | The chat ID where the tool was invoked | +| `X-Open-WebUI-Message-Id` | The message ID associated with the tool call | + +Your external tool can use these headers to emit events back to the UI via: + +``` +POST /api/v1/chats/{chat_id}/messages/{message_id}/event +``` + +See [External Tool Events](#-external-tool-events) below for details. --- @@ -452,6 +463,117 @@ Yesโ€”emit `"chat:message:delta"` events in a loop, then finish with `"chat:mess --- +## ๐ŸŒ External Tool Events + +External tools (OpenAPI and MCP servers) can emit events to the Open WebUI UI via a REST endpoint. This enables features like status updates, notifications, and streaming content from tools running on external servers. + +### Headers Provided by Open WebUI + +When Open WebUI calls your external tool, it includes these headers: + +| Header | Description | +|--------|-------------| +| `X-Open-WebUI-Chat-Id` | The chat ID where the tool was invoked | +| `X-Open-WebUI-Message-Id` | The message ID associated with the tool call | + +### Event Endpoint + +**Endpoint:** `POST /api/v1/chats/{chat_id}/messages/{message_id}/event` + +**Authentication:** Requires a valid Open WebUI API key or session token. + +**Request Body:** + +```json +{ + "type": "status", + "data": { + "description": "Processing your request...", + "done": false + } +} +``` + +### Supported Event Types + +External tools can emit the same event types as native tools: +- `status` โ€“ Show progress/status updates +- `notification` โ€“ Display toast notifications +- `chat:message:delta` / `message` โ€“ Append content to the message +- `chat:message` / `replace` โ€“ Replace message content +- `files` / `chat:message:files` โ€“ Attach files +- `source` / `citation` โ€“ Add citations + +:::note +Interactive events (`input`, `confirmation`, `execute`) require `__event_call__` and are **not supported** for external tools as they need bidirectional WebSocket communication. +::: + +### Example: Python External Tool + +```python +import httpx + +def my_tool_handler(request): + # Extract headers from incoming request + chat_id = request.headers.get("X-Open-WebUI-Chat-Id") + message_id = request.headers.get("X-Open-WebUI-Message-Id") + api_key = "your-open-webui-api-key" + + # Emit a status event + httpx.post( + f"http://your-open-webui-host/api/v1/chats/{chat_id}/messages/{message_id}/event", + headers={"Authorization": f"Bearer {api_key}"}, + json={ + "type": "status", + "data": {"description": "Working on it...", "done": False} + } + ) + + # ... do work ... + + # Emit completion status + httpx.post( + f"http://your-open-webui-host/api/v1/chats/{chat_id}/messages/{message_id}/event", + headers={"Authorization": f"Bearer {api_key}"}, + json={ + "type": "status", + "data": {"description": "Complete!", "done": True} + } + ) + + return {"result": "success"} +``` + +### Example: JavaScript/Node.js External Tool + +```javascript +async function myToolHandler(req) { + const chatId = req.headers['x-open-webui-chat-id']; + const messageId = req.headers['x-open-webui-message-id']; + const apiKey = 'your-open-webui-api-key'; + + // Emit a notification + await fetch( + `http://your-open-webui-host/api/v1/chats/${chatId}/messages/${messageId}/event`, + { + method: 'POST', + headers: { + 'Authorization': `Bearer ${apiKey}`, + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + type: 'notification', + data: { type: 'info', content: 'Tool is processing...' } + }) + } + ); + + return { result: 'success' }; +} +``` + +--- + ## ๐Ÿ“ Conclusion **Events** give you real-time, interactive superpowers inside Open WebUI. They let your code update content, trigger notifications, request user input, stream results, handle code, and much moreโ€”seamlessly plugging your backend intelligence into the chat UI. diff --git a/docs/features/plugin/tools/index.mdx b/docs/features/plugin/tools/index.mdx index 0e08e4390..7ad37607f 100644 --- a/docs/features/plugin/tools/index.mdx +++ b/docs/features/plugin/tools/index.mdx @@ -180,11 +180,11 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo | `search_web` | Search the public web for information. Best for current events, external references, or topics not covered in internal documents. | | `fetch_url` | Visits a URL and extracts text content via the Web Loader. | | **Knowledge Base** | *Requires per-model "Knowledge Base" category enabled (default: on).* | -| `list_knowledge_bases` | List the user's accessible knowledge bases with file counts. | -| `query_knowledge_bases` | Search knowledge bases by semantic similarity to query. Finds KBs whose name/description match the meaning of your query. Use this to discover relevant knowledge bases before querying their files. | -| `search_knowledge_bases` | Search knowledge bases by name and description. | -| `query_knowledge_files` | Search knowledge base files using simple vector search. **Note:** Does not use hybrid search or rerankingโ€”for full RAG pipeline with reranking, use File Context instead by attaching files via `#` or assigning knowledge bases. | -| `search_knowledge_files` | Search files across accessible knowledge bases by filename. | +| `list_knowledge_bases` | List the user's accessible knowledge bases with file counts. **Use this first** to discover what knowledge is available. | +| `query_knowledge_bases` | Search KB *names and descriptions* by semantic similarity. Use to find which KB is relevant when you don't know which one to query. | +| `search_knowledge_bases` | Search knowledge bases by name/description (text match). | +| `query_knowledge_files` | Search *file contents* inside KBs using vector search. **This is your main tool for finding information.** When a KB is attached to the model, searches are automatically scoped to that KB. | +| `search_knowledge_files` | Search files across accessible knowledge bases by filename (not content). | | `view_knowledge_file` | Get the full content of a file from a knowledge base. | | **Image Gen** | *Requires image generation enabled (per-tool).* | | `generate_image` | Generates a new image based on a prompt. Requires `ENABLE_IMAGE_GENERATION`. | @@ -252,6 +252,15 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo Open WebUI automatically detects and stores your timezone when you log in. This allows time-related tools and features to provide accurate local times without any manual configuration. Your timezone is determined from your browser settings. ::: +:::info Recommended KB Tool Workflow +**When an attached KB is returning empty results:** +1. First call `list_knowledge_bases` to confirm the model can see the attached KB +2. Then use `query_knowledge_files` (without specifying `knowledge_ids` โ€” it auto-scopes to attached KBs) +3. If still empty, the files may not be embedded yet, or you may have **Full Context mode enabled** which bypasses the vector store + +**Do NOT use Full Context mode with knowledge tools** โ€” Full Context injects file content directly and doesn't store embeddings, so `query_knowledge_files` will return empty. Use Focused Retrieval (default) for tool-based access. +::: + :::tip Knowledge Base Tools vs RAG Pipeline The native `query_knowledge_files` tool uses **simple vector search** with a default of 5 results. It does **not** use: - Hybrid search (BM25 + vector) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index a3dacb7c3..8f0c47fb2 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -1350,7 +1350,7 @@ If you have already deployed with `JWT_EXPIRES_IN=-1`, you can rotate or change - type: `bool` - Default: `False` -- Description: Forwards user information (name, ID, email, role and chat-id) as X-headers to OpenAI API and Ollama API. +- Description: Forwards user and session information as HTTP headers to OpenAI API, Ollama API, MCP servers, and Tool servers. If enabled, the following headers are forwarded: - `X-OpenWebUI-User-Name` - `X-OpenWebUI-User-Id` @@ -1358,6 +1358,50 @@ If enabled, the following headers are forwarded: - `X-OpenWebUI-User-Role` - `X-OpenWebUI-Chat-Id` +This enables per-user authorization, auditing, rate limiting, and request tracing on external services. + +#### `FORWARD_USER_INFO_HEADER_USER_NAME` + +- Type: `str` +- Default: `X-OpenWebUI-User-Name` +- Description: Customizes the header name used to forward the user's display name. Change this if your infrastructure requires a specific header prefix. + +#### `FORWARD_USER_INFO_HEADER_USER_ID` + +- Type: `str` +- Default: `X-OpenWebUI-User-Id` +- Description: Customizes the header name used to forward the user's ID. + +#### `FORWARD_USER_INFO_HEADER_USER_EMAIL` + +- Type: `str` +- Default: `X-OpenWebUI-User-Email` +- Description: Customizes the header name used to forward the user's email address. + +#### `FORWARD_USER_INFO_HEADER_USER_ROLE` + +- Type: `str` +- Default: `X-OpenWebUI-User-Role` +- Description: Customizes the header name used to forward the user's role. + +#### `FORWARD_SESSION_INFO_HEADER_CHAT_ID` + +- Type: `str` +- Default: `X-OpenWebUI-Chat-Id` +- Description: Customizes the header name used to forward the current chat/session ID. + +:::tip Custom Header Prefix +Use these variables when integrating with services that require specific header naming conventions. For example, AWS Bedrock AgentCore requires headers prefixed with `X-Amzn-Bedrock-AgentCore-Runtime-Custom-`: + +```bash +FORWARD_USER_INFO_HEADER_USER_NAME=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Name +FORWARD_USER_INFO_HEADER_USER_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Id +FORWARD_USER_INFO_HEADER_USER_EMAIL=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Email +FORWARD_USER_INFO_HEADER_USER_ROLE=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Role +FORWARD_SESSION_INFO_HEADER_CHAT_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-Chat-Id +``` +::: + #### `ENABLE_WEB_LOADER_SSL_VERIFICATION` - Type: `bool`