Skip to main content
دوال الذكاء الاصطناعي هي دوال مضمّنة في ClickHouse يمكنك استخدامها لاستدعاء الذكاء الاصطناعي أو إنشاء embeddings للعمل مع بياناتك، واستخراج المعلومات، وتصنيف البيانات، وغير ذلك…
دوال الذكاء الاصطناعي تجريبية. اضبط allow_experimental_ai_functions لتمكينها.
قد تُرجع دوال الذكاء الاصطناعي مخرجات غير متوقعة. وتعتمد النتيجة بدرجة كبيرة على جودة الموجّه والنموذج المستخدم.
تشترك جميع الدوال في بنية تحتية موحّدة توفّر ما يلي:

الإعداد

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

معلمات المجموعة المسماة

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

اختيار بيانات الاعتماد

تحدِّد الدالة المجموعة المُسمّاة المطلوب استخدامها وفق الترتيب التالي:
  1. مفتاح credentials في خريطة المَعلمات الخاصة بها، إن وُجد؛
  2. وإلا، إعداد بيانات الاعتماد الافتراضي المنطبق:
إذا لم يُضبط أيٌّ منهما، يفشل الاستدعاء. تستخدم دوال النص ودوال التضمين إعدادات افتراضية منفصلة لأن نقطة النهاية الخاصة بإكمالات الدردشة تختلف عن نظيرتها الخاصة بالتضمينات.

خريطة المعلمات

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

إعدادات على مستوى الاستعلام

تَرِد جميع الإعدادات المتعلقة بالذكاء الاصطناعي في الإعدادات تحت البادئة ai_function_.

تقييد مضيفات نقطة النهاية

يمثل عنوان URL الخاص بـ endpoint في مجموعة مسماة للذكاء الاصطناعي وجهةً خارجية يتصل بها الخادم باستخدام هويته الخاصة، وقد يتضمن — إذا جرى تحديده — api_key الخاص بالمجموعة المسماة في رؤوس الطلب. افتراضيًا، يسمح ClickHouse بأي مضيف. لحصر الدوال في مجموعة محددة من الموفّرين، اضبط remote_url_allow_hosts في إعدادات الخادم، على سبيل المثال:
لاحظ أن هذا الإعداد عام على مستوى الخادم ويسري على جميع الميزات التي تستخدم HTTP.

أمان النقل (HTTP مقابل HTTPS)

يُحدَّد النقل حصريًا من خلال 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 مضيف الوجهة فقط ولا يفحص scheme الخاص بعنوان URL، لذا فإن endpoint من نوع http:// والموجَّه إلى مضيف مسموح به يمر أيضًا. ولضمان نقل مشفَّر، اضبط مجموعات مُسمّاة باستخدام نقاط نهاية https://. لاحظ أنه في كلتا الحالتين يتلقى الموفّر بيانات الإدخال بصيغة مكشوفة بعد إنهاء TLS؛ إذ لا يحمي TLS البيانات إلا على مسار الشبكة بين الخادم والموفّر.

الموفّرون المدعومون

Observability

يُتتبَّع نشاط AI function عبر ProfileEvents في ClickHouse: استعلم عن هذه الأحداث:

aiClassify

أُضيف في: v26.4.0 يُصنّف النص المُعطى ضمن إحدى الفئات المتاحة باستخدام موفّر LLM. ترسل الدالة النص مع موجّه تصنيف ثابت وتنسيق استجابة من نوع JSON-schema يقيّد النموذج بحيث يُرجع تسمية واحدة فقط من التسميات المزوّدة. وعندما تُعاد الاستجابة على شكل كائن JSON بالصيغة {"category": "..."}، تُستخرج التسمية ويُعاد نصّها. تُؤخذ بيانات الاعتماد (وهي مجموعة مسماة تحدد الموفّر والنموذج ونقطة النهاية، واختياريًا مفتاح واجهة برمجة تطبيقات) من المفتاح credentials في خريطة المعاملات الاختيارية، أو من الإعداد ai_function_text_default_credentials إذا لم تتضمنه الخريطة. البنية
الأسماء البديلة: AIClassify الوسيطة
  • text — النص المطلوب تصنيفه. String
  • categories — قائمة ثابتة بتسميات الفئات المرشحة. Array(String)
  • paramsMap(String, String) ثابت اختياري للمعلمات. المفاتيح الخاصة بالدالة: temperature (درجة حرارة أخذ العينات التي تتحكم في مستوى العشوائية؛ القيمة الافتراضية 0.0) وmax_tokens (الحد الأقصى لعدد الرموز المُخرجة في كل استدعاء؛ القيمة الافتراضية 1024). كما تنطبق أيضًا المعلمات العامة credentials وmodel (راجع الدالة). Map(String, String)
القيمة المُعادة إحدى تسميات الفئات المقدَّمة، أو القيمة الافتراضية لنوع العمود (سلسلة فارغة) إذا فشل الطلب وكان ai_function_throw_on_error معطّلًا. String أمثلة تصنيف المشاعر
Query
Response
تصنيف عمود باستخدام بيانات اعتماد صريحة
Query

aiEmbed

استُحدث في: v26.6.0 ينشئ متجه تضمين للنص المُعطى باستخدام موفّر الذكاء الاصطناعي المُعَدّ. ترسل الدالة النص إلى نقطة نهاية التضمين المُعَدّة وتُرجع المتجه الناتج بصيغة Array(Float32). ضمن كتلة واحدة من الصفوف، تُجمَّع المدخلات في دفعات يصل حجمها إلى 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)، متجهًا بالحجم المحدد؛ وإلا فسيُعاد الحجم الأصلي للنموذج. البنية
الوسيطات
  • text — النص المراد تحويله إلى تضمين. String
  • model — اسم نموذج التضمين. const String
  • paramsMap(String, String) ثابت اختياري للمعلمات. مفتاح خاص بهذه الدالة: dimensions (عدد أبعاد متجه الإخراج المطلوب؛ تعني القيمة 0 أو عدم تحديده استخدام الحجم الأصلي للنموذج). وينطبق أيضًا المعامل العام credentials (راجع دوال الذكاء الاصطناعي). Map(String, String)
