9.7 · 客户端 SDKs（Client SDKs）

客户端 SDKs

客户端 SDK

相关源文件

本章引用的主要源码文件：

• .agents/skills/component-refactoring/SKILL.md
• .agents/skills/frontend-testing/SKILL.md
• .agents/skills/frontend-testing/references/checklist.md
• .agents/skills/frontend-testing/references/mocking.md
• .github/actions/setup-web/action.yml
• AGENTS.md
• CLAUDE.md
• e2e/package.json
• package.json
• packages/dify-ui/README.md
• packages/dify-ui/src/dialog/index.tsx
• packages/dify-ui/src/scroll-area/index.stories.tsx
• packages/dify-ui/src/toast/__tests__/index.spec.tsx
• packages/dify-ui/tsconfig.json
• packages/dify-ui/vite.config.ts
• packages/dify-ui/vitest.setup.ts
• packages/migrate-no-unchecked-indexed-access/package.json
• packages/migrate-no-unchecked-indexed-access/src/no-unchecked-indexed-access/run.ts
• pnpm-lock.yaml
• pnpm-workspace.yaml
• sdks/nodejs-client/package.json
• sdks/nodejs-client/tsconfig.json
• sdks/nodejs-client/vite.config.ts
• vite.config.ts
• web/AGENTS.md
• web/README.md
• web/app/components/base/form/index.stories.tsx
• web/app/components/header/account-setting/members-page/edit-workspace-modal/__tests__/index.spec.tsx
• web/contract/router.ts
• web/docs/lint.md
• web/docs/test.md
• web/eslint.config.mjs
• web/eslint.constants.mjs
• web/knip.config.ts
• web/scripts/analyze-component.js
• web/vite.config.ts

本文档详细介绍了 Dify 提供的用于集成其 API 的官方客户端 SDK。内容涵盖 Python 和 Node.js SDK、一个社区贡献的 PHP 客户端、它们的 API 覆盖范围，以及常见 Dify 功能的使用示例。这些 SDK 简化了与 Dify 的聊天、补全、工作流和知识库 API 的交互，抽象了直接的 HTTP 请求并处理了认证。

Node.js 客户端 SDK

Dify Node.js SDK 名为 dify-client，为从 Node.js 应用程序与 Dify API 交互提供了一种便捷方式。它已发布到 npm，并支持多种 Dify API 端点。该项目使用 pnpm 管理，位于 sdks/nodejs-client 目录下 pnpm-workspace.yaml:26。

安装

Node.js SDK 可以通过 npm 安装：

npm install dify-client

来源：sdks/nodejs-client/package.json:1-71

架构与核心组件

Node.js SDK 由多个客户端类组成，每个类负责一组特定的 Dify API 功能。这些客户端共享一个通用的底层 HTTP 客户端来发送请求。

客户端类

• DifyClient：提供通用的应用级 API，例如获取应用参数、消息反馈、文件上传以及音频/文本转换。
• ChatClient：处理聊天相关的操作，包括创建聊天消息（阻塞和流式）、停止消息、获取建议问题、管理对话以及处理标注。
• CompletionClient：管理补全相关的交互，例如创建补全消息（阻塞和流式）以及停止补全任务。
• WorkflowClient：用于运行 Dify 工作流。
• KnowledgeBaseClient：提供管理数据集、文档、片段、子片段、元数据以及运行检索增强生成（RAG）管线的方法。
• WorkspaceClient：用于工作区级别的操作，例如按类型获取模型。

这些类封装了特定的 API 路由功能，并为与后端交互提供了类型化接口。

请求处理

SDK 使用内部 HTTP 客户端发送请求。它支持聊天和补全消息的阻塞和流式响应模式。对于流式响应，SDK 返回一个 AsyncIterable，可以对其进行迭代以处理到达的 SSE（服务器推送事件）。

流式响应的数据流：

来源：sdks/nodejs-client/README.md:15-93，sdks/nodejs-client/src/client/chat.test.ts:11-51，sdks/nodejs-client/src/client/completion.test.ts:10-46

使用示例

以下示例演示了如何使用 Node.js SDK 进行常见的 Dify API 交互：

import {
  DifyClient,
  ChatClient,
  CompletionClient,
  WorkflowClient,
  KnowledgeBaseClient,
  WorkspaceClient
} from 'dify-client'

const API_KEY = 'your-app-api-key'
const DATASET_API_KEY = 'your-dataset-api-key' // 用于知识库和工作区 API
const user = 'random-user-id'
const query = '请用不超过 10 个字讲一个短故事。'

const chatClient = new ChatClient(API_KEY)
const completionClient = new CompletionClient(API_KEY)
const workflowClient = new WorkflowClient(API_KEY)
const kbClient = new KnowledgeBaseClient(DATASET_API_KEY)
const workspaceClient = new WorkspaceClient(DATASET_API_KEY)
const client = new DifyClient(API_KEY)

// 通用应用信息
const appParams = await client.getApplicationParameters(user)
await client.messageFeedback('message-id', 'like', user)

// 补全（阻塞模式）
const completion = await completionClient.createCompletionMessage({
  inputs: { query },
  user,
  response_mode: 'blocking'
})

// 聊天（流式模式）
const stream = await chatClient.createChatMessage({
  inputs: {},
  query,
  user,
  response_mode: 'streaming'
})
for await (const event of stream) {
  console.log(event.event, event.data)
}

