Valves

Valves

Valves 和 UserValves 用于允许用户提供动态详情，例如 API 密钥或配置选项。这些会在 GUI 菜单中为给定的函数创建可填写的字段或布尔开关。它们始终是可选的，但强烈建议使用。

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

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。这
       # 能够支持如模型验证器等复杂的用例。
        test_valve: int = Field(  # 注意类型提示：它用于
            # 选择在 UI 中向用户显示的元素类型（按钮、文本框等）。
            default=4,
            description="控制数值的阀门"
            # required=False,  # 您可以通过使用 True 来强制必填该字段
        )
        # 为了让用户在多个字符串之间做出选择，您可以使用 typing 中的 Literal：
        choice_option: Literal["choiceA", "choiceB"] = Field(
            default="choiceA",
            description="多选阀门的示例",
        )
        priority: int = Field(
            default=0,
            description="Filter 操作的优先级。较低的值会优先通过"
        )
        # priority 字段是可选的，但如果存在，将用于对 Filters 进行排序。
        pass
        # 请注意，这个 'pass' 有助于解析，推荐使用。

    # UserValves 的定义方式相同。
     class UserValves(BaseModel):
         test_user_valve: bool = Field(
             default=False, description="控制 True/False（开启/关闭）开关的用户阀门"
        )
        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 定义中使用带有 input 键的 json_schema_extra 来进行配置。

密码输入（遮蔽字段）

对于密码、API 密钥或机密信息等敏感字段，您可以使用密码输入类型在 UI 中遮蔽其值。这可以防止密码在屏幕上被直接看到（防止旁观窥视）。

from pydantic import BaseModel, Field

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

渲染后，此字段将显示为遮蔽 input（用圆点代替字符），并提供一个切换按钮以便在需要时显示该值，这底层使用了 Open WebUI 的 SensitiveInput 组件。

提示

对于用户在 Valves 或 UserValves 中配置的任何凭据或机密信息，请务必使用密码输入类型。这对 UserValves 尤为重要，因为终端用户可以直接从聊天界面对其进行配置。

选择下拉菜单输入

对于用户需要从预定义列表中进行选择的字段，请使用选择输入类型来渲染下拉菜单。选项可以是静态的（硬编码列表），也可以是动态的（在运行时由方法生成）。

静态选项

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

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": "个人工作区"},
                {"value": "ws-2", "label": "团队工作区"}
            ]

提示

动态选项特别适用于以下场景：

• 从已连接的提供商中获取可用的 API 模型
• 基于当前系统状态加载数据库或文件选项
• 呈现用户专属资源，例如项目或工作区
• 任何选项会根据运行时上下文发生改变的场景