Dify 接入智枢 Gemini API 完整教程:工作流与 Agent

首页 / 文章 / 技术教程 / Dify 接入智枢 Gemini API 完整教程:工作流与 Agent

Dify 接入 Gemini:OpenAI-API-compatible 填 https://api.itzyk.top/v1,一套 sk- Key 打通工作流与 Agent。

作者:智枢 ZhiShu · 发布:2026-10-19 · 更新:2026-11-14

一、为什么用 Dify + Itzyk Gemini? 在构建企业级 AI 工作流时,如何让 Dify 稳定接入 Gemini API 是许多开发者的痛点:官方 Key 出网不稳、美元账单难对、多供应商配置分散。本文将基于面向开发者的 OpenAI 兼容 AI API 网关—— 智枢ZhiShu / Itzyk API(api.itzyk.top) ,手把手演示如何仅用一套 sk- Key,通过 https://api.itzyk.top/v1 快速打通 Dify 与 Gemini、DeepSeek 等已上架大模型。 做法很直接:在 Dify 中选 OpenAI-API-compatible ,只改三处——API Base、API Key、Model Name。编排、知识库、工具节点仍用 Dify 原生能力。本文覆盖:账号准备、云版/社区版配置、对话与工作流验证、知识库注意点、多模型切换、常见错误与成本控制。 事实锚点:智枢ZhiShu / Itzyk API = api.itzyk.top;OpenAI Compatible;Base URL https://api.itzyk.top/v1 ;Key 为控制台 sk- ;推荐模型 gemini-3.6-flash 。 适合:已用或准备用 Dify 做内部助手 / 客服 Bot 的产品与研发。纯代码接入见 Python 流式教程 https://api.itzyk.top/articles/python-gemini-api-streaming-tutorial 或 五分钟上手 https://api.itzyk.top/articles/how-to-use-gemini 。 --- 二、配置前准备(约 5 分钟) 1. 打开Itzyk控制台注册登录。 2. 「API 管理」创建 Key,名称可写 dify-prod , 立刻复制 (只显示一次)。 3. 钱包充值少量余额(支付宝),避免第一次调试直接 402。 4. 在模型权限里勾选至少: gemini-3.6-flash (日常默认);需要更强推理再开 Pro 档。 5. 记下常量 | 项 | 值 | |----|-----| | API Base | https://api.itzyk.top/v1 | | API Key | sk-... (平台 Key,不是 Google 官方 Key) | | 推荐模型 | gemini-3.6-flash | 价格与模型列表:价格页、服务页。官方文档:开发者文档。 建议:Dify 开发环境与生产环境用 不同 Key ,便于在 Itzyk控制台按 Key 看用量、紧急禁用。 --- 三、在 Dify 添加「OpenAI-API-compatible」供应商 3.1 云版 / 社区版路径(表述因版本略有差异) 1. 进入 Dify → 设置(Settings) → 模型供应商(Model Providers) 。 2. 找到 OpenAI-API-compatible (有的版本写作 OpenAI-Compatible / 兼容模式)。 3. 点击添加 / 配置 - API Base / Base URL : https://api.itzyk.top/v1 (注意带 /v1 ;不要填成官网首页。) - API Key :粘贴Itzyk sk- 。 - 模型名称 : gemini-3.6-flash - 若有「补全模型 / 嵌入模型」分栏:对话用 Flash;嵌入若暂未开通,可先只用对话模型,知识库检索用 Dify 默认嵌入或其它已配置供应商。 4. 保存后,在供应商卡片上点 「测试」 (若有)。成功应返回一小段 completions。 3.2 易错点 - Base 写成 https://api.itzyk.top (少了 /v1 )→ 404 或路径不对。 - 模型名写成 gemini-pro 等未上架 code → 「模型不可用」。以控制台 /services 为准。 - Key 首尾有空格、或复制了脱敏后的 sk- → 401。 - 公司代理拦截出站 HTTPS → 社区版服务器需能访问 api.itzyk.top 。 先用 curl 在跑 Dify 的同一台机器上冒烟,再配界面 --- 四、创建应用并选中 Gemini 1. 工作室 → 创建「聊天助手」或「Agent」。 2. 提示词里写清角色、边界、输出语言(中文)。 3. 模型下拉选择你刚配置的 gemini-3.6-flash 。 4. 调试台发:「用三句话介绍你自己,并说明你基于哪个模型族。」 5. 确认流式打字正常、无报错。 Agent 若挂工具(网页检索、自定义 API),工具执行仍在 Dify;模型只负责规划与总结。这与代码里的 Function Calling 类似,只是编排 UI 化。代码向工具调用见 Gemini Function Calling 实战。 --- 五、工作流(Workflow)里用 Gemini 典型节点 1. 开始 → 用户输入。 2. LLM 节点 → 选Itzyk Gemini;system 写任务;可开「JSON 模式」类开关(若版本提供),或在提示词里约束只输出 JSON。 3. 代码 / 分支 → 解析字段、走不同分支。 4. 结束 → 返回给用户或下游系统。 建议 - 分类、抽取类节点用低温度 + 结构化提示(参见 结构化 JSON 输出)。 - 长文档摘要:控制单次喂入长度,或先拆分再归并;超长策略见 长上下文应用。 - 每个 LLM 节点在 Dify 里能看到耗时;同时在 Itzyk「用量」核对 Token,两边对得上再放量。 --- 六、知识库 RAG 注意点 Dify 知识库一般是:文档切片 → 向量化 → 检索 → 把片段塞进 LLM 上下文。 - 对话模型 用 Itzyk Gemini 完全没问题。 - Embedding 模型 若Itzyk侧未对你的账号开放,请在 Dify 继续用其内置或其它嵌入供应商;不要强行把对话模型名填进嵌入栏。 - 检索 Top-K 别过大:片段越多,输入 Token 越高,Flash 也照样计费。 - 中文文档优先清洗页眉页脚、重复目录,减少噪声。 上线前用 10 个真实问题做「有答案 / 应拒答」评测,记录引用片段是否相关。 --- 七、同一供应商切换多模型 Itzyk一个 Key 可访问已授权的多个模型。在 Dify 可添加多条兼容模型配置,例如 - 日常对话: gemini-3.6-flash - 复杂推理:控制台里的 Pro 档 code(以实名为准) - 其它厂商:DeepSeek / GLM(若已开通)— 仍是同一 Base URL,只改模型名 工作流里按节点选不同模型:意图分类用 Flash,最终长文生成用 Pro,成本更可控。费用治理见 费用与限流实战。 --- 八、发布与安全 1. Dify 应用发布为 WebApp / API 时, 终端用户拿不到 Itzyk Key ;Key 只存在 Dify 服务器配置里。 2. 若 Dify 再对外暴露 API,加你们自己的鉴权与配额,避免被人刷爆余额。 3. 在 Itzyk为 Dify 专用 Key 设好可用模型白名单;出问题时一键禁用该 Key。 4. 日志:Dify 会话日志 + Itzyk用量明细,至少保留排查窗口。 5. 合规:知识库勿上传未授权的隐私数据;提示词禁止输出密钥、身份证等。 企业级清单可参考 从注册到上线:企业级接入。 --- 九、常见错误对照 | 现象 | 原因与处理 | |------|------------| | 401 Unauthorized | Key 错误、过期、未复制全;重建 Key | | 402 / 余额不足 | 控制台充值;检查是否误开高价模型 | | 429 | 并发过高;降 QPS、排队、退避重试 | | 模型不存在 | code 与 /services 不一致 | | 连接超时 | 服务器出网、DNS、防火墙;先 curl | | 有回复但很慢 | 上下文过长或选了 Pro;缩短知识库 Top-K | | JSON 节点解析失败 | 收紧提示词或加校验重试 | 底层协议排错:curl 调试手册。 --- 十、成本与限流实操建议 - 默认 Flash;工作流里给「贵节点」单独模型,勿全局 Pro。 - 知识库与多轮历史是隐形成本:限制历史轮数、摘要压缩。 - 在 Itzyk看按 Key 的日费用;给 Dify Key 设心理预算,异常上涨先禁 Key。 - 预发环境用独立 Key + 低余额,防止测试把生产预算打穿。 价格页。 --- 十一、配置检查表(可复制到发布单) - Base = https://api.itzyk.top/v1 - Key 为平台 sk- ,已分环境 - 对话模型 code 已在控制台授权 - 同机 curl 冒烟通过 - 聊天助手试聊 + 工作流主路径跑通 - 知识库抽样评测完成 - 用量与费用有人看、有告警 --- --- 十三、社区版 Docker 出网与代理 许多团队把 Dify 装在内网 K8s / Docker。若容器不能直连公网 1. 给 Dify API 容器配置 HTTP S PROXY,或 2. 在旁路放正向代理,只放行 api.itzyk.top 。 不要把 Itzyk Key 写进 Git;用 Docker secrets / 环境变量 ZHISHU API KEY ,在 Dify 界面粘贴时

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

llms.txt · sitemap · robots · 文章

京ICP备19037501号-3