Plug-in Vertex AI

Il plug-in Vertex AI fornisce interfacce per diversi servizi di IA:

• Modelli di IA generativa di Google:
  • Generazione di testo Gemini
  • Generazione di immagini con Imagen2 e Imagen3
  • Generazione di incorporamenti di testo
• Un sottoinsieme di metriche di valutazione tramite l'API Rapid Evaluation di Vertex AI:
  • BLEU
  • ROUGE
  • Fluenza
  • Sicurezza
  • Attendibilità
  • Qualità del riassunto
  • Utilità del riepilogo
  • Preferenze di lettura per il riepilogo
• Ricerca vettoriale

Installazione

npm i --save @genkit-ai/vertexai

Se vuoi eseguire localmente i flussi che utilizzano questo plug-in, devi installare anche lo strumento Google Cloud CLI.

Configurazione

Per utilizzare questo plug-in, specificalo quando inizili Genkit:

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

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

Il plug-in richiede di specificare l'ID progetto Google Cloud, la regione a cui vuoi inviare richieste all'API Vertex e le credenziali del progetto Google Cloud.

• Puoi specificare l'ID progetto Google Cloud impostando projectId nella configurazione vertexAI() o impostando la variabile di ambiente GCLOUD_PROJECT. Se esegui il flusso da un ambiente Google Cloud (Cloud Functions, Cloud Run e così via), GCLOUD_PROJECT viene impostato automaticamente sull'ID progetto dell'ambiente.
• Puoi specificare la posizione dell'API impostando location nella configurazione vertexAI() o la variabile di ambiente GCLOUD_LOCATION.

• Per fornire le credenziali API, devi configurare le credenziali predefinite dell'applicazione Google Cloud.

  1. Per specificare le credenziali:

     • Se esegui il flusso da un ambiente Google Cloud (Cloud Functions, Cloud Run e così via), questo valore viene impostato automaticamente.

     • Nel tuo ambiente di sviluppo locale, esegui:

       gcloud auth application-default login

     • Per altri ambienti, consulta la documentazione relativa alle credenziali predefinite dell'applicazione.

  2. Inoltre, assicurati che all'account sia stato concesso il ruolo IAM Vertex AI User (roles/aiplatform.user). Consulta la documentazione sul controllo dell'accesso di Vertex AI.

Utilizzo

Modelli di AI generativa

Questo plug-in esporta in modo statico i riferimenti ai modelli di AI generativa supportati:

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

Puoi utilizzare questi riferimenti per specificare il modello utilizzato da 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?',
});

Questo plug-in supporta anche la verifica delle risposte di Gemini utilizzando la Ricerca Google o i tuoi dati.

Importante: Vertex AI addebita una tariffa per le richieste di grounding oltre al costo di invio delle richieste LLM. Prima di utilizzare questa funzionalità, consulta la pagina Prezzi di Vertex AI e assicurati di comprendere i prezzi delle richieste di fondazione.

Esempio:

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,
    }
  }
})

Questo plug-in esporta anche in modo statico un riferimento al modello di embedding del testo di Gecko:

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

Puoi utilizzare questo riferimento per specificare quale inserzionista utilizza un indicizzatore o un retriever. Ad esempio, se utilizzi Chroma DB:

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

In alternativa, puoi generare direttamente un'incorporazione:

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

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

Il modello Imagen3 consente di generare immagini dal prompt dell'utente:

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();

e persino la modifica avanzata delle immagini esistenti:

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();

Per opzioni più dettagliate, consulta la documentazione del modello Imagen.

Anthropic Claude 3 su Model Garden di Vertex AI

Se hai accesso ai modelli Claude 3 (haiku, sonnet o opus) in Vertex AI Model Garden, puoi utilizzarli con Genkit.

Di seguito è riportata una configurazione di esempio per attivare i modelli di 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],
    }),
  ],
});

Dopodiché utilizzali come modelli regolari:

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

Llama 3.1 405b su Model Garden di Vertex AI

