尧图网站建设 
简介一份面向Python开发者的DeepSeek接口实战指南聚焦图像分类与文本分类两大场景帮助具备编程经验的技术团队快速集成云端智能分类能力。文档以代码实例贯穿始终详细演示了注册获取接口密钥、安装requests与Pillow库、构造带授权头的POST请求、上传图像或文本数据以及从JSON响应中提取标签与置信度的完整流程同时提供了两个典型示例图像分类通过files参数上传图片获得“cat/0.98”结果文本分类通过json参数提交语句获得“Technology/0.95”结果并针对图像预处理如用Pillow统一尺寸及请求失败时的常见错误如无效密钥、负载格式不正确给出了具体排查方法。压缩包为单份docx文档共1个文件容量约17KB内容紧凑适合快速查阅。目前已有2675人学习浏览对于需要快速掌握HTTP接口调用并构建分类原型的开发团队是一份可直接上手的参考资料也适合作为团队内部对接接口调用规范的参考。1. 把 DeepSeek 图像与文本分类跑通API 调用顺序与最容易卡住的三个细节DeepSeek API 调用与图像分类、文本分类的结合是最近开发群里问得最多的组合。我把整个流程拆开来看发现大多数人的问题不在“不知道 requests 怎么写”而在鉴权头怎么放、文件上传到底用 files 还是 json、返回值里 label 和 confidence 怎么解析。这份笔记按实际调用顺序走一遍注册拿 key、装依赖、构造请求、解析结果、处理异常最后补几个最容易翻车的点。适合有 Python 基础、想把分类能力在两天内接进现有系统的开发者也适合正在搭自动标注管线的团队——哪些步骤必须在本地做、哪些字段必须兜底都能直接落代码。2. 调用前的准备工作API 密钥、requests 与 Pillow 三者关系理清楚2.1 API 密钥的获取与 Bearer 鉴权机制DeepSeek 开放平台上注册并登录后在控制台或 API 管理页面能看到一串以 sk- 开头的字符串这就是 API 密钥。它的作用是身份验证请求时把这个值放进 HTTP 请求头服务端在收到请求后先校验这个值再决定要不要继续执行业务逻辑。常见的鉴权格式是 Authorization: Bearer 你的 key这个格式在机器学习服务里非常普遍不是 DeepSeek 独创的设计。拿到密钥后第一个习惯不要硬编码在 .py 文件里。我一般用环境变量或者项目根目录的 .env 文件配合 gitignore 把密钥排除在版本控制之外。密钥泄露这件事外包项目里经常发生轻则账号被刷额度重则整个开放平台的接口被恶意调用。第二注意看密钥的权限范围有些平台给的是只读密钥有些是读写分离图像分类这种推理接口通常只需要只读或调用权限权限给大没有好处。代码层面密钥的加载我经常这样写import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(DEEPSEEK_API_KEY) if not api_key: raise SystemExit(请先在 .env 文件里配置 DEEPSEEK_API_KEY)这段代码的逻辑是把环境变量加载进运行时然后用 os.getenv 取出密钥。如果没取到就直接报错退出避免后续请求因为 key 为空而返回 401 后还要排查半天。参数说明load_dotenv 默认读取当前工作目录下的 .env 文件如果你的凭证文件放在其他路径比如 config/.env就得显式传路径load_dotenv(config/.env)。2.2 依赖库怎么装requests 与 Pillow 的真实分工很多人分不清 requests 和 Pillow 各自承担什么角色。requests 负责的是 HTTP 通信也就是把你的图片数据或文字数据送到 DeepSeek 的服务器再把响应拿回来Pillow 负责的是图像预处理也就是在上传之前把图片调整成模型能接受的尺寸、格式和质量。文本分类场景下可以用不到 Pillow但图像分类几乎必用。安装命令pip install requests pip install Pillow代码逻辑不复杂就是两个 Python 库。参数说明requests 的版本只要不是太老的都能用Pillow 建议装到 8.0 以上因为低版本对 JPEG 和 EXIF 处理的兼容性不够好。如果服务器在国内安装慢是常见问题我给两条路一条是换 pip 镜像源比如清华或阿里云的源在命令后面加 -i https://pypi.tuna.tsinghua.edu.cn/simple另一条是用虚拟环境装避免把系统 Python 目录搞脏。装完之后建议跑一条快速验证命令python -c import requests, PIL; print(requests.__version__, PIL.__version__)这一行命令能确认两个库都能正常导入。如果 Pillow 导入时报错或者提示缺少 JPEG 支持多半是当初安装时系统里没有 libjpeg 依赖重新装 Pillow 时用 pip install Pillow --force-reinstall 试一次。Pillow 在精简容器里经常出现“cannot write mode P as JPEG”这类报错本质就是缺少格式支持不是代码问题。2.3 调用前必须确定的四个参数真正写代码之前四个参数值得先想清楚请求 URL、请求方法、请求头、请求体。请求 URL 是这次调用的地址DeepSeek 图像分类接口的文档里会给出具体的 endpoint示例里的 https://api.deepseek.com/v1/classify 只是一个占位形式实际地址一定以最新版本官方文档为准。文本分类接口同理示例里的 https://api.deepseek.com/v1/text_classify 不保证长期不变。请求方法几乎都是 POST因为分类推理要携带数据语义上不是幂等的。请求头里两个字段最常用Authorization 用来放鉴权信息Content-Type 用来声明请求体的媒体类型。图像上传场景下Content-Type 更合适的写法是让 requests 库自动生成 multipart/form-data 边界不手动设置否则容易出 415 错误。文本分类场景下 Content-Type 设置为 application/json。请求体是整件事的难点。图像分类的数据量很大直接塞进 JSON 既不现实服务端也不方便接收常规做法是用文件上传requests 库的 files 参数会把文件构造成 multipart/form-data 格式。文本分类则直接把文本放到 JSON 字段里传输。我把两个场景的参数放一起对比参数图像分类文本分类请求方法POSTPOST请求头认证Bearer API KeyBearer API KeyContent-Typemultipart/form-dataapplication/json数据载体files 参数json 参数响应格式JSONJSON表格看完能定位自己卡在哪个环节。如果上传报错先检查是不是和表格里的 Content-Type 对不上再检查数据载体。另外 time 这个参数建议在所有请求上都加requests 默认没有超时服务端一旦僵住你的线程就会一直挂着批处理任务里这是灾难。3. 图像分类的 API 调用文件上传、预处理与结果解析3.1 第一个能返回结果的 POST 请求下面这个代码块是图像分类最基础的调用路径你可以把它复制到项目里替换 API 密钥和图片路径直接运行import os import requests api_key os.getenv(DEEPSEEK_API_KEY) url https://api.deepseek.com/v1/classify image_path sample.jpg with open(image_path, rb) as image_file: image_data image_file.read() headers { Authorization: fBearer {api_key} } files { image: (sample.jpg, image_data, image/jpeg) } response requests.post(url, headersheaders, filesfiles, timeout15) if response.status_code 200: result response.json() print(分类标签:, result[data][label]) print(置信度:, result[data][confidence]) else: print(f请求失败: {response.status_code}) print(response.text)这段代码我逐段说。第一api_key 从环境变量拿不在代码里写死。第二用 with open 读取图片的二进制字节流这是文件上传的标准姿势不要用 PIL 打开后再 save 一次多一步就多一个出错机会。第三headers 里只放 Authorization不放 Content-Type原因是 requests 库在处理 files 参数时会自动帮你加上 multipart/form-data 和随机的 boundary手动设置反而会破坏这个格式。第四timeout15 表示连接阶段和读取阶段各等最多 15 秒防止接口无响应时线程永挂。响应判断用 response.status_code 200。不要只判断响应里有没有 status 字段HTTP 状态码是最先需要确认的。如果返回 200再取 response.json()然后从 data 里拿 label 和 confidence。如果返回 401、404、429 这类非 200 状态码打印状态码同时把 response.text 打出来text 里通常带着服务端给出的具体错误排查时一眼能定位。3.2 图片预处理尺寸、格式、EXIF 和压缩从工程角度讲图片不处理直接上传是我见过最典型的翻车位。森林图像分类、商品图分类这类真实业务里用户上传的图可能是 10MB 的无人机航拍图也可能是手机拍的 2MB 竖图同一批图片尺寸差异很大。而深度模型输入大多固定常见的是 224x224 或更高分辨率的方形图。服务端通常不会帮你缩图它只负责接收和推理图片太大轻则请求超时重则被接口拒绝。from PIL import Image, ImageOps def prepare_image(src_path, dst_path, size(224, 224), quality90): img Image.open(src_path) img ImageOps.exif_transpose(img) img img.convert(RGB) img img.resize(size, Image.LANCZOS) img.save(dst_path, JPEG, qualityquality) print(f已生成: {dst_path}, 尺寸: {img.size})这段函数的处理顺序是先 exif_transpose 把图片的旋转信息应用掉否则手机拍摄的照片会被翻转九十度再 convert(RGB) 统一格式把 PNG 的透明通道或 RGBA 模式去掉JPEG 不支持透明通道不做这一步保存时会报错resize 用 LANCZOS 算法这是 Pillow 里缩放质量最高的重采样滤波器缺点是速度稍慢但预处理阶段可接受最后 save 统一成 JPEG 并压缩到 quality90图片体积通常能降到原来的五分之一。参数说明size 要按模型文档要求的输入尺寸来不一定是 224quality 在 85 到 95 之间比较稳妥低于 80 会导致压缩痕迹明显高于 95 体积下降有限。如果原图是长宽不均匀的矩形直接 resize 会把物体拉伸变形我一般先做中心裁剪或等比缩放补边这取决于你的业务分类任务里小的形变通常不影响结果但如果你想严谨一点可以用 ImageOps.fit 替代 resize它会自动裁剪到目标比例。3.3 响应解析label、confidence 与业务字段映射DeepSeek 图像分类返回的 JSON 结构示例里是两层外层 status 表示调用状态内层 data 才是结果体data.label 是分类标签data.confidence 是置信度取值通常在 0 到 1 之间。实际业务里我建议不要直接打数字存储加一层字段映射表更稳因为模型输出的标签可能是 train、cat 这些短字符串也可能是类别 ID跟业务线想要的展示名不同。响应结构如果出现 status 是 success 而 data 里没 label或者 label 是空字符串这类异常要专门处理。我的做法是写一个解析函数兜底def parse_classify_response(json_data): if json_data.get(status) ! success: raise ValueError(f接口状态异常: {json_data.get(message)}) data json_data.get(data, {}) label data.get(label, ) confidence float(data.get(confidence, 0)) if not label: raise ValueError(分类标签为空) return label, confidence这个函数的意义是把解析逻辑隔离出来后续接口字段变动只改这一处。confidence 强转 float避免服务端返回字符串类型JSON 里的 0.98 在 Python 里是 float但有些网关会把它搞成文本强转后统一。label 为空字符串时主动抛错而不是返回一个空值让下游代码带着空标签去写数据库。4. 文本分类的 API 调用JSON 请求体、边界检查与响应映射4.1 文本分类为什么可以不用 files 参数图像分类需要传文件所以走了 multipart/form-data。文本分类的输入是纯文本通常只有几百到几千字节没必要用 multipart直接把文本放进 JSON 请求体里服务端解析 JSON 取字段更方便。DeepSeek 文本分类接口的调用方式和图像分类的前半段几乎一致只是 URL 不同、数据字段不同、Content-Type 不同。import requests api_key your_api_key_here url https://api.deepseek.com/v1/text_classify data { text: Deep learning models are revolutionizing the AI field. } headers { Authorization: fBearer {api_key}, Content-Type: application/json } response requests.post(url, headersheaders, jsondata, timeout15) if response.status_code 200: result response.json() print(分类标签:, result[data][label]) print(置信度:, result[data][confidence]) else: print(f请求失败: {response.status_code}) print(response.text)这里有两个细节值得记住。第一个是 requests 库的 json 参数传入字典之后requests 会自动把字典序列化成 JSON 字符串同时帮你设置 Content-Type 为 application/json因此代码里的 Content-Type 其实可以省略。我保留它是为了让阅读代码的人一眼看到格式无害但不必需。第二个是中文文本的编码问题requests 的 json 参数序列化时默认 ensure_ascii 为 True也就是非 ASCII 字符会被转成 \uXXXX 形式服务端一般能解出来但如果你在调试时想直接看请求体可以把 ensure_ascii 改为 False或者用 json.dumps 手动构造请求体再加到 data 参数里。4.2 文本字段的边界检查空文本、长度、特殊字符文本分类比图像更容易出问题的其实是脏数据。用户可能传一个空字符串可能传几万字的论文可能传夹杂着换行和 URL 的长文本。模型对输入长度有限制超过上限的文本要么被截断要么直接报错。把边界检查写在请求前能大幅降低接口报错率。def normalize_text(raw_text, max_len2000): text raw_text.strip() if not text: raise ValueError(文本不能为空) text text.replace(\r\n, ).replace(\n, ) if len(text) max_len: text text[:max_len] return text参数说明strip 把首尾空白去掉换行统一替换成空格避免文本里出现奇怪的 \n\r 组合max_len 设置 2000具体值看 DeepSeek 接口文档的 max_tokens 或输入限制。截断是最简单的策略但如果你的业务需要保留完整语义截断不如分段调用再聚合结果这个属于后话。特殊字符方面文本里的 URL、邮箱这些模型能不能识别取决于训练数据预处理时我不建议删掉保留原样交给模型判断即可。4.3 文本分类响应的落地用法置信度阈值与标签映射文本分类的响应结构和图像分类很相似status 为 success 时data.label 是分类标签data.confidence 是置信度。业务上怎么用这两个值比请求本身更值得思考。比如你做舆情分类模型判断一条新闻属于“体育”这个标签置信度 0.55。这个结果直接入库可靠吗我的习惯是设一个阈值置信度低于 0.6 的样本进入人工复核队列高于阈值才自动进入结果表。THRESHOLD 0.6 def decision(label, confidence): if confidence THRESHOLD: return auto, label, confidence return review, label, confidence这段代码把分类结果分成两路置信度高的自动采纳置信度低的走人工或降级处理。参数说明THRESHOLD 的取值没有标准答案二分类任务可以高一点到 0.8多分类细粒度任务 0.6 已经不错具体拿一批样本跑出来看分布再定。这一层判断逻辑放在业务代码里不放在调用 API 的模块里方便后面单独调阈值。5. 避坑手册图像与文本分类调用中最常见的五个故障5.1 401 鉴权失败现象请求返回 401响应体提示 Invalid API key。原因最常见的是 API 密钥复制不全或多了空格。很多人从控制台复制密钥时鼠标带了行尾换行符还有人是把旧密钥删了没重新生成代码里还在用失效的 key。另一个隐蔽原因是 .env 文件路径不对load_dotenv 没找到文件os.getenv 返回了 None拼接 Authorization 头时变成了 Bearer None。解决先用 print 或者调试器把实际发送的 Authorization 头完整打出来确认是不是 Bearer 加一个空格再加大串密钥。如果怀疑 .env 没加载用 print(api_key[:5]) 看看前几位是否正常。再不行去 DeepSeek 开放平台上重新生成密钥替换后重测。5.2 请求卡死直到超时现象程序跑到 requests.post 这一行就停住几分钟后报 read timeout 或 connection timeout。原因一是没设置 timeout 参数requests 默认没有超时服务端如果一直不响应客户端线程就会一直挂着。二是图片太大上传阶段占满带宽服务端接收也要时间。三是网络环境里代理设置异常requests 走了错误的代理通道。解决所有请求统一加 timeout连接和读取分开设置比如 timeout(10, 30)前一个是连接等待后一个是读取等待。图片上传前先压缩本地处理后文件体积控制在 2MB 以内。代理问题在环境变量里排查 http_proxy、https_proxy 有没有残留。5.3 413 或 415 报错现象图像分类请求返回 413 Request Entity Too Large或者 415 Unsupported Media Type。原因413 是上传的图片体积太大服务端在网关层做了大小限制比如 10MB 上限415 是 Content-Type 和服务端的接收方式不匹配常见的是手动给文件上传请求设置了 application/json或者文件后缀名和实际内容不符。比如内容是 PNG但 files 参数里写的 MIME 类型是 image/jpeg。解决413 就回到本地预处理把图片压缩、重采样到模型要求的尺寸控制体积415 按服务端文档确认接口接收的是 multipart/form-data 还是 JSON文件上传场景把 Content-Type 交给 requests 自动生成不要手动指定。5.4 响应解析报 KeyError现象response.status_code 是 200但 result[data][label] 抛出 KeyError。原因请求成功不代表内容一定完整。可能服务端返回的不是标准 JSON 结构比如 status 是 errordata 字段缺失也可能是模型对某些图片输出了异常结果服务端把 data 置为 null 或空对象。还有一种可能是业务代码解析的是旧版接口字段名而接口已经升级字段从 label 改成了 category。解决解析前先打印原始响应 body确认字段实际名称。解析函数要做防御status 非 success 时优先处理 message 字段。字段名变了就去读官方文档里的响应示例以文档为准。这个报错初看像玄学其实根因不是网络就是字段漂移。5.5 并发高时被限流现象批量处理任务跑到一半连续返回 429 或类似限流错误。原因开放平台通常对 API 调用有速率限制比如每分钟允许调多少次。多个线程或进程同时在跑很容易在某一秒打满配额。服务端的限流策略可能是按 API key 维度也可能按 IP 维度。解决在客户端加简单的信号量控制并发数把请求速度限制在文档建议值的 80% 以下。收到 429 后用指数退避重试第一次等 2 秒第二次等 4 秒第三次等 8 秒最多重试三次。import time def backoff_wait(attempt): time.sleep(2 ** attempt)这个函数的逻辑是把重试次数映射成等待秒数。参数说明attempt 从 0 开始第一次失败等 1 秒第二次等 2 秒第三次等 4 秒实际使用中按 2 的幂次放大即可。退避代码可以写成通用工具图像和文本分类接口共用。6. 进阶用法把一次 API 调用变成能稳定上线的调用习惯6.1 用 requests.Session 做批量分类单次调用没问题之后很多人立刻遇到批量图片要分类。一个个创建 requests 请求性能差而且连接不复用。requests.Session 可以做连接复用同一个 TLS 连接来回用批量场景能明显减少握手时间。import time import requests session requests.Session() session.headers.update({Authorization: fBearer {api_key}}) def classify_with_retry(session, url, files, retries3): for attempt in range(retries): try: resp session.post(url, filesfiles, timeout(10, 30)) if resp.status_code 429: backoff_wait(attempt) continue resp.raise_for_status() return resp.json() except (requests.exceptions.Timeout, requests.exceptions.ConnectionError): backoff_wait(attempt) raise RuntimeError(连续多次调用失败)参数说明retries3 表示最多重试三次429 走退避等待其他 4xx 直接抛出timeout 拆成连接和读取两段。批量时对每个文件调用一次 classify_with_retry注意图片压缩放在循环外做别在循环里反复读同一张图。6.2 调用记录与阈值复核上线后最怕的是模型改版或者某类图片长年低置信度但没有监控。我自己的习惯是把每次调用的 label、confidence、耗时、HTTP 状态码写进日志表按天统计低置信度的分布。置信度阈值不是一个固定数字它应该随业务回看。日志里至少包含这几项字段含义timestamp调用时间request_id服务端返回的请求 IDlabel分类标签confidence置信度duration_ms请求耗时status_codeHTTP 状态码这个表是回看问题的起点。如果某天凌晨日志里出现一批 duration_ms 特别高的请求基本可以判断是网络波动或服务端排队如果低置信度比例连续走高那很可能是输入数据的分布和模型训练集偏了。从那次批量任务因为超时和限流卡了整整一晚上之后我养成了一个习惯写 AI 服务的调用代码时强制先把超时、重试、低置信兜底和日志表全部写好再开始写业务逻辑。这套习惯救过我不止一次希望帮到你。本文还有配套的精品资源点击获取 DeepSeek图像与文本分类API调用实战与避坑指南
简介一份面向Python开发者的DeepSeek接口实战指南聚焦图像分类与文本分类两大场景帮助具备编程经验的技术团队快速集成云端智能分类能力。文档以代码实例贯穿始终详细演示了注册获取接口密钥、安装requests与Pillow库、构造带授权头的POST请求、上传图像或文本数据以及从JSON响应中提取标签与置信度的完整流程同时提供了两个典型示例图像分类通过files参数上传图片获得“cat/0.98”结果文本分类通过json参数提交语句获得“Technology/0.95”结果并针对图像预处理如用Pillow统一尺寸及请求失败时的常见错误如无效密钥、负载格式不正确给出了具体排查方法。压缩包为单份docx文档共1个文件容量约17KB内容紧凑适合快速查阅。目前已有2675人学习浏览对于需要快速掌握HTTP接口调用并构建分类原型的开发团队是一份可直接上手的参考资料也适合作为团队内部对接接口调用规范的参考。1. 把 DeepSeek 图像与文本分类跑通API 调用顺序与最容易卡住的三个细节DeepSeek API 调用与图像分类、文本分类的结合是最近开发群里问得最多的组合。我把整个流程拆开来看发现大多数人的问题不在“不知道 requests 怎么写”而在鉴权头怎么放、文件上传到底用 files 还是 json、返回值里 label 和 confidence 怎么解析。这份笔记按实际调用顺序走一遍注册拿 key、装依赖、构造请求、解析结果、处理异常最后补几个最容易翻车的点。适合有 Python 基础、想把分类能力在两天内接进现有系统的开发者也适合正在搭自动标注管线的团队——哪些步骤必须在本地做、哪些字段必须兜底都能直接落代码。2. 调用前的准备工作API 密钥、requests 与 Pillow 三者关系理清楚2.1 API 密钥的获取与 Bearer 鉴权机制DeepSeek 开放平台上注册并登录后在控制台或 API 管理页面能看到一串以 sk- 开头的字符串这就是 API 密钥。它的作用是身份验证请求时把这个值放进 HTTP 请求头服务端在收到请求后先校验这个值再决定要不要继续执行业务逻辑。常见的鉴权格式是 Authorization: Bearer 你的 key这个格式在机器学习服务里非常普遍不是 DeepSeek 独创的设计。拿到密钥后第一个习惯不要硬编码在 .py 文件里。我一般用环境变量或者项目根目录的 .env 文件配合 gitignore 把密钥排除在版本控制之外。密钥泄露这件事外包项目里经常发生轻则账号被刷额度重则整个开放平台的接口被恶意调用。第二注意看密钥的权限范围有些平台给的是只读密钥有些是读写分离图像分类这种推理接口通常只需要只读或调用权限权限给大没有好处。代码层面密钥的加载我经常这样写import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(DEEPSEEK_API_KEY) if not api_key: raise SystemExit(请先在 .env 文件里配置 DEEPSEEK_API_KEY)这段代码的逻辑是把环境变量加载进运行时然后用 os.getenv 取出密钥。如果没取到就直接报错退出避免后续请求因为 key 为空而返回 401 后还要排查半天。参数说明load_dotenv 默认读取当前工作目录下的 .env 文件如果你的凭证文件放在其他路径比如 config/.env就得显式传路径load_dotenv(config/.env)。2.2 依赖库怎么装requests 与 Pillow 的真实分工很多人分不清 requests 和 Pillow 各自承担什么角色。requests 负责的是 HTTP 通信也就是把你的图片数据或文字数据送到 DeepSeek 的服务器再把响应拿回来Pillow 负责的是图像预处理也就是在上传之前把图片调整成模型能接受的尺寸、格式和质量。文本分类场景下可以用不到 Pillow但图像分类几乎必用。安装命令pip install requests pip install Pillow代码逻辑不复杂就是两个 Python 库。参数说明requests 的版本只要不是太老的都能用Pillow 建议装到 8.0 以上因为低版本对 JPEG 和 EXIF 处理的兼容性不够好。如果服务器在国内安装慢是常见问题我给两条路一条是换 pip 镜像源比如清华或阿里云的源在命令后面加 -i https://pypi.tuna.tsinghua.edu.cn/simple另一条是用虚拟环境装避免把系统 Python 目录搞脏。装完之后建议跑一条快速验证命令python -c import requests, PIL; print(requests.__version__, PIL.__version__)这一行命令能确认两个库都能正常导入。如果 Pillow 导入时报错或者提示缺少 JPEG 支持多半是当初安装时系统里没有 libjpeg 依赖重新装 Pillow 时用 pip install Pillow --force-reinstall 试一次。Pillow 在精简容器里经常出现“cannot write mode P as JPEG”这类报错本质就是缺少格式支持不是代码问题。2.3 调用前必须确定的四个参数真正写代码之前四个参数值得先想清楚请求 URL、请求方法、请求头、请求体。请求 URL 是这次调用的地址DeepSeek 图像分类接口的文档里会给出具体的 endpoint示例里的 https://api.deepseek.com/v1/classify 只是一个占位形式实际地址一定以最新版本官方文档为准。文本分类接口同理示例里的 https://api.deepseek.com/v1/text_classify 不保证长期不变。请求方法几乎都是 POST因为分类推理要携带数据语义上不是幂等的。请求头里两个字段最常用Authorization 用来放鉴权信息Content-Type 用来声明请求体的媒体类型。图像上传场景下Content-Type 更合适的写法是让 requests 库自动生成 multipart/form-data 边界不手动设置否则容易出 415 错误。文本分类场景下 Content-Type 设置为 application/json。请求体是整件事的难点。图像分类的数据量很大直接塞进 JSON 既不现实服务端也不方便接收常规做法是用文件上传requests 库的 files 参数会把文件构造成 multipart/form-data 格式。文本分类则直接把文本放到 JSON 字段里传输。我把两个场景的参数放一起对比参数图像分类文本分类请求方法POSTPOST请求头认证Bearer API KeyBearer API KeyContent-Typemultipart/form-dataapplication/json数据载体files 参数json 参数响应格式JSONJSON表格看完能定位自己卡在哪个环节。如果上传报错先检查是不是和表格里的 Content-Type 对不上再检查数据载体。另外 time 这个参数建议在所有请求上都加requests 默认没有超时服务端一旦僵住你的线程就会一直挂着批处理任务里这是灾难。3. 图像分类的 API 调用文件上传、预处理与结果解析3.1 第一个能返回结果的 POST 请求下面这个代码块是图像分类最基础的调用路径你可以把它复制到项目里替换 API 密钥和图片路径直接运行import os import requests api_key os.getenv(DEEPSEEK_API_KEY) url https://api.deepseek.com/v1/classify image_path sample.jpg with open(image_path, rb) as image_file: image_data image_file.read() headers { Authorization: fBearer {api_key} } files { image: (sample.jpg, image_data, image/jpeg) } response requests.post(url, headersheaders, filesfiles, timeout15) if response.status_code 200: result response.json() print(分类标签:, result[data][label]) print(置信度:, result[data][confidence]) else: print(f请求失败: {response.status_code}) print(response.text)这段代码我逐段说。第一api_key 从环境变量拿不在代码里写死。第二用 with open 读取图片的二进制字节流这是文件上传的标准姿势不要用 PIL 打开后再 save 一次多一步就多一个出错机会。第三headers 里只放 Authorization不放 Content-Type原因是 requests 库在处理 files 参数时会自动帮你加上 multipart/form-data 和随机的 boundary手动设置反而会破坏这个格式。第四timeout15 表示连接阶段和读取阶段各等最多 15 秒防止接口无响应时线程永挂。响应判断用 response.status_code 200。不要只判断响应里有没有 status 字段HTTP 状态码是最先需要确认的。如果返回 200再取 response.json()然后从 data 里拿 label 和 confidence。如果返回 401、404、429 这类非 200 状态码打印状态码同时把 response.text 打出来text 里通常带着服务端给出的具体错误排查时一眼能定位。3.2 图片预处理尺寸、格式、EXIF 和压缩从工程角度讲图片不处理直接上传是我见过最典型的翻车位。森林图像分类、商品图分类这类真实业务里用户上传的图可能是 10MB 的无人机航拍图也可能是手机拍的 2MB 竖图同一批图片尺寸差异很大。而深度模型输入大多固定常见的是 224x224 或更高分辨率的方形图。服务端通常不会帮你缩图它只负责接收和推理图片太大轻则请求超时重则被接口拒绝。from PIL import Image, ImageOps def prepare_image(src_path, dst_path, size(224, 224), quality90): img Image.open(src_path) img ImageOps.exif_transpose(img) img img.convert(RGB) img img.resize(size, Image.LANCZOS) img.save(dst_path, JPEG, qualityquality) print(f已生成: {dst_path}, 尺寸: {img.size})这段函数的处理顺序是先 exif_transpose 把图片的旋转信息应用掉否则手机拍摄的照片会被翻转九十度再 convert(RGB) 统一格式把 PNG 的透明通道或 RGBA 模式去掉JPEG 不支持透明通道不做这一步保存时会报错resize 用 LANCZOS 算法这是 Pillow 里缩放质量最高的重采样滤波器缺点是速度稍慢但预处理阶段可接受最后 save 统一成 JPEG 并压缩到 quality90图片体积通常能降到原来的五分之一。参数说明size 要按模型文档要求的输入尺寸来不一定是 224quality 在 85 到 95 之间比较稳妥低于 80 会导致压缩痕迹明显高于 95 体积下降有限。如果原图是长宽不均匀的矩形直接 resize 会把物体拉伸变形我一般先做中心裁剪或等比缩放补边这取决于你的业务分类任务里小的形变通常不影响结果但如果你想严谨一点可以用 ImageOps.fit 替代 resize它会自动裁剪到目标比例。3.3 响应解析label、confidence 与业务字段映射DeepSeek 图像分类返回的 JSON 结构示例里是两层外层 status 表示调用状态内层 data 才是结果体data.label 是分类标签data.confidence 是置信度取值通常在 0 到 1 之间。实际业务里我建议不要直接打数字存储加一层字段映射表更稳因为模型输出的标签可能是 train、cat 这些短字符串也可能是类别 ID跟业务线想要的展示名不同。响应结构如果出现 status 是 success 而 data 里没 label或者 label 是空字符串这类异常要专门处理。我的做法是写一个解析函数兜底def parse_classify_response(json_data): if json_data.get(status) ! success: raise ValueError(f接口状态异常: {json_data.get(message)}) data json_data.get(data, {}) label data.get(label, ) confidence float(data.get(confidence, 0)) if not label: raise ValueError(分类标签为空) return label, confidence这个函数的意义是把解析逻辑隔离出来后续接口字段变动只改这一处。confidence 强转 float避免服务端返回字符串类型JSON 里的 0.98 在 Python 里是 float但有些网关会把它搞成文本强转后统一。label 为空字符串时主动抛错而不是返回一个空值让下游代码带着空标签去写数据库。4. 文本分类的 API 调用JSON 请求体、边界检查与响应映射4.1 文本分类为什么可以不用 files 参数图像分类需要传文件所以走了 multipart/form-data。文本分类的输入是纯文本通常只有几百到几千字节没必要用 multipart直接把文本放进 JSON 请求体里服务端解析 JSON 取字段更方便。DeepSeek 文本分类接口的调用方式和图像分类的前半段几乎一致只是 URL 不同、数据字段不同、Content-Type 不同。import requests api_key your_api_key_here url https://api.deepseek.com/v1/text_classify data { text: Deep learning models are revolutionizing the AI field. } headers { Authorization: fBearer {api_key}, Content-Type: application/json } response requests.post(url, headersheaders, jsondata, timeout15) if response.status_code 200: result response.json() print(分类标签:, result[data][label]) print(置信度:, result[data][confidence]) else: print(f请求失败: {response.status_code}) print(response.text)这里有两个细节值得记住。第一个是 requests 库的 json 参数传入字典之后requests 会自动把字典序列化成 JSON 字符串同时帮你设置 Content-Type 为 application/json因此代码里的 Content-Type 其实可以省略。我保留它是为了让阅读代码的人一眼看到格式无害但不必需。第二个是中文文本的编码问题requests 的 json 参数序列化时默认 ensure_ascii 为 True也就是非 ASCII 字符会被转成 \uXXXX 形式服务端一般能解出来但如果你在调试时想直接看请求体可以把 ensure_ascii 改为 False或者用 json.dumps 手动构造请求体再加到 data 参数里。4.2 文本字段的边界检查空文本、长度、特殊字符文本分类比图像更容易出问题的其实是脏数据。用户可能传一个空字符串可能传几万字的论文可能传夹杂着换行和 URL 的长文本。模型对输入长度有限制超过上限的文本要么被截断要么直接报错。把边界检查写在请求前能大幅降低接口报错率。def normalize_text(raw_text, max_len2000): text raw_text.strip() if not text: raise ValueError(文本不能为空) text text.replace(\r\n, ).replace(\n, ) if len(text) max_len: text text[:max_len] return text参数说明strip 把首尾空白去掉换行统一替换成空格避免文本里出现奇怪的 \n\r 组合max_len 设置 2000具体值看 DeepSeek 接口文档的 max_tokens 或输入限制。截断是最简单的策略但如果你的业务需要保留完整语义截断不如分段调用再聚合结果这个属于后话。特殊字符方面文本里的 URL、邮箱这些模型能不能识别取决于训练数据预处理时我不建议删掉保留原样交给模型判断即可。4.3 文本分类响应的落地用法置信度阈值与标签映射文本分类的响应结构和图像分类很相似status 为 success 时data.label 是分类标签data.confidence 是置信度。业务上怎么用这两个值比请求本身更值得思考。比如你做舆情分类模型判断一条新闻属于“体育”这个标签置信度 0.55。这个结果直接入库可靠吗我的习惯是设一个阈值置信度低于 0.6 的样本进入人工复核队列高于阈值才自动进入结果表。THRESHOLD 0.6 def decision(label, confidence): if confidence THRESHOLD: return auto, label, confidence return review, label, confidence这段代码把分类结果分成两路置信度高的自动采纳置信度低的走人工或降级处理。参数说明THRESHOLD 的取值没有标准答案二分类任务可以高一点到 0.8多分类细粒度任务 0.6 已经不错具体拿一批样本跑出来看分布再定。这一层判断逻辑放在业务代码里不放在调用 API 的模块里方便后面单独调阈值。5. 避坑手册图像与文本分类调用中最常见的五个故障5.1 401 鉴权失败现象请求返回 401响应体提示 Invalid API key。原因最常见的是 API 密钥复制不全或多了空格。很多人从控制台复制密钥时鼠标带了行尾换行符还有人是把旧密钥删了没重新生成代码里还在用失效的 key。另一个隐蔽原因是 .env 文件路径不对load_dotenv 没找到文件os.getenv 返回了 None拼接 Authorization 头时变成了 Bearer None。解决先用 print 或者调试器把实际发送的 Authorization 头完整打出来确认是不是 Bearer 加一个空格再加大串密钥。如果怀疑 .env 没加载用 print(api_key[:5]) 看看前几位是否正常。再不行去 DeepSeek 开放平台上重新生成密钥替换后重测。5.2 请求卡死直到超时现象程序跑到 requests.post 这一行就停住几分钟后报 read timeout 或 connection timeout。原因一是没设置 timeout 参数requests 默认没有超时服务端如果一直不响应客户端线程就会一直挂着。二是图片太大上传阶段占满带宽服务端接收也要时间。三是网络环境里代理设置异常requests 走了错误的代理通道。解决所有请求统一加 timeout连接和读取分开设置比如 timeout(10, 30)前一个是连接等待后一个是读取等待。图片上传前先压缩本地处理后文件体积控制在 2MB 以内。代理问题在环境变量里排查 http_proxy、https_proxy 有没有残留。5.3 413 或 415 报错现象图像分类请求返回 413 Request Entity Too Large或者 415 Unsupported Media Type。原因413 是上传的图片体积太大服务端在网关层做了大小限制比如 10MB 上限415 是 Content-Type 和服务端的接收方式不匹配常见的是手动给文件上传请求设置了 application/json或者文件后缀名和实际内容不符。比如内容是 PNG但 files 参数里写的 MIME 类型是 image/jpeg。解决413 就回到本地预处理把图片压缩、重采样到模型要求的尺寸控制体积415 按服务端文档确认接口接收的是 multipart/form-data 还是 JSON文件上传场景把 Content-Type 交给 requests 自动生成不要手动指定。5.4 响应解析报 KeyError现象response.status_code 是 200但 result[data][label] 抛出 KeyError。原因请求成功不代表内容一定完整。可能服务端返回的不是标准 JSON 结构比如 status 是 errordata 字段缺失也可能是模型对某些图片输出了异常结果服务端把 data 置为 null 或空对象。还有一种可能是业务代码解析的是旧版接口字段名而接口已经升级字段从 label 改成了 category。解决解析前先打印原始响应 body确认字段实际名称。解析函数要做防御status 非 success 时优先处理 message 字段。字段名变了就去读官方文档里的响应示例以文档为准。这个报错初看像玄学其实根因不是网络就是字段漂移。5.5 并发高时被限流现象批量处理任务跑到一半连续返回 429 或类似限流错误。原因开放平台通常对 API 调用有速率限制比如每分钟允许调多少次。多个线程或进程同时在跑很容易在某一秒打满配额。服务端的限流策略可能是按 API key 维度也可能按 IP 维度。解决在客户端加简单的信号量控制并发数把请求速度限制在文档建议值的 80% 以下。收到 429 后用指数退避重试第一次等 2 秒第二次等 4 秒第三次等 8 秒最多重试三次。import time def backoff_wait(attempt): time.sleep(2 ** attempt)这个函数的逻辑是把重试次数映射成等待秒数。参数说明attempt 从 0 开始第一次失败等 1 秒第二次等 2 秒第三次等 4 秒实际使用中按 2 的幂次放大即可。退避代码可以写成通用工具图像和文本分类接口共用。6. 进阶用法把一次 API 调用变成能稳定上线的调用习惯6.1 用 requests.Session 做批量分类单次调用没问题之后很多人立刻遇到批量图片要分类。一个个创建 requests 请求性能差而且连接不复用。requests.Session 可以做连接复用同一个 TLS 连接来回用批量场景能明显减少握手时间。import time import requests session requests.Session() session.headers.update({Authorization: fBearer {api_key}}) def classify_with_retry(session, url, files, retries3): for attempt in range(retries): try: resp session.post(url, filesfiles, timeout(10, 30)) if resp.status_code 429: backoff_wait(attempt) continue resp.raise_for_status() return resp.json() except (requests.exceptions.Timeout, requests.exceptions.ConnectionError): backoff_wait(attempt) raise RuntimeError(连续多次调用失败)参数说明retries3 表示最多重试三次429 走退避等待其他 4xx 直接抛出timeout 拆成连接和读取两段。批量时对每个文件调用一次 classify_with_retry注意图片压缩放在循环外做别在循环里反复读同一张图。6.2 调用记录与阈值复核上线后最怕的是模型改版或者某类图片长年低置信度但没有监控。我自己的习惯是把每次调用的 label、confidence、耗时、HTTP 状态码写进日志表按天统计低置信度的分布。置信度阈值不是一个固定数字它应该随业务回看。日志里至少包含这几项字段含义timestamp调用时间request_id服务端返回的请求 IDlabel分类标签confidence置信度duration_ms请求耗时status_codeHTTP 状态码这个表是回看问题的起点。如果某天凌晨日志里出现一批 duration_ms 特别高的请求基本可以判断是网络波动或服务端排队如果低置信度比例连续走高那很可能是输入数据的分布和模型训练集偏了。从那次批量任务因为超时和限流卡了整整一晚上之后我养成了一个习惯写 AI 服务的调用代码时强制先把超时、重试、低置信兜底和日志表全部写好再开始写业务逻辑。这套习惯救过我不止一次希望帮到你。本文还有配套的精品资源点击获取