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

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# مصنِّفات الطلبات

> صنّف كل طلب بنموذج تختاره، وفق فئاتك الخاصة، وصفِّ السجلات والاستخدام حسب النتائج.

عرّف تصنيفًا، مثل القسم أو الجمهور أو نوع المهمة، ونموذجًا يطبقه، فيضع Phaseo على كل طلب مكتمل تسميات بإجابات ذلك النموذج. تُخزَّن كل إجابة كـ [تسمية طلب](https://phaseo.app/docs/ar/v1/guides/request-labels.md)، فتصفّي السجلات والاستخدام والتحليلات وتجمّعها حسبها تمامًا مثل التسميات التي ترسلها شيفرتك. استخدم مصنِّفًا عندما لا تعرف شيفرتك الفئة: لمن كُتب الموجّه، أو ما نوع العمل الذي يؤديه الوكيل، أو ما إذا كان الطلب يمس موضوعًا خاضعًا للتنظيم.

> [!NOTE]
>
> مصنِّفات الطلبات في [مرحلة بيتا](https://phaseo.app/docs/ar/v1/developers/feature-maturity.md)، وتُفعَّل لكل مساحة عمل عند الطلب. يديرها المالكون والمسؤولون في **الإعدادات ← المصنِّفات** أو عبر واجهة الإدارة `/v1/classifiers`، باستخدام [مفتاح إدارة](https://phaseo.app/docs/ar/v1/developers/management-api-keys.md) بنطاقات `classifiers:*`.

## كيف يُصنَّف الطلب

1. ينتهي الطلب وتُعاد استجابته إلى تطبيقك. لا يضيف التصنيف أي زمن استجابة أبدًا.
2. يبني Phaseo نصًا للطلب: تعليمات النظام، والرسائل، وأسماء الأدوات (لا مخططاتها)، ونتائج الأدوات. يقتصر كل دور على 4,000 حرف، وتُحجب الأسرار مثل مفاتيح API. إذا كان المصنِّف يشمل الاستجابة، تُضاف المخرجات المولَّدة أيضًا.
3. يختار نموذج المصنِّف من قيمك. يُتجاهل أي شيء يجيب به خارجها (راجع [اختر نموذجًا](#choose-a-model)).
4. تُخزَّن الإجابات كتسميات على الطلب، مع درجة الثقة لكل إجابة، قبل أن يظهر الطلب في سجلاتك.

تعمل المصنِّفات على طلبات `chat/completions` و`responses` و`messages` الناجحة. إذا فشل التصنيف أو انتهت مهلته، يظل الطلب مسجّلًا، لكن دون تلك التسميات.

## أنشئ مصنِّفًا

ابدأ من إعداد مسبق في لوحة التحكم أو أرسل التصنيف بنفسك:

```bash theme={null}
curl https://api.phaseo.app/v1/classifiers \
  -H "Authorization: Bearer $PHASEO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Department",
    "model": "google/gemini-2.5-flash-lite",
    "dimensions": [{
      "key": "department",
      "name": "Department",
      "allow_other": true,
      "values": [
        { "value": "engineering", "description": "Writing, reviewing, or debugging code" },
        { "value": "legal", "description": "Contracts, policies, and compliance" },
        { "value": "sales" },
        { "value": "support" }
      ]
    }],
    "sample_rate": 0.25,
    "monthly_budget_usd": 20
  }'
```

| الحقل | المعنى |
| - | - |
| `dimensions` | من 1 إلى 12 سؤالًا. يصبح كل `key` مفتاح التسمية؛ ويسرد كل بُعد من 2 إلى 50 قيمة (1 مع `allow_other`). |
| `multiple` | السماح بأكثر من قيمة واحدة لبُعد ما. تصبح كل قيمة تسمية مستقلة بالمفتاح نفسه. |
| `allow_other` | السماح للنموذج بالإجابة `other` عندما لا يناسب شيء. |
| `instructions` | إرشادات إضافية تُضاف إلى موجّه التصنيف، حتى 8,000 حرف. |
| `sample_rate` | نسبة الطلبات المؤهلة التي تُصنَّف، من `0.0001` إلى `1`. |
| `sample_by` | `request` يأخذ عينة من كل طلب. `session` يُدخل الجلسة أو يستبعدها كاملة ويعيد استخدام إجاباتها لمدة ساعة، فيُصنَّف تشغيل الوكيل الطويل مرة واحدة. |
| `input_scope` | `prompt` يصنّف الطلب. `prompt_and_response` يعرض على النموذج الاستجابة أيضًا. |
| `scope` | صنّف فقط الطلبات القادمة من هذه `key_ids` أو `app_ids` أو `models`، حتى 50 من كل منها. |
| `monthly_budget_usd` | أوقف المصنِّف مؤقتًا لبقية الشهر بتوقيت UTC بمجرد أن ينفق هذا المبلغ. |

يمكن أن تحتوي مساحة العمل على خمسة مصنِّفات كحد أقصى. تصل التغييرات إلى الـ Gateway خلال دقيقة تقريبًا.

## اختر نموذجًا

يمكن لأي نموذج نصي أو [نموذج قرار](https://phaseo.app/docs/ar/v1/api-reference/endpoint/decisions.md) أن يصنّف. يختار Phaseo طريقة سؤاله بحسب ما يدعمه مزوّدو النموذج:

| النموذج | كيف يُسأل |
| - | - |
| نموذج نصي يدعم المخرجات المنظَّمة | طلب `responses` بمخطط JSON صارم، فتكون كل إجابة إحدى قيمك. |
| نموذج قرار | طلب `decisions` بسؤال اختيار واحد لكل بُعد. البُعد ذو `multiple` يطرح سؤال نعم/لا لكل قيمة ويحتفظ بكل قيمة احتمالها 0.5 على الأقل (إذا احتاج المصنِّف إلى أكثر من 128 سؤالًا، يحصل مثل هذا البُعد على أفضل قيمة واحدة بدلًا من ذلك). الثقة هي احتمال النموذج نفسه. |
| النماذج النصية الأخرى | طلب `responses` يطلب صيغة JSON نفسها في الموجّه. تُتجاهل الإجابات خارج قيمك، لذا قد يبقى البُعد بلا تسمية أكثر. وهو أيضًا البديل عندما يرفض المزوّد المخطط. |

عادةً ما يكفي نموذج صغير وسريع. استخدم **جرِّبه على عيّنة** في محرر المصنِّف لفحص نموذج قبل الحفظ.

## صفِّ وجمّع حسب النتائج

إجابات المصنِّف تسميات طلبات عادية:

* في **السجلات** و**الاستخدام**، صفِّ حسب تسمية مثل `department` = `legal`.
* عبر API، استخدم `label_key` و`label_value`:

```text theme={null}
GET /v1/analytics?label_key=department&label_value=legal
```

* تتلقى وجهات [Broadcast](https://phaseo.app/docs/ar/v1/guides/integrations/observability.md) التسميات كسمات span بصيغة `phaseo.label.<key>`.

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

## التكلفة والخصوصية

* كل تصنيف طلب منفصل إلى نموذج المصنِّف، يُجرى بمفتاح API أو رمز OAuth نفسه الذي استخدمه الطلب الأصلي. يُحتسب بالسعر العادي لذلك النموذج ويتبع إعدادات المزوّد والاحتفاظ بالبيانات وBYOK في مساحة عملك.
* تحمل طلبات المصنِّف التسمية `phaseo.classifier` مضبوطة على معرّف المصنِّف، لذا يمكنك رؤية إنفاقها في **الاستخدام**. لا تُصنَّف هي نفسها ولا تُحتسب ضمن سياسات حدود المعدل لديك.
* أبقِ التكاليف منخفضة بنموذج صغير وسريع، أو بمعدل عينات، أو بأخذ عينات حسب الجلسة، أو بنطاق، أو بميزانية شهرية.
* لا يذهب النص إلا إلى نموذج المصنِّف. يُسجَّل طلب المصنِّف مثل أي طلب آخر، لذا فإن تخزين مدخلاته يتبع إعدادات التسجيل في مساحة عملك.


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