הפלאגין של Vertex AI

הפלאגין של Vertex AI מספק ממשקים לכמה שירותי 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 מוגדר באופן אוטומטי למזהה הפרויקט של הסביבה.
  • אפשר לציין את מיקום ה-API על ידי הגדרת location בתצורה של vertexAI() או על ידי הגדרת משתנה הסביבה GCLOUD_LOCATION.
  • כדי לספק פרטי כניסה ל-API, צריך להגדיר את Application Default Credentials של Google Cloud.

    1. כדי לציין את פרטי הכניסה:

      • אם אתם מריצים את התהליך מסביבת Google Cloud (Cloud Functions,‏ Cloud Run וכו'), ההגדרה הזו מוגדרת באופן אוטומטי.
      • בסביבת הפיתוח המקומית, מריצים את הפקודה הבאה:

        gcloud auth application-default login
      • בסביבות אחרות, אפשר לעיין במסמכי העזרה של Application Default Credentials.

    2. בנוסף, חשוב לוודא שהחשבון קיבל את התפקיד Vertex AI User IAM (roles/aiplatform.user). אפשר לעיין במסמכים בנושא בקרת גישה ב-Vertex AI.

שימוש

מודלים של 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) ב-Vertex AI Model Garden, תוכלו להשתמש בהם עם 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 API Service ב-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',
});

מעריכים

כדי להשתמש במודלים להערכה של Vertex AI Rapid Evaluation, מוסיפים בלוק 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 מספק מפרט מותאם אישית שמגדיר את סוג ה-Rouge כ-rougeLsum.

אפשר להריץ את שני המודלים באמצעות הפקודה genkit eval:run עם מערך נתונים תואם: כלומר, מערך נתונים עם השדות output ו-reference. אפשר להריץ את הבודק Safety גם באמצעות הפקודה genkit eval:flow -e vertexai/safety, כי הוא דורש רק output.

הוספה לאינדקס ואחזור נתונים

הפלאגין של Genkit ל-Vertex AI כולל הטמעות של מפתחות אינדקס ומאגרי אחזור שמגובים על ידי שירות Vertex AI Vector Search.

(במאמר יצירה עם שיפור אחזור מוסבר איך משתמשים במאגרי אינדקס ובמאגרי אחזור בהטמעה של RAG).

שירות Vertex AI Vector Search הוא אינדקס מסמכים שפועל לצד מאגר המסמכים שבחרתם: מאגר המסמכים מכיל את תוכן המסמכים, ואינדקס Vertex AI Vector Search מכיל, לכל מסמך, את הטמעת הווקטור שלו והפניה למסמך במאגר המסמכים. אחרי שהמסמכים יתווספו לאינדקס על ידי שירות Vertex AI Vector Search, הוא יוכל להגיב לשאילתות חיפוש וליצור רשימות של אינדקסים במאגר המסמכים.

הטמעות המאגר והאחזור שסופקו על ידי הפלאגין של Vertex AI משתמשות ב-Cloud Firestore או ב-BigQuery בתור מאגר המסמכים. הפלאגין כולל גם ממשקים שאפשר להטמיע כדי לתמוך במאגרי מסמכים אחרים.

כדי להשתמש ב-Vertex AI Vector Search:

  1. בוחרים מודל הטמעה. המודל הזה אחראי ליצירת הטמעות וקטוריות מטקסט. משתמשים מתקדמים יכולים להשתמש במודל הטמעה (embedding) שמותאם לקבוצות הנתונים הספציפיות שלהם, אבל לרוב המשתמשים, המודל text-embedding-004 של Vertex AI הוא בחירה טובה לטקסט באנגלית, והמודל text-multilingual-embedding-002 הוא בחירה טובה לטקסט בכמה שפות.
  2. יוצרים אינדקס חדש בקטע Vector Search במסוף 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,
            },
          ],
        }),
      ],
    });
    

    מציינים את הכלי להטמעה שבחרתם בשלב הראשון ואת הכלי להוספה לאינדקס ואת הכלי לאחזור מסמכים שיצרתם בשלב הקודם.

    כדי להגדיר את הפלאגין כך שישתמש באינדקס החיפוש של Vector שיצרתם מקודם, צריך לספק כמה ערכים. אפשר למצוא אותם בקטע Vector Search במסוף Google Cloud:

    • indexId: מופיע בכרטיסייה Indexes
    • 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,
    });
    

דוגמאות הקוד ל: