{"id":43732728,"url":"https://github.com/yuanbaobaoo/dify-java-client","last_synced_at":"2026-02-05T10:31:16.219Z","repository":{"id":277487546,"uuid":"932577591","full_name":"yuanbaobaoo/dify-java-client","owner":"yuanbaobaoo","description":"The Simple and Easy-to-Use Dify Java Client （一款简单易用的 Dify Java 客户端）","archived":false,"fork":false,"pushed_at":"2025-07-11T09:11:06.000Z","size":218,"stargazers_count":67,"open_issues_count":1,"forks_count":13,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-11T12:28:33.717Z","etag":null,"topics":["dify","java"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yuanbaobaoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-14T06:18:52.000Z","updated_at":"2025-07-11T09:10:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"2518c9b4-3c60-4aae-861c-ed097934d810","html_url":"https://github.com/yuanbaobaoo/dify-java-client","commit_stats":null,"previous_names":["yuanbaobaoo/dify-java-client"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/yuanbaobaoo/dify-java-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuanbaobaoo%2Fdify-java-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuanbaobaoo%2Fdify-java-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuanbaobaoo%2Fdify-java-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuanbaobaoo%2Fdify-java-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yuanbaobaoo","download_url":"https://codeload.github.com/yuanbaobaoo/dify-java-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuanbaobaoo%2Fdify-java-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29119232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T09:40:36.738Z","status":"ssl_error","status_checked_at":"2026-02-05T09:36:49.977Z","response_time":65,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dify","java"],"created_at":"2026-02-05T10:31:14.081Z","updated_at":"2026-02-05T10:31:16.211Z","avatar_url":"https://github.com/yuanbaobaoo.png","language":"Java","readme":"dify-java-client\n---\n\n\u003cp style=\"text-align: left\"\u003e\n    \u003ca href=\"https://github.com/yuanbaobaoo/dify-java-client\" target=\"_blank\"\u003e\n        \u003cimg alt=\"maven-central\" src=\"https://img.shields.io/badge/github-🤪-green\" /\u003e \n    \u003c/a\u003e\n    \u0026nbsp;\n    \u003ca href=\"https://openjdk.org/projects/jdk/17\" target=\"_blank\"\u003e\n        \u003cimg alt=\"maven-central\" src=\"https://img.shields.io/badge/Java-17-blue\" /\u003e \n    \u003c/a\u003e\n    \u0026nbsp;\n    \u003ca href=\"https://central.sonatype.com/artifact/io.github.yuanbaobaoo/dify-java-client\" target=\"_blank\"\u003e\n        \u003cimg alt=\"maven-central\" src=\"https://img.shields.io/badge/maven--central-1.4.5-green\" /\u003e \n    \u003c/a\u003e\n\u003c/p\u003e\n\n简单易用的 Dify Java客户端，支持在任意Java项目中使用 [Dify](https://dify.ai/) 的工作流、对话助手、Agent、Dataset、文字转语音、语音转文字等开放能力。\n\n中文 | [English](./README_EN.md)\n\n## 安装依赖\n- 环境需求\n```code\nJava : \u003e= 17\nDify Version: \u003c= 1.x\n```\n\n- maven\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.yuanbaobaoo\u003c/groupId\u003e\n    \u003cartifactId\u003edify-java-client\u003c/artifactId\u003e\n    \u003cversion\u003e1.4.5\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n- gradle\n```gradle\nimplementation group: 'io.github.yuanbaobaoo', name: 'dify-java-client', version: '1.4.5'\n```\n\n## 快速开始\n使用 ```DifyClientBuilder``` 创建各类客户端实例\n```java\n/**\n * 创建一个对话类型客户端对象，支持 base()、chat()、flow()、completion() 其对应返回类型也是不一致的\n */\nIAppChatClient appClient = DifyClientBuilder.app().chat().apiKey(\"app-xxx\").baseUrl(\"https://api.dify.ai/v1\").build();\n\n/**\n * 创建一个知识库类型客户端对象\n */\nIDatasetClient datasetClient = DifyClientBuilder.dataset().apiKey(\"app-xxx\").baseUrl(\"https://api.dify.ai/v1\").build();\n\n/**\n * 创建一个WebConsole类型客户端对象，用于模拟Dify控制台操作（试验特性）\n */\nIWebConsoleClient webClient = DifyClientBuilder.web(\"${server}\", \"${userName}\", \"${password}\").connect();\n```\n\n## 创建 App 类型的 Client\n在代码中，使用 ```DifyClientBuilder.app()``` 即可创建App类型的客户端对象。\nApp客户端是指适用于 ChatBot、Agent、ChatFlow、Completion 类型的应用，提供了会话相关的API，支持会话的流式返回。主要包含如下：\n- [```IAppBaseClient```](https://github.com/yuanbaobaoo/dify-java-client/blob/master/src/main/java/io/github/yuanbaobaoo/dify/app/IAppBaseClient.java)\n- [```IAppChatClient```](https://github.com/yuanbaobaoo/dify-java-client/blob/master/src/main/java/io/github/yuanbaobaoo/dify/app/IAppChatClient.java)\n- [```IAppFlowClient```](https://github.com/yuanbaobaoo/dify-java-client/blob/master/src/main/java/io/github/yuanbaobaoo/dify/app/IAppFlowClient.java)\n- [```IAppCompletion```](https://github.com/yuanbaobaoo/dify-java-client/blob/master/src/main/java/io/github/yuanbaobaoo/dify/app/IAppCompletion.java)\n\n### 1、IAppBaseClient\n基础Client，提供Dify公共API，具体可查阅 ```IAppBaseClient```\n```java\nIAppBaseClient client = DifyClientBuilder.app().base().apiKey(\"app-xxxx\").baseUrl(\"https://api.dify.ai/v1\").build();\n\n// 调用接口\nString metaInfo = client.getAppMetaInfo();\n// 上传文件\nDifyFileResult result = client.uploadFile(new File(\"pom.xml\"), \"abc-123\");\n```\n\n### 2、IAppChatClient\n适用于 ChatBot、Agent、ChatFlow 类型应用，继承自 ```IAppBaseClient```，提供了会话相关的API：\n```java\nIAppChatClient client = DifyClientBuilder.app().chat().apiKey(\"app-xxxx\").baseUrl(\"https://api.dify.ai/v1\").build();\n\n// 创建消息\nParamMessage m = ParamMessage.builder().query(\"你是谁\").user(\"abc-123\").inputs(Map.of(\n        \"test\", \"value\",\n        \"file1\", ParamFile.builder()\n                .type(ParamFile.FileType.audio)\n                .transferMethod(ParamFile.TransferMethod.remote_url)\n                .build()\n)).build();\n\n// 发送阻塞消息\nDifyChatResult result = chatClient.sendMessages(m);\n\n// 发送流式消息\nCompletableFuture\u003cVoid\u003e future = client.sendMessagesAsync(m, (r) -\u003e {\n    System.out.println(\"ok: \" + r.getPayload().toJSONString());\n});\n```\n\n### 3、IAppFlowClient\n适用于 WorkFlow 类型应用，继承自 ```IAppBaseClient```，提供了工作流相关的API：\n```java\nIAppFlowClient flowClient = DifyClientBuilder.app().flow().apiKey(\"app-xxxx\").baseUrl(\"https://api.dify.ai/v1\").build();\n\n// 创建消息\nParamMessage m = ParamMessage.builder().user(\"abc-123\").inputs(Map.of(\n        \"name\", \"元宝宝\",\n        \"text\", \"Java为什么叫Java？\"\n)).build();\n\n// 阻塞式运行工作流\nDifyChatResult result = flowClient.runBlocking(m);\n\n// 流式运行工作流\nCompletableFuture\u003cVoid\u003e future = client.runStreaming(m, (r) -\u003e {\n    System.out.println(\"ok: \" + r.getPayload().toJSONString());\n});\n```\n\n### 4、IAppCompletion\n适用于 Completion 类型应用，继承自 ```IAppBaseClient```，提供了文本生成相关的API：\n```java\nIAppCompletion completion = DifyClientBuilder.completion().flow().apiKey(\"app-xxxx\").baseUrl(\"https://api.dify.ai/v1\").build();\n\n// 创建消息\nParamMessage m = ParamMessage.builder().query(\"Java为什么叫Java\").user(\"abc-123\").build();\n\n// 阻塞式运行\nDifyChatResult result = completion.sendMessages(m);\n\n// 流式运行\nCompletableFuture\u003cVoid\u003e future = completion.sendMessagesAsync(m, (r) -\u003e {\n    System.out.println(\"ok: \" + r.getPayload().toJSONString());\n});\n```\n\n## 创建 知识库 类型的 Client\n当前项目提供了内部知识库Client 与 外部知识库相关类型定义，其中外部知识库并没有做具体实现。\n\n### Dify内置知识库: IDifyDatasetClient\n具体API定义，请查阅 [```io.github.yuanbaobaoo.dify.dataset.IDifyDatasetClient```](https://github.com/yuanbaobaoo/dify-java-client/blob/master/src/main/java/io/github/yuanbaobaoo/dify/dataset/IDatasetClient.java)\n\n#### 参考案例\n```java\nIDatasetClient client = DifyClientBuilder.dataset().apiKey(\"dataset-xxxx\").baseUrl(\"https://api.dify.ai/v1\").build();\n\n// 声明参数\nParamDataset dataset = ParamDataset.builder()\n        .name(\"你的知识库名称\")\n        .build();\n\n// 创建空知识库\nclient.create(dataset);\n```\n\n#### Hero类\n项目中，针对知识库的工具类，除了提供了基于 ```IDatasetClient``` 的相关方法外，还提供了Hero类对知识库进行操作支持。\n具体使用哪种方式，取决于你的需求。\n\n- 案例一：新增文档\n```java\n// dify 配置\nDifyConfig config = DifyConfig.builder().server(\"https://api.dify.ai/v1\").apiKey(\"dataset-xxxx\").build();\n\n// 声明参数\nParamDocument document = ParamDocument.builder()\n        .name(\"测试文档\")\n        .text(\"你好啊你好吧\")\n        .indexingTechnique(DatasetConsts.IndexingTechnique.high_quality)\n        .processRule(ProcessRule.builder().mode(ProcessRule.Mode.automatic).build())\n        .build();\n```\n方式1、直接使用 IDatasetClient操作API\n```java\nIDatasetClient client = DifyClientBuilder.dataset().config(config).build();\nclient.insertDocByText(\"知识库ID\", document);\n```\n方式2、使用 DifyClientBuilder 创建一个 Hero对象\n```java\nDatasetHero dataset = DifyClientBuilder.dataset().config(config).of(\"知识库ID\");\ndataset.insertTxt(document);\n```\n方式3、直接创建Hero对象\n```java\nDatasetHero dataset = DatasetHero.of(\"知识库ID\", config);\ndataset.insertTxt(document);\n```\n\n- 案例2：更新文档\n```java\n// dify 配置\nDifyConfig config = DifyConfig.builder().server(\"https://api.dify.ai/v1\").apiKey(\"dataset-xxxx\").build();\n\n// 声明参数\nParamDocument document = ParamDocument.builder()\n        .name(\"测试.txt2\")\n        .text(\"又疑瑶台近，飞上青云端\")\n        .build();\n```\n方式1、直接使用 IDatasetClient操作API\n```java\nIDatasetClient client = DifyClientBuilder.dataset().config(config).build();\nclient.updateDocByText(\"知识库ID\", \"文档ID\", dataset);\n```\n方式2、使用 DifyClientBuilder 创建一个 Hero对象\n```java\nDocumentHero documentHero = DifyClientBuilder.dataset().config(config).ofDocument(\"知识库ID\", \"文档ID\");\ndocumentHero.updateByText(document);\n```\n方式3、直接创建Hero对象\n```java\nDocumentHero documentHero = DocumentHero.of(\"知识库ID\", \"文档ID\", config);\ndocumentHero.updateByText(document);\n```\n\n### Dify外部知识库: IKnowledgeService\n当前项目并未对知识库API做实现，只声明了相关参数对象和接口\n```java\npublic interface IKnowledgeService {\n    /**\n     * 知识检索\n     * @param apiKey Dify传递的API KEY\n     * @param args KnowledgeArgs\n     */\n    KnowledgeResult retrieval(String apiKey, KnowledgeArgs args);\n}\n```\n如果你有需求，可以基于声明的参数与接口进行实现即可，以下为参考代码“:\n- 1、声明一个endpoint\n```java\n/**\n * 检索本地知识库内容\n * @param args KnowledgeArgs\n */\n@PostMapping(\"/retrieval\")\npublic KnowledgeResult retrieval(@RequestBody(required = false) KnowledgeArgs args, HttpServletRequest request) {\n    return knowledgeService.retrieval(request.getHeader(\"Authorization\"), args);\n}\n```\n- 2、实现接口```io.github.yuanbaobaoo.dify.dataset.IKnowledgeService```\n```java\nclass KnowledgeService implements IKnowledgeService {\n    @Override\n    public KnowledgeResult retrieval(String apiKey, KnowledgeArgs args) {\n        // TODO 你的本地知识库检索逻辑\n    }\n}\n```\n\n## 创建 WebConsole Client\n用于模拟登录到 Dify Web控制台，并请求控制台的接口。\n- 参数\n```java\n WebConfig config = WebConfig.builder()\n            .server(\"https://api.dify.ai/\")\n            .userName(\"username\")\n            .password(\"password\")\n            .build();\n```\n- 登录\n```java\nIWebConsoleClient client = DifyClientBuilder.web(config).connect();\n```\n- 请求\n```java\n/**\n * get app list\n */\nDifyPage\u003cJSONObject\u003e res = client.queryApps(1, 30, null);\n\n/**\n * request custom api\n */\nString res = client.httpClient().requestJson();\n```\n\n## 请求自定义接口\n任意的Client对象，都拥有一个httpClient()方法，\n该方法会返回一个已经注入了 api key 和 server url 或者 login token属性的 SimpleHttpClient 对象，你可以使用该对象进行自定义接口请求。\n```java\nSimpleHttpClient http = client.httpClient();\n```\n\n## 异常处理\n- **DifyException**\n\u003e默认情况下，当正常的请求返回了 http status \u003e= 400 时，都会抛出一个异常对象 ```DifyException```。\n该对象接收了Dify返回的 ```status```、```code```、```message```、```params``` 这几个属性。\n当然你也可以通过 ```getOriginal()``` 方法获取原始返回内容。\n\n- **DifyClientException**\n\u003e除了 ```DifyException``` 之外，其他所有类型的异常都会被包装成非受检异常 ```DifyClientException``` 抛出","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuanbaobaoo%2Fdify-java-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyuanbaobaoo%2Fdify-java-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuanbaobaoo%2Fdify-java-client/lists"}