零基础入门 DeepSeek 大模型 API 开发全指南：max_tokens 停止序列 temperature 系统提示四大核心参数详解、调优实战与两种 Prompt 写法效果对比教程

调用 DeepSeek 大模型 API 的四大核心可控参数为max_tokens、stop停止序列、temperature、system系统提示分别控制输出长度、停止时机、随机程度、角色设定。max_tokens是输出 token 数的上限设太小会截断内容设太大浪费算力生成 token 越多接口响应耗时越长。stop停止序列可以让模型遇到指定字符串时立刻停止生成适合控制结构化输出的边界但停止符本身不会出现在返回结果中。temperature控制输出随机性0 最保守稳定、适合计算分析类任务1 最自然多样、适合创意写作类任务。system系统提示用于设定模型全局角色与规则指令效果比写在用户消息中更稳定全部指令堆在 user 消息里也能运行但规范性和效果可控性更差。生产环境推荐「system 放角色规则 user 放具体任务」的拆分写法是兼顾效果、规范与可维护性的最优方案。一、课程学习目标本文面向零基础接触大模型 API 开发的读者完整覆盖 DeepSeek 接口四大核心参数的原理、用法与调优技巧同时对比两种常见的 Prompt 消息写法。学完后你将掌握理解max_tokens参数的作用与调优方法使用temperature参数精准控制模型输出的随机性掌握stop停止序列的用途与使用注意事项理解系统提示System prompt的角色与最佳实践分清两种消息结构写法的差异能根据场景选择最优方案二、开发环境初始化DeepSeek 完全兼容 OpenAI 接口规范使用官方 OpenAI Python SDK 即可完成调用标准初始化代码如下from dotenv import load_dotenv from openai import OpenAI import os 加载环境变量 load_dotenv() my_api os.getenv(DEEPSEEK_API_KEY) 初始化 DeepSeek 客户端 client OpenAI( api_keymy_api, base_urlhttps://api.deepseek.com )三、核心参数一max_tokens最大令牌数3.1 什么是 Token大语言模型不是以完整单词 / 汉字为单位处理文本而是以token令牌为最小单位。你可以把 token 理解为文本碎片模型先把输入文本拆成 token再逐 token 生成输出内容。英文场景1 个 token ≈ 3.5 个英文字符中文场景1 个 token ≈ 1~2 个汉字3.2 参数作用max_tokens用来设置模型输出内容的最大 token 数量上限。设得太小模型生成到一半就被强制截断内容不完整设得太大模型不会强行填满上限只是获得了更大的生成空间内容短的时候依然会提前自然结束3.3 两种停止状态通过响应对象的finish_reason可以判断模型停止的原因停止原因含义说明stop自然停止模型认为内容已经说完主动结束生成length截断停止输出 token 数达到了max_tokens上限被强制截断3.4 为什么要调整 max_tokens考量维度具体说明API 配额限制token 用量会计入接口额度合理设置可控制成本、避免超量性能效率生成 token 越多耗时越长、算力消耗越大合理设值可优化响应速度输出质量上限太低会截断内容导致信息缺失上限太高会造成不必要的性能开销3.5 性能规律生成 token 数量与耗时基本呈正相关生成的内容越长接口响应时间越久。例如生成 100token 仅需 1 秒左右生成 4000token 则需要近 30 秒。3.6 参数汇总表参数项详细说明参数名称max_tokens核心作用限制模型输出的最大 token 数量取值范围1 ~ 接口允许的最大值DeepSeek 上限为 393216常见问题取值过小导致输出截断、内容不完整调优建议简单问答设 200-500长文本生成设 1000-4000避免无意义设超大值使用max_tokensmax_tokens参数用于设置模型生成 token 数量的上限。举个例子如果我们让模型写一首诗并将max_tokens设为 10模型会开始生成内容当生成的 token 数达到 10 时会立即停止这通常会导致输出被截断、内容不完整。我们来试一下truncated_response client.chat.completions.create( modeldeepseek-v4-flash, max_tokens10, messages[ {role: user, content: 写一首诗} ] ) print(truncated_response.choices[0].message.content)输出示例为你写一首小诗晨实际运行结果会有随机波动但一定会出现截断。模型刚开始写诗生成 10 个 token 后就被迫停止。我们还可以通过响应对象的finish_reason属性查看模型停止生成的原因。在这个场景下它的值为length代表模型因达到最大 token 限制而停止。print(truncated_response.choices[0].finish_reason)输出length当然如果我们把max_tokens设为更大的值通常就能得到完整的诗作longer_poem_response client.chat.completions.create( modeldeepseek-v4-flash, max_tokens500, messages[ {role: user, content: 写一首诗} ] ) print(longer_poem_response.choices[0].message.content)输出示例《心音》在静谧的时分当世界渐渐沉寂我听见心底的低语——温柔的字句轻轻摇曳。...这是max_tokens设为 500 时模型生成的完整内容。 如果查看这个响应的finish_reason会看到值为stop代表模型自然完成了生成内容已经输出完毕主动停止了续写。print(longer_poem_response.choices[0].finish_reason)输出stop需要注意的是模型在生成时并不知道max_tokens的存在。调整max_tokens不会改变模型的生成逻辑只是给了模型更大的生成空间数值大时或强制截断输出数值小时。同样重要的是增大max_tokens不代表模型一定会生成对应数量的 token。比如我们让模型讲一个笑话哪怕把max_tokens设为 1000输出也通常远少于 1000 个 token。response client.chat.completions.create( modeldeepseek-v4-flash, max_tokens1000, messages[{role: user, content: 讲一个笑话}] ) print(response.choices[0].message.content)输出示例分享一个经典冷笑话为什么科学家不信任原子因为万物都是原子凑出来的print(response.usage.completion_tokens)输出55在上面的例子中我们把max_tokens设为 1000但最终生成的内容只有 55 个 token。设置上限只是划定了最大边界不代表模型会填满这个上限。性能演示我们来直观感受一下生成 token 数量对性能的影响。下面的函数让模型生成一段长对话分别使用 3 档不同的max_tokens各运行一次打印实际生成的 token 数与耗时。import time def compare_num_tokens_speed(): token_counts [100, 1000, 4096] task 请生成一段至少 5000 字的长对话两个角色讨论社交媒体对心理健康的影响。 两位角色观点不同展开理性、深入的辩论。 for num_tokens in token_counts: start_time time.time() response client.chat.completions.create( modeldeepseek-v4-flash, max_tokensnum_tokens, messages[{role: user, content: task}] ) end_time time.time() execution_time end_time - start_time print(f生成 token 数{response.usage.completion_tokens}) print(f执行耗时{execution_time:.2f} 秒\n) compare_num_tokens_speed()示例输出生成 token 数100执行耗时1.51 秒生成 token 数1000执行耗时8.33 秒生成 token 数3433执行耗时28.80 秒可以清晰看到模型生成的 token 越多所需的时间就越长。停止序列Stop sequences另一个实用的参数是stop停止序列它允许我们传入一个或多个字符串作为停止标记。当模型生成的内容中出现这些字符串时会立即停止继续生成。你可以把它理解为如果生成了这个标记就立刻停下不要再输出后续内容。下面是一个不使用停止序列的请求示例response client.chat.completions.create( modeldeepseek-v4-flash, max_tokens500, messages[{role: user, content: 生成一个表示人物的 JSON 对象包含姓名、邮箱、手机号三个字段。}] ) print(response.choices[0].message.content)输出示例这是一个表示人物信息的 JSON 对象示例{name: 张三,email: zhangsanexample.com,phoneNumber: 123-456-7890}在这个示例中JSON 对象包含三个键值对分别对应...可以看到模型确实生成了 JSON 对象但后面还附带了额外的解释文字。如果我们希望模型输出完 JSON 的闭合符}后就立即停止可以加入stop参数response client.chat.completions.create( modeldeepseek-v4-flash, max_tokens500, messages[{role: user, content: 生成一个表示人物的 JSON 对象包含姓名、邮箱、手机号三个字段。}], stop[}] ) print(response.choices[0].message.content)输出示例这是一个表示人物信息的 JSON 对象示例{name: 张三,email: zhangsanexample.com,phone: 555-1234重要提示注意生成的输出中不包含作为停止序列的}本身。如果需要完整可用的 JSON需要我们手动把结尾的}补回去。我们同样可以通过finish_reason查看模型停止的原因此时值为stop代表触发了停止序列。print(response.choices[0].finish_reason)输出stop多个停止序列stop参数支持传入多个停止序列模型只要遇到其中任意一个就会立即停止生成。下面的示例让模型写诗当生成字母b或c时停止共运行 3 次def generate_random_letters_3_times(): for i in range(3): response client.chat.completions.create( modeldeepseek-v4-flash, max_tokens500, messages[{role: user, content: 写一首诗}], stop[b, c] ) print(f第 {i1} 次响应停止原因{response.choices[0].finish_reason}) generate_random_letters_3_times()示例输出第 1 次响应停止原因stop第 2 次响应停止原因stop第 3 次响应停止原因stop三次生成都因为触发了停止序列而提前结束。实际业务中我们通常不会用单个字母作为停止序列更多用于结构化输出、固定格式截断等场景。温度Temperaturetemperature参数用于控制生成内容的随机性与创造性。在 DeepSeek 中它的取值范围为 0~2默认值为 1。数值越高输出越多样化、越不可预测措辞变化越丰富数值越低输出越偏向确定性更倾向于选择概率最高的表述与答案。模型生成文本时会预测下一个 token 的概率分布。temperature的作用就是在采样下一个 token 前对这个概率分布进行缩放温度接近 0 时概率分布会被压尖高概率的 token 权重被进一步放大模型输出更稳定、更保守优先选择最稳妥的答案。温度接近 2 时概率分布会被拉平低概率 token 的出现概率提升模型输出更随机、更有探索性内容更具创造力与多样性。什么时候调整温度一个通用的选型原则分析类任务使用接近 0 的温度创意类任务使用接近 1 的温度。温度效果演示我们通过一个简单示例直观感受差异。分别使用温度 0 和温度 1让模型 3 次生成外星行星的名字要求只输出单个单词def demonstrate_temperature(): temperatures [0, 1] for temperature in temperatures: print(f使用 temperature {temperature} 调用 3 次) print() for i in range(3): response client.chat.completions.create( modeldeepseek-v4-flash, max_tokens100, temperaturetemperature, messages[{role: user, content: 想一个外星行星的名字仅输出单个单词。}] ) print(f第 {i1} 次响应{response.choices[0].message.content.strip()}) demonstrate_temperature()输出示例使用 temperature 0 调用 3 次第 1 次响应Xendor第 2 次响应Xendor第 3 次响应Xendor使用 temperature 1 调用 3 次第 1 次响应Xyron第 2 次响应Xandar第 3 次响应Zyrcon可以看到温度为 0 时三次输出几乎完全一致。需要注意即使 temperature0也不代表 100% 完全确定依然可能存在微小波动但和温度为 1 的情况相比差异非常明显。系统提示System promptsystem角色的提示词是对话中的可选配置用于给模型设定高层指令、定义角色身份、补充背景信息从而为整段对话定下基调与规则。关于系统提示的核心要点它是可选参数但对设定对话语气、上下文与角色定位非常有用。它作用于整段对话会影响该次对话中模型的所有回复。借助系统提示可以统一约束模型行为无需在每条用户消息中重复指令。通常建议将语气设定、角色设定、全局规则放在系统提示中而详细的任务指令、外部输入内容如文档、示例样本放在用户消息中效果更佳。系统提示只需要在对话开头设置一次不需要在每轮用户消息中重复。我们来试一个例子message client.chat.completions.create( modeldeepseek-v4-flash, max_tokens1000, messages[ {role: system, content: 你是一位贴心的外语老师所有回复都使用法语。}, {role: user, content: 你好很高兴认识你} ] ) print(message.choices[0].message.content)输出示例Bonjour ! Je suis ravi de vous rencontrer. Comment allez-vous aujourdhui ?四、核心参数二stop停止序列4.1 参数作用stop参数允许传入一个或多个字符串作为停止标记。模型生成内容时只要遇到这些字符串就会立刻停止继续生成相当于给输出划定了明确的结束边界。4.2 核心特性触发即停只要生成内容中出现停止序列立刻终止后续输出符不返回停止序列本身不会出现在最终返回的内容里需要手动补回支持多个可以同时传入多个停止符任意一个被触发都会停止4.3 典型使用场景生成 JSON 时设置stop[}]让模型输出完 JSON 结构就停止避免后面附带多余解释生成编号列表时设置stop[4.]保证模型只输出前 3 条不会多生成额外条目结构化数据提取时用固定分隔符作为停止标记精准控制输出范围4.4 参数汇总表参数项详细说明参数名称stop核心作用遇到指定字符串时立即终止生成传入格式字符串列表支持单个或多个停止序列重要特性停止符本身不会包含在返回结果中常见用途结构化输出截断、固定条数控制、格式边界限定五、核心参数三temperature温度5.1 参数作用temperature控制模型输出的随机性与创造性取值范围 0~2默认值为 1。数值越低输出越保守、越确定优先选概率最高的表述重复度高数值越高输出越随机、越有创造力冷门表述的出现概率提升内容多样性强5.2 底层原理模型每次生成下一个 token 时会给出所有候选词的概率分布。temperature 本质是对这个概率分布做缩放接近 0概率分布被压尖高概率词权重进一步放大输出高度稳定接近 2概率分布被拉平低概率词也有机会被选中输出天马行空5.3 取值与场景对应表temperature 取值输出特性适用场景0 ~ 0.3高度确定、保守稳定、重复度高数学计算、代码生成、数据提取、客观问答0.7 ~ 1.0自然流畅、均衡合理、有轻微变化日常对话、通用文案、内容总结1.2 ~ 2.0随机性强、脑洞大、多样性高创意写作、诗歌、头脑风暴、发散构思通用原则分析类任务用低温创意类任务用常温 / 高温。5.4 参数汇总表参数项详细说明参数名称temperature核心作用控制输出内容的随机性与创造性取值范围0 ~ 2默认值为 1极端表现0 最稳定2 最发散选型建议求准用低温求新用高温六、核心参数四system系统提示6.1 参数作用system角色的提示词用于给模型设定全局身份、基调和规则相当于在对话开始前给模型立人设它会影响整段对话中模型的所有回复。6.2 使用要点适合放角色身份、语气要求、全局规则、背景设定不适合放具体任务指令、外部文档内容、示例样本这类内容放 user 消息效果更好只需设置一次不需要在每一轮用户消息中重复6.3 参数汇总表参数项详细说明角色名称system核心作用设定模型全局角色、语气与规则作用范围整段对话生效影响所有轮次回复推荐存放内容角色设定、风格要求、全局约束不推荐存放具体任务指令、输入数据、示例样本七、专题两种 Prompt 消息写法深度对比在实际开发中很多新手会纠结角色设定和任务指令是分开写在 system 和 user 里还是全部堆在 user 消息里下面结合你的代码做完整对比。7.1 两种写法代码示例写法 A拆分式system user 分工messages[ {role: system, content: f你是{topic}领域的专家请围绕该主题生成有深度的思考题以编号列表形式输出。}, {role: user, content: f生成 {num_questions} 个关于{topic}的问题用编号列表呈现。} ]写法 B合并式全部写在 user 里messages[ {role: user, content: f你是{topic}领域的专家请围绕该主题生成有深度的思考题以编号列表形式输出。生成 {num_questions} 个关于{topic}的问题用编号列表呈现。} ]7.2 多维度对比表对比维度写法 Asystemuser 拆分写法 B全部放 user指令遵循度更高角色设定全局生效模型更稳定地遵循人设一般角色指令容易被后续任务内容稀释输出稳定性强多次调用风格、格式一致性更好弱容易出现格式跑偏、人设弱化代码可读性好角色与任务职责分明便于维护修改差所有指令混在一起长 prompt 时难以调试运行兼容性完全兼容是官方推荐的标准写法也能运行属于非规范写法多轮对话适配优system 只需要写一次后续只传 user 消息差每一轮都要重复角色设定浪费 token适合场景生产项目、多轮对话、要求稳定输出快速测试、单轮简单调用、临时调试7.3 效果差异说明从你实际运行的结果也能看出两种写法都能成功生成问题但拆分写法下模型的输出格式更规整、角色感更强思考题的深度与结构一致性更好合并写法虽然也能出结果但格式波动更大偶尔会出现多余的开场白、编号不规范等问题。7.4 最终结论快速调试、临时写小脚本两种写法都能用合并写法写起来更快正式项目、追求稳定可控强烈推荐 system user 的拆分写法这是行业通用的最佳实践可维护性与效果都更优八、实战练习与参考实现练习要求编写generate_questions函数接收topic主题和num_questions问题数量两个参数生成指定数量的深度思考题编号列表形式输出要求使用max_tokens限制长度、system设定角色、stop控制条数边界参考代码标准规范写法def generate_questions(topic: str, num_questions: int 3): response client.chat.completions.create( modeldeepseek-v4-flash, max_tokens1000, messages[ {role: system, content: f你是{topic}领域的专家请围绕该主题生成有深度的思考题以编号列表形式输出。}, {role: user, content: f生成 {num_questions} 个关于{topic}的问题用编号列表呈现。} ], stop[f{num_questions 1}.] ) print(response.choices[0].message.content) 调用示例 generate_questions(topic自由意志, num_questions3)完整可运行代码含初始化与两种写法对比from dotenv import load_dotenv from openai import OpenAI import os 加载环境变量 load_dotenv() my_api os.getenv(DEEPSEEK_API_KEY) 初始化 DeepSeek 客户端 client OpenAI( api_keymy_api, base_urlhttps://api.deepseek.com ) def generate_questions(topic: str, num_questions: int): # 写法 A拆分式system user 分工—— 推荐 # questions client.chat.completions.create( # modeldeepseek-v4-flash, # max_tokens1000, # messages[ # {role: system, content: f你是{topic}领域的专家请围绕该主题生成有深度的思考题以编号列表形式输出。}, # {role: user, content: f生成 {num_questions} 个关于{topic}的问题用编号列表呈现。} # ] # ) # 写法 B合并式全部写在 user 里—— 当前使用 questions client.chat.completions.create( modeldeepseek-v4-flash, max_tokens1000, messages[ {role: user, content: f你是{topic}领域的专家请围绕该主题生成有深度的思考题以编号列表形式输出。生成 {num_questions} 个关于{topic}的问题用编号列表呈现。} ] ) print(questions.choices[0].message.content) generate_questions(蔡徐坤, 4)九、写在最后四大核心参数是驾驭大模型 API 的基础理解它们的原理与适用场景就能精准控制输出的长度、风格、格式与角色。再配合规范的消息结构写法就能写出既稳定又易维护的调用代码。 新手学习建议先从默认参数跑通基础调用再逐个调整参数观察效果变化动手调试是理解参数作用最快的方式。