企业官网建设流程全解析

EmbodiedGen的Agentic架构设计：gpt_clients如何支持3种LLM后端一键切换

【免费下载链接】EmbodiedGenTowards a Generative 3D World Engine for Embodied Intelligence项目地址: https://gitcode.com/gh_mirrors/em/EmbodiedGen

EmbodiedGen 是一个面向具身智能的开源生成式 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-4o（Azure）、gpt-5.4（Azure）、gemma-4-31b（OpenRouter 免费模型）、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: null

Azure OpenAI：团队共享与托管部署首选

适合有托管资源的团队：填 Azure 的 endpoint、api_key、api_version，model_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_PROVIDER=codex # azure / openai / codex export ENDPOINT=... export API_KEY=... export MODEL_NAME=gpt-5.4 export GPT_TIMEOUT=120

注意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等旧采样参数；旧模型则保持temperature=0.1、max_tokens=500的低随机性配置；
• 🖼️多模态输入：query()的图片参数同时接受文件路径、base64 字符串和 PIL 对象；对接 OpenRouter 时自动把多张图拼成网格（兼容其多图限制）；
• ✅连接自检：check_connection()会发一条 "Hello" 探测，失败时提示检查gpt_config.yaml配置。

完整的后端对比与 Codex 版本要求（验证于 codex-cli 0.146.0）可参考官方文档 gpt_agent.md。

LLM 网关在 EmbodiedGen 流水线中的用武之地

切换后端后，以下 Agentic 能力会自动使用新后端，行为完全一致：

三步验证你的 LLM 后端配置

1. 确认gpt_config.yaml中agent_type指向的后端参数填写完整（Codex 后端需先codex login并执行codex login status确认）；
2. 从仓库根目录跑一条最小请求：

python -c "from embodied_gen.utils.gpt_clients import GPT_CLIENT; print(GPT_CLIENT.query('Reply OK'))"

3. 正常打印模型回复即切换成功。相关单测（含 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_name（Azure 场景它是部署名），错误信息会直接指向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