From a2a9431eab695a54fcc94e9ec32dec50a785b927 Mon Sep 17 00:00:00 2001 From: Angelos Zaimis Date: Tue, 22 Jul 2025 16:05:07 +0200 Subject: [PATCH 1/8] Update gh-pages.yml --- .github/workflows/gh-pages.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 2a97016897..661ab16a09 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -36,6 +36,9 @@ jobs: - name: Install dependencies run: npm ci - name: Build + env: + BASE_URL: ${{ vars.BASE_URL }} + SITE_URL: ${{ vars.SITE_URL }} run: npm run build - name: Upload artifact uses: actions/upload-pages-artifact@v3 @@ -53,3 +56,4 @@ jobs: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 + From 453815cb83dc565e4ae1d41beb45fe8b25a71a10 Mon Sep 17 00:00:00 2001 From: Angelos Zaimis Date: Tue, 22 Jul 2025 16:14:29 +0200 Subject: [PATCH 2/8] Update docusaurus.config.ts --- docusaurus.config.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 914e09e142..41497f902b 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -9,10 +9,11 @@ const config: Config = { favicon: "images/favicon.png", // Set the production url of your site here - url: "https://openwebui.com", + url: process.env.SITE_URL || "https://openwebui.com", + // Set the // pathname under which your site is served // For GitHub pages deployment, it is often '//' - baseUrl: "/", + baseUrl: process.env.BASE_URL || "/", // GitHub pages deployment config. // If you aren't using GitHub pages, you don't need these. From 8adc7712740f5a80048f391dd01746b2a16e486c Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Thu, 21 Aug 2025 20:29:48 +0200 Subject: [PATCH 3/8] fix build bug --- docs/features/scim.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/scim.mdx b/docs/features/scim.mdx index fa44e2f084..0ddea9dc8b 100644 --- a/docs/features/scim.mdx +++ b/docs/features/scim.mdx @@ -186,4 +186,4 @@ SCIM works best when combined with SSO (Single Sign-On). A typical setup include This ensures users are automatically created and can immediately authenticate using their corporate credentials. -For SSO configuration, see the [SSO documentation](/docs/features/sso). \ No newline at end of file +For SSO configuration, see the [SSO documentation](https://docs.openwebui.com/features/sso/). From d9c2abc9eaa3548d43e02b07ac5abd6223c5a6e9 Mon Sep 17 00:00:00 2001 From: AngelosZa Date: Sun, 24 Aug 2025 13:48:51 +0300 Subject: [PATCH 4/8] docs: update backend-controlled UI API flow tutorial --- .../backend-controlled-ui-compatible-flow.md | 212 ++++++++++++++---- 1 file changed, 163 insertions(+), 49 deletions(-) diff --git a/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md b/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md index 74a4b13d50..d02a9dffcb 100644 --- a/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md +++ b/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md @@ -26,26 +26,27 @@ Before following this tutorial, ensure you have: ## Overview -This tutorial describes a comprehensive 6-step process that enables server-side orchestration of Open WebUI conversations while ensuring that assistant replies appear properly in the frontend UI. +This tutorial describes a comprehensive 7-step process that enables server-side orchestration of Open WebUI conversations while ensuring that assistant replies appear properly in the frontend UI. ### Process Flow The essential steps are: 1. **Create a new chat with a user message** - Initialize the conversation with the user's input -2. **Manually inject an empty assistant message** - Create a placeholder for the assistant's response -3. **Trigger the assistant completion** - Generate the actual AI response (with optional knowledge integration) -4. **Mark the completion** - Signal that the response generation is complete +2. **Enrich the chat response with an assistant message** - Add assistant message to the response object in memory +3. **Fetch the first chat response** - Get the initial chat state from the server +4. **Trigger the assistant completion** - Generate the actual AI response (with optional knowledge integration) 5. **Poll for response readiness** - Wait for the assistant response to be fully generated -6. **Fetch and process the final chat** - Retrieve and parse the completed conversation +6. **Complete the assistant message** - Mark the response as completed +7. **Fetch and process the final chat** - Retrieve and parse the completed conversation This enables server-side orchestration while still making replies show up in the frontend UI exactly as if they were generated through normal user interaction. ## Implementation Guide -### Critical Step: Manually Inject the Assistant Message +### Critical Step: Enrich Chat Response with Assistant Message -The assistant message needs to be injected manually as a critical prerequisite before triggering the completion. This step is essential because the Open WebUI frontend expects assistant messages to exist in a specific structure. +The assistant message needs to be added to the chat response object in memory as a critical prerequisite before triggering the completion. This step is essential because the Open WebUI frontend expects assistant messages to exist in a specific structure. The assistant message must appear in both locations: - `chat.messages[]` - The main message array @@ -65,7 +66,7 @@ The assistant message must appear in both locations: } ``` -Without this manual injection, the assistant's response will not appear in the frontend interface, even if the completion is successful. +Without this enrichment, the assistant's response will not appear in the frontend interface, even if the completion is successful. ## Step-by-Step Implementation @@ -74,7 +75,7 @@ Without this manual injection, the assistant's response will not appear in the f This starts the chat and returns a `chatId` that will be used in subsequent requests. ```bash -curl -X POST https:///api/v1/chats/new \ +curl -X POST https://rag-ui.ai.nu.education/api/v1/chats/new \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ @@ -106,31 +107,85 @@ curl -X POST https:///api/v1/chats/new \ }' ``` -### Step 2: Manually Inject Empty Assistant Message +### Step 2: Enrich Chat Response with Assistant Message -Add the assistant message placeholder to the chat structure: +Add the assistant message to the chat response object in memory (this is done programmatically, not via API call): + +```java +// Example implementation in Java +public void enrichChatWithAssistantMessage(OWUIChatResponse chatResponse, String model) { + OWUIMessage assistantOWUIMessage = buildAssistantMessage(chatResponse, model, "assistant", ""); + assistantOWUIMessage.setParentId(chatResponse.getChat().getMessages().get(0).getId()); + + chatResponse.getChat().getMessages().add(assistantOWUIMessage); + chatResponse.getChat().getHistory().getMessages().put(assistantOWUIMessage.getId(), assistantOWUIMessage); +} +``` + +**Note:** This step is performed in memory on the response object, not via a separate API call to `/chats//messages`. + +### Step 3: Fetch First Chat Response + +After creating the chat and enriching it with the assistant message, fetch the first chat response to get the initial state: ```bash -curl -X POST https:///api/v1/chats//messages \ +curl -X POST https://rag-ui.ai.nu.education/api/v1/chats/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ - "id": "assistant-msg-id", - "role": "assistant", - "content": "", - "parentId": "user-msg-id", - "modelName": "gpt-4o", - "modelIdx": 0, - "timestamp": 1720000001000 + "chat": { + "id": "", + "title": "New Chat", + "models": ["gpt-4o"], + "messages": [ + { + "id": "user-msg-id", + "role": "user", + "content": "Hi, what is the capital of France?", + "timestamp": 1720000000000, + "models": ["gpt-4o"] + }, + { + "id": "assistant-msg-id", + "role": "assistant", + "content": "", + "parentId": "user-msg-id", + "modelName": "gpt-4o", + "modelIdx": 0, + "timestamp": 1720000001000 + } + ], + "history": { + "current_id": "assistant-msg-id", + "messages": { + "user-msg-id": { + "id": "user-msg-id", + "role": "user", + "content": "Hi, what is the capital of France?", + "timestamp": 1720000000000, + "models": ["gpt-4o"] + }, + "assistant-msg-id": { + "id": "assistant-msg-id", + "role": "assistant", + "content": "", + "parentId": "user-msg-id", + "modelName": "gpt-4o", + "modelIdx": 0, + "timestamp": 1720000001000 + } + } + } + } }' ``` -### Step 3: Trigger Assistant Completion +### Step 4: Trigger Assistant Completion Generate the actual AI response using the completion endpoint: ```bash -curl -X POST https:///api/chat/completions \ +curl -X POST https://rag-ui.ai.nu.education/api/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ @@ -170,7 +225,7 @@ curl -X POST https:///api/chat/completions \ For advanced use cases involving knowledge bases or document collections, include knowledge files in the completion request: ```bash -curl -X POST https:///api/chat/completions \ +curl -X POST https://rag-ui.ai.nu.education/api/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ @@ -212,30 +267,36 @@ curl -X POST https:///api/chat/completions \ }' ``` -### Step 4: Mark Completion +### Step 5: Poll for Assistant Response Completion -Signal that the assistant response is complete: +Since assistant responses are generated asynchronously, poll the chat endpoint until the response is ready. The actual implementation uses a retry mechanism with exponential backoff: + +```java +// Example implementation in Java +@Retryable( + retryFor = AssistantResponseNotReadyException.class, + maxAttemptsExpression = "#{${webopenui.retries:50}}", + backoff = @Backoff(delayExpression = "#{${webopenui.backoffmilliseconds:2000}}") +) +public String getAssistantResponseWhenReady(String chatId, ChatCompletedRequest chatCompletedRequest) { + OWUIChatResponse response = owuiService.fetchFinalChatResponse(chatId); + Optional assistantMsg = extractAssistantResponse(response); + + if (assistantMsg.isPresent() && !assistantMsg.get().getContent().isBlank()) { + owuiService.completeAssistantMessage(chatCompletedRequest); + return assistantMsg.get().getContent(); + } -```bash -curl -X POST https:///api/chat/completed \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d '{ - "chat_id": "", - "id": "assistant-msg-id", - "session_id": "session-id", - "model": "gpt-4o" - }' + throw new AssistantResponseNotReadyException("Assistant response not ready yet for chatId: " + chatId); +} ``` -### Step 5: Poll for Assistant Response Completion - -Since assistant responses are generated asynchronously, poll the chat endpoint until the response is ready: +For manual polling, you can use: ```bash # Poll every few seconds until assistant content is populated while true; do - response=$(curl -s -X GET https:///api/v1/chats/ \ + response=$(curl -s -X GET https://rag-ui.ai.nu.education/api/v1/chats/ \ -H "Authorization: Bearer ") # Check if assistant message has content (response is ready) @@ -249,12 +310,28 @@ while true; do done ``` -### Step 6: Fetch Final Chat +### Step 6: Complete Assistant Message + +Once the assistant response is ready, mark it as completed: + +```bash +curl -X POST https://rag-ui.ai.nu.education/api/chat/completed \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "chat_id": "", + "id": "assistant-msg-id", + "session_id": "session-id", + "model": "gpt-4o" + }' +``` + +### Step 7: Fetch Final Chat Retrieve the completed conversation: ```bash -curl -X GET https:///api/v1/chats/ \ +curl -X GET https://rag-ui.ai.nu.education/api/v1/chats/ \ -H "Authorization: Bearer " ``` @@ -265,7 +342,7 @@ curl -X GET https:///api/v1/chats/ \ Retrieve knowledge base information for RAG integration: ```bash -curl -X GET https:///api/v1/knowledge/ \ +curl -X GET https://rag-ui.ai.nu.education/api/v1/knowledge/ \ -H "Authorization: Bearer " ``` @@ -274,10 +351,46 @@ curl -X GET https:///api/v1/knowledge/ \ Get details about a specific model: ```bash -curl -X GET https:///api/v1/models/model?id= \ +curl -X GET https://rag-ui.ai.nu.education/api/v1/models/model?id= \ -H "Authorization: Bearer " ``` +### Send Additional Messages to Chat + +For multi-turn conversations, you can send additional messages to an existing chat: + +```bash +curl -X POST https://rag-ui.ai.nu.education/api/v1/chats/ \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "chat": { + "id": "", + "messages": [ + { + "id": "new-user-msg-id", + "role": "user", + "content": "Can you tell me more about this?", + "timestamp": 1720000002000, + "models": ["gpt-4o"] + } + ], + "history": { + "current_id": "new-user-msg-id", + "messages": { + "new-user-msg-id": { + "id": "new-user-msg-id", + "role": "user", + "content": "Can you tell me more about this?", + "timestamp": 1720000002000, + "models": ["gpt-4o"] + } + } + } + } + }' +``` + ## Response Processing ### Parsing Assistant Responses @@ -735,7 +848,7 @@ This cleaning process handles: ## Important Notes - This workflow is compatible with Open WebUI + backend orchestration scenarios -- **Critical:** Avoid skipping the assistant injection step — otherwise the frontend won't display the message +- **Critical:** The assistant message enrichment must be done in memory on the response object, not via API call - No frontend code changes are required for this approach - The `stream: true` parameter allows for real-time response streaming if needed - Background tasks like title generation can be controlled via the `background_tasks` object @@ -750,11 +863,12 @@ This cleaning process handles: Use the Open WebUI backend APIs to: 1. **Start a chat** - Create the initial conversation with user input -2. **Inject an assistant placeholder message** - Prepare the response container -3. **Trigger a reply** - Generate the AI response (with optional knowledge integration) -4. **Poll for completion** - Wait for the assistant response to be ready -5. **Finalize the conversation** - Mark completion and retrieve the final chat -6. **Process the response** - Parse and clean the assistant's output +2. **Enrich with assistant message** - Add assistant placeholder to the response object in memory +3. **Fetch first response** - Get the initial chat state from the server +4. **Trigger a reply** - Generate the AI response (with optional knowledge integration) +5. **Poll for completion** - Wait for the assistant response to be ready +6. **Complete the message** - Mark the response as completed +7. **Fetch the final chat** - Retrieve and parse the completed conversation **Enhanced Capabilities:** - **RAG Integration** - Include knowledge collections for context-aware responses @@ -777,4 +891,4 @@ You can test your implementation by following the step-by-step CURL examples pro :::tip Start with a simple user message and gradually add complexity like knowledge integration and advanced features once the basic flow is working. -::: \ No newline at end of file +::: \ No newline at end of file From 0510e4405ef51244adac97c97c3b7c8384debe65 Mon Sep 17 00:00:00 2001 From: AngelosZa Date: Sun, 24 Aug 2025 13:54:57 +0300 Subject: [PATCH 5/8] feat: use default configs --- .github/workflows/gh-pages.yml | 6 +----- docusaurus.config.ts | 7 +++---- 2 files changed, 4 insertions(+), 9 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 661ab16a09..ec28e6f0fe 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -36,9 +36,6 @@ jobs: - name: Install dependencies run: npm ci - name: Build - env: - BASE_URL: ${{ vars.BASE_URL }} - SITE_URL: ${{ vars.SITE_URL }} run: npm run build - name: Upload artifact uses: actions/upload-pages-artifact@v3 @@ -55,5 +52,4 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v4 - + uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 41497f902b..23e7458fb1 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -9,11 +9,10 @@ const config: Config = { favicon: "images/favicon.png", // Set the production url of your site here - url: process.env.SITE_URL || "https://openwebui.com", - + url: "https://openwebui.com", // Set the // pathname under which your site is served // For GitHub pages deployment, it is often '//' - baseUrl: process.env.BASE_URL || "/", + baseUrl: "/", // GitHub pages deployment config. // If you aren't using GitHub pages, you don't need these. @@ -172,4 +171,4 @@ const config: Config = { plugins: [require.resolve("docusaurus-lunr-search")], }; -export default config; +export default config; \ No newline at end of file From 57fa64afaaa1b015a00170da34e47370b408ef15 Mon Sep 17 00:00:00 2001 From: AngelosZa Date: Sun, 24 Aug 2025 13:59:14 +0300 Subject: [PATCH 6/8] fixed prettier error --- .github/workflows/gh-pages.yml | 2 +- docusaurus.config.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index ec28e6f0fe..2a97016897 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -52,4 +52,4 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v4 \ No newline at end of file + uses: actions/deploy-pages@v4 diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 23e7458fb1..914e09e142 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -171,4 +171,4 @@ const config: Config = { plugins: [require.resolve("docusaurus-lunr-search")], }; -export default config; \ No newline at end of file +export default config; From 755dcc6957a01380fbbfdb3b7377c8e79b6fcebc Mon Sep 17 00:00:00 2001 From: AngelosZa Date: Sun, 24 Aug 2025 14:07:03 +0300 Subject: [PATCH 7/8] feat: add host --- .../backend-controlled-ui-compatible-flow.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md b/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md index d02a9dffcb..6ba5a66678 100644 --- a/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md +++ b/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md @@ -73,9 +73,9 @@ Without this enrichment, the assistant's response will not appear in the fronten ### Step 1: Create Chat with User Message This starts the chat and returns a `chatId` that will be used in subsequent requests. - + ```bash -curl -X POST https://rag-ui.ai.nu.education/api/v1/chats/new \ +curl -X POST https:///api/v1/chats/new \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ @@ -129,7 +129,7 @@ public void enrichChatWithAssistantMessage(OWUIChatResponse chatResponse, String After creating the chat and enriching it with the assistant message, fetch the first chat response to get the initial state: ```bash -curl -X POST https://rag-ui.ai.nu.education/api/v1/chats/ \ +curl -X POST https:///api/v1/chats/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ @@ -185,7 +185,7 @@ curl -X POST https://rag-ui.ai.nu.education/api/v1/chats/ \ Generate the actual AI response using the completion endpoint: ```bash -curl -X POST https://rag-ui.ai.nu.education/api/chat/completions \ +curl -X POST https:///api/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ @@ -225,7 +225,7 @@ curl -X POST https://rag-ui.ai.nu.education/api/chat/completions \ For advanced use cases involving knowledge bases or document collections, include knowledge files in the completion request: ```bash -curl -X POST https://rag-ui.ai.nu.education/api/chat/completions \ +curl -X POST https:///api/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ @@ -296,7 +296,7 @@ For manual polling, you can use: ```bash # Poll every few seconds until assistant content is populated while true; do - response=$(curl -s -X GET https://rag-ui.ai.nu.education/api/v1/chats/ \ + response=$(curl -s -X GET https:///api/v1/chats/ \ -H "Authorization: Bearer ") # Check if assistant message has content (response is ready) @@ -315,7 +315,7 @@ done Once the assistant response is ready, mark it as completed: ```bash -curl -X POST https://rag-ui.ai.nu.education/api/chat/completed \ +curl -X POST https:///api/chat/completed \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ @@ -331,7 +331,7 @@ curl -X POST https://rag-ui.ai.nu.education/api/chat/completed \ Retrieve the completed conversation: ```bash -curl -X GET https://rag-ui.ai.nu.education/api/v1/chats/ \ +curl -X GET https:///api/v1/chats/ \ -H "Authorization: Bearer " ``` @@ -342,7 +342,7 @@ curl -X GET https://rag-ui.ai.nu.education/api/v1/chats/ \ Retrieve knowledge base information for RAG integration: ```bash -curl -X GET https://rag-ui.ai.nu.education/api/v1/knowledge/ \ +curl -X GET https:///api/v1/knowledge/ \ -H "Authorization: Bearer " ``` @@ -351,7 +351,7 @@ curl -X GET https://rag-ui.ai.nu.education/api/v1/knowledge/ \ Get details about a specific model: ```bash -curl -X GET https://rag-ui.ai.nu.education/api/v1/models/model?id= \ +curl -X GET https:///api/v1/models/model?id= \ -H "Authorization: Bearer " ``` @@ -360,7 +360,7 @@ curl -X GET https://rag-ui.ai.nu.education/api/v1/models/model?id= \ For multi-turn conversations, you can send additional messages to an existing chat: ```bash -curl -X POST https://rag-ui.ai.nu.education/api/v1/chats/ \ +curl -X POST https:///api/v1/chats/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ From 5fa6b1eed1838c27273ea91cd55f2ce1d6c60139 Mon Sep 17 00:00:00 2001 From: AngelosZa Date: Sun, 24 Aug 2025 14:15:18 +0300 Subject: [PATCH 8/8] feat: remove host --- .../integrations/backend-controlled-ui-compatible-flow.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md b/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md index 6ba5a66678..ac7b0e687d 100644 --- a/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md +++ b/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md @@ -62,7 +62,7 @@ The assistant message must appear in both locations: "parentId": "", "modelName": "gpt-4o", "modelIdx": 0, - "timestamp": + "timestamp": "" } ``` @@ -73,7 +73,7 @@ Without this enrichment, the assistant's response will not appear in the fronten ### Step 1: Create Chat with User Message This starts the chat and returns a `chatId` that will be used in subsequent requests. - + ```bash curl -X POST https:///api/v1/chats/new \ -H "Authorization: Bearer " \