From edf9c7195087cd4c8835cf754a5293c31c672576 Mon Sep 17 00:00:00 2001 From: Kevin Cheung Date: Tue, 12 Nov 2024 13:51:24 -0800 Subject: [PATCH] docs: 0.9 plugin updates --- docs/plugins/chroma.md | 56 +++---- docs/plugins/google-genai.md | 103 ++++++------ docs/plugins/ollama.md | 64 +++----- docs/plugins/pinecone.md | 47 +++--- docs/plugins/vertex-ai.md | 302 +++++++++++++++-------------------- 5 files changed, 247 insertions(+), 325 deletions(-) diff --git a/docs/plugins/chroma.md b/docs/plugins/chroma.md index a0649df3f..4b291787a 100644 --- a/docs/plugins/chroma.md +++ b/docs/plugins/chroma.md @@ -1,6 +1,6 @@ # Chroma plugin -The Chroma plugin provides indexer and retriever implementatons that use the +The Chroma plugin provides indexer and retriever implementations that use the [Chroma](https://docs.trychroma.com/) vector database in client/server mode. ## Installation @@ -11,77 +11,73 @@ npm i --save genkitx-chromadb ## Configuration -To use this plugin, specify it when you call `configureGenkit()`: +To use this plugin, specify it when you initialize Genkit: -```js +```ts +import { genkit } from 'genkit'; import { chroma } from 'genkitx-chromadb'; -export default configureGenkit({ +const ai = genkit({ plugins: [ chroma([ { collectionName: 'bob_collection', - embedder: textEmbeddingGecko, + embedder: textEmbedding004, }, ]), ], - // ... }); ``` -You must specify a Chroma collection and the embedding model you want to use. In +You must specify a Chroma collection and the embedding model you want to use. In addition, there are two optional parameters: -- `clientParams`: If you're not running your Chroma server on the same machine - as your Genkit flow, you need to specify auth options, or you're otherwise not - running a default Chroma server configuration, you can specify a Chroma - [`ChromaClientParams` object](https://docs.trychroma.com/js_reference/Client) - to pass to the Chroma client: +* `clientParams`: If you're not running your Chroma server on the same machine as your Genkit flow, you need to specify auth options, or you're otherwise not running a default Chroma server configuration, you can specify a Chroma [ChromaClientParams object]([https://docs.trychroma.com/js_reference/Client](https://docs.trychroma.com/js_reference/Client)) to pass to the Chroma client: - ```js - clientParams: { - path: "http://192.168.10.42:8000", - } - ``` + ```ts + clientParams: { + path: "http://192.168.10.42:8000", + } + ``` -- `embedderOptions`: Use this parameter to pass options to the embedder: +* `embedderOptions`: Use this parameter to pass options to the embedder: - ```js - embedderOptions: { taskType: 'RETRIEVAL_DOCUMENT' }, - ``` + ```ts + embedderOptions: { taskType: 'RETRIEVAL_DOCUMENT' }, + ``` ## Usage Import retriever and indexer references like so: -```js +```ts import { chromaRetrieverRef } from 'genkitx-chromadb'; import { chromaIndexerRef } from 'genkitx-chromadb'; ``` -Then, pass the references to `retrieve()` and `index()`: +Then, use the references with `ai.retrieve()` and `ai.index()`: -```js +```ts // To use the index you configured when you loaded the plugin: -let docs = await retrieve({ retriever: chromaRetrieverRef, query }); +let docs = await ai.retrieve({ retriever: chromaRetrieverRef, query }); // To specify an index: export const bobFactsRetriever = chromaRetrieverRef({ collectionName: 'bob-facts', }); -docs = await retrieve({ retriever: bobFactsRetriever, query }); +docs = await ai.retrieve({ retriever: bobFactsRetriever, query }); ``` -```js +```ts // To use the index you configured when you loaded the plugin: -await index({ indexer: chromaIndexerRef, documents }); +await ai.index({ indexer: chromaIndexerRef, documents }); // To specify an index: export const bobFactsIndexer = chromaIndexerRef({ collectionName: 'bob-facts', }); -await index({ indexer: bobFactsIndexer, documents }); +await ai.index({ indexer: bobFactsIndexer, documents }); ``` -See the [Retrieval-augmented generation](../rag.md) page for a general +See the [Retrieval-augmented generation](../rag) page for a general discussion on indexers and retrievers. diff --git a/docs/plugins/google-genai.md b/docs/plugins/google-genai.md index bf67c9cb2..f851eea6f 100644 --- a/docs/plugins/google-genai.md +++ b/docs/plugins/google-genai.md @@ -11,14 +11,14 @@ npm i --save @genkit-ai/googleai ## Configuration -To use this plugin, specify it when you call `configureGenkit()`: +To use this plugin, specify it when you initialize Genkit: -```js +```ts +import { genkit } from 'genkit'; import { googleAI } from '@genkit-ai/googleai'; -export default configureGenkit({ +const ai = genkit({ plugins: [googleAI()], - // ... }); ``` @@ -27,61 +27,48 @@ The plugin requires an API key for the Gemini API, which you can get from Configure the plugin to use your API key by doing one of the following: -- Set the `GOOGLE_GENAI_API_KEY` environment variable to your API key. +* Set the `GOOGLE_GENAI_API_KEY` environment variable to your API key. +* Specify the API key when you initialize the plugin: -- Specify the API key when you initialize the plugin: - - ```js - googleAI({ apiKey: yourKey }); - ``` - - However, don't embed your API key directly in code! Use this feature only - in conjunction with a service like Cloud Secret Manager or similar. - -Some models (like Gemini 1.5 Pro) are in preview and only aviable via the -`v1beta` API. You can specify the `apiVersion` to get access to those models: - -```js -configureGenkit({ - plugins: [googleAI({ apiVersion: 'v1beta' })], -}); +```ts +googleAI({ apiKey: yourKey }); ``` -or you can specify multiple versions if you'd like to use different versions of -models at the same time. - -```js -configureGenkit({ - plugins: [googleAI({ apiVersion: ['v1', 'v1beta'] })], -}); -``` +However, don't embed your API key directly in code! Use this feature only in +conjunction with a service like Cloud Secret Manager or similar. ## Usage This plugin statically exports references to its supported models: -```js +```ts import { gemini15Flash, gemini15Pro, - textEmbeddingGecko001, + textEmbedding004, } from '@genkit-ai/googleai'; ``` You can use these references to specify which model `generate()` uses: -```js -const llmResponse = await generate({ +```ts +const ai = genkit({ + plugins: [googleAI()], model: gemini15Flash, - prompt: 'Tell me a joke.', }); + +const llmResponse = await ai.generate('Tell me a joke.'); ``` -or use embedders (ex. `textEmbeddingGecko001`) with `embed` or retrievers: +or use embedders (ex. `textEmbedding004`) with `embed` or retrievers: + +```ts +const ai = genkit({ + plugins: [googleAI()], +}); -```js -const embedding = await embed({ - embedder: textEmbeddingGecko001, +const embedding = await ai.embed({ + embedder: textEmbedding004, content: input, }); ``` @@ -90,8 +77,14 @@ const embedding = await embed({ You can use files uploaded to the Gemini Files API with Genkit: -```js +```ts import { GoogleAIFileManager } from '@google/generative-ai/server'; +import { genkit } from 'genkit'; +import { googleAI } from '@genkit-ai/googleai'; + +const ai = genkit({ + plugins: [googleAI()], +}); const fileManager = new GoogleAIFileManager(process.env.GOOGLE_GENAI_API_KEY); const uploadResult = await fileManager.uploadFile( @@ -102,7 +95,7 @@ const uploadResult = await fileManager.uploadFile( } ); -const response = await generate({ +const response = await ai.generate({ model: gemini15Flash, prompt: [ {text: 'Describe this image:'}, @@ -113,18 +106,30 @@ const response = await generate({ ## Fine-tuned models -You can use models fine-tuned with the Google Gemini API. Follow the instructions from the [Gemini API](https://ai.google.dev/gemini-api/docs/model-tuning/tutorial?lang=python) or fine-tune a model using [AI Studio](https://aistudio.corp.google.com/app/tune). +You can use models fine-tuned with the Google Gemini API. Follow the +instructions from the +[Gemini API](https://ai.google.dev/gemini-api/docs/model-tuning/tutorial?lang=python) +or fine-tune a model using +[AI Studio](https://aistudio.corp.google.com/app/tune). -The tuning process uses a base model—for example, Gemini 1.5 Flash—and your provided examples to create a new tuned model. Remember the base model you used, and copy the new model's ID. +The tuning process uses a base model—for example, Gemini 1.5 Flash—and your +provided examples to create a new tuned model. Remember the base model you +used, and copy the new model's ID. -When calling the tuned model in Genkit, use the base model as the `model` parameter, and pass the tuned model's ID as part of the `config` block. For example, if you used Gemini 1.5 Flash as the base model, and got the model ID `tunedModels/my-example-model-apbm8oqbvuv2` you can call it with a block like the following: +When calling the tuned model in Genkit, use the base model as the `model` +parameter, and pass the tuned model's ID as part of the `config` block. For +example, if you used Gemini 1.5 Flash as the base model, and got the model ID +`tunedModels/my-example-model-apbm8oqbvuv2` you can call it with: -```js -const llmResponse = await generate({ +```ts +const ai = genkit({ + plugins: [googleAI()], +}); + +const llmResponse = await ai.generate({ prompt: `Suggest an item for the menu of fish themed restruant`, - model: gemini15Flash, - config: { + model: gemini15Flash.withConfig({ version: "tunedModels/my-example-model-apbm8oqbvuv2", - }, + }), }); -``` \ No newline at end of file +``` diff --git a/docs/plugins/ollama.md b/docs/plugins/ollama.md index 37612e186..93ed0ecc5 100644 --- a/docs/plugins/ollama.md +++ b/docs/plugins/ollama.md @@ -11,8 +11,8 @@ npm i --save genkitx-ollama ## Configuration -This plugin requires that you first install and run ollama server. You can follow -the instructions on: [https://ollama.com/download](https://ollama.com/download) +This plugin requires that you first install and run the Ollama server. You can +follow the instructions on: https://ollama.com/download You can use the Ollama CLI to download the model you are interested in. For example: @@ -21,9 +21,9 @@ example: ollama pull gemma ``` -To use the plugin, specify it when you call genkit: +To use this plugin, specify it when you initialize Genkit: -```typescript +```ts import { genkit } from 'genkit'; import { ollama } from 'genkitx-ollama'; @@ -33,10 +33,10 @@ const ai = genkit({ models: [ { name: 'gemma', - type: 'generate', // Options: 'chat' | 'generate' | + type: 'generate', // type: 'chat' | 'generate' | undefined }, ], - serverAddress: 'http://127.0.0.1:11434', // default serverAddress to use + serverAddress: 'http://127.0.0.1:11434', // default local address }), ], }); @@ -44,12 +44,13 @@ const ai = genkit({ ### Authentication -If you would like to access remote deployments of ollama that require custom headers (static, -such as API keys, or dynamic, such as auth headers), you can specify those in the ollama config plugin: +If you would like to access remote deployments of Ollama that require custom +headers (static, such as API keys, or dynamic, such as auth headers), you can +specify those in the Ollama config plugin: Static headers: -```js +```ts ollama({ models: [{ name: 'gemma'}], requestHeaders: { @@ -59,20 +60,20 @@ ollama({ }), ``` -You can also dynamically set headers per request. Here's an example of how to set an ID token using -the Google Auth library: +You can also dynamically set headers per request. Here's an example of how to +set an ID token using the Google Auth library: -```js +```ts import { GoogleAuth } from 'google-auth-library'; -import { ollama, OllamaPluginParams } from 'genkitx-ollama'; -import { genkit, isDevEnv } from '@genkit-ai/core'; +import { ollama } from 'genkitx-ollama'; +import { genkit } from 'genkit'; const ollamaCommon = { models: [{ name: 'gemma:2b' }] }; const ollamaDev = { ...ollamaCommon, serverAddress: 'http://127.0.0.1:11434', -} as OllamaPluginParams; +}; const ollamaProd = { ...ollamaCommon, @@ -81,11 +82,11 @@ const ollamaProd = { const headers = await fetchWithAuthHeader(params.serverAddress); return { Authorization: headers['Authorization'] }; }, -} as OllamaPluginParams; +}; const ai = genkit({ plugins: [ - ollama(isDevEnv() ? ollamaDev : ollamaProd), + ollama(process.env.NODE_ENV === 'development' ? ollamaDev : ollamaProd), ], }); @@ -117,34 +118,9 @@ async function getIdTokenClient(url: string) { This plugin doesn't statically export model references. Specify one of the models you configured using a string identifier: -```js +```ts const llmResponse = await ai.generate({ - model: 'ollama/gemma:2b', + model: 'ollama/gemma', prompt: 'Tell me a joke.', }); ``` - -## Embedders -The Ollama plugin supports embeddings, which can be used for similarity searches and other NLP tasks. - -```typescript -const ai = genkit({ - plugins: [ - ollama({ - serverAddress: 'http://localhost:11434', - embedders: [{ name: 'nomic-embed-text', dimensions: 768 }], - }), - ], -}); - -async function getEmbedding() { - const embedding = await ai.embed({ - embedder: 'ollama/nomic-embed-text', - content: 'Some text to embed!', - }) - - return embedding; -} - -getEmbedding().then((e) => console.log(e)) -``` \ No newline at end of file diff --git a/docs/plugins/pinecone.md b/docs/plugins/pinecone.md index c90fbea83..957e02b31 100644 --- a/docs/plugins/pinecone.md +++ b/docs/plugins/pinecone.md @@ -1,6 +1,6 @@ # Pinecone plugin -The Pinecone plugin provides indexer and retriever implementatons that use the +The Pinecone plugin provides indexer and retriever implementations that use the [Pinecone](https://www.pinecone.io/) cloud vector database. ## Installation @@ -11,21 +11,21 @@ npm i --save genkitx-pinecone ## Configuration -To use this plugin, specify it when you call `configureGenkit()`: +To use this plugin, specify it when you initialize Genkit: -```js +```ts +import { genkit } from 'genkit'; import { pinecone } from 'genkitx-pinecone'; -export default configureGenkit({ +const ai = genkit({ plugins: [ pinecone([ { indexId: 'bob-facts', - embedder: textEmbeddingGecko, + embedder: textEmbedding004, }, ]), ], - // ... }); ``` @@ -34,51 +34,48 @@ You must specify a Pinecone index ID and the embedding model you want to use. In addition, you must configure Genkit with your Pinecone API key. There are two ways to do this: -- Set the `PINECONE_API_KEY` environment variable. +* Set the `PINECONE_API_KEY` environment variable. +* Specify it in the `clientParams` optional parameter: -- Specify it in the `clientParams` optional parameter: + ```ts + clientParams: { + apiKey: ..., + } + ``` - ```js - clientParams: { - apiKey: ..., - } - ``` - - The value of this parameter is a `PineconeConfiguration` object, which gets - passed to the Pinecone client; you can use it to pass any parameter the client - supports. + The value of this parameter is a `PineconeConfiguration` object, which gets passed to the Pinecone client; you can use it to pass any parameter the client supports. ## Usage Import retriever and indexer references like so: -```js +```ts import { pineconeRetrieverRef } from 'genkitx-pinecone'; import { pineconeIndexerRef } from 'genkitx-pinecone'; ``` -Then, pass the references to `retrieve()` and `index()`: +Then, use these references with `ai.retrieve()` and `ai.index()`: -```js +```ts // To use the index you configured when you loaded the plugin: -let docs = await retrieve({ retriever: pineconeRetrieverRef, query }); +let docs = await ai.retrieve({ retriever: pineconeRetrieverRef, query }); // To specify an index: export const bobFactsRetriever = pineconeRetrieverRef({ indexId: 'bob-facts', }); -docs = await retrieve({ retriever: bobFactsRetriever, query }); +docs = await ai.retrieve({ retriever: bobFactsRetriever, query }); ``` -```js +```ts // To use the index you configured when you loaded the plugin: -await index({ indexer: pineconeIndexerRef, documents }); +await ai.index({ indexer: pineconeIndexerRef, documents }); // To specify an index: export const bobFactsIndexer = pineconeIndexerRef({ indexId: 'bob-facts', }); -await index({ indexer: bobFactsIndexer, documents }); +await ai.index({ indexer: bobFactsIndexer, documents }); ``` See the [Retrieval-augmented generation](../rag.md) page for a general diff --git a/docs/plugins/vertex-ai.md b/docs/plugins/vertex-ai.md index abd6662df..926227caa 100644 --- a/docs/plugins/vertex-ai.md +++ b/docs/plugins/vertex-ai.md @@ -2,20 +2,20 @@ The Vertex AI plugin provides interfaces to several AI services: -- [Google generative AI models](https://cloud.google.com/vertex-ai/generative-ai/docs/): - - Gemini text generation - - Imagen2 image generation - - Text embedding generation -- A subset of evaluation metrics through the Vertex AI [Rapid Evaluation API](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/evaluation): - - [BLEU](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#bleuinput) - - [ROUGE](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#rougeinput) - - [Fluency](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#fluencyinput) - - [Safety](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#safetyinput) - - [Groundeness](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#groundednessinput) - - [Summarization Quality](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#summarizationqualityinput) - - [Summarization Helpfulness](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#summarizationhelpfulnessinput) - - [Summarization Verbosity](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#summarizationverbosityinput) -- [Vector Search](https://cloud.google.com/vertex-ai/docs/vector-search/overview) +* [Google generative AI models](https://cloud.google.com/vertex-ai/generative-ai/docs/): + * Gemini text generation + * Imagen2 image generation + * Text embedding generation +* A subset of evaluation metrics through the Vertex AI [Rapid Evaluation API](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/evaluation): + * [BLEU](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#bleuinput) + * [ROUGE](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#rougeinput) + * [Fluency](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#fluencyinput) + * [Safety](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#safetyinput) + * [Groundeness](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#groundednessinput) + * [Summarization Quality](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#summarizationqualityinput) + * [Summarization Helpfulness](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#summarizationhelpfulnessinput) + * [Summarization Verbosity](https://cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations/evaluateInstances#summarizationverbosityinput) +* [Vector Search](https://cloud.google.com/vertex-ai/docs/vector-search/overview) ## Installation @@ -23,59 +23,38 @@ The Vertex AI plugin provides interfaces to several AI services: npm i --save @genkit-ai/vertexai ``` -If you want to locally run flows that use this plugin, you also need the -[Google Cloud CLI tool](https://cloud.google.com/sdk/docs/install) installed. +If you want to locally run flows that use this plugin, you also need the [Google Cloud CLI tool](https://cloud.google.com/sdk/docs/install) installed. ## Configuration -To use this plugin, specify it when you call `configureGenkit()`: +To use this plugin, specify it when you initialize Genkit: -```js +```ts +import { genkit } from 'genkit'; import { vertexAI } from '@genkit-ai/vertexai'; -export default configureGenkit({ +const ai = genkit({ plugins: [ vertexAI({ projectId: 'your-cloud-project', location: 'us-central1' }), ], - // ... }); ``` -The plugin requires you to specify your Google Cloud project ID, the -[region](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations) -to which you want to make Vertex API requests, and your Google Cloud project -credentials. +The plugin requires you to specify your Google Cloud project ID, the [region](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations) to which you want to make Vertex API requests, and your Google Cloud project credentials. -- You can specify your Google Cloud project ID either by setting `projectId` in - the `vertexAI()` configuration or by setting the `GCLOUD_PROJECT` environment - variable. If you're running your flow from a Google Cloud environment (Cloud - Functions, Cloud Run, and so on), `GCLOUD_PROJECT` is automatically set to the - project ID of the environment. +* You can specify your Google Cloud project ID either by setting `projectId` in the `vertexAI()` configuration or by setting the `GCLOUD_PROJECT` environment variable. If you're running your flow from a Google Cloud environment (Cloud Functions, Cloud Run, and so on), `GCLOUD_PROJECT` is automatically set to the project ID of the environment. +* You can specify the API location either by setting `location` in the `vertexAI()` configuration or by setting the `GCLOUD_LOCATION` environment variable. +* To provide API credentials, you need to set up Google Cloud Application Default Credentials. + 1. To specify your credentials: + * If you're running your flow from a Google Cloud environment (Cloud Functions, Cloud Run, and so on), this is set automatically. + * On your local dev environment, do this by running: -- You can specify the API location either by setting `location` in the - `vertexAI()` configuration or by setting the `GCLOUD_LOCATION` environment - variable. + ```posix-terminal + gcloud auth application-default login + ``` -- To provide API credentials, you need to set up Google Cloud Application - Default Credentials. - - 1. To specify your credentials: - - - If you're running your flow from a Google Cloud environment (Cloud - Functions, Cloud Run, and so on), this is set automatically. - - - On your local dev environment, do this by running: - - ```posix-terminal - gcloud auth application-default login - ``` - - - For other environments, see the [Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc) - docs. - - 1. In addition, make sure the account is granted the Vertex AI User IAM role - (`roles/aiplatform.user`). See the Vertex AI [access control](https://cloud.google.com/vertex-ai/generative-ai/docs/access-control) - docs. + * For other environments, see the [Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc) docs. + 2. In addition, make sure the account is granted the Vertex AI User IAM role (`roles/aiplatform.user`). See the Vertex AI [access control](https://cloud.google.com/vertex-ai/generative-ai/docs/access-control) docs. ## Usage @@ -83,31 +62,37 @@ credentials. This plugin statically exports references to its supported generative AI models: -```js -import { gemini15Flash, gemini15Pro, imagen2 } from '@genkit-ai/vertexai'; +```ts +import { gemini15Flash, gemini15Pro, imagen3 } from '@genkit-ai/vertexai'; ``` -You can use these references to specify which model `generate()` uses: +You can use these references to specify which model `ai.generate()` uses: -```js -const llmResponse = await generate({ +```ts +const ai = genkit({ + plugins: [vertexAI({ projectId: 'your-cloud-project', location: 'us-central1' })], +}); + +const llmResponse = await ai.generate({ model: gemini15Flash, prompt: 'What should I do when I visit Melbourne?', }); ``` -This plugin also supports grounding Gemini text responses using -[Google Search](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/ground-gemini#web-ground-gemini) -or [your own data](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/ground-gemini#private-ground-gemini). +This plugin also supports grounding Gemini text responses using [Google Search](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/ground-gemini#web-ground-gemini) or [your own data](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/ground-gemini#private-ground-gemini). Important: Vertex AI charges a fee for grounding requests in addition to the cost of making LLM requests. See the [Vertex AI pricing](https://cloud.google.com/vertex-ai/generative-ai/pricing) page and be sure you understand grounding request pricing before you use this feature. Example: -```js -await generate({ +```ts +const ai = genkit({ + plugins: [vertexAI({ projectId: 'your-cloud-project', location: 'us-central1' })], +}); + +await ai.generate({ model: gemini15Flash, - prompt: ..., + prompt: '...', config: { googleSearchRetrieval: { disableAttribution: true, @@ -124,22 +109,20 @@ await generate({ }) ``` -This plugin also statically exports a reference to the Gecko text embedding -model: +This plugin also statically exports a reference to the Gecko text embedding model: -```js -import { textEmbeddingGecko } from '@genkit-ai/vertexai'; +```ts +import { textEmbedding004 } from '@genkit-ai/vertexai'; ``` -You can use this reference to specify which embedder an indexer or retriever -uses. For example, if you use Chroma DB: +You can use this reference to specify which embedder an indexer or retriever uses. For example, if you use Chroma DB: -```js -configureGenkit({ +```ts +const ai = genkit({ plugins: [ chroma([ { - embedder: textEmbeddingGecko, + embedder: textEmbedding004, collectionName: 'my-collection', }, ]), @@ -149,19 +132,26 @@ configureGenkit({ Or you can generate an embedding directly: -```js -// import { embed, EmbedderArgument } from '@genkit-ai/ai/embedder'; -const embedding = await embed({ - embedder: textEmbeddingGecko, +```ts +const ai = genkit({ + plugins: [vertexAI({ projectId: 'your-cloud-project', location: 'us-central1' })], +}); + +const embedding = await ai.embed({ + embedder: textEmbedding004, content: 'How many widgets do you have in stock?', }); ``` Imagen3 model allows generating images from user prompt: -```js +```ts import { imagen3 } from '@genkit-ai/vertexai'; +const ai = genkit({ + plugins: [vertexAI({ projectId: 'your-cloud-project', location: 'us-central1' })], +}); + const response = await ai.generate({ model: imagen3, output: { format: 'media' }, @@ -173,7 +163,11 @@ return response.media(); and even advanced editing of existing images: -```js +```ts +const ai = genkit({ + plugins: [vertexAI({ projectId: 'your-cloud-project', location: 'us-central1' })], +}); + const baseImg = fs.readFileSync('base.png', { encoding: 'base64' }); const maskImg = fs.readFileSync('mask.png', { encoding: 'base64' }); @@ -198,7 +192,7 @@ const response = await ai.generate({ return response.media(); ``` -Refer to (Imagen model documentation)[https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/imagen-api#edit_images_2] for more detailed options. +Refer to [Imagen model documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/imagen-api#edit_images_2) for more detailed options. #### Anthropic Claude 3 on Vertex AI Model Garden @@ -206,7 +200,8 @@ If you have access to Claude 3 models ([haiku](https://console.cloud.google.com/ Here's sample configuration for enabling Vertex AI Model Garden models: -```js +```ts +import { genkit } from 'genkit'; import { vertexAI, claude3Haiku, @@ -214,7 +209,7 @@ import { claude3Opus, } from '@genkit-ai/vertexai'; -export default configureGenkit({ +const ai = genkit({ plugins: [ vertexAI({ location: 'us-central1', @@ -228,8 +223,8 @@ export default configureGenkit({ Then use them as regular models: -```js -const llmResponse = await generate({ +```ts +const llmResponse = await ai.generate({ model: claude3Sonnet, prompt: 'What should I do when I visit Melbourne?', }); @@ -241,10 +236,11 @@ First you'll need to enable [Llama 3.1 API Service](https://console.cloud.google Here's sample configuration for Llama 3.1 405b in Vertex AI plugin: -```js +```ts +import { genkit } from 'genkit'; import { vertexAI, llama31 } from '@genkit-ai/vertexai'; -export default configureGenkit({ +const ai = genkit({ plugins: [ vertexAI({ location: 'us-central1', @@ -258,8 +254,8 @@ export default configureGenkit({ Then use it as regular models: -```js -const llmResponse = await generate({ +```ts +const llmResponse = await ai.generate({ model: llama31, prompt: 'Write a function that adds two numbers together', }); @@ -269,10 +265,11 @@ const llmResponse = await generate({ To use the evaluators from Vertex AI Rapid Evaluation, add an `evaluation` block to your `vertexAI` plugin configuration. -```js +```ts +import { genkit } from 'genkit'; import { vertexAI, VertexAIEvaluationMetricType } from '@genkit-ai/vertexai'; -export default configureGenkit({ +const ai = genkit({ plugins: [ vertexAI({ projectId: 'your-cloud-project', @@ -290,7 +287,6 @@ export default configureGenkit({ }, }), ], - // ... }); ``` @@ -300,60 +296,31 @@ Both evaluators can be run using the `genkit eval:run` command with a compatible ### Indexers and retrievers -The Genkit Vertex AI plugin includes indexer and retriever implementations -backed by the Vertex AI Vector Search service. +The Genkit Vertex AI plugin includes indexer and retriever implementations backed by the Vertex AI Vector Search service. -(See the [Retrieval-augmented generation](../rag.md) page to learn how indexers -and retrievers are used in a RAG implementation.) +(See the [Retrieval-augmented generation](http://../rag.md) page to learn how indexers and retrievers are used in a RAG implementation.) -The Vertex AI Vector Search service is a document index that works alongside the -document store of your choice: the document store contains the content of -documents, and the Vertex AI Vector Search index contains, for each document, -its vector embedding and a reference to the document in the document store. -After your documents are indexed by the Vertex AI Vector Search service, it can -respond to search queries, producing lists of indexes into your document store. +The Vertex AI Vector Search service is a document index that works alongside the document store of your choice: the document store contains the content of documents, and the Vertex AI Vector Search index contains, for each document, its vector embedding and a reference to the document in the document store. After your documents are indexed by the Vertex AI Vector Search service, it can respond to search queries, producing lists of indexes into your document store. -The indexer and retriever implementations provided by the Vertex AI plugin use -either Cloud Firestore or BigQuery as the document store. The plugin also -includes interfaces you can implement to support other document stores. +The indexer and retriever implementations provided by the Vertex AI plugin use either Cloud Firestore or BigQuery as the document store. The plugin also includes interfaces you can implement to support other document stores. -Important: Pricing for Vector Search consists of both a charge for every -gigabyte of data you ingest and an hourly charge for the VMs that host your -deployed indexes. See [Vertex AI pricing](https://cloud.google.com/vertex-ai/pricing#vectorsearch). -This is likely to be most cost-effective when you are serving high volumes of -traffic. Be sure to understand the billing implications the service will have -on your project before using it. +Important: Pricing for Vector Search consists of both a charge for every gigabyte of data you ingest and an hourly charge for the VMs that host your deployed indexes. See [Vertex AI pricing](https://cloud.google.com/vertex-ai/pricing#vectorsearch). This is likely to be most cost-effective when you are serving high volumes of traffic. Be sure to understand the billing implications the service will have on your project before using it. To use Vertex AI Vector Search: -1. Choose an embedding model. This model is responsible for creating vector - embeddings from text. Advanced users might use an embedding model optimized - for their particular data sets, but for most users, Vertex AI's - `text-embedding-004` model is a good choice for English text and the - `text-multilingual-embedding-002` model is good for multilingual text. - -1. In the [Vector Search](https://console.cloud.google.com/vertex-ai/matching-engine/indexes) - section of the Google Cloud console, create a new index. The most important - settings are: - - - **Dimensions:** Specify the dimensionality of the vectors produced by your - chosen embedding model. The `text-embedding-004` and - `text-multilingual-embedding-002` models produce vectors of 768 - dimensions. - - - **Update method:** Select streaming updates. +1. Choose an embedding model. This model is responsible for creating vector embeddings from text. Advanced users might use an embedding model optimized for their particular data sets, but for most users, Vertex AI's `text-embedding-004` model is a good choice for English text and the `text-multilingual-embedding-002` model is good for multilingual text. +2. In the [Vector Search](https://console.cloud.google.com/vertex-ai/matching-engine/indexes) section of the Google Cloud console, create a new index. The most important settings are: + * **Dimensions:** Specify the dimensionality of the vectors produced by your chosen embedding model. The `text-embedding-004` and `text-multilingual-embedding-002` models produce vectors of 768 dimensions. + * **Update method:** Select streaming updates. After you create the index, deploy it to a standard (public) endpoint. -1. Get a document indexer and retriever for the document store you want to use: +3. Get a document indexer and retriever for the document store you want to use: **Cloud Firestore** - ```js - import { - getFirestoreDocumentIndexer, - getFirestoreDocumentRetriever - } from '@genkit-ai/vertexai'; + ```ts + import { getFirestoreDocumentIndexer, getFirestoreDocumentRetriever } from '@genkit-ai/vertexai'; import { initializeApp } from 'firebase-admin/app'; import { getFirestore } from 'firebase-admin/firestore'; @@ -361,40 +328,32 @@ To use Vertex AI Vector Search: initializeApp({ projectId: PROJECT_ID }); const db = getFirestore(); - const firestoreDocumentRetriever: DocumentRetriever = - getFirestoreDocumentRetriever(db, FIRESTORE_COLLECTION); - const firestoreDocumentIndexer: DocumentIndexer = - getFirestoreDocumentIndexer(db, FIRESTORE_COLLECTION); + const firestoreDocumentRetriever = getFirestoreDocumentRetriever(db, FIRESTORE_COLLECTION); + const firestoreDocumentIndexer = getFirestoreDocumentIndexer(db, FIRESTORE_COLLECTION); ``` **BigQuery** - ```js - import { - getBigQueryDocumentIndexer, - getBigQueryDocumentRetriever, - } from '@genkit-ai/vertexai'; + ```ts + import { getBigQueryDocumentIndexer, getBigQueryDocumentRetriever } from '@genkit-ai/vertexai'; import { BigQuery } from '@google-cloud/bigquery'; const bq = new BigQuery({ projectId: PROJECT_ID }); - const bigQueryDocumentRetriever: DocumentRetriever = - getBigQueryDocumentRetriever(bq, BIGQUERY_TABLE, BIGQUERY_DATASET); - const bigQueryDocumentIndexer: DocumentIndexer = - getBigQueryDocumentIndexer(bq, BIGQUERY_TABLE, BIGQUERY_DATASET); + const bigQueryDocumentRetriever = getBigQueryDocumentRetriever(bq, BIGQUERY_TABLE, BIGQUERY_DATASET); + const bigQueryDocumentIndexer = getBigQueryDocumentIndexer(bq, BIGQUERY_TABLE, BIGQUERY_DATASET); ``` **Other** - To support other documents stores you can provide your own implementations - of `DocumentRetriever` and `DocumentIndexer`: + To support other documents stores you can provide your own implementations of `DocumentRetriever` and `DocumentIndexer`: - ```js - const myDocumentRetriever: DocumentRetriever = async (neighbors: Neighbor[]) => { + ```ts + const myDocumentRetriever = async (neighbors) => { // Return the documents referenced by `neighbors`. // ... } - const myDocumentIndexer: DocumentIndexer = async (documents: Document[]) => { + const myDocumentIndexer = async (documents) => { // Add `documents` to storage. // ... } @@ -402,13 +361,13 @@ To use Vertex AI Vector Search: For an example, see [Sample Vertex AI Plugin Retriever and Indexer with Local File](https://github.com/firebase/genkit/tree/main/js/testapps/vertexai-vector-search-custom). -1. Add a `vectorSearchOptions` block to your `vertexAI` plugin configuration: +4. Add a `vectorSearchOptions` block to your `vertexAI` plugin configuration: - ```js - import { configureGenkit } from '@genkit-ai/core'; + ```ts + import { genkit } from 'genkit'; import { vertexAI, textEmbedding004 } from '@genkit-ai/vertexai'; - configureGenkit({ + const ai = genkit({ plugins: [ vertexAI({ projectId: PROJECT_ID, @@ -429,42 +388,31 @@ To use Vertex AI Vector Search: }); ``` - Provide the embedder you chose in the first step and the document indexer - and retriever you created in the previous step. + Provide the embedder you chose in the first step and the document indexer and retriever you created in the previous step. - To configure the plugin to use the Vector Search index you created earlier, - you need to provide several values, which you can find in the Vector Search - section of the Google Cloud console: + To configure the plugin to use the Vector Search index you created earlier, you need to provide several values, which you can find in the Vector Search section of the Google Cloud console: - - `indexId`: listed on the [Indexes](https://console.cloud.google.com/vertex-ai/matching-engine/indexes) tab - - `indexEndpointId`: listed on the [Index Endpoints](https://console.cloud.google.com/vertex-ai/matching-engine/index-endpoints) tab - - `deployedIndexId` and `publicDomainName`: listed on the "Deployed index - info" page, which you can open by clicking the name of the deployed index - on either of the tabs mentioned earlier + * `indexId`: listed on the [Indexes](https://console.cloud.google.com/vertex-ai/matching-engine/indexes) tab + * `indexEndpointId`: listed on the [Index Endpoints](https://console.cloud.google.com/vertex-ai/matching-engine/index-endpoints) tab + * `deployedIndexId` and `publicDomainName`: listed on the "Deployed index info" page, which you can open by clicking the name of the deployed index on either of the tabs mentioned earlier +5. Now that everything is configured, you can use the indexer and retriever in your Genkit application: -1. Now that everything is configured, import retriever and indexer references - from the plugin: - - ```js + ```ts import { vertexAiIndexerRef, vertexAiRetrieverRef, } from '@genkit-ai/vertexai'; - ``` - Pass the references to `index()` and `retrieve()`: + // ... inside your flow function: - ```js - await index({ + await ai.index({ indexer: vertexAiIndexerRef({ indexId: VECTOR_SEARCH_INDEX_ID, }), documents, }); - ``` - ```js - const res = await retrieve({ + const res = await ai.retrieve({ retriever: vertexAiRetrieverRef({ indexId: VECTOR_SEARCH_INDEX_ID, }), @@ -474,6 +422,6 @@ To use Vertex AI Vector Search: See the code samples for: -- [Vertex Vector Search + BigQuery](https://github.com/firebase/genkit/tree/main/js/testapps/vertexai-vector-search-bigquery) -- [Vertex Vector Search + Firestore](https://github.com/firebase/genkit/tree/main/js/testapps/vertexai-vector-search-firestore) -- [Vertex Vector Search + a custom DB](https://github.com/firebase/genkit/tree/main/js/testapps/vertexai-vector-search-custom) +* [Vertex Vector Search + BigQuery](https://github.com/firebase/genkit/tree/main/js/testapps/vertexai-vector-search-bigquery) +* [Vertex Vector Search + Firestore](https://github.com/firebase/genkit/tree/main/js/testapps/vertexai-vector-search-firestore) +* [Vertex Vector Search + a custom DB](https://github.com/firebase/genkit/tree/main/js/testapps/vertexai-vector-search-custom) \ No newline at end of file