// 通过 workflow_id 运行高级聊天流
await chatClient.createChatMessage({
  inputs: {},
  query,
  user,
  workflow_id: 'workflow-id',
  response_mode: 'blocking'
})

// 以阻塞模式运行工作流
await workflowClient.run({
  inputs: { query },
  user,
  response_mode: 'blocking'
})

// 知识库数据集操作（需要数据集令牌）
await kbClient.listDatasets({ page: 1, limit: 20 })
await kbClient.createDataset({ name: '知识库', indexing_technique: 'economy' })

// 工作区管理（需要数据集令牌）
await workspaceClient.getModelsByType('text-embedding')

来源：sdks/nodejs-client/README.md:15-93

Node.js SDK 中的 API 覆盖范围

Node.js SDK 覆盖了广泛的 Dify API，组织如下：

Node.js SDK 发布工作流

Node.js SDK 通过位于 sdks/nodejs-client/scripts/ 的 shell 脚本 publish.sh 从 Dify 仓库工作区发布。

发布自动化执行以下步骤：

来源：sdks/nodejs-client/scripts/publish.sh:116-230

PHP 客户端

Dify PHP SDK 是一个社区贡献的客户端，用于将 Dify 集成到 PHP 应用程序中。它使用 Guzzle HTTP 客户端来执行 API 请求。

要求

• PHP 7.2 或更高版本
• Guzzle HTTP 客户端库

来源：sdks/php-client/README.md:7-9

安装

要使用 PHP 客户端，请将 dify-client.php 复制到您的项目中，通过 Composer 引入 Guzzle，并自动加载该文件：

{
    "require": {
        "guzzlehttp/guzzle": "^7.9"
    },
    "autoload": {
        "files": ["path/to/dify-client.php"]
    }
}

来源：sdks/php-client/README.md:16-22

架构与核心组件

PHP 客户端包含一个基础的 DifyClient 类以及继承它的专门类：CompletionClient、ChatClient 和 WorkflowClient。

• DifyClient：处理 API 认证、基础 URL、使用 JSON 或 multipart/form-data 编码发送 HTTP 请求，并提供消息反馈、获取应用参数、文件上传、文本转音频和获取元信息等方法。
• CompletionClient：继承 DifyClient，提供创建补全消息的方法。
• ChatClient：继承 DifyClient，管理聊天消息创建、建议、停止消息、对话操作和音频转文本。
• WorkflowClient：继承 DifyClient，支持运行和停止工作流执行。

请求发送会正确处理流式响应，如果 API 返回流式数据，则会解析分块响应。

来源：sdks/php-client/dify-client.php:5-206

使用示例

以下是一个 PHP 示例，演示了 PHP 客户端的基本用法：

<?php

require 'vendor/autoload.php';

$apiKey = 'your-api-key-here';
$user_id = 'user_id';
$conversation_id = 'conversation_id';

$difyClient = new DifyClient($apiKey);

// 创建补全客户端并发送阻塞补全消息
$completionClient = new CompletionClient($apiKey);
$response = $completionClient->create_completion_message(array("query" => "你是谁？"), "blocking", $user_id);

// 上传文件
$fileForUpload = [
    [
        'tmp_name' => '/path/to/file/filename.jpg',
        'name' => 'filename.jpg'
    ]
];
$response = $difyClient->file_upload($user_id, $fileForUpload);

// 运行工作流
$workflowClient = new WorkflowClient($apiKey);
$response = $workflowClient->run(['input_key' => 'input_value'], 'blocking', $user_id);

?>

来源：sdks/php-client/README.md:30-89

PHP 客户端中的 API 覆盖范围

来源：sdks/php-client/dify-client.php:5-206

SDK 到服务 API 的映射

下图将自然语言空间（SDK 函数调用）桥接到代码实体空间（API 端点）。

来源：web/app/components/develop/template/template_chat.en.mdx:24-29，web/app/components/develop/template/template_workflow.en.mdx:24-29，web/app/components/develop/template/template.en.mdx:24-29，web/app/components/develop/template/template.zh.mdx:179-184

附加数据流：SDK 中的流式响应

流式模式使用后端的服务器推送事件（SSE）向客户端 SDK 传递实时的部分响应。

此流程使应用程序能够处理增量输出，例如流式聊天消息或工作流事件，从而提高响应速度和用户体验。

来源：web/app/components/develop/template/template_chat.en.mdx，web/app/components/develop/template/template_workflow.en.mdx

总结

Dify 为 Node.js 和 PHP 提供了官方客户端 SDK，涵盖了聊天、补全、工作流、知识库管理和工作区集成等全面的 API。这些 SDK 抽象了原始的 HTTP API，处理了认证和流式协议，并为开发者提供了符合语言习惯的使用模式。它们使 Dify 的 AI 能力能够快速集成到不同编程环境的应用中。

来源：

• sdks/nodejs-client/package.json
• sdks/nodejs-client/README.md
• sdks/nodejs-client/scripts/publish.sh
• sdks/nodejs-client/src/client/base.test.ts
• sdks/nodejs-client/src/client/chat.test.ts
• sdks/nodejs-client/src/client/completion.test.ts
• sdks/nodejs-client/src/client/knowledge-base.test.ts
• sdks/php-client/dify-client.php
• sdks/php-client/README.md
• web/app/components/develop/template/template_chat.en.mdx
• web/app/components/develop/template/template_workflow.en.mdx
• web/app/components/develop/template/template.en.mdx
• web/app/components/develop/template/template.zh.mdx