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

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

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

دوال الذكاء الاصطناعي في مرحلة Beta.

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

لا تتوفر دوال الذكاء الاصطناعي في خدمات ClickHouse Cloud في الوقت الحالي. ترقّب التحديثات.

حقن الموجّه

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

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

• فرض الحصص: حدود لكل استعلام على الرموز (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)، إذ تتطلب نقاط نهاية مختلفة وتستخدم عادةً نماذج مختلفة.

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

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

-- The embedding functions (`aiEmbed`, `aiSimilarity`) do not read `model` from the named collection,
-- pass it as a positional argument instead. Defining `model` in an embedding 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-...';

​

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

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

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

​

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

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

1. مفتاح credentials في خريطة المَعلمات الخاصة بها، إن وُجد؛
2. وإلا، إعداد بيانات الاعتماد الافتراضي المنطبق:
   • ai_function_text_default_credentials لدوال النص (aiGenerate وaiClassify وaiFilter وaiExtract وaiTranslate وaiRedact);
   • ai_function_embedding_default_credentials لدوال التضمين (aiEmbed وaiSimilarity).

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

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'));

رشِّح الصفوف باستخدام شرط بلغة طبيعية عبر aiFilter، إذ تُرجع UInt8 ويمكن استخدامها مباشرةً في WHERE:

SELECT * FROM reviews
WHERE aiFilter(body, 'the customer is angry about shipping');

​

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

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

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

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

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

SELECT aiGenerate(body, map('temperature', '0.2', 'system_prompt', 'You are terse.')) FROM articles;

​

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

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

​

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

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

<remote_url_allow_hosts>
    <host>api.openai.com</host>
    <host>api.anthropic.com</host>
</remote_url_allow_hosts>

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

​

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

يُحدَّد النقل حصريًا من خلال scheme لعنوان URL الخاص بـ 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 البيانات إلا على مسار الشبكة بين الخادم والموفّر.

​

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

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

​

Observability

يُتتبَّع نشاط AI function عبر ProfileEvents في ClickHouse:

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

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

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;

​

aiClassify

أُضيف في: v26.4.0

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

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

هذه الدالة غير حتمية: يمكن أن تُرجع نتائج مختلفة للوسيطات نفسها.

البنية

aiClassify(text, categories[, params])

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

وسيطات الدالة

• text — النص المطلوب تصنيفه. String
• categories — قائمة ثابتة بتسميات الفئات المرشحة. Array(String)
• params — Map(String, String) ثابت اختياري للمعلمات. المفاتيح الخاصة بالدالة: temperature (درجة حرارة أخذ العينات التي تتحكم في مستوى العشوائية؛ القيمة الافتراضية 0.0) وmax_tokens (الحد الأقصى لعدد الرموز المُخرجة في كل استدعاء؛ القيمة الافتراضية 1024). كما تنطبق أيضًا المعلمات العامة credentials وmodel (راجع دوال الذكاء الاصطناعي). Map(String, String)

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

إحدى تسميات الفئات المقدَّمة، أو القيمة الافتراضية لنوع العمود (سلسلة فارغة) إذا فشل الطلب وكان ai_function_throw_on_error معطّلًا. String

أمثلة

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

Query

SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral'])

Response

positive

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

Query

CREATE TABLE issues (body String) ENGINE = Memory;
INSERT INTO issues VALUES ('The application exits unexpectedly after login.');
SELECT body, aiClassify(body, ['bug', 'question', 'feature'], map('credentials', 'ai_text_credentials')) AS kind FROM issues LIMIT 5

​

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)، متجهًا بالحجم المحدد؛ وإلا فسيُعاد الحجم الأصلي للنموذج.

البنية

aiEmbed(text, model[, params])

الأسماء البديلة: AIEmbed

وسيطات الدالة

• text — النص المراد تحويله إلى تضمين. String
• model — اسم نموذج التضمين. const String
• params — Map(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

SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials'))

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

Query

SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256'))

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

Query

CREATE TABLE articles (title String) ENGINE = Memory;
INSERT INTO articles VALUES ('ClickHouse is a fast analytical database.');
SELECT aiEmbed(title, 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) FROM articles LIMIT 10

​

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, instruction_or_schema[, params])

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

وسيطات الدالة

