Plug-in da Vertex AI

O plug-in da Vertex AI oferece interfaces para vários serviços de IA:

• Modelos de IA generativa do Google:
  • Geração de texto do Gemini
  • Geração de imagens do Imagen2 e do Imagen3
  • Geração de embedding de texto
• Um subconjunto de métricas de avaliação pela API Rapid Evaluation da Vertex AI:
  • BLEU (link em inglês)
  • ROUGE (link em inglês)
  • Fluência
  • Segurança
  • Embasamento
  • Qualidade do resumo
  • Utilidade do resumo
  • Verbosidade do resumo
• Vector Search

Instalação

npm i --save @genkit-ai/vertexai

Se você quiser executar localmente fluxos que usam esse plug-in, também precisará da ferramenta CLI do Google Cloud instalada.

Configuração

Para usar esse plug-in, especifique-o ao inicializar o Genkit:

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

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

O plug-in exige que você especifique o ID do projeto do Google Cloud, a região para a qual você quer fazer solicitações da API Vertex e as credenciais do seu projeto do Google Cloud.

• É possível especificar o ID do projeto do Google Cloud definindo projectId na configuração vertexAI() ou definindo a variável de ambiente GCLOUD_PROJECT. Se você estiver executando seu fluxo em um ambiente do Google Cloud (Cloud Functions, Cloud Run etc.), o GCLOUD_PROJECT será definido automaticamente como o ID do projeto do ambiente.
• É possível especificar o local da API definindo location na configuração vertexAI() ou definindo a variável de ambiente GCLOUD_LOCATION.

• Para fornecer credenciais de API, você precisa configurar o Application Default Credentials do Google Cloud.

  1. Para especificar suas credenciais:

     • Se você estiver executando seu fluxo em um ambiente do Google Cloud (Cloud Functions, Cloud Run e outros), isso é definido automaticamente.

     • No ambiente de desenvolvimento local, faça isso executando o seguinte:

       gcloud auth application-default login

     • Para outros ambientes, consulte a documentação do Application Default Credentials.

  2. Além disso, confirme se a conta recebeu o papel do IAM de usuário da Vertex AI (roles/aiplatform.user). Consulte a documentação do controle de acesso da Vertex AI.

Uso

Modelos de IA generativa

Esse plug-in exporta estaticamente referências aos modelos de IA generativa compatíveis:

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

Você pode usar essas referências para especificar qual modelo ai.generate() usa:

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

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

Esse plug-in também oferece suporte para respostas de texto do Gemini com base em pesquisas do Google ou seus próprios dados.

Importante: a Vertex AI cobra uma taxa para solicitações de endereçamento, além do custo de fazer solicitações de LLM. Consulte a página de preços da Vertex AI e entenda os preços dos pedidos de grounding antes de usar esse recurso.

Exemplo:

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

Esse plug-in também exporta estaticamente uma referência ao modelo de embedding de texto do Gecko:

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

Use essa referência para especificar qual incorporador um indexador ou retriever usa. Por exemplo, se você usa o Chroma DB:

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

Também é possível gerar uma incorporação diretamente:

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

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

O modelo Imagen3 permite gerar imagens a partir de comandos do usuário:

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 até mesmo edição avançada de imagens 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();

Consulte a documentação do modelo Imagen para conferir opções mais detalhadas.

Anthropic Claude 3 no Model Garden da Vertex AI

Se você tiver acesso aos modelos Claude 3 (haiku, sonnet ou opus) no Model Garden da Vertex AI, poderá usá-los com o Genkit.

Confira um exemplo de configuração para ativar os modelos do Model Garden da 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],
    }),
  ],
});

Em seguida, use-os como modelos normais:

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

Llama 3.1 405b no Model Garden da Vertex AI

Primeiro, ative o serviço da API Llama 3.1 no Vertex AI Model Garden.

Confira um exemplo de configuração do Llama 3.1 405b no plug-in da Vertex AI:

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

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

Em seguida, use-o como modelos normais:

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

Modelos Mistral no Model Garden da Vertex AI

Se você tiver acesso aos modelos Mistral (Mistral Large, Mistral Nemo ou Codestral) no Model Garden da Vertex AI, poderá usá-los com o Genkit.

Confira um exemplo de configuração para ativar os modelos do Model Garden da 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],
    }),
  ],
});

Em seguida, use-os como modelos normais:

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

Os modelos oferecem suporte a: - mistralLarge: modelo grande Mistral mais recente com recursos de chamada de função - mistralNemo: otimizado para eficiência e velocidade - codestral: especializado para tarefas de geração de código

Cada modelo oferece suporte a respostas de streaming e chamadas de função:

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

Avaliadores

Para usar os avaliadores da avaliação rápida da Vertex AI, adicione um bloco evaluation à configuração do 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',
          },
        },
      ],
    }),
  ],
});

A configuração acima adiciona avaliadores para as métricas Safety e ROUGE. O exemplo mostra duas abordagens: a métrica Safety usa a especificação padrão, enquanto a métrica ROUGE fornece uma especificação personalizada que define o tipo de rouge como rougeLsum.

Os dois avaliadores podem ser executados usando o comando genkit eval:run com um conjunto de dados compatível, ou seja, um conjunto de dados com campos output e reference. O avaliador Safety também pode ser executado usando o comando genkit eval:flow -e vertexai/safety, já que ele só exige um output.

Indexadores e recuperadores

O plug-in da Vertex AI do Genkit inclui implementações de indexador e recuperador com suporte do serviço de pesquisa de vetor da Vertex AI.

