企业官网建设流程全解析

简介：面向有一定编程基础、希望深入掌握大模型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_KEY="sk-xxxxxxxxxxxxxxxx"

如果你用.env文件管理本地配置，配合python-dotenv读取：

pip install python-dotenv

from 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_KEY=sk-xxx，并且要把.env加进.gitignore。

关于轮换：如果怀疑 Key 泄露，直接在平台删除旧 Key，再创建新 Key。旧 Key 删除的瞬间会失效，所有依赖它的请求立即返回 401。所以上线环境下换 Key 的正确顺序是：先更新服务端配置并重启，确认新 Key 能请求成功，再删除旧 Key。删除动作放在最后，能少一次线上事故。

2.3 请求头里的两个字段：Authorization 与 Content-Type

一切就绪后，最基础的请求头长这样：

Authorization: Bearer sk-xxxxxxxx Content-Type: application/json

Authorization 使用 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": f"Bearer {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, headers=headers, json=payload, timeout=30) print(resp.status_code) print(resp.text)

这里json=payload会把字典自动序列化成 JSON 字符串。timeout=30表示连接和读取的超时上限。打印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 与 messages

DeepSeek 的对话补全端点是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": f"Bearer {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, headers=headers, json=payload, timeout=60) print(resp.status_code) print(resp.text)

逻辑说明：

• model参数决定用哪个模型。我日常用的是deepseek-chat，具体模型名以文档为准，网上旧资料里写的模型名未必还有效。
• messages是数组，每个元素至少含role和content。role=system用来设定助手人设，role=user是输入。
• 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, model="deepseek-chat", **kwargs): headers = { "Authorization": f"Bearer {os.environ['DEEPSEEK_API_KEY']}", "Content-Type": "application/json", } payload = {"model": model, "messages": messages, **kwargs} resp = requests.post( "https://api.deepseek.com/chat/completions", headers=headers, json=payload, timeout=(10, 120), ) if resp.status_code != 200: raise RuntimeError(f"DeepSeek 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, temperature=0.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} ], temperature=0, max_tokens=100) print(resp)

temperature=0是为了让输出尽量确定，情感分析这种分类任务不希望太发散。max_tokens=100足够容纳一个 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, temperature=0.2, max_tokens=512) print(code)

将 temperature 调低到 0.2，是为了减少变量命名和写法的随机性。max_tokens=512对一个简单函数是足够的。如果模型不遵守“不要使用围栏”的约定，返回了带 ` ```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 Unauthorized：Key 看着没错，但认证就是不通过

现象：请求返回 401，Body 里提示认证失败或 API key invalid。你在控制台复制了好几次，肉眼看着和配置里的一模一样。

原因：最常见的是复制时带了前导或尾部空格、换行，或者环境变量没有真正生效。我用.env文件时，值两侧不小心多了一个空格，程序读到的 Key 和真实 Key 就差这一个空格，请求全部 401。其次是 Headers 里漏了Bearer前缀，只有一串裸 Key。

解决：第一件事在代码里打印密钥的 repr：

print(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, headers=headers, json=payload, timeout=(10, 120))

另外给请求加重试。429、5xx 适合短退避重试，但 400 和 401 不应该重试，重试也只是浪费时间。简单写法：

import time for attempt in range(3): try: resp = requests.post(url, headers=headers, json=payload, 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: raise

5.3 400 参数错误：模型名、messages 结构和上下文超限

现象：返回 400，错误信息类似invalid request、model not found或this model's maximum context length is ...。你检查了 payload，感觉字段名称都是对的。

原因：模型名写成了过时或错误的字符串。DeepSeek API 没有deepseek-code这类独立模型，代码生成也走deepseek-chat。还有messages结构不合法：content必须是字符串；如果误传成 list 就会报错。上下文超限是因为 prompt token 数加 max_tokens 超过模型上下文窗口。

解决：先在控制台文档页确认当前可用的模型名和上下文上限。调试时打印 payload，人工看一遍：

print(json.dumps(payload, ensure_ascii=False, indent=2))

如果超长，做分段摘要或截断：

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, headers=headers, json=payload, 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 completion，choices[0].message.content可能是一句话。这一步通过，说明 Key、网络、URL 都没问题，剩下的就是应用层的问题。

6.2 用 usage 字段把成本记下来

DeepSeek API 按 token 计费，prompt 和 completion 价格不同。我在封装函数里强制记录 usage：

data = 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 直接崩了，我才养成这个习惯：只要模型参与输出，后处理必须兜底。希望帮到你。

本文还有配套的精品资源，点击获取