إجراء بحث عن تشابه المتّجه باستخدام Vertex AI

مرحبًا بك في ميزة البحث عن التشابهات في المتّجهات من Firebase SQL Connect، وهي ميزة من Firebase لتنفيذ البحث الدلالي تتكامل مع Google Vertex AI.

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

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

يمكنك الاعتماد على الدعم المضمّن في SQL Connect لإنشاء تضمينات متجهة تلقائيًا باستخدام Embeddings API من Vertex AI، أو استخدام واجهة برمجة التطبيقات هذه لإنشائها يدويًا.

المتطلبات الأساسية

• إعداد SQL Connect لمشروعك

• فعِّل واجهات Vertex AI API.

الإعداد

يمكنك الاختيار بين مسار التطوير المحلي (إذا كنت مطوّرًا لتطبيقات الويب أو Kotlin Android أو iOS) أو مسار IDX (لمطوّري تطبيقات الويب). يمكنك استخدام قاعدة بيانات محلية أو مشروع SQL Connect الخاص بالإنتاج وCloud SQL الخاص به لإنشاء مثيل PostgreSQL لأغراض التطوير.

تفترض هذه التعليمات أنّك أنشأت مشروعك SQL Connectباتّباع دليل البدء السريع.

الدمج مع PostgreSQL المحلي

1. إعداد مثيل PostgreSQL محلي

2. امنح نفسك دور مستخدم Vertex AI في "إدارة الهوية وإمكانية الوصول".

3. في بيئتك، عليك إعداد Google Cloud بيانات الاعتماد التلقائية للتطبيق.

4. في مثيل PostgreSQL المحلي، ثبِّت إضافة pgvector.

5. فعِّل الإضافة باستخدام CREATE EXTENSION vector وفقًا لتعليمات pgvector المستودع.

الدمج مع IDX

1. اضبط مساحة عمل IDX باستخدام نموذج SQL Connect.

2. امنح نفسك دور مستخدم Vertex AI في "إدارة الهوية وإمكانية الوصول".

3. فعِّل الإضافة باستخدام CREATE EXTENSION vector وفقًا لتعليمات pgvector المستودع.

تصميم المخطط

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

