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 專案憑證。

  • 您可以透過在 vertexAI() 設定中設定 projectId，或設定 GCLOUD_PROJECT 環境變數，指定 Google Cloud 專案 ID。如果您是透過 Google Cloud 環境 (Cloud Functions、Cloud Run 等) 執行流程，GCLOUD_PROJECT 會自動設為該環境的專案 ID。
  • 您可以透過在 vertexAI() 設定中設定 location，或設定 GCLOUD_LOCATION 環境變數，指定 API 位置。

  • 如要提供 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 模型園地中的 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 服務。

以下是 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 指標新增評估工具。本範例顯示兩種方法：Safety 指標使用預設規格，而 ROUGE 指標則提供自訂規格，將 rouge 類型設為 rougeLsum。

您可以使用 genkit eval:run 指令搭配相容的資料集 (也就是含有 output 和 reference 欄位的資料集) 執行這兩種評估工具。Safety 評估器也可以使用 genkit eval:flow -e vertexai/safety 指令執行，因為它只需要 output。

索引器和擷取器

Genkit Vertex AI 外掛程式包含由 Vertex AI Vector Search 服務支援的索引器和擷取器實作項目。

(請參閱「檢索增強生成」頁面，瞭解如何在 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. 將 vectorSearchOptions 區塊新增至 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,
        },
      ],
    }),
  ],
});

    提供您在第一步驟中選擇的嵌入器，以及您在上一個步驟中建立的文件索引器和擷取器。

    如要設定外掛程式，以便使用先前建立的 Vector Search 索引，您必須提供幾個值，這些值可在 Google Cloud 控制台的 Vector Search 專區中找到：

    • 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 的內容快取功能，請參閱相關說明文件。