简介：面向具备一定Python基础、希望快速接入DeepSeek语言能力的开发者与研究人员，这份文档围绕从注册获取API Key到完成首次调用的完整链路展开，适合希望把接口接入现有产品、减少试错成本的中级开发者。内容覆盖环境准备与OpenAI SDK安装，分别给出基于OpenAI SDK和原生HTTP请求的Python调用示例，并说明请求参数、响应JSON解析及429、503等错误处理思路。对temperature、top_p、max_tokens等生成参数以及stream流式输出、多轮对话上下文维护也有专门示例，末尾补充密钥保护、速率限制与使用条款等注意事项。包内共1个docx文件，压缩后约13KB，篇幅精炼，便于随查随用。已有3163人学习，可作为聊天机器人、客服系统、智能助理等文本交互项目的基础代码参考；示例覆盖基础请求与进阶配置，可直接修改后嵌入业务，也可作为搭建原型或二次开发的起点，并配合官方文档链接继续深入。

1. 从一次“接口返回 200 但页面卡住”的联调说起：大模型 API 调用指南的落地边界

大模型 API 调用指南：从注册到流式输出完整流程，真正难的不是把第一条请求发出去，而是让鉴权、参数、流式增量 and 多轮上下文在同一个工程里可靠运行。一个客服机器人接上某大模型开放平台后，HTTP 状态码是 200，前端却一直转圈，最后发现是流式响应没有被逐块消费。这个项目适合有 Python 基础、想把自然语言处理能力接进聊天机器人、客服系统或智能助理的开发者；新手能照着跑通第一条 HTTP 请求，熟手更该关注客户端分层、错误码兜底和会话状态管理。别把它当成复制一段示例代码就结束的事，接口能通只是起点。

2. 接口地图与工程骨架：注册鉴权、模型标识和第一条 HTTP 请求

2.1 注册与 Key 管理：先固定四个环境变量

接入某大模型开放平台，第一步不是写代码，而是把账号体系和密钥管理这件事做干净。注册完成后进入开放平台，创建 API Key，通常只完整显示一次，后面再想看只能重新创建。很多团队在这个环节翻车：Key 被贴进前端代码、被写进 Git 提交、被复制到聊天窗口里，最后只能紧急轮换。我的习惯是第一天就把 Key 放进环境变量，并且区分测试 Key 和生产 Key，测试 Key 只给本地和预发环境用，生产 Key 只注入运行容器，业务代码里不出现任何明文字符串。

需要先固定的变量一般有四个：接口地址、API Key、模型标识、超时时间。接口地址不要凭记忆写，按平台文档给的端点填；模型标识从平台的模型列表里抄，不要猜chat-model这类名字在某个平台上一定存在；超时时间要拆成连接超时和读取超时，流式场景的读取超时要更长。常见做法是准备一个.env.example文件，只写变量名和说明，不写真实值，再把.env加进忽略列表。这样新同事拉下代码后知道要配什么，也不会把密钥带进版本历史。

提示：创建 Key 后先记录创建时间和用途，按“本地调试 / 预发 / 生产”分开命名。轮换时先加新 Key，再删旧 Key，避免业务中断。

2.2 目录结构：把配置、客户端、业务提示词分层

工程骨架不需要一上来就上复杂框架，但一定要把“配置”“传输”“提示词”“业务编排”拆开。否则后面换模型、调参数、加流式输出时，改动会像拆毛线团。下面这张文件清单是我常用的最小结构，适合先用 Python 把链路跑通，再往 Web 服务里接。

这样分层之后，换模型只需要改config.py里的模型标识；调提示词只动prompts.py；修重试逻辑只动client.py。很多示例代码把所有东西塞进一个文件，跑通很快，但第二次改需求就会后悔。client.py里也不要直接拼业务提示词，传输层只关心“发什么请求、怎么收响应”，业务层才关心“让模型扮演什么角色、回答什么任务”。这条边界守住了，后面接流式、接多轮、接前端都会轻很多。

2.3 最小请求跑通：用 HTTP 请求建立可对比的基线

很多兼容式 SDK 会把请求体封装起来，设置base_url、api_key、model就能调用，看起来省事。但不同版本 SDK 的参数名、返回对象、流式迭代方式会有差异，一旦报错，排查时很容易变成黑匣子。我的做法是第一条基线先用 HTTP 请求直接发，看到原始 JSON 和状态码，再决定要不要包 SDK。下面这段代码只依赖requests，适合 Python 3.8 以上环境，先安装依赖再运行。

pip install requests

