المكوّن الإضافي Vertex AI

يقدّم المكوّن الإضافي Vertex AI واجهات لعدّة خدمات ذكاء اصطناعي:

تثبيت

npm i --save @genkit-ai/vertexai

إذا كنت تريد تشغيل عمليات سير العمل التي تستخدِم هذا المكوّن الإضافي على الجهاز، يجب أيضًا تثبيت أداة Google Cloud CLI.

الإعداد

لاستخدام هذا المكوّن الإضافي، حدِّده عند إعداد Genkit:

import { genkit } from 'genkit';
import { vertexAI } from '@genkit-ai/vertexai';

const ai = genkit({
  plugins: [
    vertexAI({ location: 'us-central1' }),
  ],
});

يطلب منك المكوّن الإضافي تحديد معرّف مشروعك على Google Cloud والمنطقة التي تريد إرسال طلبات Vertex API إليها وبيانات اعتماد مشروعك على Google Cloud.

  • يمكنك تحديد رقم تعريف مشروعك على Google Cloud إما عن طريق ضبط projectId في إعدادات vertexAI() أو عن طريق ضبط متغيّر البيئة GCLOUD_PROJECT. إذا كنت تُشغّل عملية المعالجة من بيئة Google Cloud (Cloud Functions وCloud Run وما إلى ذلك)، يتم ضبط GCLOUD_PROJECT تلقائيًا على معرّف المشروع للبيئة.
  • يمكنك تحديد موقع واجهة برمجة التطبيقات إما عن طريق ضبط location في إعدادات vertexAI() أو عن طريق ضبط متغيّر البيئة GCLOUD_LOCATION.

  • لتقديم بيانات اعتماد واجهة برمجة التطبيقات، عليك إعداد "بيانات الاعتماد التلقائية لتطبيق Google Cloud".

    1. لتحديد بيانات الاعتماد، يُرجى اتّباع الخطوات التالية:

      • إذا كنت تشغّل عملية المعالجة من بيئة Google Cloud (Cloud Functions وCloud Run وما إلى ذلك)، يتم ضبط هذا الإعداد تلقائيًا.

      • في بيئة التطوير المحلية، يمكنك إجراء ذلك من خلال تنفيذ:

        gcloud auth application-default login

      • بالنسبة إلى البيئات الأخرى، يُرجى الاطّلاع على مستندات بيانات الاعتماد التلقائية للتطبيق.

    2. بالإضافة إلى ذلك، تأكَّد من منح الحساب دور "مستخدم Vertex AI" في "إدارة الهوية وإمكانية الوصول" (roles/aiplatform.user). اطّلِع على مستندات التحكّم في الوصول في Vertex AI.

الاستخدام

نماذج الذكاء الاصطناعي التوليدي

يصدِّر هذا المكوِّن الإضافي بشكلٍ ثابت إشارات إلى نماذج الذكاء الاصطناعي التوليدي المتوافقة:

import { gemini15Flash, gemini15Pro, imagen3 } from '@genkit-ai/vertexai';

يمكنك استخدام هذه المراجع لتحديد النموذج الذي يستخدمه ai.generate():

const ai = genkit({
  plugins: [vertexAI({ location: 'us-central1' })],
});

const llmResponse = await ai.generate({
  model: gemini15Flash,
  prompt: 'What should I do when I visit Melbourne?',
});

يتيح هذا المكوّن الإضافي أيضًا تحديد مصدر ردود Gemini النصية باستخدام بحث Google أو بياناتك الخاصة.

مثال:

const ai = genkit({
  plugins: [vertexAI({ location: 'us-central1' })],
});

await ai.generate({
  model: gemini15Flash,
  prompt: '...',
  config: {
    googleSearchRetrieval: {
      disableAttribution: true,
    }
    vertexRetrieval: {
      datastore: {
        projectId: 'your-cloud-project',
        location: 'us-central1',
        collection: 'your-collection',
      },
      disableAttribution: true,
    }
  }
})

يُصدِّر هذا المكوّن الإضافي أيضًا مرجعًا إلى نموذج تضمين النص في Gecko بشكل ثابت:

import { textEmbedding004 } from '@genkit-ai/vertexai';

