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,8 @@ export enum HarmSeverity {
 
 // @public
 export interface HybridParams {
-    // (undocumented)
-    mode?: InferenceMode;
-    // (undocumented)
-    onCloudParams?: ModelParams;
-    // Warning: (ae-forgotten-export) The symbol "LanguageModelCreateOptions" needs to be exported by the entry point index.d.ts
-    //
-    // (undocumented)
+    inCloudParams?: ModelParams;
+    mode: InferenceMode;
     onDeviceParams?: LanguageModelCreateOptions;
 }
 
@@ -515,7 +511,7 @@ export interface ImagenSafetySettings {
 // @public
 export enum InferenceMode {
     // (undocumented)
-    ONLY_ON_CLOUD = "ONLY_ON_CLOUD",
+    ONLY_IN_CLOUD = "ONLY_IN_CLOUD",
     // (undocumented)
     ONLY_ON_DEVICE = "ONLY_ON_DEVICE",
     // (undocumented)

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