> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-locadex-parallel-t9n-main-irpovz79o3kkpgs4.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> توثيق دوال الذكاء الاصطناعي

# دوال الذكاء الاصطناعي

دوال الذكاء الاصطناعي هي دوال مضمّنة في ClickHouse يمكنك استخدامها لاستدعاء الذكاء الاصطناعي أو إنشاء embeddings للعمل مع بياناتك، واستخراج المعلومات، وتصنيف البيانات، وغير ذلك...

<Note>
  دوال الذكاء الاصطناعي تجريبية. اضبط [`allow_experimental_ai_functions`](/ar/reference/settings/session-settings#allow_experimental_ai_functions) لتمكينها.
</Note>

<Note>
  قد تُرجع دوال الذكاء الاصطناعي مخرجات غير متوقعة. وتعتمد النتيجة بدرجة كبيرة على جودة الموجّه والنموذج المستخدم.
</Note>

تشترك جميع الدوال في بنية تحتية موحّدة توفّر ما يلي:

* **فرض الحصص**: حدود لكل استعلام على الرموز ([`ai_function_max_input_tokens_per_query`](/ar/reference/settings/session-settings#ai_function_max_input_tokens_per_query), [`ai_function_max_output_tokens_per_query`](/ar/reference/settings/session-settings#ai_function_max_output_tokens_per_query)) واستدعاءات واجهة برمجة التطبيقات ([`ai_function_max_api_calls_per_query`](/ar/reference/settings/session-settings#ai_function_max_api_calls_per_query)).
* **إعادة المحاولة مع زيادة تدريجية في التأخير**: تتم إعادة محاولة الإخفاقات العابرة ([`ai_function_max_retries`](/ar/reference/settings/session-settings#ai_function_max_retries)) باستخدام تأخير أُسّي متزايد ([`ai_function_retry_initial_delay_ms`](/ar/reference/settings/session-settings#ai_function_retry_initial_delay_ms)).

<div id="configuration">
  ## التهيئة
</div>

تشير دوال AI إلى **مجموعة مُسمّاة** تخزّن بيانات اعتماد الموفّر والتهيئة. الوسيط الأول لكل دالة هو اسم هذه المجموعة.

مثال على تعليمة لإنشاء مجموعة مُسمّاة تتضمن بيانات اعتماد الموفّر:

```sql theme={null}
CREATE NAMED COLLECTION ai_credentials AS
    provider = 'openai',
    endpoint = 'https://api.openai.com/v1/chat/completions',
    model = 'gpt-4o-mini',
    api_key = 'sk-...';
```

<div id="named-collection-parameters">
  ### معلمات المجموعة المسماة
</div>

| المعلمة       | النوع  | الافتراضي | الوصف                                                                                                                                          |
| ------------- | ------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`    | String | —         | موفّر النموذج. القيم المدعومة: `'openai'` و`'anthropic'`. انظر الملاحظة أدناه.                                                                 |
| `endpoint`    | String | —         | عنوان URL لنقطة نهاية واجهة برمجة التطبيقات.                                                                                                   |
| `model`       | String | —         | اسم النموذج (مثل `'gpt-4o-mini'` و`'text-embedding-3-small'`).                                                                                 |
| `api_key`     | String | —         | مفتاح المصادقة الخاص بالموفّر. اختياري: عند عدم تحديده، لا يُرسَل ترويس المصادقة، مما يتيح الاستهداف لخوادم متوافقة مع OpenAI لا تتطلب مصادقة. |
| `max_tokens`  | UInt64 | `1024`    | الحد الأقصى لعدد الرموز الناتجة لكل استدعاء لواجهة برمجة التطبيقات.                                                                            |
| `api_version` | String | —         | سلسلة إصدار واجهة برمجة التطبيقات. تستخدمها Anthropic (`'2023-06-01'`).                                                                        |

<Note>
  يمكن استخدام أي واجهة برمجة تطبيقات متوافقة مع OpenAI (مثل vLLM وOllama وLiteLLM) عبر ضبط `provider = 'openai'` وتوجيه `endpoint` إلى خدمتك.
</Note>

<div id="query-level-settings">
  ### إعدادات على مستوى الاستعلام
</div>

تَرِد جميع الإعدادات المتعلقة بالذكاء الاصطناعي في [الإعدادات](/ar/reference/settings/session-settings) تحت البادئة `ai_function_`.

<div id="restricting-endpoint-hosts">
  ### تقييد مضيفات نقطة النهاية
</div>

يمثل عنوان URL الخاص بـ `endpoint` في مجموعة مسماة للذكاء الاصطناعي وجهةً خارجية يتصل بها الخادم باستخدام هويته الخاصة، وقد يتضمن — إذا جرى تحديده — `api_key` الخاص بالمجموعة المسماة في رؤوس الطلب. افتراضيًا، يسمح ClickHouse بأي مضيف. لحصر الدوال في مجموعة محددة من الموفّرين، اضبط [`remote_url_allow_hosts`](/ar/reference/settings/server-settings/settings#remote_url_allow_hosts) في إعدادات الخادم، على سبيل المثال:

```xml theme={null}
<remote_url_allow_hosts>
    <host>api.openai.com</host>
    <host>api.anthropic.com</host>
</remote_url_allow_hosts>
```

لاحظ أن هذا الإعداد عام على مستوى الخادم ويسري على جميع الميزات التي تستخدم HTTP.

<div id="supported-providers">
  ## الموفّرون المدعومون
</div>

| الموفّر   | قيمة `provider` | وظائف الدردشة | ملاحظات                             |
| --------- | --------------- | ------------- | ----------------------------------- |
| OpenAI    | `'openai'`      | نعم           | الموفّر الافتراضي.                  |
| Anthropic | `'anthropic'`   | نعم           | يستخدم نقطة النهاية `/v1/messages`. |

<div id="observability">
  ## Observability
</div>

يُتتبَّع نشاط AI function عبر [ProfileEvents](/ar/reference/system-tables/query_log) في ClickHouse:

| ProfileEvent      | Description                                                                                  |
| ----------------- | -------------------------------------------------------------------------------------------- |
| `AIAPICalls`      | عدد طلبات HTTP المُرسلة إلى موفّر الذكاء الاصطناعي.                                          |
| `AIInputTokens`   | إجمالي رموز الإدخال المستهلَكة.                                                              |
| `AIOutputTokens`  | إجمالي رموز الإخراج المستهلَكة.                                                              |
| `AIRowsProcessed` | عدد الصفوف التي تلقّت نتيجة.                                                                 |
| `AIRowsSkipped`   | عدد الصفوف التي جرى تخطيها (تم تجاوز الحصة، أو حدث خطأ مع `ai_function_throw_on_error = 0`). |

استعلم عن هذه الأحداث:

```sql theme={null}
SELECT
    ProfileEvents['AIAPICalls'] AS api_calls,
    ProfileEvents['AIInputTokens'] AS input_tokens,
    ProfileEvents['AIOutputTokens'] AS output_tokens
FROM system.query_log
WHERE query_id = 'query_id'
AND type = 'QueryFinish'
ORDER BY event_time DESC;
```

{/*AUTOGENERATED_START*/}

<div id="aiClassify">
  ## aiClassify
</div>

أُضيف في: v26.4.0

يُصنّف النص المُعطى ضمن إحدى الفئات المتاحة باستخدام موفّر LLM.

ترسل الدالة النص مع موجّه تصنيف ثابت وتنسيق استجابة من نوع JSON-schema
يقيّد النموذج بحيث يُرجع تسمية واحدة فقط من التسميات المزوّدة. وعندما تُعاد الاستجابة على شكل كائن JSON
بالصيغة `{"category": "..."}`، تُستخرج التسمية ويُعاد نصّها.

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

**الصياغة**

```sql theme={null}
aiClassify(collection, text, categories[, temperature])
```

**الأسماء البديلة**: `AIClassify`

**المعاملات**

* `collection` — اسم مجموعة مسماة تحتوي على بيانات اعتماد الموفّر والتهيئة. [`String`](/ar/reference/data-types/string)
* `text` — النص المطلوب تصنيفه. [`String`](/ar/reference/data-types/string)
* `categories` — قائمة ثابتة بتسميات الفئات المرشحة. [`Array(String)`](/ar/reference/data-types/array)
* `temperature` — درجة حرارة أخذ العينات التي تتحكم في مستوى العشوائية. القيمة الافتراضية: `0.0`. [`Float64`](/ar/reference/data-types/float)

**القيمة المُعادة**

إحدى تسميات الفئات المقدَّمة، أو القيمة الافتراضية لنوع العمود (سلسلة فارغة) إذا فشل الطلب وكان `ai_function_throw_on_error` معطّلًا. [`String`](/ar/reference/data-types/string)

**أمثلة**

**تصنيف المشاعر**

```sql title=Query theme={null}
SELECT aiClassify('ai_credentials', 'I love this product!', ['positive', 'negative', 'neutral'])
```

```response title=Response theme={null}
positive
```

**تصنيف عمود**

```sql title=Query theme={null}
SELECT body, aiClassify('ai_credentials', body, ['bug', 'question', 'feature']) AS kind FROM issues LIMIT 5
```

```response title=Response theme={null}
```

<div id="aiEmbed">
  ## aiEmbed
</div>

أُضيفت في: v26.6.0

تُنشئ متجه تضمين للنص المحدد باستخدام موفّر الذكاء الاصطناعي المُهيّأ.

ترسل الدالة النص إلى نقطة نهاية التضمين المُهيّأة وتُرجع المتجه الناتج بصيغة `Array(Float32)`.
ضمن كتلة واحدة من الصفوف، تُجمَّع المُدخلات في دفعات يصل حجمها إلى
[`ai_function_embedding_max_batch_size`](/ar/reference/settings/session-settings#ai_function_embedding_max_batch_size)
عنصرًا لكل طلب HTTP لتقليل العبء الإضافي لكل استدعاء.

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

وتطلب الوسيطة الاختيارية `dimensions`، عند دعمها من قِبل النموذج (مثل `text-embedding-3-*` من OpenAI)،
متجهًا بالحجم المحدد؛ وإلا فسيُعاد الحجم الأصلي للنموذج.

**البنية**

```sql theme={null}
aiEmbed(collection, text[, dimensions])
```

**الوسائط**

* `collection` — اسم مجموعة مُسمّاة تحتوي على بيانات اعتماد الموفّر والتهيئة. [`String`](/ar/reference/data-types/string)
* `text` — النص المطلوب تضمينه. [`String`](/ar/reference/data-types/string)
* `dimensions` — عدد الأبعاد المستهدف الاختياري لمتجه الإخراج. تعني القيمة `0` أو عدم تحديدها استخدام الحجم الأصلي للنموذج. [`UInt64`](/ar/reference/data-types/int-uint)

**القيمة المُعادة**

متجه التضمين، أو مصفوفة فارغة إذا كان الإدخال NULL أو فارغًا، أو إذا فشل الطلب وكان `ai_function_throw_on_error` معطّلًا، أو إذا جرى تجاوز الحصة وكان `ai_function_throw_on_quota_exceeded` معطّلًا. [`Array(Float32)`](/ar/reference/data-types/array)

**أمثلة**

**تضمين سلسلة نصية واحدة**

```sql title=Query theme={null}
SELECT aiEmbed('ai_credentials', 'Hello world')
```

```response title=Response theme={null}
```

**مع أبعاد محددة صراحة**

```sql title=Query theme={null}
SELECT aiEmbed('ai_credentials', 'Hello world', 256)
```

```response title=Response theme={null}
```

**تضمين عمود من النصوص**

```sql title=Query theme={null}
SELECT aiEmbed('ai_credentials', title, 256) FROM articles LIMIT 10
```

```response title=Response theme={null}
```

<div id="aiExtract">
  ## aiExtract
</div>

أُضيف في: v26.4.0

يستخرج معلومات منظَّمة من نص غير منظَّم باستخدام موفّر LLM.

يمكن أن تكون الوسيطة الثالثة إما تعليمة بلغة طبيعية حرة الصياغة (مثل `'the main complaint'`) أو
مخططًا مُرمَّزًا بتنسيق JSON بالشكل `'{"field_a": "description of field a", "field_b": "description of field b"}'`.

في وضع التعليمات، تُرجِع الدالة القيمة المستخرجة كسلسلة نصية عادية، أو سلسلة فارغة إذا لم يُعثر على أي شيء.
وفي وضع المخطط، تُرجِع الدالة سلسلة كائن JSON تتطابق مفاتيحها مع المخطط المطلوب؛ وتكون الحقول المفقودة `null`.

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

**البنية**

```sql theme={null}
aiExtract(collection, text, instruction_or_schema[, temperature])
```

**الأسماء البديلة**: `AIExtract`

**الوسيطات**

* `collection` — اسم مجموعة مُسمّاة تحتوي على بيانات اعتماد الموفّر والتهيئة. [`String`](/ar/reference/data-types/string)
* `text` — النص المراد استخراج المعلومات منه. [`String`](/ar/reference/data-types/string)
* `instruction_or_schema` — تعليمة استخراج بصياغة حرة، أو كائن JSON ثابت يصف الحقول المطلوب استخراجها. [`const String`](/ar/reference/data-types/string)
* `temperature` — درجة حرارة أخذ العينات التي تتحكم في مستوى العشوائية. القيمة الافتراضية: `0.0`. [`const Float64`](/ar/reference/data-types/float)

**القيمة المُعادة**

قيمة واحدة مستخرجة (وضع التعليمات) أو سلسلة JSON تمثل كائنًا (وضع المخطط). تُرجِع القيمة الافتراضية لنوع العمود (سلسلة فارغة) إذا فشل الطلب وكان `ai_function_throw_on_error` معطّلًا. [`String`](/ar/reference/data-types/string)

**أمثلة**

**تعليمة بصياغة حرة**

```sql title=Query theme={null}
SELECT aiExtract('ai_credentials', 'The package arrived late and was damaged.', 'the main complaint')
```

```response title=Response theme={null}
late and damaged package
```

**استخراج المخطط**

```sql title=Query theme={null}
SELECT aiExtract('ai_credentials', review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5
```

```response title=Response theme={null}
```

<div id="aiGenerate">
  ## aiGenerate
</div>

أُضيف في: v26.4.0

ينشئ محتوى نصيًا حرّ الصياغة من موجّه باستخدام موفّر LLM.

ترسل الدالة الموجّه إلى موفّر AI المُعدّ وتُرجِع النص المُنشأ.
يمكن توفير موجّه نظام اختياري لتوجيه سلوك النموذج (مثل النبرة أو التنسيق أو الدور).
إذا لم يتم توفير موجّه نظام، فسيكون موجّه النظام الافتراضي هو: `You are a helpful assistant. Provide a clear and concise response.`

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

**الصيغة**

```sql theme={null}
aiGenerate(collection, prompt[, system_prompt[, temperature]])
```

**الأسماء المستعارة**: `AIGenerate`

**المعاملات**

* `collection` — اسم مجموعة مسماة تحتوي على بيانات اعتماد الموفّر والتهيئة. [`String`](/ar/reference/data-types/string)
* `prompt` — موجّه المستخدم أو سؤاله الذي يُرسل إلى النموذج. [`String`](/ar/reference/data-types/string)
* `system_prompt` — تعليمة اختيارية ثابتة على مستوى النظام تُوجّه سلوك النموذج (مثل الشخصية أو تنسيق المخرجات)، وتُرسل مع كل موجّه. [`String`](/ar/reference/data-types/string)
* `temperature` — درجة حرارة أخذ العينات التي تتحكم في العشوائية. القيمة الافتراضية: `0.7`. [`Float64`](/ar/reference/data-types/float)

**القيمة المُعادة**

الاستجابة النصية المُولَّدة، أو القيمة الافتراضية لنوع العمود (سلسلة فارغة) إذا أخفق الطلب وكان `ai_function_throw_on_error` معطّلًا. [`String`](/ar/reference/data-types/string)

**أمثلة**

**سؤال بسيط**

```sql title=Query theme={null}
SELECT aiGenerate('ai_credentials', 'What is 2 + 2? Reply with just the number.')
```

```response title=Response theme={null}
4
```

**باستخدام موجّه النظام**

```sql title=Query theme={null}
SELECT aiGenerate('ai_credentials', 'Explain ClickHouse', 'You are a database expert. Be concise.')
```

```response title=Response theme={null}
```

**تلخيص قيم العمود**

```sql title=Query theme={null}
SELECT article_title, aiGenerate('ai_credentials', concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5
```

```response title=Response theme={null}
```

<div id="aiTranslate">
  ## aiTranslate
</div>

أُضيف في: v26.4.0

يترجم النص المحدد إلى اللغة الهدف المطلوبة باستخدام موفّر LLM.

يمكن تمرير تعليمات إضافية للأسلوب أو اللهجة كوسيطة رابعة (مثلًا: `'أبقِ المصطلحات التقنية من دون ترجمة'`).

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

**بناء الجملة**

```sql theme={null}
aiTranslate(collection, text, target_language[, instructions[, temperature]])
```

**الأسماء البديلة**: `AITranslate`

**الوسيطات**

* `collection` — اسم مجموعة مُسمّاة تحتوي على بيانات اعتماد الموفّر والتهيئة. [`String`](/ar/reference/data-types/string)
* `text` — النص المراد ترجمته. [`String`](/ar/reference/data-types/string)
* `target_language` — اسم اللغة المستهدفة أو رمز BCP-47 (مثل `'French'`، `'es-MX'`). [`String`](/ar/reference/data-types/string)
* `instructions` — تعليمات إضافية ثابتة اختيارية للمترجم. [`String`](/ar/reference/data-types/string)
* `temperature` — درجة حرارة أخذ العينات التي تتحكم في مستوى العشوائية. القيمة الافتراضية: `0.3`. [`Float64`](/ar/reference/data-types/float)

**القيمة المُعادة**

النص المترجَم، أو القيمة الافتراضية لنوع العمود (سلسلة فارغة) إذا فشل الطلب وكان `ai_function_throw_on_error` معطّلًا. [`String`](/ar/reference/data-types/string)

**أمثلة**

**الترجمة إلى الفرنسية**

```sql title=Query theme={null}
SELECT aiTranslate('ai_credentials', 'Hello, world!', 'French')
```

```response title=Response theme={null}
Bonjour le monde!
```

**الترجمة إلى اليابانية مع إرشادات الأسلوب**

```sql title=Query theme={null}
SELECT aiTranslate('ai_credentials', body, 'Japanese', 'Use polite form (desu/masu)') FROM articles LIMIT 5
```

```response title=Response theme={null}
```