onyxdotapp/code-interpreter

LLM安全Python执行环境镜像文档

镜像概述

本镜像提供一个专为大型语言模型（LLM）设计的安全Python执行环境，旨在为需要处理不可信Python代码的LLM应用提供隔离、可控的运行空间。通过沙箱机制和资源限制，有效防止***代码执行、资源滥用及系统安全风险，同时保持与主流LLM框架的兼容性。

核心功能与特性

安全隔离机制

• 代码沙箱：采用轻量级容器隔离技术，限制代码执行权限，防止访问主机系统资源
• 危险模块过滤：默认禁用os、subprocess、socket等具有潜在风险的Python标准库模块
• 文件系统限制：仅允许访问指定的临时目录，禁止读写主机文件系统

资源管控能力

• CPU/内存限制：可配置CPU核心数、内存使用上限，防止资源耗尽
• 执行超时控制：支持设置代码执行最大时长，默认30秒，超时自动终止
• 网络隔离：默认禁用网络访问，可选开启并限制访问白名单域名

环境兼容性

• 预装核心依赖：包含numpy、pandas、matplotlib等数据分析常用库
• LLM框架支持：兼容LangChain、LLaMA Index等主流LLM应用框架的代码执行需求
• Python版本：基于Python 3.10构建，支持现代Python语法特性

可观测性与可控性

• 执行日志：详细记录代码执行过程、资源占用、输出结果及错误信息
• 权限配置：支持自定义允许/禁止的模块列表、系统调用白名单
• 状态监控：提供健康检查接口，实时监控容器运行状态

使用场景与适用范围

典型应用场景

• LLM代码解释器：为GPT、Claude等LLM提供安全的代码执行后端（类似Code Interpreter功能）
• 用户代码评测系统：自动批改编程作业或竞赛代码，隔离不同用户代码
• 教育实训平台：提供安全的Python实验环境，允许学生编写并运行代码
• 自动化工作流：处理外部系统提交的Python脚本，防止***代码影响主系统

适用用户群体

• LLM应用开发者（需集成代码执行功能）
• 在线教育平台运营方
• 编程评测系统维护人员
• 需要处理不可信代码的企业级应用团队

使用方法与配置说明

基本使用流程

1. 获取镜像

bash
docker pull llm-safe-python-executor:latest

2. 启动容器（基础配置）

bash
docker run -d \
  --name llm-safe-exec \
  -p 8080:8080 \
  -e EXECUTION_TIMEOUT=30 \
  -e RESOURCE_LIMIT_CPU=1 \
  -e RESOURCE_LIMIT_MEM=1g \
  llm-safe-python-executor:latest

3. 提交代码执行请求

通过HTTP API提交代码执行请求：

bash
curl -X POST http://localhost:8080/execute \
  -H "Content-Type: application/json" \
  -d '{"code": "print(\"Hello, LLM Safe Exec!\")"}'

响应示例：

json
{
  "success": true,
  "output": "Hello, LLM Safe Exec!\n",
  "execution_time_ms": 42,
  "memory_used_mb": 8.2
}

高级配置参数

环境变量配置

docker-compose配置示例

yaml
version: '3.8'

services:
  llm-safe-exec:
    image: llm-safe-python-executor:latest
    container_name: llm-safe-exec
    ports:
      - "8080:8080"
    environment:
      - RESOURCE_LIMIT_CPU=2
      - RESOURCE_LIMIT_MEM=2g
      - EXECUTION_TIMEOUT=60
      - ALLOWED_MODULES="numpy,pandas,matplotlib"
      - NETWORK_ALLOWED=true
      - NETWORK_WHITELIST="pypi.org,github.com"
      - LOG_LEVEL=DEBUG
    volumes:
      - ./execution-logs:/app/logs  # 挂载日志目录
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G

API接口说明

代码执行接口

• URL: /execute
• 方法: POST
• 请求体:

  json
  {
    "code": "import numpy as np; print(np.array([1,2,3]))",  // 必选，待执行的Python代码
    "timeout": 45,  // 可选，覆盖全局超时设置（秒）
    "allow_network": true  // 可选，覆盖全局网络设置
  }
  

• 响应体:

  json
  {
    "success": true,
    "output": "[1 2 3]\n",
    "execution_time_ms": 125,
    "memory_used_mb": 45.3,
    "error": null,  // 执行失败时包含错误信息
    "timestamp": "2023-11-01T12:34:56Z"
  }
  

健康检查接口

• URL: /health
• 方法: GET
• 响应: 200 OK （容器正常运行）

安全最佳实践

1. 最小权限原则：仅开放必要的模块和资源权限，避免使用--privileged模式运行容器
2. 定期更新镜像：及时获取安全补丁和依赖更新
3. 日志审计：定期检查执行日志，监控异常代码执行行为
4. 资源隔离：在生产环境中使用独立的主机或Kubernetes Pod运行，进一步隔离风险
5. 输入验证：在提交代码至本环境前，建议先进行基础代码安全扫描（如检测明显的***模式）

注意事项

• 本镜像不能完全替代专业的代码安全审计工具，对于高风险场景建议结合多层安全防护
• 默认配置下不支持图形界面相关操作（如matplotlib的GUI后端），需通过Agg后端生成图片文件
• 长时间运行可能产生临时文件累积，建议定期清理或配置自动清理机制（如通过cron任务）
• 网络访问功能启用后需谨慎配置白名单，避免被用于数据泄露或***请求转发