> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-d2fddb8a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# الاستجابات المهيكلة

> أجبر نماذج الدردشة في Venice على إرجاع JSON يطابق مخططك باستخدام response_format وJSON Schema للحصول على مخرجات موثوقة وقابلة للتحليل.

أدرجت Venice الآن المخرجات المهيكلة عبر "response\_format" كحقل متاح في API. يتيح لك هذا الحقل توليد استجابات لمطالباتك تتبع تنسيقًا محددًا مسبقًا. مع هذه الطريقة الجديدة، تقل احتمالية أن تُهلوس النماذج بمفاتيح أو قيم غير صحيحة في الاستجابة، وهو ما كان أكثر شيوعًا عند المحاولة من خلال التلاعب بـ system prompt أو عبر function calling.

يستخدم حقل "response\_format" للمخرجات المهيكلة تنسيق OpenAI API، ومُوصَّف بشكل أكبر في دليل openAI [هنا](https://platform.openai.com/docs/guides/structured-outputs). أصدرت OpenAI أيضًا مقالًا تمهيديًا لاستخدام المخرجات المهيكلة ضمن API تحديدًا [هنا](https://openai.com/index/introducing-structured-outputs-in-the-api/). نظرًا لأن هذه وظيفة متقدمة، هناك حفنة من "العقبات" في أسفل هذه الصفحة يجب اتباعها.

هذه الوظيفة غير متاحة بشكل أصلي لجميع النماذج. يرجى الرجوع إلى قسم النماذج [هنا](https://docs.venice.ai/api-reference/endpoint/models/list?playground=open)، والبحث عن "supportsResponseSchema" للنماذج المعنية.

```json theme={null}
    {
      "id": "venice-uncensored",
      "type": "text",
      "object": "model",
      "created": 1726869022,
      "owned_by": "venice.ai",
      "model_spec": {
        "availableContextTokens": 32768,
        "capabilities": {
          "supportsFunctionCalling": true,
          "supportsResponseSchema": true,
          "supportsWebSearch": true
        },
```

### كيفية استخدام الاستجابات المهيكلة

لاستخدام "response\_format" بشكل صحيح، يمكنك تعريف مخططك بـ "properties" مختلفة، تمثل فئات المخرجات، كل منها بأنواع بيانات مكوّنة بشكل فردي. يمكن تضمين هذه الكائنات لإنشاء هياكل أكثر تقدمًا من المخرجات.

فيما يلي مثال على استدعاء API باستخدام response\_format لشرح عملية حل معادلة رياضية خطوة بخطوة.

يمكنك أن ترى أن الخصائص تم تكوينها لتتطلب كلًا من "steps" و "final\_answer" ضمن الاستجابة. ضمن التداخل، تتكون فئة steps من كل من "explanation" و "output"، كل منهما كسلاسل نصية.

```json theme={null}
curl --request POST \
  --url https://api.venice.ai/api/v1/chat/completions \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "venice-uncensored",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful math tutor."
    },
    {
      "role": "user",
      "content": "solve 8x + 31 = 2"
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "math_response",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "explanation": {
                  "type": "string"
                },
                "output": {
                  "type": "string"
                }
              },
              "required": ["explanation", "output"],
              "additionalProperties": false
            }
          },
          "final_answer": {
            "type": "string"
          }
        },
        "required": ["steps", "final_answer"],
        "additionalProperties": false
      }
    }
  }
}

```

فيما يلي الاستجابة التي تم تلقّيها من النموذج. يمكنك أن ترى أن الهيكل اتبع المتطلبات بتقديم "steps" مع "explanation" و "output" لكل خطوة، ثم "final answer".

```json theme={null}
{
  "steps": [
    {
      "explanation": "Subtract 31 from both sides to isolate the term with x.",
      "output": "8x + 31 - 31 = 2 - 31"
    },
    {
      "explanation": "This simplifies to 8x = -29.",
      "output": "8x = -29"
    },
    {
      "explanation": "Divide both sides by 8 to solve for x.",
      "output": "x = -29 / 8"
    }
  ],
  "final_answer": "x = -29 / 8"
}

```

على الرغم من أن هذا مثال بسيط، يمكن استقراء هذا في حالات استخدام أكثر تقدمًا مثل: استخراج البيانات، وتمارين Chain of Thought، وتوليد UI، وتصنيف البيانات والعديد من الحالات الأخرى.

### عقبات

فيما يلي بعض المتطلبات الرئيسية التي يجب وضعها في الاعتبار عند استخدام المخرجات المهيكلة عبر response\_format:

* قد تستغرق الطلبات الأولية باستخدام response\_format وقتًا أطول لتوليد استجابة. لن تشهد الطلبات اللاحقة نفس زمن الاستجابة الذي شهده الطلب الأول.

* للاستعلامات الأكبر، يمكن أن يفشل النموذج في الإكمال إذا تم الوصول إلى `max_tokens` أو timeout النموذج، أو إذا تم انتهاك أي حدود معدل

* تنسيق المخطط غير الصحيح سيؤدي إلى أخطاء عند الإكمال، عادة بسبب timeout

* على الرغم من أن response\_format يضمن أن يُخرج النموذج بطريقة معينة، إلا أنه لا يضمن أن النموذج قدم المعلومات الصحيحة بالداخل. المحتوى مدفوع بالـ prompt وأداء النموذج.

* المخرجات المهيكلة عبر response\_format غير متوافقة مع استدعاءات الدوال المتوازية

* مهم: يجب أن تتضمن جميع الحقول أو المعاملات علامة `required`. لجعل حقل اختياريًا، تحتاج إلى إضافة خيار `null` ضمن `type` للحقل، هكذا `"type": ["string", "null"]`&#x20;

* من الممكن جعل الحقول اختيارية بإعطاء خيار `null` ضمن الحقل المطلوب للسماح باستجابة فارغة.

* مهم: يجب تعيين `additionalProperties` إلى false ليعمل response\_format بشكل صحيح

* مهم: يجب تعيين `strict` إلى true ليعمل response\_format بشكل صحيح