تحسين محادثات ClickHouse Assistant باستخدام طبقة دلالية

دليل لاستخدام AGENTS.md لتزويد وكيل دردشة ClickHouse Assistant بمنطق أعمال مخصص وتعليمات خاصة بالبيانات

يمكن تخصيص وكيل دردشة ClickHouse Assistant لفهم منطق الأعمال الخاص بك، وهياكل البيانات، ومعرفة المجال لديك من خلال AGENTS.md، وهو استعلام محفوظ خاص يعمل كطبقة دلالية فوق مطالبة النظام الخاصة بالوكيل.

من خلال إنشاء ملف AGENTS.md، يمكنك تقديم تعليمات مخصصة تُحقن في بداية كل محادثة لتوجيه إنشاء استعلامات SQL وتحليل البيانات استنادًا إلى متطلبات مؤسستك الفريدة، وحساباتها، واصطلاحاتها.

​

كيف يعمل

عندما تحفظ استعلامًا باسم “AGENTS.md” (مع مراعاة حالة الأحرف) في Cloud Console:

1. يحمّل وكيل دردشة ClickHouse Assistant هذا الملف تلقائيًا عند إرسال رسالة
2. يُوضَع المحتوى داخل وسم محتوى منظَّم ويُدرَج في مطالبة النظام الخاصة بالوكيل
3. تُطبَّق هذه التعليمات على جميع محادثات دردشة ClickHouse Assistant في تلك الخدمة

​

إنشاء AGENTS.md

1. أنشئ الاستعلام المحفوظ

   1. في Cloud Console، أنشئ استعلامًا جديدًا
   2. سمّه بهذا الاسم تمامًا: “AGENTS.md” (مع مراعاة حالة الأحرف)
   3. اكتب تعليماتك المخصصة في محرر نص الاستعلام (وليس SQL فعليًا)
   4. احفظ الاستعلام
2. أضف تعليماتك

   نظّم تعليماتك بلغة واضحة وقابلة للتنفيذ. ضمّن ما يلي:

   • قواعد العمل والحسابات
   • إرشادات هيكلية البيانات
   • المصطلحات الخاصة بالمجال
   • أنماط الاستعلام الشائعة
   • قواعد تحسين الأداء

​

أفضل الممارسات

​

تعامل مع السياق بوصفه موردًا محدودًا

السياق ثمين—فكل token يستنزف “ميزانية الانتباه” لدى الوكيل. وكما هو الحال لدى البشر ذوي الذاكرة العاملة المحدودة، يتراجع أداء النماذج اللغوية كلما ازداد السياق. وهذا يعني العثور على أصغر مجموعة ممكنة من الرموز الأكثر دلالة بما يزيد إلى أقصى حد من احتمال الوصول إلى النتيجة التي تريدها.

​

اعثر على المستوى المناسب من التفصيل

وازن بين نقيضين:

• شديد التحديد: تضمين منطق if-else هش ومكتوب بشكل صارم، مما يخلق قابلية للكسر ويزيد تعقيد الصيانة
• شديد الغموض: إرشادات عامة لا تقدّم مؤشرات ملموسة أو تفترض خطأً وجود سياق مشترك

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

​

نظّم المحتوى في أقسام واضحة

استخدم وسوم XML أو عناوين Markdown لإنشاء أقسام مميّزة يسهل استعراضها:

<background_information>
Context about your data and domain
</background_information>

<calculation_rules>
Specific formulas and business logic
</calculation_rules>

<tool_guidance>
How to use specific ClickHouse features
</tool_guidance>

​

قدّم أمثلة متنوعة ومعيارية

الأمثلة بمثابة «صورة تساوي ألف كلمة». فبدلاً من حشر كل الحالات الحدّية في الـ prompt الخاص بك، انتقِ مجموعة مركّزة من الأمثلة المتنوعة التي توضّح السلوك المتوقع بفاعلية.

​

اجعله موجزًا لكن كاملًا

