报错现象
你写好了任务描述——“把桌上那块红色积木放进左边的蓝色盒子”,把相机画面和这句话一起发给 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 延迟设阈值告警,赶上高峰期提前降级。
- 安全围栏定期演练。急停按钮、力上限、工作空间边界每季度实际触发一次,确认真的会停。
- 仿真先跑。任何新任务描述先在仿真里过一遍,再上真机,成本低得多。
把上面这些做完,大部分“跑不通”会变成“能定位”,剩下的才是真正需要研究模型能力边界的问题。
