Dify API 怎么用？如何把 AI 应用集成到业务系统？

Dify API 适合怎么用？

Dify API 的作用，是把控制台里搭好的 AI 应用接到自己的业务系统里。客服系统自动生成回复、运营后台总结用户反馈、内部知识库问答、工单分类和报告生成，都可以通过 API 调用 Dify。关键不是背端点，而是先判断应用类型：对话用 Chat API，结构化流程用 Workflow API，知识库同步用 Dataset 相关接口。

认证和地址怎么配置？

Dify API 通常使用 Bearer Token。密钥在应用的 API Access 页面生成，请求时放到 Header：

http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

生产环境不要把 API Key 放在前端、App 包或公开配置里。更稳的方式是前端请求自己的后端，后端保存密钥并代理 Dify 调用，这样才能做登录校验、限流、审计和密钥轮换。私有化部署还要确认 Base URL，云端可能是 https://api.dify.ai/v1，内网通常是自己的域名加 /v1。

Chat API 怎么调用？

聊天应用常用 /v1/chat-messages。最小请求通常包括 inputs、query、response_mode 和 user：

python
import requests
resp = requests.post(
  "https://api.example.com/v1/chat-messages",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={"inputs": {}, "query": "总结这条工单", "response_mode": "blocking", "user": "u-123"},
  timeout=60
)
print(resp.json())

blocking 开发简单，适合后台任务；streaming 体验更好，适合聊天窗口逐字输出。取舍是流式需要 SSE 支持，很多网关默认会缓冲响应，导致用户仍然最后一次性看到结果。多轮对话还要保存 Dify 返回的 conversation_id，下一轮继续传回去，否则追问会变成新会话。

Workflow API 适合什么？

/v1/workflows/run 更像触发一个后端任务，适合分类、抽取、审核、生成报告等固定输入输出场景。调用方传入 inputs 和 user，Dify 按节点执行后返回结果。它的好处是流程清楚、输出可控；边界是字段名依赖很强，工作流输入一改，业务系统也要同步改。

生产集成还要补工程能力：超时、重试、错误分类、日志脱敏和成本控制。模型接口比普通接口慢，不能所有异常都返回“系统繁忙”。建议记录 request id、用户、耗时、状态码和错误类型，正文内容按合规要求脱敏。

追问

Chat API 和 Workflow API 怎么选？

需要连续对话、上下文和追问，用 Chat API。输入一组字段、跑完流程、返回结构化结果，用 Workflow API。边界是 Chat API 更像助手，Workflow API 更像后端任务。踩坑点是把复杂审批或分类流程硬塞进聊天提示词，后期很难调试。

API Key 能放前端吗？

不建议，生产环境基本不要这样做。前端密钥会被抓包、源码或反编译拿到，别人可以绕过你的权限直接调用 Dify。后端代理虽然多一层开发，但能做鉴权、限流和审计。取舍上，只有临时 demo 可以前端直连，正式业务不要这么省事。

streaming 和 blocking 有什么坑？

blocking 简单稳定，但长回答会让用户等很久。streaming 体验好，不过浏览器、Nginx、网关和后端都要支持长连接和 SSE。常见坑是代理层缓冲响应，服务端明明一段段返回，前端却最后才显示。排查时要从 Dify、后端代理、网关三层分别看。

知识库上传成功后为什么搜不到？

上传成功通常只代表文件已提交，不代表切分、嵌入和索引完成。大文件或批量导入会异步处理，期间检索不到是正常的。业务系统应该查询处理状态，完成后再开放搜索。边界是文档质量、切分策略和嵌入模型都会影响召回，不是 API 成功就等于问答准确。