使用 AI SDK 集成 DeepSeekai-sdk/deepseek 提供方完整实战指南【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/aiai-sdk/deepseek是 AI SDKTypeScript 的 AI 工具包官方提供的 DeepSeek 提供方封装负责把 DeepSeek 平台的对话补全、推理、多模态与文件上传能力统一接入 AI SDK 的generateText、streamText、tool等标准接口。本文以 packages/deepseek/README.md 为主线结合完整文档 content/providers/01-ai-sdk-providers/30-deepseek.mdx 与提供方源码讲清安装、Provider 实例配置、模型调用、推理、Beta 特性、元数据与文件上传读完即可在项目中落地 DeepSeek 模型。一、认识 ai-sdk/deepseekAI SDK 采用一个核心 多个提供方的架构核心库ai提供统一的generateText/streamText/generateObject等高层 API而ai-sdk/deepseek只负责把 DeepSeek 的 API 请求与响应转换成 AI SDK 标准的LanguageModelV4实现。当前仓库中该包版本为 3.0.42见 package.json要求 Node.js 22运行时依赖ai-sdk/provider与ai-sdk/provider-utils两个 workspace 包并以zod作为 peer 依赖。从源码结构看整个包划分为几个清晰模块见 packages/deepseek/srcdeepseek-provider.tsProvider 工厂负责 API Key、Base URL、请求头、fetch 的装配chat/语言模型核心包括请求参数构建、消息转换、工具准备、流式解析、用量换算files/DeepSeek Files API 封装用于图片上传与引用index.ts包的公开出口导出deepSeek、createDeepSeek及全部选项类型。二、安装与前置准备DeepSeek 提供方位于ai-sdk/deepseek模块安装命令npm i ai-sdk/deepseek使用前你需要申请 API Key从 DeepSeek Platform 的 API Keys 页面获取。该 Key 默认通过DEEPSEEK_API_KEY环境变量读取详见下文 Provider 实例一节确认模型 ID当前文档推荐使用deepseek-v4-flash或deepseek-v4-pro。值得注意的是文档明确指出 DeepSeek 已于 2026 年 7 月 24 日退役deepseek-chat与deepseek-reasoner这两个别名自定义及遗留模型 ID 仍可作为字符串传入以兼容自定义端点部署在 Vercel如果你使用 Vercel 的 AI Gateway可以直接访问 DeepSeek以及数百个其他提供方模型无需额外安装包、API Key 或额外成本。此外官方建议在使用 Claude Code、Cursor 这类编码 Agent 时把 AI SDK skill 加入仓库方便 Agent 直接获得本项目的最佳实践npx skills add vercel/ai三、Provider 实例默认实例与自定义工厂3.1 导入默认实例包默认导出一个已配置好的 Provider 实例deepSeek同时保留了小写deepseek作为兼容别名源码见 index.tsimport { deepSeek } from ai-sdk/deepseek;3.2 用 createDeepSeek 自定义配置需要自定义配置时导入createDeepSeek并传入设置import { createDeepSeek } from ai-sdk/deepseek; const deepSeek createDeepSeek({ apiKey: process.env.DEEPSEEK_API_KEY ?? , });可用的可选设置项如下与源码中 DeepSeekProviderSettings 一一对应设置项类型说明与默认值apiKeystring通过Authorization请求头发送的 API Key默认读取DEEPSEEK_API_KEY环境变量baseURLstringAPI 调用的 URL 前缀默认https://api.deepseek.comheadersRecordstring, string附加到每次请求的自定义请求头fetch(input: RequestInfo, init?: RequestInit) PromiseResponse自定义 fetch 实现可用来做请求拦截中间件或提供测试用实现3.3 工厂实现的底层细节从 createDeepSeek 实现 可以看到几个关键行为Base URL 规范化withoutTrailingSlash(options.baseURL ?? https://api.deepseek.com)会去掉末尾斜杠所有请求 URL 在此基础上拼接路径如/chat/completions请求头装配getHeaders()使用loadApiKey解析 API Key显式传入优先否则读DEEPSEEK_API_KEY环境变量并通过withUserAgentSuffix为 User-Agent 追加ai-sdk/deepseek/${VERSION}标识Beta 能力开关当baseURL以/beta结尾时supportsAssistantPrefixCompletion与supportsStrictToolCalls两个能力标志会被置为true见 deepseek-provider.ts这是下文聊天前缀补全和严格工具调用两个 Beta 特性的前提不支持的能力直接抛错embeddingModel、imageModel、textEmbeddingModel均抛出NoSuchModelError——DeepSeek 提供方目前只提供语言模型和文件上传接口可序列化语言模型实现了WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE静态方法deepseek-chat-language-model.ts可被 AI SDK 的工作流workflow系统序列化保存。四、语言模型模型 ID 与三种创建方式4.1 模型 ID当前一等公民模型 ID 定义在 deepseek-chat-language-model-options.tsdeepseek-v4-flash文本生成主力模型deepseek-v4-pro更高性能的 V4 推理模型deepseek-v4-flash-vision-exp实验性视觉模型支持图片输入。类型定义中还保留了(string {})逃生舱因此自定义端点或遗留模型 ID 仍可作为字符串传入只是不会出现在编辑器的类型提示中。4.2 创建模型的三种写法import { deepSeek } from ai-sdk/deepseek; import { generateText } from ai; const { text } await generateText({ model: deepSeek(deepseek-v4-flash), prompt: Write a vegetarian lasagna recipe for 4 people., });也可以使用.chat()或.languageModel()工厂方法const model deepSeek.chat(deepseek-v4-flash); // 或 const model deepSeek.languageModel(deepseek-v4-flash);三种写法在源码中是等价的——Provider 上直接调用、chat、languageModel三个入口都指向同一个createLanguageModel见 deepseek-provider.ts返回统一的DeepSeekChatLanguageModel实例。该模型实现了LanguageModelV4规范specificationVersion v4支持generateText之外的所有 AI SDK Core 接口例如streamText流式生成。五、Provider 级调用选项深度解析DeepSeek 模型支持以下可选的 provider 选项通过providerOptions.deepseek传入完整类型与校验见 deepseek-chat-language-model-options.ts选项类型说明logprobsboolean返回生成内容与推理 token 的对数概率结果放在providerMetadata.deepseek.logprobstopLogprobsnumber每个 token 位置返回最可能的 N 个 token取值0~20设置后自动启用logprobsuserIdstring不透明的终端用户标识DeepSeek 用于内容安全追踪、KV 缓存隔离与调度隔离。必须匹配^[a-zA-Z0-9_-]$且不超过 512 字符禁止包含姓名、邮箱等隐私信息thinking{ type: enabled \| disabled }控制 V4 模型的思维链推理模式开关reasoningEffortlow \| high \| max控制 V4 推理模型的思考强度strictJsonSchemaboolean结构化输出是否使用严格 JSON Schema 校验默认true仅当端点支持 JSON Schema 响应格式时生效一个覆盖主要选项的完整示例import { deepSeek, type DeepSeekLanguageModelChatOptions, } from ai-sdk/deepseek; import { generateText } from ai; const { text, reasoning } await generateText({ model: deepSeek(deepseek-v4-flash), prompt: How many rs are in the word strawberry?, providerOptions: { deepseek: { userId: tenant_123-user, thinking: { type: enabled }, reasoningEffort: high, } satisfies DeepSeekLanguageModelChatOptions, }, });5.1 兼容性映射与警告为了向后兼容运行时传入的旧值会被自动映射到规范值并返回 compatibility 警告实现见 deepseek-chat-language-model.ts 与 L301-L363thinking.type: adaptive→enabledreasoningEffort: medium→highxhigh→max顶层 AI SDK 的reasoning设置如minimal/medium/xhigh也会被映射到 DeepSeek 的low/high/max。5.2 已废弃与无效的参数行为frequencyPenalty/presencePenaltyDeepSeek 已废弃顶层这两个设置。Provider 会将其从请求中省略并在使用时返回 deprecation 警告见 deepseek-chat-language-model.tstemperature/topP思考模式开启时V4 模型默认开启这两个参数不生效Provider 会省略它们并返回 unsupported 警告。显式设置thinking.type: disabled后才能使用temperature和topP见 deepseek-chat-language-model.tstopK/seed同样不受支持传入即返回 unsupported 警告。这些警告会随generateText/streamText的结果返回便于调用方迁移到规范用法。六、消息级选项参与者名称Message NamesDeepSeek 支持在 system、user、assistant 消息上附加可选的参与者名称。在每条消息的providerOptions.deepseek.name中设置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, }, }, ], });同样的消息选项也适用于streamTextimport { 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); }使用注意与源码 convert-to-deepseek-chat-messages.ts 的行为一致未设置时名称会被省略name必须是字符串DeepSeek不支持在 tool 消息上设置名称Provider 会忽略该设置并返回 unsupported-feature 警告消息名称中不要包含不必要的个人或可识别信息。七、推理能力ReasoningDeepSeek V4 模型支持思维链推理推理文本通过流式接口暴露。streamText返回的流中会依次出现reasoning与text两类 partimport { deepSeek } from ai-sdk/deepseek; import { streamText } from ai; const result streamText({ model: deepSeek(deepseek-v4-pro), prompt: How many rs are in the word strawberry?, }); for await (const part of result.stream) { if (part.type reasoning) { // 这是推理文本 console.log(Reasoning:, part.text); } else if (part.type text) { // 这是最终答案 console.log(Answer:, part.text); } }底层实现上Provider 把 DeepSeek 响应中的reasoning_content字段转换为 AI SDK 的 reasoning 内容类型非流式响应中推理内容作为reasoningcontent 排在文本之前见 deepseek-chat-language-model.ts流式响应则按顺序发射reasoning-start/reasoning-delta/reasoning-end并在文本或工具调用开始时自动结束推理段见 deepseek-chat-language-model.ts。对于多轮对话消息转换逻辑还会处理推理历史V4 模型要求每轮 assistant 消息都携带reasoning_content字段缺失时回填空字符串而 R1 类旧模型在用户消息之前的推理内容会被跳过见 convert-to-deepseek-chat-messages.ts。八、Beta 特性一聊天前缀补全Chat Prefix CompletionDeepSeek 的聊天前缀补全Beta会续写最后一条 assistant 消息的内容。使用方式用 beta Base URL 创建 Provider并在目标 assistant 消息的 provider 选项中设置prefix: trueimport { 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, }, }, ], });约束条件违反时请求会在发出前失败带前缀的消息必须是 assistant 消息且必须是 prompt 中的最后一条消息配置的baseURL必须以/beta结尾使用代理时同样要求该特性处于 Beta 阶段行为可能发生变化。源码中对应校验位于 convert-to-deepseek-chat-messages.ts而supportsAssistantPrefixCompletion标志来自 deepseek-provider.ts。九、Beta 特性二严格工具调用Strict Tool CallsDeepSeek 的严格工具调用模式Beta同样要求 beta Base URL并为请求中的每一个函数工具设置strict: trueimport { 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 }), }), }, });源码 deepseek-prepare-tools.ts 中有两条硬性校验存在strict: true的工具但 Base URL 不以/beta结尾 → 本地直接抛出UnsupportedFunctionalityError请求中只要有一个严格工具所有函数工具都必须设置strict: true否则抛出混合严格与非严格工具调用错误。此外该文件还处理了toolChoice的映射auto、none、required原样透传tool类型转换为 DeepSeek 的{ type: function, function: { name } }Provider 定义的工具type: provider不被支持并返回警告。十、Provider Metadata缓存命中与响应指纹DeepSeek 通过result.providerMetadata暴露系统指纹与上下文缓存用量import { deepSeek } from ai-sdk/deepseek; import { generateText } from ai; const result await generateText({ model: deepSeek(deepseek-v4-flash), prompt: Your prompt here, }); console.log(result.providerMetadata); // 示例输出 // { // deepseek: { // systemFingerprint: fp_eaab8d114b_prod0820_fp8_kvcache, // promptCacheHitTokens: 1856, // promptCacheMissTokens: 5, // }, // }字段含义字段说明systemFingerprint响应对应的后端配置指纹promptCacheHitTokens命中了缓存的输入 token 数promptCacheMissTokens未命中缓存的输入 token 数对于流式响应Provider 会持续追踪每个 chunk 中的指纹最终返回最后一个非空值见 deepseek-chat-language-model.ts。利用promptCacheHitTokens可以观测系统提示词等稳定前缀的 KV 缓存命中情况从而优化请求成本。10.1 Chat Response 元数据DeepSeek 还会在providerMetadata.deepseek中保留 Chat Completions 响应的提供方专属字段responseObjectchat.completion或chat.completion.chunkchoiceIndex被选中的响应 choice 索引messageRole响应消息的角色若提供toolCallTypes每个返回工具调用的类型。这些字段之所以保留在 provider metadata 中是因为它们是 DeepSeek Chat Completions 响应的专属信息而非 AI SDK 共享结果字段组装逻辑见 deepseek-chat-language-model.ts 与 L710-L741。10.2 错误码映射Provider 会把 DeepSeek 的错误码/错误类型映射为标准的 HTTP 状态码与可重试标记见 deepseek-chat-language-model.ts例如rate_limit_exceeded→ 429可重试、insufficient_quota→ 429不可重试、server_error/api_error→ 500可重试、overloaded_error→ 503可重试、timeout→ 504可重试、invalid_api_key→ 401、model_not_found→ 404、context_length_exceeded→ 400 等。十一、多模态图片输入与文件上传11.1 内联图片与图片 URL对于内联图片或图片 URL可以在文件 part 的 provider 选项中设置图片处理细节。DeepSeek 支持low、high、original、auto四种档位类型定义见 deepseek-file-part-options.tsimport { 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, }, }, ], }, ], });图片输入的限制由 convert-to-deepseek-chat-messages.ts 与 L170-L241 保障支持 JPEG、PNG、GIF、WebP 四种图片格式HTTP 图片 URL 最长 8192 字符超限会抛出InvalidPromptError支持fileData: true选项内联图片改用 DeepSeek 的file_data内容表示会保留文件 part 的filename但不能与图片 URL 或imageDetail同时使用。11.2 通过 DeepSeek Files API 上传图片使用 Files API 上传图片后把返回的 provider 引用直接传给视觉模型可以避免每次请求重复发送图片字节import { deepSeek, type DeepSeekFilesOptions } from ai-sdk/deepseek; import { generateText, uploadFile } from ai; import { readFile } from node:fs/promises; const { providerReference, mediaType } await uploadFile({ api: deepSeek.files(), data: await readFile(./image.png), filename: image.png, providerOptions: { deepseek: { expiresAfter: 3600, } satisfies DeepSeekFilesOptions, }, }); const { text } await generateText({ model: deepSeek(deepseek-v4-flash-vision-exp), messages: [ { role: user, content: [ { type: text, text: Describe this image. }, { type: file, mediaType: mediaType ?? image/png, data: providerReference, }, ], }, ], });上传相关的硬性限制在 deepseek-files.ts 与 validateFileUpload 中实现均在发送请求前本地校验约束取值支持格式JPEG.jpg/.jpeg、PNG、GIF、WebP单文件大小上限64 MiB文件名长度上限512 字符expiresAfter取值范围3600 秒1 小时~ 2,592,000 秒30 天不指定则文件永久保留其他行为细节image/jpg媒体类型别名可接受当媒体类型是通用的如application/octet-stream时会回退使用受支持的文件名扩展名判定即使声明类型或文件名看起来是图片可识别的非图片内容也会被拒绝上传成功后要求响应中包含有效的文件 ID并校验返回的object、purpose判别字段及数字元数据其余响应元数据保持可选以兼容不完整响应——缺失值不会进入providerMetadata缺失的响应文件名会回退到uploadFile传入的filename。十二、模型能力矩阵模型文本生成对象生成图片输入工具调用工具流式输出deepseek-v4-flash✅✅❌✅✅deepseek-v4-pro✅✅❌✅✅deepseek-v4-flash-vision-exp✅✅✅✅✅其中对象生成对应 AI SDK 的generateObject/streamObject结构化输出请求构建时会把响应格式转换为 DeepSeek 的response_format带 schema 时使用json_schemastrict默认取strictJsonSchema ?? true否则回退为json_object并自动向消息注入系统提示词Return JSON...见 deepseek-chat-language-model.ts 与 convert-to-deepseek-chat-messages.ts。除上述三个模型外任何可用的提供方模型 ID 都可以作为字符串传入。十三、小结ai-sdk/deepseek把 DeepSeek 平台的对话补全、思维链推理、严格工具调用、KV 缓存观测、多模态图片与 Files API 文件上传完整地抽象进了 AI SDK 的统一接口。从 deepseek-provider.ts 的工厂装配到 deepseek-chat-language-model.ts 的参数构建、流式解析与错误映射再到 convert-to-deepseek-chat-messages.ts 的消息转换与 deepseek-files.ts 的文件上传你可以在上述源码中进一步验证本文涉及的每个行为。结合 README 中的安装示例与本文的完整选项说明你已经可以用三行代码接入deepseek-v4-flash/deepseek-v4-pro完成文本生成通过providerOptions精确控制推理开关、思考强度与缓存隔离使用 Beta Base URL 体验前缀补全与严格工具调用通过providerMetadata观测缓存命中与系统指纹借助 Files API 实现一次上传、多次引用的图片问答流程。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考