• text — النص المراد استخراج المعلومات منه. String
• instruction_or_schema — تعليمة استخراج بصياغة حرة، أو كائن JSON ثابت يصف الحقول المطلوب استخراجها. const String
• params — Map(String, String) ثابت اختياري للمعلمات. المفاتيح الخاصة بالدالة هي: temperature (درجة حرارة أخذ العينات التي تتحكم في مستوى العشوائية؛ الافتراضي 0.0) وmax_tokens (الحد الأقصى لرموز الإخراج في كل استدعاء؛ الافتراضي 1024). كما تنطبق أيضًا المعلمات العامة credentials وmodel (راجع دوال الذكاء الاصطناعي). Map(String, String)

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

قيمة واحدة مستخرجة (وضع التعليمات) أو سلسلة JSON تمثل كائنًا (وضع المخطط). تُرجِع القيمة الافتراضية لنوع العمود (سلسلة فارغة) إذا فشل الطلب وكان ai_function_throw_on_error معطّلًا. String

أمثلة

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

Query

SELECT aiExtract('The package arrived late and was damaged.', 'the main complaint')

Response

late and damaged package

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

Query

CREATE TABLE reviews (review String) ENGINE = Memory;
INSERT INTO reviews VALUES ('The screen is bright, but the battery lasts only two hours.');
SELECT aiExtract(review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5

​

aiFilter

أُضيف في: v26.8.0

يقيّم شرطًا مكتوبًا بلغة طبيعية على النص المحدد باستخدام موفّر LLM، ويُرجع قيمة منطقية (UInt8) مناسبة للاستخدام في WHERE وPREWHERE وJOIN ... ON.

تطلب الدالة من النموذج أن يردّ بـ true أو false فقط وبأحرف صغيرة. تُحوَّل أي استجابة مكتملة بخلاف true (بما في ذلك false والنص غير المعروف) إلى 0، وبالتالي يُستبعد الصف. أما الرد غير المكتمل الذي يشير إليه الموفّر — سواء كان مقتطعًا أو مُرشَّحًا للمحتوى أو يتطلب إجراءً إضافيًا — فيُعامل بدلًا من ذلك كخطأ: عند تفعيل ai_function_throw_on_error (وهو الإعداد الافتراضي) يُجهض الاستعلام؛ وعند تعطيله تُحوَّل قيمة الصف إلى 0 ويُستبعد.

تحذير: لا تعتمد على نتائج aiFilter دون تدقيق. قد تكون المسندات المستندة إلى LLM غير صحيحة أو غير متسقة؛ لذا لا تستخدمها إلا عندما تكون الإيجابيات الكاذبة والسلبيات الكاذبة مقبولة.

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

ملاحظة: يؤدي استخدام aiFilter في JOIN ... ON إلى تقييم LLM مرة واحدة لكل زوج مرشّح، وقد يكون ذلك مكلفًا.

هذه الدالة غير حتمية: يمكن أن تُرجع نتائج مختلفة للوسيطات نفسها.

البنية

aiFilter(text, condition[, params])

الأسماء البديلة: AIFilter

وسيطات الدالة

• text — النص المراد تقييمه. String
• condition — شرط ثابت باللغة الطبيعية يجب أن يستوفيه النص. String
• params — Map(String, String) ثابت اختياري للمعلمات. المفاتيح الخاصة بالدالة هي: temperature (درجة حرارة أخذ العينات التي تتحكم في العشوائية؛ القيمة الافتراضية 0.0) وmax_tokens (الحد الأقصى لرموز الإخراج لكل استدعاء؛ القيمة الافتراضية 1024). تنطبق أيضًا المعلمتان العامتان credentials وmodel (راجع دوال الذكاء الاصطناعي). Map(String, String)

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

1 إذا كان النص يطابق الشرط، و0 في غير ذلك. تُرجع القيمة الافتراضية (0) إذا فشل الطلب وكان ai_function_throw_on_error معطّلًا. UInt8

أمثلة

تصفية المراجعات الغاضبة

Query

CREATE TABLE reviews (body String) ENGINE = Memory;
INSERT INTO reviews VALUES ('The package arrived three days late.');
SELECT * FROM reviews WHERE aiFilter(body, 'the customer is angry about shipping')

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

Query

CREATE TABLE issues (body String) ENGINE = Memory;
INSERT INTO issues VALUES ('The application exits unexpectedly after login.');
SELECT body, aiFilter(body, 'describes a bug', map('credentials', 'ai_text_credentials')) AS is_bug FROM issues LIMIT 5

​

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[, params])

