把 Dify 接进业务系统:从一个订单助手 Demo 说起

最近我把一个订单助手拆成了一个 Dify 接入 Demo。学习的重点不是堆 API 名称,而是把一条业务请求从用户入口、模型编排、知识检索,一直追到业务服务,并明确每一步由谁负责。

项目代码和完整配置步骤:github.com/ydpzg/dify_demo。示例只使用合成订单,退款端点会校验参数后返回 SIMULATED,不会修改真实数据。

我是怎么学的:从一个具体业务问题开始

我先把问题限定为“用户问订单状态,必要时发起退款申请”。这让学习过程有了可检查的结果:能否拿到正确订单、能否解释规则、工具调用是否受控,以及遇到需要审批的操作时能否停下来等人处理。

接着把系统拆成四段:业务前端负责交互;自己的后端负责登录态、租户和 Dify App Key;Dify 负责 Agent、知识库与工作流编排;业务 API 负责返回真实数据并执行最终校验。Demo 用 Python 标准库直接调用 Dify API,没有依赖 Dify SDK,因此每个请求、身份字段和流式事件都能看到。

一次请求如何经过各层系统
  1. 01 / 入口Web / App用户提问 · 查看结果
  2. 02 / 业务边界业务后端认证 · 权限 · 会话
  3. 03 / 智能编排Dify App API检索知识 · 组织步骤 · 选择工具
  4. 04 / 数据与执行业务 API查询订单 · 校验并执行获批动作

App Key 保存在业务后端;业务 API 始终负责最终授权和数据校验。

随后我按能力逐步搭建:先用 Chatflow 连知识库做问答,再通过 Agent 调订单查询工具;接着试 Workflow 的固定步骤和流式事件;最后把 Human Input 加在高风险步骤前。这样可以分清“模型生成了建议”和“业务系统真的执行了操作”。

先把 Dify 应用配置好

  1. 在 Dify Workspace 配置可用的模型提供商。
  2. 需要企业知识问答时,创建知识库、上传资料,等索引完成后在 Chatflow 中添加知识检索节点并发布。
  3. 需要自主选择工具时,创建 Agent 并加入工具;需要固定业务步骤时,创建 Workflow,声明输入和输出后发布。
  4. 在每个应用的 API Access 页面创建 App API Key。知识库服务使用单独的 Knowledge Service API Key,不要混用。

把项目克隆到本地后,在仓库目录复制 .env.example 为 .env,再填入相应密钥和知识库 ID。执行 python3 dify_demo.py info 可以检查 Chat 应用密钥;不要把真实密钥放进浏览器代码或提交到仓库。

git clone https://github.com/ydpzg/dify_demo.git
cd dify_demo
cp .env.example .env
python3 dify_demo.py info

Dify Cloud 使用官方 API 地址;自托管部署则使用实例显示的 API Base URL。具体接口和授权方式以所用实例的 API 文档为准。

模型供应商的凭证边界也要在配置阶段先想清楚。如果直接在 Dify Model Provider 中填写 OpenAI、DeepSeek 等供应商 Key,Dify 会保存并使用该 Key。它不会自动传给你的业务 API,但已经进入 Dify Workspace 的凭证管理范围。

如果不希望原始供应商 Key 进入 Dify,可以把 Provider 的 Base URL 或自定义端点指向自己的模型网关。此时 Dify 只保存网关地址和网关凭证,网关再使用原始供应商 Key 调用上游。模型网关至少要兼容普通响应、SSE 流式响应、工具调用、多模态字段和错误码;同时要分别评估 Dify 与网关的日志、追踪、数据保留和权限。

三种常见接法:Chatflow、Agent 和 Workflow

Chatflow + 知识库适合让用户用自然语言查询制度、产品手册和内部 FAQ。文档先经过切分与索引,检索到的片段再进入回答流程。Demo 的 chat 命令调用已发布的 Chat/Chatflow;retrieve 命令则直接检查经典知识库命中的片段,便于调试切分和召回。

按业务步骤选择应用形态
知识问答Chatflow
用户问题知识检索有依据的回答
动态选工具Agent
用户目标判断与选工具汇总结果
固定业务步骤Workflow
输入校验业务节点结果 / 审批
python3 dify_demo.py chat "公司的退款政策是什么?"
python3 dify_demo.py retrieve "退款到账需要多久?"

Agent适合需要根据上下文选择一个或多个工具的场景,例如先查订单,再根据订单状态解释后续步骤。Demo 的 Agent API 用 SSE 流式接收回复和工具事件,并可通过 conversation_id 延续会话。

python3 dify_demo.py agent "查询 order-1001 状态,并说明下一步"
python3 dify_demo.py agent "继续说明退款条件" --conversation-id YOUR_CONVERSATION_ID

Workflow适合规则明确、步骤可预期的流程,例如校验输入、查业务数据、生成说明、等待审核、再返回结果。Workflow API 可以流式运行;执行到 Human Input 时会暂停,读取表单并提交 action 后再恢复。

让模型调用业务工具,但把执行权留在后端

项目提供一个 mock 业务 API,并在 openapi/business_tools.yaml 描述两个工具:Bearer Token 保护的订单查询,以及有金额范围校验的退款模拟。把 OpenAPI 定义导入 Dify 的 Swagger API 工具,再将工具加入 Agent 或流程,即可让 Dify 按工具描述构造请求。

python3 business_api.py
python3 dify_demo.py agent "查询 order-1001 状态"

# 订单数据是合成数据,退款只会返回 SIMULATED

