دوال الذكاء الاصطناعي تجريبية. اضبط
allow_experimental_ai_functions لتمكينها.قد تُرجع دوال الذكاء الاصطناعي مخرجات غير متوقعة. وتعتمد النتيجة بدرجة كبيرة على جودة الموجّه والنموذج المستخدم.- فرض الحصص: حدود لكل استعلام على الرموز (
ai_function_max_input_tokens_per_query,ai_function_max_output_tokens_per_query) واستدعاءات واجهة برمجة التطبيقات (ai_function_max_api_calls_per_query). - إعادة المحاولة مع زيادة تدريجية في التأخير: تتم إعادة محاولة الإخفاقات العابرة (
ai_function_max_retries) باستخدام تأخير أُسّي متزايد (ai_function_retry_initial_delay_ms).
الإعداد
aiGenerate, aiClassify, aiFilter, aiExtract, aiTranslate, aiRedact) مقابل دوال التضمين (aiEmbed, aiSimilarity)، إذ تتطلب نقاط نهاية مختلفة وتستخدم عادةً نماذج مختلفة.
مثال على تعليمة لإنشاء مجموعة مُسمّاة تحتوي على بيانات اعتماد الموفّر، إحداهما مع نقطة نهاية للدردشة والأخرى مع نقطة نهاية للتضمين:
معلمات المجموعة المسماة
يمكن استخدام أي واجهة برمجة تطبيقات متوافقة مع OpenAI (مثل vLLM وOllama وLiteLLM) عبر ضبط
provider = 'openai' وتوجيه endpoint إلى خدمتك.اختيار بيانات الاعتماد
- مفتاح
credentialsفي خريطة المَعلمات الخاصة بها، إن وُجد؛ - وإلا، إعداد بيانات الاعتماد الافتراضي المنطبق:
ai_function_text_default_credentialsلدوال النص (aiGenerateوaiClassifyوaiFilterوaiExtractوaiTranslateوaiRedact);ai_function_embedding_default_credentialsلدوال التضمين (aiEmbedوaiSimilarity).
aiFilter، إذ تُرجع UInt8 ويمكن استخدامها مباشرةً في WHERE:
خريطة المعلمات
Map(String, String) من المعلمات في النهاية. جميع القيم سلاسل نصية (ضع الأرقام بين علامتَي اقتباس، مثل '0.2'). تُرفض المفاتيح غير المعروفة. وإذا كان المفتاح موجودًا، فإنه يتجاوز القيمة المناظرة في المجموعة المُسمّاة؛ أما إذا لم يكن موجودًا، فيُستخدَم ما في المجموعة المُسمّاة (بالنسبة إلى model/max_tokens) أو القيمة الافتراضية المضمّنة. والاستثناء هو دوال التضمين (aiEmbed وaiSimilarity)، إذ تأخذ model بوصفها وسيطة موضعية مطلوبة (مثل aiEmbed(text, model[, params]) وaiSimilarity(text1, text2, model[, params])) وتُرجع خطأ إذا جرى تعيينها بدلًا من ذلك في خريطة المعلمات أو المجموعة المُسمّاة. وذلك لضمان تضمينات قابلة لإعادة الإنتاج.
المعلمات التالية مشتركة بين جميع دوال الذكاء الاصطناعي:
وتقبل كل دالة أيضًا معلمات إضافية خاصة بها (مثل
max_tokens وtemperature وsystem_prompt وinstructions وdimensions). راجع المرجع الخاص بكل دالة أدناه لمعرفة المعلمات التي تقبلها وقيمها الافتراضية.
إعدادات على مستوى الاستعلام
ai_function_.
تقييد مضيفات نقطة النهاية
endpoint في مجموعة مسماة للذكاء الاصطناعي وجهةً خارجية يتصل بها الخادم باستخدام هويته الخاصة، وقد يتضمن — إذا جرى تحديده — api_key الخاص بالمجموعة المسماة في رؤوس الطلب. افتراضيًا، يسمح ClickHouse بأي مضيف. لحصر الدوال في مجموعة محددة من الموفّرين، اضبط remote_url_allow_hosts في إعدادات الخادم، على سبيل المثال:
أمان النقل (HTTP مقابل HTTPS)
endpoint. لا يوجد تشفير على مستوى التطبيق لحمولة الطلب؛ إذ تعتمد حماية البيانات أثناء النقل بالكامل على هذا الـ scheme:
https://— يستخدم الاتصال TLS. يُشفَّر جسم الطلب (النص المُدخل، والتوجيهات) وapi_keyفي رأس الطلب أثناء النقل، كما يجري التحقق من certificate الخاصة بالموفّر. استخدم هذا مع أي موفّر بعيد.http://— الاتصال غير مشفَّر. يُرسَل جسم الطلب وapi_keyبصيغة مكشوفة. استخدم هذا فقط مع موفّر موثوق على private network (مثل instance محلي منvLLMأوOllama).
endpoint يؤدي إلى إرسال البيانات بصيغة مكشوفة إلى مضيف بعيد: إذ تؤدي أي نقطة نهاية غير HTTPS لا يكون مضيفها loopback إلى ظهور استثناء. تُستثنى مضيفات loopback (localhost، 127.0.0.0/8، ::1)، لذا يعمل خادم model محلي على http://localhost مباشرةً. للسماح بنقطة نهاية http:// ذات نص مكشوف على مضيف بعيد، اضبط ai_function_allow_insecure_endpoint على 1. هذا check مستقل عن remote_url_allow_hosts: فهذا الإعداد هو allowlist للمضيفين ولا يفحص scheme الخاص بعنوان URL، لذا فإن endpoint من نوع http:// والموجَّه إلى مضيف مسموح به يمر منه أيضًا.
لاحظ أنه في كلتا الحالتين يتلقى الموفّر بيانات الإدخال بصيغة مكشوفة بعد إنهاء TLS؛ إذ لا يحمي TLS البيانات إلا على مسار الشبكة بين الخادم والموفّر.
الموفّرون المدعومون
Observability
استعلم عن هذه الأحداث:
aiClassify
credentials في خريطة المعلمات الاختيارية، أو من الإعداد
ai_function_text_default_credentials إذا لم تتضمنه الخريطة.
البنية
AIClassify
الوسيطة
text— النص المطلوب تصنيفه.Stringcategories— قائمة ثابتة بتسميات الفئات المرشحة.Array(String)params—Map(String, String)ثابت اختياري للمعلمات. المفاتيح الخاصة بالدالة:temperature(درجة حرارة أخذ العينات التي تتحكم في مستوى العشوائية؛ القيمة الافتراضية0.0) وmax_tokens(الحد الأقصى لعدد الرموز المُخرجة في كل استدعاء؛ القيمة الافتراضية1024). كما تنطبق أيضًا المعلمات العامةcredentialsوmodel(راجع دالة الذكاء الاصطناعي).Map(String, String)
ai_function_throw_on_error معطّلًا. String
أمثلة
تصنيف المشاعر
Query
Response
Query
aiEmbed
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)،
متجهًا بالحجم المحدد؛ وإلا فسيُعاد الحجم الأصلي للنموذج.
البنية
AIEmbed
الوسيطات
text— النص المراد تحويله إلى تضمين.Stringmodel— اسم نموذج التضمين.const Stringparams—Map(String, String)ثابت اختياري للمعلمات. مفتاح خاص بهذه الدالة:dimensions(عدد أبعاد متجه الإخراج المطلوب؛ تعني القيمة0أو عدم تحديده استخدام الحجم الأصلي للنموذج). وينطبق أيضًا المعلمة العامةcredentials(راجع دوال الذكاء الاصطناعي).Map(String, String)
ai_function_throw_on_error معطّلًا، أو إذا تم تجاوز الحصة وكان ai_function_throw_on_quota_exceeded معطّلًا. Array(Float32)
أمثلة
تضمين سلسلة نصية واحدة (يمكن حذف credentials إذا كان الإعداد ai_function_embedding_default_credentials مضبوطًا)
Query
Query
Query
aiExtract
'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— النص المراد استخراج المعلومات منه.Stringinstruction_or_schema— تعليمة استخراج بصياغة حرة، أو كائن JSON ثابت يصف الحقول المطلوب استخراجها.const Stringparams—Map(String, String)ثابت اختياري للمعلمات. المفاتيح الخاصة بالدالة هي:temperature(درجة حرارة أخذ العينات التي تتحكم في مستوى العشوائية؛ الافتراضي0.0) وmax_tokens(الحد الأقصى لرموز الإخراج في كل استدعاء؛ الافتراضي1024). كما تنطبق أيضًا المعلمات العامةcredentialsوmodel(راجع دوال الذكاء الاصطناعي).Map(String, String)
ai_function_throw_on_error معطّلًا. String
أمثلة
تعليمة بصياغة حرة
Query
Response
Query
aiFilter
UInt8) مناسبة للاستخدام في WHERE وPREWHERE وJOIN ... ON.
تطلب الدالة من النموذج أن يردّ بـ true أو false فقط وبأحرف صغيرة. تُحوَّل الطلبات الفاشلة (عندما يكون
ai_function_throw_on_error معطّلًا) والاستجابات غير المعروفة إلى 0، وبالتالي يُستبعد الصف.
تحذير: لا تعتمد على نتائج aiFilter دون تدقيق. قد تكون المسندات المستندة إلى LLM غير صحيحة
أو غير متسقة؛ لذا لا تستخدمها إلا عندما تكون الإيجابيات الكاذبة والسلبيات الكاذبة مقبولة.
تُؤخذ بيانات الاعتماد (مجموعة مسمّاة تحدد الموفّر والنموذج ونقطة النهاية، ومفتاح واجهة برمجة تطبيقات اختياريًا)
من المفتاح credentials في خريطة المعلمات الاختيارية، أو من إعداد
ai_function_text_default_credentials إذا لم تتضمنه الخريطة.
ملاحظة: يؤدي استخدام aiFilter في JOIN ... ON إلى تقييم LLM مرة واحدة لكل زوج مرشّح، وقد يكون ذلك مكلفًا.
البنية
AIFilter
الوسيطات
text— النص المراد تقييمه.Stringcondition— شرط ثابت باللغة الطبيعية يجب أن يستوفيه النص.Stringparams—Map(String, String)ثابت اختياري للمعلمات. المفاتيح الخاصة بالدالة هي:temperature(درجة حرارة أخذ العينات التي تتحكم في العشوائية؛ القيمة الافتراضية0.0) وmax_tokens(الحد الأقصى لرموز الإخراج لكل استدعاء؛ القيمة الافتراضية1024). تنطبق أيضًا المعلمتان العامتانcredentialsوmodel(راجع دوال الذكاء الاصطناعي).Map(String, String)
1 إذا كان النص يطابق الشرط، و0 في غير ذلك. تُرجع القيمة الافتراضية (0) إذا فشل الطلب وكان ai_function_throw_on_error معطّلًا. UInt8
أمثلة
تصفية المراجعات الغاضبة
Query
Query
aiGenerate
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— الموجّه أو السؤال الذي يُرسله المستخدم إلى النموذج.Stringparams— قيمة ثابتة اختيارية من النوع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
aiRedact
[REDACTED] افتراضيًا، ويمكن تهيئته عبر
المعلمة replacement). تقيّد مصفوفة categories أنواع معلومات تحديد الهوية الشخصية التي تُحجب؛ أما المصفوفة الفارغة
فتستخدم مجموعة افتراضية من الفئات الشائعة (الاسم، البريد الإلكتروني، رقم الهاتف، العنوان، بطاقة الائتمان، عنوان IP).
يوجّه aiRedact النموذج إلى تغيير نطاقات معلومات تحديد الهوية الشخصية المكتشفة فقط، لكن الحفاظ على النص المحيط بها
يتم بأفضل جهد، وقد يظل النموذج يغيّره (انظر التحذير أعلاه). تُحوَّل أيضًا محارف التحكم، باستثناء علامة الجدولة
والسطر الجديد وعودة العربة، إلى مسافات قبل إرسال الطلب، لذلك لا يكون الناتج
مطابقًا على مستوى البايت للمدخلات التي تحتوي عليها.
لأن aiRedact يعيد النص الكامل للإدخال بعد استبدال معلومات تحديد الهوية الشخصية، فإن طول الناتج يقارب طول الإدخال.
اضبط max_tokens (القيمة الافتراضية 1024) على قيمة أعلى من طول الإدخال بالرموز المميزة؛ إذ ستكون الاستجابة المقتطعة بسبب حد منخفض جدًا
غير مكتملة.
البنية
AIRedact
الوسيطات
text— النص المراد حجبه.Stringcategories— قائمة ثابتة بفئات معلومات التعريف الشخصية المراد حجبها (مثل['name', 'ssn', 'credit_card']). تستخدم المصفوفة الفارغة مجموعة افتراضية من الفئات الشائعة (الاسم، والبريد الإلكتروني، ورقم الهاتف، والعنوان، وبطاقة الائتمان، وعنوان IP).Array(String)params—Map(String, String)اختيارية وثابتة للمعلمات. المفاتيح الخاصة بالدالة هي:temperature(درجة حرارة أخذ العينات التي تتحكم في العشوائية؛ القيمة الافتراضية0.0)، وmax_tokens(الحد الأقصى لرموز الإخراج لكل استدعاء؛ القيمة الافتراضية1024— بما أنaiRedactيعيد النص كاملاً، فاضبطها على قيمة أكبر من طول الإدخال بالرموز، وإلا فقد تكون الاستجابة مقتطعة وغير مكتملة)، وreplacement(الرمز الذي يحل محل كل نطاق مكتشف من معلومات التعريف الشخصية؛ القيمة الافتراضية[REDACTED]). تنطبق أيضًا المعلمتان العامتانcredentialsوmodel(راجع دوال الذكاء الاصطناعي).Map(String, String)
ai_function_throw_on_error معطلاً. String
أمثلة
حجب فئات محددة
Query
Response
Query
aiSimilarity
-1 لمتجهات التضمين
المتعاكسة، ويعني ذلك دلاليًا أن النصوص ذات الدرجات التي تقترب من -1 متعاكسة في
المعنى. وتعني درجة 0 أن المتجهات متعامدة، أي غير مرتبطة دلاليًا. وأخيرًا، تعني درجة 1
أن متجهات التضمين تشير في الاتجاه نفسه، وأن النصوص ذات الدرجات التي تقترب من 1
متشابهة في المعنى. وهو مكمّل cosineDistance للتضمينات
نفسها (aiSimilarity = 1 - cosineDistance(embedding1, embedding2)).
تتطابق عملية التجميع على دفعات وبيانات الاعتماد والمعلمة dimensions مع aiEmbed، بما في ذلك
إعداد بيانات الاعتماد الافتراضية ai_function_embedding_default_credentials.
كما في aiEmbed، يُعدّ model وسيطًا موضعيًا مطلوبًا (قيمة ثابتة من نوع String) ولا يُقرأ من
المجموعة المُسمّاة أو خريطة المعلمات.
البنية
AISimilarity
الوسائط
text1— النص الأول.Stringtext2— النص الثاني.Stringmodel— اسم نموذج التضمين.const Stringparams—Map(String, String)ثابت اختياري للمعلمات. المفتاح الخاص بالدالة هو:dimensions(عدد الأبعاد المستهدف للتضمينات؛ تشير القيمة0أو عدم تحديده إلى الحجم الأصلي للنموذج). ينطبق أيضًا المعلمة العامةcredentials(راجع دوال الذكاء الاصطناعي).Map(String, String)
[-1, 1]، أو NULL إذا كان أحد النصين NULL أو فارغًا، أو إذا فشل طلب تضمين وكانت ai_function_throw_on_error معطّلة، أو إذا تم تجاوز حصة وكانت ai_function_throw_on_quota_exceeded معطّلة. Nullable(Float32)
أمثلة
قارن بين سلسلتين (credentials يمكن حذفها إذا كان الإعداد ai_function_embedding_default_credentials مضبوطًا)
Query
Query
Query
aiTranslate
instructions في خريطة المعلمات (على سبيل المثال: 'الإبقاء على المصطلحات التقنية دون ترجمة').
تُؤخذ بيانات الاعتماد (مجموعة مسماة تحدد الموفّر والنموذج ونقطة النهاية، ومفتاح واجهة برمجة تطبيقات اختياريًا)
من المفتاح credentials في خريطة المعلمات الاختيارية، أو من
الإعداد ai_function_text_default_credentials إذا لم تتضمنه الخريطة.
البنية
AITranslate
الوسيطات
text— النص المراد ترجمته.Stringtarget_language— اسم اللغة الهدف أو رمز BCP-47 لها (مثل'French'و'es-MX').Stringparams—Map(String, String)ثابت اختياري للمعلمات. المفاتيح الخاصة بهذه الدالة هي:temperature(درجة حرارة أخذ العينات التي تتحكم في العشوائية؛ والقيمة الافتراضية0.3)، وmax_tokens(الحد الأقصى لعدد التوكنات الناتجة في كل استدعاء؛ والقيمة الافتراضية1024)، وinstructions(تعليمات إضافية للمترجم تتعلق بالأسلوب أو اللهجة). كما تنطبق أيضًا المعلمتان الشائعتانcredentialsوmodel(راجع دوال الذكاء الاصطناعي).Map(String, String)
ai_function_throw_on_error معطّلًا. String
أمثلة
الترجمة إلى الفرنسية
Query
Response
Query