From c46ad0bf389db6cb5b8f96ada4a2e11870510edd Mon Sep 17 00:00:00 2001 From: dmail Date: Wed, 5 Feb 2025 10:39:09 -0800 Subject: [PATCH 1/8] Docs: Edits to Auth doc for 1.0 GA --- docs/firebase.md | 102 ++++++++++++++++++++++++----------------------- 1 file changed, 52 insertions(+), 50 deletions(-) diff --git a/docs/firebase.md b/docs/firebase.md index 16ade8e55..1f9b7a484 100644 --- a/docs/firebase.md +++ b/docs/firebase.md @@ -1,10 +1,10 @@ # Deploy flows using Cloud Functions for Firebase -Cloud Functions for Firebase has an `onCallGenkit` method that allows you to +Cloud Functions for Firebase has an `onCallGenkit` method that lets you quickly create a [callable function](https://firebase.google.com/docs/functions/callable?gen=2nd) -with a Genkit action (e.g. a Flow). These functions can be called with `genkit/beta/client` or the -[Functions client SDK](https://firebase.google.com/docs/functions/callable?gen=2nd#call_the_function), -which will automatically add auth info. +with a Genkit action (e.g. a Flow). These functions can be called using +`genkit/beta/client`or the [Functions clientSDK](https://firebase.google.com/docs/functions/callable?gen=2nd#call_the_function), +which automatically adds auth info. ## Before you begin @@ -14,7 +14,7 @@ which will automatically add auth info. * It would be helpful, but not required, if you've already used Cloud Functions for Firebase before. -## 1. Set up a Firebase project +## 1. Set up a Firebase project {:#setup} If you don't already have a Firebase project with TypeScript Cloud Functions set up, follow these steps: @@ -57,17 +57,17 @@ up, follow these steps: in TypeScript, but you can also deploy your Genkit flows if you're using JavaScript. -## 2. Wrap the Flow in onCallGenkit +## 2. Wrap the Flow in onCallGenkit {:#wrap-flow} After you've set up a Firebase project with Cloud Functions, you can copy or write flow definitions in the project’s `functions/src` directory, and export them in `index.ts`. -For your flows to be deployable, you will need to wrap them in `onCallGenkit`. +For your flows to be deployable, you need to wrap them in `onCallGenkit`. This method has all the features of the normal `onCall`. It automatically supports both streaming and JSON responses. -Suppose you have the following flow: +Suppose you have the following flow: ```ts const generatePoemFlow = ai.defineFlow( @@ -83,7 +83,7 @@ const generatePoemFlow = ai.defineFlow( ); ``` -You can expose this Flow as a Callable Function using `onCallGenkit`: +You can expose this flow as a callable function using `onCallGenkit`: ```ts import { onCallGenkit } from 'firebase-functions/https'; @@ -94,8 +94,8 @@ export generatePoem = onCallGenkit(generatePoemFlow); ### Define an authorization policy All deployed flows, whether deployed to Firebase or not, should have an -authorization policy; without one, your potentially-expensive generative AI -flows would be invocable by anyone. To define an authorization policy, use the +authorization policy; without one, anyone can invoke your potentially-expensive +generative AI flows. To define an authorization policy, use the `authPolicy` parameter in `onCallGenkit`: ```ts @@ -105,7 +105,7 @@ export const generatePoem = onCallGenkit({ ``` This sample uses a manual function as its auth policy. In addition, the https -library exports the helpers `signedIn()` and `hasClaim()`. Here is the same code +library exports the `signedIn()` and `hasClaim()` helpers. Here is the same code using one of those helpers: ```ts @@ -116,7 +116,7 @@ export const generatePoem = onCallGenkit({ }, generatePoemFlow); ``` -### Make API credentials available to deployed flows +### Make API credentials available to deployed flows Once deployed, your flows need some way to authenticate with any remote services they rely on. Most flows will at a minimum need credentials for accessing the @@ -127,59 +127,61 @@ chose: - {Gemini (Google AI)} - 1. Make sure Google AI is [available in your - region](https://ai.google.dev/available_regions). + 1. Make sure Google AI is [available in your + region](https://ai.google.dev/available_regions). - 1. [Generate an API key](https://aistudio.google.com/app/apikey) for the - Gemini API using Google AI Studio. + 1. [Generate an API key](https://aistudio.google.com/app/apikey) for the + Gemini API using Google AI Studio. - 1. Store your API key in Cloud Secret Manager: + 1. Store your API key in Cloud Secret Manager: - ```posix-terminal - firebase functions:secrets:set GOOGLE_GENAI_API_KEY - ``` + ```posix-terminal + firebase functions:secrets:set GOOGLE_GENAI_API_KEY + ``` - This step is important to prevent accidentally leaking your API key, which - grants access to a potentially metered service. + This step is important to prevent accidentally leaking your API key, which + grants access to a potentially metered service. - See [Store and access sensitive configuration information](/docs/functions/config-env?gen=2nd#secret-manager) - for more information on managing secrets. + See [Store and access sensitive configuration information](/docs/functions/config-env?gen=2nd#secret-manager) + for more information on managing secrets. - 1. Edit `src/index.ts` and add the following after the existing imports: + 1. Edit `src/index.ts` and add the following after the existing imports: - ```ts - import {defineSecret} from "firebase-functions/params"; - const googleAIapiKey = defineSecret("GOOGLE_GENAI_API_KEY"); - ``` + ```ts + import {defineSecret} from "firebase-functions/params"; + const googleAIapiKey = defineSecret("GOOGLE_GENAI_API_KEY"); + ``` - Then, in the flow definition, declare that the cloud function needs access - to this secret value: + Then, in the flow definition, declare that the cloud function needs access + to this secret value: - ```ts - export const generatePoem = onCallGenkit({ - secrets: [googleAIapiKey] - }, generatePoemFlow); - ``` + ```ts + export const generatePoem = onCallGenkit({ + secrets: [googleAIapiKey] + }, generatePoemFlow); + ``` Now, when you deploy this function, your API key will be stored in Cloud Secret Manager, and available from the Cloud Functions environment. - {Gemini (Vertex AI)} - 1. In the Cloud console, [Enable the Vertex AI - API](https://console.cloud.google.com/apis/library/aiplatform.googleapis.com?project=_) - for your Firebase project. + 1. In the Cloud console, [Enable the Vertex AI + API](https://console.cloud.google.com/apis/library/aiplatform.googleapis.com?project=_) + for your Firebase project. - 1. On the [IAM](https://console.cloud.google.com/iam-admin/iam?project=_) - page, ensure that the **Default compute service account** is granted the - **Vertex AI User** role. + 1. On the [IAM](https://console.cloud.google.com/iam-admin/iam?project=_) + page, ensure that the **Default compute service account** is granted the + **Vertex AI User** role. The only secret you need to set up for this tutorial is for the model provider, but in general, you must do something similar for each service your flow uses. ### Add App Check enforcement + [Firebase App Check](https://firebase.google.com/docs/app-check) uses native attestation -to verify that your API is only being called by your application. onCallGenkit supports App Check enforcement declaratively. +to verify that your API is only being called by your application. +`onCallGenkit` supports App Check enforcement declaratively. ```ts export const generatePoem = onCallGenkit({ @@ -191,7 +193,7 @@ export const generatePoem = onCallGenkit({ }, generatePoemFlow); ``` -### Set a CORS policy +### Set a CORS policy Callable functions default to allowing any domain to call your function. If you would like to customize this, use the `cors` option. @@ -232,7 +234,7 @@ export const generateFlow = onCallGenkit({ }, generatePoemFlow); ``` -## 3. Deploy flows to Firebase +## 3. Deploy flows to Firebase {:#deploy-flows} After you've defined flows using `onCallGenkit`, you can deploy them as you would deploy other Cloud Functions: @@ -351,7 +353,7 @@ Open the web app by visiting the URL printed by the `deploy` command. The app requires you to sign in with a Google account, after which you can initiate endpoint requests. -## Optional: Run flows in the developer UI +## Optional: Run flows in the developer UI {:#run-flows} You can run flows defined using `onCallGenkit` in the developer UI, exactly the same way as you run flows defined using `defineFlow`, so there's no need to switch @@ -364,7 +366,7 @@ npx genkit start -- npx tsx --watch src/index.ts ``` or - + ```posix-terminal cd $PROJECT_ROOT/functions @@ -373,7 +375,7 @@ npm run genkit:start You can now navigate to the URL printed by the `genkit start` command to access. -## Optional: Developing using Firebase Local Emulator Suite +## Optional: Developing using Firebase Local Emulator Suite {:#firebase-local} Firebase offers a [suite of emulators for local development](/docs/emulator-suite), which you can @@ -392,4 +394,4 @@ the Dev UI). To see traces from Firestore in the Dev UI you can navigate to the Inspect tab and toggle the "Dev/Prod" switch. When toggled to "prod" it will be loading -traces from firestore. +traces from firestore. \ No newline at end of file From 3c033140edc1858d736363196d753e704dada290 Mon Sep 17 00:00:00 2001 From: dmail Date: Wed, 5 Feb 2025 11:00:06 -0800 Subject: [PATCH 2/8] Docs: Edits to Firebase doc for 1.0 GA --- docs/firebase.md | 69 ++++++++++++++++++++++++------------------------ 1 file changed, 34 insertions(+), 35 deletions(-) diff --git a/docs/firebase.md b/docs/firebase.md index 1f9b7a484..b30c8c239 100644 --- a/docs/firebase.md +++ b/docs/firebase.md @@ -53,7 +53,7 @@ up, follow these steps: firebase init genkit ``` - The rest of this page assumes that you've selected to write your functions + The rest of this page assumes that you've decided to write your functions in TypeScript, but you can also deploy your Genkit flows if you're using JavaScript. @@ -64,8 +64,8 @@ write flow definitions in the project’s `functions/src` directory, and export them in `index.ts`. For your flows to be deployable, you need to wrap them in `onCallGenkit`. -This method has all the features of the normal `onCall`. It automatically supports -both streaming and JSON responses. +This method has all the features of the normal `onCall`. It automatically +supports both streaming and JSON responses. Suppose you have the following flow: @@ -96,7 +96,7 @@ export generatePoem = onCallGenkit(generatePoemFlow); All deployed flows, whether deployed to Firebase or not, should have an authorization policy; without one, anyone can invoke your potentially-expensive generative AI flows. To define an authorization policy, use the -`authPolicy` parameter in `onCallGenkit`: +`authPolicy` parameter of `onCallGenkit`: ```ts export const generatePoem = onCallGenkit({ @@ -119,7 +119,7 @@ export const generatePoem = onCallGenkit({ ### Make API credentials available to deployed flows Once deployed, your flows need some way to authenticate with any remote services -they rely on. Most flows will at a minimum need credentials for accessing the +they rely on. Most flows need, at a minimum, credentials for accessing the model API service they use. For this example, do one of the following, depending on the model provider you @@ -139,8 +139,8 @@ chose: firebase functions:secrets:set GOOGLE_GENAI_API_KEY ``` - This step is important to prevent accidentally leaking your API key, which - grants access to a potentially metered service. + This step is important to prevent accidentally leaking your API key, + which grants access to a potentially metered service. See [Store and access sensitive configuration information](/docs/functions/config-env?gen=2nd#secret-manager) for more information on managing secrets. @@ -152,8 +152,8 @@ chose: const googleAIapiKey = defineSecret("GOOGLE_GENAI_API_KEY"); ``` - Then, in the flow definition, declare that the cloud function needs access - to this secret value: + Then, in the flow definition, declare that the cloud function needs + access to this secret value: ```ts export const generatePoem = onCallGenkit({ @@ -161,7 +161,7 @@ chose: }, generatePoemFlow); ``` - Now, when you deploy this function, your API key will be stored in Cloud + Now, when you deploy this function, your API key is stored in Cloud Secret Manager, and available from the Cloud Functions environment. - {Gemini (Vertex AI)} @@ -179,9 +179,9 @@ but in general, you must do something similar for each service your flow uses. ### Add App Check enforcement -[Firebase App Check](https://firebase.google.com/docs/app-check) uses native attestation -to verify that your API is only being called by your application. -`onCallGenkit` supports App Check enforcement declaratively. +[Firebase App Check](https://firebase.google.com/docs/app-check) uses a +built-in attestation mechanism to verify that your API is only being called by +your application. `onCallGenkit` supports App Check enforcement declaratively. ```ts export const generatePoem = onCallGenkit({ @@ -195,8 +195,9 @@ export const generatePoem = onCallGenkit({ ### Set a CORS policy -Callable functions default to allowing any domain to call your function. If you would -like to customize this, use the `cors` option. +Callable functions default to allowing any domain to call your function. If you +want to customize the domains that can do this, use the `cors` option. +With proper authentication (especially App Check), CORS is often unnecessary. ```ts export const generatePoem = onCallGenkit({ @@ -204,12 +205,10 @@ export const generatePoem = onCallGenkit({ }, generatePoemFlow); ``` -With proper authentication (especially App Check), CORS is often unnecessary. - ### Complete example -After you've made all of the changes described above, your deployable flow will -look something like the following example: +After you've made all of the changes described earlier, your deployable flow +looks something like the following example: ```ts import { genkit } from 'genkit'; @@ -236,8 +235,8 @@ export const generateFlow = onCallGenkit({ ## 3. Deploy flows to Firebase {:#deploy-flows} -After you've defined flows using `onCallGenkit`, you can deploy them as you would -deploy other Cloud Functions: +After you've defined flows using `onCallGenkit`, you can deploy them the same +way you would deploy other Cloud Functions: ```posix-terminal cd $PROJECT_ROOT @@ -245,10 +244,10 @@ cd $PROJECT_ROOT firebase deploy --only functions ``` -You've now deployed the flow as a Cloud Function! But, you won't be able to +You've now deployed the flow as a Cloud Function! But you can't access your deployed endpoint with `curl` or similar, because of the flow's -authorization policy. Continue to the next section to learn how to securely -access the flow. +authorization policy. The next section explains how to securely access the +flow. ## Optional: Try the deployed flow {:#example-client} @@ -261,8 +260,8 @@ app: 1. In the [Authentication](https://console.firebase.google.com/project/_/authentication/providers) - section of the Firebase console, enable the **Google** provider, which you - will use in this example. + section of the Firebase console, enable the **Google** provider, used in + this example. 1. In your project directory, set up Firebase Hosting, where you will deploy the sample app: @@ -355,9 +354,9 @@ endpoint requests. ## Optional: Run flows in the developer UI {:#run-flows} -You can run flows defined using `onCallGenkit` in the developer UI, exactly the same -way as you run flows defined using `defineFlow`, so there's no need to switch -between the two between deployment and development. +You can run flows defined using `onCallGenkit` in the developer UI, exactly the +same way as you run flows defined using `defineFlow`, so there's no need to +switch between the two between deployment and development. ```posix-terminal cd $PROJECT_ROOT/functions @@ -381,17 +380,17 @@ Firebase offers a [suite of emulators for local development](/docs/emulator-suite), which you can use with Genkit. -To use the Genkit Dev UI with the Firebase Emulator Suite, start the Firebase emulators -like this: +To use the Genkit Dev UI with the Firebase Emulator Suite, start the Firebase +emulators as follows: ```posix-terminal npx genkit start -- firebase emulators:start --inspect-functions ``` -This will run your code in the emulator and run the Genkit framework in -development mode, which launches and exposes the Genkit reflection API (but not +This command runs your code in the emulator, and runs the Genkit framework in +development mode. This launches and exposes the Genkit reflection API (but not the Dev UI). -To see traces from Firestore in the Dev UI you can navigate to the Inspect tab -and toggle the "Dev/Prod" switch. When toggled to "prod" it will be loading +To see traces from Firestore in the Dev UI, you can navigate to the _Inspect_ +tab and toggle the *Dev/Prod* switch. When toggled to _prod_ it loads traces from firestore. \ No newline at end of file From d7813756acc45b6896c7db397023768a29d73042 Mon Sep 17 00:00:00 2001 From: dmail Date: Wed, 5 Feb 2025 11:02:54 -0800 Subject: [PATCH 3/8] Docs: Edits to Firebase doc for 1.0 GA --- docs/flows.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/flows.md b/docs/flows.md index 7eb7b71f3..e4ca89629 100644 --- a/docs/flows.md +++ b/docs/flows.md @@ -109,8 +109,8 @@ Here's an example of a flow that supports streaming: * The `streamSchema` option specifies the type of values your flow streams. This does not necessarily need to be the same type as the `outputSchema`, which is the type of the flow's complete output. -* The second parameter to your flow definition is called "sideChannel". It provides - multiple useful features, such as request context and the `sendChunk` callback. +* The second parameter to your flow definition is called `sideChannel`. It + provides features such as request context and the `sendChunk` callback. The `sendChunk` callback takes a single parameter, of the type specified by `streamSchema`. Whenever data becomes available within your flow, send the data to the output stream by calling this function. @@ -240,8 +240,9 @@ but this section gives brief overviews of your deployment options. ### Cloud Functions for Firebase -To deploy flows with Cloud Functions for Firebase, use the `onCallGenkit` feature of `firebase-functions/https`. -This will wrap your flow in a callable function. You may set an auth policy and configure App Check. +To deploy flows with Cloud Functions for Firebase, use the `onCallGenkit` +feature of `firebase-functions/https`. `onCallGenkit` wraps your flow in a +callable function. You may set an auth policy and configure App Check. ```ts {% includecode github_path="firebase/genkit/js/doc-snippets/src/flows/firebase.ts" region_tag="ex" adjust_indentation="auto" %} From 65e5f8bed0f3ebf4c935365fe75f7e18c8142906 Mon Sep 17 00:00:00 2001 From: dmail Date: Wed, 5 Feb 2025 11:11:02 -0800 Subject: [PATCH 4/8] Docs: Edits to Firebase doc for 1.0 GA --- docs/plugin-authoring-evaluator.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/plugin-authoring-evaluator.md b/docs/plugin-authoring-evaluator.md index 9ee8d218b..2dc87e18c 100644 --- a/docs/plugin-authoring-evaluator.md +++ b/docs/plugin-authoring-evaluator.md @@ -84,10 +84,9 @@ function getDeliciousnessPrompt(ai: Genkit) { Define a function that takes an example that includes `output` as required by the prompt, and scores the result. Genkit testcases include -`input` as -a required field, with `output` and `context` as optional fields. It is the -responsibility of the evaluator to validate that all fields required for -evaluation are present. +`input` as a required field, with `output` and `context` as optional fields. +It is the responsibility of the evaluator to validate that all fields +required for evaluation are present. ```ts import { ModelArgument } from 'genkit'; From 5a82528ee14e1cfda0c139ea84f1a64125445f16 Mon Sep 17 00:00:00 2001 From: dmail Date: Wed, 5 Feb 2025 11:23:41 -0800 Subject: [PATCH 5/8] Docs: Edits to Firebase doc for 1.0 GA --- docs/tool-calling.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tool-calling.md b/docs/tool-calling.md index ec7e3c259..5112ce27a 100644 --- a/docs/tool-calling.md +++ b/docs/tool-calling.md @@ -121,9 +121,9 @@ const getWeather = ai.defineTool( ``` The syntax here looks just like the `defineFlow()` syntax; however, `name`, -`description` and `inputSchema` parameters are required. When writing a tool +`description`, and `inputSchema` parameters are required. When writing a tool definition, take special care with the wording and descriptiveness of these -parameters, as they are vital for the LLM to effectively make use of the +parameters. They are vital for the LLM to make effective use of the available tools. ### Using tools @@ -199,8 +199,8 @@ Genkit will automatically handle the tool call if the LLM needs to use the ### Pause the tool loop by using interrupts By default, Genkit repeatedly calls the LLM until every tool call has been -resolved. You may want to conditionally pause execution in situations where -you want to, for example: +resolved. You can conditionally pause execution in situations where you want +to, for example: * Ask the user a question or display UI. * Confirm a potentially risky action with the user. From c44dd968837d02fded1f5eb4ac9c11f349bf6ffc Mon Sep 17 00:00:00 2001 From: dmail Date: Wed, 5 Feb 2025 15:23:14 -0800 Subject: [PATCH 6/8] Docs: Edits to Firebase doc for 1.0 GA --- docs/cloud-run.md | 9 +-- docs/devtools.md | 2 +- docs/plugins/firebase.md | 122 ++++++++++++++++++++++++++++----------- 3 files changed, 94 insertions(+), 39 deletions(-) diff --git a/docs/cloud-run.md b/docs/cloud-run.md index 5551019a1..e72c8ec76 100644 --- a/docs/cloud-run.md +++ b/docs/cloud-run.md @@ -83,13 +83,14 @@ When you deploy your flows with Cloud Run, you have two options for authorization: - **Cloud IAM-based authorization**: Use Google Cloud's native access management - facilities to gate access to your endpoints. See + facilities to gate access to your endpoints. For information on providing + these credentials, see [Authentication](https://cloud.google.com/run/docs/authenticating/overview) - in the Cloud Run docs for information on providing these credentials. + in the Cloud Run docs. - **Authorization policy defined in code**: Use the authorization policy feature - of Genkit express plugin to verify authorization info using custom code. This is often, - but not necessarily, token-based authorization. + of the Genkit express plugin to verify authorization info using custom code. + This is often, but not necessarily, token-based authorization. If you want to define an authorization policy in code, use the `authPolicy` parameter in the flow definition: diff --git a/docs/devtools.md b/docs/devtools.md index e3bb65656..6cac30096 100644 --- a/docs/devtools.md +++ b/docs/devtools.md @@ -33,7 +33,7 @@ npx genkit --help ### Genkit Developer UI -The Genkit Developer UI is a local web app that allows you to interactively +The Genkit Developer UI is a local web app that lets you interactively work with models, flows, prompts, and other elements in your Genkit project. The Developer UI is able to identify what Genkit components you have defined diff --git a/docs/plugins/firebase.md b/docs/plugins/firebase.md index 735dff917..56defabb0 100644 --- a/docs/plugins/firebase.md +++ b/docs/plugins/firebase.md @@ -3,10 +3,14 @@ use https://github.com/firebase/firebase-tools/blob/master/templates/init/functi # Firebase plugin -The Firebase plugin provides integrations with Firebase services, allowing you to build intelligent and scalable AI applications. Key features include: +The Firebase plugin provides integrations with Firebase services, so you can +build intelligent and scalable AI applications. Key features include: -- **Firestore Vector Store**: Use Firestore for indexing and retrieval with vector embeddings. -- **Telemetry**: Export telemetry to [Google's Cloud operations suite](https://cloud.google.com/products/operations) that powers the Firebase Genkit Monitoring console. +- **Firestore Vector Store**: Use Firestore for indexing and retrieval +with vector embeddings. +- **Telemetry**: Export telemetry to +[Google's Cloud operations suite](https://cloud.google.com/products/operations) that powers the Firebase Genkit +Monitoring console. ## Installation @@ -20,13 +24,19 @@ npm install @genkit-ai/firebase ### Firebase Project Setup -1. All Firebase products require a Firebase project. You can create a new project or enable Firebase in an existing Google Cloud project using the [Firebase console](https://console.firebase.google.com/). -2. If deploying flows with Cloud Functions, [upgrade your Firebase project](https://console.firebase.google.com/project/_/overview?purchaseBillingPlan=metered) to the Blaze plan. -3. If you want to run code locally that exports telemetry, you need the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) tool installed. +1. All Firebase products require a Firebase project. You can create a new + project or enable Firebase in an existing Google Cloud project using the + [Firebase console](https://console.firebase.google.com/). +1. If deploying flows with Cloud functions, + [upgrade your Firebase project](https://console.firebase.google.com/project/_/overview?purchaseBillingPlan=metered) + to the Blaze plan. +1. If you want to run code locally that exports telemetry, you need the + [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) tool installed. ### Firebase Admin SDK Initialization -You must initialize the Firebase Admin SDK in your application. This is not handled automatically by the plugin. +You must initialize the Firebase Admin SDK in your application. +This is not handled automatically by the plugin. @@ -38,32 +48,49 @@ initializeApp({ }); ``` -The plugin requires you to specify your Firebase project ID. You can specify your Firebase project ID in either of the following ways: +The plugin requires you to specify your Firebase project ID. You can specify +your Firebase project ID in either of the following ways: -- Set `projectId` in the `initializeApp()` configuration object as shown in the snippet above. +- Set `projectId` in the `initializeApp()` configuration object as shown +in the snippet above. -- Set 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. +- Set 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. - If you set `GCLOUD_PROJECT`, you can omit the configuration parameter in `initializeApp()`. + If you set `GCLOUD_PROJECT`, you can omit the configuration + parameter in `initializeApp()`. ### Credentials -To provide Firebase credentials, you also need to set up Google Cloud Application Default Credentials. To specify your credentials: +To provide Firebase credentials, you also need to set up Google Cloud +Application Default Credentials. 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. +- If you're running your flow from a Google Cloud environment (Cloud Functions, +- Cloud Run, and so on), this is set automatically. - For other environments: - 1. Generate service account credentials for your Firebase project and download the JSON key file. You can do so on the [Service account](https://console.firebase.google.com/project/_/settings/serviceaccounts/adminsdk) page of the Firebase console. - 2. Set the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to the file path of the JSON file that contains your service account key, or you can set the environment variable `GCLOUD_SERVICE_ACCOUNT_CREDS` to the content of the JSON file. + 1. Generate service account credentials for your Firebase project and + download the JSON key file. You can do so on the + [Service account](https://console.firebase.google.com/project/_/settings/serviceaccounts/adminsdk) + page of the Firebase console. + 1. Set the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to the file + path of the JSON file that contains your service account key, or you can set + the environment variable `GCLOUD_SERVICE_ACCOUNT_CREDS` to the content of the JSON file. ## Features and usage ### Telemetry -Firebase Genkit Monitoring is powered by Google's Cloud operation suite. This requires telemetry related API's to be enabled for your project. Please refer to the [Google Cloud plugin](google-cloud.md#set-up-a-google-cloud-account) documentation for more details. +Firebase Genkit Monitoring is powered by Google's Cloud operation suite. This +requires telemetry related API's to be enabled for your project. Please refer +to the [Google Cloud plugin](google-cloud.md#set-up-a-google-cloud-account) +documentation for more details. -Grant the following roles to the **"Default compute service account"** within the [Google Cloud IAM Console](https://console.cloud.google.com/iam-admin/iam): +Grant the following roles to the **"Default compute service account"** within +the [Google Cloud IAM Console](https://console.cloud.google.com/iam-admin/iam): - **Monitoring Metric Writer** (roles/monitoring.metricWriter) - **Cloud Trace Agent** (roles/cloudtrace.agent) @@ -87,11 +114,18 @@ This plugin shares [configuration options](google-cloud.md#plugin-configuration) You can use Cloud Firestore as a vector store for RAG indexing and retrieval. -This section contains information specific to the `firebase` plugin and Cloud Firestore's vector search feature. See the [Retrieval-augmented generation](/../rag.md) page for a more detailed discussion on implementing RAG using Genkit. +This section contains information specific to the `firebase` plugin and Cloud +Firestore's vector search feature. See the +[Retrieval-augmented generation](/../rag.md) page for a more detailed +discussion on implementing RAG using Genkit. -#### Using GCLOUD_SERVICE_ACCOUNT_CREDS and Firestore +#### Using `GCLOUD_SERVICE_ACCOUNT_CREDS` and Firestore -If you are using service account credentials by passing credentials directly via `GCLOUD_SERVICE_ACCOUNT_CREDS` and are also using Firestore as a vector store, you will need to pass credentials directly to the Firestore instance during initialization or the singleton may be initialized with application default credentials depending on plugin initialization order. +If you are using service account credentials by passing credentials directly +via `GCLOUD_SERVICE_ACCOUNT_CREDS` and are also using Firestore as a vector +store, you need to pass credentials directly to the Firestore instance +during initialization or the singleton may be initialized with application +default credentials depending on plugin initialization order. @@ -111,7 +145,8 @@ if (process.env.GCLOUD_SERVICE_ACCOUNT_CREDS) { #### Define a Firestore retriever -Use `defineFirestoreRetriever()` to create a retriever for Firestore vector-based queries. +Use `defineFirestoreRetriever()` to create a retriever for Firestore +vector-based queries. @@ -136,7 +171,8 @@ const retriever = defineFirestoreRetriever(ai, { #### Retrieve documents -To retrieve documents using the defined retriever, pass the retriever instance and query options to `ai.retrieve`. +To retrieve documents using the defined retriever, pass the retriever instance +and query options to `ai.retrieve`. @@ -167,11 +203,16 @@ The following options can be passed to the `options` field in `ai.retrieve`: ``` - **`collection`**: *(string)* - Override the default collection specified in the retriever configuration. This is useful for querying subcollections or dynamically switching between collections. + Override the default collection specified in the retriever configuration. +- This is useful for querying subcollections or dynamically switching between +- collections. #### Populate Firestore with Embeddings -To populate your Firestore collection, use an embedding generator along with the Admin SDK. For example, the menu ingestion script from the [Retrieval-augmented generation](http://../rag.md) page could be adapted for Firestore in the following way: +To populate your Firestore collection, use an embedding generator along with +the Admin SDK. For example, the menu ingestion script from the +[Retrieval-augmented generation](http://../rag.md) page could be adapted for +Firestore in the following way: @@ -237,11 +278,16 @@ async function extractTextFromPdf(filePath: string) { } ``` -Firestore depends on indexes to provide fast and efficient querying on collections. (Note that "index" here refers to database indexes, and not Genkit's indexer and retriever abstractions.) +Firestore depends on indexes to provide fast and efficient querying on +collections. (Note that "index" here refers to database indexes, and not +Genkit's indexer and retriever abstractions.) -The prior example requires the `embedding` field to be indexed to work. To create the index: +The prior example requires the `embedding` field to be indexed to work. +To create the index: -- Run the `gcloud` command described in the [Create a single-field vector index](https://firebase.google.com/docs/firestore/vector-search?authuser=0#create_and_manage_vector_indexes) section of the Firestore docs. +- Run the `gcloud` command described in the +- [Create a single-field vector index](https://firebase.google.com/docs/firestore/vector-search?authuser=0#create_and_manage_vector_indexes) +- section of the Firestore docs. The command looks like the following: @@ -251,21 +297,29 @@ The prior example requires the `embedding` field to be indexed to work. To creat --field-config=vector-config='{"dimension":"768","flat": "{}"}',field-path=yourEmbeddingField ``` - However, the correct indexing configuration depends on the queries you will make and the embedding model you're using. + However, the correct indexing configuration depends on the queries you +- make and the embedding model you're using. -- Alternatively, call `ai.retrieve()` and Firestore will throw an error with the correct command to create the index. +- Alternatively, call `ai.retrieve()` and Firestore will throw an error with +- the correct command to create the index. #### Learn more -- See the [Retrieval-augmented generation](http://../rag.md) page for a general discussion on indexers and retrievers in Genkit. -- See [Search with vector embeddings](https://firebase.google.com/docs/firestore/vector-search) in the Cloud Firestore docs for more on the vector search feature. +- See the [Retrieval-augmented generation](http://../rag.md) page for a general discussion +on indexers and retrievers in Genkit. +- See [Search with vector embeddings](https://firebase.google.com/docs/firestore/vector-search) in the Cloud Firestore docs for more +on the vector search feature. ### Deploy flows as Cloud Functions -To deploy a flow with Cloud Functions, use the Firebase Functions library's native support for genkit. The `onCallGenkit` method allows -you to create a [callable function](https://firebase.google.com/docs/functions/callable?gen=2nd) from a flow. It will automatically support -streaming and JSON requests. You can use the [Cloud Functions client SDKs](https://firebase.google.com/docs/functions/callable?gen=2nd#call_the_function) to call them. +To deploy a flow with Cloud Functions, use the Firebase Functions library's +built-in support for genkit. The `onCallGenkit` method lets +you to create a [callable function](https://firebase.google.com/docs/functions/callable?gen=2nd) +from a flow. It automatically supports +streaming and JSON requests. You can use the +[Cloud Functions client SDKs](https://firebase.google.com/docs/functions/callable?gen=2nd#call_the_function) +to call them. From 3c2cc3a930ca81180e14949aad8263b5f77e01ab Mon Sep 17 00:00:00 2001 From: dmail Date: Wed, 5 Feb 2025 16:11:34 -0800 Subject: [PATCH 7/8] Docs: Edits to Firebase doc for 1.0 GA --- docs/plugins/firebase.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/plugins/firebase.md b/docs/plugins/firebase.md index 56defabb0..7b3f2c1dd 100644 --- a/docs/plugins/firebase.md +++ b/docs/plugins/firebase.md @@ -286,8 +286,8 @@ The prior example requires the `embedding` field to be indexed to work. To create the index: - Run the `gcloud` command described in the -- [Create a single-field vector index](https://firebase.google.com/docs/firestore/vector-search?authuser=0#create_and_manage_vector_indexes) -- section of the Firestore docs. +[Create a single-field vector index](https://firebase.google.com/docs/firestore/vector-search?authuser=0#create_and_manage_vector_indexes) +section of the Firestore docs. The command looks like the following: @@ -298,11 +298,11 @@ To create the index: ``` However, the correct indexing configuration depends on the queries you -- make and the embedding model you're using. + make and the embedding model you're using. - Alternatively, call `ai.retrieve()` and Firestore will throw an error with -- the correct command to create the index. + the correct command to create the index. #### Learn more From 7cb632b32d10e42b333f92d6f09cb6bd89cf79b5 Mon Sep 17 00:00:00 2001 From: thedmail Date: Wed, 5 Feb 2025 16:46:50 -0800 Subject: [PATCH 8/8] Accepting typo-fix suggestion in docs/firebase.md Co-authored-by: Chris Ray Gill --- docs/firebase.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/firebase.md b/docs/firebase.md index b30c8c239..d68d91b69 100644 --- a/docs/firebase.md +++ b/docs/firebase.md @@ -3,7 +3,7 @@ Cloud Functions for Firebase has an `onCallGenkit` method that lets you quickly create a [callable function](https://firebase.google.com/docs/functions/callable?gen=2nd) with a Genkit action (e.g. a Flow). These functions can be called using -`genkit/beta/client`or the [Functions clientSDK](https://firebase.google.com/docs/functions/callable?gen=2nd#call_the_function), +`genkit/beta/client`or the [Functions client SDK](https://firebase.google.com/docs/functions/callable?gen=2nd#call_the_function), which automatically adds auth info. ## Before you begin