Plug-in Vertex AI

Le plug-in Vertex AI fournit des interfaces avec plusieurs services d'IA:

Installation

npm i --save @genkit-ai/vertexai

Si vous souhaitez exécuter localement des flux qui utilisent ce plug-in, vous devez également installer l'outil Google Cloud CLI.

Configuration

Pour utiliser ce plug-in, spécifiez-le lorsque vous initialisez Genkit:

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

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

Le plug-in vous demande de spécifier l'ID de votre projet Google Cloud, la région à laquelle vous souhaitez envoyer des requêtes d'API Vertex et les identifiants de votre projet Google Cloud.

  • Vous pouvez spécifier votre ID de projet Google Cloud en définissant projectId dans la configuration vertexAI() ou en définissant la variable d'environnement GCLOUD_PROJECT. Si vous exécutez votre flux à partir d'un environnement Google Cloud (Cloud Functions, Cloud Run, etc.), GCLOUD_PROJECT est automatiquement défini sur l'ID de projet de l'environnement.
  • Vous pouvez spécifier l'emplacement de l'API en définissant location dans la configuration vertexAI() ou en définissant la variable d'environnement GCLOUD_LOCATION.

  • Pour fournir des identifiants d'API, vous devez configurer les identifiants par défaut de l'application Google Cloud.

    1. Pour spécifier vos identifiants:

      • Si vous exécutez votre flux à partir d'un environnement Google Cloud (Cloud Functions, Cloud Run, etc.), cette valeur est définie automatiquement.

      • Dans votre environnement de développement local, exécutez la commande suivante:

        gcloud auth application-default login

      • Pour les autres environnements, consultez la documentation sur les identifiants par défaut de l'application.

    2. Assurez-vous également que le compte dispose du rôle IAM Utilisateur Vertex AI (roles/aiplatform.user). Consultez la documentation sur le contrôle des accès dans Vertex AI.

Utilisation

Modèles d'IA générative

Ce plug-in exporte de manière statique les références à ses modèles d'IA générative compatibles:

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

Vous pouvez utiliser ces références pour spécifier le modèle utilisé par 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?',
});

Ce plug-in permet également d'ancrer les réponses textuelles de Gemini à l'aide de la recherche Google ou de vos propres données.

Exemple :

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

Ce plug-in exporte également de manière statique une référence au modèle d'embedding textuel Gecko:

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

Vous pouvez utiliser cette référence pour spécifier l'outil d'intégration utilisé par un indexeur ou un récupérateur. Par exemple, si vous utilisez Chroma DB:

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

Vous pouvez également générer une représentation vectorielle continue directement:

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

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

Le modèle Imagen3 permet de générer des images à partir d'une requête utilisateur:

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

et même de modifier des images existantes de manière avancée:

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

Pour en savoir plus, consultez la documentation du modèle Imagen.

Anthropic Claude 3 sur Model Garden Vertex AI

Si vous avez accès aux modèles Claude 3 (haiku, sonnet ou opus) dans Model Garden Vertex AI, vous pouvez les utiliser avec Genkit.

Voici un exemple de configuration pour activer les modèles Model Garden de Vertex AI:

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

Utilisez-les ensuite comme des modèles standards:

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

Llama 3.1 405b dans Vertex AI Model Garden

Vous devez d'abord activer le service d'API Llama 3.1 dans Vertex AI Model Garden.

Voici un exemple de configuration pour Llama 3.1 405b dans le 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],
    }),
  ],
});

Utilisez-le ensuite comme des modèles standards:

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

Modèles Mistral dans Vertex AI Model Garden

Si vous avez accès aux modèles Mistral (Mistral Large, Mistral Nemo ou Codestral) dans Vertex AI Model Garden, vous pouvez les utiliser avec Genkit.

Voici un exemple de configuration pour activer les modèles Model Garden de Vertex AI:

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

Utilisez-les ensuite comme des modèles standards:

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

Les modèles sont compatibles avec les éléments suivants : - mistralLarge: dernier grand modèle Mistral avec des fonctionnalités d'appel de fonction - mistralNemo: optimisé pour l'efficacité et la rapidité - codestral: spécialisé pour les tâches de génération de code

Chaque modèle est compatible avec les réponses en streaming et les appels de fonction:

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

Évaluateurs

Pour utiliser les évaluateurs de l'évaluation rapide Vertex AI, ajoutez un bloc evaluation à la configuration de votre 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 configuration ci-dessus ajoute des évaluateurs pour les métriques Safety et ROUGE. L'exemple présente deux approches : la métrique Safety utilise la spécification par défaut, tandis que la métrique ROUGE fournit une spécification personnalisée qui définit le type de rouge sur rougeLsum.

Les deux évaluateurs peuvent être exécutés à l'aide de la commande genkit eval:run avec un ensemble de données compatible, c'est-à-dire un ensemble de données avec des champs output et reference. L'évaluateur Safety peut également être exécuté à l'aide de la commande genkit eval:flow -e vertexai/safety, car il ne nécessite qu'un output.

Indexeurs et récupérateurs

Le plug-in Vertex AI Genkit inclut des implémentations d'indexeur et de récupérateur compatibles avec le service Vertex AI Vector Search.

(Consultez la page Génération augmentée de récupération pour découvrir comment les indexeurs et les récupérateurs sont utilisés dans une implémentation de RAG.)

