Complemento de Vertex AI

El complemento de Vertex AI proporciona interfaces para varios servicios de IA:

• Modelos de IA generativa de Google:
  • Generación de texto de Gemini
  • Generación de imágenes de Imagen2 e Imagen3
  • Generación de incorporaciones de texto
• Un subconjunto de métricas de evaluación a través de la API de Rapid Evaluation de Vertex AI:
  • BLEU
  • ROUGE
  • Fluidez
  • Seguridad
  • Fundamentación
  • Calidad del resumen
  • Utilidad de los resúmenes
  • Verbosidad del resumen
• Búsqueda de vectores

Instalación

npm i --save @genkit-ai/vertexai

Si quieres ejecutar localmente flujos que usan este complemento, también debes tener instalada la herramienta Google Cloud CLI.

Configuración

Para usar este complemento, especifícalo cuando inicialices Genkit:

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

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

El complemento requiere que especifiques el ID de tu proyecto de Google Cloud, la región a la que deseas realizar solicitudes a la API de Vertex y las credenciales de tu proyecto de Google Cloud.

• Puedes especificar el ID de tu proyecto de Google Cloud configurando projectId en la configuración de vertexAI() o configurando la variable de entorno GCLOUD_PROJECT. Si ejecutas tu flujo desde un entorno de Google Cloud (Cloud Functions, Cloud Run, etc.), GCLOUD_PROJECT se establece automáticamente en el ID del proyecto del entorno.
• Para especificar la ubicación de la API, configura location en la configuración de vertexAI() o establece la variable de entorno GCLOUD_LOCATION.

• Para proporcionar las credenciales de la API, debes configurar las credenciales predeterminadas de la aplicación de Google Cloud.

  1. Para especificar tus credenciales, haz lo siguiente:

     • Si ejecutas tu flujo desde un entorno de Google Cloud (Cloud Functions, Cloud Run, etc.), esto se configura automáticamente.

     • En tu entorno de desarrollo local, ejecuta el siguiente comando:

       gcloud auth application-default login

     • Para otros entornos, consulta los documentos Credenciales predeterminadas de la aplicación.

  2. Además, asegúrate de que la cuenta tenga el rol de IAM Usuario de Vertex AI (roles/aiplatform.user). Consulta los documentos de control de acceso de Vertex AI.

Uso

Modelos de IA generativa

Este complemento exporta de forma estática referencias a sus modelos de IA generativa compatibles:

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

Puedes usar estas referencias para especificar qué modelo usa 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?',
});

Este complemento también admite la fundamentación de respuestas de texto de Gemini con la Búsqueda de Google o tus propios datos.

Ejemplo:

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

Este complemento también exporta de forma estática una referencia al modelo de incorporación de texto de Gecko:

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

Puedes usar esta referencia para especificar qué incorporador usa un indexador o un recuperador. Por ejemplo, si usas Chroma DB:

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

También puedes generar una incorporación directamente:

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

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

El modelo Imagen3 permite generar imágenes a partir de instrucciones del usuario:

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

y hasta edición avanzada de imágenes existentes:

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

Consulta la documentación del modelo de imagen para obtener opciones más detalladas.

Claude 3 de Anthropic en Model Garden de Vertex AI

Si tienes acceso a modelos de Claude 3 (haiku, soneto o opus) en Model Garden de Vertex AI, puedes usarlos con Genkit.

Esta es una configuración de muestra para habilitar los modelos de 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],
    }),
  ],
});

Luego, úsalas como modelos normales:

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

Llama 3.1 405b en Vertex AI Model Garden

Primero, deberás habilitar el servicio de la API de Llama 3.1 en Vertex AI Model Garden.

Esta es una configuración de ejemplo para Llama 3.1 405b en el complemento de Vertex AI:

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

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

Luego, úsalo como modelos normales:

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

Modelos de Mistral en Vertex AI Model Garden

Si tienes acceso a los modelos de Mistral (Mistral Large, Mistral Nemo o Codestral) en Vertex AI Model Garden, puedes usarlos con Genkit.

Esta es una configuración de muestra para habilitar los modelos de 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],
    }),
  ],
});

Luego, úsalas como modelos normales:

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

Los modelos admiten lo siguiente: - mistralLarge: El modelo grande Mistral más reciente con capacidades de llamadas a funciones - mistralNemo: Se optimizó para la eficiencia y la velocidad - codestral: Se especializa en tareas de generación de código

Cada modelo admite respuestas de transmisión y llamadas a funciones:

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

Evaluadores

Para usar los evaluadores de la evaluación rápida de Vertex AI, agrega un bloque evaluation a la configuración del complemento 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 configuración anterior agrega evaluadores para las métricas Safety y ROUGE. En el ejemplo, se muestran dos enfoques: la métrica Safety usa la especificación predeterminada, mientras que la métrica ROUGE proporciona una especificación personalizada que establece el tipo de rouge en rougeLsum.

Ambos evaluadores se pueden ejecutar con el comando genkit eval:run con un conjunto de datos compatible, es decir, un conjunto de datos con campos output y reference. El evaluador Safety también se puede ejecutar con el comando genkit eval:flow -e vertexai/safety, ya que solo requiere un output.

Indexadores y recuperadores

El complemento de Vertex AI de Genkit incluye implementaciones de indexadores y recuperadores respaldadas por el servicio de Búsqueda de vectores de Vertex AI.

