@ai-sdk/deepseek 2.0.58 → 2.0.60

package/docs/30-deepseek.mdx

@@ -75,7 +75,7 @@ import { deepseek } from '@ai-sdk/deepseek';
 import { generateText } from 'ai';
 
 const { text } = await generateText({
-  model: deepseek('deepseek-chat'),
+  model: deepseek('deepseek-v4-flash'),
   prompt: 'Write a vegetarian lasagna recipe for 4 people.',
 });
 ```
@@ -83,39 +83,73 @@ const { text } = await generateText({
 You can also use the `.chat()` or `.languageModel()` factory methods:
 
 ```ts
-const model = deepseek.chat('deepseek-chat');
+const model = deepseek.chat('deepseek-v4-flash');
 // or
-const model = deepseek.languageModel('deepseek-chat');
+const model = deepseek.languageModel('deepseek-v4-flash');
 ```
 
 DeepSeek language models can be used in the `streamText` function
 (see [AI SDK Core](/docs/ai-sdk-core)).
 
+DeepSeek retired the `deepseek-chat` and `deepseek-reasoner` aliases on July 24,
+2026. Use `deepseek-v4-flash` or `deepseek-v4-pro` for the current API. Custom
+and legacy model IDs remain accepted as strings for compatibility with custom
+endpoints.
+
 The following optional provider options are available for DeepSeek models:
 
+- `logprobs` _boolean_
+
+  Optional. Returns log probabilities for generated content and reasoning
+  tokens in `providerMetadata.deepseek.logprobs`.
+
+- `topLogprobs` _number_
+
+  Optional. Returns the specified number of most likely tokens at each token
+  position. Accepts values from `0` through `20` and automatically enables
+  `logprobs`.
+
+- `userId` _string_
+
+  Optional. An opaque end-user identifier that DeepSeek uses for content-safety
+  tracing, KV-cache isolation, and scheduling isolation. The value must match
+  `^[a-zA-Z0-9_-]+$` and contain at most 512 characters. Do not include names,
+  email addresses, or other private user information.
+
 - `thinking` _object_
 
-  Optional. Controls thinking mode (chain-of-thought reasoning). You can enable thinking mode either by using the `deepseek-reasoner` model or by setting this option.
-  - `type`: `'adaptive' | 'enabled' | 'disabled'` - Enable, disable, or let the model decide (`adaptive`) when to think. See [DeepSeek's thinking mode docs](https://api-docs.deepseek.com/guides/thinking_mode).
+  Optional. Controls thinking mode (chain-of-thought reasoning) for DeepSeek V4 models.
+  - `type`: `'enabled' | 'disabled'` - Enable or disable thinking mode. See [DeepSeek's thinking mode docs](https://api-docs.deepseek.com/guides/thinking_mode).
+
+- `reasoningEffort` _'low' | 'high' | 'max'_
+
+  Optional. Controls thinking strength for DeepSeek V4 reasoning models.
+  `medium` is sent as `high`, and `xhigh` is sent as `max`. A compatibility
+  warning is returned whenever the requested value is mapped.
 
-- `reasoningEffort` _'low' | 'medium' | 'high' | 'xhigh' | 'max'_
+For backwards compatibility, legacy provider options supplied at runtime are
+also mapped to documented values: `thinking.type: 'adaptive'` becomes
+`'enabled'`, `reasoningEffort: 'medium'` becomes `'high'`, and
+`reasoningEffort: 'xhigh'` becomes `'max'`. Each mapping returns a compatibility
+warning so callers can migrate to a canonical value.
 
-  Optional. Controls thinking strength for DeepSeek V4 reasoning models. Per
-  DeepSeek's docs, `low` and `medium` are mapped to `high`, and `xhigh` is
-  mapped to `max` server-side for compatibility with other providers. When
-  using the top-level `reasoning` setting, `minimal` is sent as `low`, and
-  `low`, `medium`, `high`, and `xhigh` pass through to DeepSeek's native
-  effort values. Ignored when thinking is explicitly disabled.
+DeepSeek has deprecated the top-level `frequencyPenalty` and `presencePenalty`
+settings. The provider omits these settings and returns a deprecation warning
+when they are used. `temperature` and `topP` have no effect while thinking is
+enabled, including the default thinking mode for DeepSeek V4 models, so the
+provider omits them with an unsupported warning. Explicitly set
+`thinking.type` to `'disabled'` to use `temperature` and `topP`.
 
-```ts highlight="7-12"
+```ts highlight="7-13"
 import { deepseek, type DeepSeekLanguageModelOptions } from '@ai-sdk/deepseek';
 import { generateText } from 'ai';
 
 const { text, reasoning } = await generateText({
-  model: deepseek('deepseek-chat'),
+  model: deepseek('deepseek-v4-flash'),
   prompt: 'How many "r"s are in the word "strawberry"?',
   providerOptions: {
     deepseek: {
+      userId: 'tenant_123-user',
       thinking: { type: 'enabled' },
       reasoningEffort: 'high',
     } satisfies DeepSeekLanguageModelOptions,
@@ -123,16 +157,106 @@ const { text, reasoning } = await generateText({
 });
 ```
 
