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

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

دوال الذكاء الاصطناعي تجريبية. اضبط 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).

التهيئة

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

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

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

المعلمة	النوع	الافتراضي	الوصف
`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'`).

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

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

تَرِد جميع الإعدادات المتعلقة بالذكاء الاصطناعي في الإعدادات تحت البادئة 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.

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

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

aiClassify(collection, text, categories[, temperature])

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

collection — اسم مجموعة مسماة تحتوي على بيانات اعتماد الموفّر والتهيئة. String
text — النص المطلوب تصنيفه. String
categories — قائمة ثابتة بتسميات الفئات المرشحة. Array(String)
temperature — درجة حرارة أخذ العينات التي تتحكم في مستوى العشوائية. القيمة الافتراضية: 0.0. Float64

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

Query

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

Response

positive

تصنيف عمود

Query

SELECT body, aiClassify('ai_credentials', body, ['bug', 'question', 'feature']) AS kind FROM issues LIMIT 5

Response

aiEmbed

أُضيفت في: v26.6.0 تُنشئ متجه تضمين للنص المحدد باستخدام موفّر الذكاء الاصطناعي المُهيّأ. ترسل الدالة النص إلى نقطة نهاية التضمين المُهيّأة وتُرجع المتجه الناتج بصيغة Array(Float32). ضمن كتلة واحدة من الصفوف، تُجمَّع المُدخلات في دفعات يصل حجمها إلى ai_function_embedding_max_batch_size عنصرًا لكل طلب HTTP لتقليل العبء الإضافي لكل استدعاء. الوسيطة الأولى هي مجموعة مُسمّاة تحدد الموفّر، والنموذج، ونقطة النهاية، ويمكن أن تتضمن مفتاح واجهة برمجة تطبيقات اختياريًا. وتطلب الوسيطة الاختيارية dimensions، عند دعمها من قِبل النموذج (مثل text-embedding-3-* من OpenAI)، متجهًا بالحجم المحدد؛ وإلا فسيُعاد الحجم الأصلي للنموذج. البنية

aiEmbed(collection, text[, dimensions])

الوسائط

collection — اسم مجموعة مُسمّاة تحتوي على بيانات اعتماد الموفّر والتهيئة. String
text — النص المطلوب تضمينه. String
dimensions — عدد الأبعاد المستهدف الاختياري لمتجه الإخراج. تعني القيمة 0 أو عدم تحديدها استخدام الحجم الأصلي للنموذج. UInt64

القيمة المُعادة متجه التضمين، أو مصفوفة فارغة إذا كان الإدخال NULL أو فارغًا، أو إذا فشل الطلب وكان ai_function_throw_on_error معطّلًا، أو إذا جرى تجاوز الحصة وكان ai_function_throw_on_quota_exceeded معطّلًا. Array(Float32) أمثلة تضمين سلسلة نصية واحدة

Query

SELECT aiEmbed('ai_credentials', 'Hello world')

Response

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

Query

SELECT aiEmbed('ai_credentials', 'Hello world', 256)

Response

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

Query

SELECT aiEmbed('ai_credentials', title, 256) FROM articles LIMIT 10

Response

aiExtract

أُضيف في: v26.4.0 يستخرج معلومات منظَّمة من نص غير منظَّم باستخدام موفّر LLM. يمكن أن تكون الوسيطة الثالثة إما تعليمة بلغة طبيعية حرة الصياغة (مثل 'the main complaint') أو مخططًا مُرمَّزًا بتنسيق JSON بالشكل '{"field_a": "description of field a", "field_b": "description of field b"}'. في وضع التعليمات، تُرجِع الدالة القيمة المستخرجة كسلسلة نصية عادية، أو سلسلة فارغة إذا لم يُعثر على أي شيء. وفي وضع المخطط، تُرجِع الدالة سلسلة كائن JSON تتطابق مفاتيحها مع المخطط المطلوب؛ وتكون الحقول المفقودة null. الوسيطة الأولى هي مجموعة مُسمّاة تحدد الموفّر والنموذج ونقطة النهاية، وبشكل اختياري مفتاح واجهة برمجة تطبيقات. البنية

aiExtract(collection, text, instruction_or_schema[, temperature])

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

collection — اسم مجموعة مُسمّاة تحتوي على بيانات اعتماد الموفّر والتهيئة. String
text — النص المراد استخراج المعلومات منه. String
instruction_or_schema — تعليمة استخراج بصياغة حرة، أو كائن JSON ثابت يصف الحقول المطلوب استخراجها. const String
temperature — درجة حرارة أخذ العينات التي تتحكم في مستوى العشوائية. القيمة الافتراضية: 0.0. const Float64

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

Query

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

Response

late and damaged package

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

Query

SELECT aiExtract('ai_credentials', review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5

Response

aiGenerate

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

aiGenerate(collection, prompt[, system_prompt[, temperature]])

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

collection — اسم مجموعة مسماة تحتوي على بيانات اعتماد الموفّر والتهيئة. String
prompt — موجّه المستخدم أو سؤاله الذي يُرسل إلى النموذج. String
system_prompt — تعليمة اختيارية ثابتة على مستوى النظام تُوجّه سلوك النموذج (مثل الشخصية أو تنسيق المخرجات)، وتُرسل مع كل موجّه. String
temperature — درجة حرارة أخذ العينات التي تتحكم في العشوائية. القيمة الافتراضية: 0.7. Float64

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

Query

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

Response

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

Query

SELECT aiGenerate('ai_credentials', 'Explain ClickHouse', 'You are a database expert. Be concise.')

Response

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

Query

SELECT article_title, aiGenerate('ai_credentials', concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5

Response

aiTranslate

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

aiTranslate(collection, text, target_language[, instructions[, temperature]])

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

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

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

Query

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

Response

Bonjour le monde!

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

Query

SELECT aiTranslate('ai_credentials', body, 'Japanese', 'Use polite form (desu/masu)') FROM articles LIMIT 5

Response

​التهيئة

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

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

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

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

​Observability

​aiClassify

​aiEmbed

​aiExtract

​aiGenerate

​aiTranslate

التهيئة

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

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

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

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

Observability

aiClassify

aiEmbed

aiExtract

aiGenerate

aiTranslate