> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

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

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

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

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

<div id="configuration">
  ## الإعداد
</div>

تشير دوال الذكاء الاصطناعي إلى **مجموعة مُسمّاة** تخزّن بيانات اعتماد الموفّر وإعداداته. ويمكن إنشاء مجموعات مُسمّاة مختلفة واستخدامها مع دوال مختلفة أو مع استدعاءات مختلفة للدوال. على سبيل المثال، قد ترغب في تعريف مجموعة مُسمّاة مختلفة لاستخدامها مع دوال النص (`aiGenerate`, `aiClassify`, `aiExtract`, `aiTranslate`) مقابل الدالة `aiEmbed`، إذ تتطلب نقاط نهاية مختلفة وتستخدم عادةً نماذج مختلفة.

مثال على تعليمة لإنشاء مجموعة مُسمّاة تحتوي على بيانات اعتماد الموفّر، إحداهما مع نقطة نهاية للدردشة والأخرى مع نقطة نهاية للتضمين:

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

-- `aiEmbed` does not read `model` from the named collection; pass it as a positional argument instead.
-- Defining `model` in an `aiEmbed` collection is an error, not silently ignored.
CREATE NAMED COLLECTION ai_embedding_credentials AS
    provider = 'openai',
    endpoint = 'https://api.openai.com/v1/embeddings',
    api_key = 'sk-...';
```

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

| المعلمة       | النوع  | الافتراضي | الوصف                                                                                                                                                       |
| ------------- | ------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`    | String | —         | موفّر النموذج. القيم المدعومة: `'openai'` و`'anthropic'`. انظر الملاحظة أدناه.                                                                              |
| `endpoint`    | String | —         | عنوان URL لنقطة نهاية واجهة برمجة التطبيقات.                                                                                                                |
| `model`       | String | —         | اسم النموذج (مثل `'gpt-4o-mini'`). تستخدمه الدوال النصية؛ وتتطلب `aiEmbed` إدخال `model` كوسيط موضعي، وتُرجع خطأً إذا تم تحديد `model` في المجموعة المسماة. |
| `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="selecting-credentials">
  ### اختيار بيانات الاعتماد
</div>

تحدِّد الدالة المجموعة المُسمّاة المطلوب استخدامها وفق الترتيب التالي:

1. مفتاح `credentials` في خريطة المَعلمات الخاصة بها، إن وُجد؛
2. وإلا، إعداد بيانات الاعتماد الافتراضي المنطبق:
   * [`ai_function_text_default_credentials`](/docs/ar/reference/settings/session-settings#ai_function_text_default_credentials) لدوال النص (`aiGenerate` و`aiClassify` و`aiExtract` و`aiTranslate`);
   * [`ai_function_embedding_default_credentials`](/docs/ar/reference/settings/session-settings#ai_function_embedding_default_credentials) للدالة `aiEmbed`.

إذا لم يُضبط أيٌّ منهما، يفشل الاستدعاء. تستخدم دوال النص ودوال التضمين إعدادات افتراضية منفصلة لأن نقطة النهاية الخاصة بإكمالات الدردشة تختلف عن نظيرتها الخاصة بالتضمينات.

```sql theme={null}
SET ai_function_text_default_credentials = 'ai_text_credentials';

-- Uses ai_text_credentials from the setting:
SELECT aiGenerate('What is 2 + 2? Reply with just the number.');

