> ## 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.

# إرسال JSON منظّم باستخدام الإعدادات المسبقة وPython SDK

> استخدم Python SDK الرسمي والإعدادات المسبقة والمخرجات المنظّمة وتصحيح الأخطاء على مستوى الطلب من دون اللجوء إلى استدعاءات HTTP الخام.

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

## الهدف

* إبقاء شيفرة استدعاء Python صغيرة
* التوجيه باستخدام slug لإعداد مُسبق بدلًا من تثبيت نموذج في الشيفرة
* طلب مخرجات منظّمة صارمة
* الاحتفاظ ببيانات استجابة وصفية كافية لتصحيح أخطاء التوجيه أو سلوك الإضافات

## 1. ابدأ بعميل مشترك

```python theme={null}
import os

from phaseo import Phaseo

gateway = Phaseo(api_key=os.environ["PHASEO_API_KEY"])
```

أعد استخدام العميل نفسه بدلًا من إنشاء عميل لكل طلب.

## 2. انقل القيم الافتراضية المستقرة إلى إعداد مُسبق

أنشئ إعدادًا مسبقًا ضمن **لوحة التحكم -> الإعدادات -> الإعدادات المسبقة** عندما ينبغي تثبيت القيم التالية عبر عدة مستدعين:

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

بعد إنشاء الإعداد المسبق، يمكن إبقاء شيفرة استدعاء Python موجزة.

## 3. اطلب شكل JSON صارمًا

```python theme={null}
response = gateway.generate_response(
    {
        "preset": "release-summary",
        "input": "Summarize the last 24 hours of deployment activity.",
        "response_format": {
            "type": "json_schema",
            "name": "release_summary",
            "schema": {
                "type": "object",
                "required": ["summary", "risk_level"],
                "properties": {
                    "summary": {"type": "string"},
                    "risk_level": {
                        "type": "string",
                        "enum": ["low", "medium", "high"],
                    },
                },
                "additionalProperties": False,
            },
        },
        "plugins": [{"id": "response-healing"}],
        "meta": True,
    }
)
```

أسباب فعالية هذا الشكل:

* يُبقي `preset` إعدادات التوجيه والمطالبة الافتراضية خارج شيفرة التطبيق
* يجعل `response_format` العقد واضحًا
* يمكن لـ `plugins` استعادة JSON غير السليم شبه الصالح عندما يسمح سير العمل بذلك
* يحتفظ `meta` بتفاصيل التوجيه وتنفيذ الإضافات لتصحيح الأخطاء

## 4. حلّل JSON وسجّل معرّفات التشغيل

```python theme={null}
import json

message_text = ""
for item in response.get("output", []):
    if item.get("type") != "message":
        continue
    for part in item.get("content", []):
        if part.get("type") == "output_text":
            message_text = part.get("text", "")
            break

payload = json.loads(message_text)

print("response_id:", response.get("id"))
print("selected_provider:", response.get("meta", {}).get("routing", {}).get("selected_provider"))
print("plugin_executions:", response.get("meta", {}).get("plugin_executions"))
print(payload)
```

يكفي هذا عادةً للعاملين في Python لربط سطر سجل واحد في التطبيق بما يلي:

* نافذة تفاصيل الطلب في لوحة التحكم
* تشخيصات التوجيه
* بيانات تنفيذ الإضافات الوصفية

## 5. صحّح الأخطاء قبل إضافة تجاوزات

إذا وُجّه طلب بطريقة مختلفة عن المتوقع:

1. افتح الطلب ضمن **Gateway -> الاستخدام**
2. افحص تشخيصات التوجيه والمزوّدين المرشحين
3. افحص بيانات تنفيذ الإضافات الوصفية إذا كان الطلب يتضمن JSON منظّمًا
4. غيّر الإعداد المسبق بعد أن توضّح السجلات ما حدث فعلًا فقط

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

## 6. حافظ على التوافق مع التخزين المؤقت عند إعادة الاستخدام

إذا فعّل الإعداد المسبق تخزين الاستجابات مؤقتًا:

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

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

## أدلة ذات صلة

* [إطلاق الإعدادات المسبقة وتصحيح أخطاء التوجيه](./preset-rollout-and-routing-debug.mdx)
* [استخدام تخزين الاستجابات المؤقت مع الإعدادات المسبقة](./response-caching-with-presets.mdx)
* [إصلاح استجابات JSON المنظّمة](./response-healing-for-structured-json.mdx)
* [نظرة عامة على Python SDK](../sdk-reference/python/overview.mdx)


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