Innanzitutto, devi abilitare il servizio API Llama 3.1 in Model Garden di Vertex AI.

Ecco una configurazione di esempio per Llama 3.1 405b nel plug-in Vertex AI:

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

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

Poi utilizzali come modelli regolari:

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

Modelli Mistral in Model Garden di Vertex AI

Se hai accesso ai modelli Mistral (Mistral Large, Mistral Nemo o Codestral) in Model Garden di Vertex AI, puoi utilizzarli con Genkit.

Di seguito è riportata una configurazione di esempio per attivare i modelli di 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],
    }),
  ],
});

Dopodiché utilizzali come modelli regolari:

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
  }
});

I modelli supportano: - mistralLarge: il modello Mistral Large più recente con funzionalità di chiamata di funzioni - mistralNemo: ottimizzato per efficienza e velocità - codestral: specializzato per attività di generazione di codice

Ogni modello supporta le risposte in streaming e le chiamate di funzione:

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);
}

Valutatori

Per utilizzare gli valutatori di Vertex AI Rapid Evaluation, aggiungi un blocco evaluation alla configurazione del plug-in 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',
          },
        },
      ],
    }),
  ],
});

La configurazione riportata sopra aggiunge valutatori per le metriche Safety e ROUGE. L'esempio mostra due approcci: la metrica Safety utilizza la specifica predefinita, mentre la metrica ROUGE fornisce una specifica personalizzata che imposta il tipo di rogue su rougeLsum.

Entrambi gli valutatori possono essere eseguiti utilizzando il comando genkit eval:run con un set di dati compatibile, ovvero un set di dati con i campi output e reference. Il valutatore Safety può essere eseguito anche utilizzando il comando genkit eval:flow -e vertexai/safety, poiché richiede solo un output.

Indicizzatori e retriever

Il plug-in Genkit Vertex AI include implementazioni di indicizzatori e retriever supportate dal servizio Vertex AI Vector Search.

(Consulta la pagina Retrieval Augmented Generation per scoprire come vengono utilizzati gli indicizzatori e i retriever in un'implementazione RAG).

Il servizio Vertex AI Vector Search è un indice di documenti che funziona insieme al tuo datastore preferito: il datastore contiene i contenuti dei documenti e l'indice Vertex AI Vector Search contiene, per ogni documento, il relativo embedding vettoriale e un riferimento al documento nel datastore. Dopo che i documenti sono stati indicizzati dal servizio Vertex AI Vector Search, possono rispondere alle query di ricerca, producendo elenchi di indici nel tuo repository di documenti.

Le implementazioni dell'indice e del recupero fornite dal plug-in Vertex AI utilizzano Cloud Firestore o BigQuery come repository di documenti. Il plug-in include anche interfacce che puoi implementare per supportare altri repository di documenti.

Importante: i prezzi di Ricerca vettoriale sono costituiti da un addebito per ogni gigabyte di dati importati e da un addebito orario per le VM che ospitano gli indici di cui è stato eseguito il deployment. Consulta la pagina Prezzi di Vertex AI. Questa opzione è probabilmente la più conveniente quando gestisci volumi elevati di traffico. Prima di utilizzarlo, assicurati di comprendere le implicazioni in termini di fatturazione che il servizio avrà sul tuo progetto.

Per utilizzare Vertex AI Vector Search:

1. Scegli un modello di incorporamento. Questo modello è responsabile della creazione di incorporamenti di vettori dal testo. Gli utenti avanzati potrebbero utilizzare un modello di embedding ottimizzato per i loro set di dati specifici, ma per la maggior parte degli utenti il modello text-embedding-004 di Vertex AI è una buona scelta per il testo in inglese e il modello text-multilingual-embedding-002 è adatto per il testo multilingue.

2. Nella sezione Ricerca di vettori della console Google Cloud, crea un nuovo indice. Le impostazioni più importanti sono:

   • Dimensioni:specifica la dimensionalità dei vettori prodotti dal modello di embedding scelto. I modelli text-embedding-004 e text-multilingual-embedding-002 producono vettori di 768 dimensioni.
   • Metodo di aggiornamento: seleziona Aggiornamenti in streaming.

   Dopo aver creato l'indice, eseguine il deployment in un endpoint standard (pubblico).

3. Ottieni un indicizzatore e un retriever di documenti per l'archivio di documenti che vuoi utilizzare:

   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);
   

   Altro

   Per supportare altri store di documenti, puoi fornire le tue implementazioni di DocumentRetriever e DocumentIndexer:

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

   Per un esempio, consulta Esempio di recupero e indicizzazione del plug-in Vertex AI con file locale.

