Vertex AI プラグイン

Vertex AI プラグインは、次の AI サービスへのインターフェースを提供します。

インストール

npm i --save @genkit-ai/vertexai

このプラグインを使用するフローをローカルで実行する場合は、Google Cloud CLI ツールもインストールする必要があります。

構成

このプラグインを使用するには、Genkit の初期化時に指定します。

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

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

このプラグインでは、Google Cloud プロジェクト ID、Vertex API リクエストを行うリージョン、Google Cloud プロジェクトの認証情報を指定する必要があります。

  • Google Cloud プロジェクト ID は、vertexAI() 構成で projectId を設定するか、GCLOUD_PROJECT 環境変数を設定することで指定できます。Google Cloud 環境（Cloud Functions、Cloud Run など）からフローを実行している場合、GCLOUD_PROJECT は環境のプロジェクト ID に自動的に設定されます。
  • API のロケーションは、vertexAI() 構成で location を設定するか、GCLOUD_LOCATION 環境変数を設定することで指定できます。

  • API 認証情報を指定するには、Google Cloud アプリケーションのデフォルト認証情報を設定する必要があります。

    1. 認証情報を指定するには:

      • Google Cloud 環境（Cloud Functions、Cloud Run など）からフローを実行している場合は、自動的に設定されます。

      • ローカル開発環境で、次のコマンドを実行します。

        gcloud auth application-default login

      • 他の環境については、アプリケーションのデフォルト認証情報のドキュメントをご覧ください。

    2. また、アカウントに Vertex AI ユーザー IAM ロール（roles/aiplatform.user）が付与されていることを確認します。Vertex AI のアクセス制御のドキュメントをご覧ください。

用途

生成 AI モデル

このプラグインは、サポートされている生成 AI モデルへの参照を静的にエクスポートします。

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

これらの参照を使用して、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?',
});

このプラグインは、Google 検索または独自のデータを使用して Gemini のテキスト回答をグラウンディングすることもサポートしています。

例:

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

このプラグインは、Gecko テキスト エンベディング モデルへの参照も静的にエクスポートします。

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

この参照を使用して、インデックス エンジンまたは取得ツールが使用する埋め込みツールを指定できます。たとえば、Chroma DB を使用している場合:

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

または、エンベディングを直接生成することもできます。

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

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

Imagen3 モデルでは、ユーザー プロンプトから画像を生成できます。

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

既存の画像の高度な編集も可能です。

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

詳細なオプションについては、Imagen モデルのドキュメントをご覧ください。

Vertex AI Model Garden での Anthropic Claude 3

Vertex AI Model Garden の Claude 3 モデル（俳句、ソネット、オペス）にアクセスできる場合は、Genkit で使用できます。

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

次に、通常のモデルとして使用します。

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

Vertex AI Model Garden の Llama 3.1 405b

まず、Vertex AI Model Garden で Llama 3.1 API Service を有効にする必要があります。

Vertex AI プラグインでの Llama 3.1 405b の構成例を次に示します。

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

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

次に、通常のモデルとして使用します。

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

Vertex AI Model Garden の Mistral モデル

Vertex AI Model Garden で Mistral モデル（Mistral Large、Mistral Nemo、Codestral）にアクセスできる場合は、Genkit で使用できます。

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

次に、通常のモデルとして使用します。

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

モデルは次のものをサポートしています。 - mistralLarge: 関数呼び出し機能を備えた最新の Mistral 大規模モデル - mistralNemo: 効率と速度を重視して最適化されたモデル - codestral: コード生成タスクに特化したモデル

各モデルは、レスポンスのストリーミングと関数呼び出しをサポートしています。

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

エバリュエータ

Vertex AI Rapid Evaluation の評価ツールを使用するには、vertexAI プラグインの構成に evaluation ブロックを追加します。

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

上記の構成では、Safety 指標と ROUGE 指標のエバリュエータを追加しています。この例では、2 つのアプローチを示しています。Safety 指標はデフォルトの仕様を使用しますが、ROUGE 指標は、ルージュ タイプを rougeLsum に設定するカスタマイズされた仕様を提供します。

どちらの評価ツールも、output フィールドと reference フィールドを含む互換性のあるデータセットで genkit eval:run コマンドを使用して実行できます。Safety エバリュエータは output のみを必要とするため、genkit eval:flow -e vertexai/safety コマンドを使用して実行することもできます。

インデクサーとリトリーバー

Genkit Vertex AI プラグインには、Vertex AI ベクトル検索サービスが基盤となるインデクサーと取得ツールの実装が含まれています。

（RAG 実装でインデクサーとリトリーバーがどのように使用されるかについては、検索拡張生成のページをご覧ください）。

