跳到主内容
快讯直播
AI智模界
教程

Gemini Robotics 2.5 接入报错排查实战

报错现象

你写好了任务描述——“把桌上那块红色积木放进左边的蓝色盒子”,把相机画面和这句话一起发给 Gemini Robotics 2.5,期待拿回一串动作序列,交给机械臂执行。结果在下面几种情况里卡住:

1. 认证类:HTTP 401 或 403,返回体形如

{"error":{"code":401,"message":"API key not valid. Please pass a valid API key.","status":"UNAUTHENTICATED"}}

所有请求无一成功,换成浏览器里复制来的 key 也不管用。

2. 请求结构类:HTTP 400 INVALID_ARGUMENT,message 里提示内容字段缺失或不合法,例如图像数据传了 base64 却少 mimeType,或者工具声明里的 JSON Schema 写错一个括号。

3. 限流类:HTTP 429 RESOURCE_EXHAUSTED,或客户端出现 ReadTimeout、ConnectionResetError,高峰期尤其明显。

4. 解析类:模型确实回话了,但内容不是干净 JSON。常见两种形态——一种是外面包了 ``` `json `` 围栏,直接 json.loads 报 json.decoder.JSONDecodeError: Expecting value: line 1 column 1;另一种是 JSON 在半截被截断,报 Unterminated string starting at`。

5. 动作层类:JSON 解析成功了,交给机械臂驱动时抛出 JointLimitError、SafetyViolation: target pose out of workspace、TimeoutError: wait for motion complete,或者干脆关节索引对不上。

6. 长程漂移:前三步都正常,第四步开始重复同一个动作、突然回 home、或者把“10 厘米”执行成“10 弧度”。

影响范围不一样:1~3 是链路层,全部任务都失败;4 是解析层,时好时坏;5~6 只影响特定任务,但最难查,因为它看起来“成功了”。

可能原因

按出现概率从高到低:

1. API key 没有真正注入到运行进程。终端里 export 过,但服务跑在 Docker、systemd 或 CI 里,环境变量根本没带进去。

2. 请求体结构不合法。多模态内容的组织方式、图像编码、工具或响应 Schema 的字段名写错。

3. 没有做输出结构约束。放任模型自由发挥,拿回来的是自然语言,或者输出被 token 上限截断。

4. 模型层与动作层没有对齐“接口约定”。动作名对不上驱动支持的原语,单位混用(度/弧度、厘米/米),坐标系不一致(相机系 vs 基座系)。

5. 长程任务缺少状态回传。只在开头给一次观测,后面让模型“闭眼”规划十几步,误差累积后必然漂移。

6. 安全围栏阈值设得太紧。工作空间边界或速度上限卡在实际可达范围之内,动作被拦下。

7. 重试策略缺失或粗暴。429/5xx 直接抛错,或者对所有错误无脑重试,导致配额雪崩。

8. 仿真与真机环境差异。标定偏移、夹爪零点、相机外参在仿真里是对的,真机上偏了几厘米。

逐条排查与解决

第 1 条:key 是否真的进了进程

先确认变量存在但不要打印明文:

```bash

echo "长度=${#GEMINI_API_KEY}"

```

长度为 0 就是没注入。分别检查各运行形态:

```bash

Docker

docker exec -it <容器名> env | grep -c GEMINI_API_KEY

systemd

systemctl show <服务名> -p Environment

当前 shell 的子进程链路

bash -lc 'echo ${#GEMINI_API_KEY}'

```

然后用最小请求打通鉴权,BASE_URL 与模型 ID 以官方文档当前版本为准:

```bash

curl -sS -o /tmp/resp.json -w '%{http_code}\n' \

-H "x-goog-api-key: ${GEMINI_API_KEY}" \

-H "Content-Type: application/json" \

-X POST "${GEMINI_BASE_URL}/models/${MODEL_ID}:generateContent" \

-d '{"contents":[{"parts":[{"text":"ping"}]}]}'

```

返回 200 说明链路通,问题在后面几条;仍返回 401 就检查 key 是否属于当前项目、是否被限制来源,以及账号权限是否已开通对应能力。

第 2 条:请求体逐层加字段

先只发纯文本,通过后再加图片,再加工具声明。这样能一步定位到哪一层出错。图像编码注意平台差异:

```bash

base64 -w0 frame.jpg > /tmp/frame.b64 # Linux

base64 -i frame.jpg -o /tmp/frame.b64 # macOS

```

用 jq 做结构体检,能提前发现漏字段:

```bash

jq -e '.contents[0].parts | length' request.json

jq -e '.contents[0].parts[] | select(.inlineData) | .inlineData.mimeType' request.json

```

判断标准很直接:curl 直接发 request.json 报 400,但纯文本体报 200,就是内容构造问题,与鉴权无关。

第 3 条:强制结构化输出并做二次校验

两件事一起做。第一,请求里声明响应 Schema,把动作序列的形状固定下来;第二,客户端拿到结果后仍要用 jsonschema 校验一遍,不要信任“模型说它给了 JSON”。

一个最小可用的动作 Schema 示例:

```json

{

"type": "object",

"required": ["steps"],

"properties": {

"steps": {

"type": "array",

"maxItems": 12,

"items": {

"type": "object",

"required": ["action", "params"],

"properties": {

"action": {"enum": ["move_to", "grip", "release", "wait", "home"]},

"params": {"type": "object"}

}

}

}

}

}

```

兜住围栏和截断:

```python

import json, re

from jsonschema import validate