(Consulta la página Generación mejorada de recuperación para aprender a usar los indexadores y recuperadores en una implementación de RAG).

El servicio de Búsqueda de vectores de Vertex AI es un índice de documentos que funciona junto con el almacén de documentos que elijas: el almacén de documentos contiene el contenido de los documentos, y el índice de Búsqueda de vectores de Vertex AI contiene, para cada documento, su incorporación vectorial y una referencia al documento en el almacén de documentos. Después de que el servicio de Búsqueda de vectores de Vertex AI indexa tus documentos, puede responder a las búsquedas y generar listas de índices en tu almacén de documentos.

Las implementaciones del indexador y el recuperador que proporciona el complemento de Vertex AI usan Cloud Firestore o BigQuery como el almacén de documentos. El complemento también incluye interfaces que puedes implementar para admitir otros almacenes de documentos.

Para usar la Búsqueda de vectores de Vertex AI, haz lo siguiente:

1. Elige un modelo de incorporación. Este modelo es responsable de crear incorporaciones vectoriales a partir de texto. Los usuarios avanzados pueden usar un modelo de incorporación optimizado para sus conjuntos de datos particulares, pero para la mayoría de los usuarios, el modelo text-embedding-004 de Vertex AI es una buena opción para el texto en inglés y el modelo text-multilingual-embedding-002 es bueno para el texto multilingüe.

2. En la sección Vector Search de la consola de Google Cloud, crea un índice nuevo. Los parámetros de configuración más importantes son los siguientes:

   • Dimensiones: Especifica la dimensionalidad de los vectores que produce el modelo de incorporación que elegiste. Los modelos text-embedding-004 y text-multilingual-embedding-002 producen vectores de 768 dimensiones.
   • Método de actualización: Selecciona las actualizaciones de transmisión.

   Después de crear el índice, impleméntalo en un extremo estándar (público).

3. Obtén un indexador y un recuperador de documentos para el almacén de documentos que deseas usar:

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

   Otro

   Para admitir otros almacenes de documentos, puedes proporcionar tus propias implementaciones de DocumentRetriever y DocumentIndexer:

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

   Para ver un ejemplo, consulta Obtenedor y indexador de complementos de Vertex AI de muestra con archivo local.

4. Agrega un bloque vectorSearchOptions a la configuración del complemento 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,
           },
         ],
       }),
     ],
   });
   

   Proporciona el incorporador que elegiste en el primer paso y el indexador y el recuperador de documentos que creaste en el paso anterior.

   Para configurar el complemento para que use el índice de Vector Search que creaste antes, debes proporcionar varios valores, que puedes encontrar en la sección de Vector Search de la consola de Google Cloud:

   • indexId: aparece en la pestaña Índices
   • indexEndpointId: aparece en la pestaña Extremos de índice
   • deployedIndexId y publicDomainName: aparecen en la página "Información del índice implementado", que puedes abrir haciendo clic en el nombre del índice implementado en cualquiera de las pestañas mencionadas anteriormente

5. Ahora que todo está configurado, puedes usar el indexador y el recuperador en tu aplicación de 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 las muestras de código para lo siguiente:

• Vector Search de Vertex + BigQuery
• Búsqueda de vectores de Vertex + Firestore
• Búsqueda de vectores de Vertex + una base de datos personalizada

Almacenamiento en caché de contexto

El complemento Genkit de Vertex AI admite la caché de contexto, que permite a los modelos volver a usar contenido almacenado en caché anteriormente para optimizar el uso de tokens cuando se trata de grandes cantidades de contenido. Esta función es especialmente útil para flujos de conversación o situaciones en las que el modelo hace referencia a un contenido extenso de forma coherente en varias solicitudes.

Cómo usar el almacenamiento en caché de contexto

Para habilitar la caché de contexto, asegúrate de que tu modelo la admita. Por ejemplo, gemini15Flash y gemini15Pro son modelos que admiten la caché de contexto, y deberás especificar el número de versión 001.

Puedes definir un mecanismo de almacenamiento en caché en tu aplicación de la siguiente manera:

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

En esta configuración: - messages: Te permite pasar el historial de conversaciones. - metadata.cache.ttlSeconds: Especifica el tiempo de actividad (TTL) para almacenar en caché una respuesta específica.

Ejemplo: Aprovecha textos grandes con contexto

En el caso de las aplicaciones que hacen referencia a documentos largos, como Guerra y paz o El Señor de los Anillos, puedes estructurar tus consultas para volver a usar los contextos almacenados en caché:

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

Beneficios del almacenamiento en caché de contexto

1. Rendimiento mejorado: Reduce la necesidad de procesar de forma repetida entradas grandes.
2. Eficiencia de costos: Disminuye el uso de la API para datos redundantes, lo que optimiza el consumo de tokens.
3. Mejor latencia: Agiliza los tiempos de respuesta de las consultas repetidas o relacionadas.

Modelos compatibles con el almacenamiento en caché de contexto

Solo modelos específicos, como gemini15Flash y gemini15Pro, admiten la caché de contexto y, actualmente, solo en los números de versión 001. Si se usa un modelo no compatible, se generará un error que indicará que no se puede aplicar el almacenamiento en caché.

Lecturas adicionales

Consulta más información sobre el almacenamiento en caché de contexto en Vertex AI en su documentación.