يمكنك استخدام هذا المرجع لتحديد أداة التضمين التي يستخدمها مؤشر أو أداة استرجاع. على سبيل المثال، إذا كنت تستخدم Chroma DB:

const ai = genkit({
  plugins: [
    chroma([
      {
        embedder: textEmbedding004,
        collectionName: 'my-collection',
      },
    ]),
  ],
});

أو يمكنك إنشاء رمز إدراج مباشرةً:

const ai = genkit({
  plugins: [vertexAI({ location: 'us-central1' })],
});

const embedding = await ai.embed({
  embedder: textEmbedding004,
  content: 'How many widgets do you have in stock?',
});

يسمح نموذج Imagen3 بإنشاء صور من طلب المستخدم:

import { imagen3 } from '@genkit-ai/vertexai';

const ai = genkit({
  plugins: [vertexAI({ location: 'us-central1' })],
});

const response = await ai.generate({
  model: imagen3,
  output: { format: 'media' },
  prompt: 'a banana riding a bicycle',
});

return response.media();

ويمكنك أيضًا إجراء تعديلات متقدّمة على الصور الحالية:

const ai = genkit({
  plugins: [vertexAI({ location: 'us-central1' })],
});

const baseImg = fs.readFileSync('base.png', { encoding: 'base64' });
const maskImg = fs.readFileSync('mask.png', { encoding: 'base64' });

const response = await ai.generate({
  model: imagen3,
  output: { format: 'media' },
  prompt: [
    { media: { url: `data:image/png;base64,${baseImg}` }},
    {
      media: { url: `data:image/png;base64,${maskImg}` },
      metadata: { type: 'mask' },
    },
    { text: 'replace the background with foo bar baz' },
  ],
  config: {
    editConfig: {
      editMode: 'outpainting',
    },
  },
});

return response.media();

يُرجى الرجوع إلى مستندات نماذج Imagen للحصول على خيارات أكثر تفصيلاً.

Anthropic Claude 3 على Vertex AI Model Garden

إذا كان بإمكانك الوصول إلى نماذج Claude 3 (haiku أو sonnet أو opus) في Model Garden في Vertex AI، يمكنك استخدامها مع Genkit.

في ما يلي نموذج لإعداد تفعيل نماذج Vertex AI Model Garden:

import { genkit } from 'genkit';
import {
  claude3Haiku,
  claude3Sonnet,
  claude3Opus,
  vertexAIModelGarden,
} from '@genkit-ai/vertexai/modelgarden';

const ai = genkit({
  plugins: [
    vertexAIModelGarden({
      location: 'us-central1',
      models: [claude3Haiku, claude3Sonnet, claude3Opus],
    }),
  ],
});

بعد ذلك، استخدِم هذه النماذج كالمعتاد:

const llmResponse = await ai.generate({
  model: claude3Sonnet,
  prompt: 'What should I do when I visit Melbourne?',
});

Llama 3.1 405b على Vertex AI Model Garden

أولاً، عليك تفعيل خدمة واجهة برمجة التطبيقات Llama 3.1 في Vertex AI Model Garden.

في ما يلي نموذج لإعدادات Llama 3.1 405b في المكوّن الإضافي Vertex AI:

import { genkit } from 'genkit';
import { llama31, vertexAIModelGarden } from '@genkit-ai/vertexai/modelgarden';

const ai = genkit({
  plugins: [
    vertexAIModelGarden({
      location: 'us-central1',
      models: [llama31],
    }),
  ],
});

بعد ذلك، استخدِم هذه النماذج كالنماذج العادية:

const llmResponse = await ai.generate({
  model: llama31,
  prompt: 'Write a function that adds two numbers together',
});

نماذج Mistral على Model Garden في Vertex AI

إذا كان بإمكانك الوصول إلى نماذج Mistral (Mistral Large أو Mistral Nemo أو Codestral) في Vertex AI Model Garden، يمكنك استخدامها مع Genkit.

في ما يلي نموذج لإعداد تفعيل نماذج Vertex AI Model Garden:

import { genkit } from 'genkit';
import {
  mistralLarge,
  mistralNemo,
  codestral,
  vertexAIModelGarden,
} from '@genkit-ai/vertexai/modelgarden';

const ai = genkit({
  plugins: [
    vertexAIModelGarden({
      location: 'us-central1',
      models: [mistralLarge, mistralNemo, codestral],
    }),
  ],
});

