Gemini 多轮对话与会话记忆实战:messages 怎么拼

首页 / 文章 / 技术教程 / Gemini 多轮对话与会话记忆实战:messages 怎么拼

Itzyk上 Gemini 无状态,多轮靠拼 messages:全量/滑动窗口/摘要三档记忆,流式落库、计费超时与排错清单一次讲清。

作者:Itzyk API · 发布:2026-10-10 · 更新:2026-11-09

一、前言 第一次调通 POST /v1/chat/completions 之后,产品很快会追问:「能不能记住刚才说的?」「用户刷新页面还在吗?」「客服会话要存多久?成本怎么控?」通过Itzyk调用的 Gemini 与 OpenAI 一样,对调用方是 无状态 的:每次请求只根据你传入的 messages 生成回复。所谓「记忆」,是业务侧把历史拼回去,或做摘要后再喂给模型——网关不会替你存会话。 Itzyk API(https://api.itzyk.top)把 Gemini 做成 OpenAI Compatible 接口,多轮写法与 OpenAI 完全一致:按顺序传 system / user / assistant 。网关负责鉴权、限流、按 Token 计费与访问日志;会话存储、窗口裁剪、摘要策略、过期清理由你的应用完成。本文讲清消息协议、内存 Demo、流式落库、三种记忆档位、与本项目计费/超时/限流的关系、产品化会话层建议,以及排错清单。默认模型使用 gemini-3.6-flash 。 适合人群:要做智能客服、助手型 App、内部 Copilot 的前后端工程师;已经会单轮调用、准备上多轮的同学。 --- 二、消息协议、角色与计费直觉 | 角色 | 用途 | |------|------| | system | 人设、边界、输出格式;宜短而稳,建议每轮都带 | | user | 用户输入 | | assistant | 历史模型回复,用于连贯 | Itzyk将请求转发到 Gemini 兼容端点,并按返回 usage 扣费(本仓库 gateway/internal/billing )。 历史越长,每一轮输入 Token 越多,费用越高 ——这是会话设计的第一约束。图像/视频是另计费端点,对话服务请用 Key 模型白名单避免误调。 准备: 在 https://api.itzyk.top/ 创建 Key 并充值。本地: ./start.sh 后使用 http://localhost:9000/v1 ,协议与线上一致。先用 curl 验证单轮,再写会话层。 --- 三、最小多轮:进程内列表(Demo) Python Node.js 进程内列表只适合演示。Web / 多实例 / 多副本部署必须把消息落到 Redis 或数据库,建议键: session:{userId}:{conversationId} ,并记录 updatedAt 便于淘汰。 「模型不记得」十有八九是:没 append assistant、多实例内存不共享、或前端开了新 conversationId——先查会话层,再查模型。 --- 四、流式多轮:先展示,再落库 体验上要边生成边显示; 完整 assistant 文本应在流结束后再写入存储 ,避免半截记忆污染下一轮。 前端若要 SSE,务必经你们 BFF 持有 Key;浏览器暴露 sk- 等于公开钱包。用户控制台 Playground 即是「服务端持 Key 调 Gateway」的参考形态。客户端超时建议 ≥ 60s;用户中止生成时取消上游请求,减少无效计费。 Nginx 场景注意关闭 SSE 缓冲;本仓库生产部署对 Gateway 流式有对应配置实践,自建时可对照 deploy/ 。 --- 五、会话记忆的三种档位 1)全量历史(短会话) 客服开场、表单引导、十轮以内问答:回放全部 messages。实现简单,Token 随轮次线性增长。默认搭配 Flash。 2)滑动窗口(最常用) 只保留最近 N 轮(如 8~12),更早丢掉; system 始终保留 。 在每次 create 前 messages = trim messages 。缺点是早期约束可能丢失,可把关键业务约束写进 system(短)。 3)摘要压缩(长会话) 当估算输入 Token 超过阈值(例如 8k~16k),把旧对话交给模型摘要,再拼最近 K 轮原文: 摘要本身耗 Token,但能换长期连贯。可用 Flash 做日常对话,偶发用 Pro 做高质量摘要(同一 sk- ,只改 model )。阈值可用公开算价接口粗估,或按字符数启发式(中文约 1.5~2 字符/Token,仅供参考)。 --- 六、与计费、超时、限流(本项目视角) Itzyk按请求实际 usage 扣费,金额精度到小数(仓库迁移中有 decimal 16,8 相关实践)。多轮场景下: - 每一轮都重复计历史 Token :第 20 轮通常远贵于第 2 轮——窗口/摘要不是优化项,是成本开关 - 402 :余额不足,提示充值,禁止重试刷接口 - 429 :前端连点或 Agent 多步易触发 Key RPM;加防抖、队列、本地令牌桶 - 401/403 :Key 或模型/IP 权限问题,修配置而非重试 - 超时 :长历史 + 流式,客户端与 BFF 超时建议 ≥ 60s;自建 Gateway 时同步检查上游超时与代理 控制台看用量曲线;管理端可配价格同步、限流与访问日志。排错顺序与 docs/gemini-usage.md 一致:Key → 余额 → 模型权限 → 代理/上游 → 日志。公开 GET /api/public/status 、 /api/public/pricing 可先看平台侧是否正常。 产品上可对「深度模式」单独升 Pro,并把预计费用提示给用户,避免客诉。 --- 七、产品化会话层建议 1. 元数据 :conversationId、userId、model、createdAt、updatedAt、status 2. 消息表 :role、content、token usage、latency ms、error code 3. 软删除与导出 :满足清除/导出个人信息的需求 4. 模型策略 :默认 gemini-3.6-flash ;「深度分析」再升 Pro 5. 安全 :防提示注入(用户试图改写 system)、敏感字段脱敏后存储 6. 幂等 :前端重试勿重复 append 同一条 user;可用 client msg id 7. 可观测 :usage 落库,与Itzyk账单对账;慢请求告警 8. ACL :Key 级模型白名单,会话服务禁止误调文生图/视频高价模型 9. 多租户 :按租户隔离会话键与配额,避免一个租户打满全局 RPM 这些与是否自建本仓库无关——用托管 https://api.itzyk.top 时会话层仍在你侧。自建则可在管理端精细控制 Provider、价格与风控。 --- 八、排错清单与冒烟命令 | 现象 | 排查 | |------|------| | 「不记得」上一句 | 是否 append assistant;多实例是否共享存储;conversationId 是否变了 | | 越聊越慢/越贵 | 未裁剪窗口;上滑动窗口或摘要;检查是否误用 Pro | | 401 | Bearer / Key 错误或过期 | | 402 | 充值;是否误开高价模型 | | 403 | 模型未授权或 IP 白名单 | | 流式中断 | 代理缓冲、超时、客户端取消;用 curl -N 验证 | | 多轮串话 | 会话键冲突;并发写入未加锁 | 建议自动化:CI 里用测试 Key 跑「两轮点名」断言第二轮能答出名字,防止会话拼装回归。 --- 九、小结 多轮对话的本质是: 无状态的 Gemini + 有状态的你的会话层 。经Itzyk调用时,拼好 messages 即可获得与 OpenAI 相同的开发体验;真正要设计的是窗口、摘要、存储、幂等与成本。默认模型用 gemini-3.6-flash ,配合滑动窗口或摘要,能在效果和账单之间取得平衡;流式场景先展示再落库,Key 永远留在服务端。 立刻试试:在 https://api.itzyk.top/ 创建 Key,跑第三节「记住我的名字」两轮示例,再把 messages 迁到 Redis,并加上 trim 。更多 API 与错误码见 https://api.itzyk.top/docs ,价格见 https://api.itzyk.top/pricing 。 --- 十、前后端约定:一份可以落地的 API 建议在你们 BFF 暴露稳定会话接口,而不是让前端直打Itzyk: | 方法 | 路径 | 说明 | |------|------|------| | POST | /api/chat/sessions | 创建会话,返回 conversationId | | GET | /api/chat/sessions/:id/messages | 拉取历史(分页) | | POST | /api/chat/sessions/:id/messages | 发送 user 文本;支持 stream=true | | DELETE | /api/chat/sessions/:id | 结束/软删会话 | 请求体示例: BFF 内部: deep=false → gemini-3.6-flash ; true → Pro。拼装 messages 时应用 trim 或摘要。流式响应可对前端继续用 SSE,或用你们网关统一的 event 格式。Key 只存在 BFF 环境变量,与Itzyk安全模型一致。 鉴权用你们用户体系;再在 BFF 映射到一把或按租户隔离的多把Itzyk Key,便于管理端做用量拆分。 --- 十一、并发与「正在输入」状态 同一 conversationId 上,用户连点发送会导致两轮历史交错。建议: 1. 会话级互斥锁(Redi

本文发布于 Itzyk API(AI API 网关,OpenAI 兼容)。更多: 文章中心 · 开发者文档 · API 服务 · 价格。

llms.txt · sitemap · robots · 文章

京ICP备19037501号-3