🐍 Python 代码执行

概述

Open WebUI 提供了两种执行 Python 代码的方法：

手动代码执行：使用浏览器中的“运行（Run）”按钮，运行由 LLMs 生成的 Python 代码块（使用 Pyodide/WebAssembly）。
代码解释器（Code Interpreter）：一项 AI 能力，允许模型自动编写并执行 Python 代码，并将其作为回复的一部分（使用 Pyodide 或 Jupyter）。

这两种方法都支持可视化输出（如 matplotlib 图表），并能直接在对话中内联显示。使用 Pyodide 引擎时，还提供了一个位于 /mnt/uploads/ 的持久化虚拟文件系统 —— 文件在多次代码执行和页面重新加载之间依然存在，并且附加到消息的文件会自动放置在该目录下，供您的代码直接访问。

代码解释器（Code Interpreter）能力

代码解释器是一项模型能力，使 LLMs 能够在对话过程中自主编写并执行 Python 代码。启用后，模型可以：

进行数学计算和数据分析
生成可视化图表（图表、曲线图、折线图等）
动态处理数据
执行多步骤的计算任务

启用代码解释器

针对单个模型的设置（管理员操作）：

前往 管理员面板 → 模型 (Admin Panel → Models)
选择您想要配置的模型
在 能力（Capabilities） 下，启用 代码解释器（Code Interpreter）
保存更改

全局配置（管理员面板操作）：

这些设置可以在 管理员面板 → 设置 → 代码执行 (Admin Panel → Settings → Code Execution) 中进行配置：

全局启用/禁用代码解释器
选择引擎：Pyodide（推荐）或 Jupyter (Legacy)
配置 Jupyter 连接设置
设置被禁用的模块

全局配置（环境变量）：

变量	默认值	描述
`ENABLE_CODE_INTERPRETER`	`true`	全局启用/禁用代码解释器
`CODE_INTERPRETER_ENGINE`	`pyodide`	要使用的引擎：`pyodide`（浏览器端，推荐）或 `jupyter`（服务器端，遗留）
`CODE_INTERPRETER_PROMPT_TEMPLATE`	（内置）	代码解释器的自定义 Prompt 模板
`CODE_INTERPRETER_BLACKLISTED_MODULES`	`""`	被禁用的 Python 模块列表（以逗号分隔）

有关 Jupyter 的配置方法，请参阅 Jupyter Notebook 集成教程。

文件系统 Prompt 注入

选择 Pyodide 引擎时，Open WebUI 会自动向代码解释器的指令中附加一条文件系统感知提示词。这会告诉模型关于 /mnt/uploads/ 的存在以及如何发现用户上传的文件。使用 Jupyter 时，则不会附加此文件系统提示词（因为 Jupyter 拥有自己的文件系统）。您不需要在自定义的 CODE_INTERPRETER_PROMPT_TEMPLATE 中包含文件系统指令 —— 它们是自动添加的。

原生函数调用（原生模式）

当对能力优秀的模型（如 GPT-5、Claude 4.5、MiniMax M2.5）使用原生函数调用（Native function calling）模式时，代码解释器将作为名为 execute_code 的内置工具提供。这提供了更一体化的体验：

无需 XML 标签：模型可以直接调用 execute_code(code)
同样的图片处理机制：输出中的 base64 图片 URLs 会被替换为文件 URLs；模型通过 Markdown 进行嵌入

要求：

ENABLE_CODE_INTERPRETER 必须在全局处于启用状态
模型必须启用了 code_interpreter 能力
Model 必须使用 Native 函数调用模式（在模型的高级参数中设置）

有关内置工具和原生模式的更多详细信息，请参阅工具开发指南。

内联显示图像（matplotlib 等）

当使用 matplotlib 或其他可视化库时，图像可以直接在对话中显示。为了使其正常工作，代码必须将图像输出为 base64 数据 URL（Data URL）。

matplotlib 推荐代码模式

import matplotlib.pyplot as plt
import io
import base64

# 创建您的图表
plt.figure(figsize=(10, 6))
plt.bar(['A', 'B', 'C'], [4, 7, 5])
plt.title('Sample Chart')

# 输出为 base64 数据 URL（触发自动上传）
buf = io.BytesIO()
plt.savefig(buf, format='png', dpi=150, bbox_inches='tight')
buf.seek(0)
img_base64 = base64.b64encode(buf.read()).decode('utf-8')
print(f"data:image/png;base64,{img_base64}")
plt.close()