-- Overrides the default for this call:
SELECT aiGenerate('Bonjour', map('credentials', 'other_credentials'));
```

<div id="parameter-map">
  ### خريطة المعلمات
</div>

تقبل كل دالة، اختياريًا، ‎`Map(String, String)`‎ من المعلمات في النهاية. جميع القيم سلاسل نصية (ضع الأرقام بين علامتَي اقتباس، مثل ‎`'0.2'`‎). تُرفض المفاتيح غير المعروفة. وإذا كان المفتاح موجودًا، فإنه يتجاوز القيمة المناظرة في المجموعة المُسمّاة؛ أما إذا لم يكن موجودًا، فيُستخدَم ما في المجموعة المُسمّاة (بالنسبة إلى ‎`model`‎/‎`max_tokens`‎) أو القيمة الافتراضية المضمّنة. والاستثناء هو ‎`aiEmbed`‎، إذ يأخذ ‎`model`‎ بوصفه وسيطة موضعية مطلوبة (‎`aiEmbed(text, model[, params])`‎) ويُرجع خطأ إذا جرى تعيينه بدلًا من ذلك في خريطة المعلمات أو المجموعة المُسمّاة.

المعلمات التالية مشتركة بين جميع دوال الذكاء الاصطناعي:

| Key           | Description                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `credentials` | المجموعة المُسمّاة المطلوب استخدامها (انظر أعلاه).                                                                                          |
| `model`       | يتجاوز قيمة `model` الخاصة بالمجموعة (لدوال النصوص فقط؛ تأخذ `aiEmbed` القيمة `model` بوصفها وسيطة موضعية مطلوبة، وليس مفتاحًا في الخريطة). |

وتقبل كل دالة أيضًا معلمات إضافية خاصة بها (مثل ‎`max_tokens`‎ و‎`temperature`‎ و‎`system_prompt`‎ و‎`instructions`‎ و‎`dimensions`‎). راجع المرجع الخاص بكل دالة أدناه لمعرفة المعلمات التي تقبلها وقيمها الافتراضية.

```sql theme={null}
SELECT aiGenerate(body, map('temperature', '0.2', 'system_prompt', 'You are terse.')) FROM articles;
```

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

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

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

يمثل عنوان URL الخاص بـ `endpoint` في مجموعة مسماة للذكاء الاصطناعي وجهةً خارجية يتصل بها الخادم باستخدام هويته الخاصة، وقد يتضمن — إذا جرى تحديده — `api_key` الخاص بالمجموعة المسماة في رؤوس الطلب. افتراضيًا، يسمح ClickHouse بأي مضيف. لحصر الدوال في مجموعة محددة من الموفّرين، اضبط [`remote_url_allow_hosts`](/docs/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="transport-security">
  ### أمان النقل (HTTP مقابل HTTPS)
</div>

يُحدَّد النقل حصريًا من خلال scheme لعنوان URL الخاص بـ `endpoint`. لا يوجد تشفير على مستوى التطبيق لحمولة الطلب؛ إذ تعتمد حماية البيانات أثناء النقل بالكامل على هذا الـ scheme:

* `https://` — يستخدم الاتصال TLS. يُشفَّر جسم الطلب (النص المُدخل، والتوجيهات) و`api_key` في headers الطلب أثناء النقل، كما يجري التحقق من certificate الخاصة بالموفّر. استخدم هذا مع أي موفّر بعيد.
* `http://` — الاتصال **غير مشفَّر**. يُرسَل جسم الطلب و`api_key` بصيغة مكشوفة. استخدم هذا فقط مع موفّر موثوق على private network (مثل instance محلي من `vLLM` أو `Ollama`).