Vertex AI Vector Search サービスは、任意のドキュメント ストアとともに機能するドキュメント インデックスです。ドキュメント ストアにはドキュメントのコンテンツが含まれ、Vertex AI Vector Search インデックスには、ドキュメントごとにベクトル エンベディングとドキュメント ストア内のドキュメントへの参照が含まれます。Vertex AI Vector Search サービスによってドキュメントにインデックスが作成されると、検索クエリに応答し、ドキュメント ストア内にインデックスのリストを生成できます。

Vertex AI プラグインによって提供されるインデクサーと取得ツールの実装では、ドキュメント ストアとして Cloud Firestore または BigQuery のいずれかを使用します。このプラグインには、他のドキュメント ストアをサポートするために実装できるインターフェースも含まれています。

Vertex AI Vector Search を使用する手順は次のとおりです。

  1. エンベディング モデルを選択します。このモデルは、テキストからベクトル エンベディングを作成します。上級ユーザーは、特定のデータセット用に最適化されたエンベディング モデルを使用できますが、ほとんどのユーザーにとって、Vertex AI の text-embedding-004 モデルは英語のテキストに適しており、text-multilingual-embedding-002 モデルは多言語テキストに適しています。

  2. Google Cloud コンソールの [ベクトル検索] セクションで、新しいインデックスを作成します。最も重要な設定は次のとおりです。

    • ディメンション: 選択したエンベディング モデルによって生成されるベクトルの次元を指定します。text-embedding-004 モデルと text-multilingual-embedding-002 モデルは、768 次元のベクトルを生成します。
    • 更新方法: ストリーミング アップデートを選択します。

    インデックスを作成したら、標準（パブリック）エンドポイントにデプロイします。

  3. 使用するドキュメント ストアのドキュメント インデックス登録ツールと取得ツールを取得します。

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

    その他

    他のドキュメント ストアをサポートするには、DocumentRetriever と DocumentIndexer の独自の実装を提供します。

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

    例については、ローカル ファイルを使用する Vertex AI プラグイン レトリーバーとインデックス エンジンのサンプルをご覧ください。

  4. vertexAI プラグイン構成に vectorSearchOptions ブロックを追加します。

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

    最初の手順で選択したエンベディング ツールと、前の手順で作成したドキュメント インデックスと取得ツールを指定します。

    前に作成したベクトル検索インデックスを使用するようにプラグインを構成するには、いくつかの値を指定する必要があります。これらの値は、Google Cloud コンソールの [ベクトル検索] セクションで確認できます。

    • indexId: [インデックス] タブに表示されます。
    • indexEndpointId: [インデックス エンドポイント] タブに表示されます。
    • deployedIndexId と publicDomainName: [デプロイされたインデックスの情報] ページに表示されます。このページは、前述のいずれかのタブでデプロイされたインデックスの名前をクリックして開くことができます。

  5. これで、すべての構成が完了しました。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,
});

次のコードサンプルをご覧ください。

コンテキスト キャッシュ保存

Vertex AI Genkit プラグインはコンテキスト キャッシュ保存をサポートしています。これにより、モデルは以前にキャッシュに保存されたコンテンツを再利用して、大規模なコンテンツを処理する際のトークン使用量を最適化できます。この機能は、会話フローで、またはモデルが複数のリクエストで大量のコンテンツを常に参照するシナリオで特に便利です。

コンテキスト キャッシュ保存の使用方法

コンテキスト キャッシュ保存を有効にするには、モデルがコンテキスト キャッシュ保存をサポートしていることを確認します。たとえば、gemini15Flash と gemini15Pro はコンテキスト キャッシュ保存をサポートするモデルであり、バージョン番号 001 を指定する必要があります。

次のように、アプリケーションでキャッシュ メカニズムを定義できます。

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

この設定では、次のようになります。 - messages: 会話履歴を渡すことができます。- metadata.cache.ttlSeconds: 特定のレスポンスをキャッシュに保存する有効期間（TTL）を指定します。

例: コンテキストで長いテキストを活用する

戦争と平和やロード オブ ザ リングなどの長いドキュメントを参照するアプリケーションの場合、キャッシュに保存されたコンテキストを再利用するようにクエリを構成できます。


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

コンテキスト キャッシュのメリット

  1. パフォーマンスの向上: 大規模な入力の繰り返し処理の必要性が軽減されます。
  2. 費用対効果: 冗長データに対する API の使用量を減らし、トークンの使用量を最適化します。
  3. レイテンシの短縮: 繰り返しのクエリや関連するクエリのレスポンス時間が短縮されます。

コンテキスト キャッシュ保存でサポートされているモデル

コンテキスト キャッシュ保存をサポートするのは、gemini15Flash や gemini15Pro などの特定のモデルのみです。現在、サポートされているのはバージョン番号 001 のみです。サポートされていないモデルが使用されている場合、キャッシュを適用できないことを示すエラーが発生します。

関連情報

Vertex AI のコンテキスト キャッシュに関する詳細については、ドキュメントをご覧ください。