Consulte a página Geração aumentada de recuperação para saber como os indexadores e recuperadores são usados em uma implementação de RAG.

O serviço de pesquisa de vetor da Vertex AI é um índice de documentos que funciona com o repositório de documentos que você escolher: o repositório contém o conteúdo dos documentos, e o índice de pesquisa de vetor da Vertex AI contém, para cada documento, o embedding vetorial e uma referência ao documento no repositório. Depois que seus documentos forem indexados pelo serviço de pesquisa de vetor da Vertex AI, ele poderá responder a consultas de pesquisa, produzindo listas de índices na sua loja de documentos.

As implementações de indexador e recuperador fornecidas pelo plug-in da Vertex AI usam o Cloud Firestore ou o BigQuery como a loja de documentos. O plug-in também inclui interfaces que podem ser implementadas para oferecer suporte a outras lojas de documentos.

Importante: o preço da Pesquisa vetorial consiste em uma cobrança por cada gigabyte de dados ingeridos e uma cobrança por hora para as VMs que hospedam os índices implantados. Consulte os preços da Vertex AI. Essa é a opção mais econômica quando você exibe grandes volumes de tráfego. Entenda as implicações de faturamento que o serviço vai ter no seu projeto antes de usá-lo.

Para usar a pesquisa de vetores da Vertex AI:

1. Escolha um modelo de embedding. Esse modelo é responsável por criar embeddings de vetores a partir de texto. Os usuários avançados podem usar um modelo de incorporação otimizado para conjuntos de dados específicos, mas, para a maioria dos usuários, o modelo text-embedding-004 da Vertex AI é uma boa escolha para textos em inglês, e o modelo text-multilingual-embedding-002 é bom para textos multilíngues.

2. Na seção Pesquisa de vetor do console do Google Cloud, crie um novo índice. As configurações mais importantes são:

   • Dimensões:especifique a dimensionalidade dos vetores produzidos pelo modelo de embedding escolhido. Os modelos text-embedding-004 e text-multilingual-embedding-002 produzem vetores de 768 dimensões.
   • Método de atualização:selecione as atualizações de streaming.

   Depois de criar o índice, implante-o em um endpoint padrão (público).

3. Receba um indexador e um extrator de documentos para o repositório de documentos que você quer 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);
   

   Outro

   Para oferecer suporte a outras lojas de documentos, forneça suas próprias implementações de DocumentRetriever e DocumentIndexer:

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

   Para conferir um exemplo, consulte Exemplo de retriever e indexador de plug-ins da Vertex AI com arquivo local.

4. Adicione um bloco vectorSearchOptions à configuração do 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,
           },
         ],
       }),
     ],
   });
   

   Informe o incorporação que você escolheu na primeira etapa e o indexador e o extrator de documentos que você criou na etapa anterior.

   Para configurar o plug-in para usar o índice da Pesquisa vetorial que você criou anteriormente, é necessário fornecer vários valores, que podem ser encontrados na seção "Pesquisa vetorial" do console do Google Cloud:

   • indexId: listado na guia Índices
   • indexEndpointId: listado na guia Endpoints do índice
   • deployedIndexId e publicDomainName: listados na página "Informações do índice implantado", que pode ser aberta clicando no nome do índice implantado em qualquer uma das guias mencionadas anteriormente

5. Agora que tudo está configurado, você pode usar o indexador e o extrator no seu aplicativo do 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,
   });
   

Confira os exemplos de código para:

• Pesquisa de vetor da Vertex + BigQuery
• Pesquisa de vetor da Vertex + Firestore
• Pesquisa de vetor da Vertex + um DB personalizado

Armazenamento em cache de contexto

O plug-in do Vertex AI Genkit oferece suporte à Armazenamento em cache de contexto, que permite que os modelos reutilizem conteúdo armazenado em cache anteriormente para otimizar o uso de tokens ao lidar com grandes partes de conteúdo. Esse recurso é especialmente útil para fluxos de conversa ou cenários em que o modelo faz referência a um grande conteúdo de forma consistente em várias solicitações.

Como usar o armazenamento em cache de contexto

Para ativar o armazenamento em cache de contexto, verifique se o modelo oferece suporte a ele. Por exemplo, gemini15Flash e gemini15Pro são modelos compatíveis com o armazenamento em cache de contexto, e você vai precisar especificar o número da versão 001.

É possível definir um mecanismo de armazenamento em cache no app desta forma:

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

Nessa configuração: - messages: permite transmitir o histórico de conversas. - metadata.cache.ttlSeconds: especifica o time to live (TTL) para armazenar uma resposta específica em cache.

Exemplo: como usar textos grandes com contexto

Para aplicativos que fazem referência a documentos longos, como Guerra e Paz ou O Senhor dos Anéis, é possível estruturar as consultas para reutilizar contextos em 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.',
});

Benefícios do armazenamento em cache de contexto

1. Melhoria no desempenho: reduz a necessidade de processamento repetido de entradas grandes.
2. Eficiência de custo: reduz o uso da API para dados redundantes, otimizando o consumo de tokens.
3. Melhor latência: acelera os tempos de resposta para consultas repetidas ou relacionadas.

Modelos com suporte para armazenamento em cache de contexto

Apenas modelos específicos, como gemini15Flash e gemini15Pro, são compatíveis com o armazenamento em cache de contexto e, no momento, apenas nos números de versão 001. Se um modelo sem suporte for usado, um erro será gerado, indicando que o armazenamento em cache não pode ser aplicado.

Leitura adicional

Consulte mais informações sobre o armazenamento em cache de contexto na documentação da Vertex AI.