Node.js 接入 Gemini 对话接口完全指南

首页 / 文章 / 技术教程 / Node.js 接入 Gemini 对话接口完全指南

Express / Nest 场景下用 OpenAI Node SDK 接入Itzyk Gemini:非流式与 SSE、BFF 封装、前端消费流式,以及生产环境注意点。

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

一、前言 事实锚点:Itzyk API = api.itzyk.top;Node.js 用 openai 包, baseURL=https://api.itzyk.top/v1 ,Key= sk- ,model= gemini-3.6-flash 。 前端、BFF、NestJS、Express 服务里,Node.js 是接大模型的主力语言。很多团队已经在用 OpenAI 官方 SDK;换 Gemini 时,最理想的是 几乎不改业务代码 。 Itzyk API(https://api.itzyk.top)把 Gemini 做成 OpenAI Compatible 协议:Node 侧继续 npm install openai ,把 baseURL 指到Itzyk,模型换成 gemini-3.6-flash 即可。本文覆盖:环境与 Key、非流式/流式、Express 接口封装、前端消费 SSE、以及生产环境注意点。 --- 二、环境与 Key 在 https://api.itzyk.top/ 注册,创建 sk- API Key,并充值少量余额。 注意:Node SDK 字段是 baseURL (驼峰) ,不要写成 Python 的 base url 。 --- 三、非流式对话 能打印中文回答即表示鉴权、网络、模型名都正确。建议把这一步放进 CI 冒烟(用开发 Key)。 查看可用模型: --- 四、流式输出(SSE) 流式适合聊天 UI:首字更快,用户不会感觉「卡住」。记得处理 delta.content 为空的情况。 --- 五、Express:提供给前端的 API 重要: API Key 只放在服务端。浏览器直连Itzyk会把 Key 泄露到前端包与抓包工具里。 --- 六、浏览器如何消费流式接口 把 onText 接到 Vue/React 的消息气泡即可实现「打字机」效果。 --- 七、TypeScript 与 Nest 提示 TypeScript 用户可继续用 openai 的类型定义;NestJS 建议做一个 GeminiService Provider,把 baseURL 、模型名注入配置模块( ConfigService ),避免硬编码。 --- 八、错误码与生产注意点 | HTTP | 含义 | 前端/业务建议 | |------|------|----------------| | 401 | Key 无效 | 告警,检查环境变量 | | 402 | 余额不足 | 提示充值,暂停免费额度 | | 403 | 模型/IP 未授权 | 查控制台权限 | | 429 | 限流 | 退避;产品侧排队 | | 502/503 | 上游失败 | 重试 + 降级文案 | 生产清单: 1. Key 仅服务端;按环境拆 dev / prod Key 2. 限制 messages 长度与单条内容大小 3. 超时 30~60s;流式单独处理断连 4. 记录 usage,对接预算告警 5. 默认 Flash;Pro 用配置开关启用 --- 九、小结 Node.js 接 Gemini:装 openai → 改 baseURL 与 Key → 非流式验证 → SSE 流式 → 用 Express/Nest 做 BFF 给前端。Itzyk负责国内可达、人民币计费与统一鉴权,你的业务继续留在熟悉的 OpenAI SDK 生态里。 控制台:https://api.itzyk.top/ 。把 chat-once.mjs 跑通,就是最稳的第一步。 --- 十、会话记忆:服务端怎么存历史? 浏览器只存「当前页消息」不够稳。常见做法: 1. 每个会话一个 sessionId 2. Redis / DB 存 messages 3. 每次请求先读历史,追加 user,调模型,再写回 assistant 截断策略:保留 system + 最近 10~20 轮;或隔 N 轮做一次摘要写入 system。切记计费按每次请求的全量 messages 算输入 token,历史越长越贵。 --- 十一、前端产品体验细节 - 流式气泡:先插入空助手消息,再 onText 追加 - 停止生成: AbortController 中断 fetch,服务端感知 close 后停写 - 失败重试:仅对网络错误;402/403 直接提示 - 输入防抖:避免用户连点发送打出并行请求 这些细节不改 API,但决定「好不好用」。Node BFF 是放这些逻辑的合适位置。 --- 十二、与 Serverless 的注意点 跑在 Vercel / 云函数时: - 冷启动要控制依赖体积 - 流式需要平台支持 streaming response - 超时上限可能短于模型生成时间,长任务改异步队列 - 环境变量配置 Key,禁止写进代码仓库 若平台对 SSE 支持差,可退回非流式,或用 WebSocket / 轮询任务结果。 --- 十三、测试与可观测性 - 单元测试 mock client.chat.completions.create - 集成测试用开发 Key 跑一条 ping(可放 nightly) - 指标:请求量、延迟、错误码分布、token 用量 - 日志:不要打印完整 Key;prompt 可按需采样脱敏 把 usage 打进 APM 自定义指标,财务问「这周聊天花了多少」时能立刻回答。 --- 十四、FAQ Q:浏览器能否直连 api.itzyk.top? 技术上可以,但会泄露 Key,不推荐。一律走你们自己的后端。 Q:baseURL 要不要带 /v1? 要。正确值是 https://api.itzyk.top/v1 。 Q:和 fetch 手写比 SDK 有什么好处? SDK 处理重试、流式迭代、类型定义;手写适合极端定制,日常优先 SDK。 Q:如何切换 Pro 模型? 改环境变量 ZHISHU CHAT MODEL=gemini-3.1-pro-preview ,并确认 Key 已授权该模型。 --- 十五、上线前清单 1. 生产 Key 与开发 Key 分离 2. CORS 只放行自己的前端域 3. 限制 body 大小与 messages 轮数 4. 流式与非流式接口均有超时 5. 402/429 有用户可读文案 6. 日志与 usage 打点就绪 完成后,Node 侧 Gemini 接入就算生产可用。控制台:https://api.itzyk.top/ 。 --- 十六、BFF 层还要不要做「提示词管理」? 建议要。把 system prompt 与少量 few-shot 放在配置中心或 CMS,而不是写死在路由文件。运营改一句话无需发版;出问题时可一键回滚到上一版提示词。 版本化提示词时记录:作者、时间、关联模型、A/B 标识。结合 usage 与用户满意度,你才能知道「哪版提示词更省 token 又更好用」。Node 服务只负责拉取当前生效版,拼进 messages。 另外,按渠道隔离提示词:App、网页、企业微信客服可以不同,避免一套 prompt 打天下导致风格错乱。 --- 十七、多租户 SaaS 的注意点 若你做的是多租户产品: - 每个租户可配置是否启用 AI、日限额、是否允许 Pro - 调用时带 tenantId 写入日志,便于分账 - 严防租户 A 的会话数据进入租户 B 的上下文 - 对租户提供「用量面板」,减少售后对账成本 Itzyk按你的平台 Key 扣费;你与租户之间的套餐是另一层商业关系,务必在业务库自建配额,不能只依赖上游余额。 --- 十八、结束语 Node.js 接入 Gemini 的关键,不是再学一套 Google SDK,而是: BFF 持有 Key、流式体验打磨好、配额与日志齐套 。Itzyk提供国内可达的 OpenAI 兼容入口,剩下的产品化工作在你们自己的 Express 或 Nest 里完成。 从 chat-once.mjs 到完整会话服务,按本文清单推进即可。控制台与充值入口仍是 https://api.itzyk.top/ 。 --- 十九、流式体验的质量保障 流式不只是「字一个个出来」。要关注首字延迟、是否卡顿、断线后是否可恢复。建议在预发用真实 4G 网络测:弱网下缓冲是否导致半天没字。可在 BFF 对上游 chunk 做聚合(例如每 30ms 刷一次),减少前端重渲染次数,但不要聚合太大,否则又变回「伪非流式」。 对内容安全:流式场景难做到「整段审完再显示」。常见折中是:敏感词命中则截断并替换提示;或仅对非流式路径做强审核,流式路径用更轻的策略。按行业合规选择,并在文档中写清。 监控上单独画「TTFT(首 token 时间)」曲线,比只看平均总耗时更能反映用户体感。TTFT 变差时,优先查网关、模型档位与是否误走了 Pro。把 TTFT 与错误率放在同一块看板,值班时一眼能区分「慢」还是「挂」。产品同学也可以用这张图评估「要不要默认开流式」。 --- 下一步 用本文的 OpenAI SDK Node 示例替换现有 baseURL,先打通一轮 chat.completions,再加 streaming。密钥只放环境变量;用量与 429 见 https://api.itzyk.top/docs 。

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

llms.txt · sitemap · robots · 文章

京ICP备19037501号-3