1- نظرة عامة
في هذا الدرس التطبيقي حول الترميز، ستنشئ تطبيقًا قابلاً للتوسّع للبحث في "قاعدة المعلومات". بدلاً من إدارة مسار استخراج البيانات وتحويلها وتحميلها المعقّد باستخدام نصوص برمجية وحلقات Python لإنشاء عمليات تضمين متّجهات، ستستخدم AlloyDB AI للتعامل مع إنشاء عمليات التضمين بشكلٍ أصلي داخل قاعدة البيانات باستخدام أمر SQL واحد.
ما ستنشئه
تطبيق قاعدة بيانات "قابل للبحث" عن قاعدة معلومات بأداء عالٍ
أهداف الدورة التعليمية
ستتعرّف على كيفية:
- توفير مجموعة AlloyDB وتفعيل إضافات الذكاء الاصطناعي
- إنشاء بيانات اصطناعية (أكثر من 50,000 صف) باستخدام SQL
- إعادة ملء تضمينات المتجهات لمجموعة البيانات بأكملها باستخدام المعالجة المجمّعة
- إعداد المشغّلات التزايدية في الوقت الفعلي لتضمين البيانات الجديدة تلقائيًا
- إجراء البحث المختلط (المتجه + فلاتر SQL) عن "السياق المرن"
المتطلبات
2. قبل البدء
إنشاء مشروع
- في Google Cloud Console، ضمن صفحة اختيار المشروع، اختَر أو أنشِئ مشروعًا على Google Cloud.
- تأكَّد من تفعيل الفوترة لمشروعك على Cloud. تعرَّف على كيفية التحقّق من تفعيل الفوترة في مشروع.
- ستستخدم Cloud Shell، وهي بيئة سطر أوامر تعمل في Google Cloud. انقر على "تفعيل Cloud Shell" في أعلى "وحدة تحكّم Google Cloud".
- بعد الاتصال بـ Cloud Shell، يمكنك التأكّد من أنّك قد أثبتّ هويتك وأنّ المشروع مضبوط على معرّف مشروعك باستخدام الأمر التالي:
gcloud auth list
- نفِّذ الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك.
gcloud config list project
- إذا لم يتم ضبط مشروعك، استخدِم الأمر التالي لضبطه:
gcloud config set project <YOUR_PROJECT_ID>
- فعِّل واجهات برمجة التطبيقات المطلوبة: اتّبِع الرابط وفعِّل واجهات برمجة التطبيقات.
يمكنك بدلاً من ذلك استخدام أمر gcloud لهذا الغرض. راجِع المستندات لمعرفة أوامر gcloud وطريقة استخدامها.
gcloud services enable \
alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com
المشاكل المحتملة وتحديد المشاكل وحلّها
متلازمة "المشروع الوهمي" | نفّذت الأمر |
حاجز الفوترة | لقد فعّلت المشروع، ولكن نسيت حساب الفوترة. AlloyDB هو محرّك عالي الأداء، ولن يبدأ إذا كان "خزان الوقود" (الفوترة) فارغًا. |
تأخُّر انتشار واجهة برمجة التطبيقات | نقرت على "تفعيل واجهات برمجة التطبيقات"، ولكن سطر الأوامر لا يزال يعرض |
Quota Quags | إذا كنت تستخدم حسابًا تجريبيًا جديدًا تمامًا، قد تبلغ حصة إقليمية لمثيلات AlloyDB. إذا تعذّر تنفيذ |
وكيل الخدمة"مخفي" | في بعض الأحيان، لا يتم منح دور |
3- إعداد قاعدة البيانات
في هذا التمرين العملي، سنستخدم AlloyDB كقاعدة بيانات لبيانات الاختبار. تستخدم المجموعات للاحتفاظ بجميع الموارد، مثل قواعد البيانات والسجلات. تحتوي كل مجموعة على مثيل أساسي يوفّر نقطة وصول إلى البيانات. ستحتوي الجداول على البيانات الفعلية.
لننشئ مجموعة ومثيل وجدول AlloyDB سيتم تحميل مجموعة البيانات الاختبارية فيها.
- انقر على الزر أو انسخ الرابط أدناه إلى المتصفّح الذي سجّلت فيه الدخول إلى حساب مستخدم Google Cloud Console.
- بعد إكمال هذه الخطوة، سيتم استنساخ المستودع إلى محرّر Cloud Shell المحلي، وستتمكّن من تنفيذ الأمر أدناه من مجلد المشروع (من المهم التأكّد من أنّك في دليل المشروع):
sh run.sh
- استخدِم الآن واجهة المستخدم (من خلال النقر على الرابط في الوحدة الطرفية أو النقر على الرابط "معاينة على الويب" في الوحدة الطرفية).
- أدخِل تفاصيل معرّف المشروع واسمَي المجموعة والآلة الافتراضية لبدء الاستخدام.
- يمكنك تناول القهوة بينما يتم عرض السجلات، ويمكنك الاطّلاع على كيفية تنفيذ ذلك في الخلفية هنا. قد يستغرق ذلك حوالي 10 إلى 15 دقيقة.
المشاكل المحتملة وتحديد المشاكل وحلّها
مشكلة "الصبر" | مجموعات قواعد البيانات هي بنية أساسية ثقيلة. إذا أعَدت تحميل الصفحة أو أغلقت جلسة Cloud Shell لأنّها "تبدو عالقة"، قد ينتهي بك الأمر إلى إنشاء آلة افتراضية "وهمية" تم توفيرها جزئيًا ولا يمكن حذفها بدون تدخّل يدوي. |
عدم تطابق المنطقة | إذا فعّلت واجهات برمجة التطبيقات في |
مجموعات الزومبي | إذا سبق لك استخدام الاسم نفسه لمجموعة ولم تحذفها، قد تشير البرمجة النصية إلى أنّ اسم المجموعة مستخدَم من قبل. يجب أن تكون أسماء المجموعات فريدة ضمن المشروع. |
انتهاء مهلة Cloud Shell | إذا استغرقت استراحة القهوة 30 دقيقة، قد يتم تشغيل وضع السكون في Cloud Shell وفصل عملية |
4. توفير المخطط
في هذه الخطوة، سنتناول ما يلي:
بعد تشغيل مجموعة AlloyDB ومثيلها، انتقِل إلى أداة تعديل SQL في AlloyDB Studio لتفعيل إضافات الذكاء الاصطناعي وتوفير المخطّط.
قد تحتاج إلى الانتظار إلى أن يكتمل إنشاء مثيلك. بعد ذلك، سجِّل الدخول إلى AlloyDB باستخدام بيانات الاعتماد التي أنشأتها عند إنشاء المجموعة. استخدِم البيانات التالية للمصادقة على PostgreSQL:
- اسم المستخدم : "
postgres" - قاعدة البيانات : "
postgres" - كلمة المرور : "
alloydb" (أو أي كلمة مرور تم ضبطها عند إنشاء الحساب)
بعد إكمال عملية المصادقة بنجاح في AlloyDB Studio، يتم إدخال أوامر SQL في "المحرّر". يمكنك إضافة نوافذ "المحرّر" متعددة باستخدام علامة الجمع على يسار النافذة الأخيرة.
ستُدخل أوامر AlloyDB في نوافذ المحرّر، باستخدام الخيارات "تشغيل" و"تنسيق" و"محو" حسب الحاجة.
تفعيل الإضافات
لإنشاء هذا التطبيق، سنستخدم الإضافتين pgvector وgoogle_ml_integration. تتيح لك إضافة pgvector تخزين عمليات التضمين المتجهة والبحث عنها. توفّر إضافة google_ml_integration دوال يمكنك استخدامها للوصول إلى نقاط نهاية التوقّعات في Vertex AI من أجل الحصول على توقّعات في SQL. فعِّل هذه الإضافات من خلال تنفيذ تعريفات البيانات التالية:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
إنشاء جدول
نحتاج إلى مجموعة بيانات لتوضيح المقياس. بدلاً من استيراد ملف CSV، سننشئ 50,000 صف من "مقالات المساعدة" الاصطناعية على الفور باستخدام SQL.
يمكنك إنشاء جدول باستخدام عبارة DDL أدناه في AlloyDB Studio:
-- 1. Create the table
CREATE TABLE help_articles (
id SERIAL PRIMARY KEY,
title TEXT,
category TEXT,
product_version TEXT,
content_body TEXT,
embedding vector(768) -- Dimension for text-embedding-005
);
-- 2. Generate 50,000 rows of synthetic data
INSERT INTO help_articles (title, category, product_version, content_body)
SELECT
'Help Article ' || i,
CASE
WHEN i % 3 = 0 THEN 'Billing'
WHEN i % 3 = 1 THEN 'Technical'
ELSE 'General'
END,
CASE
WHEN i % 2 = 0 THEN '2.0'
ELSE '1.0'
END,
'This article covers common issues regarding ' ||
CASE
WHEN i % 3 = 0 THEN 'payment failures, invoice disputes, and credit card updates.'
WHEN i % 3 = 1 THEN 'connection timeouts, latency issues, and API errors.'
ELSE 'account profile settings, password resets, and user roles.'
END
FROM generate_series(1, 50000) AS i;
سيسمح العمود item_vector بتخزين قيم المتّجه للنص.
تحقَّق من البيانات:
SELECT count(*) FROM help_articles;
-- Output: 50000
تفعيل علامات قاعدة البيانات
انتقِل إلى "وحدة تحكّم إعدادات المثيل"، وانقر على "تعديل المثيل الأساسي"، ثم انتقِل إلى "الإعدادات المتقدّمة" وانقر على "إضافة علامات قاعدة البيانات".
إذا لم يكن كذلك، أدخِله في القائمة المنسدلة الخاصة بالعلامات واضبطه على "مفعَّل" ثم حدِّث المثيل.
إذا لم يكن كذلك، أدخِله في القائمة المنسدلة الخاصة بالعلامات واضبطه على "مفعَّل" ثم حدِّث المثيل.
خطوات ضبط علامات قاعدة البيانات:
- في Google Cloud Console، انتقِل إلى صفحة "المجموعات".
- انقر على مجموعة في عمود اسم المورد.
- في صفحة نظرة عامة، انتقِل إلى الآلات الافتراضية في مجموعتك، واختَر آلة افتراضية، ثم انقر على تعديل.
- إضافة علامة قاعدة بيانات أو تعديلها أو حذفها من مثيلك:
إضافة علامة
- لإضافة علامة قاعدة بيانات إلى مثيلك، انقر على "إضافة علامة".
- اختَر علامة من قائمة "علامة قاعدة البيانات الجديدة".
- أدخِل قيمة للعَلم.
- انقر على "تم".
- انقر على تعديل الجهاز الافتراضي.
- تأكَّد من أنّ إصدار إضافة google_ml_integration هو 1.5.2 أو إصدار أحدث:
للاطّلاع على إصدار الإضافة، استخدِم الأمر التالي:
SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
إذا كنت بحاجة إلى ترقية الإضافة إلى إصدار أحدث، استخدِم الأمر التالي:
ALTER EXTENSION google_ml_integration UPDATE;
منح الإذن
- للسماح لأحد المستخدمين بإدارة عملية إنشاء عمليات التضمين التلقائي، امنحه أذونات INSERT وUPDATE وDELETE على الجدولَين google_ml.embed_gen_progress وgoogle_ml.embed_gen_settings:
GRANT INSERT, UPDATE, DELETE ON google_ml.embed_gen_progress TO postgres;
postgres هو USER_NAME الذي تم منح الأذونات له.
- نفِّذ العبارة أدناه لمنح إذن التنفيذ على الدالة "embedding":
GRANT EXECUTE ON FUNCTION embedding TO postgres;
منح دور "مستخدم Vertex AI" لحساب خدمة AlloyDB
من وحدة تحكّم Google Cloud IAM، امنح حساب خدمة AlloyDB (الذي يبدو على النحو التالي: service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com) إذن الوصول إلى الدور "مستخدم Vertex AI". سيحتوي PROJECT_NUMBER على رقم مشروعك.
بدلاً من ذلك، يمكنك تنفيذ الأمر أدناه من "وحدة Cloud Shell الطرفية":
PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"
المشاكل المحتملة وتحديد المشاكل وحلّها
حلقة "فقدان الذاكرة" بشأن كلمات المرور | إذا كنت قد استخدمت عملية الإعداد "بنقرة واحدة" ولم تتمكّن من تذكُّر كلمة المرور، انتقِل إلى صفحة "المعلومات الأساسية للمثيل" في وحدة التحكّم وانقر على "تعديل" لإعادة ضبط كلمة مرور |
رسالة الخطأ "لم يتم العثور على الإضافة" | إذا تعذّر تنفيذ |
5- إنشاء رسومات متّجهة "بطلقة واحدة"
هذا هو جوهر الدرس التطبيقي. بدلاً من كتابة حلقة Python لمعالجة هذه الصفوف البالغ عددها 50,000، سنستخدم الدالة ai.initialize_embeddings.
ينفِّذ هذا الأمر الفردي الإجراءَين التاليَين:
- إعادة ملء جميع الصفوف الحالية
- إنشاء عبارة تشغيل لتضمين الصفوف المستقبلية تلقائيًا
نفِّذ عبارة SQL أدناه من "محرّر طلبات البحث" في AlloyDB
CALL ai.initialize_embeddings(
model_id => 'text-embedding-005',
table_name => 'help_articles',
content_column => 'content_body',
embedding_column => 'embedding',
incremental_refresh_mode => 'transactional'
);
التحقّق من عمليات التضمين
تأكَّد من أنّه تم الآن ملء العمود embedding:
SELECT id, left(content_body, 30), substring(embedding::text, 1, 30) as vector_partial
FROM help_articles;
يجب أن تظهر لك نتيجة مشابهة لما يلي:
ما الذي حدث للتو؟
- تعبئة البيانات على نطاق واسع: يتم تلقائيًا البحث في الصفوف الحالية التي يبلغ عددها 50,000 صف وإنشاء عمليات تضمين من خلال Vertex AI.
- الأتمتة: من خلال ضبط incremental_refresh_mode => ‘transactional'، تعمل AlloyDB تلقائيًا على إعداد المشغّلات الداخلية. سيتم إنشاء عملية التضمين على الفور لأي صف جديد يتم إدراجه في help_articles.
- يمكنك اختياريًا ضبط incremental_refresh_mode => ‘None' حتى تتمكّن من الحصول على البيان لإجراء تعديلات مجمّعة واستدعاء ai.refresh_embeddings() يدويًا لتعديل جميع تضمينات الصفوف.
لقد استبدلت للتو قائمة انتظار Kafka وعاملاً في Python ونصًا برمجيًا لنقل البيانات بـ 6 أسطر من SQL. إليك المستندات الرسمية التفصيلية لجميع السمات.
اختبار المشغّل في الوقت الفعلي
لنتأكّد من أنّ ميزة "التكرار الصفري" التلقائية تعمل مع البيانات الجديدة.
- إدراج صف جديد:
INSERT INTO help_articles (title, category, product_version, content_body)
VALUES ('New Scaling Guide', 'Technical', '2.0', 'How to scale AlloyDB to millions of transactions.');
- التحقّق على الفور:
SELECT embedding FROM help_articles WHERE title = 'New Scaling Guide';
النتيجة:
من المفترض أن يظهر لك الرسم المتجهي الذي تم إنشاؤه على الفور بدون تشغيل أي نص برمجي خارجي.
حجم دفعة الضبط
يتم حاليًا ضبط حجم الدفعة تلقائيًا في AlloyDB على 50. على الرغم من أنّ الإعدادات التلقائية تعمل بشكل رائع فور توفّرها، تتيح AlloyDB للمستخدمين إمكانية ضبط الإعدادات المثالية للنموذج ومجموعة البيانات الفريدَين.
CALL ai.initialize_embeddings(
model_id => 'text-embedding-005',
table_name => 'help_articles',
content_column => 'content_body',
embedding_column => 'embedding',
incremental_refresh_mode => 'transactional',
batch_size => 20
);
ومع ذلك، يجب أن يكون المستخدمون على دراية بحدود الحصة التي يمكن أن تحدّ من الأداء. لمراجعة حصص AlloyDB المقترَحة، راجِع القسم "قبل البدء" في المستندات.
المشاكل المحتملة وتحديد المشاكل وحلّها
فجوة نشر إدارة الهوية وإمكانية الوصول | لقد نفّذت أمر |
عدم تطابق أبعاد المتّجه | تم ضبط الجدول |
6. Flexing Context Search
الآن، سننفّذ بحثًا مختلطًا. نحن نجمع بين الفهم الدلالي (المتجه) ومنطق النشاط التجاري (فلاتر SQL).
نفِّذ طلب البحث هذا للعثور على مشاكل الفوترة الخاصة بالإصدار 2.0 من المنتج:
SELECT
title,
left(content_body, 100) as content_snippet,
1 - (embedding <=> embedding('text-embedding-005', 'Invoice did not go through')::vector) as relevance
FROM help_articles
WHERE category = 'Billing' -- Hard SQL Filter
AND product_version = '2.0' -- Hard SQL Filter
ORDER BY relevance DESC
LIMIT 5;
هذه هي ميزة "تكييف المحتوى مع السياق". تتكيّف ميزة البحث لفهم نية المستخدم ("مشاكل الفوترة") مع مراعاة القيود الصارمة للنشاط التجاري (الإصدار 2.0).
أسباب نجاح هذه الميزة في "الشركات الناشئة" و"عمليات نقل البيانات"
- عدم وجود ديون متعلقة بالبنية الأساسية: لم يتم إنشاء قاعدة بيانات متجهات منفصلة (Pinecone/Milvus). لم تكتب مهمة ETL منفصلة. كل ذلك في Postgres.
- التعديلات في الوقت الفعلي: من خلال استخدام وضع "المعاملات"، لن يصبح فهرس البحث قديمًا أبدًا. عندما يتم إدخال البيانات، تصبح جاهزة للاستخدام مع المتجهات.
- قابلية التوسّع: يستند AlloyDB إلى بنية Google الأساسية. يمكنه التعامل مع الإنشاء المجمّع لملايين المتجهات بشكل أسرع من أي نص برمجي بلغة Python.
المشاكل المحتملة وتحديد المشاكل وحلّها
ملاحظة بشأن أداء الإنتاج | المشكلة: سرعة معالجة 50,000 صف بطيء جدًا عند استخدام مليون صف إذا لم يكن فلتر الفئة انتقائيًا بدرجة كافية.الحل:أضِف "فهرسًا متّجهًا": بالنسبة إلى نطاق الإنتاج، عليك إنشاء فهرس:CREATE INDEX ON help_articles USING hnsw (embedding vector_cosine_ops);التحقّق من استخدام الفهرس: شغِّل |
كارثة "عدم تطابق النماذج" | المشكلة: تم تهيئة العمود باستخدام text-embedding-005 في إجراء CALL. إذا استخدمت عن طريق الخطأ نموذجًا مختلفًا (مثل text-embedding-004 أو نموذج مفتوح المصدر) في الدالة SELECT query function embedding('model-name', ...)، قد تتطابق السمات (768)، ولكن ستكون مساحة المتجهات مختلفة تمامًا. سيتم تنفيذ طلب البحث بدون حدوث خطأ، ولكن ستكون النتائج غير ذات صلة تمامًا (ستكون درجات الصلة غير صالحة). لتحديد المشاكل وحلّها، تأكَّد من أنّ model_id في ai.initialize_embeddings يتطابق تمامًا مع model_id في طلب البحث SELECT. |
نتيجة "الفراغ الصامت" (الإفراط في الفلترة) | المشكلة: البحث المختلط هو عملية "و". يتطلّب ذلك المطابقة الدلالية ومطابقة SQL.إذا بحث مستخدم عن "مساعدة بشأن الفوترة" وكان العمود
|
4. أخطاء الأذونات/الحصص (الخطأ 500) | المشكلة:تُجري الدالة
|
5- التضمينات الخالية | المشكلة:إذا أدرجت بيانات قبل اكتمال تهيئة النموذج أو إذا تعذّر على عامل الخلفية تنفيذ العملية، قد تحتوي بعض الصفوف على
|
7. تَنظيم
بعد الانتهاء من هذا المختبر، لا تنسَ حذف مجموعة AlloyDB ونسختها.
يجب أن يؤدي ذلك إلى تنظيف المجموعة بالإضافة إلى مثيلاتها.
8. تهانينا
لقد أنشأت بنجاح تطبيق بحث قابل للتوسيع في "قاعدة المعرفة". بدلاً من إدارة مسار معقّد لاستخراج البيانات وتحويلها وتحميلها باستخدام نصوص برمجية وحلقات Python لإنشاء عمليات تضمين متّجهات، استخدمت AlloyDB AI للتعامل مع إنشاء عمليات التضمين بشكلٍ أصلي داخل قاعدة البيانات باستخدام أمر SQL واحد.
المواضيع التي تناولناها
- تخلّصنا من "حلقة التكرار في Python" لمعالجة البيانات.
- لقد أنشأنا 50,000 متّجه باستخدام أمر SQL واحد.
- أتممنا عملية إنشاء المتجهات المستقبلية باستخدام المشغّلات.
- أجرينا عملية "بحث مختلط".
الخطوات التالية
- جرِّب ذلك باستخدام مجموعة البيانات الخاصة بك.
- اطّلِع على مستندات AlloyDB AI.
- يمكنك الاطّلاع على الموقع الإلكتروني Code Vipassana لمعرفة المزيد من ورش العمل.