+### Message Names
+
+DeepSeek supports optional participant names on system, user, and assistant
+messages. Set `providerOptions.deepseek.name` on each message that should
+include a name:
+
+```ts
+import {
+  deepSeek,
+  type DeepSeekMessageProviderOptions,
+} from '@ai-sdk/deepseek';
+import { generateText } from 'ai';
+
+const { text } = await generateText({
+  model: deepSeek('deepseek-chat'),
+  instructions: {
+    role: 'system',
+    content: 'Help the customer plan a short trip.',
+    providerOptions: {
+      deepseek: {
+        name: 'travel_planner',
+      } satisfies DeepSeekMessageProviderOptions,
+    },
+  },
+  messages: [
+    {
+      role: 'user',
+      content: 'I want to visit Lisbon for a weekend.',
+      providerOptions: {
+        deepseek: {
+          name: 'customer',
+        } satisfies DeepSeekMessageProviderOptions,
+      },
+    },
+    {
+      role: 'assistant',
+      content: 'What kinds of activities do you enjoy?',
+      providerOptions: {
+        deepseek: {
+          name: 'travel_planner',
+        } satisfies DeepSeekMessageProviderOptions,
+      },
+    },
+    {
+      role: 'user',
+      content: 'Food, architecture, and walking.',
+      providerOptions: {
+        deepseek: {
+          name: 'customer',
+        } satisfies DeepSeekMessageProviderOptions,
+      },
+    },
+  ],
+});
+```
+
+The same message option works with `streamText`:
+
+```ts
+import {
+  deepSeek,
+  type DeepSeekMessageProviderOptions,
+} from '@ai-sdk/deepseek';
+import { streamText } from 'ai';
+
+const result = streamText({
+  model: deepSeek('deepseek-chat'),
+  messages: [
+    {
+      role: 'user',
+      content: 'Suggest a name for my neighborhood book club.',
+      providerOptions: {
+        deepseek: {
+          name: 'organizer',
+        } satisfies DeepSeekMessageProviderOptions,
+      },
+    },
+  ],
+});
+
+for await (const textPart of result.textStream) {
+  process.stdout.write(textPart);
+}
+```
+
+Names are omitted when the option is not set. The `name` value must be a
+string. DeepSeek does not support names on tool messages, so the provider
+ignores that placement and returns an unsupported-feature warning. Avoid
+including unnecessary personal or identifying information in message names.
+
 ### Reasoning
 