بعد ذلك، استخدِم هذه النماذج كالمعتاد:

const llmResponse = await ai.generate({
  model: mistralLarge,
  prompt: 'Write a function that adds two numbers together',
  config: {
    version: 'mistral-large-2411', // Optional: specify model version
    temperature: 0.7,              // Optional: control randomness (0-1)
    maxOutputTokens: 1024,         // Optional: limit response length
    topP: 0.9,                     // Optional: nucleus sampling parameter
    stopSequences: ['###'],        // Optional: stop generation at sequences
  }
});

تتيح النماذج ما يلي: - mistralLarge: أحدث طراز كبير من Mistral مزوّد بإمكانات استدعاء الدوالّ - mistralNemo: محسّن للكفاءة والسرعة - codestral: مخصّص لمهام إنشاء الرموز البرمجية

يتيح كل نموذج بث الردود وطلب الدوالّ:

const response = await ai.generateStream({
  model: mistralLarge,
  prompt: 'What should I cook tonight?',
  tools: ['recipe-finder'],
  config: {
    version: 'mistral-large-2411',
    temperature: 1,
  },
});

for await (const chunk of response.stream) {
  console.log(chunk.text);
}

المقيّمون

لاستخدام الأدوات التقييمية من ميزة "التقييم السريع" في Vertex AI، أضِف وحدة evaluation إلى إعدادات المكوّن الإضافي vertexAI.

import { genkit } from 'genkit';
import {
  vertexAIEvaluation,
  VertexAIEvaluationMetricType,
} from '@genkit-ai/vertexai/evaluation';

const ai = genkit({
  plugins: [
    vertexAIEvaluation({
      location: 'us-central1',
      metrics: [
        VertexAIEvaluationMetricType.SAFETY,
        {
          type: VertexAIEvaluationMetricType.ROUGE,
          metricSpec: {
            rougeType: 'rougeLsum',
          },
        },
      ],
    }),
  ],
});

تُضيف الإعدادات أعلاه جهات تقييم لمقياسَي Safety وROUGE. يعرض المثال طريقتَين: يستخدم مقياس Safety المواصفة التلقائية، في حين يقدّم مقياس ROUGE مواصفة مخصّصة تضبط نوع أحمر الشفاه على rougeLsum.

يمكن تشغيل كلا المقيميَين باستخدام الأمر genkit eval:run مع مجموعة بيانات متوافقة، أي مجموعة بيانات تحتوي على حقلَي output وreference. يمكن أيضًا تشغيل أداة تقييم Safety باستخدام الأمر genkit eval:flow -e vertexai/safety لأنّها لا تتطلّب سوى output.

برامج الفهرسة والاسترجاع

يتضمّن المكوّن الإضافي Genkit Vertex AI عمليات تنفيذ الفهرسة والاسترجاع التي تستند إلى خدمة Vertex AI Vector Search.

(اطّلِع على صفحة الإنشاء المعزّز بالاسترداد لمعرفة كيفية استخدام الفهرسة وأدوات الاسترداد في عملية تنفيذ ميزة "الإنشاء المعزّز بالاسترداد").

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

إنّ عمليات تنفيذ أداة الفهرسة وأداة الاسترجاع المقدَّمة من خلال المكوّن الإضافي Vertex AI تستخدِم إما Cloud Firestore أو BigQuery كمستودع للمستندات. يتضمّن المكوّن الإضافي أيضًا واجهات يمكنك تنفيذها لتتوافق مع أنظمة تخزين المستندات الأخرى.

