简介这是一份面向具备一定 Python 基础、希望快速接入 DeepSeek 语言能力的开发者与研究人员的实战型 API 调用指南聚焦从账号注册、密钥获取到接口集成的完整上手路径。内容以单个 docx 文档承载压缩包约 13KB轻量便于查阅覆盖环境准备、OpenAI SDK 与原生 HTTP 请求两种调用方式并延展到请求响应解析、temperature、top_p、max_tokens 等参数调节、streamTrue 流式输出和多轮对话上下文维护等常见开发需求。已有 3165 人学习说明其在中文 AI 接口入门场景中具有一定参考价值。读者可从中获得可直接改造的 Python 示例代码、429 或 503 等异常处理与速率限制提醒、密钥安全及使用规范说明以及官方文档查阅线索。其内容适合聊天机器人、客服系统和智能助理等文本交互项目的初期验证与功能集成也可作为后续复杂业务封装的代码底稿。1. 装完 SDK 跑不通多半是版本没对齐一位开发者把示例代码复制进编辑器pip install openai也执行完了回车之后终端甩出一句AttributeError: module openai has no attribute ChatCompletion。他第一反应是密钥错了换了三个 Key又把网络检查了一遍问题依旧。真正的原因在版本openai 1.x 之后旧的ChatCompletion.create入口已经挪走代码和库对不上报错信息就会把人往错误方向带。接 DeepSeek API 这套环境门槛不高Python 3.8 以上、一个 SDK、一个 API Key 就能跑起来但版本、base_url、密钥这三处只要错一处新手很容易卡半天。下面按实际装机顺序走注册拿 Key、装依赖、两条调用路线、参数与流式输出最后给验证方法和踩坑清单。2. 注册与密钥从创建 API Key 到写进环境变量2.1 账号注册与 API Key 的创建路径入口在 DeepSeek 官网页面上有「API 开放平台」和「开始对话」两个入口要拿 Key 就走前者。注册登录之后左侧或账户菜单里能找到「API Keys」点进去创建。整个流程没有什么技术含量但有两个细节值得强调一是 Key 创建后只在页面上完整显示一次关掉就看不到了必须当场复制二是同一个账号不要反复创建 Key能复用就复用创建多了后期排查调用来源会变成一团乱麻。我一般的操作顺序是这样打开官网进入「API 开放平台」完成账号注册与登录。在「API Keys」页面点创建给 Key 起一个能看出用途的名字比如local-dev、project-a-test。复制出来的字符串先粘到本地一个临时文本里别直接贴进代码文件。立刻写进环境变量或密钥管理工具确认可用后再把临时文本删掉。第 4 步是很多人省掉的结果就是 Key 散落在各种demo.py、test.ipynb里某天提交代码时一起推上去了。这类事故在团队里出过一次就够难受的。2.2 Python 环境与 openai SDK 的安装原教程给的门槛是 Python 3.8 或更高。实际装的时候我建议直接上 3.10 或 3.113.8 已经进入生命周期尾声很多依赖包的新版本不再为它提供轮子装 SDK 时容易碰上编译报错。版本确认和虚拟环境创建一起做# 确认解释器版本低于 3.8 直接换 python3 --version # 建独立虚拟环境避免污染系统 Python python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # 升级 pip老版本 pip 解析依赖时容易失败 python -m pip install --upgrade pip # 装 SDK 和 HTTP 调用要用的 requests pip install openai1.0 requests # 确认装上的实际版本 pip show openaipip show openai这一句很关键它输出的Version决定了你该用哪套写法。DeepSeek API 与 OpenAI 的接口形态兼容所以官方示例里既给了 SDK 写法也给了裸 HTTP 写法。SDK 的好处是异常类型、重试、超时都有现成封装坏处是版本迭代快网上搜到的代码经常是上一代的。版本线对照放在这里装之前先对号入座版本线安装方式调用入口base_url 参数0.28 系列pip install openai0.28.*openai.ChatCompletion.createopenai.api_base1.x 系列pip install openai1.0client.chat.completions.createOpenAI(base_url...)两条线不能混用。项目里如果是老代码要么把依赖锁在 0.28 系列保持不动要么一次性改到 1.x 写法最怕的是锁了 0.28 却复制了 1.x 的示例报错信息看着像密钥问题其实是模块里根本没有那个属性。2.3 密钥不落代码环境变量的三种写法API Key 的正确位置是环境变量不是源码。三种写法按场景选。第一种当前 shell 临时生效适合一次性调试# 注意等号两边不能有空格值不要加引号 export DEEPSEEK_API_KEYsk-你的密钥 echo $DEEPSEEK_API_KEY | head -c 8 # 只打印前 8 位确认非空第二种项目级.env文件适合本地长期开发。装一个python-dotenv把密钥写进.env代码里读环境变量import os from dotenv import load_dotenv # 读取项目根目录的 .env不覆盖已存在的系统环境变量 load_dotenv(overrideFalse) api_key os.environ.get(DEEPSEEK_API_KEY) if not api_key: raise RuntimeError(DEEPSEEK_API_KEY 未设置检查 .env 或 shell 环境)overrideFalse的意思是系统里已经有的变量优先这样 CI 环境注入的密钥不会被本地文件盖掉。.env必须写进.gitignore这一条没有商量余地echo .env .gitignore echo .venv/ .gitignore第三种CI 或容器环境用平台提供的密钥注入功能代码侧完全不用改。三者的共同点是代码里只出现os.environ[...]任何把sk-开头的字符串直接写进源码的做法都是在给自己埋后悔药。3. 两条调用路线OpenAI SDK 与原生 HTTP 请求3.1 用 OpenAI SDK 发第一个请求1.x 系列的写法是先构造 client再调client.chat.completions.create。base_url 指向 DeepSeek 的接口地址SDK 会自己在后面拼路径import os from openai import OpenAI # base_url 写域名即可SDK 内部会补 /chat/completions client OpenAI( api_keyos.environ[DEEPSEEK_API_KEY], base_urlhttps://api.deepseek.com, timeout60.0, # 单次请求超时长文本生成别设太小 max_retries2, # SDK 自带重试处理偶发连接失败 ) resp client.chat.completions.create( modeldeepseek-chat, # 模型名以控制台文档为准 messages[ {role: user, content: 你好请介绍 DeepSeek 的功能。}, ], ) # 取值路径比 0.28 深一层choices - message - content print(resp.choices[0].message.content)几个参数值得单独说。api_key从环境变量取不走字面量base_url是这套调用能不能通的关键写错就是 404timeout在生成长文本时一定要放大默认值下超时断连很常见max_retries让 SDK 自己处理连接抖动比自己写循环省事。如果手上是老项目沿用原文给的 0.28 写法也能跑只是要额外指定接口地址import openai openai.api_key 从环境变量读取别硬编码 openai.api_base https://api.deepseek.com/v1 # 老版本里这个参数叫 api_base response openai.ChatCompletion.create( modeldeepseek-chat, messages[{role: user, content: 你好请介绍 DeepSeek 的功能。}], ) print(response.choices[0].message.content)同一段逻辑1.x 里api_base变成构造参数base_urlChatCompletion.create变成client.chat.completions.create返回对象的取值路径多了一层message。升级 SDK 时按这三处改基本不会漏。3.2 requests 直连 HTTP不装 SDK 也能调有些环境不方便装 SDK比如嵌入式设备、受限的容器镜像或者你只想验证网络和密钥是否通。这时候直接打 HTTP 接口更直接import os import requests url https://api.deepseek.com/v1/chat/completions headers { Authorization: fBearer {os.environ[DEEPSEEK_API_KEY]}, Content-Type: application/json, } payload { model: deepseek-chat, messages: [ {role: user, content: 你好请介绍 DeepSeek 的功能。}, ], temperature: 0.7, } # timeout 必须显式给否则网络卡住时进程会一直挂着 resp requests.post(url, headersheaders, jsonpayload, timeout60) # 非 2xx 直接抛异常避免把错误响应当正常内容解析 resp.raise_for_status() data resp.json() print(data[choices][0][message][content])这里有三处容易写错。Authorization头是Bearer加一个空格再加密钥少了空格就是 401URL 要写完整的/v1/chat/completions和 SDK 里只写域名不一样timeout不给进程在弱网下会一直等排查时表现为「程序没报错但也不出结果」很迷惑。3.3 base_url 与请求地址的对照关系SDK 和 HTTP 两种写法最容易被混淆的就是接口地址整理成一张表调用方式地址写法说明OpenAI SDK 1.xbase_urlhttps://api.deepseek.comSDK 自动拼/chat/completionsOpenAI SDK 0.28openai.api_basehttps://api.deepseek.com/v1老版本习惯带/v1requests 直连https://api.deepseek.com/v1/chat/completions路径写全不拼我的习惯是SDK 统一写域名HTTP 统一写全路径两套代码各自成文件不互相抄。混着抄的结果就是 SDK 里写了全路径变成/chat/completions/chat/completions或者 HTTP 里只写域名少了/v1两种都是 404错误信息还长得差不多。4. 参数调节、响应处理与流式输出4.1 六个生成参数的实际取舍接口开放的可调参数不多但每个都影响输出形态。原教程提到的有temperature、top_p、frequency_penalty、presence_penalty、max_tokens、stop把它们放进一次完整调用resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 写一段产品介绍控制在 100 字内}], temperature0.7, # 0 更确定1 附近更发散 top_p0.9, # 与 temperature 二选一调不要同时大改 max_tokens512, # 输出上限设小了会被截断 frequency_penalty0.0, # 正数抑制重复用词 presence_penalty0.0, # 正数鼓励引入新话题 stop[\n\n], # 命中即停适合固定格式输出 )实际调的时候我遵循两条做结构化抽取、分类、代码生成temperature压到 0 到 0.3做文案、对话、头脑风暴放到 0.7 到 0.9。temperature和top_p不要一起大改否则输出风格的变化没法归因调参就变成了玄学。max_tokens按业务给给对话留 512 到 1024 够用长文生成再往上加但要注意它统计的是输出长度不含输入。4.2 响应结构与 finish_reason 的读法一次成功调用的返回体里最常取的是三样东西正文、结束原因、token 用量。choice resp.choices[0] print(choice.message.content) # 正文 print(choice.finish_reason) # stop / length 等 # 用量统计做成本核算时按这个累计 print(resp.usage.prompt_tokens) # 输入消耗 print(resp.usage.completion_tokens) # 输出消耗 print(resp.usage.total_tokens)finish_reason是stop说明模型正常收尾是length说明撞上了max_tokens上限正文被硬截断这时要么调大上限要么在提示词里明确要求压缩长度。线上出现过「回答只输出一半」的反馈八成是这个值没看。usage字段建议在日志里落一份按天聚合就能看出哪个功能在烧额度。4.3 流式输出streamTrue 的正确消费姿势对话类产品不开流式用户要盯着空屏幕等好几秒。SDK 里加一个streamTrue就切成逐块返回stream client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 用三句话介绍自然语言处理}], streamTrue, ) for chunk in stream: # 末尾可能出现 choices 为空的块先判空再取 if not chunk.choices: continue delta chunk.choices[0].delta if delta.content: # end 不换行flushTrue 立刻刷到终端 print(delta.content, end, flushTrue)delta是增量内容不是全量所以只能追加不能覆盖。flushTrue少了会出现「内容一次性全出来」看着像没生效其实是被标准输出缓冲了。chunk.choices判空也不能省某些收尾块里没有choices直接下标会抛IndexError。4.4 多轮对话上下文自己维护接口本身不记录会话多轮靠每次把历史消息一起发过去。用一个列表累积messages [{role: system, content: 你是一个回答简洁的助手。}] def ask(text: str) - str: messages.append({role: user, content: text}) resp client.chat.completions.create( modeldeepseek-chat, messagesmessages, temperature0.5, ) answer resp.choices[0].message.content # 关键一步把回答也塞回历史否则下一轮模型不知道上文 messages.append({role: assistant, content: answer}) return answer print(ask(我叫什么)) # 第一轮 print(ask(我刚才问了你什么)) # 能答上来说明上下文生效这个列表会越滚越长token 消耗线性上涨。常见做法是只保留最近 N 轮或者超出阈值时把早期对话压成一段摘要再塞回 system 消息。流式模式下也一样只是要在拼接完所有delta.content之后再把完整回答追加进历史别把半截内容存进去。5. 踩坑排查五个高频翻车点5.1 密钥与环境变量相关的三个坑坑一AttributeError: module openai has no attribute ChatCompletion现象代码原样复制导入 SDK 后就报这个错看着像安装不完整。原因装的是 1.x 系列代码用的是 0.28 写法入口函数已经不存在了。解决pip show openai看版本。1.x 就改成client OpenAI(...)加client.chat.completions.create必须留在 0.28 的项目就把依赖写成openai0.28.*并锁进requirements.txt别让 CI 每次装最新版。坑二401提示认证失败现象Key 明明是对的换一个也不行。原因三种情况最常见——复制时把首尾空格或换行带进去了export是在 A 终端执行的运行脚本的是 B 终端.env文件里写了DEEPSEEK_API_KEY sk-xxx等号两边有空格或者值被引号包住读出来带引号。解决先echo $DEEPSEEK_API_KEY | wc -c看长度对不对再在同一个 shell 里跑脚本。.env里等号两边不留空格值不加引号。HTTP 调用还要检查Bearer后面那个空格。坑三404接口找不到现象返回Not Found或者 JSON 里提示路径不存在。原因base_url 写重了或写漏了。SDK 里写了https://api.deepseek.com/v1/chat/completions会变成重复路径HTTP 里只写https://api.deepseek.com少了/v1/chat/completions。解决按第 3 章的对照表统一。SDK 只写到域名HTTP 写全路径。5.2 请求与流式输出相关的两个坑坑四429 和 503调用量一上来就断现象单条测试正常压测或批量跑的时候开始报 429偶尔 503。原因429 是触发了速率限制503 是服务端临时不可用。两者都属于「等一下再试就可能好」的类型但很多人直接except后pass请求就静默丢了。解决按指数退避重试给上限别无限重试。SDK 的异常类型可以直接捕import time from openai import RateLimitError, APIConnectionError def call_with_retry(messages, retries4): for i in range(retries): try: return client.chat.completions.create( modeldeepseek-chat, messagesmessages ) except (RateLimitError, APIConnectionError): if i retries - 1: raise time.sleep(2 ** i) # 1s、2s、4s 递增批量任务还要在客户端做并发控制并发数压到自己配额的一半以下比出了 429 再补救省心得多。坑五流式输出要么一次性全出要么中途断掉现象streamTrue加了但终端还是等全部生成完才显示或者长回答流到一半停住不报错。原因前者是没加flushTrue标准输出缓冲导致看起来没流式后者多半是没设timeout或设得太小长回答超过阈值被连接层掐断。解决print(..., end, flushTrue)client 构造时把timeout调到 60 秒以上长文场景调到 120 秒流式循环里加try/except捕获到中断后把已收到的内容先落库再决定是否重发。排查顺序我一般是固定的先curl确认网络和密钥再看 SDK 版本再看 base_url最后看参数。前两步能解决八成问题直接跳去调 temperature 通常是在浪费时间。6. 装完怎么验证三步自检清单环境装完不等于跑通。我习惯用三步验证从底层往上层走每一步失败都能定位到具体一层。第一步裸 HTTP 探活。这条命令不依赖任何 SDK能排除密钥和网络问题curl -s -X POST https://api.deepseek.com/v1/chat/completions \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -H Content-Type: application/json \ -d {model:deepseek-chat,messages:[{role:user,content:ping}]} \ | head -c 300返回 JSON 里出现choices就说明密钥和地址都对了。返回 401 回去查密钥返回 404 回去查路径。第二步SDK 最小脚本。把第 3 章的示例存成check_sdk.py非流式跑一次确认能打印出正文再打印resp.usage.total_tokens确认用量字段存在。第三步流式与多轮各跑一次。流式看内容是不是逐字出现多轮看第二个问题能不能引用第一个问题的内容。验证项对照如下验证项操作通过标准失败先查密钥有效curl 探活返回含choices的 JSONKey 空格、Bearer 后空格地址正确SDK 最小脚本正常打印正文base_url 是否重复或缺失/v1版本匹配pip show openai版本与写法一致0.28 与 1.x 写法混用流式生效streamTrue脚本内容逐字出现flushTrue、timeout上下文生效连续问两个相关问题第二轮能引用第一轮回答是否追加进 messages我还会额外做一件事把check_sdk.py留在仓库根目录改完配置就跑一遍。有次换机器环境变量没同步脚本一跑就报错比等到业务代码报错再回头查省了半小时。从那以后我每次换环境、升级 SDK、改 base_url都强制先跑这三步再动业务代码。希望这套流程能帮你少走点弯路。本文还有配套的精品资源点击获取
简介这是一份面向具备一定 Python 基础、希望快速接入 DeepSeek 语言能力的开发者与研究人员的实战型 API 调用指南聚焦从账号注册、密钥获取到接口集成的完整上手路径。内容以单个 docx 文档承载压缩包约 13KB轻量便于查阅覆盖环境准备、OpenAI SDK 与原生 HTTP 请求两种调用方式并延展到请求响应解析、temperature、top_p、max_tokens 等参数调节、streamTrue 流式输出和多轮对话上下文维护等常见开发需求。已有 3165 人学习说明其在中文 AI 接口入门场景中具有一定参考价值。读者可从中获得可直接改造的 Python 示例代码、429 或 503 等异常处理与速率限制提醒、密钥安全及使用规范说明以及官方文档查阅线索。其内容适合聊天机器人、客服系统和智能助理等文本交互项目的初期验证与功能集成也可作为后续复杂业务封装的代码底稿。1. 装完 SDK 跑不通多半是版本没对齐一位开发者把示例代码复制进编辑器pip install openai也执行完了回车之后终端甩出一句AttributeError: module openai has no attribute ChatCompletion。他第一反应是密钥错了换了三个 Key又把网络检查了一遍问题依旧。真正的原因在版本openai 1.x 之后旧的ChatCompletion.create入口已经挪走代码和库对不上报错信息就会把人往错误方向带。接 DeepSeek API 这套环境门槛不高Python 3.8 以上、一个 SDK、一个 API Key 就能跑起来但版本、base_url、密钥这三处只要错一处新手很容易卡半天。下面按实际装机顺序走注册拿 Key、装依赖、两条调用路线、参数与流式输出最后给验证方法和踩坑清单。2. 注册与密钥从创建 API Key 到写进环境变量2.1 账号注册与 API Key 的创建路径入口在 DeepSeek 官网页面上有「API 开放平台」和「开始对话」两个入口要拿 Key 就走前者。注册登录之后左侧或账户菜单里能找到「API Keys」点进去创建。整个流程没有什么技术含量但有两个细节值得强调一是 Key 创建后只在页面上完整显示一次关掉就看不到了必须当场复制二是同一个账号不要反复创建 Key能复用就复用创建多了后期排查调用来源会变成一团乱麻。我一般的操作顺序是这样打开官网进入「API 开放平台」完成账号注册与登录。在「API Keys」页面点创建给 Key 起一个能看出用途的名字比如local-dev、project-a-test。复制出来的字符串先粘到本地一个临时文本里别直接贴进代码文件。立刻写进环境变量或密钥管理工具确认可用后再把临时文本删掉。第 4 步是很多人省掉的结果就是 Key 散落在各种demo.py、test.ipynb里某天提交代码时一起推上去了。这类事故在团队里出过一次就够难受的。2.2 Python 环境与 openai SDK 的安装原教程给的门槛是 Python 3.8 或更高。实际装的时候我建议直接上 3.10 或 3.113.8 已经进入生命周期尾声很多依赖包的新版本不再为它提供轮子装 SDK 时容易碰上编译报错。版本确认和虚拟环境创建一起做# 确认解释器版本低于 3.8 直接换 python3 --version # 建独立虚拟环境避免污染系统 Python python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # 升级 pip老版本 pip 解析依赖时容易失败 python -m pip install --upgrade pip # 装 SDK 和 HTTP 调用要用的 requests pip install openai1.0 requests # 确认装上的实际版本 pip show openaipip show openai这一句很关键它输出的Version决定了你该用哪套写法。DeepSeek API 与 OpenAI 的接口形态兼容所以官方示例里既给了 SDK 写法也给了裸 HTTP 写法。SDK 的好处是异常类型、重试、超时都有现成封装坏处是版本迭代快网上搜到的代码经常是上一代的。版本线对照放在这里装之前先对号入座版本线安装方式调用入口base_url 参数0.28 系列pip install openai0.28.*openai.ChatCompletion.createopenai.api_base1.x 系列pip install openai1.0client.chat.completions.createOpenAI(base_url...)两条线不能混用。项目里如果是老代码要么把依赖锁在 0.28 系列保持不动要么一次性改到 1.x 写法最怕的是锁了 0.28 却复制了 1.x 的示例报错信息看着像密钥问题其实是模块里根本没有那个属性。2.3 密钥不落代码环境变量的三种写法API Key 的正确位置是环境变量不是源码。三种写法按场景选。第一种当前 shell 临时生效适合一次性调试# 注意等号两边不能有空格值不要加引号 export DEEPSEEK_API_KEYsk-你的密钥 echo $DEEPSEEK_API_KEY | head -c 8 # 只打印前 8 位确认非空第二种项目级.env文件适合本地长期开发。装一个python-dotenv把密钥写进.env代码里读环境变量import os from dotenv import load_dotenv # 读取项目根目录的 .env不覆盖已存在的系统环境变量 load_dotenv(overrideFalse) api_key os.environ.get(DEEPSEEK_API_KEY) if not api_key: raise RuntimeError(DEEPSEEK_API_KEY 未设置检查 .env 或 shell 环境)overrideFalse的意思是系统里已经有的变量优先这样 CI 环境注入的密钥不会被本地文件盖掉。.env必须写进.gitignore这一条没有商量余地echo .env .gitignore echo .venv/ .gitignore第三种CI 或容器环境用平台提供的密钥注入功能代码侧完全不用改。三者的共同点是代码里只出现os.environ[...]任何把sk-开头的字符串直接写进源码的做法都是在给自己埋后悔药。3. 两条调用路线OpenAI SDK 与原生 HTTP 请求3.1 用 OpenAI SDK 发第一个请求1.x 系列的写法是先构造 client再调client.chat.completions.create。base_url 指向 DeepSeek 的接口地址SDK 会自己在后面拼路径import os from openai import OpenAI # base_url 写域名即可SDK 内部会补 /chat/completions client OpenAI( api_keyos.environ[DEEPSEEK_API_KEY], base_urlhttps://api.deepseek.com, timeout60.0, # 单次请求超时长文本生成别设太小 max_retries2, # SDK 自带重试处理偶发连接失败 ) resp client.chat.completions.create( modeldeepseek-chat, # 模型名以控制台文档为准 messages[ {role: user, content: 你好请介绍 DeepSeek 的功能。}, ], ) # 取值路径比 0.28 深一层choices - message - content print(resp.choices[0].message.content)几个参数值得单独说。api_key从环境变量取不走字面量base_url是这套调用能不能通的关键写错就是 404timeout在生成长文本时一定要放大默认值下超时断连很常见max_retries让 SDK 自己处理连接抖动比自己写循环省事。如果手上是老项目沿用原文给的 0.28 写法也能跑只是要额外指定接口地址import openai openai.api_key 从环境变量读取别硬编码 openai.api_base https://api.deepseek.com/v1 # 老版本里这个参数叫 api_base response openai.ChatCompletion.create( modeldeepseek-chat, messages[{role: user, content: 你好请介绍 DeepSeek 的功能。}], ) print(response.choices[0].message.content)同一段逻辑1.x 里api_base变成构造参数base_urlChatCompletion.create变成client.chat.completions.create返回对象的取值路径多了一层message。升级 SDK 时按这三处改基本不会漏。3.2 requests 直连 HTTP不装 SDK 也能调有些环境不方便装 SDK比如嵌入式设备、受限的容器镜像或者你只想验证网络和密钥是否通。这时候直接打 HTTP 接口更直接import os import requests url https://api.deepseek.com/v1/chat/completions headers { Authorization: fBearer {os.environ[DEEPSEEK_API_KEY]}, Content-Type: application/json, } payload { model: deepseek-chat, messages: [ {role: user, content: 你好请介绍 DeepSeek 的功能。}, ], temperature: 0.7, } # timeout 必须显式给否则网络卡住时进程会一直挂着 resp requests.post(url, headersheaders, jsonpayload, timeout60) # 非 2xx 直接抛异常避免把错误响应当正常内容解析 resp.raise_for_status() data resp.json() print(data[choices][0][message][content])这里有三处容易写错。Authorization头是Bearer加一个空格再加密钥少了空格就是 401URL 要写完整的/v1/chat/completions和 SDK 里只写域名不一样timeout不给进程在弱网下会一直等排查时表现为「程序没报错但也不出结果」很迷惑。3.3 base_url 与请求地址的对照关系SDK 和 HTTP 两种写法最容易被混淆的就是接口地址整理成一张表调用方式地址写法说明OpenAI SDK 1.xbase_urlhttps://api.deepseek.comSDK 自动拼/chat/completionsOpenAI SDK 0.28openai.api_basehttps://api.deepseek.com/v1老版本习惯带/v1requests 直连https://api.deepseek.com/v1/chat/completions路径写全不拼我的习惯是SDK 统一写域名HTTP 统一写全路径两套代码各自成文件不互相抄。混着抄的结果就是 SDK 里写了全路径变成/chat/completions/chat/completions或者 HTTP 里只写域名少了/v1两种都是 404错误信息还长得差不多。4. 参数调节、响应处理与流式输出4.1 六个生成参数的实际取舍接口开放的可调参数不多但每个都影响输出形态。原教程提到的有temperature、top_p、frequency_penalty、presence_penalty、max_tokens、stop把它们放进一次完整调用resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 写一段产品介绍控制在 100 字内}], temperature0.7, # 0 更确定1 附近更发散 top_p0.9, # 与 temperature 二选一调不要同时大改 max_tokens512, # 输出上限设小了会被截断 frequency_penalty0.0, # 正数抑制重复用词 presence_penalty0.0, # 正数鼓励引入新话题 stop[\n\n], # 命中即停适合固定格式输出 )实际调的时候我遵循两条做结构化抽取、分类、代码生成temperature压到 0 到 0.3做文案、对话、头脑风暴放到 0.7 到 0.9。temperature和top_p不要一起大改否则输出风格的变化没法归因调参就变成了玄学。max_tokens按业务给给对话留 512 到 1024 够用长文生成再往上加但要注意它统计的是输出长度不含输入。4.2 响应结构与 finish_reason 的读法一次成功调用的返回体里最常取的是三样东西正文、结束原因、token 用量。choice resp.choices[0] print(choice.message.content) # 正文 print(choice.finish_reason) # stop / length 等 # 用量统计做成本核算时按这个累计 print(resp.usage.prompt_tokens) # 输入消耗 print(resp.usage.completion_tokens) # 输出消耗 print(resp.usage.total_tokens)finish_reason是stop说明模型正常收尾是length说明撞上了max_tokens上限正文被硬截断这时要么调大上限要么在提示词里明确要求压缩长度。线上出现过「回答只输出一半」的反馈八成是这个值没看。usage字段建议在日志里落一份按天聚合就能看出哪个功能在烧额度。4.3 流式输出streamTrue 的正确消费姿势对话类产品不开流式用户要盯着空屏幕等好几秒。SDK 里加一个streamTrue就切成逐块返回stream client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 用三句话介绍自然语言处理}], streamTrue, ) for chunk in stream: # 末尾可能出现 choices 为空的块先判空再取 if not chunk.choices: continue delta chunk.choices[0].delta if delta.content: # end 不换行flushTrue 立刻刷到终端 print(delta.content, end, flushTrue)delta是增量内容不是全量所以只能追加不能覆盖。flushTrue少了会出现「内容一次性全出来」看着像没生效其实是被标准输出缓冲了。chunk.choices判空也不能省某些收尾块里没有choices直接下标会抛IndexError。4.4 多轮对话上下文自己维护接口本身不记录会话多轮靠每次把历史消息一起发过去。用一个列表累积messages [{role: system, content: 你是一个回答简洁的助手。}] def ask(text: str) - str: messages.append({role: user, content: text}) resp client.chat.completions.create( modeldeepseek-chat, messagesmessages, temperature0.5, ) answer resp.choices[0].message.content # 关键一步把回答也塞回历史否则下一轮模型不知道上文 messages.append({role: assistant, content: answer}) return answer print(ask(我叫什么)) # 第一轮 print(ask(我刚才问了你什么)) # 能答上来说明上下文生效这个列表会越滚越长token 消耗线性上涨。常见做法是只保留最近 N 轮或者超出阈值时把早期对话压成一段摘要再塞回 system 消息。流式模式下也一样只是要在拼接完所有delta.content之后再把完整回答追加进历史别把半截内容存进去。5. 踩坑排查五个高频翻车点5.1 密钥与环境变量相关的三个坑坑一AttributeError: module openai has no attribute ChatCompletion现象代码原样复制导入 SDK 后就报这个错看着像安装不完整。原因装的是 1.x 系列代码用的是 0.28 写法入口函数已经不存在了。解决pip show openai看版本。1.x 就改成client OpenAI(...)加client.chat.completions.create必须留在 0.28 的项目就把依赖写成openai0.28.*并锁进requirements.txt别让 CI 每次装最新版。坑二401提示认证失败现象Key 明明是对的换一个也不行。原因三种情况最常见——复制时把首尾空格或换行带进去了export是在 A 终端执行的运行脚本的是 B 终端.env文件里写了DEEPSEEK_API_KEY sk-xxx等号两边有空格或者值被引号包住读出来带引号。解决先echo $DEEPSEEK_API_KEY | wc -c看长度对不对再在同一个 shell 里跑脚本。.env里等号两边不留空格值不加引号。HTTP 调用还要检查Bearer后面那个空格。坑三404接口找不到现象返回Not Found或者 JSON 里提示路径不存在。原因base_url 写重了或写漏了。SDK 里写了https://api.deepseek.com/v1/chat/completions会变成重复路径HTTP 里只写https://api.deepseek.com少了/v1/chat/completions。解决按第 3 章的对照表统一。SDK 只写到域名HTTP 写全路径。5.2 请求与流式输出相关的两个坑坑四429 和 503调用量一上来就断现象单条测试正常压测或批量跑的时候开始报 429偶尔 503。原因429 是触发了速率限制503 是服务端临时不可用。两者都属于「等一下再试就可能好」的类型但很多人直接except后pass请求就静默丢了。解决按指数退避重试给上限别无限重试。SDK 的异常类型可以直接捕import time from openai import RateLimitError, APIConnectionError def call_with_retry(messages, retries4): for i in range(retries): try: return client.chat.completions.create( modeldeepseek-chat, messagesmessages ) except (RateLimitError, APIConnectionError): if i retries - 1: raise time.sleep(2 ** i) # 1s、2s、4s 递增批量任务还要在客户端做并发控制并发数压到自己配额的一半以下比出了 429 再补救省心得多。坑五流式输出要么一次性全出要么中途断掉现象streamTrue加了但终端还是等全部生成完才显示或者长回答流到一半停住不报错。原因前者是没加flushTrue标准输出缓冲导致看起来没流式后者多半是没设timeout或设得太小长回答超过阈值被连接层掐断。解决print(..., end, flushTrue)client 构造时把timeout调到 60 秒以上长文场景调到 120 秒流式循环里加try/except捕获到中断后把已收到的内容先落库再决定是否重发。排查顺序我一般是固定的先curl确认网络和密钥再看 SDK 版本再看 base_url最后看参数。前两步能解决八成问题直接跳去调 temperature 通常是在浪费时间。6. 装完怎么验证三步自检清单环境装完不等于跑通。我习惯用三步验证从底层往上层走每一步失败都能定位到具体一层。第一步裸 HTTP 探活。这条命令不依赖任何 SDK能排除密钥和网络问题curl -s -X POST https://api.deepseek.com/v1/chat/completions \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -H Content-Type: application/json \ -d {model:deepseek-chat,messages:[{role:user,content:ping}]} \ | head -c 300返回 JSON 里出现choices就说明密钥和地址都对了。返回 401 回去查密钥返回 404 回去查路径。第二步SDK 最小脚本。把第 3 章的示例存成check_sdk.py非流式跑一次确认能打印出正文再打印resp.usage.total_tokens确认用量字段存在。第三步流式与多轮各跑一次。流式看内容是不是逐字出现多轮看第二个问题能不能引用第一个问题的内容。验证项对照如下验证项操作通过标准失败先查密钥有效curl 探活返回含choices的 JSONKey 空格、Bearer 后空格地址正确SDK 最小脚本正常打印正文base_url 是否重复或缺失/v1版本匹配pip show openai版本与写法一致0.28 与 1.x 写法混用流式生效streamTrue脚本内容逐字出现flushTrue、timeout上下文生效连续问两个相关问题第二轮能引用第一轮回答是否追加进 messages我还会额外做一件事把check_sdk.py留在仓库根目录改完配置就跑一遍。有次换机器环境变量没同步脚本一跑就报错比等到业务代码报错再回头查省了半小时。从那以后我每次换环境、升级 SDK、改 base_url都强制先跑这三步再动业务代码。希望这套流程能帮你少走点弯路。本文还有配套的精品资源点击获取