لا تفرض دوال الذكاء الاصطناعي استخدام HTTPS: إذ يُقبل `endpoint` من نوع `http://` وتُرسَل البيانات من دون تشفير. لا يوجد حاليًا إعداد server-side يرفض نقاط نهاية AI ذات النص المكشوف — إذ يقيّد [`remote_url_allow_hosts`](/docs/ar/reference/settings/server-settings/settings#remote_url_allow_hosts) مضيف الوجهة فقط ولا يفحص scheme الخاص بعنوان URL، لذا فإن `endpoint` من نوع `http://` والموجَّه إلى مضيف مسموح به يمر أيضًا. ولضمان نقل مشفَّر، اضبط مجموعات مُسمّاة باستخدام نقاط نهاية `https://`.

لاحظ أنه في كلتا الحالتين يتلقى الموفّر بيانات الإدخال بصيغة مكشوفة بعد إنهاء TLS؛ إذ لا يحمي TLS البيانات إلا على مسار الشبكة بين الخادم والموفّر.

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

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

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

يُتتبَّع نشاط AI function عبر [ProfileEvents](/docs/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": "..."}`، تُستخرج التسمية ويُعاد نصّها.

تُؤخذ بيانات الاعتماد (وهي مجموعة مسماة تحدد الموفّر والنموذج ونقطة النهاية، واختياريًا مفتاح واجهة برمجة تطبيقات)
من المفتاح `credentials` في خريطة المعاملات الاختيارية، أو من الإعداد
`ai_function_text_default_credentials` إذا لم تتضمنه الخريطة.

**البنية**

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

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

**الوسيطة**

* `text` — النص المطلوب تصنيفه. [`String`](/docs/ar/reference/data-types/string)
* `categories` — قائمة ثابتة بتسميات الفئات المرشحة. [`Array(String)`](/docs/ar/reference/data-types/array)
* `params` — `Map(String, String)` ثابت اختياري للمعلمات. المفاتيح الخاصة بالدالة: `temperature` (درجة حرارة أخذ العينات التي تتحكم في مستوى العشوائية؛ القيمة الافتراضية `0.0`) و`max_tokens` (الحد الأقصى لعدد الرموز المُخرجة في كل استدعاء؛ القيمة الافتراضية `1024`). كما تنطبق أيضًا المعلمات العامة `credentials` و`model` (راجع [الدالة](/docs/ar/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ar/reference/data-types/map)

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

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

**أمثلة**

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

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

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

**تصنيف عمود باستخدام بيانات اعتماد صريحة**

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

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

استُحدث في: v26.6.0

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

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

تُؤخذ بيانات الاعتماد (مجموعة مسماة تحدد الموفّر ونقطة النهاية، وبشكل اختياري مفتاح واجهة برمجة تطبيقات)
من المفتاح `credentials` في خريطة المعلمات، أو من الإعداد
`ai_function_embedding_default_credentials` عندما لا تتضمنه الخريطة. لاحظ أن `aiEmbed` يستخدم
إعدادًا منفصلًا لبيانات الاعتماد الافتراضية عن دوال النص، لأن نقطة نهاية تضمين تختلف
عن نقطة نهاية الدردشة.

تكون `model` وسيطة موضعية مطلوبة (قيمة ثابتة من نوع `String`). وعلى خلاف دوال النص،
لا يقرأ `aiEmbed` قيمة `model` من المجموعة المسماة أو من خريطة المعلمات. وأي مجموعة مسماة
تعرّف `model` تُرفَض بدلًا من تجاهلها بصمت.

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

**البنية**

```sql theme={null}
aiEmbed(text, model[, params])
```

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

* `text` — النص المراد تحويله إلى تضمين. [`String`](/docs/ar/reference/data-types/string)
* `model` — اسم نموذج التضمين. [`const String`](/docs/ar/reference/data-types/string)
* `params` — `Map(String, String)` ثابت اختياري للمعلمات. مفتاح خاص بهذه الدالة: `dimensions` (عدد أبعاد متجه الإخراج المطلوب؛ تعني القيمة `0` أو عدم تحديده استخدام الحجم الأصلي للنموذج). وينطبق أيضًا المعامل العام `credentials` (راجع [دوال الذكاء الاصطناعي](/docs/ar/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ar/reference/data-types/map)

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

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

**أمثلة**

**تضمين سلسلة نصية واحدة (يمكن حذف `credentials` إذا كان الإعداد `ai_function_embedding_default_credentials` مضبوطًا)**

```sql title=Query theme={null}
SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials'))
```

**مع تحديد الأبعاد صراحةً**

```sql title=Query theme={null}
SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256'))
```

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

```sql title=Query theme={null}
SELECT aiEmbed(title, 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) FROM articles LIMIT 10
```

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

تُؤخذ بيانات الاعتماد (وهي مجموعة مُسمّاة تحدد الموفّر والنموذج ونقطة النهاية، وبشكل اختياري مفتاح واجهة برمجة تطبيقات)
من المفتاح `credentials` في خريطة المعلمات الاختيارية، أو من الإعداد
`ai_function_text_default_credentials` عندما لا تتضمن الخريطة هذا المفتاح.

**البنية**

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

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

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

* `text` — النص المراد استخراج المعلومات منه. [`String`](/docs/ar/reference/data-types/string)
* `instruction_or_schema` — تعليمة استخراج بصياغة حرة، أو كائن JSON ثابت يصف الحقول المطلوب استخراجها. [`const String`](/docs/ar/reference/data-types/string)
* `params` — `Map(String, String)` ثابت اختياري للمعلمات. المفاتيح الخاصة بالدالة هي: `temperature` (درجة حرارة أخذ العينات التي تتحكم في مستوى العشوائية؛ الافتراضي `0.0`) و`max_tokens` (الحد الأقصى لرموز الإخراج في كل استدعاء؛ الافتراضي `1024`). كما تنطبق أيضًا المعلمات العامة `credentials` و`model` (راجع [دوال الذكاء الاصطناعي](/docs/ar/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ar/reference/data-types/map)

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

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

**أمثلة**

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

```sql title=Query theme={null}
SELECT aiExtract('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(review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5
```

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

أُضيف في: v26.4.0

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

ترسل الدالة الموجّه إلى موفّر الذكاء الاصطناعي المُعَدّ وتُرجع النص الناتج.

تُؤخذ بيانات الاعتماد (وهي مجموعة مسماة تحدد الموفّر، والنموذج، ونقطة النهاية، واختياريًا مفتاح واجهة برمجة تطبيقات)
من المفتاح `credentials` في خريطة المعلمات الاختيارية، أو من الإعداد
`ai_function_text_default_credentials` عندما لا تتضمنه الخريطة.

يمكن لخريطة المعلمات الاختيارية أيضًا تعيين `system_prompt` (تعليمة توجّه سلوك النموذج،
مثل النبرة، والتنسيق، والدور)، و`temperature`، و`max_tokens`، و`model`. إذا لم يتم تعيين `system_prompt`،
فالقيمة الافتراضية هي: `You are a helpful assistant. Provide a clear and concise response.`

**البنية**

```sql theme={null}
aiGenerate(prompt[, params])
```

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

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

* `prompt` — الموجّه أو السؤال الذي يُرسله المستخدم إلى النموذج. [`String`](/docs/ar/reference/data-types/string)
* `params` — قيمة ثابتة اختيارية من النوع `Map(String, String)` للمعلمات. المفاتيح الخاصة بالدالة هي: `temperature` (درجة حرارة التوليد التي تتحكم في العشوائية؛ والقيمة الافتراضية `0.7`)، و`max_tokens` (الحد الأقصى لعدد الرموز المميّزة في المخرجات لكل استدعاء؛ والقيمة الافتراضية `1024`)، و`system_prompt` (تعليمة ثابتة على مستوى النظام لتوجيه سلوك النموذج؛ والقيمة الافتراضية موجّه عام للمساعد). كما تنطبق أيضًا المعلمتان الشائعتان `credentials` و`model` (راجع [دوال الذكاء الاصطناعي](/docs/ar/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ar/reference/data-types/map)

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

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

**أمثلة**

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

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

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

**مع بيانات اعتماد صريحة وموجّه النظام**

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

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

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

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

قُدِّم في: v26.4.0

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

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

تُؤخذ بيانات الاعتماد (مجموعة مسماة تحدد الموفّر والنموذج ونقطة النهاية، ومفتاح واجهة برمجة تطبيقات اختياريًا)
من المفتاح `credentials` في خريطة المعلمات الاختيارية، أو من
الإعداد `ai_function_text_default_credentials` إذا لم تتضمنه الخريطة.

**البنية**

```sql theme={null}
aiTranslate(text, target_language[, params])
```

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

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

* `text` — النص المراد ترجمته. [`String`](/docs/ar/reference/data-types/string)
* `target_language` — اسم اللغة الهدف أو رمز BCP-47 لها (مثل `'French'` و`'es-MX'`). [`String`](/docs/ar/reference/data-types/string)
* `params` — `Map(String, String)` ثابت اختياري للمعلمات. المفاتيح الخاصة بهذه الدالة هي: `temperature` (درجة حرارة أخذ العينات التي تتحكم في العشوائية؛ والقيمة الافتراضية `0.3`)، و`max_tokens` (الحد الأقصى لعدد التوكنات الناتجة في كل استدعاء؛ والقيمة الافتراضية `1024`)، و`instructions` (تعليمات إضافية للمترجم تتعلق بالأسلوب أو اللهجة). كما تنطبق أيضًا المعلمتان الشائعتان `credentials` و`model` (راجع [دوال الذكاء الاصطناعي](/docs/ar/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ar/reference/data-types/map)

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

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

**أمثلة**

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

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

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

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

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