Dify Java Client

发布日期：2025-08-20 07:22:07 浏览次数： 2390

作者：时光瞭望塔

微信搜一搜，关注“时光瞭望塔”

dify Java Client

Dify Java Client 是一个用于与 Dify 平台进行交互的 Java 客户端库。它提供了对 Dify 应用 API 和知识库 API 的完整支持，让 Java 开发者能够轻松地将 Dify 的生成式 AI 能力集成到自己的应用中。

功能特性

Dify Java Client 提供以下核心功能：

1. 多种应用类型支持

• 对话型应用 (Chat): 通过 DifyChatClient 调用对话型应用，支持会话管理、消息反馈等功能
• 文本生成应用 (Completion): 通过 DifyCompletionClient 调用文本生成型应用
• 工作流编排对话 (Chatflow): 通过 DifyChatflowClient 调用工作流编排对话型应用
• 工作流应用 (Workflow): 通过 DifyWorkflowClient 调用工作流应用
• 知识库管理 (Datasets): 通过 DifyDatasetsClient 管理知识库、文档和检索

2. 丰富的交互模式

• 阻塞模式: 同步调用API，等待完整响应
• 流式模式: 通过回调接收实时生成的内容，支持打字机效果
• 文件处理: 支持文件上传、语音转文字、文字转语音等多媒体功能

3. 完整的会话管理

• 创建和管理会话
• 获取历史消息
• 会话重命名
• 消息反馈（点赞/点踩）
• 获取建议问题

4. 知识库全流程支持

• 创建和管理知识库
• 上传和管理文档
• 文档分段管理
• 语义检索

5. 灵活的配置选项

• 自定义连接超时
• 自定义读写超时
• 自定义HTTP客户端

安装

系统要求

• Java 8 或更高版本
• Maven 3.x 或 Gradle 4.x 以上

Maven

<dependency>
    <groupId>io.github.imfangs</groupId>
    <artifactId>dify-java-client</artifactId>
    <version>1.1.6</version>
</dependency>

Gradle

implementation 'io.github.imfangs:dify-java-client:1.1.6'

快速开始

创建客户端

// 创建完整的 Dify 客户端
DifyClientclient= DifyClientFactory.createClient("https://api.dify.ai/v1", "your-api-key");

// 创建特定类型的客户端
DifyChatClientchatClient= DifyClientFactory.createChatClient("https://api.dify.ai/v1", "your-api-key");
DifyCompletionClientcompletionClient= DifyClientFactory.createCompletionClient("https://api.dify.ai/v1", "your-api-key");
DifyChatflowClientchatflowClient= DifyClientFactory.createChatWorkflowClient("https://api.dify.ai/v1", "your-api-key");
DifyWorkflowClientworkflowClient= DifyClientFactory.createWorkflowClient("https://api.dify.ai/v1", "your-api-key");
DifyDatasetsClientdatasetsClient= DifyClientFactory.createDatasetsClient("https://api.dify.ai/v1", "your-api-key");

// 使用自定义配置创建客户端
DifyConfigconfig= DifyConfig.builder()
    .baseUrl("https://api.dify.ai/v1")
    .apiKey("your-api-key")
    .connectTimeout(5000)
    .readTimeout(60000)
    .writeTimeout(30000)
    .build();

DifyClientclientWithConfig= DifyClientFactory.createClient(config);

使用示例

1. 对话型应用 (Chat)

阻塞模式

// 创建聊天客户端
DifyChatClientchatClient= DifyClientFactory.createChatClient("https://api.dify.ai/v1", "your-api-key");

// 创建聊天消息
ChatMessagemessage= ChatMessage.builder()
    .query("你好，请介绍一下自己")
    .user("user-123")
    .responseMode(ResponseMode.BLOCKING)
    .build();

// 发送消息并获取响应
ChatMessageResponseresponse= chatClient.sendChatMessage(message);
System.out.println("回复: " + response.getAnswer());
System.out.println("会话ID: " + response.getConversationId());
System.out.println("消息ID: " + response.getMessageId());

流式模式

// 创建聊天消息
ChatMessagemessage= ChatMessage.builder()
    .query("请给我讲一个简短的故事")
    .user("user-123")
    .responseMode(ResponseMode.STREAMING)
    .build();

// 发送流式消息
chatClient.sendChatMessageStream(message, newChatStreamCallback() {
    @Override
    publicvoidonMessage(MessageEvent event) {
        System.out.println("收到消息片段: " + event.getAnswer());
    }

    @Override
    publicvoidonMessageEnd(MessageEndEvent event) {
        System.out.println("消息结束，完整消息ID: " + event.getMessageId());
    }

    @Override
    publicvoidonError(ErrorEvent event) {
        System.err.println("错误: " + event.getMessage());
    }

    @Override
    publicvoidonException(Throwable throwable) {
        System.err.println("异常: " + throwable.getMessage());
    }
});

会话管理

// 获取会话历史消息
MessageListResponsemessages= chatClient.getMessages(conversationId, "user-123", null, 10);

// 获取会话列表
ConversationListResponseconversations= chatClient.getConversations("user-123", null, 10, "-updated_at");