-DeepSeek has reasoning support for the `deepseek-reasoner` model. The reasoning is exposed through streaming:
+DeepSeek V4 models support reasoning. The reasoning is exposed through streaming:
 
 ```ts
 import { deepseek } from '@ai-sdk/deepseek';
 import { streamText } from 'ai';
 
 const result = streamText({
-  model: deepseek('deepseek-reasoner'),
+  model: deepseek('deepseek-v4-pro'),
   prompt: 'How many "r"s are in the word "strawberry"?',
 });
 
@@ -150,39 +274,186 @@ for await (const part of result.fullStream) {
 See [AI SDK UI: Chatbot](/docs/ai-sdk-ui/chatbot#reasoning) for more details
 on how to integrate reasoning into your chatbot.
 
-### Cache Token Usage
+### Chat Prefix Completion
 
-DeepSeek provides context caching on disk technology that can significantly reduce token costs for repeated content. You can access the cache hit/miss metrics through the `providerMetadata` property in the response:
+DeepSeek's beta [chat prefix completion](https://api-docs.deepseek.com/guides/chat_prefix_completion/)
+continues the content of a final assistant message. Create a provider with a
+beta base URL and set `prefix: true` in that assistant message's provider
+options:
+
+```ts highlight="8,20-26"
+import {
+  createDeepSeek,
+  type DeepSeekAssistantMessageProviderOptions,
+} from '@ai-sdk/deepseek';
+import { generateText } from 'ai';
+
+const deepSeek = createDeepSeek({
+  baseURL: 'https://api.deepseek.com/beta',
+});
+
+const { text } = await generateText({
+  model: deepSeek('deepseek-v4-flash'),
+  messages: [
+    {
+      role: 'user',
+      content: 'Write a short sentence about the color of the sky.',
+    },
+    {
+      role: 'assistant',
+      content: 'The sky is',
+      providerOptions: {
+        deepseek: {
+          prefix: true,
+        } satisfies DeepSeekAssistantMessageProviderOptions,
+      },
+    },
+  ],
+});
+```
+
+The prefixed message must be an assistant message and the final message in the
+prompt. The configured `baseURL` must end in `/beta`, including when using a
+proxy. Invalid placement or a non-beta base URL causes the request to fail
+before it is sent.
+
+<Note>
+  Chat prefix completion is a DeepSeek beta feature and its behavior may change.
+</Note>
+
+### Strict Tool Calls
+
+DeepSeek's strict tool-call mode is a beta feature. Create the provider with a
+beta base URL and set `strict: true` on every function tool in the request:
+
+```ts highlight="5,14"
+import { createDeepSeek } from '@ai-sdk/deepseek';
+import { generateText, tool } from 'ai';
+import { z } from 'zod';
+
+const deepSeek = createDeepSeek({
+  baseURL: 'https://api.deepseek.com/beta',
+});
+
+const result = await generateText({
+  model: deepSeek('deepseek-chat'),
+  prompt: 'What is the weather in San Francisco?',
+  tools: {
+    weather: tool({
+      description: 'Get the weather for a location.',
+      inputSchema: z.object({ location: z.string() }),
+      strict: true,
+      execute: async ({ location }) => ({ location, temperature: 18 }),
+    }),
+  },
+});
+```
+
+Strict tools fail locally when the base URL does not end in `/beta`. When any
+function tool is strict, every function tool in the same request must set
+`strict: true`.
+
+### Provider Metadata
+
+DeepSeek exposes the response system fingerprint and context cache usage through
+the `providerMetadata` property:
 
 ```ts
 import { deepseek } from '@ai-sdk/deepseek';
 import { generateText } from 'ai';
 
 const result = await generateText({
-  model: deepseek('deepseek-chat'),
+  model: deepseek('deepseek-v4-flash'),
   prompt: 'Your prompt here',
 });
 
 console.log(result.providerMetadata);
