Gemini 报 role 只能是 user 或 model

这类问题我又碰上了一次。把多轮对话按 OpenAI 的习惯写成 role=assistant 传给 gemini-1.5-pro，返回 400 INVALID_ARGUMENT，提示 Please use a valid role: user, model，单轮请求却正常。

第一反应是「工具调用消息用了 function 角色，不在允许列表里」，验证下来不成立。

这类报错背后常见的原因有几处，逐个排除就行。Gemini 用 model 表示助手角色，不认 assistant；不同版本 SDK 对角色映射的处理不一致；system 提示词被塞进 contents，角色校验直接失败。

上来先把 assistant 统一映射成 model 再发送

contents=[{'role':'model' if r=='assistant' else 'user','parts':[{'text':t}]} for r,t in turns]

随后用 curl 发最小报文验证角色写法

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro:generateContent?key=$KEY" -H 'Content-Type: application/json' -d '{"contents":[{"role":"user","parts":[{"text":"hi"}]}]}'

系统提示词挪到独立字段

payload['system_instruction'] = {'parts':[{'text':'你是客服'}]}

等前面都确认过，再写入转换函数并加单元测试覆盖三种角色

python -m pytest tests/test_role_map.py -q

同事提醒我看一下最近一次发布，时间点确实对得上。

改完先别撤，确认这几项。请求返回 200，candidates 里有内容，多轮追问能正常延续上下文，日志里不再出现 INVALID_ARGUMENT。

提醒一点。system 提示词不是一条 role=system 的消息，而是独立的 system_instruction 字段，混进 contents 里会直接报角色非法。同一份配置在测试环境跑通，不代表线上没事，两边的默认值经常不一样。