# minimal_client.py import os import requests # 接口地址和模型标识都用占位值，按平台文档替换 BASE_URL = os.getenv("LLM_BASE_URL", "https://api.example-llm.com/v1/chat/completions") API_KEY = os.environ["LLM_API_KEY"] # 不要写死在代码里 MODEL = os.getenv("LLM_MODEL", "chat-model") def chat_once(user_text: str) -> str: headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", } payload = { "model": MODEL, "messages": [ {"role": "system", "content": "你是一个简洁的技术助手。"}, {"role": "user", "content": user_text}, ], "temperature": 0.3, "max_tokens": 512, "stream": False, } # 连接超时 5 秒，读取超时 60 秒，避免请求无限挂起 resp = requests.post(BASE_URL, headers=headers, json=payload, timeout=(5, 60)) resp.raise_for_status() data = resp.json() return data["choices"][0]["message"]["content"] if __name__ == "__main__": print(chat_once("用三句话解释什么是自然语言处理。"))

这段代码的逻辑很直白：先构造请求头，把 API Key 放进Authorization，再构造 JSON 请求体，最后用requests.post发出去。timeout=(5, 60)里的 5 是建立连接的超时，60 是等待服务器返回数据的超时；如果不设读取超时，网络抖动时进程可能一直挂着。stream=False表示一次性拿完整响应，适合做第一条基线。resp.raise_for_status()会把 4xx、5xx 变成异常，避免后续解析 JSON 时才发现状态码不对。响应里的choices[0].message.content是常见的返回结构，但不同平台可能有字段差异，第一次调用时最好把原始 JSON 打印出来看一眼再封装。

参数上，BASE_URL、API_KEY、MODEL都不应该硬编码。temperature先给 0.3，是偏保守的值，适合问答和客服场景；max_tokens限制输出长度，防止模型一次生成过长内容。这里没有写top_p、stop等参数，是为了让基线足够干净。等这条请求能稳定返回，再把参数抽到配置文件里，逐项加。若返回 401，先查 Key 是否带空格、请求头格式是否为Bearer加空格；若返回 400，先看模型标识和消息数组是否符合平台要求；若返回 429，说明触发了限流，后面再讲重试。用 HTTP 请求先跑通，后面换成兼容式 SDK 时，至少知道正确的请求体和响应结构长什么样。

3. 请求与响应处理：消息数组、生成参数和 429/503 兜底

3.1 消息数组的拼装：角色边界比提示词长度更先决定效果

消息数组是调用大模型 API 时最容易被写乱的地方。常见错误是把系统提示词、历史对话、当前问题全部拼成一个字符串塞进user，短期能出结果，长期很难控制行为。更清晰的做法是保留角色边界：system固定助手身份和约束，user放当前任务，assistant放历史回复。多轮对话按时间顺序追加，不要把assistant的历史内容改写成user，否则模型会分不清谁说过什么。下面这段函数把消息拼装独立出来，方便在业务层复用。

def build_messages(system_prompt, history, user_text, max_history=8): # history 是已经按顺序保存的 user/assistant 消息列表 trimmed = history[-max_history:] messages = [{"role": "system", "content": system_prompt}] messages.extend(trimmed) messages.append({"role": "user", "content": user_text}) return messages

这段函数的参数说明：system_prompt是行为约束，比如“只回答与产品相关的问题”；history是历史消息列表；user_text是当前输入；max_history控制保留多少条历史消息。注意这里裁剪的是消息条数，不是 token 数，真正上线时还要按 token 预算做二次裁剪。逻辑上先放系统提示词，再放最近历史，最后放当前问题，顺序不要颠倒。system提示词一般只放一份，不要每轮重复追加，否则上下文会膨胀得很快。

实际业务里，我一般把提示词模板放在prompts.py，用占位符替换产品名、语气、输出格式，而不是在请求函数里手写长字符串。这样做的好处是提示词可以单独测试、单独版本化。还有一点要注意：不要把所有规则都堆进system，规则越多，模型越容易顾此失彼；把格式要求、拒答边界、角色设定分成短句，比一大段议论文式提示词更可维护。

3.2 生成参数怎么调：temperature、top_p、max_tokens、stop 的取舍

生成参数没有一套放之四海皆准的值，但可以先按场景定基线。客服问答、信息抽取、代码解释这类任务要的是可复现，temperature给低一些；创意文案、头脑风暴可以高一些。top_p和temperature不建议同时大幅调整，否则效果变化很难归因。max_tokens是输出预算，不是上下文总长度，很多 400 错误是把这两个概念混了。stop适合结构化输出，比如让模型在特定标记处停下。