-// Example output: { deepseek: { promptCacheHitTokens: 1856, promptCacheMissTokens: 5 } }
+// Example output:
+// {
+//   deepseek: {
+//     systemFingerprint: 'fp_eaab8d114b_prod0820_fp8_kvcache',
+//     promptCacheHitTokens: 1856,
+//     promptCacheMissTokens: 5,
+//   },
+// }
 ```
 
-The metrics include:
+The metadata includes:
 
+- `systemFingerprint`: The backend configuration fingerprint for the response
 - `promptCacheHitTokens`: Number of input tokens that were cached
 - `promptCacheMissTokens`: Number of input tokens that were not cached
 
+For streamed responses, the latest non-null fingerprint from the response
+chunks is returned.
+
 <Note>
   For more details about DeepSeek's caching system, see the [DeepSeek caching
   documentation](https://api-docs.deepseek.com/guides/kv_cache#checking-cache-hit-status).
 </Note>
 
+### Chat Response Metadata
+
+DeepSeek preserves provider-specific response fields in
+`providerMetadata.deepseek` for generated and streamed responses:
+
+- `responseObject`: `chat.completion` or `chat.completion.chunk`
+- `choiceIndex`: the selected response choice index
+- `messageRole`: the response message role, when supplied
+- `toolCallTypes`: the tool-call type for each returned call
+
+These fields remain in provider metadata because they are specific to
+DeepSeek's Chat Completions response rather than shared AI SDK result fields.
+
+### Vision File Parts
+
+For inline images or image URLs, use file-part provider options to select the
+image processing detail. DeepSeek supports `low`, `high`, `original`, and
+`auto`:
+
+```ts highlight="2,13-17"
+import {
+  deepseek,
+  type DeepSeekFilePartProviderOptions,
+} from '@ai-sdk/deepseek';
+import { generateText } from 'ai';
+
+const { text } = await generateText({
+  model: deepseek('deepseek-v4-flash-vision-exp'),
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'Describe this image.' },
+        {
+          type: 'file',
+          data: new URL('https://example.com/image.webp'),
+          mediaType: 'image/webp',
+          providerOptions: {
+            deepseek: {
+              imageDetail: 'low',
+            } satisfies DeepSeekFilePartProviderOptions,
+          },
+        },
+      ],
+    },
+  ],
+});
+```
+
+Set `fileData: true` on an inline image file part to use DeepSeek's
+`file_data` content-part representation. This preserves the file part's
+`filename`. `fileData` cannot be used with image URLs or `imageDetail`.
+
+DeepSeek accepts JPEG, PNG, GIF, and WebP image inputs. HTTP image URLs can be
+at most 8,192 characters.
+
 ## Model Capabilities
 
 | Model                          | Text Generation     | Object Generation   | Image Input         | Tool Usage          | Tool Streaming      |
 | ------------------------------ | ------------------- | ------------------- | ------------------- | ------------------- | ------------------- |
-| `deepseek-chat`                | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> |
-| `deepseek-reasoner`            | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `deepseek-v4-flash`            | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `deepseek-v4-pro`              | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> |
 | `deepseek-v4-flash-vision-exp` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
 
 <Note>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/deepseek",
-  "version": "2.0.58",
+  "version": "2.0.60",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "3.0.15",
-    "@ai-sdk/provider-utils": "4.0.47"
+    "@ai-sdk/provider-utils": "4.0.49"
   },
   "devDependencies": {
     "@types/node": "20.17.24",

package/src/chat/convert-to-deepseek-chat-messages.ts

@@ -1,28 +1,44 @@
-import type {
-  LanguageModelV3CallOptions,
-  LanguageModelV3Prompt,
-  SharedV3Warning,
+import {
+  InvalidPromptError,
+  UnsupportedFunctionalityError,
+  type LanguageModelV3CallOptions,
+  type LanguageModelV3Prompt,
+  type SharedV3Warning,
 } from '@ai-sdk/provider';
-import { convertToBase64 } from '@ai-sdk/provider-utils';
+import { convertToBase64, parseProviderOptions } from '@ai-sdk/provider-utils';
 import type {
   DeepSeekChatPrompt,
   DeepSeekContentPart,
 } from './deepseek-chat-api-types';
+import { deepseekAssistantMessageProviderOptions } from './deepseek-chat-options';
+import { deepseekFilePartProviderOptions } from './deepseek-file-part-options';
+
+const supportedImageMediaTypes = new Set([
+  'image/gif',
+  'image/jpeg',
+  'image/jpg',
+  'image/png',
+  'image/webp',
+]);
 
-export function convertToDeepSeekChatMessages({
+export async function convertToDeepSeekChatMessages({
   prompt,
   responseFormat,
   modelId,
+  providerOptionsName = 'deepseek',
+  supportsAssistantPrefixCompletion = false,
   supportsStructuredOutputs = false,
 }: {
   prompt: LanguageModelV3Prompt;
   responseFormat: LanguageModelV3CallOptions['responseFormat'];
   modelId: string;
+  providerOptionsName?: string;
+  supportsAssistantPrefixCompletion?: boolean;
   supportsStructuredOutputs?: boolean;
-}): {
+}): Promise<{
   messages: DeepSeekChatPrompt;
   warnings: Array<SharedV3Warning>;
-} {
+}> {
   const isDeepSeekV4 = modelId.includes('deepseek-v4');
   const messages: DeepSeekChatPrompt = [];
   const warnings: Array<SharedV3Warning> = [];
@@ -59,12 +75,34 @@ export function convertToDeepSeekChatMessages({
   }
 
   let index = -1;
-  for (const { role, content } of prompt) {
+  for (const { role, content, providerOptions } of prompt) {
     index++;
 
+    // The assistant schema extends the common message schema, so one parse
+    // validates names for every role and the assistant-only prefix option.
+    const deepseekMessageOptions = await parseProviderOptions({
+      provider: providerOptionsName,
+      providerOptions,
+      schema: deepseekAssistantMessageProviderOptions,
+    });
+
+    if (deepseekMessageOptions?.prefix === true && role !== 'assistant') {
+      throw new InvalidPromptError({
+        prompt,
+        message:
+          'DeepSeek assistant prefix completion requires `prefix: true` on an assistant message.',
+      });
+    }
+
     switch (role) {
       case 'system': {
-        messages.push({ role: 'system', content });
+        messages.push({
+          role: 'system',
+          content,
+          ...(deepseekMessageOptions?.name != null && {
+            name: deepseekMessageOptions.name,
+          }),
+        });
         break;
       }
 
@@ -88,7 +126,13 @@ export function convertToDeepSeekChatMessages({
             }
           }
 
-          messages.push({ role: 'user', content: userContent });
+          messages.push({
+            role: 'user',
+            content: userContent,
+            ...(deepseekMessageOptions?.name != null && {
+              name: deepseekMessageOptions.name,
+            }),
+          });
           break;
         }
 
@@ -100,20 +144,86 @@ export function convertToDeepSeekChatMessages({
             part.type === 'file' &&
             (part.mediaType === 'image' || part.mediaType.startsWith('image/'))
           ) {
-            const mediaType =
+            const filePartOptions = await parseProviderOptions({
+              provider: providerOptionsName,
+              providerOptions: part.providerOptions,
+              schema: deepseekFilePartProviderOptions,
+            });
+
+            const resolvedMediaType =
               part.mediaType === 'image' || part.mediaType === 'image/*'
                 ? 'image/jpeg'
                 : part.mediaType;
 
-            userContent.push({
-              type: 'image_url',
-              image_url: {
-                url:
-                  part.data instanceof URL
-                    ? part.data.toString()
-                    : `data:${mediaType};base64,${convertToBase64(part.data)}`,
-              },
-            });
+            if (!supportedImageMediaTypes.has(resolvedMediaType)) {
+              throw new UnsupportedFunctionalityError({
+                functionality: `DeepSeek image media type ${resolvedMediaType}`,
+                message:
+                  'DeepSeek supports JPEG, PNG, GIF, and WebP image inputs.',
+              });
+            }
+
+            if (part.data instanceof URL) {
+              const url = part.data.toString();
+
+              if (url.length > 8192) {
+                throw new InvalidPromptError({
+                  prompt,
+                  message:
+                    'DeepSeek image URLs must not exceed 8192 characters.',
+                });
+              }
+
+              if (filePartOptions?.fileData === true) {
+                throw new InvalidPromptError({
+                  prompt,
+                  message:
+                    'DeepSeek `fileData` image parts require inline data, not a URL.',
+                });
+              }
+
+              userContent.push({
+                type: 'image_url',
+                image_url: {
+                  url,
+                  ...(filePartOptions?.imageDetail != null && {
+                    detail: filePartOptions.imageDetail,
+                  }),
+                },
+              });
+            } else {
+              const dataUrl = `data:${
+                resolvedMediaType === 'image/jpg'
+                  ? 'image/jpeg'
+                  : resolvedMediaType
+              };base64,${convertToBase64(part.data)}`;
+
+              if (filePartOptions?.fileData === true) {
+                if (filePartOptions.imageDetail != null) {
+                  throw new InvalidPromptError({
+                    prompt,
+                    message:
+                      'DeepSeek `imageDetail` cannot be combined with `fileData`.',
+                  });
+                }
+
+                userContent.push({
+                  type: 'file',
+                  file_data: dataUrl,
+                  ...(part.filename != null && { filename: part.filename }),
+                });
+              } else {
+                userContent.push({
+                  type: 'image_url',
+                  image_url: {
+                    url: dataUrl,
+                    ...(filePartOptions?.imageDetail != null && {
+                      detail: filePartOptions.imageDetail,
+                    }),
+                  },
+                });
+              }
+            }
           } else {
             warnings.push({
               type: 'unsupported',
@@ -122,11 +232,35 @@ export function convertToDeepSeekChatMessages({
           }
         }
 
-        messages.push({ role: 'user', content: userContent });
+        messages.push({
+          role: 'user',
+          content: userContent,
+          ...(deepseekMessageOptions?.name != null && {
+            name: deepseekMessageOptions.name,
+          }),
+        });
 
         break;
       }
       case 'assistant': {
+        if (deepseekMessageOptions?.prefix === true) {
+          if (index !== prompt.length - 1) {
+            throw new InvalidPromptError({
+              prompt,
+              message:
+                'DeepSeek assistant prefix completion requires the prefixed assistant message to be the final message.',
+            });
+          }
+
+          if (!supportsAssistantPrefixCompletion) {
+            throw new UnsupportedFunctionalityError({
+              functionality: 'DeepSeek assistant prefix completion',
+              message:
+                'DeepSeek assistant prefix completion requires a beta base URL ending in `/beta`.',
+            });
+          }
+        }
+
         let text = '';
         let reasoning: string | undefined;
 
@@ -174,6 +308,12 @@ export function convertToDeepSeekChatMessages({
         messages.push({
           role: 'assistant',
           content: text,
+          ...(deepseekMessageOptions?.name != null && {
+            name: deepseekMessageOptions.name,
+          }),
+          ...(deepseekMessageOptions?.prefix === true && {
+            prefix: true,
+          }),
           reasoning_content: reasoning ?? (isDeepSeekV4 ? '' : undefined),
           tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
         });
@@ -182,6 +322,13 @@ export function convertToDeepSeekChatMessages({
       }
 
       case 'tool': {
+        if (deepseekMessageOptions?.name != null) {
+          warnings.push({
+            type: 'unsupported',
+            feature: 'message name on tool messages',
+          });
+        }
+
         for (const toolResponse of content) {
           if (toolResponse.type === 'tool-approval-response') {
             continue;

package/src/chat/convert-to-deepseek-usage.ts

@@ -48,7 +48,7 @@ export function convertDeepSeekUsage(
     },
     outputTokens: {
       total: completionTokens,
-      text: completionTokens - reasoningTokens,
+      text: Math.max(0, completionTokens - reasoningTokens),
       reasoning: reasoningTokens,
     },
     raw: usage,