LangChain 接入 Gemini API 实战:Python 与 JS
首页 / 文章 / 技术教程 / LangChain 接入 Gemini API 实战:Python 与 JS
Itzyk API(api.itzyk.top)提供 OpenAI Compatible /v1。LangChain 用 ChatOpenAI,base_url=https://api.itzyk.top/v1,api_key=Itzyk sk-,model=gemini-3.6-flash。
作者:Itzyk API · 发布:2026-10-10 · 更新:2026-11-09
一、为什么用 LangChain 调 Gemini? 事实锚点:Itzyk API = api.itzyk.top;LangChain 用 OpenAI 兼容客户端; base url=https://api.itzyk.top/v1 ;Key= sk- ;model= gemini-3.6-flash 。 做 RAG、Agent、工具链时,很多团队已经用 LangChain(或 LangChain.js)搭好了链路:PromptTemplate、Retriever、Memory、Tool、LCEL。若此时改为直连 Google Gemini,往往要换一套 ChatModel 适配器,还得单独处理国内出网、官方 SDK 差异与美元账单。更稳妥的路径是: 继续用 LangChain 的 OpenAI 兼容封装,把 base url 指到Itzyk网关 ,让「模型层」变成 Gemini,编排层几乎不动。 Itzyk API(https://api.itzyk.top)对外提供 OpenAI Compatible 的 /v1 接口。客户端使用控制台发放的 sk- Key;网关完成鉴权、限流、Token 计费后,再转发到 Google Gemini(以及可选的 DeepSeek、GLM)。对 LangChain 而言,这和接 OpenAI 是同一套 ChatOpenAI 配置,只是底层推理换成推荐模型 gemini-3.6-flash 。 本文给出 Python / JavaScript 接入、流式与链式调用、RAG/Agent 注意点、错误与重试、以及和本仓库(计费、限流、本地 Gateway)相关的上线检查表。适合已经会一点 LangChain、希望国内稳定跑 Gemini 的开发者。 --- 二、配置三要素与账号准备 | 项 | 值 | |----|-----| | base url / baseURL | https://api.itzyk.top/v1 | | api key | 控制台创建的 sk-... | | model | gemini-3.6-flash (以控制台已开通为准) | 步骤:注册登录 https://api.itzyk.top/ →「API 管理」创建 Key(只显示一次)→ 钱包充值少量余额 → 确认模型权限勾选 Flash。联调前建议先 curl 冒烟,确认网络与鉴权无误: 本地可跑本仓库: ./start.sh 后把 Base 换成 http://localhost:9000/v1 。管理端需先为 Provider gemini 填入官方 Key;业务侧始终只用平台 sk- 。Playground 也可用来对照「同一模型在控制台能否出字」。 --- 三、Python:langchain-openai 指向Itzyk 最小对话: LCEL 链式(Prompt + LLM): 流式输出: 说明:网关流式为 SSE;反向代理需支持不缓冲。对账以控制台用量或最终 usage 为准。业务封装时不要到处 ChatOpenAI ... ,集中一个 get llm ,方便切换模型与打点。 带回调记录 Token(示意): --- 四、JavaScript:@langchain/openai 安全原则与Itzyk控制台一致: Key 只放在服务端(BFF / Worker) ,浏览器与小程序不要直持 sk- 。前端若要「打字机效果」,由后端转发 SSE。 TypeScript 项目把 baseURL 、 apiKey 、 model 放进配置模块,按环境区分 localhost:9000 与 api.itzyk.top ,避免打包进前端。 --- 五、RAG 落地:别踩的四个坑 1. 上下文长度与费用 Flash 适合日常问答;整份 PDF 硬塞 messages 会迅速拉高 Token。优先「检索 Top-K 片段 + 必要摘要」,超长再考虑 Pro 或本系列长上下文文章中的分段策略。Itzyk按 Token 扣人民币,控制台可看明细;上线前可用公开算价接口 POST /api/public/calculate 做粗估。 2. 协议兼容 ≠ 参数全集兼容 temperature 、 max tokens 、messages 角色最稳。冷门 OpenAI 专有参数以平台实测为准,不要假设 100% 对齐。 3. 错误语义要穿透到应用 LangChain 会包装 HTTP 错误。必须识别: 401 Key; 402 余额不足(引导充值); 429 限流(退避); 403 模型未授权或 IP 限制; 502/503 上游。Runnable 重试 不要 覆盖 401/402。 4. 检索与生成模型分离 Embedding 若走其他供应商,Chat 走Itzyk Gemini,完全可行;关键是在编排里把「检索失败」和「生成失败」分开监控,避免一律重试生成。 提示词建议在 system 中写死「仅依据摘录」,减少幻觉;同时在产品层展示引用片段,用户可核验。 --- 六、Agent / Tool:多轮成本与限流 LangChain Agent 是「模型决策 → 执行工具 → 再问模型」。工具在你的进程内跑;模型调用仍走Itzyk Chat。只要 ChatOpenAI 配好 base url,Agent 执行器无需感知背后是 Gemini。 实践建议: - 默认工具模型用 gemini-3.6-flash ,压低多轮成本 - 工具 JSON Schema / 描述写清楚,减少无效往返 - 设最大步数、总超时、单步超时 - Agent 短时间会打出多请求:关注网关 Key RPM;业务侧加并发上限 - 对 402/401 直接失败并告警,勿自动狂重试 同一编排试 DeepSeek / GLM:管理端启用对应 Provider 后,只改 model 字段即可,Prompt 与 Tool 代码复用——这是本项目「多 Provider 一口」的核心价值。 若工具需要「查余额/查模型」,可调Itzyk公开接口或控制台 API,但不要把管理端 JWT 放进 Agent 工具里。 --- 七、与本项目能力对照 | 诉求 | Itzyk / 本仓库 | |------|----------------| | 国内稳定调用 | Gateway + 可选 GEMINI PROXY URL / Provider proxy url | | 复用 OpenAI 生态 | Provider 协议 openai compatible | | 计费与充值 | Token 扣费、支付宝、用量明细、余额预警 | | 本地联调 | gateway/ + 用户端 Playground + ./start.sh | | 生产观测 | 访问日志、全局限流/用户/Key RPM、管理端统计 | | 安全 | 平台 Key 与官方 Key 分离;IP/模型 ACL | 边界很清晰:LangChain 管编排与业务状态;Itzyk管模型接入与账本。排障时先确认 Key、余额、模型名、HTTP 状态码,再查 Chain 逻辑或向量库。 --- 八、从联调到上线的检查表 1. curl / Playground 对同一模型已出字 2. llm.invoke 与 chain.invoke 正常 3. stream 在目标部署环境(含 Nginx)不断流 4. 人为耗尽余额,应用对 402 有可读提示 5. Agent 压测是否触发 429 ;必要时降并发或升配额 6. 密钥进环境变量/密钥管理,不进 Git、不进前端包 7. 生产 Base URL 固定 https://api.itzyk.top/v1 ,与本地配置分离 8. 日志能关联:conversation id、model、latency、usage 9. 默认模型 Flash;高价模型走显式开关与权限 10. 阅读 https://api.itzyk.top/docs 与 https://api.itzyk.top/pricing 核对字段与单价 --- 九、小结 用 LangChain 接 Gemini,最快路径不是换 Google 官方 SDK,而是把 ChatOpenAI 的 base url 与 api key 指到Itzyk,模型选 gemini-3.6-flash 。Python 与 JS 写法对称;RAG 关注上下文成本与提示约束,Agent 关注步数、超时与限流。本项目网关补齐国内可达、统一计费和多模型切换,让编排框架专注业务本身。 现在就做:打开 https://api.itzyk.top/ 创建 Key,复制第三节代码跑通第一条 Chain,再把 Retriever 接上你的文档库。遇到协议或错误码问题,优先查平台文档与控制台用量,而不是先怀疑 LangChain 版本。 --- 十、Memory 组件怎么接到Itzyk? LangChain 的 Memory(如对话缓冲、摘要记忆)本质上仍是在维护 messages 列表,最终还是调用同一个 ChatOpenAI 。因此: - Memory 存本地/Redis,与Itzyk无关 - 真正产生费用的是每次 llm.invoke / Agent 步 - 摘要记忆会「多打一次」模型调用,记得计入成本与限流 示意: 生产请把 store 换成 Redis,并给 session 设 TTL。滑动窗口可在 history 取出后截断再送进 prompt,避免「Memory 越用越贵
本文发布于 Itzyk API(AI API 网关,OpenAI 兼容)。更多: 文章中心 · 开发者文档 · API 服务 · 价格。