用 Dify 的 API 把能力接进自己的系统：密钥、流式和会话状态
很多项目真正需要的形态是：用户不知道背后有 Dify，他们只是在用你的产品。
Dify 提供 API，让它作为能力层被自己的系统调用。但「接进来」有几种接法，代价差别很大，选错了要么返工，要么留下安全隐患。
具体的接口路径、鉴权方式和参数请以 Dify 官方文档为准，会随版本变化。这篇讲架构选择。
先说一个绝对不能踩的坑
API 密钥绝不能出现在前端代码里。
这条要单独拎出来说，因为它是最常见、后果最严重的错误。
前端代码是公开的。用户打开开发者工具就能看，或者从打包后的文件里搜出来。任何写在前端的密钥，等于公开发布。
拿到密钥的人能做什么：随意调用你的接口刷额度、读取你知识库里的全部内容、甚至用你的额度去干别的事。
「先这么上，之后再改」——这是我们见过最多的说法，然后就没有之后了。
判断标准很简单：如果这个页面用户能打开，那里面就不能有密钥。没有例外。
四种接法
一、前端直连
前端直接调 Dify 接口。
只适合内部验证。 改动最小，想快速看看效果时可以用。但因为密钥暴露的问题，绝不能上生产。
二、后端代理（大多数项目的答案）
前端调你自己的后端，后端再调 Dify。
这是绝大多数生产项目该用的方式。 它解决的不只是密钥：
- 密钥留在服务端，前端接触不到
- 能做鉴权：只有登录用户能问，或者某些角色只能问某些内容。这件事只能在你自己的后端做——Dify 不知道你的用户体系
- 能做限流：防止单个用户刷爆额度
- 能记日志：谁问了什么、系统答了什么，留在自己的库里，排查和优化都要靠它，也常常是甲方的审计要求
- 能做内容过滤：进去之前和出来之后各加一道
主要技术难点是流式响应的透传。 如果要打字机效果，后端不能等结果全部返回再转发，得边收边转。动手前先确认你的后端框架支持流式转发——这是这条路最容易卡住的地方，有些老框架处理起来相当别扭。
三、事件驱动
不是实时对话，而是由事件触发处理：新工单进来自动匹配相似案例、新文档上传自动生成摘要。
优点：没有响应时间压力，可以从容重试；能批量处理；不用处理流式响应，实现简单得多。
要注意：失败要能重试且不重复处理，结果要有地方落库。
四、只借检索，生成自己做
只用知识库的检索能力，拿到文档片段之后，生成环节用自己选的模型、自己写的提示词。
什么时候值得这么做：
- 对输出格式、语气有特殊要求
- 想在不同场景用不同模型
- 已经有自己的对话逻辑，只缺检索
代价：要自己处理提示词组装、上下文长度控制、模型调用。工作量明显变大，换来完全的控制权。
判断标准：如果你一直在跟平台的生成逻辑较劲——改提示词改不到想要的效果——那说明该走这条路了。
会话状态存在哪：一个要提前定的架构问题
多轮对话要记住上下文。这个状态存哪，三种选择：
存在 Dify 那边。 由平台维护会话，你只传会话标识。最简单，但你对上下文没有控制权——想在中间插入业务信息、想裁剪历史、想跨设备同步，都不好办。
存在自己库里。 每次调用时由你的后端组装完整上下文传过去。控制权完全在手上，代价是要自己处理上下文长度——轮数多了历史会越来越长，既费钱又可能超出模型的上下文限制，需要裁剪或摘要策略。
混合。 平台维护基础会话，你额外存一份业务侧记录用于分析和审计。这是不少生产项目的实际选择。
判断标准：如果业务需要在对话中注入外部信息（用户的订单状态、权限、历史行为），那必须自己管上下文，否则做不到。
还有一点容易被忽略：会话记录属于业务数据。如果对话涉及客户信息、订单细节，那这些记录的敏感程度等同于业务数据本身，存储和访问控制都要按这个标准来，不能当成「日志」随便放。
接进去之后还要处理三件事
一、答不上来怎么办。 检索不到相关内容时，应该明确说不知道并给出下一步，而不是硬答。这个兜底逻辑写在你的后端，别指望模型自觉。
二、响应慢了怎么办。 检索加生成是有耗时的，前端要有加载状态，超时要有兜底提示。
三、服务不可用怎么办。 你依赖的是一个外部服务（哪怕是自己部署的）。它挂了的时候，你的产品应该降级——显示提示、转人工、或退回关键词搜索，而不是整个功能白屏。
第三条最常被忽略，因为开发阶段服务一直是好的。但上线后这是迟早会遇到的情况。
密钥本身也要管起来
把密钥放到服务端只是第一步，它本身还需要管理。
不要写死在代码里。 代码会进版本库，进了版本库就很难彻底删干净——即使后来删掉，历史记录里还在。用环境变量或配置管理，配置文件加进忽略列表。
要能换。 密钥可能泄露、可能需要轮换、给客户部署时可能一个客户一个。如果换密钥需要改代码重新发版，那实际上就没人会换。
给客户部署时要说清楚归属。 这个密钥是谁的账号、额度谁付、用完了谁充、过期了谁管——这几个问题不在合同里写明，一定会扯皮。甲方觉得系统是你交付的所以你该管，你觉得调用费用本来就该甲方出。
什么时候说明该做定制开发
如果你在做这些事，说明已经在平台边界上了：
- 为绕开平台限制，在自己代码里写了大量补丁逻辑
- 检索效果需要针对文档结构深度调优，而平台配置项不够
- 需要把对话能力和业务系统深度联动，做必须机械保证执行的兜底机制
这时候继续加补丁，成本会超过重新实现。判断标准见低代码 Agent 平台的能力边界。
我们做过这类活——把对话功能嵌进客户自己的小程序，按其产品资料调模型、调知识库、调工具调用；也为需要安全兜底的场景做过关键词识别、强制转人工和人工后台。卡在类似地方的话，可以聊聊。
同类接法在 FastGPT 上的差异见 FastGPT API 接入的四种接法。