Open-WebUI-Functions：扩展 Open WebUI 的 Python 函数集合

Open-WebUI-Functions is a collection of Python-based functions that extend Open WebUI with additional pipelines, filters, and integrations. These functions make it easier to connect external AI providers, process data, and tailor the Open WebUI experience to real-world workflows.

📚 Contents

🔎 Overview

This repository focuses on reusable Python functions for Open WebUI. It includes provider-specific pipelines, request and response filters, optional analytics helpers, secure secret handling, and both streaming and non-streaming integrations.

🏷️ Version

Branch	Version
`main`
*`hotfix/`**
*`release/`**
`dev`
*`feature/`**

These badges are generated and updated automatically by the GitVersion Badge workflow for all GitFlow branch types.

✨ Features

🧩 Custom pipelines: Extend Open WebUI with AI processing pipelines, including model inference and data transformations.
🔍 Filters for data processing: Apply custom filtering logic to refine, manipulate, or preprocess input and output data.
🤝 Azure AI support: Seamlessly connect Open WebUI with Azure OpenAI and other Azure AI models.
🤝 N8N workflow integration: Enable interactions with N8N for automation.
📱 Flexible configuration: Use environment variables to adjust function settings dynamically.
🚀 Streaming and non-streaming support: Handle both real-time and batch processing efficiently.
🛡️ Secure API key management: Automatically encrypt sensitive information such as API keys.

🏗️ Project structure

.
├── docs/
│   ├── azure-ai-citations.md
│   ├── azure-ai-integration.md
│   ├── google-gemini-integration.md
│   ├── infomaniak-integration.md
│   ├── n8n-integration.md
│   ├── n8n-tool-usage-display.md
│   ├── setup-azure-log-analytics.md
│   └── testing.md
├── filters/
│   ├── google_search_tool.py
│   ├── time_token_tracker.py
│   └── vertex_ai_search_tool.py
├── pipelines/
│   ├── azure/
│   ├── google/
│   ├── infomaniak/
│   └── n8n/
└── tests/
    └── e2e/          # Docker-based end-to-end tests (run.sh)

🔗 Prerequisites

Important

To use these functions, make sure the following requirements are met:

An active Open WebUI instance: You must have Open WebUI installed and running.
Required AI services (if applicable): Some pipelines depend on external AI services, such as Azure AI.
Admin access: You must have administrator privileges in Open WebUI to install functions.
Python packages: Some functions list extra Python packages in the requirements: line of their header (for example, the Google Gemini pipeline needs google-genai, which Open WebUI no longer bundles as of 0.11.4). Open WebUI installs them automatically unless ENABLE_PIP_INSTALL_FRONTMATTER_REQUIREMENTS=false or OFFLINE_MODE=true is set; in that case, install them into your Open WebUI image yourself (see Gemini requirements).

🚀 Installation

Tip

Follow these steps to install and configure functions in Open WebUI.

Ensure admin access

Note

You must be an admin in Open WebUI to install functions.

Open Admin Settings
- Navigate to the Admin Settings section in Open WebUI.
Open the Functions tab
- Go to the Functions tab in the admin panel.
Create a new function
- Click Add New Function.
- Copy the function code from this repository and paste it into the function editor.
Set environment variables if required
- Some functions require API keys or provider-specific configuration through environment variables.

Important

Set WEBUI_SECRET_KEY for secure encryption of sensitive API keys. This is required for the encryption features to work properly.

Save and activate
- Save the function, and it will be available inside Open WebUI.

🛡️ Security Features

Warning

API key security: Always use encryption for sensitive information such as API keys.

API key encryption

The functions include a built-in encryption mechanism for sensitive information:

Automatic encryption: API keys and other sensitive data are automatically encrypted when stored.
Encrypted storage: Values are stored with an encrypted: prefix followed by the encrypted data.
Transparent usage: Encryption and decryption happen automatically when values are accessed.
No extra configuration required: Everything works out of the box when WEBUI_SECRET_KEY is set.

Important

To enable encryption, set the WEBUI_SECRET_KEY environment variable:

