阀值配置

Valves

Valves 和 UserValves 用来让用户或管理员为 Tool / Function / Pipe / Pipeline 提供动态配置，例如 API Key、行为开关、优先级、目标模型等。它们在 UI 中会被渲染成可填写的字段、下拉框或布尔开关。

它们不是强制要求，但非常推荐使用。

Valves 与 UserValves 的区别

• Valves：只能由管理员在 Tools / Functions 菜单中配置
• UserValves：终端用户可以直接在聊天会话里配置

它们都可以定义在 Pipe、Pipeline、Filter 或 Tools 类中。

示例

from pydantic import BaseModel, Field
from typing import Literal

class Filter:
    class Valves(BaseModel):
        test_valve: int = Field(
            default=4,
            description="A valve controlling a numberical value"
        )
        choice_option: Literal["choiceA", "choiceB"] = Field(
            default="choiceA",
            description="An example of a multi choice valve",
        )
        priority: int = Field(
            default=0,
            description="Priority level for the filter operations. Lower values are passed through first"
        )
        pass

    class UserValves(BaseModel):
        test_user_valve: bool = Field(
            default=False,
            description="A user valve controlling a True/False switch"
        )
        pass

    def __init__(self):
        self.valves = self.Valves()

    def inlet(self, body: dict, __user__: dict):
        test_user_valve = __user__["valves"].test_user_valve
        test_user_valve = dict(__user__["valves"])["test_user_valve"]

注意点：

• Valves / UserValves 都继承自 BaseModel
• Valves 可直接通过 self.valves 访问
• UserValves 通过 __user__["valves"] 访问
• 不要用 __user__["valves"]["field"] 这种方式，它可能只拿到默认值而不是实际值

输入类型

你可以用 Field(..., json_schema_extra={...}) 控制 UI 里该字段的渲染方式。

密码输入（Masked Fields）

对于密码、API Key、secret 这类敏感字段，建议使用 password 输入类型：

from pydantic import BaseModel, Field

class Tools:
    class UserValves(BaseModel):
        service_password: str = Field(
            default="",
            description="Your service password",
            json_schema_extra={"input": {"type": "password"}}
        )

这会在 UI 中渲染成掩码输入框，并允许用户按需切换可见性。

提示

所有凭据类字段都建议用 password 输入，尤其是由终端用户直接配置的 UserValves。

Select 下拉框

当字段应该从固定候选列表中选择时，可以指定 select 输入类型。

静态选项

from pydantic import BaseModel, Field

class Tools:
    class Valves(BaseModel):
        priority: str = Field(
            default="medium",
            description="Processing priority level",
            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="Logging verbosity",
            json_schema_extra={
                "input": {
                    "type": "select",
                    "options": [
                        {"value": "debug", "label": "Debug (Verbose)"},
                        {"value": "info", "label": "Info (Standard)"},
                        {"value": "warn", "label": "Warning (Minimal)"},
                        {"value": "error", "label": "Error (Critical Only)"}
                    ]
                }
            }
        )

动态选项

如果候选项需要运行时生成，例如：

• 拉取可用模型
• 列出数据库
• 按用户返回工作区

可以把 options 写成一个方法名字符串：

from pydantic import BaseModel, Field

class Tools:
    class Valves(BaseModel):
        selected_model: str = Field(
            default="",
            description="Choose a model to use",
            json_schema_extra={
                "input": {
                    "type": "select",
                    "options": "get_model_options"
                }
            }
        )

        @classmethod
        def get_model_options(cls, __user__=None) -> list[dict]:
            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"}
            ]

如果是 UserValves，该方法还可以接收 __user__，按当前用户返回个性化选项：

from pydantic import BaseModel, Field

class Tools:
    class UserValves(BaseModel):
        workspace: str = Field(
            default="",
            description="Select your workspace",
            json_schema_extra={
                "input": {
                    "type": "select",
                    "options": "get_user_workspaces"
                }
            }
        )

        @classmethod
        def get_user_workspaces(cls, __user__=None) -> list[dict]:
            if not __user__:
                return []

            return [
                {"value": "ws-1", "label": "Personal Workspace"},
                {"value": "ws-2", "label": "Team Workspace"}
            ]

动态选项很适合这些场景

• 读取已连接提供方的模型列表
• 根据系统运行时状态动态列出资源
• 按用户权限或所属组织返回不同候选项