type Movie @table {
 id: ID! @col(name: "movie_id") @default(id: ID! @col(name: "movie_id") @default(expr: "uuidV4()")
 title: String!
 description: String
 descriptionEmbedding: Vector! @col(size:768)
 // ...
}

إنشاء عمليات تضمين واستردادها

توفّر SQL Connect دعمًا مدمجًا لعمليات تضمين المتجهات باستخدام قيمة الخادم _embed. يؤدي ذلك إلى توجيه SQL Connect لإنشاء تضمينات المتّجهات من خلال استدعاء واجهات Embedding API في Vertex AI داخليًا. يمكن استخدام قيمة الخادم في كل من عمليات التغيير والاستعلامات._embed

التغييرات

إنشاء تضمين وتخزينه من خلال SQL Connect

في تطبيق البحث المتّجهي، من المحتمل أن تحتاج إلى طلب إنشاء عمليات التضمين بمجرد إضافة سجلّات إلى قاعدة البيانات. في ما يلي createMovie تعديل يضيف سجل فيلم إلى جدول Movie ويمرّر أيضًا وصفًا للفيلم مع تضمين model محدّد.

mutation createMovie($title: String!, $description: String!) {
  movie_insert(data: {
    title: $title,
    description: $description,
    descriptionEmbedding_embed: {model: "text-embedding-005", text: $description}
  })
}

في بعض الحالات، قد تحتاج إلى تعديل وصف الفيلم وتضمينه.

mutation updateDescription($id: String!, $description: String!) {
  movie_update(id: $id, data: {
    description: $description,
    descriptionEmbedding_embed: {model: "text-embedding-005", text: $description}
  })
}

لاستدعاء عملية التعديل الأخيرة من أحد العملاء، اتّبِع الخطوات التالية:

import { updateMovieDescription } from 'lib/dataconnect-sdk/';

await updateMovieDescription({ id: movieId, description: description});

// Use the response

طلبات البحث

يمكنك جلب تضمينات المتّجهات باستخدام طلب بحث مثل ما يلي. يُرجى العِلم أنّ descriptionEmbedding الذي يعرضه طلب البحث هو مصفوفة من الأرقام العشرية، وهي عادةً غير قابلة للقراءة من قِبل البشر. وبالتالي، لا تتيح حِزم SDK التي تم إنشاؤها SQL Connectإرجاعها مباشرةً.

يمكنك استخدام تضمينات المتجهات التي تم إرجاعها لإجراء بحث عن التشابه، كما هو موضّح في القسم التالي.

query getMovieDescription($id: String!) @auth(level: PUBLIC) {
 movie(id: $id)
   id
   description
   descriptionEmbedding
}

إجراء بحث عن صور مشابهة

يمكننا الآن إجراء بحث عن التشابه.

بالنسبة إلى كل حقل Vector، تنشئ SQL Connect دالة GraphQL تنفّذ عملية البحث عن التشابه. اسم هذه الدالة التي تم إنشاؤها هو ${pluralType}_${vectorFieldName}_similarity. وهي تتوافق مع بعض المَعلمات كما هو موضّح في الأمثلة التالية وفي قائمة المراجع.

يمكنك تحديد دالة GraphQL تستدعي البحث عن التشابه. كما ذكرنا أعلاه، توجّه قيمة الخادم _embed SQL Connect إلى إنشاء تضمينات المتّجهات باستخدام واجهات Embedding API من Vertex AI، وفي هذه الحالة، لإنشاء تضمينات لعبارة البحث المستخدَمة للمقارنة مع تضمينات أوصاف الأفلام.

في هذا المثال، سيعرض البحث عن المحتوى المشابه ما يصل إلى 5 أفلام يكون وصفها الأقرب دلاليًا إلى طلب البحث المُدخَل. يتم ترتيب مجموعة النتائج تصاعديًا حسب المسافة، أي من الأقرب إلى الأبعد.

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "text-embedding-005", text: $query},
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
      }
  }

ضبط طلب البحث عن التشابه

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

للعثور على قيمة مناسبة لـ within، يمكننا إضافة _metadata.distance إلى الحقول المحدّدة لمعرفة مدى بُعد كل نتيجة عن متجه طلب البحث. استنادًا إلى قيم distance التي تم عرضها، يمكننا ضبط المَعلمة within، ولن يتم تضمين سوى النتائج التي تقل مسافتها عن قيمة within:

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "text-embedding-005", text: $query},
      within: 2,
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
        _metadata {
          distance
        }
      }
  }

يمكنك أيضًا تجربة دوال مسافة مختلفة من خلال ضبط المَعلمة method.

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "text-embedding-005", text: $query},
      within: .5,
      method: COSINE,
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
        _metadata {
          distance
        }
      }
  }

يُرجى العِلم أنّ الطرق المختلفة تعرض قيمًا مختلفة جدًا للمسافة: إذا كنت قد ضبطت within، عليك ضبط هذه القيمة مرة أخرى بعد تغيير method.

استدعاء طلب البحث عن التشابه

لإجراء بحث مشابه من رمز العميل، اتّبِع الخطوات التالية:

import { searchMovieDescriptionUsingL2similarity} from 'lib/dataconnect-sdk';

const response = await searchMovieDescriptionUsingL2similarity({ query });

// Use the response

استخدام عمليات تضمين مخصّصة

تتيح لك السمة SQL Connect أيضًا استخدام عمليات التضمين مباشرةً كـ Vector بدلاً من استخدام قيمة الخادم _embed لإنشائها.

تخزين تضمين مخصّص

باستخدام Vertex Embeddings API، حدِّد نموذجًا مطابقًا واطلب نتائج التضمين ذات البُعد الصحيح.

