🧩 Functions（函数插件）

⚠️ 关键安全警告

Functions 会在你的服务器上执行任意 Python 代码。 只有管理员才能创建或导入 Function。你必须只从可信来源安装，并在导入前审阅代码。恶意 Function 可能访问文件系统、外传数据，甚至直接接管整个实例。完整背景见 Plugin Security Warning。

Functions 是 OPL 数据空间的 Python 插件扩展机制。和主要让模型在推理时调用外部 API 的 Tools 不同，Functions 更深入地改变平台行为：它可以新增自定义“模型”、拦截和改写消息流、或把交互按钮直接挂到聊天界面上。

你可以用它接入私有模型提供商、实现数据库查询界面、做翻译/审计/合规中间层、添加导出或工作流触发按钮，甚至构建完全不依赖 LLM 的交互型服务。只要能用 Python 写出来，就可以封装成 Function。

Functions 的源码以 Python 文本形式保存在数据库中，运行时动态加载，并在服务端执行。管理员负责创建和管理，普通用户只消费其结果。

Function 类型

OPL 数据空间支持三类 Function。类型由代码中的类名自动识别，无需手工指定。

类型	类名	作用	用户看到的形态
Pipe	`class Pipe`	增加一个自定义模型或代理	在聊天侧栏中显示为可选模型
Filter	`class Filter`	拦截模型前后数据流	作为中间件透明运行在现有模型上
Action	`class Action`	为消息增加交互按钮	出现在聊天消息工具栏

Pipe

Pipe 会把自己注册成 OPL 数据空间中的一个“模型”。当用户选择它并发送消息时，由 pipe() 方法完整处理请求，不一定需要真实的 LLM 后端。

典型场景：

接入非 OpenAI 协议的模型 API
构建多步骤 agent 或业务工作流
封装搜索、数据库、智能家居、代码执行器等非 LLM 接口
做模型路由、缓存、负载均衡、成本跟踪

一个 Pipe 也可以通过 pipes() 暴露多个模型入口（manifold）。

→ Pipe Function 指南

Filter

Filter 位于用户与模型之间，可在三个阶段介入：

inlet()：请求发给模型前处理输入
stream()：实时处理模型流式输出
outlet()：模型生成完成后再处理结果

典型用途包括：

实时翻译
内容审核与脱敏
Prompt Injection 检测
A/B 测试
合规日志
响应后处理与缓存

Filter 可以全局应用，也可以只绑定给特定模型。支持按聊天开关的 Filter，允许用户在某次会话中启用或关闭。

→ Filter Function 指南

Action

Action 会在聊天消息工具栏中增加一个自定义按钮。用户点击后，action() 方法执行，并可利用事件系统给 UI 实时反馈、提示或确认。

典型场景包括：

总结或翻译某条消息
导出结构化内容
发送 Slack 通知
触发 CI/CD 或外部工作流
生成 PDF 报告
运行附加自动化逻辑

→ Action Function 指南

Functions 的工作方式

类型识别

当你保存一个 Function 时， OPL 数据空间会扫描源码里的顶层类名 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

模块加载与缓存

OPL 数据空间通过 exec() 把 Python 源码加载到临时模块命名空间中。加载后会缓存在内存里，只有当源码发生变化时才重新加载。代码里的 import 也会自动重写，以便在 OPL 数据空间包命名空间内正确解析。

Frontmatter 元数据

文件顶部的三引号 docstring 会被解析为 YAML frontmatter：