def parse_steps(text, schema):

m = re.search(r"\{.*\}", text, re.S)

if not m:

raise ValueError("响应中没有 JSON 片段")

data = json.loads(m.group(0)) # 截断会在这里抛错

validate(instance=data, schema=schema) # 结构不对会在这里抛错

return data["steps"]

```

如果 json.loads 反复在同一个位置截断,优先怀疑输出 token 上限不够,把上限调高,并要求模型把 steps 数量控制在合理范围。另外检查返回里的结束原因字段,若因长度被截,重试也是白搭。

第 4 条:把单位、坐标系、动作名统一到一层

在模型输出与驱动之间插一层 normalize(),做三件事:动作白名单过滤、单位统一(内部一律米、弧度、秒)、坐标系转换。给个骨架:

```python

ALLOWED = {"move_to", "grip", "release", "wait", "home"}

def normalize(step, limits):

if step["action"] not in ALLOWED:

raise ValueError(f"未知动作 {step['action']}")

p = step.get("params", {})

if "angle_deg" in p: # 度转弧度

p["angle_rad"] = p.pop("angle_deg") * 3.141592653589793 / 180

if "distance_cm" in p: # 厘米转米

p["distance_m"] = p.pop("distance_cm") / 100

for k, (lo, hi) in limits.items(): # 越界直接拒绝,不发给驱动

if k in p and not (lo <= p[k] <= hi):

raise ValueError(f"{k}={p[k]} 超出 [{lo}, {hi}]")

return step

```

判断是不是这条原因:把 normalize 单独跑一遍模型返回的历史数据,抛错就说明约定没对齐;同时给驱动层写单元测试,把每个动作原语都走一次 dry-run。

第 5 条:给长程任务加状态回传与卡死检测

不要一次规划十几步然后闷头执行。推荐“三明治”结构:模型出 3~5 步子计划 → 执行 → 回传末端位姿和一张新图 → 再出下一段。同时做卡死检测:

```python

last = None

same_count = 0

for step in steps:

if step == last:

same_count += 1

if same_count >= 2:

raise RuntimeError("连续重复同一动作,判定卡死,触发重规划")

else:

same_count = 0

last = step

robot.execute(step)

```

再加一个总步数上限,超过就停,别让机器人在原地反复试。

第 6 条:围栏分三层,别都堆在一处

请求前做一次工作空间裁剪(在 normalize 里做);执行中做速度、力矩上限与看门狗定时器;异常时走急停。判断是不是围栏误触发,看日志里 SafetyViolation 的目标点坐标是否只是略微越界。把边界值做成配置项,先放宽 5% 跑一次 dry-run,确认是阈值问题而不是真的越界。

第 7 条:只对可重试错误做退避

```python

import random, time

def call_with_retry(fn, retries=5):

for i in range(retries):

try:

return fn()

except TransientError: # 仅 429、5xx、超时

if i == retries - 1:

raise

time.sleep(min(2 ** i, 30) * (0.5 + random.random()))

```

400 系列里的参数错误重试一万次也不会成功,反而浪费配额。

第 8 条:仿真回归与标定核对

把同一批任务描述在仿真里跑一遍,对比真机轨迹的末端误差。误差稳定偏一个方向,多半是相机外参或基座标定问题,重跑标定流程,不要在这里靠改 prompt 解决。

都不管用时的兜底方案

1. 降级到示教回放。人工拖拽录一条成功轨迹存成文件,出问题时回放这条轨迹,保证产线先能跑。

2. 影子模式。所有动作只生成不执行,写成日志,先确认动作序列本身是否合理,把“模型错”和“执行错”分开。

3. 切成单步确认模式。每一步动作打印出来,人工点确认再下发,把长程问题降维成单步问题。

4. 换调用方式定位边界。SDK 报错就用 curl 直连 REST 再试一次,能区分是封装层的问题还是服务侧的问题。

5. 打包可复现材料。把任务描述原文、请求体、模型原始返回、解析结果、执行日志、时间戳和 trace id 存成一个目录,有了这份东西再去找支持渠道,效率完全不同。

6. 换路径绕开。把一句话任务拆成两三句更窄的指令分别调用,先让流程跑通,再回头优化长程能力。

如何预防再次发生

  • 把 Schema 当约定。动作 Schema 放进代码仓库,CI 里跑 jsonschema 校验和动作白名单测试,模型换个说法也跑不出去。
  • 分层解耦。任务层(自然语言 → 子目标)、技能层(子目标 → 动作原语)、驱动层(原语 → 关节指令)分开,出问题能一眼定位到层。
  • 结构化日志。每条任务记录:请求体、模型原始返回、解析后动作、执行结果、耗时、trace id。事后排查不用猜。
  • 回归集常备。攒 20~50 条典型任务描述,每次改 prompt、换模型、调参数都跑一遍,看通过率而不是看单次效果。
  • 版本集中配置。模型 ID、端点、参数写在一个配置文件里,切换走灰度,不要散落在代码各处。
  • 配额与延迟监控。对 429 比例、P95 延迟设阈值告警,赶上高峰期提前降级。
  • 安全围栏定期演练。急停按钮、力上限、工作空间边界每季度实际触发一次,确认真的会停。
  • 仿真先跑。任何新任务描述先在仿真里过一遍,再上真机,成本低得多。

把上面这些做完,大部分“跑不通”会变成“能定位”,剩下的才是真正需要研究模型能力边界的问题。

AI 生成本文由 AI 基于公开信息自动生成,仅供参考。