> ## 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 لإبقاء تنفيذ المزوّد ومعالجة بياناته ضمن مسارات الاتحاد الأوروبي أو الولايات المتحدة الموثّقة لدى Phaseo. يمكنك استخدام التوجيه الإقليمي مع Chat Completions وResponses وMessages دون تغيير معرّفات النماذج أو مفاتيح API.

<Warning>
  التوجيه الإقليمي لا يضمن حاليًا إقامة البيانات من البداية إلى النهاية. يقيّد Phaseo اختيار المزوّدين ويستخدم تلميح موضع Cloudflare بالقرب من المنطقة المحددة، لكن أنظمة الحسابات والفوترة والتخزين المؤقت والعمليات المشتركة قد تعالج البيانات خارج تلك المنطقة.
</Warning>

## اختيار نقطة نهاية

| المنطقة | عنوان URL الأساسي | السلوك |
| - | - | - |
| الاتحاد الأوروبي | `https://eu.api.phaseo.app/v1` | يتطلب مسارات مزوّدين يكون التنفيذ ومنطقة البيانات فيها ضمن الاتحاد الأوروبي |
| الولايات المتحدة | `https://us.api.phaseo.app/v1` | يتطلب مسارات مزوّدين يكون التنفيذ ومنطقة البيانات فيها ضمن الولايات المتحدة |
| عالمي | `https://api.phaseo.app/v1` | يستخدم سياسة التوجيه العالمي القياسية |

اسم المضيف الإقليمي هو حد السياسة. لا يمكن للطلب تجاوزه بقيمة متعارضة لـ`required_execution_region` أو `required_data_region`.

## استخدام SDK الخاص بـPhaseo

اضبط `region` عند إنشاء العميل. يستخدم كل طلب مدعوم يرسله هذا العميل عنوان URL الأساسي الإقليمي المقابل.

<CodeGroup>
  ```ts TypeScript theme={null}
  import { Phaseo } from "@phaseo/sdk";

  const phaseo = new Phaseo({
    apiKey: process.env.PHASEO_API_KEY!,
    region: "eu",
  });

  const response = await phaseo.responses.create({
    model: "openai/gpt-5-mini",
    input: "Summarize this note in one sentence.",
  });

  console.log(response.output_text);
  ```

  ```python Python theme={null}
  import os
  from phaseo import Phaseo

  phaseo = Phaseo(
      api_key=os.environ["PHASEO_API_KEY"],
      region="eu",
  )

  response = phaseo.responses.create({
      "model": "openai/gpt-5-mini",
      "input": "Summarize this note in one sentence.",
  })

  print(response.get("output_text"))
  ```
</CodeGroup>

استخدم `"us"` للتوجيه إلى الولايات المتحدة. احذف `region` أو استخدم `"global"` للتوجيه العالمي. ترفض حزمة SDK الإعدادات التي تجمع `region` مع `baseUrl` أو `base_url` مخصص، لأن الخيارين سيحددان مضيفين متنافسين.

## استخدام Chat Completions

```bash theme={null}
curl https://eu.api.phaseo.app/v1/chat/completions \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-mini",
    "messages": [
      {"role": "user", "content": "Write a two-line status update."}
    ]
  }'
```

## استخدام Responses

```bash theme={null}
curl https://eu.api.phaseo.app/v1/responses \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-mini",
    "input": "Extract the three most important actions from this note."
  }'
```

## استخدام Messages

تقبل نقطة نهاية Messages تنسيق طلبات Anthropic مع الحفاظ على القيد الإقليمي نفسه على المزوّدين.

```bash theme={null}
curl https://us.api.phaseo.app/v1/messages \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "anthropic/claude-sonnet-4.6",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "Summarize this incident report."}
    ]
  }'
```

## ميزات الطلبات المدعومة

يدعم التوجيه الإقليمي حاليًا:

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

ترفض نقاط النهاية الإقليمية:

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

يُسمح بأدوات الدوال لأنها تُنفّذ في تطبيقك. وتُحظر الأداة المستضافة لدى المزوّد لأن موقع تنفيذها قد لا يطابق السياسة الإقليمية.

## اكتشاف النماذج المتاحة في منطقة