بعد ذلك، حوِّل مصفوفة الأرقام العشرية التي تم إرجاعها إلى Vector لتمريرها إلى عملية التعديل للتخزين.

mutation updateDescription($id: String!, $description: String!, $descriptionEmbedding: Vector!) {
  movie_update(id: $id, data: {
    // title, genre...
    description: $description,
    descriptionEmbedding: $descriptionEmbedding
  })
}

إجراء بحث عن التشابه باستخدام التضمينات المخصّصة

نفِّذ العملية نفسها لاسترداد التضمينات لعبارات البحث وتحويلها إلى Vectors.

بعد ذلك، استخدِم طلب البحث _similarity لتنفيذ كل عملية بحث.

query searchMovieDescriptionUsingL2Similarity($compare: Vector!, $within: Float, $excludesContent: String, $limit: Int) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare: $compare,
      method: L2,
      within: $within,
      where: {content: {ne: $excludesContent}}, limit: $limit)
      {
        id
        title
        description
      }
  }

النشر في الإصدار العلني

نشر المخطط والموصّل

الخطوة الأخيرة في عملية التكرار SQL Connect النموذجية هي نشر أصولك في مرحلة الإنتاج.

عند نشر مخططك الذي يحتوي على أنواع Vector إلى Cloud SQL باستخدام الأمر firebase deploy، تتّخذ واجهة سطر الأوامر Firebase الخطوات اللازمة لتفعيل إنشاء عمليات التضمين المستندة إلى Vertex AI على مثيل Cloud SQL.

firebase deploy --only dataconnect

إذا أردت تفعيل ميزة التضمين في مثيل Cloud SQL يدويًا أو واجهت خطأ في واجهة سطر الأوامر، اتّبِع هذه التعليمات.

بنية البحث عن المتّجهات

إضافات المخطط

يتوافق نوع بيانات SQL Connect مع النوع vector في PostgreSQL على النحو المحدّد في الإضافة pgvector. يتم تخزين النوع vector في pgvector كمصفوفة من أرقام الفاصلة العائمة ذات الدقة الفردية في PostgreSQL.Vector

في SQL Connect، يتم تمثيل النوع Vector كصفيفة من أرقام JSON. يتم تحويل المدخلات إلى مصفوفة من قيم float32. إذا تعذّر التحويل، سيتم عرض رسالة خطأ.

استخدِم مَعلمة الحجم في التوجيه @col لضبط أبعاد الرسومات المتجهة.

type Question @table {
    text: String!
    category: String!
    textEmbedding: Vector! @col(size: 768)
}

لا تتوفّر ميزة size إلا لأنواع Vector. تتطلّب عمليات Vector، مثل البحث عن التشابه، أن يكون لجميع Vector عدد الأبعاد نفسه.

directive @col(
  # … existing args
  """
  Defines a fixed column size for certain scalar types.

  - For Vector, size is required.
  - For all other types, size is currently unsupported and hence supplying it will result in a schema error.
  """
  size: Int
) on FIELD_DEFINITION

قيمة الخادم _embed للاستعلامات والتعديلات

_embed

توجّه قيمة الخادم هذه خدمة SQL Connect لإنشاء عمليات تضمين وتخزينها باستخدام واجهات برمجة التطبيقات الخاصة بعمليات التضمين في Vertex AI. يمكن استخدام قيمة الخادم هذه في كلّ من طلبات البحث وعمليات التغيير.

المَعلمات الخاصة بالبحث عن صور مشابهة

method: COSINE|INNER_PRODUCT|L2

دالة المسافة المستخدَمة للبحث عن الأماكن المجاورة القريبة الخوارزميات المتوافقة حاليًا هي مجموعة فرعية من خوارزميات البحث في pgvector.

within: float

قيد على المسافة التي يتم ضمنها إجراء البحث عن أقرب جار.

where: FDC filter condition

اطّلِع على دليل المخططات وطلبات البحث والتعديلات.

limit: int

عدد النتائج المطلوب عرضها.