From 0dc68a2ce8ee8997ee76b15eba3d8ec8501300c4 Mon Sep 17 00:00:00 2001 From: omaralalwi Date: Thu, 17 Jul 2025 00:44:05 +0300 Subject: [PATCH] feat / support response format option --- README-AR.md | 39 +++++++++++++++++++++-- README-CN.md | 38 +++++++++++++++++++++-- README.md | 41 +++++++++++++++++++++++-- composer.json | 2 +- src/DeepSeekClient.php | 11 +++++++ src/Enums/Configs/TemperatureValues.php | 1 + src/Enums/Requests/QueryFlags.php | 1 + 7 files changed, 125 insertions(+), 8 deletions(-) diff --git a/README-AR.md b/README-AR.md index 8e9ad5a..cccbfc0 100644 --- a/README-AR.md +++ b/README-AR.md @@ -22,14 +22,13 @@ [الإنجليزية](README.md) | [الصينية](README-CN.md) -

- ## فهرس المحتويات - [✨ المميزات](#-المميزات) - [📦 التثبيت](#-التثبيت) - [🚀 البداية السريعة](#-البداية-السريعة) - [الاستخدام الأساسي](#الاستخدام-الأساسي) - [التكوين المتقدم](#التكوين-المتقدم) + - [تحذير هام عند استخدام وضع JSON](#-متطلب-وضع-json-في-deepseek) - [الاستخدام مع عميل HTTP من Symfony](#الاستخدام-مع-عميل-http-من-symfony) - [الحصول على قائمة النماذج](#الحصول-على-قائمة-النماذج) - [استدعاء الدوال](#استدعاء-الدوال) @@ -101,12 +100,48 @@ $response = $client ->withStream() ->withTemperature(1.2) ->setMaxTokens(8192) + ->setResponseFormat('text') ->query('Explain quantum computing in simple terms') ->run(); echo 'API Response:'.$response; ``` + +## ⚠️ متطلب وضع JSON في DeepSeek + +عند استخدام: + +```php +->setResponseFormat('json_object') +``` + +يجب أن يحتوي الـ برومبت على **كلمة "json"** بشكل واضح. + +وإلا سيتم رفض الطلب من قبل وترجع رسالة الخطأ التالية: + +> `"Prompt must contain the word 'json' in some form to use 'response_format' of type 'json_object'"` + +--- + +### 🚫 استخدام غير صحيح + +```php +->setResponseFormat('json_object') +->query('اشرح الحوسبة الكمومية بطريقة مبسطة') +``` + +### ✅ استخدام صحيح + +```php +->setResponseFormat('json_object') +->query('أجب بصيغة JSON صحيحة. اشرح الحوسبة الكمومية بطريقة مبسطة.') +``` + +> ✅ **نصيحة**: للحصول على أفضل النتائج، قم أيضًا بإعطاء مثال على صيغة JSON في الرسالة. + +--- + ### الاستخدام مع عميل HTTP من Symfony الحزمة مبنية مسبقاً مع `symfony Http client`، فإذا كنت بحاجة إلى استخدامها مع عميل HTTP الخاص بـ Symfony، فيمكن تحقيق ذلك بسهولة عن طريق تمرير `clientType:'symfony'` إلى دالة `build`. diff --git a/README-CN.md b/README-CN.md index b93bb99..0458b5c 100644 --- a/README-CN.md +++ b/README-CN.md @@ -22,14 +22,13 @@ [EN](README.md) | [AR](README-AR.md) -

- ## 目录 - [✨ 特性](#-特性) - [📦 安装](#-安装) - [🚀 快速入门](#-快速入门) - [基本用法](#基本用法) - [高级配置](#高级配置) + - [使用 JSON 模式的重要警告](#-deepseek-json-模式使用要求) - [使用 Symfony HttpClient](#使用-symfony-httpclient) - [获取模型列表](#获取模型列表) - [函数调用](#函数调用) @@ -100,12 +99,47 @@ $response = $client ->withStream() ->withTemperature(1.2) ->setMaxTokens(8192) + ->setResponseFormat('text') ->query('Explain quantum computing in simple terms') ->run(); echo 'API Response:'.$response; ``` + +## ⚠️ DeepSeek JSON 模式使用要求 + +当使用： + +```php +->setResponseFormat('json_object') +``` + +你的提示语（prompt）**必须包含 "json" 这个词**，否则 API 会返回以下错误： + +> `"Prompt must contain the word 'json' in some form to use 'response_format' of type 'json_object'"` + +--- + +### 🚫 错误示例 + +```php +->setResponseFormat('json_object') +->query('用简单的语言解释量子计算') +``` + +### ✅ 正确示例 + +```php +->setResponseFormat('json_object') +->query('请以有效的 JSON 格式回答，并用简单语言解释量子计算。') +``` + +> ✅ **建议**：为了获得更好的结果，最好也在提示中提供一个 JSON 示例，并强调 “只返回 JSON”。 + + +--- + ### Use with Symfony HttpClient the package already built with `symfony Http client`, if you need to use package with `symfony` Http Client , it is easy to achieve that, just pass `clientType:'symfony'` with `build` function. diff --git a/README.md b/README.md index 6ec9b7e..262f8ca 100644 --- a/README.md +++ b/README.md @@ -18,10 +18,9 @@ GitHub Stars - -[AR](README-AR.md) | [CN](README-CN.md) +