调参时我习惯一次只动一个参数，并且固定一组测试问题做对比。比如同样问“解释自然语言处理”，先把temperature从 0.3 调到 0.7，看回答风格变化；再固定温度，改max_tokens看截断情况。不要今天改温度、明天改top_p、后天换模型，最后出问题不知道是谁造成的。流式场景还要注意：max_tokens太小会让输出在中途断掉，前端看到的是“话说一半”，不是接口报错。

3.3 错误处理与重试：指数退避、超时和幂等键

接口调用不可能永远一次成功。401 是鉴权问题，400 多半是参数或上下文超限，429 是限流，503 是服务端暂时不可用，超时和连接错误属于网络层。重试策略要克制：只对 429、503 和网络超时重试，不要对 401、400 重试，否则只会浪费时间和额度。指数退避加随机抖动是常见做法，避免多个客户端在同一秒一起重试。下面这段代码把重试边界写清楚。

import random import time import requests def post_with_retry(url, headers, payload, max_retries=3): for attempt in range(max_retries + 1): try: resp = requests.post(url, headers=headers, json=payload, timeout=(5, 60)) except (requests.Timeout, requests.ConnectionError): if attempt >= max_retries: raise time.sleep(min(2 ** attempt + random.random(), 8)) continue # 只对限流和服务端暂时不可用做重试 if resp.status_code in (429, 503) and attempt < max_retries: time.sleep(min(2 ** attempt + random.random(), 8)) continue resp.raise_for_status() return resp.json() raise RuntimeError("retry exhausted")

这段代码里，max_retries=3表示最多再试 3 次，加上首次请求一共 4 次；2 ** attempt形成 1、2、4 秒的退避，random.random()加一点抖动；上限 8 秒防止退避过长。resp.raise_for_status()放在重试判断之后，确保 400、401 这类错误直接抛出，不进入重试。流式请求的重试要更谨慎：如果已经消费了一部分增量，重试可能导致前端重复显示，常见做法是记录已输出位置，或者让前端重新发起一轮并清空局部状态。

如果平台支持幂等键，可以在请求头里带业务生成的request_id，同一业务请求重试时复用；如果平台没有明确说明支持，就不要假设它一定幂等。更稳妥的做法是在业务侧用请求 ID 去重，把请求 ID、模型名、状态码、耗时、是否流式写进日志。这样出现计费争议或重复回复时，能拿日志对齐，而不是靠猜。重试不是越多越好，超过业务可接受等待时间就应快速失败，把错误交给上层提示。

4. 流式输出与多轮对话：SSE 解析、增量拼接和会话状态

4.1 流式响应的数据形态：逐行读取与 delta 拼接

流式输出最常见的形态是 SSE，也就是服务器把数据切成多个事件逐段推给客户端。请求时把stream设为True，响应不再是一次性完整 JSON，而是一行行data:开头的内容，空行分隔事件，结束时可能出现[DONE]标记。不同平台的结束标记可能不同，所以代码里要留出兼容位。下面这段生成器负责逐行读取、解析 JSON、取出增量文本。

import json import requests def stream_chat(url, headers, payload): payload = {**payload, "stream": True} # stream=True 让 requests 不把响应体一次性读完 with requests.post(url, headers=headers, json=payload, timeout=(5, 120), stream=True) as resp: resp.raise_for_status() for raw_line in resp.iter_lines(decode_unicode=True): if not raw_line: continue line = raw_line.strip() if not line.startswith("data:"): continue data = line[5:].strip() if data == "[DONE]": break try: chunk = json.loads(data) except json.JSONDecodeError: continue choices = chunk.get("choices") or [] if not choices: continue delta = choices[0].get("delta") or {} piece = delta.get("content") if piece: yield piece

这段代码的关键点有三个：stream=True必须加在requests.post上，否则响应体会被整体缓冲；iter_lines(decode_unicode=True)按行读取，适合处理 SSE；增量内容通常在choices[0].delta.content，不是message.content。timeout=(5, 120)的读取超时给到 120 秒，是因为流式响应可能持续较久，但也不能无限等待。解析失败时直接跳过，不要让一个坏行把整个流打断。[DONE]只是常见结束标记，接入新平台时要先看文档或抓一次原始响应确认。

流式输出最容易出的问题不是解析，而是缓冲。服务端加了缓冲、网关加了缓冲、前端用await resp.text()一次性读取，都会让“流式”变成“最后一次性出现”。排查时先看客户端是否逐块打印，再看中间层是否关闭了缓冲。命令行里可以用print(piece, end="", flush=True)验证；Web 服务里要确认响应类型是text/event-stream，并且没有中间层把小块合并。