لاستخدام ميزة "البحث عن المتّجهات" في Vertex AI:

  1. اختَر نموذجًا للإدراج. هذا النموذج مسؤول عن إنشاء نماذج مصغّرة للنص. قد يستخدم المستخدمون المتقدّمون نموذجًا مضمّنًا محسّنًا لمجموعات البيانات الخاصة بهم، ولكن بالنسبة إلى معظم المستخدمين، يُعدّ نموذج text-embedding-004 في Vertex AI خيارًا جيدًا للنصوص الإنجليزية، ويُعدّ نموذج text-multilingual-embedding-002 خيارًا جيدًا للنصوص المتعددة اللغات.

  2. في قسم بحث المتجهات في وحدة تحكّم Google Cloud، أنشئ فهرسًا جديدًا. في ما يلي أهم الإعدادات:

    • السمات: حدِّد أبعاد المتجهات التي ينتج عنها نموذج التضمين الذي اخترته. تُنشئ نماذج text-embedding-004 وtext-multilingual-embedding-002 خطوطًا متّجهة تضم 768 سمة.
    • طريقة التحديث: اختَر تحديثات البث.

    بعد إنشاء الفهرس، يمكنك نشره على نقطة نهاية عادية (عامة).

  3. احصل على أداة فهرسة واسترجاع للمستندات في مستودع المستندات الذي تريد استخدامه:

    Cloud Firestore

    import { getFirestoreDocumentIndexer, getFirestoreDocumentRetriever } from '@genkit-ai/vertexai/vectorsearch';

import { initializeApp } from 'firebase-admin/app';
import { getFirestore } from 'firebase-admin/firestore';

initializeApp({ projectId: PROJECT_ID });
const db = getFirestore();

const firestoreDocumentRetriever = getFirestoreDocumentRetriever(db, FIRESTORE_COLLECTION);
const firestoreDocumentIndexer = getFirestoreDocumentIndexer(db, FIRESTORE_COLLECTION);

    BigQuery

    import { getBigQueryDocumentIndexer, getBigQueryDocumentRetriever } from '@genkit-ai/vertexai/vectorsearch';
import { BigQuery } from '@google-cloud/bigquery';

const bq = new BigQuery({ projectId: PROJECT_ID });

const bigQueryDocumentRetriever = getBigQueryDocumentRetriever(bq, BIGQUERY_TABLE, BIGQUERY_DATASET);
const bigQueryDocumentIndexer = getBigQueryDocumentIndexer(bq, BIGQUERY_TABLE, BIGQUERY_DATASET);

    غير ذلك

    لتفعيل ميزة استخدام متاجر مستندات أخرى، يمكنك تقديم آليات تنفيذك الخاصة لكل من DocumentRetriever وDocumentIndexer:

    const myDocumentRetriever = async (neighbors) => {
  // Return the documents referenced by `neighbors`.
  // ...
}
const myDocumentIndexer = async (documents) => {
  // Add `documents` to storage.
  // ...
}

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

  4. أضِف وحدة vectorSearchOptions إلى إعدادات المكوّن الإضافي vertexAI:

    import { genkit } from 'genkit';
import { textEmbedding004 } from '@genkit-ai/vertexai';
import { vertexAIVectorSearch } from '@genkit-ai/vertexai/vectorsearch';

const ai = genkit({
  plugins: [
    vertexAIVectorSearch({
      projectId: PROJECT_ID,
      location: LOCATION,
      vectorSearchOptions: [
        {
          indexId: VECTOR_SEARCH_INDEX_ID,
          indexEndpointId: VECTOR_SEARCH_INDEX_ENDPOINT_ID,
          deployedIndexId: VECTOR_SEARCH_DEPLOYED_INDEX_ID,
          publicDomainName: VECTOR_SEARCH_PUBLIC_DOMAIN_NAME,
          documentRetriever: firestoreDocumentRetriever,
          documentIndexer: firestoreDocumentIndexer,
          embedder: textEmbedding004,
        },
      ],
    }),
  ],
});

    قدِّم أداة التضمين التي اخترتها في الخطوة الأولى وأداة فهرسة المستندات واستردادها التي أنشأتها في الخطوة السابقة.

    لضبط المكوّن الإضافي لاستخدام فهرس "البحث بالاستناد إلى الرسومات" الذي أنشأته سابقًا، عليك تقديم عدة قيم يمكنك العثور عليها في قسم "البحث بالاستناد إلى الرسومات" في وحدة تحكّم Google Cloud:

    • indexId: مُدرَجة في علامة التبويب المؤشرات
    • indexEndpointId: مُدرَجة في علامة التبويب نقاط نهاية الفهرسة
    • deployedIndexId وpublicDomainName: مُدرَجَان في صفحة "معلومات الفهرس المنشور"، والتي يمكنك فتحها بالنقر على اسم الفهرس المنشور في أيّ من علامتَي التبويب المذكورتَين سابقًا

  5. بعد ضبط كل الإعدادات، يمكنك استخدام أداة الفهرسة والاسترجاع في تطبيق Genkit:

    import {
  vertexAiIndexerRef,
  vertexAiRetrieverRef,
} from '@genkit-ai/vertexai/vectorsearch';