-

+[AR](README-AR.md) | [CN](README-CN.md) ## Table of Contents - [✨ Features](#-features) @@ -29,6 +28,7 @@ - [🚀 Quick Start](#-quick-start) - [Basic Usage](#basic-usage) - [Advanced Configuration](#advanced-configuration) + - [important warning with json mode](#-deepseek-json-mode-requirement) - [Use with Symfony HttpClient](#use-with-symfony-httpclient) - [Get Models List](#get-models-list) - [Function Calling](#function-calling) @@ -100,12 +100,47 @@ $response = $client ->withStream() ->setTemperature(1.2) ->setMaxTokens(8192) + ->setResponseFormat('text') // or "json_object" with careful . ->query('Explain quantum computing in simple terms') ->run(); echo 'API Response:'.$response; ``` +## ⚠️ DeepSeek JSON Mode Requirement + +When using: + +```php +->setResponseFormat('json_object') +``` + +Your prompt **must contain the word `"json"`** in some form. Otherwise, the API will reject the request with the following error: + +> `"Prompt must contain the word 'json' in some form to use 'response_format' of type 'json_object'"` + +--- + +### 🚫 Incorrect Usage + +```php +->setResponseFormat('json_object') +->query('Explain quantum computing in simple terms') +``` + +### ✅ Correct Usage + +```php +->setResponseFormat('json_object') +->query('Respond in valid JSON format. Explain quantum computing in simple terms.') +``` + +> ✅ **Tip**: For best results, also provide a JSON example or explicitly say: +> *"Respond only in valid JSON."* + + +--- + ### Use with Symfony HttpClient the package already built with `symfony Http client`, if you need to use package with `symfony` Http Client , it is easy to achieve that, just pass `clientType:'symfony'` with `build` function. diff --git a/composer.json b/composer.json index e4a48f2..e9e0a67 100644 --- a/composer.json +++ b/composer.json @@ -49,7 +49,7 @@ "role": "creator" } ], - "version": "2.0.5", + "version": "2.0.6", "require": { "php": "^8.1.0", "nyholm/psr7": "^1.8", diff --git a/src/DeepSeekClient.php b/src/DeepSeekClient.php index c44d0cd..62e39f5 100644 --- a/src/DeepSeekClient.php +++ b/src/DeepSeekClient.php @@ -50,6 +50,7 @@ class DeepSeekClient implements ClientContract protected float $temperature; protected int $maxTokens; + protected string $responseFormatType; /** * response result contract @@ -81,6 +82,7 @@ public function __construct(ClientInterface $httpClient) $this->endpointSuffixes = EndpointSuffixes::CHAT->value; $this->temperature = (float) TemperatureValues::GENERAL_CONVERSATION->value; $this->maxTokens = (int) TemperatureValues::MAX_TOKENS->value; + $this->responseFormatType = TemperatureValues::RESPONSE_FORMAT_TYPE->value; $this->tools = null; } @@ -93,6 +95,9 @@ public function run(): string QueryFlags::TEMPERATURE->value => $this->temperature, QueryFlags::MAX_TOKENS->value => $this->maxTokens, QueryFlags::TOOLS->value => $this->tools, + QueryFlags::RESPONSE_FORMAT->value => [ + 'type' => $this->responseFormatType + ], ]; $this->setResult((new Resource($this->httpClient, $this->endpointSuffixes))->sendRequest($requestData, $this->requestMethod)); @@ -192,6 +197,12 @@ public function setMaxTokens(int $maxTokens): self return $this; } + public function setResponseFormat(string $type): self + { + $this->responseFormatType = $type; + return $this; + } + public function buildQuery(string $content, ?string $role = null): array { return [ diff --git a/src/Enums/Configs/TemperatureValues.php b/src/Enums/Configs/TemperatureValues.php index b9b9a93..c09d315 100644 --- a/src/Enums/Configs/TemperatureValues.php +++ b/src/Enums/Configs/TemperatureValues.php @@ -13,4 +13,5 @@ enum TemperatureValues: string case CREATIVE_WRITING = "1.5"; case POETRY = "1.6"; case MAX_TOKENS = "4096"; + case RESPONSE_FORMAT_TYPE = "text"; } diff --git a/src/Enums/Requests/QueryFlags.php b/src/Enums/Requests/QueryFlags.php index 2b4b557..29e2586 100644 --- a/src/Enums/Requests/QueryFlags.php +++ b/src/Enums/Requests/QueryFlags.php @@ -10,4 +10,5 @@ enum QueryFlags: string case TEMPERATURE = 'temperature'; case MAX_TOKENS = 'max_tokens'; case TOOLS = 'tools'; + case RESPONSE_FORMAT = 'response_format'; }