关键经验是让工具保持窄而清楚:一个工具做一件明确的事,参数写明格式和约束,服务端对输入重新验证。工具 URL 必须能被 Dify 服务端访问;Cloud 服务不能访问你电脑上的 localhost。生产环境需要可达的 HTTPS 服务和合适的网络控制。

订单归属、用户授权、租户隔离、退款上限、幂等和审计都应由业务 API 执行。模型可以帮助理解用户意图、选择允许的工具并组织回复,但不会成为业务授权来源。对退款等有副作用的接口,还应设计人工确认和重复提交保护。

这里要把几类凭证分开:Dify 的 user 只是终端用户标识,不是业务认证凭证;App API Key 是业务后端调用 Dify 的凭证;DEMO_BUSINESS_API_TOKEN 是 Dify 调用 Demo 业务 API 的固定服务凭证。当前 Demo 不会根据 user 自动传递真实业务用户 Token,因此订单归属、授权、租户隔离和真实 Token 仍由业务后端控制。

如果业务必须让 Dify 参与一次带用户身份的调用,可以考虑两种方式。方案 A 是由 BFF 先验证用户,再把短时 Token 放进专用 Dify 输入变量,由 Workflow 或 Chatflow 的 HTTP Request 节点绑定到 Authorization Header。不要让 Token 进入 Prompt,也不要把它做成模型可以填写的工具参数,并要评估 Dify 日志和追踪中的数据留存。

更推荐方案 B:Token Broker。BFF 把普通业务输入和短时 request_context_id 发给 Dify;Dify 调业务网关时只携带固定 Dify 服务凭证和这个上下文 ID;业务网关向 Token Broker 校验并兑换一次性上下文,再用对应的用户 Token 调业务 API:

用户 -> BFF:登录并取得用户 Token
BFF -> Dify:普通业务输入 + 短时 request_context_id
Dify -> 业务网关:固定 Dify 服务凭证 + request_context_id
业务网关 -> Token Broker:校验并兑换一次性上下文
业务网关 -> 业务 API:Authorization: Bearer <用户 Token>

request_context_id 应随机、短时、一次性,并绑定用户、租户、允许操作和当前请求。这样 Dify 负责编排,后端仍然掌握真实身份与执行权限。

退款申请:模型准备建议,业务后端控制执行
  1. 用户请求提出退款说明订单与原因
  2. 只读核验查询订单校验归属与退款条件
  3. 流程暂停Dify 等待审核返回审核表单与 form_token
  4. 人工决定批准?批准 / 拒绝
  5. 仅批准后后端再次校验幂等、权限、金额后执行
批准 → 调用退款业务 API拒绝 → 记录原因并结束

Demo 中退款只返回 SIMULATED;模型本身没有直接执行退款的权限。

知识、文件、人工审核和反馈怎样组合

知识库解决“回答依据从哪里来”,工具解决“怎样读取或请求业务动作”,Workflow 解决“步骤如何串起来”。上传 PDF、提取语音或合成语音可以扩展输入输出;用户会话、消息历史与反馈 API 则帮助把助手接进客服界面并收集质量信号。

当工作流需要审批时,Human Input 会让运行暂停并返回 form_token。业务前端应使用当前登录用户呈现审核表单,再把批准或拒绝结果提交给 Dify;token 要绑定原用户和会话,不应作为公开链接传播。Demo 中的 workflow-stream、human-get 和 human-submit 展示了这个暂停与恢复过程。

点赞、点踩和人工维护的问答标注可以用于发现回答问题、补充高频标准答案。用户反馈并不自动等于可信知识;需要经过审核,再决定是否更新知识库或标注。项目也提供把已发布 Dify 应用作为 MCP Server 提供给 Cursor 等客户端的配置示例。

Dify 能给业务系统带来什么

  • 把自然语言接到现有 API。 用户可以描述目标,Dify 负责把意图路由到设计好的工具,业务系统继续管理数据和交易。
  • 让分散文档变成可查询的知识入口。 通过知识库检索,把制度、手册和常见问题放入问答流程,减少用户在多个系统间查找信息的步骤。
  • 把固定流程可视化并便于调整。 Workflow/Chatflow 可以组合模型、知识库、条件分支、工具和人工输入,让产品与工程更容易共同检查业务步骤。
  • 逐步扩展交互形态。 在一个 API 集成基础上,可以增加文件、音频、会话历史、反馈以及面向 MCP 客户端的入口。
  • 把迭代聚焦到业务价值。 团队可以先验证一个低风险问答或只读查询流程,再逐渐接入审批和写操作,并用失败率、人工接管率、回答采纳率和每次任务成本衡量效果。

这些价值来自减少信息查找和流程编排的摩擦,不是自动获得的效率收益。是否有效,要结合真实任务的正确率、延迟、模型成本、人工审核时间和业务风险来评估。

从 Demo 到生产,需要补上的部分

这个仓库是一份学习和集成样例,不是生产系统。退款端点不会执行真实退款,业务服务也没有真实用户体系、数据库、租户隔离、速率限制、持久化审计或完整的重试与恢复策略。上线前应逐项补齐,并确保 Dify 使用的网络地址和 API Key 范围符合部署环境。

我会按风险从低到高推进:先做有来源可核验的知识问答,再接只读查询,然后引入带权限检查的业务请求;涉及资金或数据变更时,先让系统生成待审核操作,获得明确授权后才由业务后端执行。每一步都保留监控、告警和人工接管入口。

资料与代码