尧图网站开发 
简介面向有一定编程基础、希望深入掌握大模型API调用的自然语言处理开发者这份PDF系统梳理了DeepSeek API从账号注册与API Key获取到安装requests库、配置基础URL与鉴权参数、构造包含model和messages的JSON请求体、发送请求并解析返回数据的完整工程链路。内容不是简单贴代码而是结合简单文本生成、情感分析、代码生成等真实案例逐一拆解请求头与请求体的组装方式、状态码校验、异常处理与常见坑点并对API Key的妥善保存给出实用建议能有效避开初学阶段容易踩的弯路。压缩包为单文件PDF共1个pdf文档整体仅659KB便携易读可随时查阅。已有2353人浏览学习尤其适合有一定Python基础的开发者用于搭建智能客服、内容创作工具或探索AI在教育、医疗等行业的落地场景是快速上手DeepSeek API并形成工程化调用能力的实用参考资料。1. DeepSeek API 和网页聊天不是一回事先把三个事实确认清楚DeepSeek API 和你在网页聊天框里用的 DeepSeek 不是一回事它按 token 计费鉴权失败一次也可能算一次钱。把它接进生产系统前有三个事实先确认清楚——入口在 platform.deepseek.com 而不是聊天页API Key 只完整显示一次对话补全端点返回的是 choices[0].message.content 而不是 text。情感分析、代码生成没有专用接口都要靠提示词在通用对话接口上实现。下面这份拆解照着我调通的流程走从注册、拿 Key、发请求到把输出接进业务每步都留着踩坑记录。适合第一次接大模型 API 的 Python 开发者也适合被半路接口卡住想让后端跑起来的熟手。2. 账号、密钥与请求头把调用 DeepSeek API 的身份底座打牢2.1 注册入口与账号验证先分清开放平台和聊天应用浏览器打开https://platform.deepseek.com这是 DeepSeek 开放平台不是网页聊天版。很多新手在聊天页面的侧栏里找 API Key找了半天找不到就是因为入口弄混了。开放平台右上角有注册入口一般用邮箱或者手机号设置密码后系统会发一封验证邮件。点完邮件里的验证链接账号才算激活。注册完首次登录控制台会展示几个核心板块API Keys、用量统计、余额和充值入口。DeepSeek API 是典型按量计费服务每次请求根据 token 数计费调用前应该先看一眼余额。见过不少同事注册完一个测试循环跑了二十分钟第二天收到欠费通知虽然金额不大但会影响开发体验。好在平台有用量页面可以按时间范围查看消耗。我的习惯是在控制台把账户信息、模型列表截个图保存到团队的 wiki后续排查 400 和 401 时对照很快。官方文档入口在平台页面的“文档”或“技术文档”区域里面会写明当前计费规格和模型列表。项目上线前记得给团队成员开子账号或统一管理 Key不要把个人 Key 贴在共享文档里。2.2 获取 API Key一次性显示、环境变量与轮换方式登录开放平台后在“API Keys”页面点击“创建 API Key”。输入名称后系统会生成一串以sk-开头的字符串。这里要注意完整明文只在弹窗里显示一次。关掉弹窗再去查只能看到密钥的尾部掩码所以必须立刻保存。我第一次用 DeepSeek API 时把 Key 复制到了聊天窗口后来粘贴代码时带了换行调了半天 401。后来改成环境变量方案把 Key 和代码彻底分开再没被这种低级问题卡住。在 Mac/Linux 下可以写入 shell 配置export DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxx如果你用.env文件管理本地配置配合python-dotenv读取pip install python-dotenvfrom dotenv import load_dotenv import os load_dotenv() api_key os.getenv(DEEPSEEK_API_KEY) if not api_key: raise RuntimeError(DEEPSEEK_API_KEY 未设置)这段代码的逻辑是先加载.env再从环境变量读取 Key没有 Key 就直接报错避免后续请求发送空值。.env文件里第一行写DEEPSEEK_API_KEYsk-xxx并且要把.env加进.gitignore。关于轮换如果怀疑 Key 泄露直接在平台删除旧 Key再创建新 Key。旧 Key 删除的瞬间会失效所有依赖它的请求立即返回 401。所以上线环境下换 Key 的正确顺序是先更新服务端配置并重启确认新 Key 能请求成功再删除旧 Key。删除动作放在最后能少一次线上事故。2.3 请求头里的两个字段Authorization 与 Content-Type一切就绪后最基础的请求头长这样Authorization: Bearer sk-xxxxxxxx Content-Type: application/jsonAuthorization 使用 Bearer Token 标准。很多接口文档会写成Bearer your_api_key其中空格不能省略。如果你把 Key 直接放在没有 Bearer 前缀的字段里服务端会认为请求未认证。Content-Type 则声明请求体是 JSON缺了这个字段可能导致服务端拒绝解析。Python 里我把 headers 固定成字典避免每次散着传import os import requests api_key os.environ[DEEPSEEK_API_KEY] headers { Authorization: fBearer {api_key}, Content-Type: application/json, Accept: application/json, } url https://api.deepseek.com/chat/completions payload { model: deepseek-chat, messages: [ {role: user, content: 你好} ] } resp requests.post(url, headersheaders, jsonpayload, timeout30) print(resp.status_code) print(resp.text)这里jsonpayload会把字典自动序列化成 JSON 字符串。timeout30表示连接和读取的超时上限。打印resp.status_code是排查问题的第一动作200 才继续往下解析非 200 时把resp.text打出来看错误体。后面章节会展开错误体里的字段。3. 用 requests 发出第一个请求URL、消息体与响应解析的每一步3.1 虚拟环境与 pip 安装先避免环境污染DeepSeek API 的 Python 客户端其实就是一个 HTTP 客户端requests 库够用。我不建议一上来就装openaiSDK先把裸请求调通再决定要不要封装。在干净目录里建虚拟环境mkdir -p ~/deepseek-demo cd ~/deepseek-demo python -m venv venv source venv/bin/activate pip install requests这里有个 Python 3.11 以后的高频坑pip install requests报错error: externally-managed-environment。这不是 requests 的问题而是系统 Python 限制全局安装。解决方法是启用 venv或者只用当前虚拟环境。不要图方便加--break-system-packages那会让系统 Python 越来越乱。装完后验证一下python -c import requests; print(requests.__version__)3.2 最小可运行请求URL、model 与 messagesDeepSeek 的对话补全端点是POST https://api.deepseek.com/chat/completions。有些资料会写/v1/chat/completions以官方文档为准我这边按不带/v1的 URL 验证过。一个最小的请求写出来就是这样import os import requests api_key os.environ[DEEPSEEK_API_KEY] url https://api.deepseek.com/chat/completions headers { Authorization: fBearer {api_key}, Content-Type: application/json, } payload { model: deepseek-chat, messages: [ {role: system, content: 你是一个善于用简短句子回答问题的助手。}, {role: user, content: 介绍一下 Python 列表推导式。} ], max_tokens: 256, temperature: 0.7, } resp requests.post(url, headersheaders, jsonpayload, timeout60) print(resp.status_code) print(resp.text)逻辑说明model参数决定用哪个模型。我日常用的是deepseek-chat具体模型名以文档为准网上旧资料里写的模型名未必还有效。messages是数组每个元素至少含role和content。rolesystem用来设定助手人设roleuser是输入。max_tokens限制生成的 token 数量。256 足够回答列表推导式避免返回太长超出预算。temperature控制随机性。0.7 是通用默认档文本创作可以调高到 1.0要得到确定结果就调到 0.2 甚至 0。发送请求后先不要急着解析。print(resp.text)可以把原始 JSON 完整打出来。我第一次对接时想当然地按resp.json()[choices][0][text]取值结果 KeyError耐心看完响应才意识到它叫message.content。3.3 响应结构与 usage 字段不只取文本一个标准的成功响应核心结构如下{ choices: [ { index: 0, message: { role: assistant, content: Python 列表推导式是一种从可迭代对象构建新列表的简洁写法。 }, finish_reason: stop } ], usage: { prompt_tokens: 28, completion_tokens: 32, total_tokens: 60 } }提取内容的代码data resp.json() content data[choices][0][message][content] print(content)finish_reason值得检查。它返回stop代表正常结束length代表生成被max_tokens截断。如果你发现摘要突然停在半句多半是max_tokens设小了而不是模型坏了。usage里是每一次调用的 token 消耗Prompt 和补全价格往往不同所以两边要分开记录。处理非 200 状态时我封装了一个最简单的函数def chat(messages, modeldeepseek-chat, **kwargs): headers { Authorization: fBearer {os.environ[DEEPSEEK_API_KEY]}, Content-Type: application/json, } payload {model: model, messages: messages, **kwargs} resp requests.post( https://api.deepseek.com/chat/completions, headersheaders, jsonpayload, timeout(10, 120), ) if resp.status_code ! 200: raise RuntimeError(fDeepSeek API error {resp.status_code}: {resp.text}) data resp.json() if data[choices][0][finish_reason] length: print(警告返回内容超过 max_tokens 上限) return data[choices][0][message][content]timeout(10, 120)拆开了连接超时和读取超时连不上 10 秒断掉等待生成最多给 120 秒长文本生成确实可能超过半分钟。4. 文本生成、情感分析、代码生成三个真实场景的调用姿势与参数调优4.1 文本生成用 system prompt 定角色别让模型临场发挥智能客服、内容摘要、邮件草稿本质上都是文本生成。区别在于 system prompt 有没有把角色和输出要求交代清楚。假设要做一个“技术问答客服”可以这样构造消息messages [ {role: system, content: 你是某云产品的技术支持工程师。回答要克制、准确不要编造产品能力。无法回答时直接说需要转人工。}, {role: user, content: 我们的 API 返回 429一般是什么原因} ] answer chat(messages, temperature0.3) print(answer)把 temperature 降到 0.3客服回答就会更收敛不会每次换一套说辞。如果你做内容创作工具想把输出写得有风格再把 temperature 调到 0.9 左右。这个参数是大模型应用里最容易调出不同效果的一个值得来回试。内容摘要场景更简单只要把原文粘贴进 user 消息再在 system 里约束摘要长度和格式messages [ {role: system, content: 你只做摘要。输出不超过 200 字不输出其他解释。}, {role: user, content: original_text} ]这里有一个常见的坑长文本要提前算好 token 占用模型输入输出共享上下文窗口。如果文章太长会直接触发上下文超限后续调用全部 400。常见做法是先对输入做截断或分段摘要。4.2 情感分析没有独立接口用提示词让模型输出 JSON留意一下网上有些教程会写POST /sentiment-analysis这种专用接口DeepSeek API 官方并没有这个端点。它是一个通用对话模型任务都靠提示词表达。情感分析的正确姿势是让模型输出 JSON然后程序解析。prompt 判断下面文本的情感倾向只输出 JSON 对象不要输出其他内容。 JSON 格式 {sentiment: positive 或 negative 或 neutral, confidence: 0.0 到 1.0 之间的小数} 文本这部电影的剧情非常精彩演员的表演也十分出色我非常喜欢 resp chat([ {role: user, content: prompt} ], temperature0, max_tokens100) print(resp)temperature0是为了让输出尽量确定情感分析这种分类任务不希望太发散。max_tokens100足够容纳一个 JSON 对象避免模型絮叨。模型通常会返回{sentiment: positive, confidence: 0.95}如果你的程序需要继续处理用json.loads解析import json try: result json.loads(resp) sentiment result[sentiment] confidence float(result[confidence]) except (json.JSONDecodeError, KeyError, TypeError) as e: print(解析失败原始输出如下) print(resp) raise e这段容错代码不是摆设。模型偶尔会在 JSON 外增加解释性文字或把数字写成0.95字符串。直接把响应喂给json.loads会翻车所以一旦解析失败先打印原始输出定位问题再考虑调整提示词。4.3 代码生成用严格指令和低 temperature 拿到可运行代码代码生成同样走 Chat Completions没有名为/code-generation的专用接口。要拿到“直接可运行”的代码关键在于角色约束和输出格式。messages [ {role: system, content: 你是一名资深 Python 工程师。用户要求写代码时只输出可运行的代码不要解释不要使用 Markdown 代码块围栏。}, {role: user, content: 写一个计算两个数之和的函数。} ] code chat(messages, temperature0.2, max_tokens512) print(code)将 temperature 调低到 0.2是为了减少变量命名和写法的随机性。max_tokens512对一个简单函数是足够的。如果模型不遵守“不要使用围栏”的约定返回了带 python 的文本我们需要清洗一下import re def strip_code_fence(raw: str) - str: raw raw.strip() if raw.startswith(): raw re.sub(r^[a-zA-Z]*\n, , raw) raw re.sub(r\n$, , raw) return raw code strip_code_fence(code)为什么还要写清洗函数因为生产环境接到的模型输出是不可控的。大模型对指令的遵守程度不是 100%在后端直接执行未经清洗的代码会有语法风险。清洗后最好再用compile(code, generated, exec)做一次语法校验确认无语法错误才落盘或执行。5. 调用 DeepSeek API 的常见问题与避坑记录认证、超时、限流和参数陷阱5.1 401 UnauthorizedKey 看着没错但认证就是不通过现象请求返回 401Body 里提示认证失败或 API key invalid。你在控制台复制了好几次肉眼看着和配置里的一模一样。原因最常见的是复制时带了前导或尾部空格、换行或者环境变量没有真正生效。我用.env文件时值两侧不小心多了一个空格程序读到的 Key 和真实 Key 就差这一个空格请求全部 401。其次是 Headers 里漏了Bearer前缀只有一串裸 Key。解决第一件事在代码里打印密钥的 reprprint(repr(os.environ[DEEPSEEK_API_KEY]))输出如果是 sk-xxx\n就说明有空格或换行清洗.env后重新加载。第二件事检查请求头格式确认Authorization长这样Bearer sk-xxx。第三件事如果还不行回控制台“API Keys”页面看密钥状态是否之前误删了。5.2 请求超时模型还在生成程序先掐断了现象requests.exceptions.ReadTimeout或者ConnectTimeout程序在长时间等待后直接抛异常前面做的重试逻辑又把它当成真正的失败。原因连接超时通常和本地网络限制有关比如办公室防火墙对长连接的干扰读取超时则可能是请求文本太长、服务器生成内容耗时超过了 timeout。很多教程把 timeout 设为 10 秒这只适合早期简单模型对现代大模型来说 10 秒远远不够。解决把 timeout 拆开连接 10 秒、读取 120 秒resp requests.post(url, headersheaders, jsonpayload, timeout(10, 120))另外给请求加重试。429、5xx 适合短退避重试但 400 和 401 不应该重试重试也只是浪费时间。简单写法import time for attempt in range(3): try: resp requests.post(url, headersheaders, jsonpayload, timeout(10, 120)) if resp.status_code 429: time.sleep(2 ** attempt) continue resp.raise_for_status() break except requests.exceptions.RequestException: time.sleep(2 ** attempt) if attempt 2: raise5.3 400 参数错误模型名、messages 结构和上下文超限现象返回 400错误信息类似invalid request、model not found或this models maximum context length is ...。你检查了 payload感觉字段名称都是对的。原因模型名写成了过时或错误的字符串。DeepSeek API 没有deepseek-code这类独立模型代码生成也走deepseek-chat。还有messages结构不合法content必须是字符串如果误传成 list 就会报错。上下文超限是因为 prompt token 数加 max_tokens 超过模型上下文窗口。解决先在控制台文档页确认当前可用的模型名和上下文上限。调试时打印 payload人工看一遍print(json.dumps(payload, ensure_asciiFalse, indent2))如果超长做分段摘要或截断max_input_chars 30000 truncated original_text[:max_input_chars]这里的 30000 只是我的经验值具体要以文档为准。关键是截断要放在发送之前不要等 400 再被动处理。5.4 429 与配额不足不是 Key 问题是请求太快或余额不够现象返回 429 Too Many Requests或者提示 insufficient quota / balance insufficient。明明刚刚还调通了一个请求再跑一个循环就全部失败。原因短时间并发请求超过接口限流阈值比如循环里一秒钟发几十个请求必然触发限流如果是余额不足提示状态码可能不是 429而是 402 或 403具体看平台定义。解决在循环里加最小间隔控制并发节奏是基本功for text in texts: response requests.post(url, headersheaders, jsonpayload, timeout(10, 120)) if response.status_code 429: time.sleep(1) continue # ... 处理响应 time.sleep(0.5)如果是余额问题去控制台充值即可。关键是把“限流”和“余额不足”在代码里分开处理限流可以退避重试余额不足应该直接告警不要盲目重试把账单刷高。6. 上线前最后一道检查curl 冒烟、usage 核价与 JSON 结构校验6.1 一行 curl 把环境验干净每次部署新环境我不用 Python 先跑而是用 curl 直接打一发最小请求。这样可以排除 requests、venv、代码逻辑的干扰只看 Key 和网络是否正常。curl -s https://api.deepseek.com/chat/completions \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -H Content-Type: application/json \ -d {model:deepseek-chat,messages:[{role:user,content:ping}],max_tokens:16}-s是静默模式不打印进度条-d后面是 JSON 请求体。正常情况下会返回一个完整 chat completionchoices[0].message.content可能是一句话。这一步通过说明 Key、网络、URL 都没问题剩下的就是应用层的问题。6.2 用 usage 字段把成本记下来DeepSeek API 按 token 计费prompt 和 completion 价格不同。我在封装函数里强制记录 usagedata resp.json() usage data.get(usage, {}) log.append({ prompt_tokens: usage.get(prompt_tokens, 0), completion_tokens: usage.get(completion_tokens, 0), })批量任务完成后再汇总python -c import json log json.load(open(api_log.json)) print(sum(item[prompt_tokens] for item in log)) print(sum(item[completion_tokens] for item in log)) 这样每次发布新 prompt 前都能对比前后成本。我就是靠这个发现某个 prompt 把输入 token 撑大了三倍及时精简才没让月度账单失控。6.3 JSON 响应校验别让模型输出直接进业务大模型返回的内容不该直接信任。凡是让模型输出 JSON 的场景我都用一个校验函数收口def parse_model_json(content: str): content content.strip() if content.startswith(): content re.sub(r^[a-zA-Z]*\n|\n$, , content) try: return json.loads(content) except json.JSONDecodeError: idx content.find({) if idx 0: return json.loads(content[idx:]) raise这个函数先剥掉 Markdown 围栏再尝试整段解析如果整段失败就截取第一个{后面的部分很多模型输出前面的解释文字截出来就是合法 JSON。从那以后我每次把 DeepSeek API 接进项目都会强制走一遍 curl 冒烟、usage 记录、JSON 解析校验这三步。特别是之前有一次生产环境的 prompt 改成了带 Markdown 的输出前端解析 JSON 直接崩了我才养成这个习惯只要模型参与输出后处理必须兜底。希望帮到你。本文还有配套的精品资源点击获取 
简介面向有一定编程基础、希望深入掌握大模型API调用的自然语言处理开发者这份PDF系统梳理了DeepSeek API从账号注册与API Key获取到安装requests库、配置基础URL与鉴权参数、构造包含model和messages的JSON请求体、发送请求并解析返回数据的完整工程链路。内容不是简单贴代码而是结合简单文本生成、情感分析、代码生成等真实案例逐一拆解请求头与请求体的组装方式、状态码校验、异常处理与常见坑点并对API Key的妥善保存给出实用建议能有效避开初学阶段容易踩的弯路。压缩包为单文件PDF共1个pdf文档整体仅659KB便携易读可随时查阅。已有2353人浏览学习尤其适合有一定Python基础的开发者用于搭建智能客服、内容创作工具或探索AI在教育、医疗等行业的落地场景是快速上手DeepSeek API并形成工程化调用能力的实用参考资料。1. DeepSeek API 和网页聊天不是一回事先把三个事实确认清楚DeepSeek API 和你在网页聊天框里用的 DeepSeek 不是一回事它按 token 计费鉴权失败一次也可能算一次钱。把它接进生产系统前有三个事实先确认清楚——入口在 platform.deepseek.com 而不是聊天页API Key 只完整显示一次对话补全端点返回的是 choices[0].message.content 而不是 text。情感分析、代码生成没有专用接口都要靠提示词在通用对话接口上实现。下面这份拆解照着我调通的流程走从注册、拿 Key、发请求到把输出接进业务每步都留着踩坑记录。适合第一次接大模型 API 的 Python 开发者也适合被半路接口卡住想让后端跑起来的熟手。2. 账号、密钥与请求头把调用 DeepSeek API 的身份底座打牢2.1 注册入口与账号验证先分清开放平台和聊天应用浏览器打开https://platform.deepseek.com这是 DeepSeek 开放平台不是网页聊天版。很多新手在聊天页面的侧栏里找 API Key找了半天找不到就是因为入口弄混了。开放平台右上角有注册入口一般用邮箱或者手机号设置密码后系统会发一封验证邮件。点完邮件里的验证链接账号才算激活。注册完首次登录控制台会展示几个核心板块API Keys、用量统计、余额和充值入口。DeepSeek API 是典型按量计费服务每次请求根据 token 数计费调用前应该先看一眼余额。见过不少同事注册完一个测试循环跑了二十分钟第二天收到欠费通知虽然金额不大但会影响开发体验。好在平台有用量页面可以按时间范围查看消耗。我的习惯是在控制台把账户信息、模型列表截个图保存到团队的 wiki后续排查 400 和 401 时对照很快。官方文档入口在平台页面的“文档”或“技术文档”区域里面会写明当前计费规格和模型列表。项目上线前记得给团队成员开子账号或统一管理 Key不要把个人 Key 贴在共享文档里。2.2 获取 API Key一次性显示、环境变量与轮换方式登录开放平台后在“API Keys”页面点击“创建 API Key”。输入名称后系统会生成一串以sk-开头的字符串。这里要注意完整明文只在弹窗里显示一次。关掉弹窗再去查只能看到密钥的尾部掩码所以必须立刻保存。我第一次用 DeepSeek API 时把 Key 复制到了聊天窗口后来粘贴代码时带了换行调了半天 401。后来改成环境变量方案把 Key 和代码彻底分开再没被这种低级问题卡住。在 Mac/Linux 下可以写入 shell 配置export DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxx如果你用.env文件管理本地配置配合python-dotenv读取pip install python-dotenvfrom dotenv import load_dotenv import os load_dotenv() api_key os.getenv(DEEPSEEK_API_KEY) if not api_key: raise RuntimeError(DEEPSEEK_API_KEY 未设置)这段代码的逻辑是先加载.env再从环境变量读取 Key没有 Key 就直接报错避免后续请求发送空值。.env文件里第一行写DEEPSEEK_API_KEYsk-xxx并且要把.env加进.gitignore。关于轮换如果怀疑 Key 泄露直接在平台删除旧 Key再创建新 Key。旧 Key 删除的瞬间会失效所有依赖它的请求立即返回 401。所以上线环境下换 Key 的正确顺序是先更新服务端配置并重启确认新 Key 能请求成功再删除旧 Key。删除动作放在最后能少一次线上事故。2.3 请求头里的两个字段Authorization 与 Content-Type一切就绪后最基础的请求头长这样Authorization: Bearer sk-xxxxxxxx Content-Type: application/jsonAuthorization 使用 Bearer Token 标准。很多接口文档会写成Bearer your_api_key其中空格不能省略。如果你把 Key 直接放在没有 Bearer 前缀的字段里服务端会认为请求未认证。Content-Type 则声明请求体是 JSON缺了这个字段可能导致服务端拒绝解析。Python 里我把 headers 固定成字典避免每次散着传import os import requests api_key os.environ[DEEPSEEK_API_KEY] headers { Authorization: fBearer {api_key}, Content-Type: application/json, Accept: application/json, } url https://api.deepseek.com/chat/completions payload { model: deepseek-chat, messages: [ {role: user, content: 你好} ] } resp requests.post(url, headersheaders, jsonpayload, timeout30) print(resp.status_code) print(resp.text)这里jsonpayload会把字典自动序列化成 JSON 字符串。timeout30表示连接和读取的超时上限。打印resp.status_code是排查问题的第一动作200 才继续往下解析非 200 时把resp.text打出来看错误体。后面章节会展开错误体里的字段。3. 用 requests 发出第一个请求URL、消息体与响应解析的每一步3.1 虚拟环境与 pip 安装先避免环境污染DeepSeek API 的 Python 客户端其实就是一个 HTTP 客户端requests 库够用。我不建议一上来就装openaiSDK先把裸请求调通再决定要不要封装。在干净目录里建虚拟环境mkdir -p ~/deepseek-demo cd ~/deepseek-demo python -m venv venv source venv/bin/activate pip install requests这里有个 Python 3.11 以后的高频坑pip install requests报错error: externally-managed-environment。这不是 requests 的问题而是系统 Python 限制全局安装。解决方法是启用 venv或者只用当前虚拟环境。不要图方便加--break-system-packages那会让系统 Python 越来越乱。装完后验证一下python -c import requests; print(requests.__version__)3.2 最小可运行请求URL、model 与 messagesDeepSeek 的对话补全端点是POST https://api.deepseek.com/chat/completions。有些资料会写/v1/chat/completions以官方文档为准我这边按不带/v1的 URL 验证过。一个最小的请求写出来就是这样import os import requests api_key os.environ[DEEPSEEK_API_KEY] url https://api.deepseek.com/chat/completions headers { Authorization: fBearer {api_key}, Content-Type: application/json, } payload { model: deepseek-chat, messages: [ {role: system, content: 你是一个善于用简短句子回答问题的助手。}, {role: user, content: 介绍一下 Python 列表推导式。} ], max_tokens: 256, temperature: 0.7, } resp requests.post(url, headersheaders, jsonpayload, timeout60) print(resp.status_code) print(resp.text)逻辑说明model参数决定用哪个模型。我日常用的是deepseek-chat具体模型名以文档为准网上旧资料里写的模型名未必还有效。messages是数组每个元素至少含role和content。rolesystem用来设定助手人设roleuser是输入。max_tokens限制生成的 token 数量。256 足够回答列表推导式避免返回太长超出预算。temperature控制随机性。0.7 是通用默认档文本创作可以调高到 1.0要得到确定结果就调到 0.2 甚至 0。发送请求后先不要急着解析。print(resp.text)可以把原始 JSON 完整打出来。我第一次对接时想当然地按resp.json()[choices][0][text]取值结果 KeyError耐心看完响应才意识到它叫message.content。3.3 响应结构与 usage 字段不只取文本一个标准的成功响应核心结构如下{ choices: [ { index: 0, message: { role: assistant, content: Python 列表推导式是一种从可迭代对象构建新列表的简洁写法。 }, finish_reason: stop } ], usage: { prompt_tokens: 28, completion_tokens: 32, total_tokens: 60 } }提取内容的代码data resp.json() content data[choices][0][message][content] print(content)finish_reason值得检查。它返回stop代表正常结束length代表生成被max_tokens截断。如果你发现摘要突然停在半句多半是max_tokens设小了而不是模型坏了。usage里是每一次调用的 token 消耗Prompt 和补全价格往往不同所以两边要分开记录。处理非 200 状态时我封装了一个最简单的函数def chat(messages, modeldeepseek-chat, **kwargs): headers { Authorization: fBearer {os.environ[DEEPSEEK_API_KEY]}, Content-Type: application/json, } payload {model: model, messages: messages, **kwargs} resp requests.post( https://api.deepseek.com/chat/completions, headersheaders, jsonpayload, timeout(10, 120), ) if resp.status_code ! 200: raise RuntimeError(fDeepSeek API error {resp.status_code}: {resp.text}) data resp.json() if data[choices][0][finish_reason] length: print(警告返回内容超过 max_tokens 上限) return data[choices][0][message][content]timeout(10, 120)拆开了连接超时和读取超时连不上 10 秒断掉等待生成最多给 120 秒长文本生成确实可能超过半分钟。4. 文本生成、情感分析、代码生成三个真实场景的调用姿势与参数调优4.1 文本生成用 system prompt 定角色别让模型临场发挥智能客服、内容摘要、邮件草稿本质上都是文本生成。区别在于 system prompt 有没有把角色和输出要求交代清楚。假设要做一个“技术问答客服”可以这样构造消息messages [ {role: system, content: 你是某云产品的技术支持工程师。回答要克制、准确不要编造产品能力。无法回答时直接说需要转人工。}, {role: user, content: 我们的 API 返回 429一般是什么原因} ] answer chat(messages, temperature0.3) print(answer)把 temperature 降到 0.3客服回答就会更收敛不会每次换一套说辞。如果你做内容创作工具想把输出写得有风格再把 temperature 调到 0.9 左右。这个参数是大模型应用里最容易调出不同效果的一个值得来回试。内容摘要场景更简单只要把原文粘贴进 user 消息再在 system 里约束摘要长度和格式messages [ {role: system, content: 你只做摘要。输出不超过 200 字不输出其他解释。}, {role: user, content: original_text} ]这里有一个常见的坑长文本要提前算好 token 占用模型输入输出共享上下文窗口。如果文章太长会直接触发上下文超限后续调用全部 400。常见做法是先对输入做截断或分段摘要。4.2 情感分析没有独立接口用提示词让模型输出 JSON留意一下网上有些教程会写POST /sentiment-analysis这种专用接口DeepSeek API 官方并没有这个端点。它是一个通用对话模型任务都靠提示词表达。情感分析的正确姿势是让模型输出 JSON然后程序解析。prompt 判断下面文本的情感倾向只输出 JSON 对象不要输出其他内容。 JSON 格式 {sentiment: positive 或 negative 或 neutral, confidence: 0.0 到 1.0 之间的小数} 文本这部电影的剧情非常精彩演员的表演也十分出色我非常喜欢 resp chat([ {role: user, content: prompt} ], temperature0, max_tokens100) print(resp)temperature0是为了让输出尽量确定情感分析这种分类任务不希望太发散。max_tokens100足够容纳一个 JSON 对象避免模型絮叨。模型通常会返回{sentiment: positive, confidence: 0.95}如果你的程序需要继续处理用json.loads解析import json try: result json.loads(resp) sentiment result[sentiment] confidence float(result[confidence]) except (json.JSONDecodeError, KeyError, TypeError) as e: print(解析失败原始输出如下) print(resp) raise e这段容错代码不是摆设。模型偶尔会在 JSON 外增加解释性文字或把数字写成0.95字符串。直接把响应喂给json.loads会翻车所以一旦解析失败先打印原始输出定位问题再考虑调整提示词。4.3 代码生成用严格指令和低 temperature 拿到可运行代码代码生成同样走 Chat Completions没有名为/code-generation的专用接口。要拿到“直接可运行”的代码关键在于角色约束和输出格式。messages [ {role: system, content: 你是一名资深 Python 工程师。用户要求写代码时只输出可运行的代码不要解释不要使用 Markdown 代码块围栏。}, {role: user, content: 写一个计算两个数之和的函数。} ] code chat(messages, temperature0.2, max_tokens512) print(code)将 temperature 调低到 0.2是为了减少变量命名和写法的随机性。max_tokens512对一个简单函数是足够的。如果模型不遵守“不要使用围栏”的约定返回了带 python 的文本我们需要清洗一下import re def strip_code_fence(raw: str) - str: raw raw.strip() if raw.startswith(): raw re.sub(r^[a-zA-Z]*\n, , raw) raw re.sub(r\n$, , raw) return raw code strip_code_fence(code)为什么还要写清洗函数因为生产环境接到的模型输出是不可控的。大模型对指令的遵守程度不是 100%在后端直接执行未经清洗的代码会有语法风险。清洗后最好再用compile(code, generated, exec)做一次语法校验确认无语法错误才落盘或执行。5. 调用 DeepSeek API 的常见问题与避坑记录认证、超时、限流和参数陷阱5.1 401 UnauthorizedKey 看着没错但认证就是不通过现象请求返回 401Body 里提示认证失败或 API key invalid。你在控制台复制了好几次肉眼看着和配置里的一模一样。原因最常见的是复制时带了前导或尾部空格、换行或者环境变量没有真正生效。我用.env文件时值两侧不小心多了一个空格程序读到的 Key 和真实 Key 就差这一个空格请求全部 401。其次是 Headers 里漏了Bearer前缀只有一串裸 Key。解决第一件事在代码里打印密钥的 reprprint(repr(os.environ[DEEPSEEK_API_KEY]))输出如果是 sk-xxx\n就说明有空格或换行清洗.env后重新加载。第二件事检查请求头格式确认Authorization长这样Bearer sk-xxx。第三件事如果还不行回控制台“API Keys”页面看密钥状态是否之前误删了。5.2 请求超时模型还在生成程序先掐断了现象requests.exceptions.ReadTimeout或者ConnectTimeout程序在长时间等待后直接抛异常前面做的重试逻辑又把它当成真正的失败。原因连接超时通常和本地网络限制有关比如办公室防火墙对长连接的干扰读取超时则可能是请求文本太长、服务器生成内容耗时超过了 timeout。很多教程把 timeout 设为 10 秒这只适合早期简单模型对现代大模型来说 10 秒远远不够。解决把 timeout 拆开连接 10 秒、读取 120 秒resp requests.post(url, headersheaders, jsonpayload, timeout(10, 120))另外给请求加重试。429、5xx 适合短退避重试但 400 和 401 不应该重试重试也只是浪费时间。简单写法import time for attempt in range(3): try: resp requests.post(url, headersheaders, jsonpayload, timeout(10, 120)) if resp.status_code 429: time.sleep(2 ** attempt) continue resp.raise_for_status() break except requests.exceptions.RequestException: time.sleep(2 ** attempt) if attempt 2: raise5.3 400 参数错误模型名、messages 结构和上下文超限现象返回 400错误信息类似invalid request、model not found或this models maximum context length is ...。你检查了 payload感觉字段名称都是对的。原因模型名写成了过时或错误的字符串。DeepSeek API 没有deepseek-code这类独立模型代码生成也走deepseek-chat。还有messages结构不合法content必须是字符串如果误传成 list 就会报错。上下文超限是因为 prompt token 数加 max_tokens 超过模型上下文窗口。解决先在控制台文档页确认当前可用的模型名和上下文上限。调试时打印 payload人工看一遍print(json.dumps(payload, ensure_asciiFalse, indent2))如果超长做分段摘要或截断max_input_chars 30000 truncated original_text[:max_input_chars]这里的 30000 只是我的经验值具体要以文档为准。关键是截断要放在发送之前不要等 400 再被动处理。5.4 429 与配额不足不是 Key 问题是请求太快或余额不够现象返回 429 Too Many Requests或者提示 insufficient quota / balance insufficient。明明刚刚还调通了一个请求再跑一个循环就全部失败。原因短时间并发请求超过接口限流阈值比如循环里一秒钟发几十个请求必然触发限流如果是余额不足提示状态码可能不是 429而是 402 或 403具体看平台定义。解决在循环里加最小间隔控制并发节奏是基本功for text in texts: response requests.post(url, headersheaders, jsonpayload, timeout(10, 120)) if response.status_code 429: time.sleep(1) continue # ... 处理响应 time.sleep(0.5)如果是余额问题去控制台充值即可。关键是把“限流”和“余额不足”在代码里分开处理限流可以退避重试余额不足应该直接告警不要盲目重试把账单刷高。6. 上线前最后一道检查curl 冒烟、usage 核价与 JSON 结构校验6.1 一行 curl 把环境验干净每次部署新环境我不用 Python 先跑而是用 curl 直接打一发最小请求。这样可以排除 requests、venv、代码逻辑的干扰只看 Key 和网络是否正常。curl -s https://api.deepseek.com/chat/completions \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -H Content-Type: application/json \ -d {model:deepseek-chat,messages:[{role:user,content:ping}],max_tokens:16}-s是静默模式不打印进度条-d后面是 JSON 请求体。正常情况下会返回一个完整 chat completionchoices[0].message.content可能是一句话。这一步通过说明 Key、网络、URL 都没问题剩下的就是应用层的问题。6.2 用 usage 字段把成本记下来DeepSeek API 按 token 计费prompt 和 completion 价格不同。我在封装函数里强制记录 usagedata resp.json() usage data.get(usage, {}) log.append({ prompt_tokens: usage.get(prompt_tokens, 0), completion_tokens: usage.get(completion_tokens, 0), })批量任务完成后再汇总python -c import json log json.load(open(api_log.json)) print(sum(item[prompt_tokens] for item in log)) print(sum(item[completion_tokens] for item in log)) 这样每次发布新 prompt 前都能对比前后成本。我就是靠这个发现某个 prompt 把输入 token 撑大了三倍及时精简才没让月度账单失控。6.3 JSON 响应校验别让模型输出直接进业务大模型返回的内容不该直接信任。凡是让模型输出 JSON 的场景我都用一个校验函数收口def parse_model_json(content: str): content content.strip() if content.startswith(): content re.sub(r^[a-zA-Z]*\n|\n$, , content) try: return json.loads(content) except json.JSONDecodeError: idx content.find({) if idx 0: return json.loads(content[idx:]) raise这个函数先剥掉 Markdown 围栏再尝试整段解析如果整段失败就截取第一个{后面的部分很多模型输出前面的解释文字截出来就是合法 JSON。从那以后我每次把 DeepSeek API 接进项目都会强制走一遍 curl 冒烟、usage 记录、JSON 解析校验这三步。特别是之前有一次生产环境的 prompt 改成了带 Markdown 的输出前端解析 JSON 直接崩了我才养成这个习惯只要模型参与输出后处理必须兜底。希望帮到你。本文还有配套的精品资源点击获取