# Set this in your Open WebUI environment or .env file
WEBUI_SECRET_KEY="your-secure-random-string"

🧩 Pipelines

Note

Pipelines are processing functions that extend Open WebUI with custom AI models, external integrations, and data manipulation logic.

1. Azure AI Foundry Pipeline

Tip

Azure OpenAI integration made easy

This pipeline provides seamless integration with Azure OpenAI and other Azure AI models, with advanced features such as Azure Search integration and multiple model support.

Enables interaction with Azure OpenAI and other Azure AI models.
Supports Azure Search / RAG integration for enhanced document retrieval (Azure OpenAI only). It uses Azure OpenAI On Your Data, which Microsoft retires on October 14, 2026; see Connect a Foundry IQ knowledge base for the recommended migration.
Native OpenWebUI citations support 🎯: Rich citation cards, source previews, relevance scores, and automatic [docX] → clickable markdown link conversion, also for streamed answers (Azure OpenAI only). Answers with [docX] references show only the referenced documents; answers without any show all retrieved documents (default) or none with AZURE_AI_SHOW_ALL_CITATIONS_WITHOUT_REFERENCES=false.
Search only where it helps: Background tasks (titles, tags, follow-ups) skip Azure AI Search and add no sources; tools/tool_choice (including Open WebUI's built-in tools) and stream_options are not sent together with data_sources, which Azure would otherwise ignore or reject, so function calling is not available in chats that use Azure AI Search.
Relevance scores: BM25 keyword and semantic rerank scores from Azure AI Search are displayed as a relevance percentage on citation cards, with independently configurable normalization via BM25_SCORE_MAX and RERANK_SCORE_MAX.
Supports multiple models via AZURE_AI_MODEL (semicolon- or comma-separated, for example gpt-4o;gpt-4o-mini) or automatic model extraction from the Azure OpenAI URL.
Large predefined model catalogue (GPT-4o, GPT-5, o3, o4-mini, Phi-4, DeepSeek-R1/V3, Mistral, Llama 3.x, Cohere, Grok, and more) via USE_PREDEFINED_AZURE_AI_MODELS.
Customizable pipeline display prefix via AZURE_AI_PIPELINE_PREFIX.
Flexible authentication: api-key header (default) or Authorization: Bearer token via AZURE_AI_USE_AUTHORIZATION_HEADER.
Token usage tracking: Requests stream_options.include_usage in streaming mode so token counts are saved to the Open WebUI database (not available for streaming with Azure AI Search, which does not support it).
Filters valid parameters to ensure clean requests.
Handles both streaming and non-streaming responses.
Provides configurable error handling and timeouts; a stream that fails ends with an Error: … message instead of an empty or cut-off answer, and streamed events of up to 4 MiB (large Azure AI Search contexts) are read.
Supports encryption of sensitive information such as API keys.

🔗 Azure AI Pipeline in Open WebUI

🔗 Learn more about Azure AI

📖 Azure AI citations documentation

2. N8N Pipeline

Tip

N8N workflow automation integration

Connect Open WebUI with N8N to leverage powerful workflow automation. It includes configurable AI agent tool usage display for better transparency into agent actions.

Integrates Open WebUI with N8N, an automation and workflow platform.
AI agent tool usage display (v2.2.0) 🛠️: Shows tool calls from N8N AI Agent workflows with three verbosity levels (minimal, compact, detailed) and customizable length limits (non-streaming mode only).
Streaming and non-streaming support for real-time and batch data processing.
Parses n8n native streaming (NDJSON), Server-Sent Events and plain-text streams without leaking SSE framing into the answer.
Forwards token usage from the workflow's non-streamed JSON reply to Open WebUI.
Shows error chunks of an n8n stream in the answer and ends a failed or interrupted stream with an error status.
Sends Open WebUI tasks (title, tags, follow-ups, ...) without chat_id, so they stay out of the workflow's chat memory.
Sends messages from Open WebUI to an N8N webhook.
Supports real-time message processing with dynamic field handling.
Enables automation of AI-generated responses inside an N8N workflow.
Supports encryption of sensitive information such as API keys.
Includes an example N8N workflow for the N8N Pipeline.

Important

Tool usage display limitation: The AI agent tool call display currently works only in non-streaming mode due to N8N's current streaming implementation. The code is future-proof and will work automatically when N8N adds intermediateSteps to streaming responses.

🔗 N8N Pipeline in Open WebUI

🔗 Learn more about N8N

📖 N8N tool usage display documentation

3. Infomaniak

Integrates Open WebUI with Infomaniak, a Swiss web hosting and cloud services provider.
Sends messages from Open WebUI to an Infomaniak AI Tool.
Streaming and non-streaming support with token usage tracking and status updates.
Supports encryption of sensitive information such as API keys.

🔗 Infomaniak Pipeline in Open WebUI

🔗 Learn more about Infomaniak

4. Google Gemini

Integrates Open WebUI with Google Gemini, a generative AI model by Google.
Supports integration with the Google Generative AI API or Vertex AI API for content generation.
Sends messages from Open WebUI to Google Gemini.
Supports encryption of sensitive information such as API keys.
Supports both streaming and non-streaming responses (streaming is automatically disabled for image generation models, including released IDs such as gemini-3.1-flash-image).
Thinking & reasoning: Configurable thinking levels (low / high; minimal / high for gemini-3.1-flash-image and gemini-3.1-flash-lite-image, minimal / medium / high for gemini-nano-banana-2.1) for Gemini 3 models and thinking budgets (0–32 768 tokens) for Gemini 2.5 models, with per-chat override support.
Lean history: Previously rendered thinking summaries are stripped from assistant messages before the conversation is replayed to the API (configurable).
Provides configurable error handling and timeouts: temporary API errors are retried (GOOGLE_RETRY_COUNT) for streaming and non-streaming requests, and every started status (thinking, image, video) is closed when a request fails or is stopped.
Advanced image processing: Optimized image handling with configurable compression, resizing, and quality settings.
Configurable parameters: Environment variables for image optimization (quality, max dimensions, format conversion).
Multi-image history: Configurable history image limit, hash-based deduplication, and automatic [Image N] labels so the model can reference earlier images.
Image generation (Gemini 3): Configurable aspect ratio (for example 16:9 or 1:1) and resolution (1K, 2K, or 4K) for Gemini 3 image models, with per-user valve overrides.
Nano Banana image models: gemini-nano-banana-2.1, gemini-3.1-flash-image and gemini-3.1-flash-lite-image are detected as image models; each generated image is uploaded once (interim thought images are skipped unless no final image arrives). API clients get generated images and videos as links in the answer. Google Search grounding is left out for the image models without Search support (gemini-2.5-flash-image, gemini-3.1-flash-lite-image). Newer image models outside Gemini 3 / Nano Banana naming can be added via GOOGLE_IMAGE_GENERATION_MODELS without a code change.
Video generation (Veo): Generate videos with Google Veo models (3.1, 3, 2). Configurable aspect ratio, resolution, duration, negative prompt, and person generation controls. Supports text-to-video and image-to-video for all supported Veo models. Videos are automatically uploaded and embedded with playback controls.
Token usage tracking: Returns prompt, completion, and total token counts to Open WebUI for automatic persistence in the database, for streaming and non-streaming responses.
Background tasks: Works as the Open WebUI task model for title, tag and follow-up generation (without Google Search grounding, even when the chat uses it).
Model whitelist & additional models: Restrict the visible model list via GOOGLE_MODEL_WHITELIST and add SDK-unsupported models via GOOGLE_MODEL_ADDITIONAL; changes show on the next model list refresh, without waiting for the model cache TTL.
Grounding with Google Search via the google_search_tool.py filter
Grounding with Vertex AI Search via the vertex_ai_search_tool.py filter
Native tool calling support (on Open WebUI 0.10+ set Function Calling to Legacy for now, see known limitations)
Configurable API version support

🔗 Google Gemini Pipeline in Open WebUI

🔗 Learn more about Google Gemini

Note

For LiteLLM users: To use Google Gemini models through LiteLLM, configure LiteLLM directly in Open WebUI under Admin Panel → Settings → Connections → OpenAI instead of using this pipeline. For more information about LiteLLM, visit the official LiteLLM GitHub repository.

🔍 Filters

Note

Filters allow preprocessing and post-processing of data within Open WebUI.

1. Time Token Tracker

Note

Performance monitoring for AI interactions

Track response times, token usage, and optionally send analytics to Azure Log Analytics for more complete observability.

Measures response time and token usage for AI interactions.
Supports tracking of total token usage and per-message token counts.
Can calculate token usage for all messages or only a subset.
Uses OpenAI's tiktoken library for token counting (accurate only for OpenAI models).
Falls back to an estimate (about 4 characters per token) while no tiktoken encoding is loaded, for example on offline installations without a tiktoken cache, so the chat still goes through. The encoding is downloaded in the background; requests do not wait for it (the very first one at most 5 seconds). Estimated counts are marked: tokensEstimated in the Log Analytics record and the log line, ~ in the status message.
Also works for API requests. Since Open WebUI 0.10, the filter's outlet step runs for them too. There is no chat window to show a status message, but the metrics are still logged and sent to Log Analytics.
On Open WebUI 0.11, response time and request tokens stay correct when Open WebUI adds RAG context or a code interpreter prompt to the user message after the filter's inlet step.
Optionally sends logs to an Azure Log Analytics Workspace (SEND_TO_LOG_ANALYTICS=true). The record is sent in the background with a 10 second timeout, so responses do not wait for Log Analytics.

Warning

The filter uses the Azure Monitor HTTP Data Collector API. Microsoft ended support for it on September 14, 2026; ingestion still works, but not for workspaces behind Azure Monitor Private Link (AMPLS). The Logs ingestion API that replaces it is not supported yet. See How to set up Azure Log Analytics.

🔗 Time Token Tracker in Open WebUI

🔗 How to set up Azure Log Analytics

2. Google Search Tool

Companion filter for the Google Gemini pipeline. Requires Open WebUI 0.9.0 or newer.
When Web Search is switched on for a chat, it replaces Open WebUI's own web search with Google Search grounding and the URL context tool.
Attach it to your Gemini models only. As a global filter it would switch off Open WebUI's web search for all other models too.
Requests without a features object (API clients, channel replies, automations) pass through unchanged.
Does not check Open WebUI's per-user web search permission, see the limitations.

🔗 Web search with Gemini

3. Vertex AI Search Tool

Companion filter for the Google Gemini pipeline in Vertex AI mode. Requires Open WebUI 0.9.0 or newer.
Turns on Vertex AI Search grounding when a request asks for the vertex_ai_search feature.
Gets the data store from the request's params.vertex_rag_store or, if that is not set, from the VERTEX_AI_RAG_STORE environment variable.

🔗 Grounding with Vertex AI Search

🤝 Integrations

🧪 Testing

Every function is tested end-to-end against a real Open WebUI container with mocked provider APIs (Gemini, Azure OpenAI / AI Foundry, n8n, Infomaniak, Azure Log Analytics). Only Docker and bash are needed (Git Bash works on Windows):

tests/e2e/run.sh                              # all suites on the pinned Open WebUI image
tests/e2e/run.sh --image v0.11.3-slim gemini  # one suite on another Open WebUI release
tests/e2e/check_owui_api.sh latest            # static check of the Open WebUI APIs the functions use

The five suites (gemini, azure, n8n, infomaniak, filters) run 292 checks in 7-10 minutes. Results are reported as PASS, FAIL or KNOWN (a failure that matches a registered known bug, shown with its issue and the branch with the pending fix). See the testing guide for options, debugging and how to add scenarios.

💪 Contributing

Tip

We welcome contributions of all kinds. You do not need to write code to contribute.

For detailed onboarding and contribution guidance, see CONTRIBUTING.md.

📜 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

💬 Support

Note

If you have any questions, suggestions, or need assistance, please open an issue to connect with us. 🤝

💫 Star History

Created by owndev — let's make Open WebUI even more amazing together. 💪