• أدرج فقط التعليمات التي يُحتاج إليها باستمرار
• كن موجزًا — فالسياق الأوسع يضعف الأداء بسبب “تعفّن السياق”
• احذف القواعد القديمة أو نادرة الاستخدام
• تأكد من توفر معلومات كافية لتوجيه السلوك المطلوب

لا يعني الحد الأدنى بالضرورة أن يكون قصيرًا. أنت بحاجة إلى قدر كافٍ من التفاصيل لضمان التزام الوكيل بالسلوك المتوقع، مع تجنب الإطناب غير الضروري.

​

مثال: المقاييس المحسوبة من البيانات الخام

وجّه الوكيل عندما تتطلب المقاييس حسابات محددة بدلًا من الوصول المباشر إلى العمود:

<metric_calculations>
IMPORTANT: "active_sessions" is NOT a column. It must be calculated.

To calculate active sessions:
COUNT(DISTINCT session_id || '|' || user_id) AS active_sessions

This counts unique combinations of session and user identifiers.

When the user asks for "active sessions" or "session count", always use this formula:
SELECT
    date,
    COUNT(DISTINCT session_id || '|' || user_id) AS active_sessions
FROM events
GROUP BY date;

</metric_calculations>

​

مثال: قواعد منطق الأعمال

عرِّف الحسابات والتصنيفات الخاصة بمجال العمل:

<business_rules>
Revenue Calculation:
- Exclude refunded transactions: WHERE transaction_status != 'refunded'
- Apply regional tax rates using CASE expressions
- Use MRR for subscriptions:
  SUM(CASE
    WHEN billing_cycle = 'monthly' THEN amount
    WHEN billing_cycle = 'yearly' THEN amount / 12
    ELSE 0
  END) AS mrr

Traffic Source Classification:
Use CASE expression to categorize:
CASE
  WHEN traffic_source IN ('google', 'bing', 'organic') THEN 'Organic Search'
  WHEN traffic_source IN ('facebook', 'instagram', 'social') THEN 'Social Media'
  WHEN traffic_source = 'direct' THEN 'Direct'
  ELSE 'Other'
END AS source_category

Customer Segmentation:
- Enterprise: annual_contract_value >= 100000
- Mid-Market: annual_contract_value >= 10000 AND annual_contract_value < 100000
- SMB: annual_contract_value < 10000

Always include these categorizations when generating traffic or revenue reports.
</business_rules>

​

مثال: خصوصيات بنية البيانات

وثّق تنسيقات البيانات غير التقليدية أو القرارات القديمة المتعلقة بالمخطط:

<data_structure_notes>
The user_status column uses numeric codes, not strings:
- 1 = 'active'
- 2 = 'inactive'
- 3 = 'suspended'
- 99 = 'deleted'

When filtering or displaying user status, always use:
CASE user_status
  WHEN 1 THEN 'active'
  WHEN 2 THEN 'inactive'
  WHEN 3 THEN 'suspended'
  WHEN 99 THEN 'deleted'
END AS status_label

The product_metadata column contains JSON strings that must be parsed:
SELECT
    product_id,
    JSONExtractString(product_metadata, 'category') AS category,
    JSONExtractInt(product_metadata, 'inventory_count') AS inventory
FROM products;
</data_structure_notes>

​

مثال: مصطلحات المجال

اربط مصطلحات الأعمال بالتنفيذ التقني:

<terminology>
When users refer to "conversions", they mean:
- For e-commerce: transactions WHERE transaction_type = 'purchase'
- For SaaS: subscriptions WHERE subscription_status = 'active' AND first_payment_date IS NOT NULL

"Churn" is calculated as:
COUNT(DISTINCT user_id) WHERE last_active_date < today() - INTERVAL 90 DAY
AND previous_subscription_status = 'active'

"DAU" (Daily Active Users) means:
COUNT(DISTINCT user_id) WHERE activity_date = today()

"Qualified leads" must meet ALL criteria:
- lead_score >= 70
- company_size >= 50
- budget_confirmed = true
- contact_role IN ('Director', 'VP', 'C-Level')
</terminology>