Backport: feat(ai/core): support plain string model IDs in rerank() (#14214)

vercel-ai-sdk[bot] · web-flow · commit f15213372be7 · 2026-04-07T21:25:52.000-07:00
diff --git a/.changeset/rerank-string-model-resolution.md b/.changeset/rerank-string-model-resolution.md
@@ -0,0 +1,7 @@
+---
+"ai": patch
+---
+
+feat (ai/core): support plain string model IDs in `rerank()` function
+
+The `rerank()` function now accepts plain model strings (e.g., `'cohere/rerank-v3.5'`) in addition to `RerankingModel` objects, matching the behavior of `generateText`, `embed`, and other core functions.
diff --git a/packages/ai/src/model/resolve-model.test.ts b/packages/ai/src/model/resolve-model.test.ts
@@ -4,13 +4,15 @@ import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
 
 import { MockEmbeddingModelV3 } from '../test/mock-embedding-model-v3';
 import { MockLanguageModelV3 } from '../test/mock-language-model-v3';
+import { MockRerankingModelV3 } from '../test/mock-reranking-model-v3';
 import { MockVideoModelV3 } from '../test/mock-video-model-v3';
 import { customProvider } from '../registry/custom-provider';
 import { MockImageModelV2 } from '../test/mock-image-model-v2';
 import {
   resolveEmbeddingModel,
   resolveImageModel,
   resolveLanguageModel,
+  resolveRerankingModel,
   resolveVideoModel,
 } from './resolve-model';
 
@@ -356,3 +358,129 @@ describe('resolveVideoModel', () => {
     });
   });
 });
+
+describe('resolveRerankingModel', () => {
+  describe('when a reranking model v3 is provided', () => {
+    it('should return it as-is', () => {
+      const originalModel = new MockRerankingModelV3({
+        provider: 'test-provider',
+        modelId: 'test-model-id',
+      });
+
+      const resolvedModel = resolveRerankingModel(originalModel);
+
+      expect(resolvedModel).toBe(originalModel);
+      expect(resolvedModel.specificationVersion).toBe('v3');
+    });
+  });
+
+  describe('when a reranking model v3 is provided', () => {
+    it('should return it as v3', () => {
+      const resolvedModel = resolveRerankingModel(
+        new MockRerankingModelV3({
+          provider: 'test-provider',
+          modelId: 'test-model-id',
+        }),
+      );
+
+      expect(resolvedModel.provider).toBe('test-provider');
+      expect(resolvedModel.modelId).toBe('test-model-id');
+      expect(resolvedModel.specificationVersion).toBe('v3');
+    });
+  });
+
+  describe('when a string is provided and the global default provider is not set', () => {
+    it('should return a gateway reranking model', () => {
+      const mockModel = new MockRerankingModelV3({
+        provider: 'gateway',
+        modelId: 'test-model-id',
+      });
+
+      const rerankingModelSpy = vi
+        .spyOn(gateway, 'rerankingModel')
+        .mockReturnValue(mockModel as any);
+
+      try {
+        const resolvedModel = resolveRerankingModel('test-model-id');
+
+        expect(resolvedModel.provider).toBe('gateway');
+        expect(resolvedModel.modelId).toBe('test-model-id');
+      } finally {
+        rerankingModelSpy.mockRestore();
+      }
+    });
+  });
+
+  describe('when a string is provided and the global default provider is set', () => {
+    beforeEach(() => {
+      globalThis.AI_SDK_DEFAULT_PROVIDER = customProvider({
+        rerankingModels: {
+          'test-model-id': new MockRerankingModelV3({
+            provider: 'global-test-provider',
+            modelId: 'actual-test-model-id',
+          }),
+        },
+      });
+    });
+
+    afterEach(() => {
+      delete globalThis.AI_SDK_DEFAULT_PROVIDER;
+    });
+
+    it('should return a reranking model from the global default provider', () => {
+      const resolvedModel = resolveRerankingModel('test-model-id');
+
+      expect(resolvedModel.provider).toBe('global-test-provider');
+      expect(resolvedModel.modelId).toBe('actual-test-model-id');
+    });
+  });
+
+  describe('when a string is provided and the provider does not support reranking models', () => {
+    beforeEach(() => {
+      globalThis.AI_SDK_DEFAULT_PROVIDER = {
+        specificationVersion: 'v3' as const,
+        languageModel: () => {
+          throw new Error('not implemented');
+        },
+        embeddingModel: () => {
+          throw new Error('not implemented');
+        },
+        imageModel: () => {
+          throw new Error('not implemented');
+        },
+      };
+    });
+
+    afterEach(() => {
+      delete globalThis.AI_SDK_DEFAULT_PROVIDER;
+    });
+
+    it('should throw an error', () => {
+      expect(() => resolveRerankingModel('test-model-id')).toThrow(
+        'The default provider does not support reranking models.',
+      );
+    });
+  });
+
+  describe('when a model with unsupported specification version is provided', () => {
+    it('should throw UnsupportedModelVersionError', () => {
+      const unsupportedModel = {
+        specificationVersion: 'v1',
+        provider: 'test-provider',
+        modelId: 'test-model-id',
+      } as any;
+
+      expect(() => resolveRerankingModel(unsupportedModel)).toThrow();
+    });
+
+    it('should throw UnsupportedModelVersionError for v2 models', () => {
+      const v2Model = {
+        specificationVersion: 'v2',
+        provider: 'test-provider',
+        modelId: 'test-model-id',
+      } as any;
+
+      expect(() => resolveRerankingModel(v2Model)).toThrow();
+    });
+  });
+});
diff --git a/packages/ai/src/model/resolve-model.ts b/packages/ai/src/model/resolve-model.ts
@@ -5,6 +5,7 @@ import {
   ImageModelV3,
   LanguageModelV3,
   ProviderV3,
+  RerankingModelV3,
   SpeechModelV3,
   TranscriptionModelV3,
 } from '@ai-sdk/provider';