// 重命名会话
ConversationrenamedConversation= chatClient.renameConversation(conversationId, "新会话名称", false, "user-123");

// 删除会话
SimpleResponsedeleteResponse= chatClient.deleteConversation(conversationId, "user-123");

消息反馈

// 发送消息反馈（点赞）
SimpleResponse feedbackResponse = chatClient.feedbackMessage(messageId, "like", "user-123", "这是一个很好的回答");

// 获取建议问题
SuggestedQuestionsResponse suggestedQuestions = chatClient.getSuggestedQuestions(messageId, "user-123");

语音转换

// 语音转文字
AudioToTextResponse textResponse = chatClient.audioToText(audioFile, "user-123");
System.out.println("转换后的文本: " + textResponse.getText());

// 文字转语音
byte[] audioData = chatClient.textToAudio(null, "这是一段测试文本", "user-123");

2. 文本生成应用 (Completion)

阻塞模式

// 创建文本生成客户端
DifyCompletionClientcompletionClient= DifyClientFactory.createCompletionClient("https://api.dify.ai/v1", "your-api-key");

// 创建请求
Map<String, Object> inputs = newHashMap<>();
inputs.put("content", "茄子");

CompletionRequestrequest= CompletionRequest.builder()
    .inputs(inputs)
    .responseMode(ResponseMode.BLOCKING)
    .user("user-123")
    .build();

// 发送请求并获取响应
CompletionResponseresponse= completionClient.sendCompletionMessage(request);
System.out.println("生成的文本: " + response.getAnswer());

流式模式

// 创建请求
Map<String, Object> inputs = newHashMap<>();
inputs.put("content", "茄子");

CompletionRequestrequest= CompletionRequest.builder()
    .inputs(inputs)
    .responseMode(ResponseMode.STREAMING)
    .user("user-123")
    .build();

// 发送流式请求
completionClient.sendCompletionMessageStream(request, newCompletionStreamCallback() {
    @Override
    publicvoidonMessage(MessageEvent event) {
        System.out.println("收到消息片段: " + event.getAnswer());
    }

    @Override
    publicvoidonMessageEnd(MessageEndEvent event) {
        System.out.println("消息结束，完整消息ID: " + event.getMessageId());
    }

    @Override
    publicvoidonError(ErrorEvent event) {
        System.err.println("错误: " + event.getMessage());
    }

    @Override
    publicvoidonException(Throwable throwable) {
        System.err.println("异常: " + throwable.getMessage());
    }
});

停止生成

// 停止文本生成
SimpleResponse stopResponse = completionClient.stopCompletion(taskId, "user-123");

3. 工作流应用 (Workflow)

阻塞模式

// 创建工作流客户端
DifyWorkflowClientworkflowClient= DifyClientFactory.createWorkflowClient("https://api.dify.ai/v1", "your-api-key");

// 创建工作流请求
Map<String, Object> inputs = newHashMap<>();
inputs.put("content", "请介绍一下人工智能的应用场景");

WorkflowRunRequestrequest= WorkflowRunRequest.builder()
    .inputs(inputs)
    .responseMode(ResponseMode.BLOCKING)
    .user("user-123")
    .build();

// 执行工作流并获取响应
WorkflowRunResponseresponse= workflowClient.runWorkflow(request);
System.out.println("工作流执行ID: " + response.getTaskId());

// 输出结果
if (response.getData() != null) {
    for (Map.Entry<String, Object> entry : response.getData().getOutputs().entrySet()) {
        System.out.println(entry.getKey() + ": " + entry.getValue());
    }
}

流式模式

// 创建工作流请求
Map<String, Object> inputs = newHashMap<>();
inputs.put("content", "请详细介绍一下机器学习的基本原理");

WorkflowRunRequestrequest= WorkflowRunRequest.builder()
    .inputs(inputs)
    .responseMode(ResponseMode.STREAMING)
    .user("user-123")
    .build();

// 执行工作流流式请求
workflowClient.runWorkflowStream(request, newWorkflowStreamCallback() {
    @Override
    publicvoidonWorkflowStarted(WorkflowStartedEvent event) {
        System.out.println("工作流开始: " + event);
    }

    @Override
    publicvoidonNodeStarted(NodeStartedEvent event) {
        System.out.println("节点开始: " + event);
    }

    @Override
    publicvoidonNodeFinished(NodeFinishedEvent event) {
        System.out.println("节点完成: " + event);
    }

    @Override
    publicvoidonWorkflowFinished(WorkflowFinishedEvent event) {
        System.out.println("工作流完成: " + event);
    }

    @Override
    publicvoidonError(ErrorEvent event) {
        System.err.println("错误: " + event.getMessage());
    }

    @Override
    publicvoidonException(Throwable throwable) {
        System.err.println("异常: " + throwable.getMessage());
    }
});

工作流管理

// 停止工作流
WorkflowStopResponse stopResponse = workflowClient.stopWorkflow(taskId, "user-123");

// 获取工作流执行情况
WorkflowRunStatusResponse statusResponse = workflowClient.getWorkflowRun(workflowRunId);

