🧩 Functions

⚠️ 重要安全警告

Functions 会在您的服务器上执行任意 Python 代码。 函数的创建权限仅限于管理员。请仅安装来自信任源的函数，并在导入前仔细审核代码。恶意的 Function 可能会访问您的文件系统、窃取数据或破坏您的整个系统。有关完整详情，请参阅 Plugin 安全警告。

Functions 是模块化的 Python 插件，用于扩展 Open WebUI 本身的功能。虽然 Tools 赋予了 LLM 在推理期间调用外部 API 的能力，但 Functions 则在更深层次上改变了平台的行为。它们可以添加由任何 Python 逻辑驱动的全新“模型”、拦截并转换系统中流动的每一条消息，或者直接在聊天 UI 中放置交互式按钮。

应用场景非常广泛：连接私有 AI 提供商、构建能响应自然语言的智能家居控制器、创建数据库查询接口、为每次对话添加实时翻译、执行合规性政策、基于数据生成图表，或通过点击按钮触发外部工作流。只要您能用 Python 编写，就可以将其转换为 Function。

Functions 以 Python 源码的形式存储在数据库中，在运行时动态加载，并在服务器端执行。管理员负责创建和管理它们；常规用户则与结果进行交互。

Function 类型

Open WebUI 支持三种类型的 Functions。其类型是根据您 Python 代码中的类名自动检测的，因此您无需进行手动配置。

类型	类名 (Class Name)	作用	用户如何看到它
Pipe	`class Pipe`	添加自定义模型或 Agent	在聊天侧边栏中显示为可选择的模型
Filter	`class Filter`	拦截往返于模型的数据	作为中间件（Middleware）透明地运行在现有模型上
Action	`class Action`	为消息添加交互式按钮	在聊天消息上显示为可点击的按钮

Pipe 函数

Pipe 会在 Open WebUI 中注册为一个全新的“模型”。当用户选择它并发送消息时，pipe() 方法将处理整个请求，而不需要 LLM 后端。这使得 Pipes 极其多才多艺：

模型提供商：集成不遵循 OpenAI 协议的 API（Anthropic 原生接口、Google Vertex、自定义推理服务器）。
Agents & 工作流：构建多步骤的 Agents，使其能够调用 tools、联网搜索并开展多轮推理。
非 LLM 接口：创建智能家居控制器、数据库查询工具、搜索引擎、计算器或代码执行器。任何能接收用户输入并返回响应的逻辑。
代理与路由器 (Proxies & routers)：通过您自己的逻辑路由请求，添加缓存、负载均衡或成本追踪。

单个 Pipe 还可以通过定义返回模型标识符列表的 pipes() 方法，从而暴露多个模型（这被称为 "manifold" 岐管）。

→ Pipe 函数指南

Filter 函数

Filter 位于用户与模型之间，可在三个阶段拦截数据：

inlet()：在请求到达模型之前对其进行修改（添加上下文、净化输入、检测语言、执行速率限制、估算 token 成本）。
stream()：实时拦截模型输出的流式块（streamed chunks）（过滤审查内容、替换术语、追踪 token 使用情况）。
outlet()：在完成生成之后处理已完成的响应（记录日志到可观测性平台、格式化引用来源、追加免责声明、缓存响应）。

Filters 实现了强大的横切关注点（cross-cutting concerns），例如实时翻译、内容审核、提示词注入检测、A/B 测试、合规性日志记录以及 PII 脱敏，所有这些都无需修改底层的模型。

Filters 可以全局应用（针对所有模型），也可以附加到特定模型上。可切换的 filters 允许用户针对每场对话启用/禁用它们。

→ Filter 函数指南

Action 函数

Action 会在聊天消息工具栏中添加一个自定义按钮。当用户点击它时，action() 方法将运行，并拥有对事件系统的完整访问权限，以实现实时 UI 反馈、用户提示和确认操作。

Actions 可以做 Python 能做的任何事情：总结或翻译消息、复制格式化输出、置顶重要消息、将对话导出到外部系统、触发 CI/CD 管道、发送 Slack 通知、生成 PDF 报告、运行代码片段或启动外部工作流。

→ Action 函数指南

Functions 的工作原理

类型检测

当您保存 Function 时，Open WebUI 会扫描 Python 源码，查找名为 Pipe、Filter 或 Action 的顶级类。第一个匹配项将决定 function 的类型。您永远不需要手动设置类型，因为它会从代码中推断出来。

# 这被检测为 Pipe 函数：
class Pipe:
    async def pipe(self, body: dict) -> str:
        return "Hello from my custom model!"

# 这被检测为 Filter 函数：
class Filter:
    async def inlet(self, body: dict) -> dict:
        return body

模块加载与缓存

Python 源码会通过 exec() 被加载到临时的模块命名空间中。一旦加载，该模块就会缓存到内存中（request.app.state.FUNCTIONS），并且只有当源码发生改变时才会重新加载。您代码中的 import 语句会被自动重写，以便在 Open WebUI 包的命名空间中进行解析。

Frontmatter 前置元数据

文件顶部用三引号括起来的文档字符串会被解析为 YAML 前置元数据以获取属性：

"""
title: My Custom Function
author: your_name
author_url: https://github.com/your_name
version: 1.0.0
icon_url: https://example.com/icon.svg
required_open_webui_version: 0.4.0
requirements: requests, beautifulsoup4
"""

