我要提问
ARTICLE DETAIL

资讯详情

前沿编程新知与开发实战干货的深度解读。

Dify PHP SDK 实战:在 PHP 应用中集成 Dify 聊天、补全与工作流 API

Dify PHP SDK 实战:在 PHP 应用中集成 Dify 聊天、补全与工作流 API Dify PHP SDK 实战在 PHP 应用中集成 Dify 聊天、补全与工作流 API【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/difyDify 在仓库中提供了官方 PHP SDKsdks/php-client/它基于 Guzzle 封装了 Dify Service API/v1的核心能力聊天应用chat-messages、补全应用completion-messages、工作流运行workflows/run、文件上传、语音转文字等接口。读完本文你将掌握 SDK 的安装配置方式、全部可用方法的参数含义并能结合服务端源码理解每个方法实际调用的 HTTP 端点与返回处理细节。环境要求与安装方式根据 sdks/php-client/README.md 的说明SDK 的运行环境要求非常轻量PHP 7.2 或更高版本Guzzle HTTP 客户端库guzzlehttp/guzzle ^7.9。仓库中的 composer.json 也印证了这一点{ require: { php: 7.2, guzzlehttp/guzzle: ^7.9 }, autoload: { files: [dify-client.php] } }SDK 本身不是一个通过 Packagist 发布的 composer 包而是以“单文件客户端 Composer 自动加载”的方式集成。README 给出了两种使用路径直接体验示例进入sdks/php-client/目录执行composer install即可用目录内的composer.lock锁定依赖集成到已有项目把 dify-client.php 复制到自己项目中然后在项目的composer.json中合并如下配置再运行composer install composer dump-autoload{ require: { guzzlehttp/guzzle: ^7.9 }, autoload: { files: [path/to/dify-client.php] } }需要注意 README 中的一条提示Guzzle 并未在 7.9 之外的版本上做过测试^7.9是已验证的版本基线使用其他版本“可以试试但不保证”。autoload.files机制会把dify-client.php中的 4 个类DifyClient、CompletionClient、ChatClient、WorkflowClient在 Composer 自动加载时直接引入因此无需手动require该文件。SDK 类结构与请求机制整个 SDK 只有一个源文件 dify-client.php采用“一个基类 三个按应用类型划分的子类”的结构这与 Dify 服务端的三种应用形态聊天、文本生成、工作流一一对应。基类 DifyClient认证与请求封装从 dify-client.php#L5-L31 的源码看构造函数的逻辑是public function __construct($api_key, $base_url null) { $this-api_key $api_key; $this-base_url $base_url ?? https://api.dify.ai/v1/; $this-client new Client([ base_uri $this-base_url, headers [ Authorization Bearer . $this-api_key, Content-Type application/json, ], ]); }这里有两个关键点默认服务端点是 Dify 云服务https://api.dify.ai/v1/。如果你的 Dify 是自部署self-hosted实例必须通过第二个参数$base_url传入自己实例的地址形如https://your-dify.example.com/v1/这一点 README 虽未展开但从构造函数签名可以直接确认所有请求统一携带Authorization: Bearer api_key请求头这里的 API Key 就是 Dify 控制台为应用发布的 API Token。所有网络调用收敛到send_request()方法dify-client.php#L22-L31protected function send_request($method, $endpoint, $data null, $params null, $stream false) { $options [ json $data, // 请求体JSON query $params, // URL 查询参数 stream $stream, // 是否流式 ]; $response $this-client-request($method, $endpoint, $options); return $response; }值得注意的设计是SDK不解析响应体而是把 Guzzle 的Psr\Http\Message\ResponseInterface原样返回由调用方自己json_decode($response-getBody(), true)处理。这给了使用方最大的灵活性但也意味着错误处理需要自己判断 HTTP 状态码。子类与端点映射从源码看三个子类各自封装的端点与服务端 api/controllers/service_api/ 下的路由完全对应客户端类方法服务端端点服务端实现DifyClientmessage_feedback()POST /messages/{message_id}/feedbacksmessage.pyDifyClientget_application_parameters()GET /parametersapp.pyDifyClientfile_upload()POST /files/uploadfile.pyDifyClienttext_to_audio()POST /text-to-audioaudio.pyDifyClientget_meta()GET /metaapp.pyCompletionClientcreate_completion_message()POST /completion-messagescompletion.pyChatClientcreate_chat_message()POST /chat-messagescompletion.py 所在应用模块ChatClientget_suggestions()GET /messages/{message_id}/suggestedmessage.py#L226ChatClientstop_message()POST /chat-messages/{task_id}/stop—ChatClientget_conversations()GET /conversationsconversation.py#L159ChatClientget_conversation_messages()GET /messagesmessage.pyChatClientrename_conversation()PATCH /conversations/{conversation_id}conversation.pyChatClientdelete_conversation()DELETE /conversations/{conversation_id}conversation.pyChatClientaudio_to_text()POST /audio-to-textaudio.py#L48WorkflowClientrun()POST /workflows/runworkflow.py#L287WorkflowClientstop()POST /workflows/tasks/{task_id}/stopworkflow.py服务端这些路由挂载在 Blueprintservice_api上其url_prefix/v1见 api/controllers/service_api/init.py#L6这与 SDK 默认 base_url 末尾的/v1/相互印证——SDK 的每个短端点如chat-messages最终都会拼到/v1/chat-messages。快速上手README 官方示例全解以下示例完整继承自 sdks/php-client/README.md并补充了参数说明。基本初始化?php require vendor/autoload.php; $apiKey your-api-key-here; // 替换为 Dify 控制台中应用的真实 API Key $difyClient new DifyClient($apiKey);补全应用Completion// 创建补全客户端 $completionClient new CompletionClient($apiKey); $response $completionClient-create_completion_message( array(query Who are you?), // $inputs应用启动所需的输入变量 blocking, // $response_modeblocking 或 streaming user_id // $user终端用户标识必填 );对照 dify-client.php#L96-L104 的实现该方法把参数组装为inputs/response_mode/user/files四个字段并且当$response_mode streaming时会自动开启 Guzzle 的流式模式stream true这样 SSE 流可以边接收边处理避免一次性缓冲整个响应。聊天应用Chat// 创建聊天客户端 $chatClient new ChatClient($apiKey); $response $chatClient-create_chat_message( array(), // $inputs Who are you?, // $query用户问题 user_id, // $user blocking, // $response_mode默认 blocking $conversation_id // $conversation_id首轮对话传 null之后传上轮返回的会话 ID );从 dify-client.php#L108-L121 的实现可以看到$conversation_id只有在非空时才会被加入请求体——这与服务端“首轮不带会话 ID 新建会话、后续轮次带上以延续上下文”的协议一致。多模态附带图片/文件提问VisionSDK 支持通过files参数传入文件描述数组两种transfer_method// 方式一远程 URL图片直接以 URL 提供 $fileForVision [ [ type image, transfer_method remote_url, url your_image_url ] ]; // 方式二本地文件需先通过 file_upload() 上传拿到文件 ID // $fileForVision [ // [ // type image, // transfer_method local_file, // url your_file_id // 实际填上传接口返回的 id // ] // ]; // 补全应用 视觉模型如 gpt-4-vision $response $completionClient-create_completion_message( array(query Describe this image.), blocking, user_id, $fileForVision ); // 聊天应用 视觉模型 $response $chatClient-create_chat_message( array(), Describe this image., user_id, blocking, $conversation_id, $fileForVision );文件上传与响应解析// File Upload以 multipart/form-data 上传一次一个文件 $fileForUpload [ [ tmp_name /path/to/file/filename.jpg, // 服务器上的本地文件路径 name filename.jpg // 提交给 API 的文件名 ] ]; $response $difyClient-file_upload(user_id, $fileForUpload); $result json_decode($response-getBody(), true); echo upload_file_id: . $result[id]; // 返回的 id 即 local_file 方式引用的文件标识SDK 的file_upload()dify-client.php#L46-L73内部通过prepareMultipart()把$data如user字段与文件流拼装为 Guzzle 的 multipart 结构每个文件的字段名固定为file。服务端对该接口的约束可以在 api/controllers/service_api/app/file.py 中逐条确认请求体必须包含file字段否则返回 400no_file_uploaded一次只允许上传一个文件否则 400too_many_files文件必须带文件名且扩展名不在安全黑名单内分别对应filename_not_exists_error、file_extension_blocked超过大小限制返回 413file_too_large类型不允许返回 415unsupported_file_type。成功时返回 201 与文件对象含id、name、size、mime_type等字段该id正是上面local_file引用方式中要填的值。应用参数与消息反馈// 获取应用的参数配置应用定义的输入变量、建议问题等 $response $difyClient-get_application_parameters(user_id); // 对某条消息提交评分反馈rating 常见取值为 like / dislike以 API 约定为准 $response $difyClient-message_feedback($message_id, $rating, user_id);message_feedback()对应服务端POST /messages/{message_id}/feedbacks这是 Dify 在控制台中查看“消息评分统计”的数据来源。会话管理与更多方法README 末尾列出了“Other available methods”源码中它们的具体签名如下可一并纳入你的业务封装// 获取会话列表user 必填first_id/limit/pinned 用于游标分页与置顶过滤 $chatClient-get_conversations($user, $first_id, $limit, $pinned); // 获取会话下的消息列表conversation_id 可选不传则跨会话按 user 查询 $chatClient-get_conversation_messages($user, $conversation_id, $first_id, $limit); // 重命名会话auto_generate 为 true 时由系统自动根据内容生成标题 $chatClient-rename_conversation($conversation_id, $name, $auto_generate, $user); // 删除会话 $chatClient-delete_conversation($conversation_id, $user); // 获取某条消息后的建议追问应用需开启 suggested questions $chatClient-get_suggestions($message_id, $user); // 停止一个进行中的流式任务传入该任务的 task_id $chatClient-stop_message($task_id, $user);从源码结构看get_conversations()与get_conversation_messages()采用first_id limit的游标式分页参数与服务端 conversation.py#L159-L224 中返回has_more 游标的分页响应结构相匹配rename_conversation()实际发送PATCH方法且请求体携带auto_generate标志。此外还有两个在 README 示例中未展示、但源码已实现的能力工作流应用WorkflowClient-run($inputs, $response_mode, $user)调用POST /workflows/run触发工作流运行WorkflowClient-stop($task_id, $user)可停止指定任务dify-client.php#L189-L205语音能力DifyClient-text_to_audio($text, $user, $streaming)与ChatClient-audio_to_text($audio_file, $user)multipart 上传音频分别对应服务端的/text-to-audio与/audio-to-text路由api/controllers/service_api/app/audio.pyDifyClient-get_meta($user)则用于获取应用元信息。实践注意事项API Key 与 base_urlKey 必须替换 README 中的占位符your-api-key-here且必须来自目标应用自部署用户务必传第二个参数指定自己的/v1/基址否则会请求到 Dify 云服务。user参数是全局必填项从源码看几乎每个方法都要求传入user标识服务端用它做终端用户维度的数据隔离如“上传文件仅当前 end-user 可用”生产环境建议映射为你系统内的稳定用户 ID。流式模式response_mode传streaming时SDK 会自动打开 Guzzle stream响应体是逐块到达的 SSE 流需要按 Dify 流式事件协议逐行解析而不能直接json_decode整个 body。错误处理SDK 不抛业务异常也不解析错误体HTTP 4xx/5xx 时请自行检查$response-getStatusCode()并读取响应 JSON 中的code/message字段例如文件上传的 400/413/415 各错误码见上文服务端说明。文件上传路径tmp_name参数名来自 PHP$_FILES的惯用结构适合直接转发浏览器上传的临时文件但生产代码建议校验文件存在性与类型后再上传。小结Dify 的 PHP SDK 以单文件、零额外依赖除 Guzzle的形态提供了对 Dify Service API 的完整覆盖聊天、补全、工作流三大应用类型的运行入口加上会话管理、消息反馈、建议追问、文件上传与语音互转等配套能力。它的价值在于把 Bearer 认证、multipart 组装、流式开关这些繁琐细节收敛进DifyClient基类业务代码只需关注参数本身。结合服务端 api/controllers/service_api/ 下的路由实现你可以进一步核对每个端点的请求/响应 schema把 SDK 稳定地嵌入 PHP 业务系统中。该 SDK 以 MIT License 发布见 sdks/php-client/README.md。【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表