// 获取工作流日志
WorkflowLogsResponse logsResponse = workflowClient.getWorkflowLogs(null, null, 1, 10);

4. 知识库管理 (Datasets)

创建和管理知识库

// 创建知识库客户端
DifyDatasetsClientdatasetsClient= DifyClientFactory.createDatasetsClient("https://api.dify.ai/v1", "your-api-key");

// 创建知识库
CreateDatasetRequestcreateRequest= CreateDatasetRequest.builder()
    .name("测试知识库-" + System.currentTimeMillis())
    .description("这是一个测试知识库")
    .indexingTechnique("high_quality")
    .permission("only_me")
    .provider("vendor")
    .build();

DatasetResponsedataset= datasetsClient.createDataset(createRequest);
System.out.println("创建的知识库ID: " + dataset.getId());

// 获取知识库列表
DatasetListResponsedatasetList= datasetsClient.getDatasets(1, 10);
System.out.println("知识库总数: " + datasetList.getTotal());

文档管理

// 通过文本创建文档 - 使用自动处理模式（推荐）
CreateDocumentByTextRequestdocRequest= CreateDocumentByTextRequest.builder()
    .name("测试文档-" + System.currentTimeMillis())
    .text("这是一个测试文档的内容。\n这是第二行内容。\n这是第三行内容。")
    .indexingTechnique("high_quality")
    .docForm("text_model")
    .docLanguage("Chinese")
    .processRule(ProcessRule.builder()
        .mode("automatic")  // 使用自动处理模式
        .build())
    .build();

DocumentResponsedocResponse= datasetsClient.createDocumentByText(datasetId, docRequest);
System.out.println("创建的文档ID: " + docResponse.getDocument().getId());

// 获取文档列表
DocumentListResponsedocList= datasetsClient.getDocuments(datasetId, null, 1, 10);
System.out.println("文档总数: " + docList.getTotal());

// 删除文档
SimpleResponsedeleteResponse= datasetsClient.deleteDocument(datasetId, documentId);

知识库检索

// 创建检索请求
RetrievalModelretrievalModel=newRetrievalModel();
retrievalModel.setTopK(3);
retrievalModel.setScoreThreshold(0.5f);

RetrieveRequestretrieveRequest= RetrieveRequest.builder()
    .query("什么是人工智能")
    .retrievalModel(retrievalModel)
    .build();

// 发送检索请求
RetrieveResponseretrieveResponse= datasetsClient.retrieveDataset(datasetId, retrieveRequest);

// 处理检索结果
System.out.println("检索查询: " + retrieveResponse.getQuery().getContent());
System.out.println("检索结果数量: " + retrieveResponse.getRecords().size());
retrieveResponse.getRecords().forEach(record -> {
    System.out.println("分数: " + record.getScore());
    System.out.println("内容: " + record.getSegment().getContent());
});

API 参考

客户端类型

客户端类型	描述	主要功能
`DifyClient`	完整客户端	支持所有API功能
`DifyChatClient`	对话型应用客户端	对话、会话管理、消息反馈
`DifyCompletionClient`	文本生成型应用客户端	文本生成、停止生成
`DifyChatflowClient`	工作流编排对话型应用客户端	工作流编排对话
`DifyWorkflowClient`	工作流应用客户端	执行工作流、工作流管理
`DifyDatasetsClient`	知识库客户端	知识库管理、文档管理、检索

响应模式

模式	枚举值	描述
阻塞模式	`ResponseMode.BLOCKING`	同步调用，等待完整响应
流式模式	`ResponseMode.STREAMING`	通过回调接收实时生成的内容

事件类型

事件类型	描述
`MessageEvent`	消息事件，包含生成的文本片段
`MessageEndEvent`	消息结束事件，包含完整消息ID
`MessageFileEvent`	文件消息事件，包含文件信息
`TtsMessageEvent`	文字转语音事件
`TtsMessageEndEvent`	文字转语音结束事件
`MessageReplaceEvent`	消息替换事件
`AgentMessageEvent`	Agent消息事件
`AgentThoughtEvent`	Agent思考事件
`WorkflowStartedEvent`	工作流开始事件
`NodeStartedEvent`	节点开始事件
`NodeFinishedEvent`	节点完成事件
`WorkflowFinishedEvent`	工作流完成事件
`ErrorEvent`	错误事件
`PingEvent`	心跳事件

高级配置

自定义HTTP客户端

// 创建自定义配置
DifyConfig config = DifyConfig.builder()
    .baseUrl("https://api.dify.ai/v1")
    .apiKey("your-api-key")
    .connectTimeout(5000)  // 连接超时（毫秒）
    .readTimeout(60000)    // 读取超时（毫秒）
    .writeTimeout(30000)   // 写入超时（毫秒）
    .build();

// 使用自定义配置创建客户端
DifyClient client = DifyClientFactory.createClient(config);

53AI，企业落地大模型首选服务商

产品：场景落地咨询+大模型应用平台+行业解决方案

承诺：免费POC验证，效果达标后再合作。零风险落地应用大模型，已交付160+中大型企业