图像显示工作原理

代码执行并将 data:image/png;base64,... 输出到标准输出（stdout）
Open WebUI 的中间件在输出中检测到 base64 图像数据
图像被自动上传并作为文件存储
base64 字符串被替换为文件 URL（例如 /api/v1/files/{id}/content）
模型在代码输出中看到此 URL，并在其回复中进行引用
图像在对话中内联渲染显示

理解流程

模型的代码应该输出 base64 数据 URL。Open WebUI 会拦截此数据并将其转换为永久的文件 URL。接着，模型应该在 Markdown 中使用这个生成的 URL，如 ![Chart](/api/v1/files/abc123/content) —— 它绝对不应该直接将原始 base64 字符串粘贴到其回复文本中。

如果您看到原始 base64 文本出现在对话回复中，说明模型错误地复现了 base64，而不是使用代码输出中转换后的 URL。

示例 Prompt

创建一个柱状图显示季度销售额：Q1: 150, Q2: 230, Q3: 180, Q4: 310。

预期的模型行为：

模型使用上述 base64 模式编写 Python 代码
代码执行并输出 data:image/png;base64,...
Open WebUI 将其转换为输出中的文件 URL（例如 ![Output Image](/api/v1/files/abc123/content)）
模型在回复中引用此 URL 以显示图表

常见问题

问题	原因	解决方案
对话中出现原始 base64 文本	模型在其回复文本中输出了 base64	指示模型仅在代码中打印 base64，不要重复它
图像未显示	代码使用了 `plt.show()` 却未输出 base64	改为使用上述 base64 代码模式
“正在分析...”加载圈卡住	代码执行超时或出错	检查后端日志以排查错误

手动代码执行（Pyodide）

Open WebUI 包含一个使用 Pyodide (WebAssembly) 的浏览器端 Python 环境。这允许直接在您的浏览器中运行 Python 脚本，无需任何服务器端配置。

Pyodide Worker 是持久的 —— 它只会被创建一次，并在多次代码执行之间重复使用。这意味着在同一会话中，变量、导入的模块以及写入虚拟文件系统的文件都会在多次执行之间保留。

手动运行代码

要求 LLM 编写 Python 代码
代码块中会出现一个 运行（Run） 按钮
点击以使用 Pyodide 执行代码
输出会显示在代码块下方

支持的第三方库

Pyodide 包含以下软件包，这些包会从 import 语句中被自动检测并在需要时加载：

软件包	使用场景
micropip	软件包安装器（内部使用）
requests	HTTP 请求
beautifulsoup4	HTML/XML 解析
numpy	数值计算
pandas	数据分析与处理
matplotlib	图表和曲线图生成
seaborn	统计数据可视化
scikit-learn	机器学习
scipy	科学计算
regex	高级正则表达式
sympy	符号数学计算
tiktoken	LLMs Token 计数
pytz	时区处理

Python 标准库也是完全可用的（json, csv, math, datetime, os, io 等）。

无法在运行时任意安装

AI 无法安装 上述列表之外的其它第三方库。任何导入了不支持软件包的代码都会运行失败并报错。需要 C 语言扩展、系统调用或原生二进制文件（如 torch, tensorflow, opencv, psycopg2）的包在 Pyodide 中是不支持的，也无法使其可用。Pyodide 最适合用于 基础文件分析、简单计算、文本处理和图表生成。若要获取完整的 Python 软件包访问权限，请改用 Open Terminal。

持久化文件系统

使用 Pyodide 引擎时，一个持久化的虚拟文件系统会被挂载到 /mnt/uploads/。该文件系统由浏览器的 IndexedDB 通过 IDBFS 提供支持，并具备：

跨执行持久化 —— 某次代码执行写入的文件，在后续执行中仍然可以访问。
跨刷新持久化 —— 即使重新加载页面，文件依然存在（存储在 IndexedDB 中）。
自动上传挂载 —— 附加到消息的文件在执行代码前会从服务器获取并放置在 /mnt/uploads/ 中，供模型直接读取。
文件浏览器面板 —— 启用代码解释器（Code Interpreter）后，侧边栏的对话控制面板中会出现文件浏览器。您可以浏览、预览、上传、下载和删除文件 —— 无需命令行终端。

