> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# المعلمات

> مرجع تفصيلي لكل حقل من معلمات طلبات Phaseo الخاصة بالنص والتوجيه وتصحيح الأخطاء.

تقدّم هذه الصفحة مرجعًا تفصيليًا لكل حقل من معلمات الطلب التي يتيحها Phaseo。

استخدمها لمعرفة:

ما وظيفة المعلمة
نوع القيمة التي يتوقعها
النطاق المعتاد أو القيم المقبولة
ما إذا كانت تؤثر في الجودة أو التكلفة أو زمن الاستجابة أو سلوك التوجيه

إذا كنت تريد نصائح للضبط بدلًا من تعريفات الحقول، فراجع [معلمات الاستدلال](../guides/inference-parameters.mdx) و[أخذ العينات وفك الترميز](../guides/sampling-and-decoding.mdx)。

يختلف دعم المعلمات حسب نقطة النهاية والنموذج والمزوّد. يجمع جدول البدء السريع للنموذج دعم المزوّدين النشطين حاليًا لمسار محدد。

## نظرة سريعة

| المعلمة | النوع | الاستخدام |
| - | - | - |
| [`model`](#model) | `string` | تحديد معرّف نموذج البوابة المراد تشغيله. |
| [`stream`](#stream) | `boolean` | إرجاع مخرجات SSE تدريجيًا بدلًا من استجابة نهائية واحدة. |
| [`temperature`](#temperature) | `number` | زيادة العشوائية أو تقليلها. |
| [`top_p`](#top_p) | `number` | تضييق نطاق أخذ العينات بالنواة أو توسيعه. |
| [`top_k`](#top_k) | `integer` | حصر أخذ العينات في أفضل k من الرموز المرشحة. |
| [`max_tokens`](#max_tokens) | `integer` | تحديد طول المخرجات في المسارات التي ما زالت تستخدم اسم الحقل هذا. |
| [`max_output_tokens`](#max_output_tokens) | `integer` | تحديد طول المخرجات في المسارات التي تستخدم اسم الحقل الأحدث. |
| [`max_completion_tokens`](#max_completion_tokens) | `integer` | تحديد طول المخرجات في واجهات النص الأحدث المتوافقة مع OpenAI. |
| [`frequency_penalty`](#frequency_penalty) | `number` | الحد من تكرار الرموز والعبارات. |
| [`presence_penalty`](#presence_penalty) | `number` | تشجيع تغيير الموضوع أو المفردات. |
| [`repetition_penalty`](#repetition_penalty) | `number` | عنصر تحكم خاص بالمزوّد للحد من التكرار. |
| [`seed`](#seed) | `integer` | تحسين قابلية إعادة الإنتاج عند دعم المزوّد upstream لذلك. |
| [`stop`](#stop) | `string` or `string[]` | تحديد تسلسلات توقف صريحة. |
| [`logprobs`](#logprobs) / [`top_logprobs`](#top_logprobs) | `boolean` / `integer` | طلب بيانات احتمالات الرموز. |
| [`tools`](#tools), [`tool_choice`](#tool_choice) | `array`, `string`, `object` | التحكم في استدعاء الأدوات وتنفيذ الوظائف. |
| [`parallel_tool_calls`](#parallel_tool_calls) | `boolean` | السماح بتنفيذ الأدوات بالتتابع أو فرضه. |
| [`response_format`](#response_format) | `string` or `object` | مخرجات نصية عادية أو JSON أو مقيدة بمخطط. |
| [`json_schema`](#json_schema) | `object` | تحديد المخطط لمسارات المخرجات المنظمة. |
| [`structured_outputs`](#structured_outputs) | `boolean` | إشارة إلى القدرة على تقديم مخرجات موثوقة مقيدة بمخطط. |
| [`reasoning`](#reasoning) | `object` | إعدادات استدلال خاصة بالمزوّد. |
| [`reasoning_effort`](#reasoning_effort) | `string` | تقليل ميزانية الاستدلال أو زيادتها. |
| [`reasoning_tokens`](#reasoning_tokens) | `integer` | حد رموز أو حقل محاسبة خاص بالاستدلال. |
| [`include_reasoning`](#include_reasoning) | `boolean` | إرجاع محتوى الاستدلال أو ملخصاته عند توفر الدعم. |
| [`service_tier`](#service_tier) | `string` | اختيار مستوى طلب مدعوم مثل `fast` أو `ultrafast` أو `flex`. |
| [`prompt_cache_key`](#prompt_cache_key) | `string` | الحفاظ على ثبات التوجيه المراعي لذاكرة التخزين المؤقت للطلبات المرتبطة. |
| [`prompt_cache_options`](#prompt_cache_options) | `object` | ضبط وضع ذاكرة التخزين المؤقت للموجّهات وعناصر تحكم TTL في OpenAI. |
| [`cache_control`](#cache_control) | `object` | تطبيق تلميحات أو نقاط فصل لذاكرة prompt المؤقتة دون ارتباط بمزوّد. |
| [`prompt_cache_retention`](#prompt_cache_retention) | `string` | ضبط مدة الاحتفاظ بذاكرة prompt المؤقتة المتوافقة مع OpenAI. |
| [`provider`](#provider) | `object` | التأثير في التوجيه واختيار المزوّد. |
| [`provider_options`](#provider_options) | `object` | تمرير إعدادات المزوّد الأصلية عبر البوابة. |
| [`meta`](#meta) / [`usage`](#usage) | `boolean` | إرجاع بيانات وصفية إضافية أو تفاصيل الاستخدام في الاستجابة. |
| [`debug`](#debug) | `object` | طلب آثار التوجيه وبيانات التشخيص. |

## ملاحظات حول نقاط النهاية

تُدعم `service_tier` في واجهات طلبات النص الرئيسية:

* [Anthropic Messages](./endpoint/anthropic-messages.mdx)
* [Chat Completions](./endpoint/chat-completions.mdx)
* [Responses](./endpoint/responses.mdx)

استخدم `ultrafast` و`fast` (أو `priority` حيث يُدعم) و`flex` فقط عندما يدعمها مزيج النموذج والمزوّد المحدد. يختار `Ultrafast` أعلى مستوى سرعة مدعوم؛ ويستخدم `fast` و`priority` توجيه Fast وتسعيره نفسيهما. يكون `standard` افتراضيًا عند حذف `service_tier`.

ليست `Batch` قيمةً لـ `service_tier`. تستخدم طلبات الدُفعات واجهة Batch API منفصلة.

في طلبات Messages المتوافقة مع Anthropic، تكون قيم Anthropic الأصلية لدى المزوّد upstream هي `auto` و`standard_only`. وقد يطبّع Phaseo هذه القيم أو يعيّنها بين المزوّدين مع الحفاظ على السلوك المتوافق مع Anthropic في `/v1/messages`.

إذا كنت تستخدم SDK الرسمي لـ Anthropic مع عنوان base مخصص يشير إلى Phaseo، ففضّل قيم Anthropic الأصلية في `/v1/messages`. وبالنسبة لعناصر التحكم في الفئات الموحّدة بين المزوّدين مثل `ultrafast`, `priority` و`flex`، أو الاسم البديل `fast` لدى OpenAI، ففضّل طلبات HTTP الخام أو واجهات النص الأصلية للبوابة أو المتوافقة مع OpenAI.

## مرجع المعلمات

<span id="model" />

<h3 id="parameter-model"><code>model</code></h3>

يحدد معرّف نموذج البوابة للطلب。

| الحقل | القيمة |
| - | - |
| النوع | `string` |
| مطلوب | نعم |
| مثال | `openai/gpt-5-nano` |

استخدم معرّف النموذج الأساسي الظاهر في دليل البدء السريع لكل صفحة نموذج، إلا إذا كنت تريد عمدًا الاعتماد على اسم بديل مقبول. وتُعد المعرّفات الأساسية الخيار الأكثر أمانًا للأمثلة والأتمتة والتكاملات طويلة الأمد.

<span id="stream" />

<h3 id="parameter-stream"><code>stream</code></h3>

يعيد المخرجات تدريجيًا عبر Server-Sent Events بدلًا من انتظار نص استجابة نهائي واحد。

| الحقل | القيمة |
| - | - |
| النوع | `boolean` |
| الافتراضي | `false` |
| القيم المعتادة | `true`, `false` |

فعّل هذا الخيار لواجهات الدردشة أو عرض الرموز تباعًا أو الردود الطويلة التي يحسّن فيها ظهور المخرجات مبكرًا تجربة الاستخدام. وأوقفه إذا أردت استجابة JSON كاملة واحدة أو إعادة محاولات أبسط أو تحليلًا منظمًا أسهل。

ملاحظات:

يختلف دعم البث حسب نقطة النهاية.
يكون البث عادةً خيارًا للنقل، لا عنصرًا للتحكم في الجودة.
قد تختلف طريقة البث أيضًا حسب المزوّد في مسارات استدعاء الأدوات أو المخرجات المنظمة.

<span id="temperature" />

<h3 id="parameter-temperature"><code>temperature</code></h3>

يتحكم في مدى عشوائية اختيار الرموز.

| الحقل | القيمة |
| - | - |
| النوع | `number` |
| النطاق المعتاد | من `0.0` إلى `2.0` عند توفر الدعم |
| الافتراضي | خاص بالمزوّد والنموذج |
| قيمة بداية مناسبة | `0.2` to `0.7` |

تجعل القيم المنخفضة المخرجات أكثر تحفظًا وقابلية للتكرار. وتزيد القيم المرتفعة التنوع، ما قد يفيد في العصف الذهني أو الكتابة الإبداعية، لكنه قد يقلل الاتساق والالتزام بالمخطط.

استخدامات مناسبة:

استخراج المعلومات
التصنيف
مخرجات JSON أو المخطط
التوليد الإبداعي

إرشادات عملية:

ابدأ بقيمة منخفضة للمهام المنظمة.
غيّر `temperature` أو `top_p` أولًا، وليس كليهما معًا.
قد تؤدي الحرارة المرتفعة مع التكميم القوي إلى زيادة عدم الاستقرار.

<span id="top_p" />

<h3 id="parameter-top_p"><code>top\_p</code></h3>

يطبّق أخذ العينات بالنواة، فيحصر المرشحين في أصغر مجموعة رموز يبلغ مجموع احتمالاتها التراكمي `top_p`.

| الحقل | القيمة |
| - | - |
| النوع | `number` |
| النطاق المعتاد | من `0.0` إلى `1.0` عند توفر الدعم |
| الافتراضي | خاص بالمزوّد والنموذج |
| قيمة بداية مناسبة | `0.9` to `1.0` |

تجعل القيم المنخفضة النموذج يختار من نطاق احتمالي أضيق، ما ينتج عادةً مخرجات أكثر أمانًا وتركيزًا. وتتيح القيم الأعلى النظر في مجموعة أوسع من الرموز.

ملاحظات:

اضبط `top_p` إذا أردت تضييق مساحة البحث أو توسيعها دون تغيير temperature مباشرةً.
في معظم التطبيقات، تُعد قيمة معتدلة لـ `temperature` وقيمة `top_p` قريبة من 1.0 نقطة بداية معقولة.

<span id="top_k" />

<h3 id="parameter-top_k"><code>top\_k</code></h3>

يقيّد أخذ العينات في كل خطوة بأفضل k من الرموز المرشحة لدى المزوّدين الذين يدعمونه.

| الحقل | القيمة |
| - | - |
| النوع | `integer` |
| النطاق المعتاد | `>= 1` عند توفر الدعم |
| الافتراضي | خاص بالمزوّد والنموذج |

تضيّق قيم `top_k` المنخفضة خيارات النموذج وقد تجعل المخرجات أكثر قابلية للتوقع. وتوسّع القيم الأعلى مجموعة المرشحين.

ملاحظات:

لا يتوفر `top_k` لدى جميع المزوّدين.
اعتبره محددًا أكثر صراحةً لمجموعة الرموز مقارنةً بـ `top_p`.

<span id="max_tokens" />

<h3 id="parameter-max_tokens"><code>max\_tokens</code></h3>

يحد طول المخرجات في نقاط النهاية والمزوّدين الذين ما زالوا يستخدمون الحقل `max_tokens`.

| الحقل | القيمة |
| - | - |
| النوع | `integer` |
| النطاق المعتاد | `>= 1` |
| الافتراضي | خاص بالمزوّد والنموذج |

استخدمه للتحكم في التكلفة وزمن الاستجابة واحتمال اقتطاع المخرجات. إذا كانت القيمة منخفضة جدًا، فقد تبدو المخرجات غير مكتملة رغم أن النموذج عمل كما ينبغي.

<span id="max_output_tokens" />

<h3 id="parameter-max_output_tokens"><code>max\_output\_tokens</code></h3>

يحد طول المخرجات في المسارات التي تستخدم `max_output_tokens` بدلًا من `max_tokens`.

| الحقل | القيمة |
| - | - |
| النوع | `integer` |
| النطاق المعتاد | `>= 1` |
| الافتراضي | خاص بالمزوّد والنموذج |

يماثل `max_tokens` من حيث المعنى، لكن أرسل اسم الحقل الذي تتوقعه نقطة النهاية أو واجهة SDK المحددة.

<span id="max_completion_tokens" />

<h3 id="parameter-max_completion_tokens"><code>max\_completion\_tokens</code></h3>

يحد طول المخرجات في واجهات النص الأحدث المتوافقة مع OpenAI التي تستخدم `max_completion_tokens`.

| الحقل | القيمة |
| - | - |
| النوع | `integer` |
| النطاق المعتاد | `>= 1` |
| الافتراضي | خاص بالمزوّد والنموذج |

هذا حقل آخر لميزانية رموز المخرجات. استخدم الاسم المتوقع لنقطة النهاية بدلًا من خلط أسماء بديلة لطول المخرجات في بنية طلب واحدة.

<span id="frequency_penalty" />

<h3 id="parameter-frequency_penalty"><code>frequency\_penalty</code></h3>

يقلل تكرار الرموز بما يتناسب مع عدد مرات ظهورها سابقًا.

| الحقل | القيمة |
| - | - |
| النوع | `number` |
| النطاق المعتاد | غالبًا من `-2.0` إلى `2.0` عند توفر الدعم |
| الافتراضي | غالبًا `0` |

ارفع القيمة إذا دخل النموذج في حلقات أو كرر عبارات أو أفرط في استخدام الصياغة نفسها.

<span id="presence_penalty" />

<h3 id="parameter-presence_penalty"><code>presence\_penalty</code></h3>

يقلل إعادة استخدام الرمز بمجرد ظهوره، ما قد يساعد النموذج على استكشاف موضوعات أو صياغات جديدة.

| الحقل | القيمة |
| - | - |
| النوع | `number` |
| النطاق المعتاد | غالبًا من `-2.0` إلى `2.0` عند توفر الدعم |
| الافتراضي | غالبًا `0` |

بالمقارنة مع `frequency_penalty`، يتحكم هذا عادةً في التجديد على نطاق أوسع بدلًا من عدد مرات التكرار.

<span id="repetition_penalty" />

<h3 id="parameter-repetition_penalty"><code>repetition\_penalty</code></h3>

يطبّق سلوكًا خاصًا بالمزوّد للحد من التكرار خارج حقول العقوبة التقليدية المتوافقة مع OpenAI.

| الحقل | القيمة |
| - | - |
| النوع | `number` |
| النطاق المعتاد | خاص بالمزوّد والنموذج، وغالبًا ما يكون بين `0.0` و`2.0` |
| الافتراضي | خاص بالمزوّد والنموذج |

يشبه الغرض منه `frequency_penalty` و`presence_penalty`، لكن دلالته تختلف أكثر حسب المزوّد. تعامل معه كسلوك أصلي للمزوّد، لا كعنصر تحكم موحّد تمامًا.

<span id="seed" />

<h3 id="parameter-seed"><code>seed</code></h3>

يطلب أخذ عينات حتميًا عندما يدعم المزوّد upstream التوليد باستخدام seed.

| الحقل | القيمة |
| - | - |
| النوع | `integer` |
| الافتراضي | غير مضبوط |

استخدمه لتصحيح الأخطاء واختبارات التراجع وإعادة إنتاج السلوك قدر ما تسمح به المنصة upstream. يحسّن التوليد باستخدام seed قابلية إعادة الإنتاج، لكنه لا يضمن حتمية تامة لدى جميع المزوّدين أو عند تغييرات البنية التحتية.

<span id="stop" />

<h3 id="parameter-stop"><code>stop</code></h3>

يحدد تسلسلًا واحدًا أو أكثر لإنهاء التوليد مبكرًا.

| الحقل | القيمة |
| - | - |
| النوع | `string` or `string[]` |
| الافتراضي | غير مضبوط |
| الاستخدام الشائع | حدود المحلل ونهايات القوالب وعلامات البروتوكول |

يفيد عند الحاجة إلى حدود صارمة للمخرجات، مثل التوقف قبل التذييل أو فاصل الأداة أو القسم الاصطناعي التالي.

<span id="logprobs" />

<h3 id="parameter-logprobs"><code>logprobs</code></h3>

يطلب بيانات وصفية لاحتمالات الرموز عند توفرها.

| الحقل | القيمة |
| - | - |
| النوع | `boolean` |
| الافتراضي | `false` |

يفيد هذا أساسًا في التحليل والتقييم والترتيب وتصحيح الأخطاء ومسارات العمل المرتبطة بالثقة. ولا تحتاج إليه عادةً في استجابات المنتجات المعتادة.

<span id="top_logprobs" />

<h3 id="parameter-top_logprobs"><code>top\_logprobs</code></h3>

يطلب أفضل الرموز المرشحة البديلة لكل موضع في المخرجات مع احتمالاتها اللوغاريتمية.

| الحقل | القيمة |
| - | - |
| النوع | `integer` |
| النطاق المعتاد | خاص بالمزوّد، وغالبًا من `0` إلى `20` |
| يتطلب | `logprobs: true` |

استخدمه لفحص فروع الرموز البديلة بدلًا من رمز المخرجات المختار فقط.

<span id="tools" />

<h3 id="parameter-tools"><code>tools</code></h3>

يعرّف الأدوات أو الوظائف القابلة للاستدعاء في مسارات عمل النماذج التي تستخدم الأدوات.

| الحقل | القيمة |
| - | - |
| النوع | `array` |
| الافتراضي | غير مضبوط |

استخدم مخطط الأدوات المتوافق مع OpenAI ما لم تنص وثائق نقطة النهاية على خلاف ذلك. تصف تعريفات الأدوات ما يمكن للنموذج استدعاؤه، لا ما يجب عليه استدعاؤه.

<span id="tool_choice" />

<h3 id="parameter-tool_choice"><code>tool\_choice</code></h3>

يتحكم فيما إذا كان يمكن للنموذج استدعاء الأدوات تلقائيًا أو يجب ألا يستدعيها أو يتعين عليه استخدام أداة محددة.

| الحقل | القيمة |
| - | - |
| النوع | `string` or `object` |
| القيم الشائعة | `none`, `auto`, `required` |

استخدم `none` إذا أردت المحتوى فقط، و`auto` إذا كان للنموذج أن يقرر، وقيمًا أكثر صرامة إذا كان التنسيق اللاحق يتطلب استدعاء أداة.

<span id="parallel_tool_calls" />

<h3 id="parameter-parallel_tool_calls"><code>parallel\_tool\_calls</code></h3>

يسمح باستدعاءات الأدوات المتزامنة أو يمنعها في واجهات API المتوافقة.

| الحقل | القيمة |
| - | - |
| النوع | `boolean` |
| الافتراضي | خاص بنقطة النهاية والمزوّد |

عطّله إذا كانت الأنظمة اللاحقة تتطلب تنفيذًا متتابعًا بدقة أو آثارًا جانبية مرتبة أو آثار agent أبسط.

<span id="response_format" />

<h3 id="parameter-response_format"><code>response\_format</code></h3>

يطلب تنسيق مخرجات محددًا مثل النص العادي أو JSON أو الاستجابات المقيدة بمخطط.

| الحقل | القيمة |
| - | - |
| النوع | `string` or `object` |
| الافتراضي | خاص بنقطة النهاية والمزوّد |

تعتمد البنى المقبولة بدقة على نقطة النهاية ومحوّل المزوّد. استخدمه عند الحاجة إلى أكثر من نص حر، خصوصًا لاستجابات JSON ومسارات الاستخراج المنظم.

<span id="structured_outputs" />

<h3 id="parameter-structured_outputs"><code>structured\_outputs</code></h3>

يشير إلى دعم الاستجابات المنظمة أو المقيدة بمخطط على المسار ومجموعة المزوّدين المحددين.

| الحقل | القيمة |
| - | - |
| النوع | `boolean` |
| المعنى | إشارة إلى القدرة وليست عنصر ضبط مباشر |

تساعدك هذه القيمة في جداول البدء السريع على معرفة ما إذا كان endpoint والمزوّدون النشطون يدعمون مسارات المخرجات المنظمة بموثوقية. والأفضل اعتبارها بيانات وصفية عن الدعم.

<span id="json_schema" />

<h3 id="parameter-json_schema"><code>json\_schema</code></h3>

يوفر مخطط JSON المستخدم لفرض المخرجات المنظمة على النماذج ونقاط النهاية المتوافقة.

| الحقل | القيمة |
| - | - |
| النوع | `object` |
| يُستخدم مع | مسارات المخرجات المنظمة أو الاستجابات المقيدة بمخطط |

استخدمه عندما يحتاج تطبيقك إلى حقول مضمونة أو استخراج ذي أنواع محددة أو عقد استجابة صارم. اجعل المخططات ضيقة ومخصصة للمهمة لتحسين الالتزام بها.

<span id="reasoning" />

<h3 id="parameter-reasoning"><code>reasoning</code></h3>

يتضمن إعدادات استدلال خاصة بالمزوّد لواجهات API القادرة على الاستدلال.

| الحقل | القيمة |
| - | - |
| النوع | `object` |
| الافتراضي | غير مضبوط |

قد يشمل ذلك، حسب المسار، التفعيل أو مستوى الجهد أو ميزانية الرموز أو مستوى التفصيل أو إرجاع محتوى الاستدلال.

<span id="reasoning_effort" />

<h3 id="parameter-reasoning_effort"><code>reasoning\_effort</code></h3>

يطلب ميزانية استدلال أقل أو أعلى عندما تتيح نقطة النهاية والنموذج هذا التحكم.

| الحقل | القيمة |
| - | - |
| النوع | `string` |
| القيم الشائعة | خاص بالمزوّد، وغالبًا ما تكون القيم مثل `minimal` و`low` و`medium` و`high` و`none` |
| الافتراضي | خاص بالمزوّد والنموذج |

قد يحسّن مستوى الجهد الأعلى مهام الاستدلال الصعبة، لكنه يزيد زمن الاستجابة واستهلاك الرموز. وغالبًا ما يناسب الجهد الأقل الطلبات الأسرع والأقل تكلفة.

<span id="reasoning_tokens" />

<h3 id="parameter-reasoning_tokens"><code>reasoning\_tokens</code></h3>

يمثل حقل رموز خاصًا بالاستدلال عند توفر الدعم.

| الحقل | القيمة |
| - | - |
| النوع | `integer` |
| الافتراضي | خاص بالمزوّد والنموذج |

قد يكون ذلك، حسب المسار، عنصر تحكم في الطلب أو حدًا أو حقل محاسبة في الاستجابة، وليس معلمة طلب مدعومة عالميًا.

<span id="include_reasoning" />

<h3 id="parameter-include_reasoning"><code>include\_reasoning</code></h3>

يطلب إرفاق محتوى الاستدلال أو ملخصاته في الاستجابات عند توفر الدعم.

| الحقل | القيمة |
| - | - |
| النوع | `boolean` |
| الافتراضي | `false` |

استخدمه بحذر. قد تكون بيانات الاستدلال أكبر حجمًا، وقد لا تتوفر في كل النماذج، وقد لا تلائم استجابات الإنتاج التي لا تحتاج إلى تفاصيل تشخيصية إضافية.

<span id="service_tier" />

<h3 id="parameter-service_tier"><code>service\_tier</code></h3>

يحدد فئة توجيه أو تسعير مدعومة في واجهات النص المتوافقة.

| الحقل | القيمة |
| - | - |
| النوع | `string` |
| القيم المدعومة | `standard`, `fast`, `ultrafast`, `priority`, `flex` |
| الافتراضي | `standard` |

استخدم `ultrafast` و`fast` (أو `priority` حيث يُدعم) و`flex` فقط عندما يدعمها مزيج النموذج والمزوّد المختار. يختار `Ultrafast` أعلى مستوى سرعة مدعوم؛ ويستخدم `fast` و`priority` توجيه Fast وتسعيره نفسيهما. احذف الحقل للبقاء على المستوى القياسي الافتراضي.

يحوّل Phaseo داخليًا قيم الفئات الموحّدة في البوابة إلى عناصر تحكم أصلية لدى المزوّد، ما يتيح للمتصلين استخدام قيم `service_tier` نفسها عبر واجهات النص المدعومة.

ملاحظات:

`Batch` مسار API منفصل وليس قيمةً لفئة الخدمة.
يختلف الدعم حسب نقطة النهاية والمزوّد.

<span id="prompt_cache_key" />

<h3 id="parameter-prompt_cache_key"><code>prompt\_cache\_key</code></h3>

يوفر مفتاح ارتباط ثابتًا بالتخزين المؤقت للتوجيه المراعي لذاكرة prompt المؤقتة.

| الحقل | القيمة |
| - | - |
| النوع | `string` |
| الاستخدام | توجيه ثابت لمطالبات مخزنة مؤقتًا ومرتبطة ببعضها |

استخدمه عندما تشترك مجموعة طلبات في بادئات prompt ثابتة ويُفضّل أن تستخدم المزوّد upstream أو المنطقة نفسها متى أمكن. ويمكن لـ Phaseo استنتاج ارتباط التخزين المؤقت من سياق الطلب أيضًا، لكن المفتاح الصريح أفضل للمحادثات الطويلة وجلسات agent ومسارات العمل المتكررة.

<span id="prompt_cache_options" />

<h3 id="parameter-prompt_cache_options"><code>prompt\_cache\_options</code></h3>

يمرر عناصر تحكم ذاكرة التخزين المؤقت لموجّهات OpenAI عبر مسارات OpenAI المدعومة.

| الحقل | القيمة |
| - | - |
| النوع | `object` |
| الحقول الشائعة | `mode`, `ttl` |
| Astra TTL | `30m` |

في GPT-6 Astra، استخدم `{"mode":"explicit","ttl":"30m"}` للتخزين المؤقت الصريح للموجّهات. يحتفظ Phaseo بهذا الكائن أثناء تطبيع الطلب ويرسله إلى OpenAI دون تغيير.

<span id="cache_control" />

<h3 id="parameter-cache_control"><code>cache\_control</code></h3>

يطبّق سياسة لذاكرة prompt المؤقتة مستقلة عن المزوّد على واجهات طلبات النص المدعومة.

| الحقل | القيمة |
| - | - |
| النوع | `object` |
| الحقول الشائعة | `type`, `ttl`, `scope` |
| الاستخدام | التخزين التلقائي للمطالبات مؤقتًا ونقاط الفصل الصريحة |

استخدم `cache_control` في المستوى الأعلى لطلبات Chat Completions وResponses وAnthropic Messages لتمرير تلميح التخزين المؤقت نفسه عبر المخطط المشترك للبوابة. ويمكنك أيضًا وضعه على كتل المحتوى المدعومة عند الحاجة إلى نقاط فصل صريحة.

قيم TTL المعتادة هي `5m` و`1h` حسب دعم المزوّد والنموذج. وتظل الأسماء البديلة الخاصة بالمزوّد، مثل `provider_options.anthropic.cache_control` و`provider_options.google.cache_control`، مقبولة للتكاملات الأصلية.

<span id="prompt_cache_retention" />

<h3 id="parameter-prompt_cache_retention"><code>prompt\_cache\_retention</code></h3>

يحدد سياسة الاحتفاظ بذاكرة prompt المؤقتة المتوافقة مع OpenAI في الطلبات المدعومة الموجّهة إلى OpenAI.

| الحقل | القيمة |
| - | - |
| النوع | `string` |
| مثال | `24h` |
| الاستخدام | الاحتفاظ بذاكرة prompt المؤقتة لدى OpenAI |

استخدمه لتمرير خيارات الاحتفاظ بذاكرة OpenAI المؤقتة دون تضمينها داخل الخيارات الخاصة بالمزوّد. يظل الاسم البديل `provider_options.openai.prompt_cache_retention` مقبولًا. وعند وجود القيمتين، تكون الأولوية لقيمة `prompt_cache_retention` في المستوى الأعلى.

<span id="provider" />

<h3 id="parameter-provider"><code>provider</code></h3>

يتضمن قيود التوجيه وتفضيلات المزوّد.

| الحقل | القيمة |
| - | - |
| النوع | `object` |
| الاستخدام | قواعد التوجيه واختيار المزوّد ومتطلبات الامتثال |

استخدمه لتحديد المزوّدين upstream المسموح لهم بتنفيذ الطلب وكيفية ترتيبهم ومتطلبات الامتثال الواجب استيفاؤها.

تشمل الحقول الشائعة:

| الحقل | النوع | الغرض |
| - | - | - |
| `order` | `string[]` | ترتيب المزوّدين المفضل. |
| `only` | `string[]` | يقصر التوجيه على مزوّدين محددين. |
| `ignore` | `string[]` | يستبعد مزوّدين محددين. |
| `include_alpha` | `boolean` | يسمح بمزوّدي alpha في قرارات التوجيه. |
| `sort` | `string` or `object` | يرتب المزوّدين غالبًا حسب `price` أو `latency` أو `throughput`. |
| `required_execution_region` | `string` | يقصر التنفيذ على منطقة مطلوبة. |
| `required_data_region` | `string` | يقصر معالجة البيانات على منطقة مطلوبة. |
| `require_zero_data_retention` | `boolean` | يشترط مزوّدين يلتزمون بقيود الاحتفاظ الصفري بالبيانات. |
| `max_price` | `object` | يحدد حدودًا قصوى لتكاليف prompt أو الإكمال أو الصور أو الصوت أو الطلب. |
| `quantizations` | `string[]` | يشترط عرضًا مؤهلًا تتطابق فيه كمية الكتالوج مع إحدى هذه القيم. |

يتبع `quantizations` مفردات توجيه المزوّدين المتوافقة مع OpenRouter، ويُقبل ضمن `provider` أو `routing`. ولا يراعي التطابق حالة الأحرف ويتجاهل المسافات والواصلات والشرطات السفلية؛ وتُعد الأسماء الواضحة مثل `float8`/`FP8` و`bfloat16`/`BF16` أسماء بديلة. تُستبعد العروض التي تفتقر إلى بيانات كمية عند وجود هذا المرشح. وإذا لم يطابق أي عرض مؤهل، تعيد البوابة خطأً يتضمن القيم المطلوبة والمتاحة حاليًا بدلًا من التوجيه بصمت إلى نسخة مختلفة.

<span id="provider_options" />

<h3 id="parameter-provider_options"><code>provider\_options</code></h3>

يتضمن إعدادات تمرير خاصة بالمزوّد ينبغي ألا تُطبّع ضمن بنية طلب البوابة المشتركة.

| الحقل | القيمة |
| - | - |
| النوع | `object` |
| الاستخدام | عناصر تحكم أصلية للمزوّد |

تشمل الأمثلة:

* `openai.context_management`
* `openai.prompt_cache_retention`
* `anthropic.cache_control`
* `google.cache_control`
* `google.cached_content`

استخدمه عند الحاجة إلى ميزة أصلية للمزوّد مع إبقاء بقية الطلب ضمن المخطط المشترك للبوابة. فضّل `cache_control` في المستوى الأعلى لتلميحات التخزين المؤقت العامة و`prompt_cache_retention` في المستوى الأعلى للاحتفاظ المتوافق مع OpenAI.

للاطلاع على أمثلة تخزين prompt مؤقتًا حسب المزوّد عبر Chat Completions وResponses وAnthropic Messages، راجع [تخزين prompt مؤقتًا](../guides/prompt-caching.mdx).

<span id="meta" />

<h3 id="parameter-meta"><code>meta</code></h3>

يطلب بيانات وصفية إضافية في الاستجابة عند توفر الدعم.

| الحقل | القيمة |
| - | - |
| النوع | `boolean` |
| الافتراضي | خاص بنقطة النهاية |

استخدمه عند الحاجة إلى بيانات وصفية إضافية غير أساسية في الاستجابة للتصحيح أو التحليلات أو الفحص اللاحق.

<span id="usage" />

<h3 id="parameter-usage"><code>usage</code></h3>

يطلب تفاصيل احتساب الاستخدام عند توفر الدعم.

| الحقل | القيمة |
| - | - |
| النوع | `boolean` |
| الافتراضي | خاص بنقطة النهاية |

يفيد ذلك عند الحاجة إلى تضمين احتساب الرموز أو الاستخدام صراحةً في متن الاستجابة بدلًا من الاعتماد على الترويسات أو لوحات المعلومات فقط.

<span id="debug" />

<h3 id="parameter-debug"><code>debug</code></h3>

يتيح تشخيصًا مضبوطًا للطلب والتوجيه.

| الحقل | القيمة |
| - | - |
| النوع | `object` |
| الاستخدام | للتطوير واستكشاف الأخطاء فقط |

تشمل حقول التصحيح المدعومة:

| الحقل | النوع | الغرض |
| - | - | - |
| `enabled` | `boolean` | يُفعّل وضع التصحيح للطلب. |
| `return_upstream_request` | `boolean` | يتضمن حمولة الطلب upstream بعد تحويلها. |
| `return_upstream_response` | `boolean` | يتضمن حمولة الاستجابة upstream عند توفرها. |
| `trace` | `boolean` | يعيد آثار التوجيه أو التصحيح. |
| `trace_level` | `summary` or `full` | يتحكم في مستوى تفصيل الآثار. |

قد تتضمن بيانات التصحيح سياقًا حساسًا للطلب. استخدمها في التطوير أو البيئات الخاضعة لرقابة صارمة فقط.

## مثال على الطلب

```json theme={null}
{
  "model": "openai/gpt-5-nano",
  "input": "Summarize this changelog.",
  "stream": false,
  "temperature": 0.3,
  "max_output_tokens": 300,
  "provider": {
    "order": ["openai", "anthropic"],
    "ignore": ["some-provider"],
    "sort": "latency",
    "required_execution_region": "eu",
    "require_zero_data_retention": true
  },
  "debug": {
    "enabled": true,
    "trace": true,
    "trace_level": "summary"
  }
}
```

## شروحات مفصلة

إذا أردت إرشادات أعمق حول الضبط بدلًا من مرجع الحقول فقط، فراجع الصفحات التالية:

* [معلمات الاستدلال](../guides/inference-parameters.mdx) لنصائح عملية حول temperature وtop\_p وtop\_k وحدود الرموز وتسلسلات التوقف وسير الضبط
* [أخذ العينات وفك الترميز](../guides/sampling-and-decoding.mdx) لفهم تأثير العشوائية والعقوبات وضوابط فك الترميز في سلوك النموذج

## صفحات ذات صلة

* [معلمات الاستدلال](../guides/inference-parameters.mdx)
* [أخذ العينات وفك الترميز](../guides/sampling-and-decoding.mdx)
* [البث](../guides/streaming.mdx)
* [الحدود](./limits.mdx)
* [الأخطاء وتصحيحها](./errors.mdx)

إذا كنت تنفذ معالجة المعلمات بصفتك agent:

* استخدم مهارات المستودع للتحقق من المخططات وبنية الطلب
* احتفظ بالمفاتيح غير المعروفة الخاصة بالمزوّد في مسارات التمرير عند السماح بذلك
* تحقق من توافق نقطة النهاية قبل الجمع بين الحقول المتقدمة مثل الأدوات أو البث أو خيارات التصحيح


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.