استدعِ `/v1/models` عبر اسم المضيف الإقليمي نفسه الذي تستخدمه للإنشاء:

```bash theme={null}
curl https://eu.api.phaseo.app/v1/models \
  -H "Authorization: Bearer $PHASEO_API_KEY"
```

تحتوي الاستجابة فقط على نماذج لها مسار مزوّد نشط وتشمل مناطق التنفيذ والبيانات المُعلنة فيه المنطقة المحددة معًا. ولا تعلن إلا عن Chat Completions وResponses وMessages بإدخال وإخراج نصيين.

يتضمن كل عرض بياناته الوصفية الإقليمية:

```json theme={null}
{
  "provider": { "id": "example-eu", "name": "Example EU" },
  "residency": {
    "execution_regions": ["eu"],
    "data_regions": ["eu"]
  }
}
```

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

## التحقق من البوابة المحددة

تتضمن الاستجابات الإقليمية:

```http theme={null}
X-Phaseo-Gateway-Region: eu
```

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

<Note>
  يحدد الترويس سياسة Phaseo الإقليمية التي عالجت الطلب. وهو ليس دليلًا على ضمان إقامة تنفيذ Cloudflare في المنطقة.
</Note>

## السلوك عند الفشل

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

| الخطأ | المعنى | الإجراء |
| - | - | - |
| `regional_endpoint_not_supported` | المسار غير متاح على Workers الإقليمية | استخدم إحدى نقاط نهاية النص الثلاث المدعومة أو API العالمية |
| `regional_non_text_content` | يحتوي الطلب على وسائط أو ملف أو مرفق | أزل المحتوى غير النصي أو استخدم API العالمية |
| `regional_non_text_output` | يطلب الطلب استجابة غير نصية | اطلب مخرجات نصية أو استخدم API العالمية |
| `regional_hosted_tool_not_supported` | طُلبت أداة مستضافة لدى المزوّد | استخدم أداة دالة يحددها العميل أو API العالمية |
| `deployment_region_conflict` | يحدد الطلب أو الإعداد المسبق منطقة أخرى | أزل الإعداد المتعارض |
| لا يوجد مسار مزوّد متاح | لا يوجد مزوّد سليم يلبي متطلبات النموذج والسياسة الإقليمية | اختر نموذجًا آخر تعيده نقطة النهاية الإقليمية `/v1/models` |

## ما يغطيه التوجيه الإقليمي

بالنسبة إلى طلب إنشاء مقبول، يشترط Phaseo أن يعلن مسار المزوّد المحدد عن الشرطين التاليين:

1. تنفيذ النموذج في المنطقة المحددة
2. معالجة بيانات المطالبات والإجابات في المنطقة المحددة

يطبق Phaseo هذه المتطلبات بعد دمج الإعدادات المسبقة وقواعد التوجيه الديناميكي، لذا لا يمكن لهذه الميزات إضعاف سياسة اسم المضيف. إذا لم يتطابق أي مزوّد، يتوقف الطلب قبل تنفيذ النموذج لدى المزوّد.

## القيود الحالية

لا يضمن هذا الإصدار الأولي بقاء دورة حياة الطلب كاملة داخل المنطقة المحددة:

* تختار تلميحات موضع Cloudflare Workers موقعًا قريبًا من منطقة السحابة المضبوطة، لكنها لا تنشئ حدًا للامتثال.
* تستخدم حسابات Phaseo والمصادقة والفوترة والبيانات الوصفية للطلبات بنية Supabase تحتية مشتركة.
* لا ترتبط Cloudflare KV وسجلات استدعاء Workers بمنطقة محددة.
* تُقيّد الطلبات الفرعية إلى المزوّدين بنقطة نهاية المزوّد المحدد، لا بإعداد موضع Cloudflare.
* لا يقتصر وصول الدعم والعمليات على العاملين في المنطقة المحددة.

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

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

* [التوجيه والمسارات البديلة](./routing-and-fallbacks.mdx)
* [النماذج المحددة بالمزوّد](./provider-qualified-models.mdx)
* [الإعدادات المسبقة](./presets.mdx)
* [استدعاء الأدوات](./tool-calling.mdx)


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