القيمة المُعادة متجه التضمين، أو مصفوفة فارغة إذا كان الإدخال NULL أو فارغًا، أو إذا فشل الطلب وكان ai_function_throw_on_error معطّلًا، أو إذا تم تجاوز الحصة وكان ai_function_throw_on_quota_exceeded معطّلًا. Array(Float32) أمثلة تضمين سلسلة نصية واحدة (يمكن حذف credentials إذا كان الإعداد ai_function_embedding_default_credentials مضبوطًا)
Query
مع تحديد الأبعاد صراحةً
Query
إنشاء تضمينات لعمود من النصوص
Query

aiExtract

أُضيف في: 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 عندما لا تتضمن الخريطة هذا المفتاح. البنية
الأسماء البديلة: AIExtract الوسيطات
  • text — النص المراد استخراج المعلومات منه. String
  • instruction_or_schema — تعليمة استخراج بصياغة حرة، أو كائن JSON ثابت يصف الحقول المطلوب استخراجها. const String
  • paramsMap(String, String) ثابت اختياري للمعلمات. المفاتيح الخاصة بالدالة هي: temperature (درجة حرارة أخذ العينات التي تتحكم في مستوى العشوائية؛ الافتراضي 0.0) وmax_tokens (الحد الأقصى لرموز الإخراج في كل استدعاء؛ الافتراضي 1024). كما تنطبق أيضًا المعلمات العامة credentials وmodel (راجع دوال الذكاء الاصطناعي). Map(String, String)
القيمة المُعادة قيمة واحدة مستخرجة (وضع التعليمات) أو سلسلة JSON تمثل كائنًا (وضع المخطط). تُرجِع القيمة الافتراضية لنوع العمود (سلسلة فارغة) إذا فشل الطلب وكان ai_function_throw_on_error معطّلًا. String أمثلة تعليمة بصياغة حرة
Query
Response
استخراج المخطط
Query

aiGenerate

أُضيف في: 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. البنية
الأسماء البديلة: AIGenerate الوسيطات
  • prompt — الموجّه أو السؤال الذي يُرسله المستخدم إلى النموذج. String
  • params — قيمة ثابتة اختيارية من النوع Map(String, String) للمعلمات. المفاتيح الخاصة بالدالة هي: temperature (درجة حرارة التوليد التي تتحكم في العشوائية؛ والقيمة الافتراضية 0.7)، وmax_tokens (الحد الأقصى لعدد الرموز المميّزة في المخرجات لكل استدعاء؛ والقيمة الافتراضية 1024)، وsystem_prompt (تعليمة ثابتة على مستوى النظام لتوجيه سلوك النموذج؛ والقيمة الافتراضية موجّه عام للمساعد). كما تنطبق أيضًا المعلمتان الشائعتان credentials وmodel (راجع دوال الذكاء الاصطناعي). Map(String, String)
القيمة المُعادة الاستجابة النصية المُولَّدة، أو القيمة الافتراضية لنوع العمود (سلسلة فارغة) إذا فشل الطلب وكان ai_function_throw_on_error معطّلًا. String أمثلة سؤال بسيط
Query
Response
مع بيانات اعتماد صريحة وموجّه النظام
Query
لخّص قيم العمود
Query

aiTranslate

قُدِّم في: v26.4.0 يترجم النص المُعطى إلى اللغة الهدف المحددة باستخدام موفّر LLM. يمكن تمرير تعليمات إضافية خاصة بالأسلوب أو اللهجة عبر المفتاح instructions في خريطة المعلمات (على سبيل المثال: 'الإبقاء على المصطلحات التقنية دون ترجمة'). تُؤخذ بيانات الاعتماد (مجموعة مسماة تحدد الموفّر والنموذج ونقطة النهاية، ومفتاح واجهة برمجة تطبيقات اختياريًا) من المفتاح credentials في خريطة المعلمات الاختيارية، أو من الإعداد ai_function_text_default_credentials إذا لم تتضمنه الخريطة. البنية
الأسماء البديلة: AITranslate الوسيطات
  • text — النص المراد ترجمته. String
  • target_language — اسم اللغة الهدف أو رمز BCP-47 لها (مثل 'French' و'es-MX'). String
  • paramsMap(String, String) ثابت اختياري للمعلمات. المفاتيح الخاصة بهذه الدالة هي: temperature (درجة حرارة أخذ العينات التي تتحكم في العشوائية؛ والقيمة الافتراضية 0.3)، وmax_tokens (الحد الأقصى لعدد التوكنات الناتجة في كل استدعاء؛ والقيمة الافتراضية 1024)، وinstructions (تعليمات إضافية للمترجم تتعلق بالأسلوب أو اللهجة). كما تنطبق أيضًا المعلمتان الشائعتان credentials وmodel (راجع دوال الذكاء الاصطناعي). Map(String, String)
القيمة المُعادة النص المترجم، أو القيمة الافتراضية لنوع العمود (سلسلة فارغة) إذا فشل الطلب وكان ai_function_throw_on_error معطّلًا. String أمثلة الترجمة إلى الفرنسية
Query
Response
ترجم إلى اليابانية مع تعليمات الأسلوب
Query
آخر تعديل في ٢٣ يوليو ٢٠٢٦