4. Aggiungi un blocco vectorSearchOptions alla configurazione del plug-in 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,
           },
         ],
       }),
     ],
   });
   

   Fornisci l'evidenziatore scelto nel primo passaggio e l'indice e il recupero dei documenti che hai creato nel passaggio precedente.

   Per configurare il plug-in in modo che utilizzi l'indice di ricerca vettoriale creato in precedenza, devi fornire diversi valori, che puoi trovare nella sezione Ricerca vettoriale della console Google Cloud:

   • indexId: elencato nella scheda Indici
   • indexEndpointId: elencato nella scheda Endpoint indice
   • deployedIndexId e publicDomainName: elencati nella pagina "Informazioni sull'indice di cui è stato eseguito il deployment", che puoi aprire facendo clic sul nome dell'indice di cui è stato eseguito il deployment in una delle schede sopra indicate

5. Ora che è tutto configurato, puoi utilizzare l'indice e il retriever nella tua applicazione 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,
   });
   

Consulta gli esempi di codice per:

• Vertex Vector Search + BigQuery
• Vertex Vector Search + Firestore
• Vertex Vector Search + un DB personalizzato

Memorizzazione nella cache del contesto

Il plug-in Genkit di Vertex AI supporta la memorizzazione nella cache del contesto, che consente ai modelli di riutilizzare i contenuti memorizzati nella cache in precedenza per ottimizzare l'utilizzo dei token quando si tratta di grandi quantità di contenuti. Questa funzionalità è particolarmente utile per i flussi di conversazione o gli scenari in cui il modello fa riferimento a una grande quantità di contenuti in modo coerente in più richieste.

Come utilizzare la memorizzazione nella cache del contesto

Per attivare la memorizzazione nella cache del contesto, assicurati che il modello la supporti. Ad esempio, gemini15Flash e gemini15Pro sono modelli che supportano la memorizzazione nella cache del contesto e dovrai specificare il numero di versione 001.

Puoi definire un meccanismo di memorizzazione nella cache nella tua applicazione nel seguente modo:

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.',
});

In questa configurazione: - messages: consente di trasmettere la cronologia della conversazione. - metadata.cache.ttlSeconds: specifica il TTL (time-to-live) per la memorizzazione nella cache di una risposta specifica.

Esempio: sfruttare i testi di grandi dimensioni con il contesto

Per le applicazioni che fanno riferimento a documenti lunghi, come Guerra e pace o Il Signore degli Anelli, puoi strutturare le query per riutilizzare i contesti memorizzati nella cache:

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.',
});

Vantaggi della memorizzazione nella cache del contesto

1. Miglioramento delle prestazioni: riduce la necessità di elaborare ripetutamente input di grandi dimensioni.
2. Efficienza dei costi: riduce l'utilizzo dell'API per i dati ridondanti, ottimizzando il consumo di token.
3. Latenza migliore: accelera i tempi di risposta per le query ripetute o correlate.

Modelli supportati per la memorizzazione nella cache del contesto

Solo modelli specifici, come gemini15Flash e gemini15Pro, supportano la memorizzazione nella cache del contesto e al momento solo per i numeri di versione 001. Se viene utilizzato un modello non supportato, verrà generato un errore che indica che la memorizzazione nella cache non può essere applicata.

Per approfondire

Scopri di più sulla memorizzazione nella cache del contesto su Vertex AI nella relativa documentazione.