From 92515c5f7ecf7870deadd2efcfd9b1f407be109f Mon Sep 17 00:00:00 2001 From: James Westbrook <0xthresh@protonmail.com> Date: Thu, 2 Apr 2026 11:04:34 -0600 Subject: [PATCH 01/25] fix: include -o wide flag on example command to get correct output --- .../advanced/terminals/kubernetes-operator.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/features/open-terminal/advanced/terminals/kubernetes-operator.md b/docs/features/open-terminal/advanced/terminals/kubernetes-operator.md index d9378e6b..138e2d23 100644 --- a/docs/features/open-terminal/advanced/terminals/kubernetes-operator.md +++ b/docs/features/open-terminal/advanced/terminals/kubernetes-operator.md @@ -196,13 +196,13 @@ The `Terminal` custom resource is the declarative API for managing terminal inst ### Printer columns ```bash -kubectl get terminals -n open-webui +kubectl get terminals -n open-webui -o wide ``` ``` -NAME USER PHASE SERVICE URL LAST ACTIVITY AGE -terminal-a1b2c3-default user-123 Running http://terminal-a1b2c3-default-svc.open-webui.svc:8000 2026-04-01T10:30:00Z 5m -terminal-d4e5f6-datascience user-456 Idle http://terminal-d4e5f6-datascience-svc.open-webui.svc:8000 2026-04-01T09:45:00Z 1h +NAME USER PHASE SERVICE URL LAST ACTIVITY AGE +terminal-a1b2c3-default user-123 Running http://terminal-a1b2c3-default-svc.open-webui.svc:8000 5m 5m +terminal-d4e5f6-datascience user-456 Idle http://terminal-d4e5f6-datascience-svc.open-webui.svc:8000 1h 1h ``` --- From 7312effc024c1fda0734f889778495a11666408f Mon Sep 17 00:00:00 2001 From: Timothy Jaeryang Baek Date: Thu, 2 Apr 2026 18:59:50 -0500 Subject: [PATCH 02/25] refac --- docs/team.mdx | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/team.mdx b/docs/team.mdx index e29a899f..e38d18e0 100644 --- a/docs/team.mdx +++ b/docs/team.mdx @@ -25,16 +25,6 @@ Our team is led by the dedicated creator and founder, [Tim J. Baek](https://gith /> -## 🏛️ Governance - -Open WebUI is centrally managed and operated by Open WebUI Inc. Our governance model is straightforward and intentional—we do not operate on [a committee-based governance system or a community-driven voting process](https://www.reddit.com/r/OpenWebUI/comments/1ijkh6m/comment/mbf0yhm/). Strategic and operational decisions are led openly and transparently by our founder, Tim J. Baek, ensuring a clear, unified, long-term vision. - -Our project is specifically designed and structured to remain sustainable and independent for **decades** to come—thanks largely to an intentional focus on remaining extremely lean, strategic, and capital-efficient. We aren't pursuing short-term milestones or temporary trends; we're carefully building something lasting and meaningful. - -Beyond our contributors, Open WebUI Inc. has an incredible global team working behind the scenes across multiple domains, including technology, operations, strategy, finance, legal, marketing, communications, partnerships, and community management. While Tim leads the vision, execution is supported by a growing network of talented individuals helping to ensure the long-term success of the project. Our team spans various expertise areas, ensuring that Open WebUI Inc. thrives not just in software development but also in operational excellence, financial sustainability, legal compliance, brand awareness, and effective collaboration with partners. - -We greatly appreciate enthusiasm and thoughtful suggestions from our community. At the same time, **we're not looking for unsolicited governance recommendations or guidance on how to operate**—we know exactly how we want to run our project (just as, for example, you wouldn't tell OpenAI how to run theirs). Open WebUI maintains strong, opinionated leadership because that's precisely what we believe is necessary to build something truly great, fast-moving, and purposeful. - ## 📜 Community Standards All community members — contributors, users, and collaborators alike — are expected to uphold our **[Code of Conduct](https://github.com/open-webui/open-webui/blob/main/CODE_OF_CONDUCT.md)**. This project is built by volunteers who dedicate their time and expertise freely. We enforce a **zero-tolerance policy**: disrespectful, entitled, or hostile behavior toward any community member will result in immediate action without prior warning. From 352d6b0422231a3f3a97d3f5af960b2dfa4bb8f8 Mon Sep 17 00:00:00 2001 From: Timothy Jaeryang Baek Date: Thu, 2 Apr 2026 19:17:34 -0500 Subject: [PATCH 03/25] refac --- docusaurus.config.ts | 22 ++- package-lock.json | 277 +++++++++++++++++++++++++++++++++- package.json | 5 +- src/css/custom.css | 78 +++++++++- src/theme/CodeBlock/index.tsx | 86 +++++++++++ 5 files changed, 455 insertions(+), 13 deletions(-) create mode 100644 src/theme/CodeBlock/index.tsx diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 6105a41e..99cf717f 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -1,7 +1,20 @@ import { Config } from "@docusaurus/types"; import type * as Preset from "@docusaurus/preset-classic"; -import { themes as prismThemes } from "prism-react-renderer"; +import rehypeShiki, { type RehypeShikiOptions } from "@shikijs/rehype"; +import { type BundledLanguage, bundledLanguages } from "shiki"; + +const shikiPlugin: [typeof rehypeShiki, RehypeShikiOptions] = [ + rehypeShiki, + { + themes: { + light: "github-light", + dark: "github-dark", + }, + defaultColor: false, + langs: Object.keys(bundledLanguages) as BundledLanguage[], + }, +]; const config: Config = { title: "Open WebUI", @@ -51,6 +64,7 @@ const config: Config = { // Remove this to remove the "edit this page" links. editUrl: "https://github.com/open-webui/docs/blob/main", exclude: ["**/tab-**/**"], + beforeDefaultRehypePlugins: [shikiPlugin], }, // blog: false, blog: { @@ -60,6 +74,7 @@ const config: Config = { // Remove this to remove the "edit this page" links. // editUrl: // "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/", + beforeDefaultRehypePlugins: [shikiPlugin], }, theme: { customCss: "./src/css/custom.css", @@ -161,9 +176,8 @@ const config: Config = { // copyright: `Copyright © ${new Date().getFullYear()} OpenWebUI`, }, prism: { - theme: prismThemes.github, - darkTheme: prismThemes.dracula, - additionalLanguages: ["hcl", "docker"], + theme: { plain: { color: "#333", backgroundColor: "#f3f3f3" }, styles: [] }, + darkTheme: { plain: { color: "#ccc", backgroundColor: "#1a1a1a" }, styles: [] }, }, } satisfies Preset.ThemeConfig, plugins: [require.resolve("docusaurus-lunr-search")], diff --git a/package-lock.json b/package-lock.json index c642f6a1..962b4db2 100644 --- a/package-lock.json +++ b/package-lock.json @@ -13,14 +13,15 @@ "@docusaurus/preset-classic": "^3.5.2", "@docusaurus/theme-mermaid": "^3.5.2", "@mdx-js/react": "^3.0.1", + "@shikijs/rehype": "^4.0.2", "clsx": "^2.1.1", "docusaurus-lunr-search": "^3.6.0", "docusaurus-plugin-sass": "^0.2.5", "marked": "^17.0.1", - "prism-react-renderer": "^2.4.0", "react": "^18.3.1", "react-dom": "^18.3.1", - "sass": "^1.79.3" + "sass": "^1.79.3", + "shiki": "^4.0.2" }, "devDependencies": { "@docusaurus/eslint-plugin": "^3.5.2", @@ -5112,6 +5113,136 @@ "integrity": "sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==", "license": "MIT" }, + "node_modules/@shikijs/core": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-4.0.2.tgz", + "integrity": "sha512-hxT0YF4ExEqB8G/qFdtJvpmHXBYJ2lWW7qTHDarVkIudPFE6iCIrqdgWxGn5s+ppkGXI0aEGlibI0PAyzP3zlw==", + "license": "MIT", + "dependencies": { + "@shikijs/primitive": "4.0.2", + "@shikijs/types": "4.0.2", + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4", + "hast-util-to-html": "^9.0.5" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/engine-javascript": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/engine-javascript/-/engine-javascript-4.0.2.tgz", + "integrity": "sha512-7PW0Nm49DcoUIQEXlJhNNBHyoGMjalRETTCcjMqEaMoJRLljy1Bi/EGV3/qLBgLKQejdspiiYuHGQW6dX94Nag==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "4.0.2", + "@shikijs/vscode-textmate": "^10.0.2", + "oniguruma-to-es": "^4.3.4" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/engine-oniguruma": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-4.0.2.tgz", + "integrity": "sha512-UpCB9Y2sUKlS9z8juFSKz7ZtysmeXCgnRF0dlhXBkmQnek7lAToPte8DkxmEYGNTMii72zU/lyXiCB6StuZeJg==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "4.0.2", + "@shikijs/vscode-textmate": "^10.0.2" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/langs": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/langs/-/langs-4.0.2.tgz", + "integrity": "sha512-KaXby5dvoeuZzN0rYQiPMjFoUrz4hgwIE+D6Du9owcHcl6/g16/yT5BQxSW5cGt2MZBz6Hl0YuRqf12omRfUUg==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "4.0.2" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/primitive": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/primitive/-/primitive-4.0.2.tgz", + "integrity": "sha512-M6UMPrSa3fN5ayeJwFVl9qWofl273wtK1VG8ySDZ1mQBfhCpdd8nEx7nPZ/tk7k+TYcpqBZzj/AnwxT9lO+HJw==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "4.0.2", + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/rehype": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/rehype/-/rehype-4.0.2.tgz", + "integrity": "sha512-cmPlKLD8JeojasNFoY64162ScpEdEdQUMuVodPCrv1nx1z3bjmGwoKWDruQWa/ejSznImlaeB0Ty6Q3zPaVQAA==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "4.0.2", + "@types/hast": "^3.0.4", + "hast-util-to-string": "^3.0.1", + "shiki": "4.0.2", + "unified": "^11.0.5", + "unist-util-visit": "^5.1.0" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/rehype/node_modules/hast-util-to-string": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/hast-util-to-string/-/hast-util-to-string-3.0.1.tgz", + "integrity": "sha512-XelQVTDWvqcl3axRfI0xSeoVKzyIFPwsAGSLIsKdJKQMXDYJS4WYrBNF/8J7RdhIcFI2BOHgAifggsvsxp/3+A==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/@shikijs/themes": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/themes/-/themes-4.0.2.tgz", + "integrity": "sha512-mjCafwt8lJJaVSsQvNVrJumbnnj1RI8jbUKrPKgE6E3OvQKxnuRoBaYC51H4IGHePsGN/QtALglWBU7DoKDFnA==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "4.0.2" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/types": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-4.0.2.tgz", + "integrity": "sha512-qzbeRooUTPnLE+sHD/Z8DStmaDgnbbc/pMrU203950aRqjX/6AFHeDYT+j00y2lPdz0ywJKx7o/7qnqTivtlXg==", + "license": "MIT", + "dependencies": { + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/vscode-textmate": { + "version": "10.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/vscode-textmate/-/vscode-textmate-10.0.2.tgz", + "integrity": "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==", + "license": "MIT" + }, "node_modules/@sideway/address": { "version": "4.1.5", "resolved": "https://registry.npmjs.org/@sideway/address/-/address-4.1.5.tgz", @@ -12171,6 +12302,82 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/hast-util-to-html": { + "version": "9.0.5", + "resolved": "https://registry.npmjs.org/hast-util-to-html/-/hast-util-to-html-9.0.5.tgz", + "integrity": "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "ccount": "^2.0.0", + "comma-separated-tokens": "^2.0.0", + "hast-util-whitespace": "^3.0.0", + "html-void-elements": "^3.0.0", + "mdast-util-to-hast": "^13.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "stringify-entities": "^4.0.0", + "zwitch": "^2.0.4" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-html/node_modules/comma-separated-tokens": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/comma-separated-tokens/-/comma-separated-tokens-2.0.3.tgz", + "integrity": "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/hast-util-to-html/node_modules/hast-util-whitespace": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/hast-util-whitespace/-/hast-util-whitespace-3.0.0.tgz", + "integrity": "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-html/node_modules/property-information": { + "version": "7.1.0", + "resolved": "https://registry.npmjs.org/property-information/-/property-information-7.1.0.tgz", + "integrity": "sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/hast-util-to-html/node_modules/space-separated-tokens": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/space-separated-tokens/-/space-separated-tokens-2.0.2.tgz", + "integrity": "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/hast-util-to-html/node_modules/zwitch": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz", + "integrity": "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/hast-util-to-jsx-runtime": { "version": "2.3.6", "resolved": "https://registry.npmjs.org/hast-util-to-jsx-runtime/-/hast-util-to-jsx-runtime-2.3.6.tgz", @@ -16671,6 +16878,23 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/oniguruma-parser": { + "version": "0.12.1", + "resolved": "https://registry.npmjs.org/oniguruma-parser/-/oniguruma-parser-0.12.1.tgz", + "integrity": "sha512-8Unqkvk1RYc6yq2WBYRj4hdnsAxVze8i7iPfQr8e4uSP3tRv0rpZcbGUDvxfQQcdwHt/e9PrMvGCsa8OqG9X3w==", + "license": "MIT" + }, + "node_modules/oniguruma-to-es": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/oniguruma-to-es/-/oniguruma-to-es-4.3.5.tgz", + "integrity": "sha512-Zjygswjpsewa0NLTsiizVuMQZbp0MDyM6lIt66OxsF21npUDlzpHi1Mgb/qhQdkb+dWFTzJmFbEWdvZgRho8eQ==", + "license": "MIT", + "dependencies": { + "oniguruma-parser": "^0.12.1", + "regex": "^6.1.0", + "regex-recursion": "^6.0.2" + } + }, "node_modules/open": { "version": "8.4.2", "resolved": "https://registry.npmjs.org/open/-/open-8.4.2.tgz", @@ -19533,6 +19757,30 @@ "node": ">=4" } }, + "node_modules/regex": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/regex/-/regex-6.1.0.tgz", + "integrity": "sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg==", + "license": "MIT", + "dependencies": { + "regex-utilities": "^2.3.0" + } + }, + "node_modules/regex-recursion": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/regex-recursion/-/regex-recursion-6.0.2.tgz", + "integrity": "sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==", + "license": "MIT", + "dependencies": { + "regex-utilities": "^2.3.0" + } + }, + "node_modules/regex-utilities": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/regex-utilities/-/regex-utilities-2.3.0.tgz", + "integrity": "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==", + "license": "MIT" + }, "node_modules/regexpu-core": { "version": "6.4.0", "resolved": "https://registry.npmjs.org/regexpu-core/-/regexpu-core-6.4.0.tgz", @@ -20591,6 +20839,25 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/shiki": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-4.0.2.tgz", + "integrity": "sha512-eAVKTMedR5ckPo4xne/PjYQYrU3qx78gtJZ+sHlXEg5IHhhoQhMfZVzetTYuaJS0L2Ef3AcCRzCHV8T0WI6nIQ==", + "license": "MIT", + "dependencies": { + "@shikijs/core": "4.0.2", + "@shikijs/engine-javascript": "4.0.2", + "@shikijs/engine-oniguruma": "4.0.2", + "@shikijs/langs": "4.0.2", + "@shikijs/themes": "4.0.2", + "@shikijs/types": "4.0.2", + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4" + }, + "engines": { + "node": ">=20" + } + }, "node_modules/side-channel": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz", @@ -22490,9 +22757,9 @@ } }, "node_modules/unist-util-visit": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.0.0.tgz", - "integrity": "sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg==", + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.1.0.tgz", + "integrity": "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==", "license": "MIT", "dependencies": { "@types/unist": "^3.0.0", diff --git a/package.json b/package.json index 881b9186..420f97a0 100644 --- a/package.json +++ b/package.json @@ -26,14 +26,15 @@ "@docusaurus/preset-classic": "^3.5.2", "@docusaurus/theme-mermaid": "^3.5.2", "@mdx-js/react": "^3.0.1", + "@shikijs/rehype": "^4.0.2", "clsx": "^2.1.1", "docusaurus-lunr-search": "^3.6.0", "docusaurus-plugin-sass": "^0.2.5", "marked": "^17.0.1", - "prism-react-renderer": "^2.4.0", "react": "^18.3.1", "react-dom": "^18.3.1", - "sass": "^1.79.3" + "sass": "^1.79.3", + "shiki": "^4.0.2" }, "devDependencies": { "@docusaurus/eslint-plugin": "^3.5.2", diff --git a/src/css/custom.css b/src/css/custom.css index 7fa16385..098f969b 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -198,8 +198,82 @@ code { border-radius: 16px !important; } -.theme-code-block .token { - font-family: "IBM Plex Mono", monospace; +/* ─── Shiki light/dark mode toggle (CSS variables strategy) ─── */ +[data-theme="light"] .shiki-code-block pre, +[data-theme="light"] .shiki-code-block pre span { + color: var(--shiki-light) !important; +} + +[data-theme="dark"] .shiki-code-block pre, +[data-theme="dark"] .shiki-code-block pre span { + color: var(--shiki-dark) !important; +} + +[data-theme="dark"] .shiki-code-block pre { + background-color: var(--shiki-dark-bg, #1a1a1a) !important; +} + +/* ─── Shiki code block styling ─── */ +.shiki-code-block { + margin-bottom: var(--ifm-leading); + border-radius: 16px; + overflow: hidden; +} + +.shiki-code-block code, +.shiki-code-block span { + background-color: transparent !important; + padding: 0; + border-radius: 0; + font-size: inherit; + font-weight: inherit; +} + +[data-theme="light"] .shiki-code-block pre { + background-color: #f3f3f3; +} + +[data-theme="dark"] .shiki-code-block pre { + background-color: #1a1a1a; +} + +.shiki-code-block-content { + position: relative; + direction: ltr; +} + +/* ─── Shiki copy button ─── */ +.shiki-copy-button { + display: flex; + align-items: center; + position: absolute; + right: calc(var(--ifm-pre-padding) / 2); + top: calc(var(--ifm-pre-padding) / 2); + padding: 0.4rem; + border: 1px solid var(--ifm-color-emphasis-300); + border-radius: var(--ifm-global-radius); + cursor: pointer; + opacity: 0; + transition: opacity 200ms ease-in-out, background-color 200ms ease-in-out; +} + +[data-theme="light"] .shiki-copy-button { + background: #f3f3f3; + color: #333; +} + +[data-theme="dark"] .shiki-copy-button { + background: #1a1a1a; + color: #ccc; +} + +.shiki-code-block:hover .shiki-copy-button { + opacity: 0.4; +} + +.shiki-copy-button:hover, +.shiki-copy-button:focus-visible { + opacity: 1 !important; } [data-theme="light"] .theme-code-block pre { diff --git a/src/theme/CodeBlock/index.tsx b/src/theme/CodeBlock/index.tsx new file mode 100644 index 00000000..333270f2 --- /dev/null +++ b/src/theme/CodeBlock/index.tsx @@ -0,0 +1,86 @@ +/** + * Swizzled CodeBlock — preserves a copy button when children have already been + * transformed into React elements by @shikijs/rehype. + * + * String children → stock StringContent (Prism path, full Docusaurus UI). + * Element children (Shiki) → lightweight wrapper with a standalone copy button. + */ +import React, { isValidElement, useState, useCallback, type ReactNode } from "react"; +import type { Props } from "@theme/CodeBlock"; +import useIsBrowser from "@docusaurus/useIsBrowser"; +import StringContent from "@theme/CodeBlock/Content/String"; +import clsx from "clsx"; + +/** Recursively extract every text-node from a React tree. */ +function extractText(node: ReactNode): string { + if (typeof node === "string") return node; + if (typeof node === "number") return String(node); + if (!node) return ""; + if (Array.isArray(node)) return node.map(extractText).join(""); + if (isValidElement(node)) { + return extractText((node.props as { children?: ReactNode }).children); + } + return ""; +} + +function CopyButton({ code }: { code: string }) { + const [copied, setCopied] = useState(false); + + const handleCopy = useCallback(() => { + navigator.clipboard.writeText(code).then(() => { + setCopied(true); + setTimeout(() => setCopied(false), 1500); + }); + }, [code]); + + return ( + + ); +} + +export default function CodeBlock({ + children: rawChildren, + ...props +}: Props): React.JSX.Element { + const isBrowser = useIsBrowser(); + + // Plain-string children → stock Prism/StringContent path + if (typeof rawChildren === "string") { + return ( + + {rawChildren} + + ); + } + + // Element children (Shiki output) + const code = extractText(rawChildren); + + return ( +
+
+ 
+					{rawChildren}
+
+ {isBrowser && } +
+
+ ); +} From 92fca6d0a0554046118be1286095d2e05d3b1ce1 Mon Sep 17 00:00:00 2001 From: Timothy Jaeryang Baek Date: Thu, 2 Apr 2026 19:33:05 -0500 Subject: [PATCH 04/25] refac --- docs/features/access-security/rbac/groups.md | 2 +- .../chat-features/index.mdx | 2 +- .../chat-features/temporal-awareness.mdx | 2 +- .../chat-features/url-params.md | 2 +- docs/features/chat-conversations/rag/index.md | 2 +- .../extensibility/plugin/tools/index.mdx | 2 +- docs/features/index.mdx | 531 +++++------------- .../_category_.json | 0 .../{ai-knowledge => workspace}/knowledge.md | 0 .../{ai-knowledge => workspace}/models.md | 4 +- .../{ai-knowledge => workspace}/prompts.md | 0 .../{ai-knowledge => workspace}/skills.md | 2 +- docs/reference/env-configuration.mdx | 2 +- docs/troubleshooting/rag.mdx | 2 +- 14 files changed, 137 insertions(+), 416 deletions(-) rename docs/features/{ai-knowledge => workspace}/_category_.json (100%) rename docs/features/{ai-knowledge => workspace}/knowledge.md (100%) rename docs/features/{ai-knowledge => workspace}/models.md (98%) rename docs/features/{ai-knowledge => workspace}/prompts.md (100%) rename docs/features/{ai-knowledge => workspace}/skills.md (97%) diff --git a/docs/features/access-security/rbac/groups.md b/docs/features/access-security/rbac/groups.md index b178f137..2f6ae72a 100644 --- a/docs/features/access-security/rbac/groups.md +++ b/docs/features/access-security/rbac/groups.md @@ -70,7 +70,7 @@ You can restrict access to specific objects (like a proprietary Model or sensiti 2. **Grant Access**: Select the specific **Groups** or **individual users** that should have "Read" or "Write" access. The redesigned access control UI makes it easy to add multiple groups or users at once. :::tip Knowledge Scoping for Models -Beyond visibility, knowledge access is also scoped by model configuration. When a model has **attached knowledge bases**, it can only access those specific KBs (not all user-accessible KBs). See [Knowledge Scoping with Native Function Calling](/features/ai-knowledge/knowledge#knowledge-scoping-with-native-function-calling) for details. +Beyond visibility, knowledge access is also scoped by model configuration. When a model has **attached knowledge bases**, it can only access those specific KBs (not all user-accessible KBs). See [Knowledge Scoping with Native Function Calling](/features/workspace/knowledge#knowledge-scoping-with-native-function-calling) for details. ::: ### Access Grant System diff --git a/docs/features/chat-conversations/chat-features/index.mdx b/docs/features/chat-conversations/chat-features/index.mdx index aa23ac2a..46e82aa2 100644 --- a/docs/features/chat-conversations/chat-features/index.mdx +++ b/docs/features/chat-conversations/chat-features/index.mdx @@ -27,6 +27,6 @@ Open WebUI provides a comprehensive set of chat features designed to enhance you - **[💬 Follow-Up Prompts](./follow-up-prompts.md)**: Automatic generation of suggested follow-up questions after model responses. -- **Skill Mentions**: Use `$` in the chat input to mention and activate [Skills](/features/ai-knowledge/skills) on-the-fly, injecting their manifests into the conversation. +- **Skill Mentions**: Use `$` in the chat input to mention and activate [Skills](/features/workspace/skills) on-the-fly, injecting their manifests into the conversation. - **Writing & Content Blocks**: Responses from models that include colon-fence blocks (e.g., `:::writing`, `:::code_execution`, `:::search_results`) are automatically rendered as formatted content in a styled container with a copy button. This is commonly used by newer OpenAI models to distinguish different types of output (prose, code results, search results) from the main response text. diff --git a/docs/features/chat-conversations/chat-features/temporal-awareness.mdx b/docs/features/chat-conversations/chat-features/temporal-awareness.mdx index 9c84effb..80d2f8b2 100644 --- a/docs/features/chat-conversations/chat-features/temporal-awareness.mdx +++ b/docs/features/chat-conversations/chat-features/temporal-awareness.mdx @@ -14,7 +14,7 @@ By default, Open WebUI injects temporal variables into the model's environment v - **`CURRENT_TIME`**: Injected as HH:MM. - **`CURRENT_WEEKDAY`**: (e.g., Monday, Tuesday). -These variables can be manually used in [**Prompts**](/features/ai-knowledge/prompts) or [**Model Files**](/features/ai-knowledge/models) using the `{{CURRENT_DATE}}` syntax. +These variables can be manually used in [**Prompts**](/features/workspace/prompts) or [**Model Files**](/features/workspace/models) using the `{{CURRENT_DATE}}` syntax. --- diff --git a/docs/features/chat-conversations/chat-features/url-params.md b/docs/features/chat-conversations/chat-features/url-params.md index e5c86e5e..feea00cd 100644 --- a/docs/features/chat-conversations/chat-features/url-params.md +++ b/docs/features/chat-conversations/chat-features/url-params.md @@ -25,7 +25,7 @@ The following table lists the available URL parameters, their function, and exam ### 1. **Models and Model Selection** -- **Description**: The `models` and `model` parameters allow you to specify which [language models](/features/ai-knowledge/models) should be used for a particular chat session. +- **Description**: The `models` and `model` parameters allow you to specify which [language models](/features/workspace/models) should be used for a particular chat session. - **How to Set**: You can use either `models` for multiple models or `model` for a single model. - **Example**: - `/?models=model1,model2` – This initializes the chat with `model1` and `model2`. diff --git a/docs/features/chat-conversations/rag/index.md b/docs/features/chat-conversations/rag/index.md index 07bcf3f6..41ba8161 100644 --- a/docs/features/chat-conversations/rag/index.md +++ b/docs/features/chat-conversations/rag/index.md @@ -212,7 +212,7 @@ When File Context is disabled, file content is **not automatically extracted or ::: :::tip Per-File Retrieval Mode -Individual files and knowledge bases can also be set to bypass RAG entirely using the **"Using Entire Document"** toggle. This injects the full file content into every message regardless of native function calling settings. See [Full Context vs Focused Retrieval](/features/ai-knowledge/knowledge#full-context-vs-focused-retrieval) for details. +Individual files and knowledge bases can also be set to bypass RAG entirely using the **"Using Entire Document"** toggle. This injects the full file content into every message regardless of native function calling settings. See [Full Context vs Focused Retrieval](/features/workspace/knowledge#full-context-vs-focused-retrieval) for details. ::: :::info diff --git a/docs/features/extensibility/plugin/tools/index.mdx b/docs/features/extensibility/plugin/tools/index.mdx index 13fb99e8..aedd1c80 100644 --- a/docs/features/extensibility/plugin/tools/index.mdx +++ b/docs/features/extensibility/plugin/tools/index.mdx @@ -362,7 +362,7 @@ The native `query_knowledge_files` tool uses **hybrid search + reranking** when 2. **Or disable Native Function Calling** for that model to restore automatic RAG injection. 3. **Or use "Full Context" mode** for attached knowledge (click on the attachment and select "Use Entire Document") which always injects the full content. -See [Knowledge Scoping with Native Function Calling](/features/ai-knowledge/knowledge#knowledge-scoping-with-native-function-calling) for more details. +See [Knowledge Scoping with Native Function Calling](/features/workspace/knowledge#knowledge-scoping-with-native-function-calling) for more details. ::: **Why use these?** It allows for **Deep Research** (searching the web multiple times, or querying knowledge bases), **Contextual Awareness** (looking up previous chats or notes), **Dynamic Personalization** (saving facts), and **Precise Automation** (generating content based on existing notes or documents). diff --git a/docs/features/index.mdx b/docs/features/index.mdx index 030d9475..98b33cb5 100644 --- a/docs/features/index.mdx +++ b/docs/features/index.mdx @@ -3,482 +3,203 @@ sidebar_position: 200 title: "⭐ Features" --- +# What You Can Do with Open WebUI -## Key Features of Open WebUI ⭐ +**One interface for every AI model. Private, extensible, and built for teams.** -- 🚀 **Effortless Setup**: Install seamlessly using Docker, Kubernetes, Podman, Helm Charts (`kubectl`, `kustomize`, `podman`, or `helm`) for a hassle-free experience with support for both `:ollama` image with bundled Ollama and `:cuda` with CUDA support. [Learn more in our Quick Start Guide](/getting-started/quick-start). - -- 🛠️ **Guided Initial Setup**: Complete the setup process with clarity, including an explicit indication of creating an admin account during the first-time setup. - -- 🤝 **Universal API Compatibility**: Effortlessly integrate with any backend that follows the **OpenAI Chat Completions protocol**. This includes official OpenAI endpoints alongside dozens of third-party and local providers. The API URL can be customized to integrate Open WebUI seamlessly into your existing infrastructure. [See Setup Guide](/getting-started/quick-start). - -- 🛡️ **Granular Permissions and User Groups**: By allowing administrators to create detailed user roles, user groups, and permissions across the workspace, we ensure a secure user environment for all users involved. This granularity not only enhances security, but also allows for customized user experiences, fostering a sense of ownership and responsibility amongst users. [Learn more about RBAC](/features/access-security/rbac). - -- 🔐 **SCIM 2.0 Provisioning**: Enterprise-grade user and group provisioning through SCIM 2.0 protocol, enabling seamless integration with identity providers like Okta, Azure AD, and Google Workspace for automated user lifecycle management. [Read the SCIM Guide](/features/access-security/auth/scim). - -- 📂 **Centralized File Management**: A unified dashboard to search, view, and manage all your uploaded documents in one place. Includes automated cleanup of Knowledge Base associations and vector embeddings when deleting files. [Learn about File Management](/features/chat-conversations/data-controls/files). - -- 💬 **Shared Chat Management**: A centralized interface to audit every conversation you've ever shared. Easily search through your shared history, re-copy links, or revoke (unshare) access instantly from a single location. [Learn about Shared Chats](/features/chat-conversations/data-controls/shared-chats). - -- 📱 **Responsive Design**: Enjoy a seamless experience across desktop PCs, laptops, and mobile devices. - -- 📱 **Progressive Web App for Mobile**: Enjoy a native progressive web application experience on your mobile device with offline access on `localhost` or a personal domain, and a smooth user interface. In order for our PWA to be installable on your device, it must be delivered in a secure context. This usually means that it must be served over HTTPS. - - :::info - - - To set up a PWA, you'll need some understanding of technologies like Linux, Docker, and reverse proxies such as `Nginx`, `Caddy`, or `Traefik`. Using these tools can help streamline the process of building and deploying a PWA tailored to your needs. While there's no "one-click install" option available, and your available option to securely deploy your Open WebUI instance over HTTPS requires user experience, using these resources can make it easier to create and deploy a PWA tailored to your needs. - - ::: - -- ✒️🔢 **Full Markdown and LaTeX Support**: Elevate your LLM experience with comprehensive Markdown, LaTex, and Rich Text capabilities for enriched interaction. [Explore Interface Features](/category/interface). - -- 🧩 **Model Builder**: Easily create custom models from base Ollama models directly from Open WebUI. Create and add custom characters and agents, customize model elements, and import models effortlessly through [Open WebUI Community](https://openwebui.com/) integration. [Learn more about Models](/features/ai-knowledge/models). - -- 📚 **Advanced RAG Integration with Multiple Vector Databases**: Dive into the future of chat interactions with cutting-edge Retrieval Augmented Generation (RAG) technology. Choose from 9 vector database options: ChromaDB (default), PostgreSQL with PGVector, Qdrant, Milvus, Elasticsearch, OpenSearch, Pinecone, S3Vector, and Oracle 23ai. Documents can be loaded into the `Documents` tab of the Workspace and accessed using the pound key [`#`] before a query, or by starting the prompt with [`#`] followed by a URL for webpage content integration. [Learn more about RAG](/features/chat-conversations/rag). - -- 📄 **Advanced Document Extraction with Multiple Engines**: Extract text and data from various document formats including PDFs, Word documents, Excel spreadsheets, PowerPoint presentations, and more using your choice of extraction engines: Apache Tika, Docling, Azure Document Intelligence, Mistral OCR, or external custom (self-built) content extraction engines/document loaders. Advanced document processing capabilities enable seamless integration with your knowledge base, preserving structure and formatting while supporting OCR for scanned documents and images. [Read about Document Extraction](/features/chat-conversations/rag/document-extraction). - -- 🔍 **Web Search for RAG & Agentic Research**: Perform web searches using 15+ providers including SearXNG, Google PSE, Brave Search, Kagi, Mojeek, Bocha, Tavily, Perplexity, and more. When using **Native Function Calling**, models can perform multiple searches sequentially and use the `fetch_url` tool to read full page content for deep research. [Learn about Agentic Search](/features/chat-conversations/web-search/agentic-search). - -- 🌐 **Web Browsing & URL Fetching**: Integrate websites by using the `#` command or allow the model to independently visit links using the `fetch_url` tool in Native Mode, extracting full text content for precise analysis. - -- 🎨 **Image Generation & Editing Integration**: Seamlessly create and edit images using engines like DALL-E, Gemini, ComfyUI, and AUTOMATIC1111. Supports **Native Tool Calling**, allowing models to independently generate and refine images during a conversation. [Learn more about Image Gen](/category/create--edit-images). - -- ⚙️ **Concurrent Model Utilization**: Effortlessly engage with multiple models simultaneously, harnessing their unique strengths for optimal responses. Leverage a diverse set of model modalities in parallel to enhance your experience. - -- 🔐 **Role-Based Access Control (RBAC)**: Ensure secure access with restricted permissions. Only authorized individuals can access your Ollama, while model creation and pulling rights are exclusively reserved for administrators. [Learn more about RBAC](/features/access-security/rbac). - -- 🌐🌍 **Multilingual Support**: Experience Open WebUI in your preferred language with our internationalization (`i18n`) support. We invite you to join us in expanding our supported languages! We're actively seeking contributors! - -- 💾 **Persistent Artifact Storage**: Built-in key-value storage API for artifacts, enabling features like journals, trackers, leaderboards, and collaborative tools with both personal and shared data scopes that persist across sessions. [Explore Chat Features](/features/chat-conversations/chat-features). - -- ☁️ **Cloud Storage Integration**: Native support for cloud storage backends including Amazon S3 (with S3-compatible providers), Google Cloud Storage, and Microsoft Azure Blob Storage for scalable file storage and data management. [See Storage Config](/reference/env-configuration#cloud-storage). - -- ☁️ **Enterprise Cloud Integration**: Seamlessly import documents from Google Drive and OneDrive/SharePoint directly through the file picker interface, enabling smooth workflows with enterprise cloud storage solutions. [Learn more in Environment Config](/reference/env-configuration#onedrive) and check out the [SharePoint Guide](/tutorials/integrations/onedrive-sharepoint/). - -- 📊 **Production Observability with OpenTelemetry**: Built-in OpenTelemetry support for comprehensive monitoring with traces, metrics, and logs export to your existing observability stack (Prometheus, Grafana, Jaeger, etc.), enabling production-grade monitoring and debugging. [See Observability Config](/reference/env-configuration/#opentelemetry-configuration). - -- 🔒 **Encrypted Database Support**: Optional at-rest encryption for SQLite databases using SQLCipher, providing enhanced security for sensitive data in smaller deployments without requiring PostgreSQL infrastructure. [See Database Encryption](/reference/env-configuration#encrypted-sqlite-with-sqlcipher). - -- ⚖️ **Horizontal Scalability for Production**: Redis-backed session management and WebSocket support enabling multi-worker and multi-node deployments behind load balancers for high-availability production environments. [See Advanced Topics](/getting-started/advanced-topics) and our [Multi-Replica Guide](/troubleshooting/multi-replica). - -- 🌟 **Continuous Updates**: We are committed to improving Open WebUI with regular updates, fixes, and new features. - -## And many more remarkable features including... ⚡️ +Open WebUI replaces the patchwork of AI tools your team juggles daily - ChatGPT for writing, a separate app for image generation, another for document search, spreadsheets full of prompts nobody can find. Everything lives in one place: conversations, knowledge, tools, and the models that power them. --- -### 🔧 Pipelines Support +## 💬 Chat & Conversations -- 🔧 **Pipelines Framework**: Seamlessly integrate and customize your Open WebUI experience with our modular plugin framework for enhanced customization and functionality (https://github.com/open-webui/pipelines). Our framework allows for the easy addition of custom logic and integration of Python libraries, from AI agents to home automation APIs. Perfect for plugin and tool development, as well as creating custom functions and filters. [Learn more about Pipelines](/features/extensibility/pipelines). +**Talk to any model, switch mid-conversation, and never lose context.** -- �️ **Native Python Function Calling**: Access the power of Python directly within Open WebUI with native function calling. Easily integrate custom code to build unique features like custom RAG pipelines, web search tools, and even agent-like actions via a built-in code editor to seamlessly develop and integrate function code within the `Tools` and `Functions` workspace. [Learn more about Tools](/features/extensibility/plugin/tools). +Your conversations are the core of Open WebUI. Chat with Ollama, OpenAI, Anthropic, or any OpenAI-compatible provider from a single interface. Attach files, search the web, execute code, and let the AI use tools - all without leaving the chat. -- �📥 **Upload Pipeline**: Pipelines can be uploaded directly from the `Admin Panel` > `Settings` > `Pipelines` menu, streamlining the pipeline management process. +| | | +| :--- | :--- | +| 🔀 **Multi-model chats** | Run two models side-by-side and compare responses | +| 📎 **File & image uploads** | Attach documents, images, and code for the AI to analyze | +| 🔍 **Web search** | AI searches the web and cites sources in real time | +| 🐍 **Code execution** | Run Python directly in the browser or via [Open Terminal](/features/open-terminal) | +| 📝 **Message queue** | Keep typing while the AI responds - messages send automatically | +| 🧠 **Memory** | The AI remembers facts about you across conversations | +| 🗂️ **Folders, tags, pins** | Organize conversations however you work | -#### The possibilities with our Pipelines framework knows no bounds and are practically limitless. Start with a few pre-built pipelines to help you get started! - -- 🔗 **Function Calling**: Integrate [Function Calling](https://github.com/open-webui/pipelines/blob/main/examples/filters/function_calling_filter_pipeline.py) seamlessly through Pipelines to enhance your LLM interactions with advanced function calling capabilities. - -- 📚 **Custom RAG**: Integrate a [custom Retrieval Augmented Generation (RAG)](https://github.com/open-webui/pipelines/tree/main/examples/pipelines/rag) pipeline seamlessly to enhance your LLM interactions with custom RAG logic. - -- 📊 **Message Monitoring with Langfuse**: Monitor and analyze message interactions in real-time usage statistics via [Langfuse](https://github.com/open-webui/pipelines/blob/main/examples/filters/langfuse_filter_pipeline.py) pipeline. - -- ⚖️ **User Rate Limiting**: Manage API usage efficiently by controlling the flow of requests sent to LLMs to prevent exceeding rate limits with [Rate Limit](https://github.com/open-webui/pipelines/blob/main/examples/filters/rate_limit_filter_pipeline.py) pipeline. - -- 🌍 **Real-Time LibreTranslate Translation**: Integrate real-time translations into your LLM interactions using [LibreTranslate](https://github.com/open-webui/pipelines/blob/main/examples/filters/libretranslate_filter_pipeline.py) pipeline, enabling cross-lingual communication. - - Please note that this pipeline requires further setup with LibreTranslate in a Docker container to work. - -- 🛡️ **Toxic Message Filtering**: Our [Detoxify](https://github.com/open-webui/pipelines/blob/main/examples/filters/detoxify_filter_pipeline.py) pipeline automatically filters out toxic messages to maintain a clean and safe chat environment. - -- 🔒 **LLM-Guard**: Ensure secure LLM interactions with [LLM-Guard](https://github.com/open-webui/pipelines/blob/main/examples/filters/llmguard_prompt_injection_filter_pipeline.py) pipeline, featuring a Prompt Injection Scanner that detects and mitigates crafty input manipulations targeting large language models. This protects your LLMs from data leakage and adds a layer of resistance against prompt injection attacks. - -- 🕒 **Conversation Turn Limits**: Improve interaction management by setting limits on conversation turns with [Conversation Turn Limit](https://github.com/open-webui/pipelines/blob/main/examples/filters/conversation_turn_limit_filter.py) pipeline. - -- 📈 **OpenAI Generation Stats**: Our [OpenAI](https://github.com/open-webui/pipelines/blob/main/examples/pipelines/providers/openai_manifold_pipeline.py) pipeline provides detailed generation statistics for OpenAI models. - -- **🚀 Multi-Model Support**: Our seamless integration with various AI models from [various providers](https://github.com/open-webui/pipelines/tree/main/examples/pipelines/providers) expands your possibilities with a wide range of language models to select from and interact with. - -#### In addition to the extensive features and customization options, we also provide [a library of example pipelines ready to use](https://github.com/open-webui/pipelines/tree/main/examples) along with [a practical example scaffold pipeline](https://github.com/open-webui/pipelines/blob/main/examples/scaffolds/example_pipeline_scaffold.py) to help you get started. These resources will streamline your development process and enable you to quickly create powerful LLM interactions using Pipelines and Python. Happy coding! 💡 +[**Explore chat features →**](/features/chat-conversations/chat-features) --- -### 🖥️ User Experience +## 📚 Knowledge & RAG -- 🖥️ **Intuitive Interface**: The chat interface has been designed with the user in mind, drawing inspiration from the user interface of ChatGPT. +**Give your AI access to your documents - and let it find what matters.** -- ⚡ **Swift Responsiveness**: Enjoy reliably fast and responsive performance. +Upload files, build knowledge bases, and let the AI retrieve exactly the information it needs. Choose between vector search (RAG) for large collections or full-content injection for precision. With native function calling, models autonomously search, browse, and synthesize across your entire knowledge base. -- 🎨 **Splash Screen**: A simple loading splash screen for a smoother user experience. +| | | +| :--- | :--- | +| 📄 **9 vector databases** | ChromaDB, PGVector, Qdrant, Milvus, Elasticsearch, and more | +| 🔍 **Hybrid search** | BM25 + vector search with cross-encoder reranking | +| 📑 **5 extraction engines** | Tika, Docling, Azure, Mistral OCR, custom loaders | +| 🤖 **Agentic retrieval** | Models search and read your documents autonomously | +| 📄 **Full context mode** | Inject entire documents - no chunking, no guessing | -- 🌐 **Personalized Interface**: Choose between a freshly designed search landing page and the classic chat UI from Settings > Interface, allowing for a tailored experience. [Explore Interface Options](/category/interface). - -- 📦 **Pip Install Method**: Installation of Open WebUI can be accomplished via the command `pip install open-webui`, which streamlines the process and makes it more accessible to new users. For further information, please visit: https://pypi.org/project/open-webui/. - -- 🌈 **Theme Customization**: Personalize your Open WebUI experience with a range of options, including a variety of solid, yet sleek themes, customizable chat background images, and three mode options: Light, Dark, or OLED Dark mode - or let *Her* choose for you! ;) - -- 🖼️ **Custom Background Support**: Set a custom background from Settings > Interface to personalize your experience. - -- 📝 **Rich Banners with Markdown**: Create visually engaging announcements with markdown support in banners, enabling richer and more dynamic content. [See Banners Documentation](/features/access-security/interface/banners). - -- 💻 **Code Syntax Highlighting**: Our syntax highlighting feature enhances code readability, providing a clear and concise view of your code. - -- 🗨️ **Markdown Rendering in User Messages**: User messages are now rendered in Markdown, enhancing readability and interaction. - -- 🎨 **Flexible Text Input Options**: Switch between rich text input and legacy text area input for chat, catering to user preferences and providing a choice between advanced formatting and simpler text input. - -- 👆 **Effortless Code Sharing** : Streamline the sharing and collaboration process with convenient code copying options, including a floating copy button in code blocks and click-to-copy functionality from code spans, saving time and reducing frustration. - -- 🎨 **Interactive Artifacts**: Render web content and SVGs directly in the interface, supporting quick iterations and live changes for enhanced creativity and productivity. - -- 🖊️ **Live Code Editing**: Supercharged code blocks allow live editing directly in the LLM response, with live reloads supported by artifacts, streamlining coding and testing. - -- 🔍 **Enhanced SVG Interaction**: Pan and zoom capabilities for SVG images, including Mermaid diagrams, enable deeper exploration and understanding of complex concepts. - -- 🔍 **Text Select Quick Actions**: Floating buttons appear when text is highlighted in LLM responses, offering deeper interactions like "Ask a Question" or "Explain", and enhancing overall user experience. - -- ↕️ **Bi-Directional Chat Support**: You can easily switch between left-to-right and right-to-left chat directions to accommodate various language preferences. - -- 📱 **Mobile Accessibility**: The sidebar can be opened and closed on mobile devices with a simple swipe gesture. - -- 🤳 **Haptic Feedback on Supported Devices**: Android devices support haptic feedback for an immersive tactile experience during certain interactions. - -- 🔍 **User Settings Search**: Quickly search for settings fields, improving ease of use and navigation. - -- 📜 **Offline Swagger Documentation**: Access developer-friendly Swagger API documentation offline, ensuring full accessibility wherever you are. - -- 💾 **Performance Optimizations**: Lazy loading of large dependencies minimizes initial memory usage, boosting performance and reducing loading times. - -- 🚀 **Persistent and Scalable Configuration**: Open WebUI configurations are stored in a database (webui.db), allowing for seamless load balancing, high-availability setups, and persistent settings across multiple instances, making it easy to access and reuse your configurations. - -- 🔄 **Portable Import/Export**: Easily import and export Open WebUI configurations, simplifying the process of replicating settings across multiple systems. - -- ❓ **Quick Access to Documentation & Shortcuts**: The question mark button located at the bottom right-hand corner of the main UI screen (available on larger screens like desktop PCs and laptops) provides users with easy access to the Open WebUI documentation page and available keyboard shortcuts. - -- 📜 **Changelog & Check for Updates**: Users can access a comprehensive changelog and check for updates in the `Settings` > `About` > `See What's New` menu, which provides a quick overview of the latest features, improvements, and bug fixes, as well as the ability to check for updates. +[**Learn about Knowledge →**](/features/workspace/knowledge) --- -### 💬 Conversations +## 🤖 Models & Agents -- 💬 **True Asynchronous Chat**: Enjoy uninterrupted multitasking with true asynchronous chat support, allowing you to create chats, navigate away, and return anytime with responses ready. +**Wrap any model with custom instructions, tools, and knowledge to build specialized agents.** -- 🔔 **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. +Create a "Python Tutor" that always uses your style guide. A "Meeting Summarizer" with your company's template. A "Code Reviewer" with your linting rules baked in. Every agent is a configuration wrapper - pick any base model, bind knowledge, tools, and a system prompt. -- 📝 **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-conversations/chat-features/message-queue). +| | | +| :--- | :--- | +| 🧩 **Model presets** | System prompts, tools, knowledge, and parameters in one package | +| 🏷️ **Dynamic variables** | `{{ USER_NAME }}`, `{{ CURRENT_DATE }}` injected automatically | +| 🔧 **Bound tools** | Force-enable specific tools per model | +| 👥 **Access control** | Restrict models to specific users or groups | +| 📊 **Global defaults** | Set baseline capabilities and parameters for all models | -- 🌐 **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/access-security/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). - -- 🖊️ **Typing Indicators in Channels**: Enhance collaboration with real-time typing indicators in channels, keeping everyone engaged and informed. - -- 👤 **User Status Indicators**: Quickly view a user's status by clicking their profile image in channels, providing better coordination and availability insights. This feature can be globally disabled by an administrator (Admin > Settings > General). - -- 💬 **Chat Controls**: Easily adjust parameters for each chat session, offering more precise control over your interactions. - -- 💖 **Favorite Response Management**: Easily mark and organize favorite responses directly from the chat overview, enhancing ease of retrieval and access to preferred responses. - -- 📌 **Pinned Chats**: Support for pinned chats, allowing you to keep important conversations easily accessible. - -- 🔍 **RAG Embedding Support**: Change the Retrieval Augmented Generation (RAG) embedding model directly in the `Admin Panel` > `Settings` > `Documents` menu, enhancing document processing. This feature supports Ollama and OpenAI models. - -- 📜 **Citations in RAG Feature**: The Retrieval Augmented Generation (RAG) feature allows users to easily track the context of documents fed to LLMs with added citations for reference points. - -- 🌟 **Enhanced RAG Pipeline**: A togglable hybrid search sub-feature for our RAG embedding feature that enhances the RAG functionality via `BM25`, with re-ranking powered by `CrossEncoder`, and configurable relevance score thresholds. - -- 📹 **YouTube RAG Pipeline**: The dedicated Retrieval Augmented Generation (RAG) pipeline for summarizing YouTube videos via video URLs enables smooth interaction with video transcriptions directly. - -- 📁 **Comprehensive Document Retrieval**: Toggle between full document retrieval and traditional snippets, enabling comprehensive tasks like summarization and supporting enhanced document capabilities. - -- 🌟 **RAG Citation Relevance**: Easily assess citation accuracy with the addition of relevance percentages in RAG results. - -- 🗂️ **Advanced RAG**: Improve RAG accuracy with smart pre-processing of chat history to determine the best queries before retrieval. - -- 📚 **Inline Citations for RAG**: Benefit from seamless inline citations for Retrieval-Augmented Generation (RAG) responses, improving traceability and providing source clarity for newly uploaded files. - -- 📁 **Large Text Handling**: Optionally convert large pasted text into a file upload to be used directly with RAG, keeping the chat interface cleaner. - -- 🔄 **Multi-Modal Support**: Effortlessly engage with models that support multi-modal interactions, including images (`e.g., LLaVA`). - -- 🤖 **Multiple Model Support**: Quickly switch between different models for diverse chat interactions. - -- 🔀 **Merge Responses in Many Model Chat**: Enhances the dialogue by merging responses from multiple models into a single, coherent reply. - -- ✅ **Multiple Instances of Same Model in Chats**: Enhanced many model chat to support adding multiple instances of the same model. - -- 💬 **Temporary Chat Feature**: Introduced a temporary chat feature, deprecating the old chat history setting to enhance user interaction flexibility. Please note that **document processing in temporary chats is performed entirely in the browser** to ensure privacy and data minimization. This means specific file types requiring backend processing (like complex DOCX parsing) may have limited functionality in temporary mode. - -- 🖋️ **User Message Editing**: Enhanced the user chat editing feature to allow saving changes without sending. - -- 💬 **Efficient Conversation Editing**: Create new message pairs quickly and intuitively using the Cmd/Ctrl+Shift+Enter shortcut, streamlining conversation length tests. - -- 🖼️ **Client-Side Image Compression**: Save bandwidth and improve performance with client-side image compression, allowing you to compress images before upload from Settings > Interface. - -- 👥 **'@' Model Integration**: By seamlessly switching to any accessible local or external model during conversations, users can harness the collective intelligence of multiple models in a single chat. This can done by using the `@` command to specify the model by name within a chat. - -- 🏷️ **Conversation Tagging** : Effortlessly categorize and locate tagged chats for quick reference and streamlined data collection using our efficient 'tag:' query system, allowing you to manage, search, and organize your conversations without cluttering the interface. - -- 🧠 **Auto-Tagging**: Conversations can optionally be automatically tagged for improved organization, mirroring the efficiency of auto-generated titles. - -- 👶 **Chat Cloning**: Easily clone and save a snapshot of any chat for future reference or continuation. This feature makes it easy to pick up where you left off or share your session with others. To create a copy of your chat, simply click on the `Clone` button in the chat's dropdown options. Can you keep up with your clones? - -- ⭐ **Visualized Conversation Flows**: Interactive messages diagram for improved visualization of conversation flows, enhancing understanding and navigation of complex discussions. - -- 📁 **Chat Folders**: Organize your chats into folders, drag and drop them for easy management, and export them seamlessly for sharing or analysis. - -- 📤 **Easy Chat Import**: Import chats into your workspace by simply dragging and dropping chat exports (JSON) onto the sidebar. - -- 📜 **Prompt Preset Support**: Instantly access custom preset prompts using the `/` command in the chat input. Load predefined conversation starters effortlessly and expedite your interactions. Import prompts with ease through [Open WebUI Community](https://openwebui.com/) integration or create your own! - -- 📅 **Prompt Variables Support**: Prompt variables such as `{{CLIPBOARD}}`, `{{CURRENT_DATE}}`, `{{CURRENT_DATETIME}}`, `{{CURRENT_TIME}}`, `{{CURRENT_TIMEZONE}}`, `{{CURRENT_WEEKDAY}}`, `{{USER_NAME}}`, `{{USER_LANGUAGE}}`, and `{{USER_LOCATION}}` can be utilized in the system prompt or by using a slash command to select a prompt directly within a chat. - - Please note that the `{{USER_LOCATION}}` prompt variable requires a secure connection over HTTPS. To utilize this particular prompt variable, please ensure that `{{USER_LOCATION}}` is toggled on from the `Settings` > `Interface` menu. - - Please note that the `{{CLIPBOARD}}` prompt variables requires access to your device's clipboard. - -- 🧠 **Memory Feature & Tools (Experimental)**: Manage information you want your LLMs to remember via `Settings` > `Personalization` > `Memory`. Capable models can now use `add_memory`, `search_memories`, and `replace_memory_content` tools to dynamically store, retrieve, and update facts about you during chat sessions. [Learn more about Memory](/features/chat-conversations/memory). +[**Learn about Models →**](/features/workspace/models) --- -### 💻 Model Management +## 📝 Notes -- 🛠️ **Model Builder**: All models can be built and edited with a persistent model builder mode within the models edit page. +**Write, think, and refine with AI by your side.** -- 📚 **Knowledge Support for Models**: The ability to attach tools, functions, and knowledge collections directly to models from a model's edit page, enhancing the information available to each model. +A dedicated workspace for content that lives outside of any single conversation. Draft with a rich editor, use AI to rewrite text in place, and attach notes to any chat for precise context injection - no chunking, no vector search. -- 🗂️ **Model Presets**: Create and manage model presets for both the Ollama and OpenAI API. +| | | +| :--- | :--- | +| ✍️ **Rich editor** | Markdown and Rich Text with a floating formatting toolbar | +| 🤖 **AI Enhance** | Rewrite or improve selected text in place | +| 📎 **Context injection** | Attach notes to any chat for full-fidelity context | +| 🔍 **Agentic access** | Models can search, read, and update notes autonomously | -- 🏷️ **Model Tagging**: The models workspace enables users to organize their models using tagging. - -- 📋 **Model Selector Dropdown Ordering**: Models can be effortlessly organized by dragging and dropping them into desired positions within the model workspace, which will then reflect the changes in the model dropdown menu. - -- 🔍 **Model Selector Dropdown**: Easily find and select your models with fuzzy search and detailed model information with model tags and model descriptions. - -- ⌨️ **Arrow Keys Model Selection**: Use arrow keys for quicker model selection, enhancing accessibility. - -- 🔧 **Quick Actions in Model Workspace**: Enhanced Shift key quick actions for hiding/displaying and deleting models in the model workspace. - -- 😄 **Transparent Model Usage**: Stay informed about the system's state during queries with knowledge-augmented models, thanks to visible status displays. - -- ⚙️ **Fine-Tuned Control with Advanced Parameters**: Gain a deeper level of control by adjusting model parameters such as `seed`, `temperature`, `frequency penalty`, `context length`, `seed`, and more. - -- 🔄 **Seamless Integration**: Copy any `ollama run {model:tag}` CLI command directly from a model's page on [Ollama library](https://ollama.com/library/) and paste it into the model dropdown to easily select and pull models. - -- 🗂️ **Create Ollama Modelfile**: To create a model file for Ollama, navigate to the `Admin Panel` > `Settings` > `Models` > `Create a model` menu. - -- ⬆️ **GGUF File Model Creation**: Effortlessly create Ollama models by uploading GGUF files directly from Open WebUI from the `Admin Settings` > `Settings` > `Model` > `Experimental` menu. The process has been streamlined with the option to upload from your machine or download GGUF files from Hugging Face. - -- ⚙️ **Default Model Setting**: The default model preference for new chats can be set in the `Settings` > `Interface` menu on mobile devices, or can more easily be set in a new chat under the model selector dropdown on desktop PCs and laptops. - -- 💡 **LLM Response Insights**: Details of every generated response can be viewed, including external model API insights and comprehensive local model info. - -- 🕒 **Model Details at a Glance**: View critical model details, including model hash and last modified timestamp, directly in the Models workspace for enhanced tracking and management. - -- 📥🗑️ **Download/Delete Models**: Models can be downloaded or deleted directly from Open WebUI with ease. - -- 🔄 **Update All Ollama Models**: A convenient button allows users to update all their locally installed models in one operation, streamlining model management. - -- 🍻 **TavernAI Character Card Integration**: Experience enhanced visual storytelling with TavernAI Character Card Integration in our model builder. Users can seamlessly incorporate TavernAI character card PNGs directly into their model files, creating a more immersive and engaging user experience. - -- 🎲 **Model Playground (Beta)**: Try out models with the model playground area (`beta`), which enables users to test and explore model capabilities and parameters with ease in a sandbox environment before deployment in a live chat environment. Export your playground conversations in JSON format (compatible with Open WebUI chat import) or as plain text for easy sharing and documentation. +[**Learn about Notes →**](/features/notes) --- -### 👥 Collaboration +## 💬 Channels -- 🗨️ **Local Chat Sharing**: Generate and share chat links between users in an efficient and seamless manner. Includes a **centralized management interface** in Settings to view, copy links, or unshare conversations at any time. [Learn more about Chat Sharing](/features/chat-conversations/chat-features/chatshare). +**Where your team and AI think together, in real time.** -- 👍👎 **RLHF Annotation**: Enhance the impact of your messages by rating them with either a thumbs up or thumbs down AMD provide a rating for the response on a scale of 1-10, followed by the option to provide textual feedback, facilitating the creation of datasets for Reinforcement Learning from Human Feedback (`RLHF`). Utilize your messages to train or fine-tune models, all while ensuring the confidentiality of locally saved data. +Persistent, shared spaces where humans and AI models participate in the same conversation. Tag `@gpt-4o` to draft a plan, then tag `@claude` to critique it - your whole team sees both responses in one timeline. -- 🔧 **Comprehensive Feedback Export**: Export feedback history data to JSON for seamless integration with RLHF processing and further analysis, providing valuable insights for improvement. +| | | +| :--- | :--- | +| 🤖 **@model tagging** | Summon any AI model into the conversation on demand | +| 🧵 **Threads & reactions** | Replies, pins, and emoji reactions | +| 🔒 **Access control** | Public, private, group-based, and direct message channels | +| 🧠 **AI channel awareness** | Models search and synthesize across channels autonomously | -- 🤝 **Community Sharing**: Share your chat sessions with the [Open WebUI Community](https://openwebui.com/) by clicking the `Share to Open WebUI Community` button. This feature allows you to engage with other users and collaborate on the platform. - - To utilize this feature, please sign-in to your Open WebUI Community account. Sharing your chats fosters a vibrant community, encourages knowledge sharing, and facilitates joint problem-solving. Please note that community sharing of chat sessions is an optional feature. Only Admins can toggle this feature on or off in the `Admin Settings` > `Settings` > `General` menu. - -- 🏆 **Community Leaderboard**: Compete and track your performance in real-time with our leaderboard system, which utilizes the ELO rating system and allows for optional sharing of feedback history. - -- ⚔️ **Model Evaluation Arena**: Conduct blind A/B testing of models directly from the Admin Settings for a true side-by-side comparison, making it easier to find the best model for your needs. - -- 🎯 **Topic-Based Rankings**: Discover more accurate rankings with our experimental topic-based re-ranking system, which adjusts leaderboard standings based on tag similarity in feedback. [Learn more about Evaluation](/features/access-security/evaluation). - -- 📂 **Unified and Collaborative Workspace** : Access and manage all your model files, prompts, documents, tools, and functions in one convenient location, while also enabling multiple users to collaborate and contribute to models, knowledge, prompts, or tools, streamlining your workflow and enhancing teamwork. +[**Learn about Channels →**](/features/channels) --- -### 📚 History & Archive +## ⚡ Open Terminal -- 📜 **Chat History**: Access and manage your conversation history with ease via the chat navigation sidebar. Toggle off chat history in the `Settings` > `Chats` menu to prevent chat history from being created with new interactions. +**Give your AI a real computer to work on.** -- 🔄 **Regeneration History Access**: Easily revisit and explore your entire LLM response regeneration history. +Connect a real computing environment to Open WebUI. The AI writes code, executes it, reads the output, fixes errors, and iterates - all from the chat. Handles files, installs packages, runs servers, and returns results. -- 📬 **Archive Chats**: Effortlessly store away completed conversations you've had with models for future reference or interaction, maintaining a tidy and clutter-free chat interface. +| | | +| :--- | :--- | +| 🖥️ **Code execution** | Runs real commands and returns output | +| 📁 **File browser** | Browse, upload, download, and edit files in the sidebar | +| 🌐 **Website preview** | Live preview of web projects inside Open WebUI | +| 🔒 **Isolation optional** | Docker container or bare metal | -- 🗃️ **Archive All Chats**: This feature allows you to quickly archive all of your chats at once. - -- 📦 **Export All Archived Chats as JSON**: This feature enables users to easily export all their archived chats in a single JSON file, which can be used for backup or transfer purposes. - -- 📄 **Download Chats as JSON/PDF/TXT**: Easily download your chats individually in your preferred format of `.json`, `.pdf`, or `.txt` format. - -- 📤📥 **Import/Export Chat History**: Seamlessly move your chat data in and out of the platform via `Import Chats` and `Export Chats` options. - -- 🗑️ **Delete All Chats**: This option allows you to permanently delete all of your chats, ensuring a fresh start. +[**Learn about Open Terminal →**](/features/open-terminal) --- -### 🎙️ Audio, Voice, & Accessibility +## 🔌 Extensibility -- 🗣️ **Voice Input Support with Multiple Providers**: Engage with your model through voice interactions using multiple Speech-to-Text providers: Local Whisper (default, with VAD filtering), OpenAI-compatible endpoints, Deepgram, and Azure Speech Services. Enjoy the convenience of talking to your model directly with automatic voice input after 3 seconds of silence for a streamlined experience. [Explore Audio Features](/category/speech-to-text--text-to-speech). - - Microphone access requires manually setting up a secure connection over HTTPS to work, or [manually whitelisting your URL at your own risk](/troubleshooting/audio#solutions-for-non-https-connections). +**Add any capability with Python tools, pipelines, MCP, or OpenAPI servers.** -- 😊 **Emoji Call**: Toggle this feature on from the `Settings` > `Interface` menu, allowing LLMs to express emotions using emojis during voice calls for a more dynamic interaction. - - Microphone access requires manually setting up a secure connection over HTTPS to work, or [manually whitelisting your URL at your own risk](/troubleshooting/audio#solutions-for-non-https-connections). +Open WebUI is a platform, not a locked-down product. Write Python tools that run inside the chat. Connect external services via OpenAPI or MCP. Build pipelines that filter, transform, or route every message. Import community-built extensions with one click. -- 🎙️ **Hands-Free Voice Call Feature**: Initiate voice calls without needing to use your hands, making interactions more seamless. - - Microphone access requires manually setting up a secure connection over HTTPS to work, or [manually whitelisting your URL at your own risk](/troubleshooting/audio#solutions-for-non-https-connections). +| | | +| :--- | :--- | +| 🐍 **Tools & Functions** | Python scripts that run in the chat - built-in code editor included | +| 🔧 **Pipelines** | Modular plugin framework for filters, providers, and custom logic | +| 🔗 **MCP support** | Native Streamable HTTP for Model Context Protocol servers | +| 🌐 **OpenAPI servers** | Auto-discover tools from any OpenAPI-compatible endpoint | +| 📝 **Skills** | Markdown instruction sets that teach models how to approach tasks | +| ⚡ **Prompts** | Slash-command templates with typed input variables and versioning | -- 📹 **Video Call Feature**: Enable video calls with supported vision models like LlaVA and GPT-4o, adding a visual dimension to your communications. - - Both Camera & Microphone access is required using a secure connection over HTTPS for this feature to work, or [manually whitelisting your URL at your own risk](/troubleshooting/audio#solutions-for-non-https-connections). - -- 👆 **Tap to Interrupt**: Stop the AI’s speech during voice conversations with a simple tap on mobile devices, ensuring seamless control over the interaction. - -- 🎙️ **Voice Interrupt**: Stop the AI’s speech during voice conversations with your voice on mobile devices, ensuring seamless control over the interaction. - -- 🔊 **Multiple Text-to-Speech Providers**: Customize your Text-to-Speech experience with multiple providers: OpenAI-compatible endpoints, Azure Speech Services, ElevenLabs (with EU residency support), local Transformers models, and browser-based WebAPI for reading aloud LLM responses. - -- 🔗 **Direct Call Mode Access**: Activate call mode directly from a URL, providing a convenient shortcut for mobile device users. - -- ✨ **Customizable Text-to-Speech**: Control how message content is segmented for Text-to-Speech (TTS) generation requests, allowing for flexible speech output options. - -- 🔊 **Azure Speech Services Integration**: Supports Azure Speech services for Text-to-Speech (TTS), providing users with a wider range of speech synthesis options. - -- 🎚️ **Customizable Audio Playback**: Allows users to adjust audio playback speed to their preferences in Call mode settings, enhancing accessibility and usability. - -- 🎵 **Broad Audio Compatibility**: Enjoy support for a wide range of audio file format transcriptions with RAG, including 'audio/x-m4a', to broaden compatibility with audio content within the platform. - -- 🎤 **Deepgram Speech-to-Text Integration**: Leverage Deepgram's advanced speech recognition capabilities for high-accuracy voice transcription, providing an additional STT option beyond local Whisper and OpenAI. - -- 🔊 **ElevenLabs Text-to-Speech Integration**: Access ElevenLabs' premium voice synthesis with support for EU residency API endpoints, offering high-quality and natural-sounding voice output for enhanced user experiences. - -- 🔊 **Audio Compression**: Experimental audio compression allows navigating around the 25MB limit for OpenAI's speech-to-text processing, expanding the possibilities for audio-based interactions. - -- 🗣️ **Experimental SpeechT5 TTS**: Enjoy local SpeechT5 support for improved text-to-speech capabilities. +[**Learn about Extensibility →**](/features/extensibility/plugin) --- -### 🐍 Code Execution +## 🎙️ Voice & Audio -- 🚀 **Versatile, UI-Agnostic, OpenAI-Compatible Plugin Framework**: Seamlessly integrate and customize [Open WebUI Pipelines](https://github.com/open-webui/pipelines) for efficient data processing and model training, ensuring ultimate flexibility and scalability. -- 🐍 **Python Code Execution**: Execute Python code locally in the browser via Pyodide with a range of libraries supported by Pyodide. +**Talk to your AI - and have it talk back.** -- 🌊 **Mermaid Rendering**: Create visually appealing diagrams and flowcharts directly within Open WebUI using the [Mermaid Diagramming and charting tool](https://mermaid.js.org/intro/), which supports Mermaid syntax rendering. - -- 🔗 **Iframe Support**: Enables rendering HTML directly into your chat interface using functions and tools. +Multiple Speech-to-Text and Text-to-Speech providers, hands-free voice calls, video calls with vision models, and customizable playback. Works with local Whisper, OpenAI, Deepgram, Azure, ElevenLabs, and browser-native WebAPI. +| | | +| :--- | :--- | +| 🎤 **Speech-to-Text** | Whisper (local), OpenAI, Deepgram, Azure | +| 🔊 **Text-to-Speech** | OpenAI, Azure, ElevenLabs, local Transformers, WebAPI | +| 📞 **Voice & video calls** | Hands-free calls with vision model support | +| 🎚️ **Playback controls** | Adjustable speed, tap to interrupt, voice interrupt | +[**Explore Audio features →**](/category/speech-to-text--text-to-speech) --- -### 🔒 Integration & Security +## 🎨 Image Generation & Editing -- ✨ **Multiple OpenAI-Compatible API Support**: Seamlessly integrate and customize various OpenAI-compatible APIs, enhancing the versatility of your chat interactions. +**Create and edit images with DALL-E, Gemini, ComfyUI, and AUTOMATIC1111.** -- 🔑 **Simplified API Key Management**: Easily generate and manage secret keys to leverage Open WebUI with OpenAI libraries, streamlining integration and development. +Generate images from text prompts or edit existing ones. With native tool calling, models independently generate and refine images during a conversation. -- 🌐 **HTTP/S Proxy Support**: Configure network settings easily using the `http_proxy` or `https_proxy` environment variable. These variables, if set, should contain the URLs for HTTP and HTTPS proxies, respectively. For web search content fetching behind a proxy, enable **Trust Proxy Environment** in Admin Panel > Settings > Web Search (or set `WEB_SEARCH_TRUST_ENV=True`). +| | | +| :--- | :--- | +| 🖼️ **Multiple engines** | DALL-E, Gemini, ComfyUI, AUTOMATIC1111, Lumenfall | +| 🤖 **Agentic generation** | Models generate images autonomously during chat | +| ✏️ **Image editing** | Modify existing images with natural language | -- 🌐🔗 **External Ollama Server Connectivity**: Seamlessly link to an external Ollama server hosted on a different address by configuring the environment variable. - -- 🛢️ **Flexible Database Integration**: Seamlessly connect to custom databases, including SQLite, Postgres, and multiple vector databases like Milvus, using environment variables for flexible and scalable data management. - -- 🗄️ **Multiple Vector Database Support**: Choose from 9 vector database options for optimal RAG performance: ChromaDB (default), PostgreSQL with PGVector, Qdrant, Milvus, Elasticsearch, OpenSearch, Pinecone, S3Vector, and Oracle 23ai. Each option provides different scaling characteristics and performance profiles to match your deployment needs. - -- ☁️ **Enterprise Cloud Storage Backends**: Configure cloud storage backends including Amazon S3 (with S3-compatible providers like MinIO), Google Cloud Storage, and Microsoft Azure Blob Storage for scalable file storage, enabling stateless instances and distributed deployments. - -- 📂 **Cloud File Picker Integration**: Import documents directly from Google Drive and OneDrive/SharePoint through native file picker interfaces, streamlining workflows for users working with enterprise cloud storage solutions. - -- 🌐🗣️ **External Speech-to-Text Support**: The addition of external speech-to-text (`STT`) services provides enhanced flexibility, allowing users to choose their preferred provider for seamless interaction. - -- 🌐 **Remote ChromaDB Support**: Extend the capabilities of your database by connecting to remote ChromaDB servers. - -- 🔀 **Multiple Ollama Instance Load Balancing**: Effortlessly distribute chat requests across multiple Ollama instances for enhanced performance and reliability. - -- 🚀 **Advanced Load Balancing and Reliability**: Utilize enhanced load balancing capabilities, stateless instances with full Redis support, and automatic web socket re-connection to promote better performance, reliability, and scalability in WebUI, ensuring seamless and uninterrupted interactions across multiple instances. - -- ☁️ **Cloud Storage Backend Support**: Enable stateless Open WebUI instances with cloud storage backends (Amazon S3, Google Cloud Storage, Microsoft Azure Blob Storage) for enhanced scalability, high availability, and balancing heavy workloads across multiple instances. - -- 🛠️ **OAuth Management for User Groups**: Enhance control and scalability in collaborative environments with group-level management via OAuth integration. - -- 🔐 **SCIM 2.0 Automated Provisioning**: Enterprise-grade user and group provisioning through SCIM 2.0 protocol, enabling seamless integration with identity providers like Okta, Azure AD, and Google Workspace for automated user lifecycle management, reducing administrative overhead. - -- 📊 **OpenTelemetry Observability**: Export traces, metrics, and logs to your observability stack using OpenTelemetry protocol (OTLP), supporting both gRPC and HTTP exporters with configurable endpoints, authentication, and sampling strategies for comprehensive production monitoring. +[**Explore Image Generation →**](/category/create--edit-images) --- -### 👑 Administration +## 🔒 Access & Security -- 👑 **Super Admin Assignment**: Automatically assigns the first sign-up as a super admin with an unchangeable role that cannot be modified by anyone else, not even other admins. +**Role-based access, SSO, SCIM provisioning, and granular permissions.** -- 🛡️ **Granular User Permissions**: Restrict user actions and access with customizable role-based permissions, ensuring that only authorized individuals can perform specific tasks. +Open WebUI is multi-user from day one. Define roles, create user groups, set per-model access, and integrate with your identity provider. From a solo install to an organization with thousands of seats. -- 👥 **Multi-User Management**: Intuitive admin panel with pagination allows you to seamlessly manage multiple users, streamlining user administration and simplifying user life-cycle management. +| | | +| :--- | :--- | +| 👥 **RBAC** | Roles, groups, and per-resource permissions | +| 🔐 **SSO/OIDC/LDAP** | Federated authentication with any identity provider | +| 📋 **SCIM 2.0** | Automated user and group provisioning | +| 📊 **Analytics** | Usage dashboards with message volume, token consumption, and cost tracking | +| 🏆 **Evaluation** | Model arena, A/B testing, and ELO-based leaderboards | +| 🔔 **Webhooks & Banners** | Notifications for sign-ups, chat completion, and admin announcements | -- 🔧 **Admin Panel**: The user management system is designed to streamline the on-boarding and management of users, offering the option to add users directly or in bulk via CSV import. - -- 👥 **Active Users Indicator**: Monitor the number of active users and which models are being utilized by whom to assist in gauging when performance may be impacted due to a high number of users. - -- 📊 **Analytics Dashboard**: Comprehensive usage insights for administrators including message volume, token consumption, user activity, and model performance metrics with interactive time-series charts and detailed breakdowns. Track costs, identify trends, and make data-driven decisions about resource allocation. [Learn more about Analytics](/features/access-security/analytics). - -- 🔒 **Default Sign-Up Role**: Specify the default role for new sign-ups to `pending`, `user`, or `admin`, providing flexibility in managing user permissions and access levels for new users. - -- 🤖 **Bulk Model Management & Filtering**: Administrators can effortlessly manage large model collections from external providers with tools to bulk enable/disable models and filter the admin list by status (Enabled, Disabled, Hidden, etc.) to maintain a clean workspace. [Learn about Admin Models](/features/ai-knowledge/models#global-model-management-admin). - -- 🔒 **Prevent New Sign-Ups**: Enable the option to disable new user sign-ups, restricting access to the platform and maintaining a fixed number of users. - -- 🔒 **Prevent Chat Deletion**: Ability for admins to toggle a setting that prevents all users from deleting their chat messages, ensuring that all chat messages are retained for audit or compliance purposes. - -- 🔗 **Webhook Integration**: Subscribe to new user sign-up events via webhook (compatible with `Discord`, `Google Chat`, `Slack` and `Microsoft Teams`), providing real-time notifications and automation capabilities. [See Webhook Guide](/features/access-security/interface/webhooks). - -- 📣 **Configurable Notification Banners**: Admins can create customizable banners with persistence in config.json, featuring options for content, background color (`info`, `warning`, `error`, or `success`), and dismissibility. Banners are accessible only to logged-in users, ensuring the confidentiality of sensitive information. - -- 🛡️ **Model Whitelisting**: Enhance security and access control by allowing admins to whitelist models for users with the `user` role, ensuring that only authorized models can be accessed. - -- 🔑 **Admin Control for Community Sharing**: Admins can enable or disable community sharing for all users via a toggle in the `Admin Panel` > `Settings` menu. This toggle allows admins to manage accessibility and privacy, ensuring a secure environment. Admins have the option of enabling or disabling the `Share on Community` button for all users, which allows them to control community engagement and collaboration. - -- 📧 **Trusted Email Authentication**: Optionally authenticate using a trusted email header, adding an extra layer of security and authentication to protect your Open WebUI instance. - -- 🔒 **Backend Reverse Proxy Support**: Bolster security through direct communication between Open WebUI's backend and Ollama. This key feature eliminates the need to expose Ollama over the local area network (LAN). Requests made to the `/ollama/api` route from Open WebUI are seamlessly redirected to Ollama from the backend, enhancing overall system security and providing an additional layer of protection. - -- 🔒 **Authentication**: Please note that Open WebUI does not natively support federated authentication schemes such as SSO, OAuth, SAML, or OIDC. However, it can be configured to delegate authentication to an authenticating reverse proxy, effectively achieving a Single Sign-On (`SSO`) experience. This setup allows you to centralize user authentication and management, enhancing security and user convenience. By integrating Open WebUI with an authenticating reverse proxy, you can leverage existing authentication systems and streamline user access to Open WebUI. For more information on configuring this feature, please refer to the [Federated Authentication Support](https://docs.openwebui.com/features/auth). - -- 🔓 **Optional Authentication**: Enjoy the flexibility of disabling authentication by setting `WEBUI_AUTH` to `False`. This is an ideal solution for fresh installations without existing users or can be useful for demonstration purposes. - -- 🚫 **Advanced API Security**: Block API users based on customized model filters, enhancing security and control over API access. - -- ❗ **Administrator Updates**: Ensure administrators stay informed with immediate update notifications upon login, keeping them up-to-date on the latest changes and system statuses. - -- 👥 **User Group Management**: Create and manage user groups for seamless organization and control. - -- 🔐 **Group-Based Access Control**: Set granular access to models, knowledge, prompts, and tools based on user groups, allowing for more controlled and secure environments. - -- 🛠️ **Granular User Permissions**: Easily manage workspace permissions, including file uploads, deletions, edits, and temporary chats, as well as model, knowledge, prompt, and tool creation. [See User Permissions Config](/reference/env-configuration/#user-permissions). - -- 🔑 **LDAP Authentication**: Enhance security and scalability with LDAP support for user management. [Learn more about LDAP](/features/access-security/auth/ldap). - -- 🔐 **SCIM 2.0 Provisioning**: Automate user and group lifecycle management through SCIM 2.0 protocol integration with identity providers like Okta, Azure AD, and Google Workspace, reducing administrative overhead and ensuring synchronized user management across systems. - -- 🌐 **Customizable OpenAI Connections**: Enjoy smooth operation with custom OpenAI setups, including prefix ID support and explicit model ID support for APIs. - -- 🔐 **Ollama API Key Management**: Manage Ollama credentials, including prefix ID support, for secure and efficient operation. - -- 🔄 **Connection Management**: Easily enable or disable individual OpenAI and Ollama connections as needed. - -- 🎨 **Intuitive Model Workspace**: Manage models across users and groups with a redesigned and user-friendly interface. - -- 🔑 **API Key Authentication**: Tighten security by easily enabling or disabling API key authentication. - -- 🔄 **Unified Model Reset**: Reset and remove all models from the Admin Settings with a one-click option. - -- 🔓 **Flexible Model Access Control**: Easily bypass model access controls for user roles when not required, using the 'BYPASS_MODEL_ACCESS_CONTROL' environment variable, simplifying workflows in trusted environments. - -- 🔒 **Configurable API Key Authentication Restrictions**: Flexibly configure endpoint restrictions for API key authentication, now off by default for a smoother setup in trusted environments. +[**Learn about Access & Security →**](/features/access-security/rbac) --- + +## 🏗️ Deploy Anywhere + +**Docker, Kubernetes, pip, bare metal - with horizontal scaling and production observability.** + +| | | +| :--- | :--- | +| 🐳 **Docker & Compose** | One-command deploy with GPU support | +| ☸️ **Kubernetes & Helm** | Production-ready orchestration | +| 📦 **pip install** | `pip install open-webui && open-webui serve` | +| ☁️ **Cloud storage** | S3, GCS, Azure Blob for stateless instances | +| 📊 **OpenTelemetry** | Traces, metrics, and logs to your observability stack | +| ⚖️ **Horizontal scaling** | Redis-backed sessions, multi-worker, multi-node | + +[**Quick Start →**](/getting-started/quick-start) · [**Advanced Topics →**](/getting-started/advanced-topics) diff --git a/docs/features/ai-knowledge/_category_.json b/docs/features/workspace/_category_.json similarity index 100% rename from docs/features/ai-knowledge/_category_.json rename to docs/features/workspace/_category_.json diff --git a/docs/features/ai-knowledge/knowledge.md b/docs/features/workspace/knowledge.md similarity index 100% rename from docs/features/ai-knowledge/knowledge.md rename to docs/features/workspace/knowledge.md diff --git a/docs/features/ai-knowledge/models.md b/docs/features/workspace/models.md similarity index 98% rename from docs/features/ai-knowledge/models.md rename to docs/features/workspace/models.md index fb08dc88..48186614 100644 --- a/docs/features/ai-knowledge/models.md +++ b/docs/features/workspace/models.md @@ -72,9 +72,9 @@ Clicking **Show** on **Advanced Params** allows you to fine-tune the inference g You can transform a generic model into a specialized agent by toggling specific capabilities and binding resources. -- **Knowledge**: Instead of manually selecting documents for every chat, you can bind a specific knowledgebase **Collection** or **File** to this model. Whenever this model is selected, RAG (Retrieval Augmented Generation) is automatically active for those specific files. Click on attached items to toggle between **Focused Retrieval** (RAG chunks) and **Using Entire Document** (full content injection). See [Full Context vs Focused Retrieval](/features/ai-knowledge/knowledge#full-context-vs-focused-retrieval) for details. +- **Knowledge**: Instead of manually selecting documents for every chat, you can bind a specific knowledgebase **Collection** or **File** to this model. Whenever this model is selected, RAG (Retrieval Augmented Generation) is automatically active for those specific files. Click on attached items to toggle between **Focused Retrieval** (RAG chunks) and **Using Entire Document** (full content injection). See [Full Context vs Focused Retrieval](/features/workspace/knowledge#full-context-vs-focused-retrieval) for details. - **Tools**: Force specific tools to be enabled by default (e.g., always enable the **Calculator** tool for a "Math Bot"). -- **Skills**: Bind [Skills](/features/ai-knowledge/skills) to this model so their manifests are always injected. The model can load full skill instructions on-demand via the `view_skill` builtin tool. +- **Skills**: Bind [Skills](/features/workspace/skills) to this model so their manifests are always injected. The model can load full skill instructions on-demand via the `view_skill` builtin tool. - **Filters**: Attach specific Pipelines/Filters (e.g., a Profanity Filter or PII Redaction script) to run exclusively on this model. - **Actions**: Attach actionable scripts like `Add to Memories` or `Button` triggers. - **Capabilities**: Granularly control what the model is allowed to do: diff --git a/docs/features/ai-knowledge/prompts.md b/docs/features/workspace/prompts.md similarity index 100% rename from docs/features/ai-knowledge/prompts.md rename to docs/features/workspace/prompts.md diff --git a/docs/features/ai-knowledge/skills.md b/docs/features/workspace/skills.md similarity index 97% rename from docs/features/ai-knowledge/skills.md rename to docs/features/workspace/skills.md index 612cdd32..b0c57a41 100644 --- a/docs/features/ai-knowledge/skills.md +++ b/docs/features/workspace/skills.md @@ -116,7 +116,7 @@ Add your Open Terminal instance as a Tool Server by following the [OpenAPI Tool Once connected, the Open Terminal tools (execute, file upload, file download) appear automatically in the chat interface. :::tip -For the best experience, pair Open Terminal with a [Skill](/features/ai-knowledge/skills) that teaches the model how to use the tool effectively — for example, instructing it to always check exit codes, handle errors gracefully, and use streaming for long-running commands. +For the best experience, pair Open Terminal with a [Skill](/features/workspace/skills) that teaches the model how to use the tool effectively — for example, instructing it to always check exit codes, handle errors gracefully, and use streaming for long-running commands. ::: See the [Open Terminal documentation](/features/open-terminal) for the full API reference and detailed setup instructions. diff --git a/docs/reference/env-configuration.mdx b/docs/reference/env-configuration.mdx index a848add8..3537b73c 100644 --- a/docs/reference/env-configuration.mdx +++ b/docs/reference/env-configuration.mdx @@ -573,7 +573,7 @@ WEBUI_BANNERS="[{\"id\": \"1\", \"type\": \"warning\", \"title\": \"Your message - Type: `list` of `dict` - Default: `[]` (which means to use the built-in default prompt suggestions) -- Description: Sets global default prompt suggestions shown to users when starting a new chat. These apply when no model-specific prompt suggestions are configured. Prompt suggestions can also be configured per-model via the Model Editor (see [Prompt Suggestions](/features/ai-knowledge/models#prompt-suggestions)), or globally for all models using the [Global Model Defaults](/features/ai-knowledge/models#global-model-defaults) feature. The format is: +- Description: Sets global default prompt suggestions shown to users when starting a new chat. These apply when no model-specific prompt suggestions are configured. Prompt suggestions can also be configured per-model via the Model Editor (see [Prompt Suggestions](/features/workspace/models#prompt-suggestions)), or globally for all models using the [Global Model Defaults](/features/workspace/models#global-model-defaults) feature. The format is: ```json [{"title": ["Title part 1", "Title part 2"], "content": "prompt"}] diff --git a/docs/troubleshooting/rag.mdx b/docs/troubleshooting/rag.mdx index 80afd4ca..b08dbb5b 100644 --- a/docs/troubleshooting/rag.mdx +++ b/docs/troubleshooting/rag.mdx @@ -467,7 +467,7 @@ The most common cause of this issue is a global `Function Calling: native` setti Open WebUI is moving toward **agentic RAG**, where the model autonomously decides when and how to search knowledge bases. This is more powerful than classic RAG because the model can retry searches with different queries if the first attempt didn't yield good results. However, it does require models that are capable of using tools effectively. For smaller or older models that struggle with tool calling, disabling Native Function Calling is the recommended approach. ::: -For the full explanation of how knowledge scoping and retrieval modes work, see the [Knowledge documentation](/features/ai-knowledge/knowledge#native-mode-agentic-mode-knowledge-tools) and [File Context vs Builtin Tools](/features/chat-conversations/rag#file-context-vs-builtin-tools). +For the full explanation of how knowledge scoping and retrieval modes work, see the [Knowledge documentation](/features/workspace/knowledge#native-mode-agentic-mode-knowledge-tools) and [File Context vs Builtin Tools](/features/chat-conversations/rag#file-context-vs-builtin-tools). --- From c538988b96a4c44951df6600aa88f2df241f8936 Mon Sep 17 00:00:00 2001 From: Timothy Jaeryang Baek Date: Thu, 2 Apr 2026 19:46:11 -0500 Subject: [PATCH 05/25] refac --- docs/features/workspace/knowledge.md | 249 ++++++------ docs/features/workspace/models.md | 280 ++++++------- docs/features/workspace/prompts.md | 576 ++++++++++----------------- docs/features/workspace/skills.md | 212 ++++++---- 4 files changed, 595 insertions(+), 722 deletions(-) diff --git a/docs/features/workspace/knowledge.md b/docs/features/workspace/knowledge.md index e02fd685..f767d27b 100644 --- a/docs/features/workspace/knowledge.md +++ b/docs/features/workspace/knowledge.md @@ -3,174 +3,149 @@ sidebar_position: 4 title: "Knowledge" --- -Knowledge part of Open WebUI is like a memory bank that makes your interactions even more powerful and context-aware. Let's break down what "Knowledge" really means in Open WebUI, how it works, and why it's incredibly helpful for enhancing your experience. +# 📚 Knowledge -## TL;DR +**Give your AI access to your documents and let it find what matters.** -- **Knowledge** is a section in Open WebUI where you can store structured information that the system can refer to during your interactions. -- It's like a memory system for Open WebUI that allows it to pull from saved data, making responses more personalized and contextually aware. -- You can use Knowledge directly in your chats with Open WebUI to access the stored data whenever you need it. +Knowledge is where you store the files and collections that your AI can search, read, and reason over. Upload PDFs, spreadsheets, code, or any text-based document. Build collections around projects, teams, or topics. When a model needs an answer, it pulls from your knowledge base instead of guessing. -Setting up Knowledge is straightforward! Simply navigate to **Workspace → Knowledge** in the sidebar and start adding details or data. You don't need coding expertise or technical setup; it's built into the core system! +Unlike [Notes](/features/notes), which inject full content into every message, Knowledge uses retrieval (RAG) to find the relevant chunks on demand. This makes it the right choice for large document sets where injecting everything would exceed the context window. -## What is the "Knowledge" Section? +--- -The **Knowledge section** is a storage area within Open WebUI where you can save specific pieces of information or data points. Think of it as a **reference library** that Open WebUI can use to make its responses more accurate and relevant to your needs. +## Why Knowledge? -### Why is Knowledge Useful? +### Your documents become searchable by AI -Imagine you're working on a long-term project and want the system to remember certain parameters, settings, or even key notes about the project without having to remind it every time. Or perhaps, you want it to remember specific personal preferences for chats and responses. The Knowledge section is where you can store this kind of **persistent information** so that Open WebUI can reference it in future conversations, creating a more **coherent, personalized experience**. +Upload a folder of contracts, technical specs, or research papers. The AI searches them by meaning, not just keywords, and cites where it found the answer. -Some examples of what you might store in Knowledge: +### Two retrieval modes for different needs -- Important project parameters or specific data points you'll frequently reference. -- Custom commands, workflows, or settings you want to apply. -- Personal preferences, guidelines, or rules that Open WebUI can follow in every chat. +Choose **Focused Retrieval** (RAG) to let the AI search large collections efficiently, or **Full Context** to inject an entire document word-for-word when precision matters. -### How to Use Knowledge in Chats +### Autonomous exploration with native function calling -Accessing stored Knowledge in your chats is easy! By simply referencing what's saved (using '#' before the name), Open WebUI can pull in data or follow specific guidelines that you've set up in the Knowledge section. +With [native function calling](/features/extensibility/plugin/tools#tool-calling-modes-default-vs-native) enabled, models don't just search. They browse your knowledge bases, read files page by page, and synthesize across multiple documents without manual prompting. -For example: +### Scoped access keeps things organized -- When discussing a project, Open WebUI can automatically recall your specified project details. -- It can apply custom preferences to responses, like formality levels or preferred phrasing. +Attach specific knowledge bases to a model so it only searches what's relevant. Or leave it unscoped and let the model discover everything the user has access to. -To reference Knowledge in your chats, just ensure it's saved in the Knowledge section, and Open WebUI will know when and where to bring in the relevant information! +--- -Admins can add knowledge to the workspace, which users can access and use; however, users do not have direct access to the workspace itself. +## Key Features -### Native Mode (Agentic Mode) Knowledge Tools +| | | +| :--- | :--- | +| 📄 **9 vector databases** | ChromaDB, PGVector, Qdrant, Milvus, OpenSearch, Elasticsearch, and more | +| 🔍 **Hybrid search** | BM25 keyword search + vector search with cross-encoder reranking | +| 📑 **5 extraction engines** | Tika, Docling, Azure, Mistral OCR, custom loaders | +| 🤖 **Agentic retrieval** | Models browse, search, and read your documents autonomously | +| 📄 **Full context mode** | Inject entire documents with no chunking | +| 📦 **Export and API** | Back up knowledge bases as zip files, manage via REST API | -When using **Native Function Calling (Agentic Mode)**, quality models can interact with your Knowledge Bases autonomously using built-in tools: +--- -:::tip Quality Models for Knowledge Exploration -Autonomous knowledge base exploration works best with frontier models (GPT-5, Claude 4.5+, Gemini 3+) that can intelligently search, browse, and synthesize information from multiple documents. Small local models may struggle with multi-step knowledge retrieval. +## Retrieval Modes + +When attaching files or knowledge bases to a model, click on the attached item to toggle between modes: + +### 🔍 Focused Retrieval (default) + +Uses RAG to find and inject the most relevant chunks based on the user's query. When hybrid search is enabled (`ENABLE_RAG_HYBRID_SEARCH`), retrieval combines BM25 keyword search with vector search, plus reranking for accuracy. + +Best for large document sets where only specific sections are relevant. + +### 📄 Full Context + +Injects the complete content of the file into every message. No chunking, no semantic search. Always injected regardless of native function calling settings, so the model doesn't need to call any tools to access it. + +Best for short reference documents, style guides, or context that's always relevant. + +--- + +## Agentic Knowledge Tools + +With [native function calling](/features/extensibility/plugin/tools#tool-calling-modes-default-vs-native) enabled, models interact with your knowledge bases using built-in tools. Which tools appear depends on whether specific knowledge is attached to the model: + +| Tool | Attached KB | No KB attached | Description | +|------|:-----------:|:--------------:|-------------| +| `list_knowledge` | ✅ | ❌ | List all KBs, files, and notes attached to the model | +| `list_knowledge_bases` | ❌ | ✅ | Browse available knowledge bases with file counts | +| `search_knowledge_bases` | ❌ | ✅ | Find knowledge bases by name or description | +| `query_knowledge_bases` | ❌ | ✅ | Search KB names/descriptions by semantic similarity | +| `search_knowledge_files` | ✅ (scoped) | ✅ (all) | Search files by filename | +| `query_knowledge_files` | ✅ (scoped) | ✅ | Search file contents using the RAG pipeline | +| `view_file` | ✅ | ❌ | Read file content with pagination (default 10K chars, cap 100K) | +| `view_knowledge_file` | ✅ | ✅ | Read file content from any accessible KB | +| `view_note` | ✅ | ❌ | Read attached notes | + +The key split: `list_knowledge` and `list_knowledge_bases` are mutually exclusive. Attaching a KB scopes the model to only those documents. Leaving it unscoped lets the model discover everything the user has access to. + +Autonomous exploration works best with frontier models that can intelligently chain search, browse, and synthesize. Smaller models may struggle with multi-step retrieval. Administrators can disable the **Knowledge Base** tool category per-model in **Workspace > Models > Edit > Builtin Tools**. + +For the full list of built-in agentic tools, see the [Native/Agentic Mode Tools Guide](/features/extensibility/plugin/tools#built-in-system-tools-nativeagentic-mode). + +:::warning Knowledge is NOT auto-injected with native function calling + +When native function calling is enabled, attached knowledge is **not automatically injected**. The model must call the knowledge tools to search and retrieve. If your model isn't using attached knowledge: + +1. **Add system prompt instructions** telling the model to use `list_knowledge` and `query_knowledge_files`. +2. **Disable native function calling** for that model to restore automatic RAG injection. +3. **Switch to Full Context mode** for the attachment to bypass RAG entirely. ::: -- **`list_knowledge`**: List all knowledge bases, files, and notes attached to the current model with file details. **Use this first** to discover what knowledge is available. Only available when the model has attached knowledge. -- **`query_knowledge_files`**: Search file contents using retrieval over the configured RAG pipeline (including hybrid search/reranking when `ENABLE_RAG_HYBRID_SEARCH` is enabled). When a KB is attached to the model, searches are automatically scoped. This should be the model's first choice for finding information before searching the web. -- **`search_knowledge_files`**: Search files by filename. Available in both modes; auto-scopes to attached KBs when the model has attached knowledge. -- **`list_knowledge_bases`**: Browse available knowledge bases with file counts. Only available when the model has **no** attached knowledge. -- **`search_knowledge_bases`**: Find specific knowledge bases by name or description. Only available when the model has **no** attached knowledge. -- **`query_knowledge_bases`**: Search KB names/descriptions by semantic similarity. Only available when the model has **no** attached knowledge. -- **`view_file`** / **`view_knowledge_file`**: Read file content with pagination support (`offset` and `max_chars` parameters for large files, default 10K chars, hard cap 100K). +--- -These tools enable models to autonomously explore and retrieve information from your knowledge bases, making conversations more contextually aware and grounded in your stored documents. +## Setting Up a Knowledge Base -#### Knowledge Scoping with Native Function Calling +1. Click **Workspace** in the sidebar, then select **Knowledge**. +2. Click **+ New Knowledge** and give it a name and description. +3. Upload files or add existing documents. +4. Attach the knowledge base to a model in **Workspace > Models > Edit**, or reference it in chat with `#`. -When native function calling is enabled, the model's access to knowledge bases depends on whether you've attached specific knowledge to the model: +### Exporting -| Model Configuration | Knowledge Access | -|-------------------|------------------| -| **No KB attached** | Model can access **all** knowledge bases the user has access to (public KBs, user's own KBs) | -| **KB attached to model** | Model is **limited** to only the attached knowledge base(s) | +Admins can export an entire knowledge base as a zip file via the item menu (three dots) > **Export**. Files are converted to `.txt` for universal compatibility. Regular users will not see the Export option. -Knowledge tool availability at a glance: +### API access -| Tool | Model has attached knowledge | Model has no attached knowledge | -|------|------------------------------|---------------------------------| -| `list_knowledge` | ✅ | ❌ | -| `list_knowledge_bases` | ❌ | ✅ | -| `search_knowledge_bases` | ❌ | ✅ | -| `query_knowledge_bases` | ❌ | ✅ | -| `search_knowledge_files` | ✅ (auto-scoped) | ✅ (all accessible KBs) | -| `query_knowledge_files` | ✅ (auto-scoped) | ✅ | -| `view_file` | ✅ (when attached items include files/collections) | ❌ | -| `view_knowledge_file` | ✅ (when attached items include files/collections) | ✅ | -| `view_note` | ✅ (when attached items include notes) | ❌ | +Knowledge bases can be managed programmatically: -Quick rule: `list_knowledge` and `list_knowledge_bases` are mutually exclusive. - -:::warning Knowledge is NOT Auto-Injected with Native Function Calling - -**Important behavioral difference:** When using Native Function Calling, attached knowledge is **not automatically injected** into the conversation. Instead, the model must actively call the knowledge tools to search and retrieve information. - -**If your model isn't using attached knowledge:** - -1. **Add instructions to your system prompt** telling the model to discover and query knowledge bases. For example: - > "When users ask questions, first use list_knowledge to see what knowledge is available, then use query_knowledge_files to search the relevant knowledge base before answering. If no knowledge is attached to this model, use list_knowledge_bases first to discover available KBs." - -2. **Or disable Native Function Calling** for that model to restore the automatic RAG injection behavior from earlier versions. - -3. **Or use "Full Context" mode** for the attached knowledge (click on the attachment and select "Use Entire Document") which bypasses RAG and always injects the full content. - -::: - -:::tip Restricting Knowledge Access -If you want a model to focus on specific documents, attach those knowledge bases to the model in **Workspace > Models > Edit**. This prevents the model from searching other available knowledge bases. -::: - -### Full Context vs Focused Retrieval - -When attaching files, notes, or knowledge bases to a model, you can choose between two retrieval modes by clicking on the attached item: - -#### 🔍 Focused Retrieval (Default) - -- Uses **RAG (Retrieval Augmented Generation)** to find relevant chunks -- Only injects the most relevant portions of documents based on the user's query -- When **hybrid search** is enabled (`ENABLE_RAG_HYBRID_SEARCH`), retrieval uses BM25 keyword search combined with vector search, plus reranking for improved accuracy — this applies to both the standard RAG pipeline and native knowledge tool retrieval paths -- Best for large documents or knowledge bases where only specific sections are relevant -- With native function calling enabled, the model decides when to search - -#### 📄 Using Entire Document (Full Context) - -- Injects the **complete content** of the file/note into every message -- Bypasses RAG entirely—no chunking or semantic search -- Best for short reference documents, style guides, or context that's always relevant -- **Always injected** regardless of native function calling settings - -:::info Full Context with Native Function Calling -When "Using Entire Document" is enabled for a file or knowledge base, its content is **always injected** into the conversation, even when native function calling is enabled. The model does not need to call any tools to access this content—it's automatically included in the context. - -Files set to Focused Retrieval (the default) will only be accessed when the model calls the appropriate knowledge tools. -::: - -:::note Per-Model Control -The Knowledge Base tools require the **Knowledge Base** category to be enabled for the model in **Workspace > Models > Edit > Builtin Tools** (enabled by default). Administrators can disable this category per-model to prevent autonomous knowledge base access. -::: - -:::info Central Tool Documentation -For complete details on all built-in agentic tools and how to configure them, see the [**Native/Agentic Mode Tools Guide**](/features/extensibility/plugin/tools#built-in-system-tools-nativeagentic-mode). -::: - -### Setting Up Your Knowledge Base - -1. **Navigate to the Knowledge Section**: Click **Workspace** in the sidebar, then select **Knowledge**. This area is designed to be user-friendly and intuitive. -2. **Add Entries**: Input information you want Open WebUI to remember. It can be as specific or broad as you like. -3. **Save and Apply**: Once saved, the Knowledge is accessible and ready to enhance your chat interactions. - -### Exporting a Knowledge Base - -Admins can export an entire knowledge base as a downloadable zip file. This is useful for backing up your knowledge, migrating data between instances, or sharing curated knowledge collections with others. - -To export a knowledge base, open the item menu (three dots) on any knowledge base entry and select **Export**. The system will generate a zip archive containing all files from that knowledge base, converted to `.txt` format for universal compatibility. The zip file will be named after the knowledge base itself. - -:::note Admin Only -The export feature is restricted to admin users. Regular users will not see the Export option in the menu. -::: - -### Programmatic Access via API - -Knowledge bases can also be managed programmatically through the Open WebUI API. This is useful for automated workflows, bulk imports, or integrating with external systems. - -Key API endpoints: - `POST /api/v1/files/` - Upload files -- `GET /api/v1/files/{id}/process/status` - Check file processing status +- `GET /api/v1/files/{id}/process/status` - Check processing status - `POST /api/v1/knowledge/{id}/file/add` - Add files to a knowledge base -:::warning Important: Async File Processing -When uploading files via API, processing happens asynchronously. You **must** wait for file processing to complete before adding files to a knowledge base, or you will receive an "empty content" error. +File processing happens asynchronously. You must poll the status endpoint until processing completes before adding files to a knowledge base, or you'll get an "empty content" error. See [API Endpoints](/reference/api-endpoints#-retrieval-augmented-generation-rag) for workflow examples. -For detailed examples and proper workflow handling, see the [API Endpoints documentation](/reference/api-endpoints#-retrieval-augmented-generation-rag). -::: +--- -## Summary +## Use Cases -- The Knowledge section is like Open WebUI's "memory bank," where you can store data that you want it to remember and use. -- **Use Knowledge to keep the system aware** of important details, ensuring a personalized chat experience. -- You can **directly reference Knowledge in chats** to bring in stored data whenever you need it using '#' + name of the knowlege. -- **Admins can export knowledge bases** as zip files for backup, migration, or sharing purposes. +### Project documentation -🌟 Remember, there's always more to discover, so dive in and make Open WebUI truly your own! +Upload your team's technical specs, architecture docs, and runbooks into a knowledge base. Attach it to a "Project Assistant" model. The AI answers questions grounded in your actual documentation instead of generic training data. + +### Legal and compliance review + +Load contracts, policies, and regulatory documents. Ask the AI to find specific clauses, compare terms across agreements, or flag inconsistencies. + +### Research synthesis + +Add dozens of papers to a knowledge base. The AI searches across all of them to answer questions, find supporting evidence, or identify contradictions between studies. + +--- + +## Limitations + +### Context window with Full Context mode + +"Using Entire Document" injects the full text. A large document attached to a model with a small context window will crowd out conversation history. + +### Processing delay for API uploads + +Files uploaded via API are processed asynchronously. Attempting to use a file before processing completes will fail silently or return empty results. + +### Native function calling changes behavior + +Enabling native function calling changes how knowledge bases work. If your KB suddenly stops producing results, check whether `function_calling: native` was set in global model defaults. See [Knowledge Base troubleshooting](/troubleshooting/rag#13-knowledge-base-attached-to-model-not-working) for details. diff --git a/docs/features/workspace/models.md b/docs/features/workspace/models.md index 48186614..00bcdc82 100644 --- a/docs/features/workspace/models.md +++ b/docs/features/workspace/models.md @@ -4,192 +4,192 @@ title: "Models" sidebar_label: "Models" --- -The `Models` section of the `Workspace` within Open WebUI is a powerful tool that allows you to create and manage custom models tailored to specific purposes. +# 🤖 Models -While backends like Ollama have their own `Modelfile` format, Open WebUI employs a robust internal **Preset System**. This allows you to "wrap" any model (including GPT-4, Claude, or local Llama 3) to bind specific **System Prompts**, **Knowledge Collections**, **Tools**, and **Dynamic Variables** to it. +**Wrap any model with custom instructions, tools, and knowledge to build specialized agents.** -This section serves as a central hub for all your models, providing a range of features to edit, clone, share, export, and hide your custom agents. +The Models workspace lets you create configuration presets that sit on top of any base model. Pick GPT-4o, Claude, Llama 3, or anything else connected to Open WebUI, then bind a system prompt, knowledge bases, tools, skills, and parameter overrides to it. The result is a purpose-built agent that behaves exactly the way you need without modifying the underlying model. -## Creating and Editing Models +A "Python Tutor" that always uses your style guide. A "Meeting Summarizer" with your company's template. A "Code Reviewer" with your linting rules baked in. Every agent is a thin wrapper: pick a base model, configure it, and share it with your team. -When you create a new model or edit an existing one, you are building a configuration wrapper around a "Base Model". -To access the model configuration interface, you have two primary entry points from the main Models list: +--- -1. **New Model**: Click the **+ New Model** button in the top-right corner. This opens a blank configuration page to create a preset from scratch. -2. **Edit Model**: Click the ellipsis (**...**) on an existing model card and select **Edit**. This opens the configuration page pre-filled with that model's current settings. +## Why Models? -Both actions lead to the same Model Builder interface, where you can configure the settings below. +### One base model, many personas -### Core Configuration +The same GPT-4o can power a coding assistant, a customer support bot, and a creative writer. Each preset has its own system prompt, tools, and knowledge, so the model behaves differently depending on which preset is selected. -- **Avatar Photo**: Upload a custom image to represent your model in the chat interface. **Animated formats** (GIF and WebP) are supported and their animations will be preserved during the upload process. -- **Model Name & ID**: The display name and unique identifier for your custom preset (e.g., "Python Tutor" or "Meeting Summarizer"). -- **Base Model**: The actual model beneath the hood that powers the agent. You can choose *any* model connected to Open WebUI. You can create a custom preset for `gpt-4o` just as easily as `llama3`. - - **Fallback Behavior**: If the configured Base Model is unavailable and the `ENABLE_CUSTOM_MODEL_FALLBACK` environment variable is set to `True`, the system will automatically fall back to the first configured default model (set in Admin Panel > Settings > Models > Default Models). This ensures mission-critical custom models remain functional even if their specific base model is removed or temporarily unavailable. -- **Description**: A short summary of what the model does. -- **Tags**: Add tags to organize models in the selector dropdown. -- **Visibility & Groups**: - - **Private**: Restricts access to specific users or groups. - - **Access Control Selector**: Use the access control panel to grant access to specific groups (e.g., "Admins", "Developers") or individual users without making the model public to everyone. The redesigned interface makes it easy to add multiple groups and users at once. +### Knowledge and tools come pre-attached -### System Prompt & Dynamic Variables +Instead of manually attaching documents and enabling tools every chat, bind them once to the model preset. Users get a fully configured agent out of the box. -The **System Prompt** defines the behavior and persona of the model. Unlike standard prompts, Open WebUI supports **Dynamic Variable Injection** using Jinja2-style placeholders. This allows the model to be aware of time, date, and user details. +### Granular access control -| Variable | Description | Output Example | -| :--- | :--- | :--- | -| `{{ CURRENT_DATE }}` | Injects today's date (YYYY-MM-DD). | `2024-10-27` | -| `{{ CURRENT_TIME }}` | Injects the current time (24hr). | `14:30:05` | -| `{{ USER_NAME }}` | The display name of the logged-in user. | `Admin` | +Restrict models to specific users or groups. A finance team sees their models; engineering sees theirs. Admins control what's available instance-wide. -**Example System Prompt:** +### Dynamic system prompts + +Use Jinja2-style variables like `{{ USER_NAME }}` and `{{ CURRENT_DATE }}` so the system prompt adapts to each user and session automatically. + +--- + +## Key Features + +| | | +| :--- | :--- | +| 🧩 **Model presets** | System prompt, tools, knowledge, skills, and parameters in one package | +| 🏷️ **Dynamic variables** | `{{ USER_NAME }}`, `{{ CURRENT_DATE }}`, `{{ CURRENT_TIME }}` injected automatically | +| 🔧 **Bound tools** | Force-enable specific tools per model | +| 📚 **Attached knowledge** | Knowledge bases and files always available via RAG or full context | +| 🎭 **Skills** | Bind markdown instruction sets loaded on-demand via `view_skill` | +| 👥 **Access control** | Restrict to specific users or groups | +| 📊 **Global defaults** | Set baseline capabilities and parameters for all models at once | +| 🔊 **Per-model TTS voice** | Give each persona its own voice | + +--- + +## Creating a Model + +Click **+ New Model** in **Workspace > Models**, or click the ellipsis (**...**) on an existing model and select **Edit**. + +### Core configuration + +| Field | Description | +| :--- | :--- | +| **Avatar** | Upload a custom image. Animated GIF and WebP are supported | +| **Name and ID** | Display name and unique identifier | +| **Base Model** | The actual model that powers this agent | +| **Description** | Short summary shown in the model selector | +| **Tags** | Organize models in the dropdown | +| **Visibility** | Private (specific users/groups) or public | + +### System prompt and variables + +The system prompt defines the behavior and persona. Use dynamic variables for context-aware instructions: + +| Variable | Output example | +| :--- | :--- | +| `{{ CURRENT_DATE }}` | `2024-10-27` | +| `{{ CURRENT_TIME }}` | `14:30:05` | +| `{{ USER_NAME }}` | `Admin` | ``` You are a helpful assistant for {{ USER_NAME }}. The current date is {{ CURRENT_DATE }}. ``` -### Advanced Parameters +### Capabilities and bindings -Clicking **Show** on **Advanced Params** allows you to fine-tune the inference generation. +Toggle what the model can do and bind resources: -- **Stop Sequences**: A powerful feature that tells the model to force-stop generating text when it hits specific characters. This is vital for roleplay or coding models to prevent them from hallucinating both sides of a conversation. - - *Format:* Enter the string (e.g., `<|end_of_text|>`, `User:`) and press `Enter`. -- **Temperature, Top P, etc.**: Adjust the creativity and determinism of the model. +| Setting | What it controls | +| :--- | :--- | +| **Knowledge** | Bind collections or files. Click attached items to toggle between Focused Retrieval and Full Context. See [Retrieval Modes](/features/workspace/knowledge#retrieval-modes) | +| **Tools** | Force-enable specific tools (e.g., Calculator for a Math Bot) | +| **Skills** | Bind [Skills](/features/workspace/skills) so their manifests are always injected | +| **Filters** | Attach pipeline filters (e.g., PII redaction) | +| **Actions** | Attach action scripts (e.g., "Add to Memories") | +| **Vision** | Enable image analysis (requires a vision-capable base model) | +| **Web Search** | Enable the configured search provider | +| **Code Interpreter** | Enable Python code execution | +| **Image Generation** | Enable image generation | +| **Builtin Tools** | Control which tool categories are available: Time, Memory, Chats, Notes, Knowledge, Channels | +| **File Context** | When enabled, attached files are processed via RAG. When disabled, no file content is extracted | +| **TTS Voice** | Set a specific voice for this model's responses | -### Prompt Suggestions +### Advanced parameters -**Prompt Suggestions** are clickable "starter chips" that appear above the input bar when a user opens a fresh chat with this model. These are vital for onboarding users to specialized agents. +- **Stop Sequences**: Force-stop generation on specific strings (e.g., `<|end_of_text|>`, `User:`). Press Enter after each. +- **Temperature, Top P, etc.**: Adjust creativity and determinism. -- **Purpose**: To guide the user on what the model is capable of or to provide one-click shortcuts for common tasks. -- **How to add**: Type a phrase (e.g., "Summarize this text") and click the **+** button. You can add multiple suggestions. -- **Example**: For a "Python Tutor" model, you might add: - - *"Explain this code step-by-step"* - - *"Find bugs in the following script"* - - *"Write a Unit Test for this function"* +### Prompt suggestions -### Capabilities, Binding & Defaults +Clickable starter chips that appear when a user opens a fresh chat with this model. Add phrases like "Explain this code step-by-step" or "Summarize this document" to guide users. -You can transform a generic model into a specialized agent by toggling specific capabilities and binding resources. - -- **Knowledge**: Instead of manually selecting documents for every chat, you can bind a specific knowledgebase **Collection** or **File** to this model. Whenever this model is selected, RAG (Retrieval Augmented Generation) is automatically active for those specific files. Click on attached items to toggle between **Focused Retrieval** (RAG chunks) and **Using Entire Document** (full content injection). See [Full Context vs Focused Retrieval](/features/workspace/knowledge#full-context-vs-focused-retrieval) for details. -- **Tools**: Force specific tools to be enabled by default (e.g., always enable the **Calculator** tool for a "Math Bot"). -- **Skills**: Bind [Skills](/features/workspace/skills) to this model so their manifests are always injected. The model can load full skill instructions on-demand via the `view_skill` builtin tool. -- **Filters**: Attach specific Pipelines/Filters (e.g., a Profanity Filter or PII Redaction script) to run exclusively on this model. -- **Actions**: Attach actionable scripts like `Add to Memories` or `Button` triggers. -- **Capabilities**: Granularly control what the model is allowed to do: - - **Vision**: Toggle to enable image analysis capabilities (requires a vision-capable Base Model). - - **Web Search**: Enable the model to access the configured search provider (e.g., Google, SearxNG) for real-time information. - - **File Upload**: Allow users to upload files to this model. - - **File Context**: When enabled (default), attached files are processed via RAG and their content is injected into the conversation. When disabled, file content is **not** extracted or injected—the model receives no file content unless it retrieves it via builtin tools. Only visible when File Upload is enabled. See [File Context vs Builtin Tools](/features/chat-conversations/rag#file-context-vs-builtin-tools) for details. - - **Code Interpreter**: Enable Python code execution. See [Python Code Execution](/features/chat-conversations/chat-features/code-execution/python) for details. - - **Image Generation**: Enable image generation integration. - - **Usage / Citations**: Toggle usage tracking or source citations. - - **Status Updates**: Show visible progress steps in the chat UI (e.g., "Searching web...", "Reading file...") during generation. Useful for slower, complex tasks. - - **Builtin Tools**: When enabled (default), automatically injects system tools (timestamps, memory, chat history, knowledge base queries, notes, etc.) in [Native Function Calling mode](/features/extensibility/plugin/tools#disabling-builtin-tools-per-model). When enabled, you can further control which **tool categories** are available (Time, Memory, Chats, Notes, Knowledge, Channels) via checkboxes in the Model Editor. Disable the main toggle if the model doesn't support function calling or you need to save context window tokens. Note: This is separate from **File Context**—see [File Context vs Builtin Tools](/features/chat-conversations/rag#file-context-vs-builtin-tools) for the difference. -- **TTS Voice**: Set a specific Text-to-Speech voice for this model. When users read responses aloud, this voice will be used instead of the global default. Useful for giving different personas distinct voices. Leave empty to use the user's settings or system default. See [Per-Model TTS Voice](/features/media-generation/audio/text-to-speech/openai-tts-integration#per-model-tts-voice) for details. -- **Default Features**: Force specific toggles (like Web Search) to be "On" immediately when a user starts a chat with this model. +--- ## Model Management -From the main list view in the `Models` section, click the ellipsis (`...`) next to any model to perform actions: +From the model list, click the ellipsis (**...**) on any model: -- **Edit**: Open the configuration panel for this model. -- **Hide**: Hide the model from the model selector dropdown within chats (useful for deprecated models) without deleting it. -- **Clone**: Create a copy of a model configuration, which will be appended with `-clone`. +| Action | Description | +| :--- | :--- | +| **Edit** | Open the configuration panel | +| **Hide** | Remove from the model selector without deleting | +| **Clone** | Create a copy (appends `-clone`) | +| **Copy Link** | Copy a direct URL to the model settings | +| **Export** | Download the configuration as `.json` | +| **Share** | Share to the Open WebUI community | +| **Delete** | Permanently remove the preset | -:::note -A raw Base Model can be cloned as a custom Workspace model, but it will not clone the raw Base Model itself. +### Import and export + +- **Import**: From `.json` files or Open WebUI community links +- **Export**: Download all custom model configurations as a single `.json` +- **Discover**: Browse community presets at the bottom of the page + +:::info Downloading base models +To download new base models, go to **Settings > Connections > Ollama** or type `ollama run hf.co/{username}/{repository}:{quantization}` in the model selector. ::: -- **Copy Link**: Copies a direct URL to the model settings. -- **Export**: Download the model configuration as a `.json` file. -- **Share**: Share your model configuration with the Open WebUI community by clicking the `Share` button (redirects to [openwebui.com](https://openwebui.com/models/create)). -- **Delete**: Permanently remove the preset. +--- -### Import and Export +## Global Model Defaults (Admin) -- **Import Models**: Import models from a `.json` file or from Open WebUI community links. -- **Export Models**: Export all your custom model configurations into a single `.json` file for backup or migration. -- **Discover a Model**: At the bottom of the page, you can explore and download presets made by the Open WebUI community. +Administrators can set baseline capabilities and parameters that apply to all models via **Admin Panel > Settings > Models > ⚙️ (gear icon)**. -:::info Downloading Raw Models -To download new raw Base Models (like `Llama-3.2-3B-Instruct-GGUF:Q8_0` or `Mistral-7B-Instruct-v0.2-GGUF:Q4_K_M`), navigate to **Settings > Connections > Ollama**. Alternatively, type `ollama run hf.co/{username}/{repository}:{quantization}` in the model selector to pull directly from Hugging Face. This action will create a button within the model selector labeled "Pull [Model Name]" that will begin downloading the model from its source once clicked. -::: +- **Default Model Metadata** (`DEFAULT_MODEL_METADATA`): Baseline capabilities (vision, web search, file context, code interpreter, builtin tools). Per-model overrides always win on conflicts. +- **Default Model Params** (`DEFAULT_MODEL_PARAMS`): Baseline inference parameters (temperature, top_p, max_tokens, function_calling). Per-model values take precedence when explicitly set. -## Global Model Management (Admin) +### Merge behavior -Administrators have access to a centralized management interface via **Admin Panel > Settings > Models**. This page provides powerful tools for decluttering and organizing the model list, especially when connected to providers with hundreds of available models. - -### View Filtering - -The **Admin View Selector** allows you to filter the entire list of models by their operational status. This is located next to the search bar and includes the following views: - -- **All**: Shows every model available to the system. -- **Enabled**: Displays only models that are currently active and selectable by users. -- **Disabled**: Shows models that have been deactivated. -- **Visible**: Shows models that are currently visible in the user model selector. -- **Hidden**: Displays only the models that have been hidden (these appear with reduced opacity in the list). - -### Bulk Actions - -To streamline the management of large model collections, the Admin Panel includes **Bulk Actions** that apply to the models currently visible in your filtered view. - -1. **Filter your view** (e.g., select "Disabled" or "Hidden"). -2. **Open the Actions menu** (Ellipsis icon next to the search bar). -3. **Select an action**: - - **Enable All**: Activates all models in the current filtered list simultaneously. - - **Disable All**: Deactivates all models in the current filtered list. - -These tools are specifically designed to help administrators quickly manage external providers (like OpenAI or Anthropic) that expose a high volume of models, allowing for instant site-wide configuration changes. - -### Global Model Defaults - -Administrators can set **global default metadata and parameters** that apply as a baseline to all models. This eliminates the need to manually configure capabilities and inference settings for every model individually. - -- **Default Model Metadata** (`DEFAULT_MODEL_METADATA`): Sets baseline capabilities (vision, web search, file context, code interpreter, builtin tools, etc.) and other model metadata for all models. For capabilities, defaults and per-model values are merged — per-model overrides always win on conflicts. For other metadata fields, the global default is only applied when a model has no value set. -- **Default Model Params** (`DEFAULT_MODEL_PARAMS`): Sets baseline inference parameters (temperature, top_p, max_tokens, seed, function_calling, etc.) for all models. Per-model parameter overrides always take precedence — but only when a per-model value is explicitly set. - -These settings are accessible via **Admin Settings → Models → ⚙️ (gear icon)** and are persisted via `PersistentConfig`. See [`DEFAULT_MODEL_METADATA`](/reference/env-configuration#default_model_metadata) and [`DEFAULT_MODEL_PARAMS`](/reference/env-configuration#default_model_params) for details. - -#### Merge Behavior - -Understanding how defaults combine with per-model settings is important: - -| Setting Type | Merge Strategy | Example | +| Setting type | Strategy | Example | |---|---|---| -| **Capabilities** (metadata) | Deep merge: `{...global, ...per_model}` | Global sets `file_context: false`, model sets `vision: true` → model gets both | -| **Other metadata** (description, tags, etc.) | Fill-only: global applied when model value is `None` | Global sets `description: "Default"`, model has no description → model gets "Default" | -| **Parameters** | Simple merge: `{...global, ...per_model}` | Global sets `temperature: 0.7`, model sets `temperature: 0.3` → model gets `0.3` | +| **Capabilities** | Deep merge | Global sets `file_context: false`, model sets `vision: true` > model gets both | +| **Other metadata** | Fill-only | Global sets description, model has none > model gets the global value | +| **Parameters** | Simple merge | Global sets `temperature: 0.7`, model sets `0.3` > model gets `0.3` | -The key subtlety: **if a model doesn't explicitly set a parameter, the global default is the only value**. This is especially important for `function_calling` — see the warning below. +:::warning Knowledge base + function calling interaction +Setting `function_calling: native` in global params changes how **all** models handle attached knowledge bases. In native mode, model-attached KBs are not auto-injected. The model must call builtin tools to retrieve knowledge. If your knowledge bases suddenly stop working, check global defaults first. -:::warning Knowledge Base + Function Calling Interaction -Setting `function_calling: native` in Global Model Params changes how **all** models handle attached Knowledge Bases. In native mode, model-attached KBs are **not** auto-injected via RAG — instead, the model must autonomously call builtin tools to retrieve knowledge. If a model doesn't explicitly override `function_calling` in its own Advanced Params, it inherits the global value silently. - -Additionally, if `file_context` is disabled in Global Model Capabilities, the RAG retrieval handler is skipped for all models that don't explicitly enable it — meaning attached files and KBs produce no results. - -If your models' attached Knowledge Bases are not working, check global defaults first. See [Knowledge Base Attached to Model Not Working](/troubleshooting/rag#13-knowledge-base-attached-to-model-not-working) for detailed troubleshooting steps. +See [Knowledge Base troubleshooting](/troubleshooting/rag#13-knowledge-base-attached-to-model-not-working). ::: -:::tip -Global defaults are ideal for enforcing organizational policies — for example, disabling code interpreter by default across all models, or setting a consistent temperature for all models. However, be cautious with `function_calling` and capability toggles, as they can have unexpected effects on Knowledge Base behavior. -::: +### Bulk management + +Filter the admin model list by status (Enabled, Disabled, Visible, Hidden) and use **Bulk Actions** to enable or disable all models in the current view at once. Useful when external providers expose hundreds of models. + +--- ## Model Switching in Chat -Open WebUI allows for dynamic model switching and parallel inference within a chat session. +Switch models mid-conversation without losing context. Select up to two models simultaneously to compare responses side-by-side, using the arrow buttons to navigate between them. -**Example**: Switching between **Mistral**, **LLaVA**, and **GPT-4** in a Multi-Stage Task. +--- -- **Scenario**: A multi-stage conversation involves different task types, such as starting with a simple FAQ, interpreting an image, and then generating a creative response. -- **Reason for Switching**: The user can leverage each model's specific strengths for each stage: - - **Mistral** for general questions to reduce computation time and costs. - - **LLaVA** for visual tasks to gain insights from image-based data. - - **GPT-4** for generating more sophisticated and nuanced language output. -- **Process**: The user switches between models, depending on the task type, to maximize efficiency and response quality. +## Use Cases -**How To:** +### Team-specific agents -1. **Select the Model**: Within the chat interface, select the desired models from the model switcher dropdown. You can select up to two models simultaneously, and both responses will be generated. You can then navigate between them by using the back and forth arrows. -2. **Context Preservation**: Open WebUI retains the conversation context across model switches, allowing smooth transitions. +Create a "Sales Assistant" with your CRM knowledge base, objection-handling prompts, and email drafting tools. Share it with the sales group. Engineering never sees it. + +### Onboarding new users + +Build models with descriptive prompt suggestions ("Ask me about our company policies", "Help me set up my development environment") so new team members know exactly what to ask. + +### Enforcing organizational standards + +Set global defaults to disable code interpreter across all models, enforce a consistent temperature, or require function calling. Individual models can override when needed. + +--- + +## Limitations + +### Preset, not fine-tune + +Model presets configure behavior through system prompts and tool bindings. They do not modify the underlying model weights. For deep behavioral changes, you need actual fine-tuning. + +### Fallback requires configuration + +If a base model becomes unavailable, the preset will fail unless `ENABLE_CUSTOM_MODEL_FALLBACK` is set to `True` and a default model is configured in Admin Panel > Settings > Models. diff --git a/docs/features/workspace/prompts.md b/docs/features/workspace/prompts.md index 2614fa3b..105868c1 100644 --- a/docs/features/workspace/prompts.md +++ b/docs/features/workspace/prompts.md @@ -3,147 +3,245 @@ sidebar_position: 3 title: "Prompts" --- -The `Prompts` section of the `Workspace` within Open WebUI enables users to create, manage, and share custom prompts. This feature streamlines interactions with AI models by allowing users to save frequently used prompts and easily access them through slash commands. +# 📝 Prompts -### Prompt Management +**Reusable slash commands that turn complex instructions into one-click forms.** -The Prompts interface provides several key features for managing your custom prompts: +Prompts let you save frequently used instructions as slash commands. Type `/summarize` in any chat and the full prompt fires instantly. Add custom input variables and users get a popup form with dropdowns, date pickers, and text fields before the prompt is sent. No one needs to remember the exact wording or structure. -* **Create**: Design new prompts with customizable names, tags, access levels, and content. -* **Share**: Share prompts with other users based on configured access permissions. -* **Access Control**: Set visibility and usage permissions for each prompt (refer to [Permissions](/features/access-security/rbac/permissions) for more details). -* **Enable/Disable**: Toggle prompts on or off without deleting them. Disabled prompts won't appear in slash command suggestions but remain in your workspace for future use. -* **Slash Commands**: Quickly access prompts using custom slash commands during chat sessions. -* **Versioning & History**: Track every change with a full version history, allowing you to compare and revert to previous versions. -* **Tags & Filtering**: Organize your prompts using tags and easily filter through your collection in the workspace. - -### Creating and Editing Prompts - -When creating or editing a prompt, you can configure the following settings: - -* **Name**: Give your prompt a descriptive name for easy identification. -* **Tags**: Categorize your prompts with tags to make them easier to find and filter in your workspace. -* **Access**: Set the access level to control who can view and use the prompt. -* **Command**: Define a slash command that will trigger the prompt (e.g., `/summarize`). Commands are triggered in the chat by typing `/` followed by the command name. -* **Prompt Content**: Write the actual prompt text that will be sent to the model. -* **Commit Message**: When saving changes, you can provide an optional commit message to describe what was updated in this version. - -### Prompt Variables - -Open WebUI supports two kinds of variables to make your prompts more dynamic and powerful: **System Variables** and **Custom Input Variables**. - -**System Variables** are automatically replaced with their corresponding value when the prompt is used. They are useful for inserting dynamic information like the current date or user details. - -* **Clipboard Content**: Use `{{CLIPBOARD}}` to insert content from your clipboard. -* **Date and Time**: - * `{{CURRENT_DATE}}`: Current date - * `{{CURRENT_DATETIME}}`: Current date and time - * `{{CURRENT_TIME}}`: Current time - * `{{CURRENT_TIMEZONE}}`: Current timezone - * `{{CURRENT_WEEKDAY}}`: Current day of the week -* **User Information**: - * `{{USER_NAME}}`: Current user's name - * `{{USER_EMAIL}}`: Current user's email address - * `{{USER_BIO}}`: Current user's bio. Configured in **Settings > Account > User Profile**. If not set, the variable remains unreplaced. - * `{{USER_GENDER}}`: Current user's gender. Configured in **Settings > Account > User Profile**. If not set, the variable remains unreplaced. - * `{{USER_BIRTH_DATE}}`: Current user's birth date. Configured in **Settings > Account > User Profile**. If not set, the variable remains unreplaced. - * `{{USER_AGE}}`: Current user's age, calculated from birth date. If birth date is not set, the variable remains unreplaced. - * `{{USER_LANGUAGE}}`: User's selected language - * `{{USER_LOCATION}}`: User's location (requires HTTPS and Settings > Interface toggle) - -**Custom Input Variables** transform your prompts into interactive templates. When you use a prompt containing these variables, a modal window will automatically appear, allowing you to fill in your values. This is extremely powerful for creating complex, reusable prompts that function like forms. See the guidelines below for a full explanation. - -By leveraging custom input variables, you can move beyond static text and build interactive tools directly within the chat interface. This feature is designed to be foolproof, enabling even non-technical users to execute complex, multi-step prompts with ease. Instead of manually editing a large block of text, users are presented with a clean, structured form. This not only streamlines the workflow but also reduces errors by guiding the user to provide exactly the right information in the right format. It unlocks a new level of interactive prompt design, making sophisticated AI usage accessible to everyone. - -### Variable Usage Guidelines - -* Enclose all variables with double curly braces: `{{variable}}` -* **All custom input variables are optional by default** - users can leave fields blank when filling out the form -* Use the `:required` flag to make specific variables mandatory when necessary -* The `{{USER_LOCATION}}` system variable requires: - * A secure HTTPS connection - * Enabling the feature in `Settings` > `Interface` -* The `{{CLIPBOARD}}` system variable requires clipboard access permission from your device. +Every change is tracked with full version history. Roll back to a previous version, compare changes, and share prompts across your team with access controls. --- -#### Advanced Variable Modifiers +## Why Prompts? -Certain system variables like `{{prompt}}` and `{{MESSAGES}}` support optional modifiers to control their length and which part of the content is included. This is particularly useful for managing context window limits. +### Stop retyping the same instructions -##### Prompt Modifiers +Save the prompt once, use it with `/command`. Bug report templates, meeting minutes, code reviews, content briefs: anything you type more than twice should be a prompt. + +### Turn prompts into interactive forms + +Add typed input variables (dropdowns, date pickers, number fields, checkboxes) and users get a clean form instead of editing raw text. Non-technical users can run complex prompts without understanding the syntax. + +### Version history with rollback + +Every change creates a new version. Compare versions side-by-side, restore a previous version to production, and track who changed what. + +### Controlled sharing + +Share prompts with specific users or groups. Public prompts appear in everyone's `/` suggestions. Private prompts stay in your own workspace. + +--- + +## Key Features + +| | | +| :--- | :--- | +| ⚡ **Slash commands** | Type `/command` to insert the full prompt | +| 📋 **Input variable forms** | Typed fields (text, dropdown, date, number, checkbox, and more) generate a popup form | +| 🕑 **Version history** | Full change tracking with commit messages, rollback, and production pinning | +| 🔄 **System variables** | `{{CURRENT_DATE}}`, `{{USER_NAME}}`, `{{CLIPBOARD}}` auto-replaced at runtime | +| 🔒 **Access control** | Share with specific users, groups, or make public | +| 🔀 **Enable/Disable toggle** | Deactivate prompts without deleting them | +| 🏷️ **Tags** | Organize and filter your prompt library | + +--- + +## Creating a Prompt + +Navigate to **Workspace > Prompts** and click **+ New Prompt**. + +| Field | Description | +| :--- | :--- | +| **Name** | Descriptive title for identification | +| **Tags** | Categorize for filtering | +| **Access** | Control who can view and use the prompt | +| **Command** | The slash command trigger (e.g., `/summarize`) | +| **Prompt Content** | The actual text sent to the model, with variables | +| **Commit Message** | Optional description of changes for version tracking | + +Use clear variable names (`{{your_name}}` not `{{var1}}`), add descriptive `placeholder` text, provide `default` values where sensible, and mark only truly essential fields as `:required`. Public prompts appear in every user's `/` suggestions, so be selective about what you make public. Use the enable/disable toggle to shelve prompts you're not actively using. + +--- + +## Variables + +### System variables + +Automatically replaced with their value at runtime: + +| Variable | Description | +| :--- | :--- | +| `{{CLIPBOARD}}` | Content from your clipboard (requires clipboard permission) | +| `{{CURRENT_DATE}}` | Current date | +| `{{CURRENT_DATETIME}}` | Current date and time | +| `{{CURRENT_TIME}}` | Current time | +| `{{CURRENT_TIMEZONE}}` | Current timezone | +| `{{CURRENT_WEEKDAY}}` | Current day of the week | +| `{{USER_NAME}}` | Your display name | +| `{{USER_EMAIL}}` | Your email address | +| `{{USER_BIO}}` | Bio from Settings > Account > User Profile (unreplaced if not set) | +| `{{USER_GENDER}}` | Gender from Settings > Account > User Profile (unreplaced if not set) | +| `{{USER_BIRTH_DATE}}` | Birth date from Settings > Account > User Profile (unreplaced if not set) | +| `{{USER_AGE}}` | Age calculated from birth date (unreplaced if not set) | +| `{{USER_LANGUAGE}}` | Your selected language | +| `{{USER_LOCATION}}` | Your location (requires HTTPS + Settings > Interface toggle) | + +### Custom input variables + +Add variables to your prompt content and users get a popup form when they use the slash command. + +**Simple input** creates a single-line text field: +``` +{{variable_name}} +``` + +**Typed input** creates a specific field type with configured properties: +``` +{{variable_name | type:property="value"}} +``` + +All custom variables are **optional by default**. Add `:required` to make a field mandatory: +``` +{{title | text:required}} +{{notes | textarea:placeholder="Additional context (optional)"}} +``` + +### Available input types + +| Type | Description | Example | +| :--- | :--- | :--- | +| **text** | Single-line text (default) | `{{name \| text:placeholder="Enter name":required}}` | +| **textarea** | Multi-line text | `{{description \| textarea:required}}` | +| **select** | Dropdown menu | `{{priority \| select:options=["High","Medium","Low"]:required}}` | +| **number** | Numeric input | `{{count \| number:min=1:max=100:default=5}}` | +| **checkbox** | Boolean toggle | `{{include_details \| checkbox:label="Include analysis"}}` | +| **date** | Date picker | `{{start_date \| date:required}}` | +| **datetime-local** | Date and time picker | `{{appointment \| datetime-local}}` | +| **color** | Color picker | `{{brand_color \| color:default="#FFFFFF"}}` | +| **email** | Email field with validation | `{{email \| email:required}}` | +| **range** | Slider | `{{rating \| range:min=1:max=10}}` | +| **tel** | Phone number | `{{phone \| tel}}` | +| **time** | Time picker | `{{meeting_time \| time}}` | +| **url** | URL with validation | `{{website \| url:required}}` | +| **month** | Month and year (Chrome/Edge only, falls back to text in Firefox/Safari) | `{{billing_month \| month}}` | +| **map** | Interactive map for coordinates (experimental) | `{{location \| map}}` | + +--- + +## Message and Prompt Modifiers + +These modifiers are especially useful for task model prompts (title generation, tag generation, follow-up suggestions) where conversations contain long messages like pasted documents or code. + +### Prompt truncation The `{{prompt}}` variable supports character-based truncation: -* **Start Truncation**: `{{prompt:start:N}}` - Includes only the first **N** characters of the content. -* **End Truncation**: `{{prompt:end:N}}` - Includes only the last **N** characters of the content. -* **Middle Truncation**: `{{prompt:middletruncate:N}}` - Includes a total of **N** characters, taking half from the beginning and half from the end, with `...` in the middle. +| Modifier | What it does | +| :--- | :--- | +| `{{prompt:start:N}}` | First N characters | +| `{{prompt:end:N}}` | Last N characters | +| `{{prompt:middletruncate:N}}` | First half + last half, N characters total | -##### Messages Variable: Two Types of Modifiers +### Message selectors vs pipe filters -The `{{MESSAGES}}` variable has **two distinct modifier types** that work at different levels: +The `{{MESSAGES}}` variable has two distinct modifier types that work at different levels: -| Modifier Type | Syntax | What It Controls | Example | -| :--- | :--- | :--- | :--- | -| **Message Selector** (colon `:`) | `{{MESSAGES:SELECTOR:N}}` | **How many messages** to include | `{{MESSAGES:END:5}}` = last 5 messages | -| **Pipe Filter** (pipe `\|`) | `\{\{MESSAGES\|filter:N\}\}` | **Character limit per message** | `\{\{MESSAGES\|middletruncate:500\}\}` = each message to 500 chars | +**Message selectors** (colon `:`) control **how many messages** to include: -:::warning Important Distinction - -**Message selectors control MESSAGE COUNT, not token count or character count.** - -- `{{MESSAGES:MIDDLETRUNCATE:500}}` selects **500 messages** (not 500 tokens/characters) -- If you have 600 messages, it keeps the first ~250 and last ~250 messages -- This does **not** truncate the content of each message - -To limit content length, use **pipe filters** instead. - -::: - -##### Message Selectors - -Message selectors control **how many messages** are included in the output: - -| Selector | Description | Example | +| Selector | What it does | Example | | :--- | :--- | :--- | -| `START:N` | First N messages | `{{MESSAGES:START:5}}` = first 5 messages | -| `END:N` | Last N messages | `{{MESSAGES:END:5}}` = last 5 messages | -| `MIDDLETRUNCATE:N` | First half + last half (total N messages) | `{{MESSAGES:MIDDLETRUNCATE:6}}` = first 3 + last 3 messages | +| `START:N` | First N messages | `{{MESSAGES:START:5}}` | +| `END:N` | Last N messages | `{{MESSAGES:END:5}}` | +| `MIDDLETRUNCATE:N` | First N/2 + last N/2 messages | `{{MESSAGES:MIDDLETRUNCATE:6}}` | -**How MIDDLETRUNCATE works for messages:** +With 20 messages, `{{MESSAGES:MIDDLETRUNCATE:6}}` keeps messages 1-3 and 18-20, skipping the 14 in the middle. -If you have 20 messages and use `{{MESSAGES:MIDDLETRUNCATE:6}}`: -- Takes the first 3 messages -- Takes the last 3 messages -- Skips the 14 messages in the middle -- Result: 6 messages total +**Pipe filters** (pipe `|`) truncate the **content of each individual message** to a character limit: -##### Pipe Filters (Per-Message Content Truncation) - -Pipe filters truncate the **content of each individual message** to a character limit. This is especially useful for task model prompts (title generation, tags, follow-ups) where conversations contain very long messages — for example, pasted documents or code. - -| Filter | Description | Example | +| Filter | What it does | Example | | :--- | :--- | :--- | | `\|start:N` | First N characters of each message | `\{\{MESSAGES\|start:300\}\}` | | `\|end:N` | Last N characters of each message | `\{\{MESSAGES\|end:300\}\}` | -| `\|middletruncate:N` | First half + last half of each message (N chars total) | `\{\{MESSAGES\|middletruncate:500\}\}` | +| `\|middletruncate:N` | First + last half of each message | `\{\{MESSAGES\|middletruncate:500\}\}` | -##### Combining Message Selectors and Pipe Filters +**Combine both** to control which messages are included and how long each one is: -You can combine both modifiers to control both **which messages** are included and **how long** each message's content is: - -**Syntax:** `{{MESSAGES:SELECTOR:N|filter:N}}` - -| Combined Syntax | What It Does | +| Syntax | What it does | | :--- | :--- | -| `\{\{MESSAGES\|middletruncate:500\}\}` | All messages, each truncated to 500 characters | -| `\{\{MESSAGES:END:2\|middletruncate:500\}\}` | Last 2 messages, each truncated to 500 characters | -| `\{\{MESSAGES:START:5\|start:200\}\}` | First 5 messages, each truncated to first 200 characters | -| `\{\{MESSAGES:MIDDLETRUNCATE:10\|middletruncate:50\}\}` | First 5 + last 5 messages, each truncated to 50 characters | +| `\{\{MESSAGES:END:2\|middletruncate:500\}\}` | Last 2 messages, each capped at 500 characters | +| `\{\{MESSAGES:START:5\|start:200\}\}` | First 5 messages, each capped at 200 characters | +| `\{\{MESSAGES:MIDDLETRUNCATE:10\|middletruncate:50\}\}` | First 5 + last 5 messages, each capped at 50 characters | -##### Practical Examples +:::warning Selectors count messages, not characters +`{{MESSAGES:MIDDLETRUNCATE:500}}` selects **500 messages**. To limit characters per message, use a pipe filter: `\{\{MESSAGES\|middletruncate:500\}\}`. Without pipe filters, a single pasted document can consume the entire context window. +::: -**Example 1: Title Generation with Limited Context** +--- + +## Version History + +Every save creates a new version. When editing a prompt, the **History sidebar** shows all versions with the commit message, author, timestamp, and a "Live" badge on the active production version. + +**Preview** any version by clicking it. **Set as Production** to restore it as the active version. **Delete** old versions from the menu (the current production version cannot be deleted). + +:::note Migration +Prompts created before the versioning update were automatically migrated with their content preserved as the initial "Live" version. The URL structure changed from command-based to ID-based, so existing bookmarks may need updating. As of v0.5.0, all variables are optional by default. +::: + +--- + +## Examples + +### Bug report generator (`/bug_report`) + +A structured form with required summary, priority dropdown, and reproduction steps, plus optional context fields: + +```txt +Generate a bug report with the following details: + +**Summary:** {{summary | text:placeholder="A brief summary of the issue":required}} +**Priority:** {{priority | select:options=["Critical","High","Medium","Low"]:default="Medium":required}} +**Steps to Reproduce:** +{{steps | textarea:placeholder="1. Go to...\n2. Click on...\n3. See error...":required}} + +**Additional Context:** {{additional_context | textarea:placeholder="Browser version, OS, screenshots, etc."}} +**Workaround:** {{workaround | textarea:placeholder="Any temporary solutions found"}} + +Please format this into a clear and complete bug report document. +``` + +### Meeting minutes (`/meeting_minutes`) + +Date and time pickers, required attendees and agenda, optional decisions and action items: + +```txt +# Meeting Minutes + +**Date:** {{meeting_date | date:required}} +**Time:** {{meeting_time | time:required}} +**Title:** {{title | text:placeholder="e.g., Weekly Team Sync":required}} +**Attendees:** {{attendees | text:placeholder="Comma-separated list of names":required}} + +## Agenda / Key Discussion Points +{{agenda_items | textarea:placeholder="Paste the agenda or list the key topics discussed.":required}} + +## Decisions Made +{{decisions | textarea:placeholder="Key decisions and outcomes"}} + +## Action Items +{{action_items | textarea:placeholder="Action item, assignee, and deadline for each."}} + +## Next Meeting +**Date:** {{next_meeting | date}} +**Topics:** {{next_topics | text:placeholder="Items to discuss next time"}} + +Please format this into a clean and professional meeting summary. +``` + +### Title generation (task model template) + +Uses message selectors + pipe filters to keep context small: ```txt Chat history: @@ -154,254 +252,16 @@ Chat history: Generate a short title for this conversation. ``` -This sends only the last 2 messages, each limited to 500 characters — ideal for generating titles without processing entire pasted documents. - -**Example 2: Summarization with Message Sampling** - -```txt -Conversation summary: -{{MESSAGES:MIDDLETRUNCATE:10|start:300}} - -Summarize the key points. -``` - -This takes the first 5 and last 5 messages (skipping the middle), and each message is truncated to its first 300 characters. - -**Example 3: Avoiding Common Mistakes** - -| Wrong | Right | Why | -| :--- | :--- | :--- | -| `\{\{MESSAGES:MIDDLETRUNCATE:500\}\}` expecting 500 tokens | `\{\{MESSAGES\|middletruncate:500\}\}` | The first selects 500 **messages**, the second limits each message to 500 **characters** | -| `\{\{MESSAGES:END:2\}\}` expecting 2000 chars | `\{\{MESSAGES:END:2\|middletruncate:1000\}\}` | Without a pipe filter, messages may be thousands of characters each | - -:::tip - -Using pipe filters on task model templates (title generation, tag generation, follow-up suggestions) is highly recommended for deployments that handle long conversations. Without pipe filters, a single message containing a pasted document could consume your entire context window. - -::: +Sends only the last 2 messages, each capped at 500 characters. --- -#### Using Custom Input Variables +## Limitations -**How It Works** +### Slash command namespace -1. **Create a prompt** with one or more custom variables using the syntax below. -2. **Use the prompt's slash command** in the chat input. -3. An **"Input Variables" popup window** will appear with a form field for each variable you defined. -4. **Fill out the form** and click `Save`. Note that by default, all fields are optional unless explicitly marked as required. -5. The variables in your prompt will be replaced with your input, and the final prompt will be sent to the model. +Public prompts appear in every user's `/` suggestions. Too many public prompts clutter the menu. Use the enable/disable toggle to keep inactive prompts out of suggestions. -**Syntax** +### Optional by default -There are two ways to define a custom variable: - -1. **Simple Input**: `{{variable_name}}` - * This creates a standard, single-line `text` type input field in the popup window. - * The field will be optional by default. - -2. **Typed Input**: `{{variable_name | [type][:property="value"]}}` - * This allows you to specify the type of input field (e.g., a dropdown, a date picker) and configure its properties. - * The field will be optional by default unless you add the `:required` flag. - -**Required vs Optional Variables** - -By default, all custom input variables are **optional**, meaning users can leave them blank when filling out the form. This flexible approach allows for versatile prompt templates where some information might not always be needed. - -To make a variable **required** (mandatory), add the `:required` flag: - -```txt -{{mandatory_field | text:required}} -{{optional_field | text}} -``` - -When a field is marked as required: - -* The form will display a visual indicator (asterisk) next to the field label -* Users cannot submit the form without providing a value -* Browser validation will prevent form submission if required fields are empty - -**Input Types Overview** - -You can specify different input types to build rich, user-friendly forms. Here is a table of available types and their properties. - -| Type | Description | Available Properties | Syntax Example | -| :--- | :--- | :--- | :--- | -| **text** | A standard single-line text input field, perfect for capturing short pieces of information like names, titles, or single-sentence summaries. This is the **default type if no other is specified**. | `placeholder`, `default`, `required` | `{{name \| text:placeholder="Enter name":required}}` | -| **textarea**| A multi-line text area designed for capturing longer blocks of text, such as detailed descriptions, article content, or code snippets. | `placeholder`, `default`, `required` | `{{description \| textarea:required}}` | -| **select** | A dropdown menu that presents a predefined list of choices. This is ideal for ensuring consistent input for things like status, priority, or categories. | `options` (JSON array), `placeholder`, `default`, `required` | `{{priority \| select:options=["High","Medium","Low"]:placeholder="Choose priority":required}}` | -| **number** | An input field that is restricted to numerical values only. Useful for quantities, ratings, or any other numeric data. | `placeholder`, `min`, `max`, `step`, `default`, `required` | `{{count \| number:min=1:max=100:default=5}}` | -| **checkbox**| A simple checkbox that represents a true or false (boolean) value. It's perfect for on/off toggles, like 'Include a conclusion?' or 'Mark as urgent?'. | `label`, `default` (boolean), `required` | `{{include_details \| checkbox:label="Include detailed analysis"}}` | -| **date** | A calendar-based date picker that allows users to easily select a specific day, month, and year, ensuring a standardized date format. | `placeholder`, `default` (YYYY-MM-DD), `required` | `{{start_date \| date:required}}` | -| **datetime-local**| A specialized picker that allows users to select both a specific date and a specific time. Great for scheduling appointments or logging event timestamps. | `placeholder`, `default`, `required` | `{{appointment \| datetime-local}}` | -| **color** | A visual color picker that allows the user to select a color or input a standard hex code (e.g., #FF5733). Useful for design and branding prompts. | `default` (hex code), `required` | `{{brand_color \| color:default="#FFFFFF"}}` | -| **email** | An input field specifically formatted and validated for email addresses, ensuring the user provides a correctly structured email. | `placeholder`, `default`, `required` | `{{recipient_email \| email:required}}` | -| **month** | A picker that allows users to select a specific month and year, without needing to choose a day. Useful for billing cycles, reports, or timelines. **Note:** This input type is only natively supported in Chrome and Edge. In Firefox and Safari, it will display as a plain text input instead of a month picker. | `placeholder`, `default`, `required` | `{{billing_month \| month}}` | -| **range** | A slider control that allows the user to select a numerical value from within a defined minimum and maximum range. Ideal for satisfaction scores or percentage adjustments. | `min`, `max`, `step`, `default`, `required` | `{{satisfaction \| range:min=1:max=10}}` | -| **tel** | An input field designed for telephone numbers. It semantically indicates the expected input type for browsers and devices. | `placeholder`, `default`, `required` | `{{phone_number \| tel}}` | -| **time** | A picker for selecting a time. Useful for scheduling meetings, logging events, or setting reminders without an associated date. | `placeholder`, `default`, `required` | `{{meeting_time \| time}}` | -| **url** | An input field for web addresses (URLs). It helps ensure that the user provides a link, which can be useful for prompts that analyze websites or reference online sources. | `placeholder`, `default`, `required` | `{{website \| url:required}}` | -| **map** | **(Experimental)** An interactive map interface that lets users click to select geographic coordinates. This is a powerful tool for location-based prompts. | `default` (e.g., "51.5,-0.09"), `required` | `{{location \| map}}` | - -#### Example Use Cases - -**1. Flexible Article Summarizer** - -Create a reusable prompt where the article content is required but additional parameters are optional. - -* **Command:** `/summarize_article` -* **Prompt Content:** - - ```txt - Please summarize the following article. {{article_text | textarea:placeholder="Paste the full text of the article here...":required}} - - {{summary_length | select:options=["Brief (3 bullets)","Detailed (5 bullets)","Executive Summary"]:default="Brief (3 bullets)"}} - - {{focus_area | text:placeholder="Any specific aspect to focus on? (optional)"}} - - {{include_quotes | checkbox:label="Include key quotes from the article"}} - ``` - - When you type `/summarize_article`, a modal will appear with a required text area for the article, and optional fields for customizing the summary style. - -**2. Advanced Bug Report Generator** - -This prompt ensures critical information is captured while allowing optional details. - -* **Command:** `/bug_report` -* **Prompt Content:** - - ```txt - Generate a bug report with the following details: - - **Summary:** {{summary | text:placeholder="A brief summary of the issue":required}} - **Priority:** {{priority | select:options=["Critical","High","Medium","Low"]:default="Medium":required}} - **Steps to Reproduce:** - {{steps | textarea:placeholder="1. Go to...\n2. Click on...\n3. See error...":required}} - - **Additional Context:** {{additional_context | textarea:placeholder="Browser version, OS, screenshots, etc. (optional)"}} - **Workaround:** {{workaround | textarea:placeholder="Any temporary solutions found (optional)"}} - - Please format this into a clear and complete bug report document. - ``` - - This creates a form where title, priority, and steps are mandatory, but additional context and workarounds are optional. - -**3. Social Media Post Generator with Smart Defaults** - -This prompt generates tailored content with required core information and optional customizations. - -* **Command:** `/social_post` -* **Prompt Content:** - - ```txt - Generate a social media post for {{platform | select:options=["LinkedIn","Twitter","Facebook","Instagram"]:required}}. - - **Topic:** {{topic | text:placeholder="e.g., New feature launch":required}} - **Key Message:** {{key_message | textarea:placeholder="What are the essential points to communicate?":required}} - **Tone of Voice:** {{tone | select:options=["Professional","Casual","Humorous","Inspirational"]:default="Professional"}} - **Call to Action:** {{cta | text:placeholder="e.g., 'Learn more', 'Sign up today'"}} - **Character Limit:** {{char_limit | number:placeholder="Leave blank for platform default"}} - **Include Hashtags:** {{include_hashtags | checkbox:label="Add relevant hashtags":default=true}} - - Please create an engaging post optimized for the selected platform. - ``` - -**4. Meeting Minutes Assistant with Flexible Structure** - -Generate structured meeting minutes with required basics and optional details. - -* **Command:** `/meeting_minutes` -* **Prompt Content:** - - ```txt - # Meeting Minutes - - **Date:** {{meeting_date | date:required}} - **Time:** {{meeting_time | time:required}} - **Meeting Title:** {{title | text:placeholder="e.g., Weekly Team Sync":required}} - **Attendees:** {{attendees | text:placeholder="Comma-separated list of names":required}} - - ## Agenda / Key Discussion Points - {{agenda_items | textarea:placeholder="Paste the agenda or list the key topics discussed.":required}} - - ## Decisions Made - {{decisions | textarea:placeholder="Key decisions and outcomes (optional)"}} - - ## Action Items - {{action_items | textarea:placeholder="List each action item, who it is assigned to, and the deadline."}} - - ## Next Meeting - **Date:** {{next_meeting | date}} - **Topics:** {{next_topics | text:placeholder="Items to discuss next time"}} - - Please format the above information into a clean and professional meeting summary. - ``` - -**5. Content Review Template** - -A flexible template for reviewing various types of content. - -* **Command:** `/content_review` -* **Prompt Content:** - - ```txt - Please review the following {{content_type | select:options=["Blog Post","Marketing Copy","Documentation","Email","Presentation"]:required}}: - - **Content Title:** {{title | text:required}} - **Content:** {{content | textarea:placeholder="Paste the content to be reviewed":required}} - - **Review Focus:** {{focus | select:options=["Grammar & Style","Technical Accuracy","Brand Voice","SEO Optimization","General Feedback"]:default="General Feedback"}} - **Target Audience:** {{audience | text:placeholder="Who is this content for?"}} - **Specific Concerns:** {{concerns | textarea:placeholder="Any particular areas you'd like me to focus on?"}} - **Word Count Target:** {{word_count | number:placeholder="Target word count (if relevant)"}} - - Please provide detailed feedback and suggestions for improvement. - ``` - -### Prompt Versioning and History - -Open WebUI includes a robust versioning system for prompts, allowing you to track changes over time and revert to previous versions if needed. - -#### Version Tracking -Every time you save changes to a prompt's content, name, command, or access control, a new version is automatically created. This ensures that your prompt's evolution is preserved. - -#### History Sidebar -When editing an existing prompt, you will see a **History** sidebar (on desktop) that lists all previous versions in reverse chronological order. Each entry shows: -* **Commit Message**: A brief description of the changes (if provided). -* **Author**: The user who made the changes, including their profile picture. -* **Timestamp**: When the change was made. -* **Live Badge**: Indicates which version is currently active in the chat. - -#### Managing Versions -* **Previewing**: Click on any version in the history sidebar to preview its content in the main editor. -* **Setting as Production**: To make a previous version the active "Live" version, select it and click **Set as Production**. -* **Deleting Versions**: You can delete individual history entries by clicking the menu icon next to the version. Note that you cannot delete the currently active production version. -* **Copying ID**: Click the prompt ID or a specific version's short ID to copy it to your clipboard for reference. - -### Access Control and Permissions - -Prompt management is controlled by the following permission settings: - -* **Prompts Access**: Users need the `USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS` permission to create and manage prompts. -* For detailed information about configuring permissions, refer to the [Permissions documentation](/features/access-security/rbac/permissions). - -### Best Practices - -* Use clear, descriptive titles for your prompts -* Create intuitive slash commands that reflect the prompt's purpose -* **Design with flexibility in mind**: Mark only truly essential fields as required, leaving optional fields for enhanced customization -* For custom variables, use clear names (e.g., `{{your_name}}` instead of `{{var1}}`) and descriptive `placeholder` text to make templates easy to understand -* **Provide sensible defaults** for optional fields where appropriate to speed up form completion -* **Use the required flag strategically** - only require information that is absolutely necessary for the prompt to function properly -* Document any specific requirements or expected inputs in the prompt description -* Test prompts with different variable combinations, including scenarios where optional fields are left blank -* Consider access levels carefully when sharing prompts with other users - public sharing means that it will appear automatically for all users when they hit `/` in a chat, so you want to avoid creating too many -* **Use the enable/disable toggle** to temporarily deactivate prompts you're not currently using instead of deleting them — this preserves the prompt's configuration and version history -* **Consider user workflows**: Think about which information users will always have versus what they might want to customize occasionally - -### Migration Notes - -* **Prompt History Migration**: Existing prompts created before the versioning update have been automatically migrated to the new system. Their current content has been preserved as the initial "Live" version in their history. -* **ID-based URLs**: The URL structure for editing prompts has changed from using commands to using unique IDs. Existing bookmarks to prompt edit pages may need to be updated. -* **Variable Requirement**: As of the v0.5.0 update, all variables are now treated as optional by default. To maintain required behavior for critical fields, edit your prompts to add the `:required` flag to those variables. +All custom input variables are optional unless marked `:required`. If your prompt depends on a field, add `:required` explicitly. diff --git a/docs/features/workspace/skills.md b/docs/features/workspace/skills.md index b0c57a41..ab11176b 100644 --- a/docs/features/workspace/skills.md +++ b/docs/features/workspace/skills.md @@ -4,62 +4,81 @@ title: "Skills" sidebar_label: "Skills" --- -Skills are reusable, markdown-based instruction sets that you can attach to models or invoke on-the-fly in chat. Unlike [Tools](/features/extensibility/plugin/tools) (which are executable Python scripts), Skills are **plain-text instructions** that teach a model *how* to approach a task — such as code review guidelines, writing style rules, or troubleshooting playbooks. +# 🧩 Skills + +**Teach your AI how to approach a task with plain-text instructions.** + +Skills are reusable, markdown-based instruction sets that you attach to models or invoke on-the-fly in chat. Unlike [Tools](/features/extensibility/plugin/tools) (executable Python scripts), Skills are plain-text instructions: code review guidelines, writing style rules, troubleshooting playbooks, data analysis workflows. The model reads them and follows them. + +Mention a skill with `$` in chat to inject its full content immediately. Or bind skills to a model so they're always available, loaded on-demand to keep the context window efficient. + +--- + +## Why Skills? + +### Instructions without code + +Write guidelines in Markdown. No Python, no API calls, no deployment. If you can write a document, you can create a skill. + +### On-demand context loading + +Model-attached skills use lazy loading. Only a lightweight manifest (name + description) is injected by default. The model loads the full instructions only when it needs them via the `view_skill` tool. + +### Reusable across models + +Create one "Code Review Guidelines" skill and attach it to every coding model. Update the skill once, and every model gets the new version. + +### Composable with tools + +Pair a skill with [Open Terminal](/features/open-terminal) or any tool server. The skill teaches the model *how* to use the tool (check exit codes, handle errors, use streaming for long-running commands), while the tool provides the *capability*. + +--- + +## Key Features + +| | | +| :--- | :--- | +| 📝 **Markdown content** | Write instructions in plain Markdown | +| ⚡ **$ mention in chat** | Type `$` to inject a skill's full content into the current message | +| 🤖 **Model binding** | Attach skills to models so they're always available | +| 📦 **Lazy loading** | Model-attached skills inject only a manifest; full content loads on-demand | +| 📥 **Import/Export** | Import `.md` files with YAML frontmatter; export as JSON | +| 🔒 **Access control** | Private by default, shareable with users or groups | +| 🔀 **Active/Inactive toggle** | Deactivate skills without deleting them | + +--- ## How Skills Work -Skills behave differently depending on how they are activated: +### User-selected skills ($ mention) -### User-Selected Skills ($ Mention) +Type `$` in the chat input to open the skill picker. Select a skill, and its **full content is injected directly** into the system prompt. The model has immediate access to the complete instructions. -When you mention a skill in chat with `$`, its **full content is injected directly** into the system prompt. The model has immediate access to the complete instructions without needing any extra tool calls. +### Model-attached skills -### Model-Attached Skills +Skills bound to a model use lazy loading: -Skills bound to a model use a **lazy-loading** architecture to keep the context window efficient: +1. **Manifest injection** - Only the skill's name and description are added to the system prompt. +2. **On-demand loading** - The model receives a `view_skill` builtin tool. When it determines it needs a skill's full instructions, it calls `view_skill(skill_name)` to load them. -1. **Manifest injection** — Only a lightweight manifest containing the skill's **name** and **description** is injected into the system prompt. -2. **On-demand loading** — The model receives a `view_skill` builtin tool. When it determines it needs a skill's full instructions, it calls `view_skill` with the skill name to load the complete content. +This means many skills can be attached to a model without consuming context window space until actually needed. -This design means that even if many skills are attached to a model, only the ones the model actually needs are loaded into context. +--- ## Creating a Skill -Navigate to **Workspace → Skills** and click **+ New Skill**. +Navigate to **Workspace > Skills** and click **+ New Skill**. | Field | Description | | :--- | :--- | -| **Name** | A human-readable display name (e.g., "Code Review Guidelines"). | -| **Skill ID** | A unique slug identifier, auto-generated from the name (e.g., `code-review-guidelines`). Editable during creation, read-only afterwards. | -| **Description** | A short summary shown in the manifest. For model-attached skills, the model uses this to decide whether to load the full instructions. | -| **Content** | The full skill instructions in **Markdown**. For user-selected skills this is injected directly; for model-attached skills it is loaded on-demand via `view_skill`. | - -Click **Save & Create** to finalize. - -## Using Skills - -### In Chat ($ Mention) - -Type `$` in the chat input to open the skill picker. Select a skill, and it will be attached to the message as a **skill mention** (similar to `@` for models or `#` for knowledge). The skill's **full content** is injected directly into the conversation, giving the model immediate access to the complete instructions. - -### Bound to a Model - -You can permanently attach skills to a model so they are always available: - -1. Go to **Workspace → Models**. -2. Edit a model and scroll to the **Skills** section. -3. Check the skills you want this model to always have access to. -4. Click **Save**. - -When a user chats with that model, the selected skills' manifests (name and description) are automatically injected, and the model can load the full content on-demand via `view_skill`. - -## Import and Export +| **Name** | Human-readable display name (e.g., "Code Review Guidelines") | +| **Skill ID** | Unique slug, auto-generated from the name. Editable during creation, read-only afterwards | +| **Description** | Short summary shown in the manifest. For model-attached skills, the model uses this to decide whether to load the full instructions | +| **Content** | Full skill instructions in Markdown | ### Importing from Markdown -Click **Import** on the Skills workspace page and select a `.md` file. If the file contains YAML frontmatter with `name` and/or `description` fields, those values are auto-populated into the creation form. - -Example frontmatter: +Click **Import** and select a `.md` file. If the file contains YAML frontmatter with `name` and/or `description` fields, those values are auto-populated: ```yaml --- @@ -72,75 +91,94 @@ description: Step-by-step instructions for thorough code reviews 1. Check for correctness... ``` -### Exporting +--- -- **Single skill**: Click the ellipsis menu (**...**) on a skill and select **Export** to download it as a JSON file. -- **Bulk export**: Click the **Export** button at the top of the Skills page to export all accessible skills as a single JSON file. +## Binding Skills to a Model + +1. Go to **Workspace > Models**. +2. Edit a model and scroll to the **Skills** section. +3. Check the skills you want this model to always have access to. +4. Click **Save**. + +The selected skills' manifests are automatically injected, and the model can load full content on-demand via `view_skill`. + +--- ## Skill Management -From the Skills workspace list, you can perform the following actions via the ellipsis menu (**...**) on each skill: +From the Skills workspace list, use the ellipsis menu (**...**): | Action | Description | | :--- | :--- | -| **Edit** | Open the skill editor to modify content, name, or description. | -| **Clone** | Create a copy with `-clone` appended to the ID and "(Clone)" to the name. | -| **Export** | Download the skill as a JSON file. | -| **Delete** | Permanently remove the skill. Also available via Shift+Click on the delete icon for quick deletion. | +| **Edit** | Modify content, name, or description | +| **Clone** | Create a copy with `-clone` appended to the ID | +| **Export** | Download as JSON | +| **Delete** | Permanently remove (Shift+Click for quick deletion) | -### Active / Inactive Toggle +**Bulk export**: Click the **Export** button at the top of the Skills page to export all accessible skills as a single JSON file. -Each skill has an **active/inactive toggle** visible on the list page. Inactive skills are excluded from manifests and cannot be loaded by the model, even if they are bound to one or mentioned in chat. +**Active/Inactive toggle**: Inactive skills are excluded from manifests and cannot be loaded by the model, even if bound to one or mentioned in chat. -## Code Execution Backends - -The backend you choose affects what your skills can do — from simple text transformations (Pyodide) to full OS-level shell access (Open Terminal). Each has different trade-offs in library support, isolation, persistence, and multi-user safety. - -See the [Code Execution overview](/features/chat-conversations/chat-features/code-execution) for a detailed comparison of all available backends and guidance on choosing the right one for your deployment. - -### Setting Up Open Terminal - -Open Terminal is a FastAPI application that automatically exposes an [OpenAPI specification](https://swagger.io/specification/). This means it works out of the box as an OpenAPI Tool Server — Open WebUI auto-discovers its endpoints and registers them as tools. No manual tool creation needed. - -**1. Start an Open Terminal instance** - -Follow the [Open Terminal setup guide](/features/open-terminal#getting-started) to launch an instance using Docker or pip. - -**2. Connect to Open WebUI** - -Add your Open Terminal instance as a Tool Server by following the [OpenAPI Tool Server Integration Guide](/features/extensibility/plugin/tools/openapi-servers/open-webui). You can connect it as: - -- A **User Tool Server** (in **Settings → Tools**) — connects from your browser, ideal for personal or local instances -- A **Global Tool Server** (in **Admin Settings → Integrations**) — connects from the backend, available to all users - -Once connected, the Open Terminal tools (execute, file upload, file download) appear automatically in the chat interface. - -:::tip -For the best experience, pair Open Terminal with a [Skill](/features/workspace/skills) that teaches the model how to use the tool effectively — for example, instructing it to always check exit codes, handle errors gracefully, and use streaming for long-running commands. -::: - -See the [Open Terminal documentation](/features/open-terminal) for the full API reference and detailed setup instructions. +--- ## Access Control Skills use the same [Access Control](/features/access-security/rbac) system as other workspace resources: - **Private by default**: Only the creator can see and edit a new skill. -- **Share with users or groups**: Use the **Access** button in the skill editor to grant `read` or `write` access to specific users or groups. -- **Read-only access**: Users with only read access can view the skill content but cannot edit it. The editor displays a "Read Only" badge. +- **Share with users or groups**: Grant `read` or `write` access via the **Access** button. +- **Read-only access**: Users with read access can view but not edit. The editor shows a "Read Only" badge. -:::caution Attached Skills Still Require User Access -Attaching a skill to a model does **not** bypass access control. When a user chats with the model, Open WebUI checks whether **that specific user** has read access to each attached skill. Skills the user cannot access are silently excluded — the model won't receive the skill manifest and cannot call `view_skill` for it. +:::caution Attached skills still require user access +Attaching a skill to a model does **not** bypass access control. When a user chats with the model, Open WebUI checks whether that user has read access to each attached skill. Skills the user can't access are silently excluded. -**Example scenario**: An admin creates a private skill and attaches it to a model shared with all users. Regular users chatting with this model will **not** have the skill available because they don't have read access to the skill itself. +**Example**: An admin creates a private skill and attaches it to a shared model. Regular users chatting with this model will not get the skill because they don't have read access. -**Solution**: Make sure users who need access to the model's skills also have read access to each skill (via access grants, group permissions, or by making the skill public). The "Workspace → Skills Access" permission controls whether users can *create and manage* skills — it does **not** affect whether model-attached skills work for them. +**Solution**: Make sure users who need the model's skills also have read access to each skill (via access grants, group permissions, or by making the skill public). ::: -### Required Permissions +### Required permissions -- **Workspace → Skills Access**: Required to access the Skills workspace and create/manage skills. -- **Sharing → Share Skills**: Required to share skills with individual users or groups. -- **Sharing → Public Skills**: Required to make skills publicly accessible. +| Permission | What it controls | +| :--- | :--- | +| **Workspace > Skills Access** | Access the Skills workspace and create/manage skills | +| **Sharing > Share Skills** | Share skills with individual users or groups | +| **Sharing > Public Skills** | Make skills publicly accessible | -See [Permissions](/features/access-security/rbac/permissions) for details on how to configure these. +See [Permissions](/features/access-security/rbac/permissions) for configuration details. + +--- + +## Use Cases + +### Code review standards + +Write your team's review checklist as a skill: naming conventions, error handling patterns, test coverage requirements. Attach it to your coding models so every review follows the same bar. + +### Writing style guide + +Document tone, formatting rules, and terminology in a skill. Attach it to content-writing models. Every draft follows your brand voice. + +### Troubleshooting playbooks + +Encode your runbook for common issues: "check logs first, verify config, test connectivity, escalate if X." The model follows the same diagnostic steps your senior engineers would. + +### Tool usage instructions + +Pair a skill with Open Terminal to teach the model *how* to use it well. "Always check exit codes. Use `set -e` in scripts. Stream output for commands that take more than 10 seconds." + +--- + +## Limitations + +### Plain text only + +Skills are instructions, not executable code. For actions that require computation, API calls, or system access, use [Tools](/features/extensibility/plugin/tools) instead. + +### Context window with $ mention + +When injected via `$` mention, the full skill content goes into the system prompt. A very long skill attached to a model with a small context window may crowd out conversation history. + +### Lazy loading requires function calling + +Model-attached skills depend on the `view_skill` builtin tool, which requires [native function calling](/features/extensibility/plugin/tools#tool-calling-modes-default-vs-native) to be enabled. Without it, the model receives only the manifest and cannot load the full instructions. From 25b963b3b09176ae213d59da7267c10fb79b5ee6 Mon Sep 17 00:00:00 2001 From: Timothy Jaeryang Baek Date: Thu, 2 Apr 2026 19:57:15 -0500 Subject: [PATCH 06/25] refac --- docs/roadmap.mdx | 128 ++++++++++++++++++++++++----------------------- 1 file changed, 66 insertions(+), 62 deletions(-) diff --git a/docs/roadmap.mdx b/docs/roadmap.mdx index f1d57506..ec85d996 100644 --- a/docs/roadmap.mdx +++ b/docs/roadmap.mdx @@ -3,69 +3,73 @@ sidebar_position: 1400 title: "🛣️ Roadmap" --- +# 🛣️ Roadmap -At Open WebUI, we're committed to continually enhancing our platform to provide the best experience for our users. Below, you'll find the structured roadmap for our ongoing and future developments, categorized into Interface, Information Retrieval, and Community. - -## Interface 🖥️ - -Our roadmap for interface innovations aims to create a highly intuitive and accessible platform. These will not only improves user satisfaction but also enhance productivity by reducing the cognitive load on users. - -- 📦 **Packaged Single Binary Executable**: Simplifying deployment and ensuring compatibility across different platforms, we aim to offer our interface as a single binary executable. This approach will facilitate effortless installation and updates, significantly enhancing usability for all users, especially those with limited technical expertise. - -- 👤 **User Page**: A personal User Page feature where users can create posts. The functionality will also include features like followers, likes, and comments. This allows users to effectively share their model configurations, prompts, and files with a broader community, creating a richer, more connected ecosystem around the platform. - -- 📝 **AI Powered Notes**: Inspired by tools like Notion and Obsidian, we plan to introduce a robust note-taking feature that includes AI integration. From simple note-taking to full-fledged document creation, this tool will offer a seamless experience, all locally integrated within the platform. - -- 📈 **Advanced User Tracking and Cost Management Tools**: Users will gain access to comprehensive tools designed for tracking application performance and user activities, as well as managing costs effectively. These tools will empower users with the data they need to make informed decisions, improve user experiences, and maintain budget control, optimizing the use of resources across their AI applications. - -- 🧠 **AI Workflow Tool**: A node-based tool to orchestrate and compose multiple aspects of AI systems. This tool will allow users to visually connect different AI modules and services, creating complex workflows with ease. It's designed to empower users to harness the full potential of AI without needing deep technical knowledge in AI programming. - -- 🔊 **Local Text-to-Speech Integration**: This feature will allow natural language processing to convert text into lifelike spoken audio, thus making the platform more accessible, especially for visually impaired users. This integration helps in consuming information without screen interaction, facilitating multitasking and improving user engagement. - -- 📣 **Wakeword Detection**: Incorporating hands-free operation through voice commands will not only enhance accessibility but also align with emerging trends in IoT and smart environments, making our platform future-ready. - -- 💻 **Better Code Execution**: Enhancing coding functionalities within the platform supports a broad range of development activities, making it a one-stop solution for developers, thereby attracting a wider tech audience and fostering a robust developer community. - -- 🤖 **Code Interpreter Function**: A flexible code interpreter embedded into the platform can support multiple programming languages, which reduces the dependency on external tools and streamlines the development process, increasing efficiency. - -- 🔧 **Streamlined Fine-tune Support**: Open WebUI will offer a seamless fine-tuning process by allowing users to automatically build a fine-tune dataset simply by using the interface and rating the responses. We will provide Python notebooks to help preprocess your dataset, making it ready for fine-tuning directly from the notebook. This approach will be super simple and elegantly integrates fine-tuning into user workflows. - -- ♿ **Accessibility Enhancements**: Making Open WebUI accessible to everyone matters deeply to us. We're actively advancing features that ensure people with diverse abilities can fully enjoy and benefit from our platform. Accessibility is not just a feature—it's a core value that shapes all our interface decisions. To help us achieve this, we're welcoming interested contributors who share this passion and have expertise in accessibility. If you believe you can help us create a more inclusive experience, please reach out at [careers@openwebui.com](mailto:careers@openwebui.com). - -## Information Retrieval (RAG) 📚 - -Open WebUI currently provides an interface that enables the use of existing information retrieval (IR) models efficiency. However, we believe there is vast potential for improvement. We fully recognize the limitations of our current RAG (Retrieval-Augmented Generation) implementation in our WebUI, understanding that a one-size-fits-all approach does not effectively meet all users' needs. - -To address this, we are committed to transforming our framework to be highly modular and extensively configurable. This new direction will enable users to tailor the information retrieval process to their specific requirements with ease, using a straightforward, interactive interface that allows for simple drag-and-drop customization. This refinement aims to significantly enhance user experience by providing a more adaptable and personalized IR setup. - -Here's our focused plan for advancing our information retrieval capabilities: - -- 🌐 **Customizable RAG Framework**: Envision a future where you can effortlessly tailor your IR setup via a user-friendly interface. This will include modular components that users can drag, drop, and configure without needing deep technical knowledge. - -- 🔄 **Advanced Integration with SoTA Methods**: We aim to incorporate the latest developments in retrieval methods, enhancing accuracy and efficiency with advanced techniques and architectures. - -- 🔍 **Dedicated R&D**: We’re scaling up our research and development to discover and integrate novel retrieval methods that push the boundaries of current methods, in collaboration with leading research entities. - -## Community 🤝 - -We aim to create a vibrant community where everyone can contribute to and benefit from shared knowledge and developments: - -- 🏆 **LLM Leaderboard**: A community-driven approach to evaluate and rank models ensures transparency and continuous improvement, leveraging real-world applications to benchmark performance instead of relying on standard datasets that might not reflect practical utility. - -- 👥 **Sub-Communities**: Encouraging niche communities to curate datasets and optimize prompts can lead to better-tuned models, as these communities have specific insights and detailed feedback that typically go unnoticed in broader datasets. - -🔗 **Community Whitepaper**: Explore our detailed strategy and join us in shaping the future of AI-driven platforms in our [whitepaper](https://openwebui.com/assets/files/whitepaper.pdf). - -# Vision for the Future 🔭 - -Our relentless effort stems from a clear vision we hold dearly: enhancing your daily life, saving time and allowing for more focus on what truly matters. - -Imagine a world where you think, and it happens. You desire a cup of coffee made exactly the way you love, and it's brewed for you. A world where you, simply think of a comprehensive data analysis report in a particular format, and it's done at the speed of your thought. The core idea is to turn the time-consuming, routine tasks over to our AI interface, freeing up your time and attention. - -This isn’t a sci-fi future; together, we are working towards it right now. As our AI models gradually become more capable and intuitively understand your specific needs, your most mundane responsibilities become automated. Through this profound shift, our collective time allowance can be redistributed towards grand endeavours. Think space exploration, longevity research or simply extra moments with loved ones. - -Creating this imagined future won't be a walk in the park, but with your help, we believe it's within our reach. Open WebUI is more than just tech - it's there to enhance your day, giving you more space for what's really important. Together, we're working on a brighter tomorrow. Thanks for joining us in this extraordinary journey. +Open WebUI is building the AI interface that replaces everything else on your desktop. Here's where we're going. --- -Join us as we push the boundaries of technology with these ambitious and transformative features in our roadmap! 💡🚀 Your participation and feedback are crucial as we strive to make Open WebUI a pioneering tool in technology advancement. \ No newline at end of file +## 🔨 In Progress + +### 🖥️ Desktop App + +A dedicated desktop application with system-level integration. Global hotkeys, menu bar access, notification support, and instant launch. One download, double-click, running. No Docker, no Python, no terminal. Your AI assistant, always one keystroke away. + +### 📈 Usage Tracking & Cost Management + +Know exactly who's using what, how many tokens are flowing through each model, and what it's costing you. Per-user breakdowns, per-model analytics, and budget controls for teams that need to scale AI usage without surprises. + +### ♿ Accessibility + +Every release gets closer. Screen reader support, full keyboard navigation, ARIA compliance, high-contrast modes. AI should be for everyone, and we take that literally. + +--- + +## 🔭 Planned + +### 🧠 AI Workflow Builder + +Drag, drop, and wire together models, tools, knowledge bases, and logic gates into multi-step AI pipelines. Think: "pull data from this API, run it through GPT-4, check the output against these rules, then post the result." All visual. No code required. + +### ⏰ Scheduled Tasks & Automations + +Set your AI to work while you sleep. Daily report generation, weekly data pulls, automated monitoring, recurring analysis. Define a workflow once and let it run on autopilot. Your AI doesn't need to wait for you to ask. + +### 🔧 Integrated Fine-tuning + +Your conversations and ratings become training data. Open WebUI will build fine-tune datasets from your actual usage, preprocess them, and hand you a ready-to-train package. Personalized models, built from how you already work. Your AI gets better the more you use it. + +### 🧑‍💻 Enhanced Collaboration + +Multiple users in the same conversation, watching responses stream in together, annotating, branching, and building on each other's prompts. Brainstorming with your team and your AI in the same room. + +### 📣 Wakeword Detection + +Say the word and start talking. No keyboard, no click, no tab switching. Walk into a room, speak, and your AI is already listening. This is what the future of human-computer interaction looks like. + +### 🌐 Modular RAG Framework + +Swap out every piece of the retrieval pipeline from the UI. Different chunking strategies, different embedding models, different rerankers, all configurable with drag-and-drop. One size doesn't fit all, and your RAG setup shouldn't pretend it does. + +### 👤 User Profiles & Sharing + +Publish your model configurations, prompts, and skills. Follow other users. Build on what they've shared. A growing ecosystem of ready-to-use AI setups that anyone can import and make their own. + +### 🏆 Community Leaderboard + +Real-world model rankings based on actual usage and feedback, not synthetic benchmarks. See which models perform best for code, for writing, for analysis, ranked by the people who use them every day. + + +--- + +## The Vision + +AI is consolidating the tools we use every day. Search, writing, analysis, code, project management, they're all converging into a single interface. Open WebUI is built to be that interface: self-hosted, extensible, and designed to grow with the models it connects to. + +Everything on this page is a step toward that goal. + +--- + +Want to help us ship faster? Run the [dev branch](https://github.com/open-webui/open-webui), test upcoming features, and report what you find. Every bug caught early lets us tackle more. + +For discussion and real-time progress, join us on [Discord](https://discord.gg/5rJgQTnV4s) or follow development on [GitHub](https://github.com/open-webui/open-webui). \ No newline at end of file From 4c057c8434305a0d90af99f140bb930d78ee9157 Mon Sep 17 00:00:00 2001 From: Timothy Jaeryang Baek Date: Thu, 2 Apr 2026 20:04:00 -0500 Subject: [PATCH 07/25] refac --- docs/features/extensibility/index.md | 115 +++++++++++++++++++++++++++ docs/features/index.mdx | 2 +- 2 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 docs/features/extensibility/index.md diff --git a/docs/features/extensibility/index.md b/docs/features/extensibility/index.md new file mode 100644 index 00000000..5e057580 --- /dev/null +++ b/docs/features/extensibility/index.md @@ -0,0 +1,115 @@ +--- +sidebar_position: 0 +title: "Extensibility" +--- + +# 🔌 Extensibility + +**Make Open WebUI do anything with Python, HTTP, or community plugins you install in one click.** + +Open WebUI ships with powerful defaults, but your workflows aren't default. Extensibility is how you close the gap: give models real-time data, enforce compliance rules, add new AI providers, or connect to any external service. Write a few lines of Python, point at an OpenAPI endpoint, or browse the community library. The platform adapts to you, not the other way around. + +There are three layers, and most teams end up using at least two: + +- **In-process Python** (Tools & Functions) runs inside Open WebUI itself with zero infrastructure and instant iteration. +- **External HTTP** (OpenAPI & MCP servers) connects to services running anywhere, from a sidecar container to a third-party SaaS. +- **Pipeline workers** (Pipelines) offload heavy or sensitive processing to a separate container, keeping your main instance fast and clean. + +--- + +## Why Extensibility? + +### Give models real-world abilities + +Out of the box, an LLM can only work with what's in its training data and your conversation. Tools let it reach out: check the weather, query a database, call an API, run a calculation. The model decides when to use a tool based on the conversation. You just make the capability available. + +### Connect any external service + +Have an internal API? A third-party SaaS with an OpenAPI spec? An MCP server already running in your stack? Open WebUI discovers endpoints automatically and exposes them as tools the model can call. No glue code, no wrappers. + +### Control every message + +Functions let you intercept and transform messages before they reach the model (input filters) or before they reach the user (output filters). Redact PII, enforce formatting rules, log to an observability platform, inject system instructions dynamically, all without touching model configuration. + +### Offload heavy processing + +When a plugin needs GPU access, large dependencies, or isolated execution, run it as a Pipeline on a separate machine. Open WebUI talks to it over a standard API. Your main instance stays lean. + +### Import from the community + +Browse hundreds of community-built Tools and Functions from the Open WebUI Community site. Find what you need, click **Import**, and it's live. No `pip install`, no restart. + +--- + +## Key Features + +| | | +| :--- | :--- | +| 🐍 **Tools** | Python scripts that give models new abilities: web search, API calls, code execution | +| ⚙️ **Functions** | Platform extensions that add model providers (Pipes), message processing (Filters), or UI actions (Actions) | +| 🔗 **MCP support** | Native Streamable HTTP for Model Context Protocol servers | +| 🌐 **OpenAPI servers** | Auto-discover and expose tools from any OpenAPI-compatible endpoint | +| 🔧 **Pipelines** | Modular plugin framework running on a separate worker for heavy or sensitive processing | +| 📝 **Skills** | Markdown instruction sets that teach models how to approach specific tasks | +| ⚡ **Prompts** | Slash-command templates with typed input variables and versioning | +| 🏪 **Community library** | One-click import of community-built Tools and Functions | + +--- + +## Architecture at a Glance + +Understanding which layer to use saves time: + +| Layer | Runs where | Best for | Trade-off | +|-------|-----------|----------|-----------| +| **Tools & Functions** | Inside Open WebUI process | Real-time data, filters, UI actions, new providers | Shares resources with the main server | +| **OpenAPI / MCP** | Any HTTP endpoint | Connecting existing services, third-party APIs | Requires a running external server | +| **Pipelines** | Separate Docker container | GPU workloads, heavy dependencies, sandboxed execution | Additional infrastructure to manage | + +Most users start with **Tools & Functions**. They require no extra setup, have a built-in code editor, and cover the majority of use cases. + +--- + +## Use Cases + +### Real-time data enrichment + +A sales team builds a Tool that queries their CRM API. When a rep asks *"What's the latest on the Acme deal?"*, the model calls the tool, retrieves the pipeline stage, last activity, and deal value, and synthesizes a briefing with live data, not stale training knowledge. + +### Enterprise compliance filters + +A healthcare organization deploys a Filter Function that scans every outbound message for PHI patterns (SSN, MRN, dates of birth). Matches are redacted before the response reaches the user, and the original is logged to their SIEM. No model configuration changes required. The filter runs transparently on every conversation. + +### Multi-provider model routing + +An engineering team uses Pipe Functions to add Anthropic, Google Vertex AI, and a self-hosted vLLM instance alongside their existing Ollama models. Users see all providers in a single model selector with no separate logins and no API key juggling. + +### Heavy-compute pipelines + +A research group runs a Retrieval-Augmented Generation pipeline that re-ranks with a cross-encoder model requiring GPU. They deploy it as a Pipeline on a dedicated GPU node. Open WebUI routes relevant queries to the pipeline automatically while keeping the main instance on commodity hardware. + +--- + +## Limitations + +### Security + +Tools, Functions, and Pipelines execute **arbitrary Python code** on your server. Only install extensions from trusted sources, review code before importing, and restrict Workspace access to administrators. See the [Security Policy](/security) for details. + +### Resource sharing + +In-process Tools and Functions share CPU and memory with Open WebUI. Computationally expensive plugins should be moved to Pipelines or external services. + +### MCP transport + +Native MCP support is **Streamable HTTP only**. For stdio or SSE-based MCP servers, use [mcpo](https://github.com/open-webui/mcpo) as a translation proxy. + +--- + +## Dive Deeper + +| Topic | What you'll learn | +|-------|-------------------| +| [**Tools & Functions**](plugin) | Writing Python Tools, Functions (Pipes, Filters, Actions), and the development API | +| [**MCP**](mcp) | Connecting Model Context Protocol servers, OAuth setup, troubleshooting | +| [**Pipelines**](pipelines) | Deploying the pipeline worker, building custom pipelines, directory structure | diff --git a/docs/features/index.mdx b/docs/features/index.mdx index 98b33cb5..b9f417dc 100644 --- a/docs/features/index.mdx +++ b/docs/features/index.mdx @@ -133,7 +133,7 @@ Open WebUI is a platform, not a locked-down product. Write Python tools that run | 📝 **Skills** | Markdown instruction sets that teach models how to approach tasks | | ⚡ **Prompts** | Slash-command templates with typed input variables and versioning | -[**Learn about Extensibility →**](/features/extensibility/plugin) +[**Learn about Extensibility →**](/features/extensibility) --- From b0f3940cd486ff4e994ed7c0802da635eb4a522e Mon Sep 17 00:00:00 2001 From: Timothy Jaeryang Baek Date: Thu, 2 Apr 2026 20:08:20 -0500 Subject: [PATCH 08/25] refac --- docs/features/media-generation/index.md | 133 ++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 docs/features/media-generation/index.md diff --git a/docs/features/media-generation/index.md b/docs/features/media-generation/index.md new file mode 100644 index 00000000..c7f2d1ff --- /dev/null +++ b/docs/features/media-generation/index.md @@ -0,0 +1,133 @@ +--- +sidebar_position: 0 +title: "Media & Generation" +--- + +# 🎨 Media & Generation + +**Talk to your AI, have it talk back, and create images without leaving the conversation.** + +Open WebUI is not just text. Speak a prompt instead of typing it. Have the AI read its response aloud. Ask it to generate an image, edit a photo, or composite multiple images into one scene. With native tool calling, the model decides when to generate or edit visuals on its own, no manual toggle required. + +Everything runs through configurable providers, so you can start with built-in local models and swap in cloud services when you need higher quality or lower latency. + +--- + +## Why Media & Generation? + +### Voice as a first-class input + +Click the microphone icon and speak. Open WebUI transcribes with local Whisper by default, or routes to OpenAI, Mistral Voxtral, Deepgram, or Azure for cloud-grade accuracy. Dictation works from desktop and mobile with no extra setup. + +### AI that speaks back + +Every response can be read aloud with adjustable playback speed, tap-to-interrupt, and voice-interrupt support. Choose from OpenAI voices, ElevenLabs, Azure, local Kokoro/Chatterbox models, or the browser's built-in WebAPI. + +### Hands-free voice and video calls + +Start a real-time voice call directly from the chat. With a vision model selected, switch to a video call where the AI sees your camera feed and responds in context. + +### Image generation inside the conversation + +Ask the model to generate an image and it appears inline. With native function calling, the model invokes `generate_image` autonomously based on the conversation, no toggle or special syntax needed. + +### Image editing and compositing + +Upload a photo and describe what you want changed. The AI edits the image in place (inpainting) or combines multiple uploaded images into a single composite scene with harmonized lighting and perspective. + +--- + +## Key Features + +| | | +| :--- | :--- | +| 🎤 **Speech-to-Text** | Local Whisper, OpenAI, Mistral Voxtral, Deepgram, Azure, or browser WebAPI | +| 🔊 **Text-to-Speech** | OpenAI, ElevenLabs, Azure, Kokoro, Chatterbox, openedai-speech, browser WebAPI | +| 📞 **Voice & video calls** | Hands-free calls with vision model support and real-time responses | +| 🎚️ **Playback controls** | Adjustable speed, tap to interrupt, voice interrupt | +| 🖼️ **Image generation** | DALL-E, Gemini, ComfyUI, AUTOMATIC1111, Lumenfall, Image Router | +| ✏️ **Image editing** | Inpainting and multi-image compositing via natural language | +| 🤖 **Agentic generation** | Models generate and edit images autonomously during chat | + +--- + +## Supported Providers + +### Speech-to-Text + +| Provider | Runs locally | API key required | +|----------|:---:|:---:| +| **Whisper** (default) | ✅ | ❌ | +| **OpenAI** (Whisper API) | ❌ | ✅ | +| **Mistral** (Voxtral) | ❌ | ✅ | +| **Deepgram** | ❌ | ✅ | +| **Azure** | ❌ | ✅ | +| **Web API** (browser-native) | ✅ | ❌ | + +### Text-to-Speech + +| Provider | Runs locally | API key required | +|----------|:---:|:---:| +| **OpenAI TTS** | ❌ | ✅ | +| **ElevenLabs** | ❌ | ✅ | +| **Azure** | ❌ | ✅ | +| **Kokoro** | ✅ | ❌ | +| **Chatterbox** | ✅ | ❌ | +| **openedai-speech** | ✅ | ❌ | +| **Web API** (browser-native) | ✅ | ❌ | + +### Image Generation + +| Engine | Type | +|--------|------| +| **DALL-E** (OpenAI) | Cloud API | +| **Gemini** | Cloud API | +| **ComfyUI** | Self-hosted, node-based workflows | +| **AUTOMATIC1111** | Self-hosted Stable Diffusion | +| **Lumenfall** | Cloud API | +| **Image Router** | Multi-provider proxy | + +--- + +## Use Cases + +### Voice-driven research + +You are reviewing a dense paper on your phone. Instead of typing, you hold the microphone and ask, "Summarize the methodology in section 3." The AI transcribes your question, answers in text, and reads the summary aloud while you keep your eyes on the road. + +### Agentic creative workflow + +A designer describes a concept in chat: "Generate a hero image for our landing page, dark gradient background, abstract geometric shapes, our brand colors." The model calls `generate_image`, renders the result inline, and then the designer uploads the output and says "Make the shapes more angular and add a subtle grid overlay." The AI edits the image in place. + +### Multilingual voice interface + +A customer support team configures Whisper with `WHISPER_MULTILINGUAL=true` and a larger model. Agents speak queries in any supported language, and transcription happens locally with no data leaving the server. + +### Live video troubleshooting + +A technician points their phone camera at a piece of equipment and starts a video call with a vision model. The AI sees the hardware, identifies the issue, and walks through the fix step by step while the technician keeps both hands free. + +--- + +## Limitations + +### Context window usage + +Image generation and editing prompts consume tokens. Complex multi-step generation requests with large conversation histories may push against context window limits. + +### Provider-dependent capabilities + +Not all image engines support editing or compositing. DALL-E and ComfyUI have the broadest support. Check the engine-specific documentation for details. + +### Local STT performance + +Local Whisper runs on CPU by default. For faster transcription, use a larger model with GPU acceleration or switch to a cloud provider. The `:cuda` Docker image accelerates RAG embeddings but has minimal impact on Whisper speed for most users. + +--- + +## Dive Deeper + +| Topic | What you'll learn | +|-------|-------------------| +| [**Create & Edit Images**](image-generation-and-editing) | Engine setup (DALL-E, Gemini, ComfyUI, AUTOMATIC1111, Lumenfall), usage, editing, and compositing | +| [**Speech-to-Text & Text-to-Speech**](audio) | Provider configuration, environment variables, and integration guides | From 40856feecd517b3370a881bdbee8cd88c59fc4f6 Mon Sep 17 00:00:00 2001 From: Timothy Jaeryang Baek Date: Thu, 2 Apr 2026 20:12:42 -0500 Subject: [PATCH 09/25] refac --- docs/contributing.mdx | 126 +++++++++++++++++++----------------------- 1 file changed, 56 insertions(+), 70 deletions(-) diff --git a/docs/contributing.mdx b/docs/contributing.mdx index 0acd9513..c64124f6 100644 --- a/docs/contributing.mdx +++ b/docs/contributing.mdx @@ -3,111 +3,97 @@ sidebar_position: 1600 title: "🤝 Contributing" --- +# 🤝 Contributing -🚀 **Welcome, Contributors!** 🚀 +**Help build the AI interface everyone deserves.** -Your interest in contributing to Open WebUI is greatly appreciated. This document is here to guide you through the process, ensuring your contributions enhance the project effectively. Let's make Open WebUI even better, together! +Open WebUI is an independent project built and maintained by a small, dedicated core team. Whether you test dev builds, fix bugs, improve docs, or translate the UI, every contribution makes the project better for thousands of users. This page explains how to get involved and what to expect. -## 📜 Code of Conduct +--- -All contributors and community participants are expected to follow our **[Code of Conduct](https://github.com/open-webui/open-webui/blob/main/CODE_OF_CONDUCT.md)**. We operate under a **zero-tolerance policy** — disrespectful, demanding, or hostile behavior will result in immediate action without prior warning. +## Code of Conduct -Our community is built on the work of volunteers who dedicate their free time to this project. Please treat every interaction with professionalism and respect. +All contributors and community participants must follow the **[Code of Conduct](https://github.com/open-webui/open-webui/blob/main/CODE_OF_CONDUCT.md)**. We operate under a **zero-tolerance policy**: disrespectful, demanding, or hostile behavior results in immediate action without prior warning. -## 💡 Contributing +This project is built by volunteers in their free time. Treat every interaction with professionalism and respect. -Looking to contribute? Great! Here's how you can help: +--- -### 🧪 Test the Development Branch +## Ways to Contribute -**One of the most valuable ways to contribute is running the dev branch.** You don't need to write code—just use it and report issues! +### Test the development branch + +One of the most valuable contributions requires no code at all. Run the dev branch, use it daily, and report what breaks. ```bash docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:dev ``` -**Keep it updated regularly** — the dev branch moves fast! If Docker doesn't work for you, the [Local Development Guide](/getting-started/development) is another great option. +The dev branch moves fast, so **pull updates regularly**. If Docker is not your preference, follow the [Local Development Guide](/getting-started/development) instead. -By testing dev builds, you help us catch bugs before stable releases. Report issues on [GitHub](https://github.com/open-webui/open-webui/issues) with clear reproduction steps. **We cannot deliver high-quality releases without community testing.** +Report issues on [GitHub](https://github.com/open-webui/open-webui/issues) with clear reproduction steps. We cannot deliver high-quality releases without community testing. -### 🌟 Code Contribution Guidelines +### Submit code -We welcome pull requests. Before submitting one, please: +We welcome pull requests. Before submitting one: -1. Open a discussion regarding your ideas [here](https://github.com/open-webui/open-webui/discussions/new/choose). -2. Follow the project's coding standards and include tests for new features. -3. Update documentation as necessary. -4. Write clear, descriptive commit messages. +1. **Open a discussion first.** Propose your idea [here](https://github.com/open-webui/open-webui/discussions/new/choose) so the team can align on approach before you write code. +2. **Follow existing conventions.** Match the project's coding standards, naming patterns, and architecture. +3. **Keep PRs atomic.** Each pull request should address a single objective. If scope grows, split it into smaller, logically independent PRs. +4. **Avoid new external dependencies.** Do not add libraries or frameworks without prior discussion. We aim to stay framework-agnostic and implement functionality ourselves when practical. +5. **Include tests.** Cover new features with tests and update documentation as needed. +6. **Write clear commit messages.** Descriptive messages make review and history tracking easier. -### 🛠 Code PR Best Practices: +### Improve documentation -1. **Atomic PRs:** Make sure your PRs are small, focused, and deal with a single objective or task. This helps in easier code review and limits the chances of introducing unrelated issues. If the scope of changes grows too large, consider breaking them into smaller, logically independent PRs. -2. **Follow Existing Code Convention:** Ensure your code aligns with the existing coding standards and practices of the project. -3. **Avoid Additional External Dependencies:** Do not include additional external dependencies without prior discussion. -4. **Framework Agnostic Approach:** We aim to stay framework agnostic. Implement functionalities on our own whenever possible rather than relying on external frameworks or libraries. If you have doubts or suggestions regarding this approach, feel free to discuss it. +Help make Open WebUI more accessible by improving docs, writing tutorials, or creating setup guides. Documentation lives in the [docs repository](https://github.com/open-webui/docs). -Thank you for contributing! 🚀 +### Translate the UI -### 📚 Documentation & Tutorials - -Help us make Open WebUI more accessible by improving documentation, writing tutorials, or creating guides on setting up and optimizing the web UI. - -### 🌐 Translations and Internationalization - -Help us make Open WebUI available to a wider audience. In this section, we'll guide you through the process of adding new translations to the project. - -We use JSON files to store translations. You can find the existing translation files in the `src/lib/i18n/locales` directory. Each directory corresponds to a specific language, for example, `en-US` for English (US), `fr-FR` for French (France) and so on. You can refer to [ISO 639 Language Codes](http://www.lingoes.net/en/translator/langcode.htm) to find the appropriate code for a specific language. +Open WebUI uses JSON translation files in `src/lib/i18n/locales`. Each subdirectory is named with an [ISO 639 language code](http://www.lingoes.net/en/translator/langcode.htm) (e.g., `en-US`, `fr-FR`). To add a new language: -- Create a new directory in the `src/lib/i18n/locales` path with the appropriate language code as its name. For instance, if you're adding translations for Spanish (Spain), create a new directory named `es-ES`. -- Copy the American English translation file(s) (from `en-US` directory in `src/lib/i18n/locale`) to this new directory and update the string values in JSON format according to your language. Make sure to preserve the structure of the JSON object. -- Add the language code and its respective title to languages file at `src/lib/i18n/locales/languages.json`. +1. Create a new directory under `src/lib/i18n/locales` named with the appropriate language code +2. Copy the `en-US` translation files into the new directory +3. Translate the string values in each JSON file while preserving the object structure +4. Register the language in `src/lib/i18n/locales/languages.json` -### 🌎 Accessibility Matters +### Improve accessibility -We are committed to making **Open WebUI** inclusive and usable for everyone. Accessibility is a core part of good system design. +Accessibility is a core part of good design. When contributing UI changes: -Here’s how you can help improve accessibility when you contribute: +| Principle | What to do | +|-----------|-----------| +| **Semantic HTML** | Use `