4.2 多轮对话状态：窗口裁剪、摘要压缩和系统提示词固定

多轮对话不是把历史消息无限追加。每轮问答都会增加上下文长度，聊到后面要么变慢，要么直接 400。常见做法是保留最近 N 轮完整消息，把更早的对话压缩成一段摘要，放在系统提示词后面。系统提示词本身不要裁，它是行为约束；最近一两轮也不要裁，它们决定当前回答的连贯性。下面这段代码先做最简单的窗口裁剪，适合第一版上线。

def append_turn(history, user_text, assistant_text): history.append({"role": "user", "content": user_text}) history.append({"role": "assistant", "content": assistant_text}) return history def trim_history(history, max_turns=6): # 一轮包含 user 和 assistant 两条消息 return history[-max_turns * 2:]

append_turn在模型返回完整回答后调用，把本轮用户输入和助手回复一起写入历史；trim_history只保留最近 6 轮，避免历史无限增长。参数max_turns要按业务调整：客服场景可能需要保留更多轮，问答机器人保留 3 到 5 轮就够。裁剪时不要只删user不删assistant，否则角色会错位。更细的做法是按 token 预算裁剪，先估算系统提示词和当前问题的 token，再把剩余预算分给历史。

当历史超过预算时，摘要压缩比直接丢弃更平滑。常见做法是把较早的对话交给模型生成一段“用户目标、已确认信息、未解决问题”的摘要，作为一条system或assistant消息保留。摘要本身也要限长，不然会变成新的负担。多轮对话还要固定系统提示词，不要在每轮重新生成不同版本，否则模型行为会漂移。业务侧最好保存conversation_id，把历史存到数据库或缓存，而不是只放在进程内存里。

4.3 接到 Web 服务：生成器、断连和背压

把流式接到 Web 服务，核心是“边生成边发送”。Python 里常见做法是用生成器配合流式响应，每次拿到增量就yield一个 SSE 事件。下面是一个简化的路由示例，省略了配置加载和鉴权，重点看响应类型和生成器结构。

import json from fastapi import FastAPI from fastapi.responses import StreamingResponse app = FastAPI() @app.post("/chat/stream") def chat_stream(payload: dict): def event_gen(): # stream_chat 是上一节定义的生成器 for piece in stream_chat(BASE_URL, HEADERS, payload): event = {"content": piece} yield f"data: {json.dumps(event, ensure_ascii=False)}\n\n" yield "data: [DONE]\n\n" return StreamingResponse(event_gen(), media_type="text/event-stream")

这段代码里，media_type="text/event-stream"告诉客户端这是 SSE；每个事件以data:开头，以两个换行结束；ensure_ascii=False保证中文不被转义。BASE_URL和HEADERS应该从配置模块注入，不要硬编码。前端断开连接时，生成器要能感知并停止向上游请求，否则上游还在生成，额度还在消耗。常见做法是捕获客户端断开异常，在finally里关闭上游响应；如果框架支持请求取消，把取消信号传给stream_chat。

背压也要考虑。不要在后端把所有增量先攒进一个大列表再发，那样流式就失去意义；也不要在前端每来一个字符就触发一次重渲染，容易卡顿。更稳妥的做法是按小批次更新 UI，比如每 20 到 50 毫秒合并一次。流式接口的日志不要打印完整增量内容，记录请求 ID、首字节时间、结束时间、总字符数就够，既能排查卡顿，又不会把用户内容写进日志。

5. 避坑与排查：密钥泄露、流式卡顿、上下文超限和重试计费

5.1 本地能跑、服务器 401：环境变量和请求头排查

现象很典型：本地命令行调用正常，部署到服务器后所有请求返回 401。原因通常不是代码逻辑，而是运行环境没有拿到 API Key：容器环境变量没注入、.env文件没被加载、变量名拼错、值前后带了空格或换行。还有一种情况是请求头被中间层改写，Authorization字段丢失或格式被改成Bearer: xxx，多了一个冒号。排查时先在服务器上确认变量是否存在，但不要打印完整值。

python -c "import os; k=os.getenv('LLM_API_KEY',''); print(bool(k), len(k), k[:3])"

这段命令只输出是否存在、长度和前三个字符，避免把密钥打到日志里。若长度为 0，说明变量没注入；若长度明显不对，检查复制时是否带了换行。请求头统一用f"Bearer {API_KEY}"，不要在 Key 前后手动加空格。部署到容器时，确认环境变量注入发生在启动命令之前；用配置文件挂载时，确认换行符没有把值截断。401 不要重试，先把鉴权链路查清楚。

