diff --git a/common/api-review/vertexai.api.md b/common/api-review/vertexai.api.md index 5c8ef330cbe..d8c189a0059 100644 --- a/common/api-review/vertexai.api.md +++ b/common/api-review/vertexai.api.md @@ -326,6 +326,7 @@ export interface GenerativeContentBlob { export class GenerativeModel extends VertexAIModel { constructor(vertexAI: VertexAI, modelParams: ModelParams, requestOptions?: RequestOptions); countTokens(request: CountTokensRequest | string | Array): Promise; + static DEFAULT_HYBRID_IN_CLOUD_MODEL: string; generateContent(request: GenerateContentRequest | string | Array): Promise; generateContentStream(request: GenerateContentRequest | string | Array): Promise; // (undocumented) @@ -418,13 +419,9 @@ export enum HarmSeverity { // @public export interface HybridParams { - // (undocumented) - mode?: InferenceMode; - // (undocumented) - onCloudParams?: ModelParams; + inCloudParams?: ModelParams; + mode: InferenceMode; // Warning: (ae-forgotten-export) The symbol "LanguageModelCreateOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) onDeviceParams?: LanguageModelCreateOptions; } @@ -514,11 +511,8 @@ export interface ImagenSafetySettings { // @public export enum InferenceMode { - // (undocumented) - ONLY_ON_CLOUD = "ONLY_ON_CLOUD", - // (undocumented) + ONLY_IN_CLOUD = "ONLY_IN_CLOUD", ONLY_ON_DEVICE = "ONLY_ON_DEVICE", - // (undocumented) PREFER_ON_DEVICE = "PREFER_ON_DEVICE" } diff --git a/docs-devsite/vertexai.generativemodel.md b/docs-devsite/vertexai.generativemodel.md index e4a238b0af5..831ec5d4369 100644 --- a/docs-devsite/vertexai.generativemodel.md +++ b/docs-devsite/vertexai.generativemodel.md @@ -29,6 +29,7 @@ export declare class GenerativeModel extends VertexAIModel | Property | Modifiers | Type | Description | | --- | --- | --- | --- | +| [DEFAULT\_HYBRID\_IN\_CLOUD\_MODEL](./vertexai.generativemodel.md#generativemodeldefault_hybrid_in_cloud_model) | static | string | Defines the name of the default in-cloud model to use for hybrid inference. | | [generationConfig](./vertexai.generativemodel.md#generativemodelgenerationconfig) | | [GenerationConfig](./vertexai.generationconfig.md#generationconfig_interface) | | | [requestOptions](./vertexai.generativemodel.md#generativemodelrequestoptions) | | [RequestOptions](./vertexai.requestoptions.md#requestoptions_interface) | | | [safetySettings](./vertexai.generativemodel.md#generativemodelsafetysettings) | | [SafetySetting](./vertexai.safetysetting.md#safetysetting_interface)\[\] | | @@ -63,6 +64,16 @@ constructor(vertexAI: VertexAI, modelParams: ModelParams, requestOptions?: Reque | modelParams | [ModelParams](./vertexai.modelparams.md#modelparams_interface) | | | requestOptions | [RequestOptions](./vertexai.requestoptions.md#requestoptions_interface) | | +## GenerativeModel.DEFAULT\_HYBRID\_IN\_CLOUD\_MODEL + +Defines the name of the default in-cloud model to use for hybrid inference. + +Signature: + +```typescript +static DEFAULT_HYBRID_IN_CLOUD_MODEL: string; +``` + ## GenerativeModel.generationConfig Signature: diff --git a/docs-devsite/vertexai.hybridparams.md b/docs-devsite/vertexai.hybridparams.md index ea175a7234b..cf847b40fa7 100644 --- a/docs-devsite/vertexai.hybridparams.md +++ b/docs-devsite/vertexai.hybridparams.md @@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # HybridParams interface -Configures on-device and on-cloud inference. +Toggles hybrid inference. Signature: @@ -22,28 +22,34 @@ export interface HybridParams | Property | Type | Description | | --- | --- | --- | -| [mode](./vertexai.hybridparams.md#hybridparamsmode) | [InferenceMode](./vertexai.md#inferencemode) | | -| [onCloudParams](./vertexai.hybridparams.md#hybridparamsoncloudparams) | [ModelParams](./vertexai.modelparams.md#modelparams_interface) | | -| [onDeviceParams](./vertexai.hybridparams.md#hybridparamsondeviceparams) | LanguageModelCreateOptions | | +| [inCloudParams](./vertexai.hybridparams.md#hybridparamsincloudparams) | [ModelParams](./vertexai.modelparams.md#modelparams_interface) | Optional. Specifies advanced params for in-cloud inference. | +| [mode](./vertexai.hybridparams.md#hybridparamsmode) | [InferenceMode](./vertexai.md#inferencemode) | Specifies on-device or in-cloud inference. Defaults to prefer on-device. | +| [onDeviceParams](./vertexai.hybridparams.md#hybridparamsondeviceparams) | LanguageModelCreateOptions | Optional. Specifies advanced params for on-device inference. | -## HybridParams.mode +## HybridParams.inCloudParams + +Optional. Specifies advanced params for in-cloud inference. Signature: ```typescript -mode?: InferenceMode; +inCloudParams?: ModelParams; ``` -## HybridParams.onCloudParams +## HybridParams.mode + +Specifies on-device or in-cloud inference. Defaults to prefer on-device. Signature: ```typescript -onCloudParams?: ModelParams; +mode: InferenceMode; ``` ## HybridParams.onDeviceParams +Optional. Specifies advanced params for on-device inference. + Signature: ```typescript diff --git a/docs-devsite/vertexai.md b/docs-devsite/vertexai.md index 305d0f09b61..734a21fa3dc 100644 --- a/docs-devsite/vertexai.md +++ b/docs-devsite/vertexai.md @@ -55,7 +55,7 @@ The Vertex AI in Firebase Web SDK. | [ImagenAspectRatio](./vertexai.md#imagenaspectratio) | (Public Preview) Aspect ratios for Imagen images.To specify an aspect ratio for generated images, set the aspectRatio property in your [ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface).See the the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) for more details and examples of the supported aspect ratios. | | [ImagenPersonFilterLevel](./vertexai.md#imagenpersonfilterlevel) | (Public Preview) A filter level controlling whether generation of images containing people or faces is allowed.See the personGeneration documentation for more details. | | [ImagenSafetyFilterLevel](./vertexai.md#imagensafetyfilterlevel) | (Public Preview) A filter level controlling how aggressively to filter sensitive content.Text prompts provided as inputs and images (generated or uploaded) through Imagen on Vertex AI are assessed against a list of safety filters, which include 'harmful categories' (for example, violence, sexual, derogatory, and toxic). This filter level controls how aggressively to filter out potentially harmful content from responses. See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) and the [Responsible AI and usage guidelines](https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#safety-filters) for more details. | -| [InferenceMode](./vertexai.md#inferencemode) | Determines whether inference happens on-device or on-cloud. | +| [InferenceMode](./vertexai.md#inferencemode) | Determines whether inference happens on-device or in-cloud. | | [Modality](./vertexai.md#modality) | Content part modality. | | [SchemaType](./vertexai.md#schematype) | Contains the list of OpenAPI data types as defined by the [OpenAPI specification](https://swagger.io/docs/specification/data-models/data-types/) | | [VertexAIErrorCode](./vertexai.md#vertexaierrorcode) | Standardized error codes that [VertexAIError](./vertexai.vertexaierror.md#vertexaierror_class) can have. | @@ -92,7 +92,7 @@ The Vertex AI in Firebase Web SDK. | [GenerativeContentBlob](./vertexai.generativecontentblob.md#generativecontentblob_interface) | Interface for sending an image. | | [GroundingAttribution](./vertexai.groundingattribution.md#groundingattribution_interface) | | | [GroundingMetadata](./vertexai.groundingmetadata.md#groundingmetadata_interface) | Metadata returned to client when grounding is enabled. | -| [HybridParams](./vertexai.hybridparams.md#hybridparams_interface) | Configures on-device and on-cloud inference. | +| [HybridParams](./vertexai.hybridparams.md#hybridparams_interface) | Toggles hybrid inference. | | [ImagenGCSImage](./vertexai.imagengcsimage.md#imagengcsimage_interface) | An image generated by Imagen, stored in a Cloud Storage for Firebase bucket.This feature is not available yet. | | [ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface) | (Public Preview) Configuration options for generating images with Imagen.See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images-imagen) for more details. | | [ImagenGenerationResponse](./vertexai.imagengenerationresponse.md#imagengenerationresponse_interface) | (Public Preview) The response from a request to generate images with Imagen. | @@ -493,7 +493,7 @@ export declare enum ImagenSafetyFilterLevel ## InferenceMode -Determines whether inference happens on-device or on-cloud. +Determines whether inference happens on-device or in-cloud. Signature: @@ -505,9 +505,9 @@ export declare enum InferenceMode | Member | Value | Description | | --- | --- | --- | -| ONLY\_ON\_CLOUD | "ONLY_ON_CLOUD" | | -| ONLY\_ON\_DEVICE | "ONLY_ON_DEVICE" | | -| PREFER\_ON\_DEVICE | "PREFER_ON_DEVICE" | | +| ONLY\_IN\_CLOUD | "ONLY_IN_CLOUD" | Exclusively uses the in-cloud model. | +| ONLY\_ON\_DEVICE | "ONLY_ON_DEVICE" | Exclusively uses the on-device model. Throws if one is not available. | +| PREFER\_ON\_DEVICE | "PREFER_ON_DEVICE" | Uses the on-device model if available, or falls back to the in-cloud model. | ## Modality diff --git a/packages/vertexai/src/api.test.ts b/packages/vertexai/src/api.test.ts index a38358f806f..aeb090e24c5 100644 --- a/packages/vertexai/src/api.test.ts +++ b/packages/vertexai/src/api.test.ts @@ -106,6 +106,21 @@ describe('Top level API', () => { expect(genModel).to.be.an.instanceOf(GenerativeModel); expect(genModel.model).to.equal('publishers/google/models/my-model'); }); + it('getGenerativeModel with HybridParams sets a default model', () => { + const genModel = getGenerativeModel(fakeVertexAI, { + mode: InferenceMode.ONLY_ON_DEVICE + }); + expect(genModel.model).to.equal( + `publishers/google/models/${GenerativeModel.DEFAULT_HYBRID_IN_CLOUD_MODEL}` + ); + }); + it('getGenerativeModel with HybridParams honors a model override', () => { + const genModel = getGenerativeModel(fakeVertexAI, { + mode: InferenceMode.ONLY_IN_CLOUD, + inCloudParams: { model: 'my-model' } + }); + expect(genModel.model).to.equal('publishers/google/models/my-model'); + }); it('getImagenModel throws if no model is provided', () => { try { getImagenModel(fakeVertexAI, {} as ImagenModelParams); @@ -117,13 +132,6 @@ describe('Top level API', () => { ); } }); - it('getGenerativeModel with HybridParams sets the model', () => { - const genModel = getGenerativeModel(fakeVertexAI, { - mode: InferenceMode.ONLY_ON_CLOUD, - onCloudParams: { model: 'my-model' } - }); - expect(genModel.model).to.equal('publishers/google/models/my-model'); - }); it('getImagenModel throws if no apiKey is provided', () => { const fakeVertexNoApiKey = { ...fakeVertexAI, diff --git a/packages/vertexai/src/api.ts b/packages/vertexai/src/api.ts index 7f11dd80844..2b8536dd89f 100644 --- a/packages/vertexai/src/api.ts +++ b/packages/vertexai/src/api.ts @@ -76,22 +76,22 @@ export function getGenerativeModel( ): GenerativeModel { // Uses the existence of HybridParams.mode to clarify the type of the modelParams input. const hybridParams = modelParams as HybridParams; - let onCloudParams: ModelParams; + let inCloudParams: ModelParams; if (hybridParams.mode) { - onCloudParams = hybridParams.onCloudParams || { - model: 'gemini-2.0-flash-lite' + inCloudParams = hybridParams.inCloudParams || { + model: GenerativeModel.DEFAULT_HYBRID_IN_CLOUD_MODEL }; } else { - onCloudParams = modelParams as ModelParams; + inCloudParams = modelParams as ModelParams; } - if (!onCloudParams.model) { + if (!inCloudParams.model) { throw new VertexAIError( VertexAIErrorCode.NO_MODEL, `Must provide a model name. Example: getGenerativeModel({ model: 'my-model-name' })` ); } - return new GenerativeModel(vertexAI, onCloudParams, requestOptions); + return new GenerativeModel(vertexAI, inCloudParams, requestOptions); } /** diff --git a/packages/vertexai/src/models/generative-model.ts b/packages/vertexai/src/models/generative-model.ts index 983118bf6ff..32406ea19f7 100644 --- a/packages/vertexai/src/models/generative-model.ts +++ b/packages/vertexai/src/models/generative-model.ts @@ -49,6 +49,10 @@ import { VertexAIModel } from './vertexai-model'; * @public */ export class GenerativeModel extends VertexAIModel { + /** + * Defines the name of the default in-cloud model to use for hybrid inference. + */ + static DEFAULT_HYBRID_IN_CLOUD_MODEL = 'gemini-2.0-flash-lite'; generationConfig: GenerationConfig; safetySettings: SafetySetting[]; requestOptions?: RequestOptions; diff --git a/packages/vertexai/src/types/enums.ts b/packages/vertexai/src/types/enums.ts index 1f81ed79a8f..57629e5c9f5 100644 --- a/packages/vertexai/src/types/enums.ts +++ b/packages/vertexai/src/types/enums.ts @@ -242,11 +242,21 @@ export enum Modality { } /** - * Determines whether inference happens on-device or on-cloud. - * @public + * Determines whether inference happens on-device or in-cloud. */ export enum InferenceMode { + /** + * Uses the on-device model if available, or falls back to the in-cloud model. + */ PREFER_ON_DEVICE = 'PREFER_ON_DEVICE', + + /** + * Exclusively uses the on-device model. Throws if one is not available. + */ ONLY_ON_DEVICE = 'ONLY_ON_DEVICE', - ONLY_ON_CLOUD = 'ONLY_ON_CLOUD' + + /** + * Exclusively uses the in-cloud model. + */ + ONLY_IN_CLOUD = 'ONLY_IN_CLOUD' } diff --git a/packages/vertexai/src/types/requests.ts b/packages/vertexai/src/types/requests.ts index c643fcd6084..345f98ca163 100644 --- a/packages/vertexai/src/types/requests.ts +++ b/packages/vertexai/src/types/requests.ts @@ -217,11 +217,19 @@ export interface FunctionCallingConfig { } /** - * Configures on-device and on-cloud inference. - * @public + * Toggles hybrid inference. */ export interface HybridParams { - mode?: InferenceMode; + /** + * Specifies on-device or in-cloud inference. Defaults to prefer on-device. + */ + mode: InferenceMode; + /** + * Optional. Specifies advanced params for on-device inference. + */ onDeviceParams?: LanguageModelCreateOptions; - onCloudParams?: ModelParams; + /** + * Optional. Specifies advanced params for in-cloud inference. + */ + inCloudParams?: ModelParams; }