Le service Vertex AI Vector Search est un indice de documents qui fonctionne avec le data store de votre choix: le data store contient le contenu des documents, et l'indice Vertex AI Vector Search contient, pour chaque document, son empreinte vectorielle et une référence au document dans le data store. Une fois vos documents indexés par le service Vertex AI Vector Search, il peut répondre aux requêtes de recherche, en produisant des listes d'index dans votre document store.

Les implémentations de l'indexeur et du récupérateur fournies par le plug-in Vertex AI utilisent Cloud Firestore ou BigQuery comme entrepôt de documents. Le plug-in inclut également des interfaces que vous pouvez implémenter pour prendre en charge d'autres magasins de documents.

Pour utiliser Vertex AI Vector Search:

  1. Choisissez un modèle d'embedding. Ce modèle est chargé de créer des représentations vectorielles continues à partir de texte. Les utilisateurs expérimentés peuvent utiliser un modèle d'embedding optimisé pour leurs ensembles de données spécifiques, mais pour la plupart des utilisateurs, le modèle text-embedding-004 de Vertex AI est un bon choix pour le texte en anglais et le modèle text-multilingual-embedding-002 pour le texte multilingue.

  2. Dans la section Vector Search (Recherche vectorielle) de la console Google Cloud, créez un indice. Les paramètres les plus importants sont les suivants:

    • Dimensions:spécifiez la dimensionnalité des vecteurs produits par le modèle d'embedding que vous avez choisi. Les modèles text-embedding-004 et text-multilingual-embedding-002 produisent des vecteurs à 768 dimensions.
    • Méthode de mise à jour:sélectionnez les mises à jour en streaming.

    Une fois l'index créé, déployez-le sur un point de terminaison standard (public).

  3. Obtenez un outil d'indexation et de récupération de documents pour le dépôt de documents que vous souhaitez utiliser:

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

    Other

    Pour prendre en charge d'autres magasins de documents, vous pouvez fournir vos propres implémentations de DocumentRetriever et DocumentIndexer:

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

    Pour en savoir plus, consultez Exemple de récupérateur et d'indexeur de plug-in Vertex AI avec fichier local.

  4. Ajoutez un bloc vectorSearchOptions à la configuration du 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,
        },
      ],
    }),
  ],
});

    Indiquez l'outil d'intégration que vous avez choisi à la première étape, ainsi que l'indexeur et le récupérateur de documents que vous avez créés à l'étape précédente.

    Pour configurer le plug-in afin qu'il utilise l'index Vector Search que vous avez créé précédemment, vous devez fournir plusieurs valeurs, que vous trouverez dans la section "Vector Search" (Recherche vectorielle) de la console Google Cloud:

    • indexId: indiqué dans l'onglet Indexes (Index)
    • indexEndpointId: indiqué dans l'onglet Points de terminaison d'index
    • deployedIndexId et publicDomainName: indiqués sur la page "Informations sur l'index déployé", que vous pouvez ouvrir en cliquant sur le nom de l'index déployé dans l'un des onglets mentionnés précédemment

  5. Maintenant que tout est configuré, vous pouvez utiliser l'indexeur et le récupérateur dans votre application 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,
});

Consultez les exemples de code pour:

Mise en cache du contexte

Le plug-in Vertex AI Genkit est compatible avec le mise en cache de contexte, qui permet aux modèles de réutiliser du contenu précédemment mis en cache pour optimiser l'utilisation des jetons lorsqu'ils traitent de grands éléments de contenu. Cette fonctionnalité est particulièrement utile pour les flux de conversation ou les scénarios où le modèle fait référence à un grand contenu de manière cohérente sur plusieurs requêtes.

Utiliser la mise en cache de contexte

Pour activer la mise en cache de contexte, assurez-vous que votre modèle est compatible avec cette fonctionnalité. Par exemple, gemini15Flash et gemini15Pro sont des modèles compatibles avec la mise en cache de contexte, et vous devrez spécifier le numéro de version 001.

Vous pouvez définir un mécanisme de mise en cache dans votre application comme suit:

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

Dans cette configuration : - messages: vous permet de transmettre l'historique des conversations. - metadata.cache.ttlSeconds: spécifie la valeur TTL (Time To Live) pour la mise en cache d'une réponse spécifique.

Exemple: Exploiter de longs textes avec le contexte

Pour les applications qui font référence à des documents longs, tels que Guerre et Paix ou Le Seigneur des anneaux, vous pouvez structurer vos requêtes pour réutiliser les contextes mis en 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.',
});

Avantages de la mise en cache de contexte

  1. Amélioration des performances: réduit le besoin de traiter de manière répétée de grandes entrées.
  2. Économies de coûts: réduit l'utilisation de l'API pour les données redondantes, ce qui optimise la consommation de jetons.
  3. Meilleure latence: accélère les temps de réponse pour les requêtes répétées ou associées.

Modèles compatibles avec la mise en cache de contexte

Seuls des modèles spécifiques, tels que gemini15Flash et gemini15Pro, sont compatibles avec la mise en cache de contexte, et actuellement uniquement avec les numéros de version 001. Si un modèle non compatible est utilisé, une erreur s'affiche, indiquant que le cache ne peut pas être appliqué.

Documentation complémentaire

Pour en savoir plus sur le stockage en cache de contexte dans Vertex AI, consultez la documentation.