EmbodiedGen的Agentic架构设计gpt_clients如何支持3种LLM后端一键切换【免费下载链接】EmbodiedGenTowards a Generative 3D World Engine for Embodied Intelligence项目地址: https://gitcode.com/gh_mirrors/em/EmbodiedGenEmbodiedGen 是一个面向具身智能的开源生成式 3D 世界引擎用大语言模型LLM驱动 3D 场景生成、布局规划、资产质量校验等 Agentic 流水线。其 Agentic 架构的关键枢纽是 gpt_clients.py 中的统一 LLM 网关GPTclient只需改一行配置就能在 Azure OpenAI、OpenRouter、Codex CLI 三种 LLM 后端之间一键切换所有业务代码零改动。为什么需要一个统一 LLM 网关EmbodiedGen 的很多能力本质上是让 LLM 看懂 3D 世界理解任务描述、生成场景图、校验资产的几何与外观、把用户口语如黄色的水果映射到场景中的具体物体。这些环节分散在十几个模块里如果每个模块各自写 API 调用换一个模型服务商就要改几十处代码。EmbodiedGen 的解法是单例网关 配置驱动全项目共享一个全局实例GPT_CLIENT定义在embodied_gen/utils/gpt_clients.py末尾各模块直接from embodied_gen.utils.gpt_clients import GPT_CLIENT即可后端的选择完全由embodied_gen/utils/gpt_config.yaml决定agent_type字段指向四组预设配置之一gpt-4oAzure、gpt-5.4Azure、gemma-4-31bOpenRouter 免费模型、codex本地 CLI调用方只需面对一个统一接口query(text_prompt, image_base64, system_role, params)文本和图片多模态输入、重试、超时全部在网关内部处理。也就是说上层 Agentic 逻辑只关心问什么问题LLM 后端关心谁来回答——这正是一键切换能成立的原因。一键切换 LLM 后端只改 gpt_config.yaml在 gpt_config.yaml 中把agent_type改成目标后端的名称即可agent_type: gpt-5.4 # 可选gpt-4o / gpt-5.4 / gemma-4-31b / codex gpt-4o: endpoint: https://xxx.openai.azure.com api_key: xxx api_version: 2025-xx-xx model_name: yfb-gpt-4o gemma-4-31b: endpoint: https://openrouter.ai/api/v1 api_key: sk-or-v1-xxx api_version: null model_name: google/gemma-4-31b-it:free codex: provider: codex endpoint: null api_key: nullAzure OpenAI团队共享与托管部署首选适合有托管资源的团队填 Azure 的 endpoint、api_key、api_versionmodel_name写部署名而非模型名。只要部署支持所选流水线所需的文本/图像输入即可。OpenRouter低成本接入多种开源模型OpenRouter 提供 OpenAI 兼容接口配置里把api_version留空GPTclient会自动走 OpenAI 兼容客户端代码中通过api_version是否为空来区分 azure / openai 两条路径。免费模型如gemma-4-31b-it:free适合本地试跑但使用前需确认所选模型支持图像输入。Codex CLI复用本地登录零密钥配置面向已经登录 Codex 的本地开发者agent_type设为codex后网关不再读取任何 API 密钥而是为每次query()启动一个临时的codex exec只读沙箱子进程复用你已有的codex login会话需先执行codex login。它通过白名单最小化环境变量不会泄漏 EmbodiedGen 的 API 密钥因此只建议在受信任的本地提示词场景使用容器、批量任务或不可信输入请选 Azure 或 OpenRouter。环境变量优先不改文件的运行时覆盖如果不想提交配置文件环境变量具有更高优先级见_resolve_agent_settings的解析逻辑export GPT_PROVIDERcodex # azure / openai / codex export ENDPOINT... export API_KEY... export MODEL_NAMEgpt-5.4 export GPT_TIMEOUT120注意GPT_PROVIDER是一个干净覆盖一旦设置YAML 中选中后端的 endpoint/key/model 全部失效、不被继承认证改由 Codex 本地登录提供。工程细节重试、超时与 GPT-5 参数自适应统一网关还屏蔽了不同后端与模型的差异让切换后端真正无痛自动重试completion_with_backoff基于 tenacity 做指数退避重试最多 5 次直到超时为止BadRequestError不重试⏱️统一超时默认 90 秒可用GPT_TIMEOUT调整GPT-5 自适应自动识别模型名中的gpt-5/gpt5改用max_completion_tokens默认 8192并剔除 GPT-5 不接受的temperature、top_p等旧采样参数旧模型则保持temperature0.1、max_tokens500的低随机性配置️多模态输入query()的图片参数同时接受文件路径、base64 字符串和 PIL 对象对接 OpenRouter 时自动把多张图拼成网格兼容其多图限制✅连接自检check_connection()会发一条 Hello 探测失败时提示检查gpt_config.yaml配置。完整的后端对比与 Codex 版本要求验证于 codex-cli 0.146.0可参考官方文档 gpt_agent.md。LLM 网关在 EmbodiedGen 流水线中的用武之地切换后端后以下 Agentic 能力会自动使用新后端行为完全一致能力位置LLM 做什么资产质量校验embodied_gen/validators/quality_checkers.py分割校验、几何/外观检查、SemanticMatcher语义匹配场景实例解析embodied_gen/utils/llm_resolve.py把黄色的水果映射到场景中的banana_0013D 资产与场景生成embodied_gen/scripts/textto3d.py、imageto3d.py、gen_scene3d.py、gen_layout.py理解任务、生成场景图与布局空间计算技能embodied_gen/skills/spatial-computing/平面图解析与轨迹规划三步验证你的 LLM 后端配置确认gpt_config.yaml中agent_type指向的后端参数填写完整Codex 后端需先codex login并执行codex login status确认从仓库根目录跑一条最小请求python -c from embodied_gen.utils.gpt_clients import GPT_CLIENT; print(GPT_CLIENT.query(Reply OK))正常打印模型回复即切换成功。相关单测含 Codex 子进程行为、GPT-5 参数过滤见 test_gpt_client.py可用pytest tests/test_unit/test_gpt_client.py回归验证。常见问题排查清单 找不到 Codex CLI确认codex在PATH中且版本支持--ephemeral、--ignore-user-config等参数API 后端连不上依次核对 endpoint、api_key、api_version 与 model_nameAzure 场景它是部署名错误信息会直接指向gpt_config.yaml多张图片报错确认所选模型支持视觉输入或改用支持多模态的部署想临时换模型不改配置export MODEL_NAME...即可覆盖GPT_PROVIDER则用于整体切换后端。总结EmbodiedGen 的 Agentic 架构把 LLM 依赖收敛到GPTclient这一个网关里配置驱动 环境变量覆盖 多模态/重试/超时自适应让换模型从改代码降级为改一行agent_type。无论你用 Azure 托管、OpenRouter 免费额度还是本地 Codex 登录都能以同一套 Agentic 流水线一键跑通 3D 世界生成。【免费下载链接】EmbodiedGenTowards a Generative 3D World Engine for Embodied Intelligence项目地址: https://gitcode.com/gh_mirrors/em/EmbodiedGen创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考