الأسماء البديلة: 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

SELECT aiGenerate('What is 2 + 2? Reply with just the number.')

Response

4

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

Query

SELECT aiGenerate('Explain ClickHouse', map('credentials', 'ai_text_credentials', 'system_prompt', 'You are a database expert. Be concise.'))

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

Query

CREATE TABLE articles (article_title String, article_body String) ENGINE = Memory;
INSERT INTO articles VALUES ('ClickHouse', 'ClickHouse is an open-source column-oriented database for online analytical processing.');
SELECT article_title, aiGenerate(concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5

​

aiRedact

أُضيف في: v26.8.0

يكتشف معلومات تحديد الهوية الشخصية (PII) في النص المعطى ويحجبها باستخدام موفّر LLM.

ينفّذ aiRedact اكتشاف معلومات تحديد الهوية الشخصية وحجبها بأفضل جهد باستخدام LLM، ولا يُعتمد على ناتجه. يعتمد اكتشاف معلومات تحديد الهوية الشخصية وإزالتها على النموذج المختار والموجّه والإدخال؛ فقد يفوّت النموذج المعرّفات أو يحجبها جزئيًا فقط أو يغيّر النص المحيط بها. يعمل بأفضل صورة مع النصوص الإنجليزية السليمة؛ وقد تكون النتائج أسوأ مع اللغات الأخرى أو النصوص التي تتضمن الكثير من الأخطاء الإملائية أو أخطاء علامات الترقيم أو الأخطاء النحوية. لا يضمن aiRedact خلو ناتجه من معلومات تحديد الهوية الشخصية، ويجب ألا يُعامل وحده كآلية آمنة أو كافية لإخفاء الهوية. راجع الناتج دائمًا للتأكد من أنه يلتزم بسياسات مؤسستك المتعلقة بخصوصية البيانات والامتثال قبل كشف البيانات لأطراف غير موثوقة.

يُستبدل كل نطاق مكتشف من معلومات تحديد الهوية الشخصية برمز حجب ([REDACTED] افتراضيًا، ويمكن تهيئته عبر المعلمة replacement). تقيّد مصفوفة categories أنواع معلومات تحديد الهوية الشخصية التي تُحجب؛ أما المصفوفة الفارغة فتستخدم مجموعة افتراضية من الفئات الشائعة (الاسم، البريد الإلكتروني، رقم الهاتف، العنوان، بطاقة الائتمان، عنوان IP).

يوجّه aiRedact النموذج إلى تغيير نطاقات معلومات تحديد الهوية الشخصية المكتشفة فقط، لكن الحفاظ على النص المحيط بها يتم بأفضل جهد، وقد يظل النموذج يغيّره (انظر التحذير أعلاه). تُحوَّل أيضًا محارف التحكم، باستثناء علامة الجدولة والسطر الجديد وعودة العربة، إلى مسافات قبل إرسال الطلب، لذلك لا يكون الناتج مطابقًا على مستوى البايت للمدخلات التي تحتوي عليها.

لأن aiRedact يعيد النص الكامل للإدخال بعد استبدال معلومات تحديد الهوية الشخصية، فإن طول الناتج يقارب طول الإدخال. اضبط max_tokens (القيمة الافتراضية 1024) على قيمة أعلى من طول الإدخال برموز الإدخال؛ إذ تُرفض الاستجابة المقتطعة بسبب حد منخفض جدًا مع AI_PROVIDER_RESPONSE_TRUNCATED (أو تُنتج القيمة الافتراضية للعمود عندما يكون ai_function_throw_on_error معطلاً) بدلًا من إرجاع نص محجوب جزئيًا.

هذه الدالة غير حتمية: يمكن أن تعيد نتائج مختلفة للوسيطات نفسها.

البنية

aiRedact(text, categories[, params])

الأسماء البديلة: AIRedact

وسيطات الدالة

• text — النص المراد حجبه. String
• categories — قائمة ثابتة بفئات معلومات تحديد الهوية الشخصية المراد حجبها (مثل ['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

SELECT aiRedact('Purchase was done by customer John Doe with email [e-mail]', ['email', 'credit_card', 'name'])

Response

Purchase was done by customer [REDACTED] with email [REDACTED]

احجب فئات معلومات تحديد الهوية الشخصية الافتراضية باستخدام رمز مميز مخصص

Query

CREATE TABLE tickets (body String) ENGINE = Memory;
INSERT INTO tickets VALUES ('Contact Jane Doe at [e-mail].');
SELECT aiRedact(body, [], map('replacement', '***')) FROM tickets LIMIT 5

​

aiSimilarity

أُضيف في: v26.8.0

يحسب التشابه الدلالي بين نصّين باستخدام موفّر التضمين المُهيّأ.

يحسب التضمينات المتجهية لكلا النصّين ويُرجع تشابه جيب التمام. تُمنح درجة -1 لمتجهات التضمين المتعاكسة، ويعني ذلك دلاليًا أن النصوص ذات الدرجات التي تقترب من -1 متعاكسة في المعنى. وتعني درجة 0 أن المتجهات متعامدة، أي غير مرتبطة دلاليًا. وأخيرًا، تعني درجة 1 أن متجهات التضمين تشير في الاتجاه نفسه، وأن النصوص ذات الدرجات التي تقترب من 1 متشابهة في المعنى. وهو مكمّل cosineDistance للتضمينات نفسها (aiSimilarity = 1 - cosineDistance(embedding1, embedding2)).

تتطابق عملية التجميع على دفعات وبيانات الاعتماد والمعلمة dimensions مع aiEmbed، بما في ذلك إعداد بيانات الاعتماد الافتراضية ai_function_embedding_default_credentials.

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

البنية

aiSimilarity(text1, text2, model[, params])

الأسماء البديلة: AISimilarity

وسيطات الدالة

• text1 — النص الأول. String
• text2 — النص الثاني. String
• model — اسم نموذج التضمين. const String
• params — 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

SELECT aiSimilarity('cat', 'kitten', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials'))

رتّب المراجعات حسب مدى تشابهها مع استعلام

Query

CREATE TABLE product_reviews (review String) ENGINE = Memory;
INSERT INTO product_reviews VALUES ('It works well under rain.');
SELECT review FROM product_reviews ORDER BY aiSimilarity(review, 'It works well under rain', 'text-embedding-3-small') DESC LIMIT 100

إزالة التكرار الدلالي باستخدام ربط ذاتي

Query

CREATE TABLE docs (id UInt64, title String) ENGINE = Memory;
INSERT INTO docs VALUES (1, 'ClickHouse documentation'), (2, 'ClickHouse database guide');
SELECT a.id, b.id FROM docs a, docs b WHERE a.id < b.id AND aiSimilarity(a.title, b.title, 'text-embedding-3-small') > 0.9

​

aiTranslate

أُضيف في: v26.4.0

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

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

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

هذه الدالة غير حتمية: فقد تُرجع نتائج مختلفة للوسيطات نفسها.

البنية

aiTranslate(text, target_language[, params])

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

وسيطات الدالة

• text — النص المراد ترجمته. String
• target_language — اسم اللغة الهدف أو رمز BCP-47 لها (مثل 'French' و'es-MX'). String
• params — Map(String, String) ثابت اختياري للمعلمات. المفاتيح الخاصة بهذه الدالة هي: temperature (درجة حرارة أخذ العينات التي تتحكم في العشوائية؛ والقيمة الافتراضية 0.3)، وmax_tokens (الحد الأقصى لعدد رموز الإخراج في كل استدعاء؛ والقيمة الافتراضية 1024)، وinstructions (تعليمات إضافية للمترجم تتعلق بالأسلوب أو اللهجة). كما تنطبق أيضًا المعلمتان العامتان credentials وmodel (راجع دوال الذكاء الاصطناعي). Map(String, String)

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

النص المترجم، أو القيمة الافتراضية لنوع العمود (سلسلة فارغة) إذا فشل الطلب وكان ai_function_throw_on_error معطّلًا. String

أمثلة

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

Query

SELECT aiTranslate('Hello, world!', 'French')

Response

Bonjour le monde!

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

Query

CREATE TABLE articles (body String) ENGINE = Memory;
INSERT INTO articles VALUES ('ClickHouse processes analytical queries quickly.');
SELECT aiTranslate(body, 'Japanese', map('instructions', 'Use polite form (desu/masu)')) FROM articles LIMIT 5