@@ -19,6 +20,7 @@ import { asLanguageModelV3 } from './as-language-model-v3';
 import { asSpeechModelV3 } from './as-speech-model-v3';
 import { asTranscriptionModelV3 } from './as-transcription-model-v3';
 import { ImageModel } from '../types/image-model';
+import { RerankingModel } from '../types/reranking-model';
 import { VideoModel } from '../types/video-model';
 
 export function resolveLanguageModel(model: LanguageModel): LanguageModelV3 {
@@ -154,6 +156,33 @@ export function resolveVideoModel(
   return model;
 }
 
+export function resolveRerankingModel(model: RerankingModel): RerankingModelV3 {
+  if (typeof model === 'string') {
+    const provider = getGlobalProvider();
+    const rerankingModel = provider.rerankingModel;
+
+    if (!rerankingModel) {
+      throw new Error(
+        'The default provider does not support reranking models. ' +
+          'Please use a RerankingModel object from a provider (e.g., gateway.rerankingModel("model-id")).',
+      );
+    }
+
+    return rerankingModel(model);
+  }
+
+  if (model.specificationVersion !== 'v3') {
+    const unsupportedModel: any = model;
+    throw new UnsupportedModelVersionError({
+      version: unsupportedModel.specificationVersion,
+      provider: unsupportedModel.provider,
+      modelId: unsupportedModel.modelId,
+    });
+  }
+
+  return model;
+}
+
 function getGlobalProvider(): ProviderV3 {
   return globalThis.AI_SDK_DEFAULT_PROVIDER ?? gateway;
 }
diff --git a/packages/ai/src/rerank/rerank.ts b/packages/ai/src/rerank/rerank.ts
@@ -7,6 +7,7 @@ import { getTracer } from '../telemetry/get-tracer';
 import { recordSpan } from '../telemetry/record-span';
 import { selectTelemetryAttributes } from '../telemetry/select-telemetry-attributes';
 import { TelemetrySettings } from '../telemetry/telemetry-settings';
+import { resolveRerankingModel } from '../model/resolve-model';
 import { RerankingModel } from '../types';
 import { RerankResult } from './rerank-result';
 import { logWarnings } from '../logger/log-warnings';
@@ -28,7 +29,7 @@ import { logWarnings } from '../logger/log-warnings';
  * @returns A result object that contains the reranked documents, the reranked indices, and additional information.
  */
 export async function rerank<VALUE extends JSONObject | string>({
-  model,
+  model: modelArg,
   documents,
   query,
   topN,
@@ -88,6 +89,8 @@ export async function rerank<VALUE extends JSONObject | string>({
    */
   providerOptions?: ProviderOptions;
 }): Promise<RerankResult<VALUE>> {
+  const model = resolveRerankingModel(modelArg);
+
   if (documents.length === 0) {
     return new DefaultRerankResult({
       originalDocuments: [],
diff --git a/packages/ai/src/types/reranking-model.ts b/packages/ai/src/types/reranking-model.ts
@@ -3,4 +3,4 @@ import { RerankingModelV3 } from '@ai-sdk/provider';
 /**
  * Reranking model that is used by the AI SDK.
  */
-export type RerankingModel = RerankingModelV3;
+export type RerankingModel = string | RerankingModelV3;