// ... inside your flow function:

await ai.index({
  indexer: vertexAiIndexerRef({
    indexId: VECTOR_SEARCH_INDEX_ID,
  }),
  documents,
});

const res = await ai.retrieve({
  retriever: vertexAiRetrieverRef({
    indexId: VECTOR_SEARCH_INDEX_ID,
  }),
  query: queryDocument,
});

اطّلِع على نماذج الرموز البرمجية لما يلي:

تخزين السياق في ذاكرة التخزين المؤقت

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

كيفية استخدام ميزة "تخزين السياق"

لتفعيل ميزة "تخزين السياق في ذاكرة التخزين المؤقت"، تأكَّد من أنّ النموذج يتيح ذلك. على سبيل المثال، gemini15Flash وgemini15Pro هما طرازان يتيحان ميزة "تخزين السياق في ذاكرة التخزين المؤقت"، وعليك تحديد رقم الإصدار 001.

يمكنك تحديد آلية تخزين مؤقت في تطبيقك على النحو التالي:

const ai = genkit({
  plugins: [googleAI()],
});

const llmResponse = await ai.generate({
  messages: [
    {
      role: 'user',
      content: [{ text: 'Here is the relevant text from War and Peace.' }],
    },
    {
      role: 'model',
      content: [
        {
          text: 'Based on War and Peace, here is some analysis of Pierre Bezukhov’s character.',
        },
      ],
      metadata: {
        cache: {
          ttlSeconds: 300, // Cache this message for 5 minutes
        },
      },
    },
  ],
  model: gemini15Flash,
  prompt: 'Describe Pierre’s transformation throughout the novel.',
});

في هذا الإعداد: - messages: يتيح لك تمرير سجلّ المحادثات. ‫- metadata.cache.ttlSeconds: لتحديد مدة البقاء (TTL) لتخزين استجابة معيّنة في ذاكرة التخزين المؤقت.

مثال: الاستفادة من النصوص الكبيرة مع السياق

بالنسبة إلى التطبيقات التي تشير إلى مستندات طويلة، مثل War and Peace أو Lord of the Rings، يمكنك تنظيم طلبات البحث لإعادة استخدام السياقات المخزّنة مؤقتًا:


const textContent = await fs.readFile('path/to/war_and_peace.txt', 'utf-8');

const llmResponse = await ai.generate({
  messages: [
    {
      role: 'user',
      content: [{ text: textContent }], // Include the large text as context
    },
    {
      role: 'model',
      content: [
        {
          text: 'This analysis is based on the provided text from War and Peace.',
        },
      ],
      metadata: {
        cache: {
          ttlSeconds: 300, // Cache the response to avoid reloading the full text
        },
      },
    },
  ],
  model: gemini15Flash,
  prompt: 'Analyze the relationship between Pierre and Natasha.',
});

مزايا ميزة "تخزين السياق"

  1. الأداء المحسَّن: يقلل من الحاجة إلى المعالجة المتكرّرة للبيانات الكبيرة.
  2. كفاءة التكلفة: يقللّ هذا الخيار من استخدام واجهة برمجة التطبيقات للبيانات المكرّرة، ما يؤدي إلى تحسين استهلاك الرموز المميّزة.
  3. وقت استجابة أفضل: تسريع أوقات الاستجابة لطلبات البحث المتكررة أو ذات الصلة

النماذج المتوافقة لتخزين السياق مؤقتًا

لا تتوفّر ميزة "تخزين السياق في ذاكرة التخزين المؤقت" إلا في طُرز محدّدة، مثل gemini15Flash وgemini15Pro، ولا تتوفّر حاليًا إلا في الإصدار 001. في حال استخدام نموذج غير متوافق، سيتم عرض خطأ يشير إلى أنّه لا يمكن تطبيق ميزة التخزين المؤقت.

مراجع إضافية

يمكنك الاطّلاع على مزيد من المعلومات حول ميزة "تخزين السياق في ذاكرة التخزين المؤقت" على Vertex AI في المستندات.