5.2 流式返回 200 但前端一直转圈：缓冲与 flush 排查

现象是接口状态码 200，浏览器网络面板里也能看到响应，但页面一直转圈，最后一次性冒出全部内容。原因通常有三层：客户端请求没加stream=True，服务端生成器没有及时yield，中间层开启了响应缓冲。排查顺序从近到远：先在 Python 里直接迭代stream_chat，用flush=True打印；再把 Web 路由的响应类型改成text/event-stream；最后检查反向代理或网关是否关闭了缓冲。

服务端代码里不要先把所有增量收集到列表再返回，生成器要逐段产出。前端用fetch读取流时，要按块读取并解码，不要用一次性读取文本的方法。若中间层有缓冲配置，需要按部署方式调整；没有权限改中间层时，可以在响应头里加禁用缓冲的提示，但最终仍要以实际链路为准。流式卡顿不一定是模型慢，先看首字节时间，再看增量间隔，能快速定位是上游慢还是下游缓冲。

5.3 多轮越聊越慢、最后 400：上下文预算和裁剪策略

现象是前几轮正常，聊到十几轮后响应越来越慢，最后返回 400。原因一般是消息数组超出上下文上限，或者max_tokens设得太大，把输出预算挤没了。很多人以为max_tokens是上下文总长度，其实它只限制输出；输入消息、系统提示词、历史回复都会占预算。排查时打印每轮消息条数和字符数，估算 token 增长趋势，不要等报错才处理。

解决策略分三层：第一层固定系统提示词，不要每轮追加；第二层保留最近 N 轮完整消息；第三层对更早历史做摘要压缩。裁剪时优先删重复的寒暄和已经解决的问题，保留用户目标、关键约束和未完成事项。若业务允许，可以把历史存到外部存储，只在需要时检索相关片段，而不是全部塞回请求。400 出现后不要盲目重试，先把请求体长度和消息条数记录下来，再调整预算。

5.4 重试后账单翻倍：幂等键、重试边界和日志

现象是网络抖动后自动重试，最后发现同一问题生成了多次回答，额度也扣了多次。原因通常是重试范围过宽：把 400 也重试了，或者在流式已输出一半时整段重发，或者没有业务去重。重试只应覆盖 429、503 和网络超时，401、400 直接失败。流式请求重试前要判断是否已经产生可见输出，如果已经输出，优先让前端重新发起并清空局部状态，而不是在后端悄悄重发。

如果平台支持幂等键，用业务请求 ID 作为幂等键；如果不确定支持，就在业务侧记录request_id，同一用户同一问题在短时间窗口内去重。日志里记录模型名、状态码、耗时、重试次数、是否流式、输入输出字符数，出现计费异常时能对齐。重试次数不要无限加，设置总等待上限，超过就返回可读错误。流式接口尤其要记录首字节时间和结束原因，区分“模型慢”和“客户端断连”。

6. 二次开发改造：把调用脚本收成可复用客户端和验证清单

二次开发时，我一般不让业务代码直接碰requests。把传输收进一个LLMClient，对外只暴露chat()和stream_chat()两个方法；配置从环境变量读，重试策略和超时作为构造参数；每次请求记录request_id、模型名、耗时、状态码、是否流式、输入输出字符数。这样换模型只改配置，换重试策略只改客户端，业务层不需要跟着动。下面是一个骨架，重点看边界，不追求完整实现。

class LLMClient: def __init__(self, base_url, api_key, model, timeout=(5, 60), max_retries=3): self.base_url = base_url self.api_key = api_key self.model = model self.timeout = timeout self.max_retries = max_retries def chat(self, messages, **kwargs): # 这里调用非流式请求，统一处理错误和重试 ... def stream_chat(self, messages, **kwargs): # 这里返回生成器，逐段产出增量文本 ...

验证清单我习惯固定成表格，每接一个新平台先跑一遍：401 是否能给出明确提示，429 是否会退避重试，503 是否会有限次重试，超时是否能快速失败，流式中断是否能停止上游，多轮超限是否能裁剪，空回复是否能兜底。表格不用长，但每次上线前都过一遍，比事后查日志省事。

从那以后我每次接新平台 API，都强制先用 HTTP 基线跑一遍 401、429、流式中断三个用例，再让业务代码接兼容式 SDK。这个习惯让我少追了很多“看起来像模型问题、实际是传输层问题”的 bug。希望帮到你。

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