跳到主要内容
注意

本教程为社区贡献，Open WebUI 团队不提供官方支持。它仅用于演示如何针对特定用例自定义 Open WebUI。想要做出贡献？请查看贡献教程。

🪄 特殊参数

在开发您自己的 Tools、Functions（Filters、Pipes 或 Actions）、Pipelines 等功能时，您可以使用特殊参数来探索 Open WebUI 所提供的全部功能。

本页面旨在详细介绍每个特殊参数的类型和结构，并提供相应示例。

body​

一个通常几乎直接传递给模型的 dict。虽然它严格来说不是一个特殊参数，但为了方便参考而将其包含在此处，并且它本身也包含一些特殊参数。

示例

{
  "stream": true,
  "model": "my-cool-model",
  # 单词以 - 分隔的小写字符串：这是模型的 ID
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "这张图片里有什么？"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAdYAAAGcCAYAAABk2YF[REDACTED]"
            # 图片以 base64 编码数据的形式传递
          }
        }
      ]
    },
    {
      "role": "assistant",
      "content": "这张图片看起来是 [REDACTED]"
    }
  ],
  "features": {
    "image_generation": false,
    "code_interpreter": false,
    "web_search": false
  },
  "stream_options": {
    "include_usage": true
  },
  "metadata": "[与 __metadata__ 完全相同的 dict]",
  "files": "[与 __files__ 完全相同的 list]"
}

