Moving to in-cloud naming

Author: erikeldridge

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<string | Part>): Promise<CountTokensResponse>;
+    static DEFAULT_HYBRID_IN_CLOUD_MODEL: string;
     generateContent(request: GenerateContentRequest | string | Array<string | Part>): Promise<GenerateContentResult>;
     generateContentStream(request: GenerateContentRequest | string | Array<string | Part>): Promise<GenerateContentStreamResult>;
     // (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"
 }
 

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) | <code>static</code> | 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.
+
+<b>Signature:</b>
+
+```typescript
+static DEFAULT_HYBRID_IN_CLOUD_MODEL: string;
+```
+
 ## GenerativeModel.generationConfig
 
 <b>Signature:</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.
 
 <b>Signature:</b>
 
@@ -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.
 
 <b>Signature:</b>
 
 ```typescript
-mode?: InferenceMode;
+inCloudParams?: ModelParams;
 ```
 
-## HybridParams.onCloudParams
+## HybridParams.mode
+
+Specifies on-device or in-cloud inference. Defaults to prefer on-device.
 
 <b>Signature:</b>
 
 ```typescript
-onCloudParams?: ModelParams;
+mode: InferenceMode;
 ```
 
 ## HybridParams.onDeviceParams
 
+Optional. Specifies advanced params for on-device inference.
+
 <b>Signature:</b>
 
 ```typescript

docs-devsite/vertexai.md

@@ -55,7 +55,7 @@ The Vertex AI in Firebase Web SDK.
 |  [ImagenAspectRatio](./vertexai.md#imagenaspectratio) | <b><i>(Public Preview)</i></b> Aspect ratios for Imagen images.<!-- -->To specify an aspect ratio for generated images, set the <code>aspectRatio</code> 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) | <b><i>(Public Preview)</i></b> A filter level controlling whether generation of images containing people or faces is allowed.<!-- -->See the <a href="http://firebase.google.com/docs/vertex-ai/generate-images">personGeneration</a> documentation for more details. |
 |  [ImagenSafetyFilterLevel](./vertexai.md#imagensafetyfilterlevel) | <b><i>(Public Preview)</i></b> 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, <code>violence</code>, <code>sexual</code>, <code>derogatory</code>, and <code>toxic</code>). 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) | <b><i>(Public Preview)</i></b> 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) | <b><i>(Public Preview)</i></b> 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.
 
 <b>Signature:</b>
 
@@ -505,9 +505,9 @@ export declare enum InferenceMode
 
 |  Member | Value | Description |
 |  --- | --- | --- |
-|  ONLY\_ON\_CLOUD | <code>&quot;ONLY_ON_CLOUD&quot;</code> |  |
-|  ONLY\_ON\_DEVICE | <code>&quot;ONLY_ON_DEVICE&quot;</code> |  |
-|  PREFER\_ON\_DEVICE | <code>&quot;PREFER_ON_DEVICE&quot;</code> |  |
+|  ONLY\_IN\_CLOUD | <code>&quot;ONLY_IN_CLOUD&quot;</code> | Exclusively uses the in-cloud model. |
+|  ONLY\_ON\_DEVICE | <code>&quot;ONLY_ON_DEVICE&quot;</code> | Exclusively uses the on-device model. Throws if one is not available. |
+|  PREFER\_ON\_DEVICE | <code>&quot;PREFER_ON_DEVICE&quot;</code> | Uses the on-device model if available, or falls back to the in-cloud model. |
 
 ## Modality
 

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,

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

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;

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'
 }

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