【实战】Dify从0到100进阶--文档解读（13）API前端再开发
一、基于 API 的开发
1. 核心理念
Dify 的“后端即服务”（BaaS）理念，意味着所有大模型、Prompt 工程、知识库和工具能力都已在后端封装，前端只需通过标准化的 HTTP 接口即可调用，不必关心模型部署、运维与扩缩容。
2. 典型流程
-
获取凭据
- 在 Dify 控制台，打开目标应用 → “访问 API” → 创建或复制 Access Token
- 推荐在后端安全地存储和管理 Token，前端仅通过自己后端代理转发请求，避免明文暴露。
-
调用 Completion（文本生成）
-
接口：
POST https://api.dify.ai/v1/completion-messages -
入参示例（cURL）：
curl --location --request POST 'https://api.dify.ai/v1/completion-messages' \--header 'Authorization: Bearer {YOUR_TOKEN}' \--header 'Content-Type: application/json' \--data-raw '{"inputs": {"text": "请给我写一首七言绝句"},"response_mode": "streaming","user": "user-001"}' -
返回：分片流或完整 JSON，包含生成的文本。
-
-
调用 Chat（对话型）
-
接口：
POST https://api.dify.ai/v1/chat-messages -
第一次对话时不传
conversation_id，后续交互需带上同一个 ID，保持上下文。 -
入参示例（Python）：
import requests, jsonurl = "https://api.dify.ai/v1/chat-messages" headers = {"Authorization": "Bearer {YOUR_TOKEN}","Content-Type": "application/json", } # 新会话 data = {"inputs": {},"query": "你好，请介绍一下上海","response_mode": "streaming","user": "user-001" } resp = requests.post(url, headers=headers, json=data) print(resp.text) # 假设返回 conversation_id = "abc-123" # 继续对话 data["conversation_id"] = "abc-123" data["query"] = "那它有哪些著名景点？" resp2 = requests.post(url, headers=headers, json=data)
-
3. 优势与实践建议
- 安全可控：后端统一管理 Token、使用权限；前端只需调用封装好的能力
- 供应商无关：可在 Dify 控制台随时切换模型厂商，或者在 Prompts 面板微调提示词
- 快速迭代：新增工具能力、知识库后，前端无需改动，实时生效
- 监控与分析：Dify 提供日志、使用量、活跃度、标注等可视化面板
最佳实践
- Token 切勿直接写在浏览器 JS 里，应通过自己后端做二次鉴权转发。
- 流式响应时，前端可使用原生 Fetch API 的 ReadableStream 接口逐步渲染 AI 内容。
- 针对对话场景，建议维护本地的 conversation_id 存储（如 localStorage），确保用户刷新页面也能恢复会话。
二、基于前端改造的开发
1. 核心思路
除了纯粹的 API 调用，Dify 还提供 Web SDK／嵌入式组件，让你在前端页面里「零后端」或「极少后端」地集成 AI 聊天、知识问答、问卷或任务型 Agent。
- 组件化：一行脚本或 NPM 包即可加载聊天界面
- 可视化设置：通过控制台可视化配置界面样式、行为、工具列表
- 事件钩子：在 JS 里监听用户输入、AI 回复、错误回调等，做二次加工
2. 快速上手示例
-
通过
<script>标签嵌入<!-- 在页面 <head> 或 </body> 前加载 SDK --> <script src="https://cdn.jsdelivr.net/npm/@dify/chat-widget"></script><!-- 聊天组件占位 --> <div id="dify-chat-container"></div><script>// 初始化DifyChatWidget.init({el: '#dify-chat-container',appId: 'YOUR_APP_ID', // 在 Dify 控制台获取userId: 'user-001', // 区分会话theme: { accent: '#1a73e8' },onMessage: (msg) => console.log('AI:', msg.content),onError: (err) => console.error(err)}); </script> -
NPM 引入（React/Vue 等框架）
npm install @dify/chat-widgetimport React, { useEffect } from 'react'; import { ChatWidget } from '@dify/chat-widget';export default function App() {return (<ChatWidgetappId="YOUR_APP_ID"userId="user-001"locale="zh-CN"onMessage={(msg) => console.log('AI:', msg)}style={{ width: 350, height: 500 }}/>); }
3. 定制化与扩展
-
UI 样式
- 主题色、字体、按钮样式都可通过配置项或 CSS 变量覆盖
-
插件能力
- 在控制台 “工具能力” 里绑定第三方插件（如 翻译、检索、表单）
- 前端无感知，只需在 SDK 配置打开工具面板
-
会话变量
- 通过
sessionVars参数注入上下文变量，让不同用户看到差异化回应
- 通过
-
事件与埋点
onSend,onReceive,onOpen,onClose等回调，可用于埋点或二次渲染
4. 与纯 API 的区别
| 特性 | 基于 API 开发 | 基于前端改造 |
|---|---|---|
| 上手难度 | 需编写网络请求代码 | 仅需引入 SDK，零代码接入 |
| 灵活度 | 自由拼接任何前端逻辑 | 受限于 SDK 提供的接口与样式 |
| 运营能力 | 需自建分析面板 | 可直接使用 Dify 可视化面板 |
| 安全性 | 自行管理 Token | App ID + JS Secret，可配置白名单域名 |
| 二次开发 | 自由度更高 | 在 SDK 能力范围内扩展 |