字段	用途
`title`	在管理员 UI 中的显示名称
`author` / `author_url`	创作者归属元数据
`version`	版本标识符
`icon_url`	显示在 function 名称旁的图标（请使用 URL，不要使用 base64）
`required_open_webui_version`	Open WebUI 最低兼容版本
`requirements`	英文逗号分隔的 pip 依赖包列表，用于自动安装

自动依赖项安装

当在前置元数据中指定了 requirements 时，Open WebUI 会在函数首次加载时，自动通过 pip 安装列出的包。这由 PIP_INSTALL_FRONTMATTER_REQUIREMENTS 环境变量控制（默认启用）。

安装 Functions

从社区库安装

浏览社区 Function 库。
在您想要的函数上点击 Get。
输入您的 Open WebUI 实例 URL（例如 http://localhost:3000）。
点击 Import to Open WebUI。您将被重定向到 Function 编辑器。
审核代码，然后点击 Save。

警告

在导入之前，务必仔细审核源码。社区函数由用户贡献，且直接运行在您的服务器上。

从 URL 安装

前往 管理员面板 → Functions。
点击 Import from URL 并粘贴 Python 文件的链接。
- GitHub 链接会被自动转换为原始文件（raw）链接。
审核并保存。

手动创建

前往 管理员面板 → Functions。
点击 Create。
输入 ID（仅支持字母、数字和下划线）、名称及描述。
在编辑器中编写您的 Python 代码。
点击 Save。函数类型会从您的代码中自动检测。

管理 Functions

管理员控制项

可在 管理员面板 → Functions 管理所有的 Functions。每个函数都包含以下控制项：

控制项	描述
Active 切换开关	启用或禁用该函数。被禁用的函数不会被加载或执行。
Global 切换开关	启用后，该函数会自动应用到所有模型。适用于 Filters 和 Actions。
Valves（⚙️ 齿轮图标）	打开该函数管理员可配置的专属设置项。
Export / Delete	将函数导出为文件或直接将其删除。

将 Functions 分配给特定模型

除了让 Filter 或 Action 全局生效之外，您还可以将其附加到特定模型上：

前往 工作区 → 模型。
编辑目标模型。
在 Filters 或 Actions 区域，勾选您要关联的函数。

这允许不同的模型使用不同的 filters。例如，您可以仅对面向公众的模型应用内容审核过滤器。

可切换的 Filters

在 __init__ 中设置 self.toggle = True 可以让 Filters 变成用户可切换的。开启后，用户在聊天输入区域会看到一个开启/关闭开关，并且可以针对单场对话启用或禁用该 filter。不包含 self.toggle 的 filters 在处于激活状态时为常开模式。

Valves & UserValves

Functions 支持基于 Pydantic 构建的双层配置系统：

层级	类名	配置者	配置位置
管理员	`Valves`	仅限管理员	管理员面板 → Functions → ⚙️
用户	`UserValves`	任何用户	聊天界面，针对各函数独立配置

Valves 非常适合 API 密钥、模型端点以及全局行为设置。UserValves 则能让每个独立用户自定义行为（例如，他们偏好的语言、输出格式或个人 API 密钥）。

两者在您的 Pipe、Filter 或 Action 类中都定义为嵌套的 Pydantic BaseModel 类。管理员配置的值将保存在数据库中，并在运行时自动加载。

→ Valves 开发指南

Functions vs Tools：如何选择

使用场景	使用...	为什么
给 LLM 提供对实时数据的访问（天气、股票、API）	Tool	Tools 在推理期间被模型所调用
添加使用非 OpenAI 规范 API 的模型提供商	Pipe 函数	Pipes 会注册为侧边栏中的模型
构建非 LLM 接口（搜索、数据库、智能家居）	Pipe 函数	Pipes 自行处理整个请求，无需 LLM
构建具有自定义逻辑的多步骤 Agent	Pipe 函数	Pipes 控制着完整的请求/响应生命周期
实时翻译、审核或对内容进行脱敏	Filter 函数	Filters 会透明地拦截每一条消息
将请求记录到可观测性平台	Filter 函数	Inlet/outlet 过滤器能看到所有流量
限制速率或强制执行使用政策	Filter 函数	Inlet 过滤器可以在模型前拒绝请求
添加按钮以导出、总结或分享消息	Action 函数	Actions 出现在消息工具栏中
从聊天 UI 中触发外部工作流	Action 函数	Actions 在点击时运行任意 Python 代码

开发资源

指南	描述
Pipe 函数指南	构建自定义模型、Agents 及非 LLM 接口
Filter 函数指南	拦截、翻译、审核并记录消息日志
Action 函数指南	添加用于导出、工作流和交互式任务的按钮
Valves	通过管理员和用户设置配置函数
Events	向 UI 发送实时更新
保留参数	`__user__`、`__event_emitter__`、`__metadata__` 等
Rich UI	在响应中嵌入交互式 HTML/JS 内容

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.

Function 类型​

Pipe 函数​

Filter 函数​

Action 函数​

Functions 的工作原理​

类型检测​

模块加载与缓存​

Frontmatter 前置元数据​

安装 Functions​

从社区库安装​

从 URL 安装​

手动创建​

管理 Functions​

管理员控制项​

将 Functions 分配给特定模型​

可切换的 Filters​

Valves & UserValves​

Functions vs Tools：如何选择​

开发资源​