🐍 Python 代码执行
概览
OPL 数据空间提供两种执行 Python 代码的方式：
- 手动代码执行：在浏览器里点击代码块上的 “Run” 按钮执行 LLM 生成的 Python（基于 Pyodide / WebAssembly）
- Code Interpreter：让模型在回答过程中自动编写并执行 Python 代码（基于 Pyodide 或 Jupyter）
这两种方式都支持图表等可视化输出，例如 matplotlib 生成的图片可直接内联到聊天中。使用 Pyodide 时，系统还会提供一个持久化虚拟文件系统 /mnt/uploads/，其中的文件可跨执行、跨刷新保留；消息上传的附件也会自动放入该目录，供代码直接访问。
Code Interpreter 能力
Code Interpreter 是模型能力之一，启用后模型可以在对话过程中自主编写并执行 Python 代码，用来：
- 做计算和数据分析
- 生成图表、图形和可视化
- 动态处理数据
- 执行多步骤计算任务
启用方式
按模型启用（Admin）：
- 进入 管理员面板 → Models
- 选择目标模型
- 在 Capabilities 中启用 Code Interpreter
- 保存
全局设置（管理员面板）：
在 管理员面板 → 设置 → 代码执行 中可以配置：
- 启用或禁用 code interpreter
- 选择引擎：Pyodide（推荐）或 Jupyter（Legacy）
- 配置 Jupyter 连接
- 设置被禁止的模块
环境变量：
| 变量 | 默认值 | 说明 |
|---|---|---|
ENABLE_CODE_INTERPRETER | true | 全局启用或禁用 Code Interpreter |
CODE_INTERPRETER_ENGINE | pyodide | 使用的执行引擎：pyodide 或 jupyter |
CODE_INTERPRETER_PROMPT_TEMPLATE | 内建 | 自定义 code interpreter 提示模板 |
CODE_INTERPRETER_BLACKLISTED_MODULES | "" | 逗号分隔的禁用 Python 模块列表 |
如需 Jupyter 配置，可参阅 Jupyter Notebook Integration。
当选择 Pyodide 引擎时， OPL 数据空间会自动向 code interpreter 指令中追加有关 /mnt/uploads/ 的文件系统提示。使用 Jupyter 时不会追加这一段，因此你通常不需要在自定义 CODE_INTERPRETER_PROMPT_TEMPLATE 里手写这些说明。
Native Function Calling（Native Mode）
当模型启用了 Native function calling，且具备较强推理能力（例如 GPT-5、Claude 4.5、MiniMax M2.5）时，Code Interpreter 会以内建工具 execute_code 的形式提供：
- 不再依赖 XML 标签
- 图片处理逻辑一致：代码输出中的 base64 图片会被替换成文件 URL，再由模型通过 markdown 嵌入
要求：
- 全局已启用
ENABLE_CODE_INTERPRETER - 模型已启用
code_interpretercapability - 模型在高级参数里把 Function Calling 设为 Native
更多工具细节见 Tool Development Guide。
图片内联显示（matplotlib 等）
如果你希望图表直接显示在聊天里，代码需要把图片输出为 base64 data URL。
推荐写法
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')
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()图片显示流程
- 代码向 stdout 打印
data:image/png;base64,... - OPL 数据空间检测到 base64 图片数据
- 系统自动把图片上传为文件
- base64 会被替换成文件 URL，例如
/api/v1/files/{id}/content - 模型在后续响应中引用这个 URL
- 图片就在聊天中内联显示
模型应该在代码里打印 base64 data URL，而不是把原始 base64 文本直接塞进自然语言回复。 OPL 数据空间会把它转换成永久文件 URL，模型应在响应中引用转换后的 URL。
常见问题
| 问题 | 原因 | 解决方法 |
|---|---|---|
| 聊天里出现原始 base64 文本 | 模型把 base64 直接写进了回复 | 提醒模型只在代码输出中打印 base64 |
| 图片不显示 | 代码只用了 plt.show() | 改用上面的 base64 输出模式 |
| “Analyzing...” 一直转圈 | 代码执行超时或报错 | 检查日志和代码输出 |
手动代码执行（Pyodide）
OPL 数据空间内建基于 Pyodide 的浏览器端 Python 环境，无需服务端额外配置。
Pyodide worker 是持久的，会在同一会话中复用，因此变量、已导入模块和虚拟文件系统中的文件都可以跨多次执行保留。
如何手动运行
- 让模型写出 Python 代码
- 代码块上会出现 Run
- 点击后由 Pyodide 执行
- 输出显示在代码块下方
支持的库
Pyodide 会按 import 自动加载以下包：
| 包 | 用途 |
|---|---|
| micropip | 包安装器（内部用途） |
| requests | HTTP 请求 |
| beautifulsoup4 | HTML / XML 解析 |
| numpy | 数值计算 |
| pandas | 数据分析 |
| matplotlib | 图表绘制 |
| seaborn | 统计可视化 |
| scikit-learn | 机器学习 |
| scipy | 科学计算 |
| regex | 高级正则 |
| sympy | 符号计算 |
| tiktoken | Token 计数 |
| pytz | 时区处理 |
Python 标准库同样可用，例如 json、csv、math、datetime、os、io 等。
AI 不能安装上表之外的新库。凡是依赖 C 扩展、系统调用或原生二进制的包，例如 torch、tensorflow、opencv、psycopg2，都不能在 Pyodide 中使用。
如果你需要完整包生态，建议改用 Open Terminal。
持久化文件系统
Pyodide 模式下，系统会在 /mnt/uploads/ 挂载一个持久化虚拟 文件系统，底层由浏览器 IndexedDB 支持，具备：
- 跨执行持久化：一次执行写入的文件，下一次还能读到
- 跨刷新持久化：刷新页面后仍保留
- 自动挂载上传文件：消息附件会在执行前自动放到
/mnt/uploads/ - 文件浏览器面板：启用 Code Interpreter 后，聊天侧栏可浏览、预览、上传、下载和删除文件
代码中如何使用文件
import os
import pandas as pd
print(os.listdir('/mnt/uploads'))
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/')如果你希望用户下载模型生成的 文件，请让模型把结果写到 /mnt/uploads/。之后它会自动出现在文件浏览器中。
/mnt/uploads/ 和文件系统提示只适用于 Pyodide。使用 Jupyter 时，文件管理走的是 Jupyter 自身的文件系统，侧边栏文件浏览器也不会出现。
示例：生成图表
提示词：
“请用 matplotlib 生成一个柱状图，展示：Acuity 4.1、Signify 7.2、Hubbell 5.6、Legrand 8.9，并把图片输出成 base64 data URL，以便内联显示。”
图像将被自动上传并显示在聊天中。
浏览器兼容性
Microsoft Edge 中 Pyodide 崩溃
如果在 Edge 中运行 Pyodide 导致 STATUS_ACCESS_VIOLATION 崩溃，通常与 Edge 的增强安全模式有关。
症状：
- 一运行 Python 代码，浏览器标签页甚至整个浏览器直接崩溃
原因：
edge://settings/privacy/security中的 Enhance your security on the web 会启用更严格的安全策略，而这些策略与基于 WebAssembly 的 Pyodide 不兼容
解决方案：
- 关闭 Edge 的增强安全模式
- 换用 Chrome 或 Firefox
- 把
CODE_INTERPRETER_ENGINE改为jupyter
这是已知兼容性问题。在官方 Pyodide console 中也会出现类似现象。
提升效果的小技巧
- 在提示词里明确说明当前运行于 “Pyodide environment” 或 “code interpreter”
- 生成图片时，明确要求输出 “base64 data URL”
- 记得让代码
print结果，否则不会显示在输出区 - 在写复杂脚本前，先确认依赖库是否在 Pyodide 支持列表中