在代码中操作文件

import os

# 列出上传的文件
print(os.listdir('/mnt/uploads'))

# 读取用户上传的 CSV 文件
import pandas as pd
df = pd.read_csv('/mnt/uploads/data.csv')
print(df.head())

# 将输出写入持久化文件系统（可通过文件浏览器下载）
df.to_csv('/mnt/uploads/result.csv', index=False)
print('Saved result.csv to /mnt/uploads/')

提示

文件浏览器面板允许您 download 任何文件该模型创建。要求模型将其输出保存到 /mnt/uploads/ 中，文件就会出现在文件浏览器中供您下载。

Jupyter 引擎

持久化文件系统提示词和 /mnt/uploads/ 的集成仅适用于 Pyodide。当使用 Jupyter 引擎时，文件是通过 Jupyter 自有的文件系统进行管理的。文件浏览器面板不适用于 Jupyter。

示例：创建图表

Prompt：

“使用 matplotlib 创建一个柱状图显示：Acuity 4.1, Signify 7.2, Hubbell 5.6, Legrand 8.9。将图表输出为 base64 数据 URL 以内联显示。”

预期的代码输出：

import matplotlib.pyplot as plt
import io
import base64

companies = ['Acuity', 'Signify', 'Hubbell', 'Legrand']
values = [4.1, 7.2, 5.6, 8.9]

plt.figure(figsize=(10, 6))
bars = plt.bar(companies, values, color=['#3498db', '#2ecc71', '#e74c3c', '#9b59b6'])

for bar, value in zip(bars, values):
    plt.text(bar.get_x() + bar.get_width()/2, bar.get_height() + 0.1, 
             str(value), ha='center', va='bottom', fontsize=12)

plt.title('Company Values', fontsize=16, fontweight='bold')
plt.xlabel('Company', fontsize=12)
plt.ylabel('Value', fontsize=12)
plt.tight_layout()

buf = io.BytesIO()
plt.savefig(buf, format='png', dpi=150, bbox_inches='tight')
buf.seek(0)
print(f"data:image/png;base64,{base64.b64encode(buf.read()).decode()}")
plt.close()

图像将被自动上传并内联显示在您的对话中。

浏览器兼容性

Microsoft Edge：Pyodide 崩溃问题

如果基于 Pyodide 的代码执行导致 Microsoft Edge 崩溃并提示 STATUS_ACCESS_VIOLATION 错误，这是由 Edge 的增强安全模式引起的。

症状：在尝试运行 Python 代码时，浏览器标签页或整个浏览器崩溃，且没有任何有用的错误提示。

原因：Edge 的“增强 Web 安全性”设置（位于 edge://settings/privacy/security）启用了更严格的安全缓解措施，这些措施与 Pyodide 等基于 WebAssembly 的运行时不兼容。

解决方案：

在 Edge 中禁用增强安全性：
- 前往 edge://settings/privacy/security
- 关闭 “增强您在 Web 上的安全性”
使用不同的浏览器：
- Chrome 和 Firefox 不存在此问题
使用 Jupyter 后端：
- 将 CODE_INTERPRETER_ENGINE 切换为 jupyter，以完全避免浏览器端执行

备注

这是 Edge 的增强安全模式与 WebAssembly 之间已知的兼容性问题。当启用此设置时，在官方的 Pyodide 控制台上也会发生相同的崩溃。

获取更佳效果的技巧

提及执行环境：告诉 LLM 它运行在 “Pyodide 环境”或“代码解释器”中，以便其生成更适配的代码
明确指出输出要求：针对图像明确要求 “输出 base64 数据 URL”
使用 print 语句：结果必须通过 print 打印出来才能显示在输出中
Check 第三方库支持：核对您所需的库是否在 Pyodide 的支持列表内

进一步阅读

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.

概述​

代码解释器（Code Interpreter）能力​

启用代码解释器​

原生函数调用（原生模式）​

内联显示图像（matplotlib 等）​

matplotlib 推荐代码模式​

图像显示工作原理​

示例 Prompt​

常见问题​

手动代码执行（Pyodide）​

手动运行代码​

支持的第三方库​

持久化文件系统​

在代码中操作文件​

示例：创建图表​

浏览器兼容性​

Microsoft Edge：Pyodide 崩溃问题​

获取更佳效果的技巧​

进一步阅读​

概述