把扣子接进自己的产品：API 接入的取舍与三个必须处理的问题
在扣子上把 Bot 搭好之后，很多项目的真实需求是：用户不该知道背后是扣子，他们只是在用你的产品。
这就需要通过 API 把能力接进自己的系统。这篇讲接入时的架构取舍和三个绕不过去的问题。
具体的接口地址、鉴权方式、参数格式请以扣子官方文档为准，会随版本变化。这篇讲架构选择，这部分变化慢得多。
第一条：密钥绝不能出现在前端
这条要放在最前面，因为它是最常见、后果最严重的错误。
前端代码是公开的。 用户打开开发者工具就能看，或者从打包后的文件里直接搜出来。任何写在网页或小程序里的密钥，等于公开发布。
拿到密钥的人能随意调用你的接口——刷你的额度、读你 Bot 能访问的全部内容。
「先这么上，之后再改」是我们见过最多的说法，然后就没有之后了。
判断标准很简单：如果这个页面用户能打开，那里面就不能有密钥。没有例外。
正确做法：前端调你自己的后端，后端持有密钥再去调扣子。
后端代理这一层能顺便解决很多事
加这一层不只是为了藏密钥，它还给了你几个必要的能力：
鉴权。 只有登录用户能用，或者某些角色只能用某些功能。这件事只能在你自己的后端做——扣子不知道你的用户体系。
限流。 防止单个用户刷爆额度，也防止恶意调用。
日志。 谁问了什么、系统答了什么，留在你自己的库里。排查问题、优化 Bot、应对审计都要靠它。
内容过滤。 进去之前和出来之后各加一道，处理敏感内容。
降级。 平台不可用时，你能返回一个友好提示或者转人工，而不是让页面白屏。
主要技术难点是流式响应的透传。 要打字机效果的话，后端不能等结果全部返回再转发，得边收边转。动手前先确认你的后端框架支持流式转发——这是最容易卡住的地方。
会话状态存在哪
多轮对话要记住上下文，这个状态存哪，有三种选择：
存在平台那边。 由扣子维护会话，你只传会话标识。最简单，但你对上下文没有控制权——想在中间插入业务信息、想裁剪历史、想跨设备同步，都不好办。
存在自己库里。 每次调用时由你的后端组装上下文传过去。控制权在手上，代价是要自己处理长度——轮数多了历史越来越长，既费钱又可能超出模型的上下文限制。
混合。 平台维护基础会话，你额外存一份业务侧记录用于分析和审计。这是不少生产项目的实际选择。
判断标准：如果业务需要在对话中注入外部信息（用户的订单状态、权限、历史行为），那必须自己管上下文，否则做不到。
还有一点：会话记录属于业务数据。如果对话涉及客户信息，这些记录的敏感程度等同于业务数据，存储和访问控制要按这个标准来，不能当成普通日志随便放。
托管平台作为依赖，风险要兜住
这是接入扣子和接入自部署方案最本质的区别：扣子是托管服务，你的产品依赖一个不受你控制的外部系统。
要兜的有三件事：
一、不可用时怎么办。 平台维护、网络抖动、限流——这些一定会发生。你的产品应该降级：显示提示、转人工、或退回关键词搜索，而不是整个功能崩掉。开发阶段服务一直是好的，所以这条最容易被忽略。
二、响应慢时怎么办。 检索加生成是有耗时的，前端要有加载状态，超时要有兜底提示，不能一直转圈。
三、平台变更时怎么办。 接口可能调整、功能可能变化、条款可能更新。把对接逻辑收在一个模块里，别让平台的接口细节散落在你代码的各个角落——将来要改或者要换，代价完全不同。
第三条对做长期项目的人尤其重要。
成本要按最坏情况估
接进自己产品之后，调用量不再由你控制——用户想问多少就问多少。
几个会让成本超出预期的因素：
一、上下文越来越长。 多轮对话时，历史会一起传给模型。一个聊了二十轮的会话，单次调用的消耗远大于第一轮。如果不做裁剪，长会话的成本增长很快。
二、知识库检索会把文档片段塞进上下文。 召回数量设得越多，每次消耗越大。这个参数常常被随手调大以求「找得全」，但成本是实打实翻倍的。
三、有人会滥用。 只要接口暴露给用户，就会有人反复调、批量调。限流不是可选项。
实际建议：
- 上线前按「重度用户 × 预期人数」估一个上限，而不是按平均值
- 在自己的后端记录调用量，别等平台账单出来才知道
- 给单用户设频率限制，给整体设日上限，超了就降级或排队
给客户做项目时，这笔账要在方案阶段就说清楚：额度谁付、超了怎么办。不然上线后第一个月的账单会变成一场谈判。
一个战略层面的问题
如果你是要给客户交付的，这里有个必须提前想清楚的事：
扣子是托管服务，不存在「交付一套系统」这回事。
你能做的是帮客户在平台上搭好、用 API 接进他们的产品。但这个东西的运行和数据都在平台方那里，客户随时可以自己接管，你也没法把它变成一个交付物。
对靠项目吃饭的集成商来说，这个差别很实际。 如果需要交付一套能装在甲方服务器上的系统，那要看 Dify 或 FastGPT——它们的许可明确允许作为应用开发平台交付给企业。详细对比见开源 Agent 平台的许可证差别。
还有一条硬约束：数据不能出网的项目，扣子从第一步就出局，因为文档和对话都要经过平台。
什么时候说明该做定制开发
- 为了绕开平台限制，在自己代码里写了大量补丁逻辑
- 需要针对文档结构做深度的检索定制，平台配置项不够
- 需要和业务系统深度联动，做必须机械保证执行的兜底机制
这时候继续加补丁，成本会超过重新实现。判断标准见低代码 Agent 平台的能力边界。
我们做过这类活——有客户要把对话功能嵌进他自己的小程序，我们按他提供的产品资料调模型、调知识库、调工具调用。有类似需求可以聊聊。
同类接法在 Dify 和 FastGPT 上的差异，见 Dify API 接入和 FastGPT API 的四种接法。