Plug-in Vertex AI

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

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 avvii 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.

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.

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

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 errore 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 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.

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 vettoriale 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 recupero nell'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: