إجراء بحث عن تشابه المتّجه باستخدام 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 APIs

الإعداد

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

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

التكامل مع PostgreSQL المحلي

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

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

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

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

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

التكامل مع IDX

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

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

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 APIs من Vertex AI داخليًا. يمكن استخدام قيمة الخادم _embed في كلٍّ من عمليات التعديل والاستعلامات.

عمليات التعديل

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

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

mutation createMovie($title: String!, $description: String!) {
  movie_insert(data: {
    title: $title,
    description: $description,
    descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $description}
  })
}

في بعض الحالات، قد تريد تعديل وصف الفيلم والتضمين.

mutation updateDescription($id: String!, $description: String!) {
  movie_update(id: $id, data: {
    description: $description,
    descriptionEmbedding_embed: {model: "textembedding-gecko@003", 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 APIs من Vertex AI، وفي هذه الحالة لإنشاء تضمينات لسلسلة البحث المستخدَمة للمقارنة مع تضمينات وصف الفيلم.

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

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "textembedding-gecko@003", 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: "textembedding-gecko@003", 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: "textembedding-gecko@003", 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 يتيح لك أيضًا استخدام التضمينات مباشرةً كـ Vectors بدلاً من استخدام قيمة الخادم _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 CLI الخطوات اللازمة لتفعيل إنشاء التضمينات المستندة إلى Vertex AI على مثيل Cloud SQL.

firebase deploy --only dataconnect

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

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

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

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

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

استخدِم مَعلمة `size` في توجيه @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 إلى إنشاء التضمينات وتخزينها باستخدام واجهات برمجة التطبيقات Embedding APIs من Vertex AI. يمكن استخدام قيمة الخادم هذه في كلٍّ من الاستعلامات وعمليات التعديل.

مَعلمات البحث عن التشابه

method: COSINE|INNER_PRODUCT|L2

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

within: float

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

where: FDC filter condition

الاطّلاع على دليل المخططات والاستعلامات وعمليات التعديل

limit: int

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