在 CAMEL 中使用 UbuntuDockerRuntime基于 Docker 隔离环境运行 Qwen 角色扮演智能体的完整实战指南【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel本篇技术指南以 CAMEL 仓库中的examples/runtimes/ubuntu_docker_runtime示例为骨架系统讲解如何将 CAMEL 智能体框架部署进 Ubuntu Docker 容器从构建my-camel:latest镜像、初始化UbuntuDockerRuntime、配置 ModelScope 上的 Qwen 模型到在隔离容器中执行多智能体角色扮演任务Role-Playing的完整流程。读完本文你将掌握 CAMEL Docker Runtime 的镜像管理命令、运行时 API 用法以及底层exec_python_file与 FastAPI 工具服务的工作原理可直接复现一个容器内跑通 CAMEL 角色扮演的可运行方案。一、示例概述与前置条件该示例演示了如何在 Ubuntu 环境下使用 CAMEL 框架配合 Docker Runtime并集成了基于 Qwen 模型通过 ModelScope 访问的角色扮演Role-Playing能力。整个示例目录examples/runtimes/ubuntu_docker_runtime中包含以下四个文件examples/runtimes/ubuntu_docker_runtime/ ├── README.md ├── manage_camel_docker.sh ├── Dockerfile └── ubuntu_docker_example.py在开始之前需要满足以下前置条件与示例文档一致Docker已安装并处于运行状态Docker daemon 可用Python 3.10 或更高版本CAMEL 包已安装镜像内会通过pip3 install -e .[all]安装宿主机上运行示例脚本同样需要 CAMEL 环境ModelScope API Key用于通过 ModelScope 的 OpenAI 兼容接口访问 Qwen 模型。从仓库结构看该示例与 CAMEL 的 Runtimes 体系直接相关camel/runtimes/__init__.py导出了DockerRuntime与UbuntuDockerRuntime并在 runtimes 文档 中明确将UbuntuDockerRuntime定位为在容器内支持.py脚本执行、环境变量注入等完整系统级配置的 Docker 运行时变体。二、第一步构建与管理 Docker 镜像2.1 使用管理脚本构建镜像示例提供了manage_camel_docker.sh一键管理脚本。进入示例目录并构建镜像cd examples/runtimes/ubuntu_docker_runtime chmod x manage_camel_docker.sh ./manage_camel_docker.sh build构建完成后验证镜像是否生成docker images | grep my-camel正常情况下你会在输出列表中看到my-camel:latest。2.2 脚本子命令详解manage_camel_docker.sh支持以下子命令对应脚本中case分支见 manage_camel_docker.sh子命令功能说明build构建新镜像在临时目录中组装构建上下文并执行docker build -t my-camel:latest .clean清理相关资源停止并删除基于my-camel的容器删除镜像最后执行docker system prune -frebuild清理并重建等价于先clean再buildlist列出相关资源展示基于my-camel的容器列表与镜像信息help显示帮助信息无参数时也会显示帮助2.3 构建脚本的底层逻辑从源码看build_image函数manage_camel_docker.sh并非直接在示例目录执行docker build而是通过SCRIPT_DIR向上三级定位 CAMEL 项目根目录CAMEL_ROOT用mktemp -d创建临时构建目录将Dockerfile与整个 CAMEL 源码camel_source拷贝进去校验camel/runtimes/api.py存在并将其复制到临时目录的api/子目录用sed将 Dockerfile 中的COPY ../../../替换为COPY camel_source/、COPY camel/runtimes/api.py替换为COPY api/api.py保证在临时上下文内 COPY 路径有效在临时目录中执行docker build构建结束后清理临时目录。因此构建时 Docker 构建上下文build context实际是整个 CAMEL 源码 修正后的 Dockerfile构建产物即为my-camel:latest。脚本构建成功后会提示You can use this image in your code as follows: runtime DockerRuntime(my-camel:latest)2.4 Dockerfile 解析镜像内装了什么Dockerfile 完整定义了镜像内容逐段拆解如下FROM ubuntu:24.04sha256:c35e29c9450151419d9448b0fd75374fec4fff364a27f176fb458d472dfc9e54 # Set non-interactive environment ENV DEBIAN_FRONTENDnoninteractive # Install basic dependencies RUN apt-get update apt-get install -y \ python3 \ python3-pip \ git \ rm -rf /var/lib/apt/lists/* # Set working directory WORKDIR /app # Copy local CAMEL code COPY ../../../ ./camel/ # Change to CAMEL directory WORKDIR /app/camel # Install CAMEL and its dependencies RUN pip3 install -e .[all]关键点基础镜像固定为Ubuntu 24.04并锁定 digestsha256:...保证构建可复现安装python3、python3-pip、git三个基础依赖将宿主机上的 CAMEL 源码整体拷入容器/app/camel并以可编辑模式安装全部依赖pip3 install -e .[all]随后将 CAMEL 的 API 服务文件复制到/home/api.py并设置容器环境变量ENV PYTHONPATH/app/camel ENV HOST0.0.0.0 ENV PORT8000 # Expose port for API service EXPOSE 8000镜像默认启动命令是一个包装脚本/home/start.sh它会打印运行环境信息并以python3 /home/api.py --host 0.0.0.0 --port 8000启动 CAMEL 的运行时 API 服务详见 api.py。也就是说容器启动后即运行一个 FastAPI 服务供宿主机侧的DockerRuntime通过 HTTP 调用容器内注册的工具函数。三、第二步验证 Docker 环境与运行时 API示例文档中描述的测试脚本python test_camel_docker.py在examples/runtimes/ubuntu_docker_runtime目录中并未随附当前目录仅包含 README、Dockerfile、管理脚本和ubuntu_docker_example.py。该测试的目标行为可概括为启动一个包含 CAMEL 运行时的 Docker 容器初始化 API 服务执行基础操作以验证功能可用。仓库中的自动化测试test/runtimes/test_docker_runtime.py与test/runtimes/test_shared_runtime.py提供了类似的验证思路直接以DockerRuntime(xukunliu/camel)或DockerRuntime(camel-multi-toolkit:latest, port8000)构造运行时并执行工具调用。这些测试与示例互为印证——通过容器内 FastAPI 端点与宿主机通信是 Docker Runtime 的标准工作方式。四、第三步配置 Qwen 模型ModelScope角色扮演任务中的对话智能体需要后端大模型支撑。示例通过 CAMEL 的ModelFactory创建基于 ModelScope 的OpenAI 兼容接口模型指向 Qwen 系列模型model ModelFactory.create( model_platformModelPlatformType.OPENAI_COMPATIBLE_MODEL, model_typeQwen/Qwen2.5-72B-Instruct, urlhttps://api-inference.modelscope.cn/v1/, api_keyYOUR_MODELSCOPE_API_KEY_HERE, # Replace with your API key )参数说明model_platformModelPlatformType.OPENAI_COMPATIBLE_MODEL使用 OpenAI 兼容协议访问第三方推理服务。CAMEL 的 ModelFactory 会根据该枚举将OPENAI_COMPATIBLE_MODEL映射到OpenAICompatibleModel实现这也是 CAMEL 对接各类兼容 OpenAI API 的模型服务商包括 ModelScope、各类云厂商推理端点的统一入口model_typeQwen/Qwen2.5-72B-Instruct模型标识需替换为你实际可用的 ModelScope 模型 IDurlhttps://api-inference.modelscope.cn/v1/ModelScope 的 OpenAI 兼容推理端点地址api_keyYOUR_MODELSCOPE_API_KEY_HERE必须替换为你的真实 ModelScope API Key否则模型调用会鉴权失败。在 CAMEL 中除了在代码中直接ModelFactory.create(...)还可以把同样配置写入config.json/config.yaml后通过ModelFactory.create_from_json/create_from_yaml加载参见 config.json 与 config.yaml 中的model_platform: OPENAI_COMPATIBLE_MODEL示例适合把密钥与模型配置从代码中剥离。五、第四步运行容器内的角色扮演测试5.1 示例主程序ubuntu_docker_example.py配置好 API Key 后在宿主执行python examples/runtimes/ubuntu_docker_runtime/ubuntu_docker_example.py该脚本ubuntu_docker_example.py的核心流程为从环境变量读取OPENAI_API_KEY可选用于向容器传递构造UbuntuDockerRuntimeruntime UbuntuDockerRuntime( imagemy-camel:latest, python_path/usr/bin/python3, ports0, environment{ HOST: 0.0.0.0, OPENAI_API_KEY: openai_api_key, # Pass API key to container }, )调用runtime.build()启动容器定位仓库内examples/ai_society/role_playing.py脚本通过runtime.exec_python_file(local_file_pathscript_path)将脚本送入容器并执行任何异常都会打印Error: ...并以非零码退出。注意示例文档正文中提到的docker_roleplaying.py文件名在示例目录中实际对应的是ubuntu_docker_example.py请以实际文件为准。5.2 容器内执行的角色扮演脚本被送入容器执行的 role_playing.py 是 CAMEL 经典的角色扮演示例其任务设定为 Develop a trading bot for the stock market构造了如下RolePlaying会话role_play_session RolePlaying( assistant_role_namePython Programmer, assistant_agent_kwargsdict(modelmodel), user_role_nameStock Trader, user_agent_kwargsdict(modelmodel), task_prompttask_prompt, with_task_specifyTrue, task_specify_agent_kwargsdict(modelmodel), )运行效果打印 AI AssistantPython Programmer与 AI UserStock Trader的系统消息打印原始任务提示词、经任务细化task specify后的指定任务提示词与最终任务提示词双方以init_chat()起始、step()迭代对话最多轮数为chat_turn_limit50任一智能体终止terminated或用户消息中出现CAMEL_TASK_DONE时结束会话。这段脚本与示例文档描述完全吻合使用 Docker 容器运行角色扮演场景初始化 Qwen 模型进行 AI 交互并执行一次多智能体通信的示例任务。六、原理深挖UbuntuDockerRuntime 是如何工作的6.1 类继承关系与默认环境UbuntuDockerRuntime继承自DockerRuntime见 ubuntu_docker_runtime.py构造参数包括参数默认值说明image必填Docker 镜像名示例中为my-camel:latestport0暴露端口0表示随机端口10000–20000removeTrue容器停止后是否自动删除python_path/usr/bin/python3容器内 Python 解释器路径**kwargs—透传给底层DockerRuntime的 Docker 客户端配置如environment、working_dir构造时UbuntuDockerRuntime会自动为容器注入以下环境变量{ PYTHON_PATH: python_path, PYTHON_EXECUTABLE: python_path, PATH: /usr/local/bin:/usr/bin:/bin, PYTHONUNBUFFERED: 1, }同时将默认工作目录设为/app。这使得容器内的 Python 脚本执行、PYTHONPATH查找与宿主机隔离但行为保持一致。6.2 build() 的生命周期验证、就绪检查与 API 启动build(time_out15)ubuntu_docker_runtime.py在底层DockerRuntime.build()创建并启动容器command: sleep infinity 端口映射之后还会执行一系列 Ubuntu 环境的自检执行python3 --version验证 Python 安装非零退出码直接抛RuntimeError执行apt-get update与apt-get install -y curl确保容器内有健康检查工具以detachTrue后台启动 API 服务python3 /home/api.py并注入PYTHONPATH指向site-packages与PYTHON_EXECUTABLE轮询最多 10 秒用curl http://localhost:8000/docs检查 API 是否返回 2xx就绪即结束轮询。这一步对应文档中初始化 API 服务器的描述——容器内的 CAMEL 运行时 APIapi.py 中基于 FastAPI 构建一旦就绪宿主机侧即可通过http://localhost:port/function_name调用容器内注册的每一个工具函数。6.3 exec_python_file把脚本送进容器执行exec_python_file(local_file_path, container_pathNone, argsNone, envNone, callbackNone)ubuntu_docker_runtime.py是 Ubuntu 变体的关键扩展能力若容器未启动则抛RuntimeError(Container is not running. Call build() first.)本地文件不存在则抛FileNotFoundError默认将脚本拷贝到容器/tmp/文件名通过_create_archive_from_file把文件打成 tar 流再用container.put_archive传入容器这正是 Docker SDK 的标准文件注入方式以[python_path, container_path]构造执行命令并注入PYTHONPATH/PYTHON_EXECUTABLE环境使用streamTrue, demuxTrue流式读取 stdout/stderr可通过callback逐行处理输出否则直接打印到宿主机终端。这正是 runtimes 文档 末尾强调的用法对于动态生成的脚本使用exec_python_file()在容器内运行以获得最大隔离性与安全性。6.4 DockerRuntime 的通用能力UbuntuDockerRuntime从DockerRuntime继承了一整套容器编排能力docker_runtime.pymount(path, mount_path)将本地目录以 bind mount 挂载进容器要求绝对路径目录必须存在copy(source, dest)把本地文件/目录打进 tar 拷贝进容器add(funcs, entrypoint, redirect_stdout, arguments)注册FunctionTool为其生成 HTTP 调用包装器wrapper会向http://localhost:port/function_name发 POST 请求并把工具名写入容器 API 的启动参数——这实现了宿主机调用 容器内执行的远程过程调用模型add_task(task)/exec_run(task)向容器注入启动任务或在运行中的容器内执行命令reset()/stop(remove...)/cleanup()容器生命周期管理ok/wait(timeout)/docs就绪探测请求根路径与 FastAPI/docs文档地址。七、运行效果与常见注意事项7.1 预期运行效果按上述步骤执行后你会看到manage_camel_docker.sh build构建出my-camel:latestubuntu_docker_example.py打印 runtime 初始化日志Initializing UbuntuDockerRuntime with python_path: ...、Environment variables set: ...随后是容器构建、Python 版本检查、apt-get与 curl 安装、API server 启动等日志容器内的角色扮演脚本输出带颜色的系统消息、任务提示词以及 AI User / AI Assistant 的彩色对话文本直至一方终止或出现CAMEL_TASK_DONE。7.2 注意事项API Key 管理ModelScope API Key 与 OpenAI API Key 都应通过环境变量或密钥管理方式注入避免硬编码进仓库代码端口冲突port0时运行时随机分配端口10000–20000避免与宿主机已有服务冲突若需固定端口可显式指定构建上下文manage_camel_docker.sh build会拷贝整个 CAMEL 源码作为构建上下文首次构建耗时较长pip3 install -e .[all]会安装全部可选依赖网络环境需可访问 PyPI示例文件差异README 中提到的test_camel_docker.py与docker_roleplaying.py在当前示例目录中并未随附实际以ubuntu_docker_example.py及 test/runtimes 中的自动化测试为准隔离边界Docker Runtime 提供的是工具函数级与脚本级沙箱对于需要长期运行、分布式调度的场景可参考camel/runtimes中同样导出的RemoteHttpRuntime、DaytonaRuntime等替代方案camel/runtimes/init.py。八、小结本文完整复现了examples/runtimes/ubuntu_docker_runtime示例的四个核心步骤——构建镜像、验证环境、配置 Qwen 模型、运行角色扮演并深入到 Dockerfile、manage_camel_docker.sh、UbuntuDockerRuntime 与 DockerRuntime 的源码层阐明了容器内 FastAPI 工具服务、exec_python_file文件注入执行、以及宿主机 HTTP 调用 ↔ 容器内执行的运行时原理。无论是希望把 CAMEL 智能体隔离在可复现的 Ubuntu 容器中还是需要为动态生成脚本提供安全执行沙箱这一套 Docker Runtime 方案都可以直接作为生产实践的起点。【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考