Valves

Valves 和 UserValves 用于让用户提供动态信息，例如 API key 或配置选项。它们会在对应函数的 GUI 菜单中生成可填写字段或布尔开关。它们始终是可选的，但强烈建议使用。

因此，Valves 和 UserValves 类可以定义在 Pipe、Pipeline、Filter 或 Tools 类中。

Valves 只能由管理员在 Tools 或 Functions 菜单中配置；而 UserValves 则可由任意用户直接在聊天会话中配置。

带注释的示例


from pydantic import BaseModel, Field
from typing import Literal

# 定义 Valves
class Filter:
   # 注意这里的缩进：Valves 和 UserValves 必须声明为
   # Tools、Filter 或 Pipe 类的属性。这里以 Filter 为例。
    class Valves(BaseModel):
       # Valves 与 UserValves 继承自 pydantic 的 BaseModel。
       # 这使得 model validators 等高级能力也可使用。
       test_valve: int = Field(  # 注意类型标注：它会决定 UI 中展示的控件类型
           # 例如按钮、文本框等
           default=4,
           description="一个用于控制数值的 valve"
           # required=False,  # 若设为 True 可强制要求填写
       )
       # 若想让用户在多个字符串中二选一或多选一，可使用 typing.Literal：
       choice_option: Literal["choiceA", "choiceB"] = Field(
           default="choiceA",
           description="一个多选 valve 示例",
       )
       priority: int = Field(
           default=0,
           description="Filter 的优先级。值越小越先执行"
       )
       # priority 字段不是必需的，但如果存在，就会被用于
       # 排序 Filters。
       pass
       # 这个 pass 有助于解析，建议保留。

   # UserValves 的定义方式完全相同。
    class UserValves(BaseModel):
        test_user_valve: bool = Field(
            default=False, description="一个控制开/关的用户 valve"
       )
       pass

   def __init__(self):
       self.valves = self.Valves()
       # 由于这些值由管理员设置，因此代码执行时可直接访问
       pass

   # inlet 方法这里只是以 Filter 为例，__user__ 的处理逻辑相同
   def inlet(self, body: dict, __user__: dict):
       # 因为 UserValves 是按用户定义的，所以只有在使用时才可访问
       # 注意：虽然 __user__ 是 dict，但 __user__["valves"] 实际是
       # 一个 UserValves 对象，因此可以这样访问：
       test_user_valve = __user__["valves"].test_user_valve
       # 或者：
       test_user_valve = dict(__user__["valves"])["test_user_valve"]
       # 但下面这种方式会返回默认值，而不是真实值：
       # test_user_valve = __user__["valves"]["test_user_valve"]  # 不要这样做！

输入类型

Valves 支持一些特殊输入类型，它们会影响字段在 UI 中的渲染方式。你可以在 Pydantic Field 中通过 json_schema_extra 的 input 键进行配置。

Password Input（掩码输入）

对于密码、API key、secret 等敏感字段，你可以使用 password 输入类型，让其在 UI 中以掩码方式显示，从而避免明文暴露在屏幕上。

from pydantic import BaseModel, Field

class Tools:
    class UserValves(BaseModel):
        service_password: str = Field(
            default="",
            description="你的服务密码",
            json_schema_extra={"input": {"type": "password"}}
        )

渲染后，这个字段会以掩码输入框显示（字符显示为圆点），并带有显示 / 隐藏切换，底层使用的是 Open WebUI 的 SensitiveInput 组件。

提示

任何凭证或 secret 类型的用户配置项，都建议使用 password 输入类型。对于 UserValves 尤其重要，因为它们允许终端用户直接在聊天界面中配置。

对于用户应从预定义选项中选择的字段，可以使用 select 输入类型把它渲染为下拉菜单。选项既可以是静态列表，也可以是运行时动态生成的内容。

静态选项

对于不会变化的选项，直接使用列表即可：

from pydantic import BaseModel, Field

class Tools:
    class Valves(BaseModel):
        priority: str = Field(
            default="medium",
            description="处理优先级",
            json_schema_extra={
                "input": {
                    "type": "select",
                    "options": ["low", "medium", "high"]
                }
            }
        )

你也可以使用 label / value 对，使选项说明更清晰：

from pydantic import BaseModel, Field

class Tools:
    class Valves(BaseModel):
        log_level: str = Field(
            default="info",
            description="日志详细程度",
            json_schema_extra={
                "input": {
                    "type": "select",
                    "options": [
                        {"value": "debug", "label": "Debug（详细）"},
                        {"value": "info", "label": "Info（标准）"},
                        {"value": "warn", "label": "Warning（最少）"},
                        {"value": "error", "label": "Error（仅关键）"}
                    ]
                }
            }
        )

动态选项

如果选项需要在运行时生成（例如获取可用模型、数据库、用户资源等），可以把方法名作为字符串传入。该方法会在配置 UI 渲染时被调用：

from pydantic import BaseModel, Field

class Tools:
    class Valves(BaseModel):
        selected_model: str = Field(
            default="",
            description="选择要使用的模型",
            json_schema_extra={
                "input": {
                    "type": "select",
                    "options": "get_model_options"  # 方法名字符串
                }
            }
        )

        @classmethod
        def get_model_options(cls, __user__=None) -> list[dict]:
            """
            动态获取可用模型。
            当 Valves 配置 UI 打开时会调用该方法。
            """
            # 示例：基于运行时状态返回可选项
            return [
                {"value": "gpt-4", "label": "GPT-4"},
                {"value": "gpt-3.5-turbo", "label": "GPT-3.5 Turbo"},
                {"value": "claude-3-opus", "label": "Claude 3 Opus"}
            ]

该方法还可以接受可选的 __user__ 参数，以生成用户级别的动态选项：

from pydantic import BaseModel, Field

class Tools:
    class UserValves(BaseModel):
        workspace: str = Field(
            default="",
            description="选择你的工作区",
            json_schema_extra={
                "input": {
                    "type": "select",
                    "options": "get_user_workspaces"
                }
            }
        )

        @classmethod
        def get_user_workspaces(cls, __user__=None) -> list[dict]:
            """
            返回当前用户可用的工作区。
            __user__ 是一个包含用户信息的 dict。
            """
            if not __user__:
                return []

            user_id = __user__.get("id")
            # 从你的数据源中获取该用户的工作区
            return [
                {"value": "ws-1", "label": "Personal Workspace"},
                {"value": "ws-2", "label": "Team Workspace"}
            ]

提示

动态选项尤其适用于以下场景：

从已连接 provider 中获取可用模型
根据当前系统状态加载数据库或文件选项
展示用户专属资源，例如项目或工作区
任何需要根据运行时上下文变化的选项

本内容仅供参考，不构成任何保证、担保或合同承诺。Open WebUI 按“现状”提供。请参阅您的许可协议以了解适用条款。

Valves​

输入类型​

Password Input（掩码输入）​

Select Dropdown Input​

静态选项​

动态选项​

Valves

输入类型

Password Input（掩码输入）

Select Dropdown Input

静态选项

动态选项