__user__ {#user}​

包含用户信息的 dict。

请注意，如果定义了 UserValves 类，则必须通过 __user__["valves"] 访问其实例。否则，valves 键值将完全从 __user__ 中缺失。

示例
{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "email": "cheesy_dude@openwebui.com",
  "name": "Patrick",
  "role": "user",
  # role 可以是 `user` 或 `admin`
  "valves": "[UserValve 实例]"
}

__metadata__ {#metadata}​

一个包含有关聊天、模型、文件等广泛信息的 dict。

示例
{
  "user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "chat_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "message_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "session_id": "xxxxxxxxxxxxxxxxxxxx",
  "tool_ids": null,
  # tool_ids 是一个 str 列表。
  "tool_servers": [],
  "files": "[与 body['files'] 相同]",
  # 如果未提供文件，files 键仍存在于 __metadata__ 中，其值为 []
  "features": {
    "image_generation": false,
    "code_interpreter": false,
    "web_search": false
  },
  "variables": {
    "{{USER_NAME}}": "cheesy_username",
    "{{USER_LOCATION}}": "Unknown",
    "{{CURRENT_DATETIME}}": "2025-02-02 XX:XX:XX",
    "{{CURRENT_DATE}}": "2025-02-02",
    "{{CURRENT_TIME}}": "XX:XX:XX",
    "{{CURRENT_WEEKDAY}}": "Monday",
    "{{CURRENT_TIMEZONE}}": "Europe/Berlin",
    "{{USER_LANGUAGE}}": "en-US"
  },
  "model": "[与 __model__ 完全相同的 dict]",
  "direct": false,
  "function_calling": "native",
  "type": "user_response",
  "interface": "open-webui"
}
检测请求来源

interface 字段表示请求的来源：

  • "open-webui" - 请求来自 Web 界面
  • 其他/缺失 - 请求可能来自直接的 API 调用

对于直接 API 调用，如果 API 客户端没有显式提供，某些字段如 chat_id、message_id 和 session_id 可能会缺失或为 null。您可以使用它来在您的过滤器中区分 WebUI 和 API 请求：

def inlet(self, body: dict, __metadata__: dict = None) -> dict:
    if __metadata__ and __metadata__.get("interface") == "open-webui":
        # 来自 WebUI 的请求
        pass
    else:
        # 直接 API 请求
        pass
    return body

__model__ {#model}​

一个包含有关模型信息的 dict。

示例
{
  "id": "my-cool-model",
  "name": "My Cool Model",
  "object": "model",
  "created": 1746000000,
  "owned_by": "openai",
  # 可以是 openai 或 ollama
  "info": {
      "id": "my-cool-model",
      "user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "base_model_id": "gpt-4o",
      # 这是模型端点服务的模型名称
      "name": "My Cool Model",
      "params": {
      "system": "You are my best assistant. You answer [REDACTED]",
      "function_calling": "native"
      # 自定义选项出现在这里，例如 "Top K"
      },
      "meta": {
      "profile_image_url": "/static/favicon.png",
      "description": "Description of my-cool-model",
      "capabilities": {
          "vision": true,
          "usage": true,
          "citations": true
      },
      "position": 17,
      "tags": [
          {
          "name": "for_friends"
          },
          {
          "name": "vision_enabled"
          }
      ],
      "suggestion_prompts": null
      },
      "access_control": {
      "read": {
          "group_ids": [],
          "user_ids": []
      },
      "write": {
          "group_ids": [],
          "user_ids": []
      }
      },
      "is_active": true,
      "updated_at": 1740000000,
      "created_at": 1740000000
  },
  "preset": true,
  "actions": [],
  "tags": [
      {
          "name": "for_friends"
      },
      {
          "name": "vision_enabled"
      }
  ]
}

__messages__ {#messages}​

历史消息 list。

参见上文的 body["messages"] 值。

__chat_id__ {#chat_id}​

表示当前聊天/对话唯一标识符的 chat_id str。

对于源自聊天上下文的所有函数调用，此参数都会可靠传递，包括：

  • 常规用户消息
  • 内部任务调用（标题生成、查询生成、标签生成等）

这允许有状态的 functions/pipes/manifolds 维护每个聊天的状态而不会碎片化。

另请参阅 __metadata__["chat_id"]，以通过元数据字典访问相同的值。

__session_id__ {#session_id}​

session_id 的 str。

参见上文的 __metadata__["session_id"] 值。

__message_id__ {#message_id}​

message_id 的 str。

参见上文的 __metadata__["message_id"] 值。

__event_emitter__ {#event_emitter}​

用于向用户显示事件信息的 Callable。

__event_call__ {#event_call}​

用于 Actions 的 Callable。

__files__ {#files}​

通过聊天发送的文件 list。请注意，图片不被视为文件，它们会作为 body["messages"] 列表的一部分直接发送给模型。

出于性能原因，文件的实际二进制数据不属于参数的一部分，但如果需要，仍可以通过其路径访问文件。例如，使用 docker 时，路径的 python 语法可以是：

from pathlib import Path

the_file = Path(f"/app/backend/data/uploads/{__files__[0]["files"]["id"]}_{__files__[0]["files"]["filename"]}")
assert the_file.exists()

请注意，相同的 files 字典也可以通过 __metadata__["files"] 访问（如果未发送文件，其值为 []），或者通过 body["files"] 访问（但如果未发送文件，files 键将完全从 body 中缺失）。

示例

[
  {
    "type": "file",
    "file": {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "filename": "Napoleon - Wikipedia.pdf",
      "user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "hash": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "data": {
        "content": "Napoleon - Wikipedia\n\n\nNapoleon I\n\nThe Emperor Napoleon in His Study at the\nTuileries, 1812\n\nEmperor of the French\n\n1st reign 18 May 1804 – 6 April 1814\n\nSuccessor Louis XVIII[a]\n\n2nd reign 20 March 1815 – 22 June 1815\n\nSuccessor Louis XVIII[a]\n\nFirst Consul of the French Republic\n\nIn office\n13 December 1799 – 18 May 1804\n\nBorn Napoleone Buonaparte\n15 August 1769\nAjaccio, Corsica, Kingdom of\nFrance\n\nDied 5 May 1821 (aged 51)\nLongwood, Saint Helena\n\nBurial 15 December 1840\nLes Invalides, Paris\n\nNapoleon\nNapoleon Bonaparte[b] (born Napoleone\nBuonaparte;[1][c] 15 August 1769 – 5 May 1821), later\nknown [REDACTED]",
        # content 值是文档解析器输出的内容，上例是使用 Tika 作为文档解析器
      },
      "meta": {
        "name": "Napoleon - Wikipedia.pdf",
        "content_type": "application/pdf",
        "size": 10486578,
        # 单位为字节，此处约为 10Mb
        "data": {},
        "collection_name": "file-96xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        # 始终以 'file' 开头
      },
      "created_at": 1740000000,
      "updated_at": 1740000000
    },
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "url": "/api/v1/files/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "Napoleon - Wikipedia.pdf",
    "collection_name": "file-96xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "uploaded",
    "size": 10486578,
    "error": "",
    "itemId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    # itemId 与 file["id"] 不同
  }
]

__request__ {#request}​

fastapi.Request 的实例。您可以在 迁移页面 或 fastapi 官方文档 中阅读更多内容。

__task__ {#task}​

表示任务类型的 str。如果存在，其值仅为 __metadata__["task"] 的简写，否则为 None。

可能的值

[
    "title_generation",
    "tags_generation",
    "emoji_generation",
    "query_generation",
    "image_prompt_generation",
    "autocomplete_generation",
    "function_calling",
    "moa_response_generation"
]

__task_body__ {#task_body}​

一个 dict，包含完成给定 __task__ 所需的 body。如果存在，其值仅为 __metadata__["task_body"] 的简写，否则为 None。

其结构与上文的 body 相同，并进行了诸如使用合适模型和系统消息等修改。

__tools__ {#tools}​

ToolUserModel 实例的 list。

有关 ToolUserModel 实例属性的详细信息，可在 tools.py 中找到相关代码。

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.