"""
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`	图标 URL
`required_open_webui_version`	最低兼容版本
`requirements`	需要自动安装的 pip 包列表

自动安装依赖

当 frontmatter 中声明了 requirements 时， OPL 数据空间会在第一次加载 Function 时自动通过 pip 安装依赖。这个行为由 PIP_INSTALL_FRONTMATTER_REQUIREMENTS 控制，默认启用。

安装 Functions

从社区库导入

访问社区 Function Library。
找到目标 Function，点击 Get。
输入你的 OPL 数据空间实例地址，例如 http://localhost:3000。
点击 Import到OPL 数据空间，系统会跳转到 Function Editor。
审阅代码后点击 Save。

注意

社区 Function 由用户贡献，并且会直接在你的服务器上运行。导入前务必审阅源码。

通过 URL 导入

打开 管理员面板 → Functions。
点击 Import from URL，粘贴 Python 文件链接。
GitHub 普通页面链接会自动转成 raw URL。
审阅后保存。

手动创建

打开 管理员面板 → Functions。
点击 Create。
填写 ID、名称和描述。
在编辑器中编写 Python 代码。
点击 Save。

保存时类型会自动识别。

管理 Functions

管理员控制项

所有 Function 都在 管理员面板 → Functions 中管理。

控件	说明
Active toggle	启用或禁用 Function。禁用后不会加载和执行。
Global toggle	对 Filter / Action 可用。启用后自动作用于所有模型。
Valves（⚙️）	打开此 Function 的管理员配置项。
Export / Delete	导出文件或删除 Function。

绑定到特定模型

如果你不想把 Filter 或 Action 全局生效，也可以只把它们绑定到某些模型：

打开 Workspace → Models。
编辑目标模型。
在 Filters 或 Actions 区域里选中需要附加的 Function。

这样不同模型可以使用不同的过滤器或动作按钮。

可切换 Filter

若在 __init__ 中设置 self.toggle = True，这个 Filter 就会成为“用户可切换”的 Filter。用户会在聊天输入区域看到一个开关，可以按会话启用或关闭。没有设置 self.toggle 的 Filter，只要激活就始终生效。

Valves 与 UserValves

Functions 支持基于 Pydantic 的双层配置体系：

层级	类名	谁来配置	位置
管理员级	`Valves`	管理员	管理员面板 → Functions → ⚙️
用户级	`UserValves`	任意用户	聊天界面内

Valves 适合保存 API Key、模型端点和全局行为参数。UserValves 允许每位用户自定义自己的偏好，例如输出语言、格式、个人 API Key 等。

这两种配置都通过嵌套的 Pydantic BaseModel 定义在 Pipe、Filter 或 Action 类中。管理员保存的值会写入数据库，并在运行时自动加载。

→ Valves 开发指南

Functions 与 Tools 该怎么选

场景	选择	原因
让模型访问天气、股票、外部 API 等实时数据	Tool	Tool 在模型推理过程中被调用
接入不兼容 OpenAI 协议的模型提供商	Pipe Function	Pipe 会注册成模型
构建非 LLM 接口，例如搜索、数据库、智能家居	Pipe Function	Pipe 可以完整处理请求，无需 LLM
构建多步骤 agent 或复杂业务流程	Pipe Function	Pipe 掌控整个请求/响应循环
实时翻译、审核、脱敏	Filter Function	Filter 能透明拦截每条消息
接入观测平台或审计日志	Filter Function	inlet / outlet 可以观察所有流量
限流、策略校验、准入控制	Filter Function	inlet 可在模型执行前拒绝请求
给消息增加导出、总结、分享按钮	Action Function	Action 挂在消息工具栏上
从聊天 UI 触发外部工作流	Action Function	Action 在点击时执行任意 Python

开发资源

指南	说明
Pipe Function 指南	构建自定义模型、Agent 与非 LLM 接口
Filter Function 指南	拦截、翻译、审核、记录消息
Action Function 指南	为消息添加工作流和交互按钮
Valves	为 Function 提供管理员和用户配置
Events	向前端 UI 发送实时事件
Reserved Arguments	`__user__`、`__event_emitter__`、`__metadata__` 等保留参数
Rich UI	在响应中嵌入交互式 HTML / JS 内容

Function 类型​

Pipe​

Filter​

Action​

Functions 的工作方式​

类型识别​

模块加载与缓存​

Frontmatter 元数据​

安装 Functions​

从社区库导入​

通过 URL 导入​

手动创建​

管理 Functions​

管理员控制项​

绑定到特定模型​

可切换 Filter​

Valves 与 UserValves​

Functions 与 Tools 该怎么选​

开发资源​