簡(jiǎn)介這份面向具備Python基礎(chǔ)的開(kāi)發(fā)者與AI集成團(tuán)隊(duì)的實(shí)踐指南聚焦通過(guò)DeepSeek API完成圖像分類和文本分類的接入流程。壓縮包內(nèi)僅有1個(gè)docx文檔大小約17KB篇幅精煉便于快速查閱與隨項(xiàng)目歸檔。文檔圍繞requests發(fā)送HTTP請(qǐng)求、Pillow處理圖像、API密鑰鑒權(quán)、POST請(qǐng)求頭與請(qǐng)求體構(gòu)造展開(kāi)并給出圖像上傳與文本分類兩套代碼示例同時(shí)說(shuō)明成功響應(yīng)中標(biāo)簽與置信度的解析方式以及無(wú)效密鑰、負(fù)載格式異常等常見(jiàn)錯(cuò)誤的排查方向。已有2676人學(xué)習(xí)適合希望快速驗(yàn)證云端機(jī)器學(xué)習(xí)服務(wù)、搭建分類應(yīng)用原型的中級(jí)開(kāi)發(fā)者參考。其價(jià)值在于將接口準(zhǔn)備、請(qǐng)求發(fā)送、結(jié)果處理與圖像尺寸預(yù)處理串成完整鏈路幫助讀者理解可復(fù)用的調(diào)用骨架并據(jù)官方文檔替換示例地址與參數(shù)減少接入初期的試錯(cuò)成本。1. 從一次 401 說(shuō)起這份調(diào)用指南真正解決的是鏈路問(wèn)題第一次把 DeepSeek 的圖像分類接口接進(jìn)項(xiàng)目報(bào)錯(cuò)不是模型分錯(cuò)而是 401——密鑰被拼進(jìn)了 URL 而不是請(qǐng)求頭。這份《DeepSeek API 調(diào)用指南》解決的正是這類問(wèn)題它不講模型結(jié)構(gòu)只講怎么用 requests 發(fā)出一個(gè) HTTP 請(qǐng)求把一張圖或一段文字 POST 給云端機(jī)器學(xué)習(xí)服務(wù)再拿回 label 和 confidence 兩個(gè)字段。內(nèi)容覆蓋密鑰獲取、Pillow 裝環(huán)境、圖像上傳、文本分類復(fù)用同一套骨架以及狀態(tài)碼排查。適合已經(jīng)有 Python 基礎(chǔ)、手里有個(gè)原型要接分類能力的開(kāi)發(fā)者如果你的場(chǎng)景是每天幾千張圖要打標(biāo)或者一批文本要自動(dòng)歸類跟著走一遍能跑通最小閉環(huán)。它也明確寫(xiě)了端點(diǎn)只作示例真實(shí)地址要回查官方文檔這點(diǎn)比很多抄來(lái)抄去的教程靠譜。2. 請(qǐng)求鏈路拆開(kāi)看Bearer 鑒權(quán)、multipart 上傳與 224×224 預(yù)處理把一次分類調(diào)用拆開(kāi)其實(shí)只有四段拼請(qǐng)求頭、準(zhǔn)備 body、發(fā)出去、解析回來(lái)。四段里出錯(cuò)概率最高的是第二段因?yàn)閳D像和文本的 body 形態(tài)完全不同一個(gè)是二進(jìn)制表單一個(gè)是 JSON。選錯(cuò)形態(tài)服務(wù)端要么返回 415要么解析出一堆亂碼。這一章先把鏈路上每個(gè)零件的形狀說(shuō)清楚后面寫(xiě)代碼才不會(huì)靠試。2.1 密鑰與請(qǐng)求頭Bearer 的三種寫(xiě)法與唯一推薦API 密鑰在原料里被描述成「注冊(cè)登錄后拿到的一串字符串」它在 HTTP 層的角色就是身份憑證。常見(jiàn)做法是放進(jìn)Authorization頭格式為Bearer key注意 Bearer 和 key 之間有一個(gè)空格少一個(gè)空格就是 401。有些人圖省事把 key 塞進(jìn) query 參數(shù)瀏覽器地址欄、Nginx access log、代理轉(zhuǎn)發(fā)記錄里都會(huì)留下明文等于把鑰匙貼在門上不建議。更穩(wěn)的習(xí)慣是從環(huán)境變量讀密鑰代碼里不出現(xiàn)字面量。下面這段用來(lái)做連通性自檢發(fā)一個(gè)輕量請(qǐng)求能拿到 200 就說(shuō)明密鑰、網(wǎng)絡(luò)、DNS 三段都通再去調(diào)分類接口就不會(huì)把環(huán)境問(wèn)題和業(yè)務(wù)問(wèn)題混在一起排查。import os import requests # 密鑰從環(huán)境變量讀取不寫(xiě)死在代碼和倉(cāng)庫(kù)里 API_KEY os.environ[DEEPSEEK_API_KEY] headers { # Bearer 后面必須有一個(gè)空格這是最常見(jiàn)的 401 來(lái)源 Authorization: fBearer {API_KEY}, # JSON 請(qǐng)求體時(shí)手寫(xiě)這一行上傳文件時(shí)千萬(wàn)別手寫(xiě)見(jiàn) 2.2 Content-Type: application/json, } # 端點(diǎn)僅作示例實(shí)際地址以官方文檔為準(zhǔn)換成任意輕量接口即可做連通性自檢 PROBE_URL https://api.deepseek.com/v1/models try: resp requests.get(PROBE_URL, headersheaders, timeout(3.05, 10)) print(resp.status_code) # 只打印前 200 字符避免日志被大響應(yīng)撐爆 print(resp.text[:200]) except requests.RequestException as e: print(網(wǎng)絡(luò)層就失敗了先查 DNS / 出口 / 超時(shí)設(shè)置, e)邏輯說(shuō)明先做一次 GET 自檢把「認(rèn)證失敗」和「分類失敗」兩類問(wèn)題隔離開(kāi)。參數(shù)說(shuō)明timeout(3.05, 10)是連接和讀取兩段超時(shí)連接段給 3 秒左右足夠覆蓋絕大多數(shù)機(jī)房到公網(wǎng)的首包時(shí)間讀取段按接口響應(yīng)速度給單寫(xiě)一個(gè)數(shù)字的話requests 會(huì)把它同時(shí)當(dāng)作兩段超時(shí)讀大響應(yīng)時(shí)容易誤殺。headers里的Content-Type在 GET 上其實(shí)可以不帶保留是為了讓這段代碼和后面的 POST 保持同一份頭字典。還有一種寫(xiě)法是用requests的auth參數(shù)那是 HTTP Basic 認(rèn)證用戶名密碼形式的和 Bearer Token 不是一回事套上去只會(huì)得到 401 或 403。這一點(diǎn)在原料里沒(méi)展開(kāi)但它是新手最?；煜牡胤?。2.2 圖像為什么必須走 files 而不是 json原料給的示例用files上傳圖像而不是把圖像塞進(jìn) JSON這個(gè)選擇不是隨意的。二進(jìn)制數(shù)據(jù)進(jìn) JSON 必須先 base64 編碼體積會(huì)漲大約三分之一服務(wù)端還要多做一次解碼兩端都虧。業(yè)界常見(jiàn)三種上傳方式取舍如下方式體積開(kāi)銷服務(wù)端處理成本適用場(chǎng)景multipart/form-datafiles幾乎無(wú)膨脹低流式解析單圖、小批量、原型驗(yàn)證base64 塞進(jìn) JSON約 33%需要解碼內(nèi)存峰值高網(wǎng)關(guān)只允許 JSON 的受限環(huán)境先傳對(duì)象存儲(chǔ)再傳 URL無(wú)最低可異步批量任務(wù)、大圖、需要留檔原圖選 multipart 之后有一個(gè)必須知道的細(xì)節(jié)requests會(huì)在檢測(cè)到files參數(shù)時(shí)自動(dòng)生成Content-Type: multipart/form-data; boundary----xxxx這個(gè) boundary 是分隔各字段的隨機(jī)字符串。如果你在headers里手寫(xiě)了一個(gè)不帶 boundary 的Content-Type: multipart/form-datarequests 就不會(huì)再補(bǔ)服務(wù)端拿不到分隔符直接把整個(gè) body 當(dāng)成一個(gè)字段解析結(jié)果通常是 400 或解析出空文件。所以上傳圖像時(shí)頭字典里只留Authorization。import requests def upload_once(image_bytes: bytes, api_key: str, url: str): # 三元組順序是字段名、文件名、MIME 類型缺一不可 files {image: (image.jpg, image_bytes, image/jpeg)} # 附加的表單字段都只能是字符串?dāng)?shù)字要自己 str() 轉(zhuǎn)換 data {top_k: 3} headers {Authorization: fBearer {api_key}} # 不要加 Content-Type return requests.post( url, headersheaders, filesfiles, datadata, timeout(3.05, 60), # 圖像推理比文本慢讀取超時(shí)給寬一點(diǎn) )邏輯說(shuō)明files的 value 用三元組而不是裸 bytes是為了讓服務(wù)端拿到正確的文件名和 MIME如果只傳{image: image_bytes}requests 會(huì)默認(rèn)按application/octet-stream發(fā)部分服務(wù)端會(huì)因此拒絕。參數(shù)說(shuō)明top_k這類字段在 multipart 里一律是字符串傳3會(huì)被 requests 編碼成3但如果你自己用data{top_k: 3}再手動(dòng)拼 body就可能踩到類型錯(cuò)誤讀取超時(shí)給到 60 秒是因?yàn)閳D像接口往往要跑一次前向冷啟動(dòng)時(shí)更慢。2.3 Pillow 預(yù)處理尺寸、色彩模式與字節(jié)流復(fù)用原料里提到「模型可能要求 224×224」這是個(gè)假設(shè)值真實(shí)尺寸必須回查文檔。但無(wú)論目標(biāo)尺寸是多少預(yù)處理要做的事是固定的四件擺正方向、統(tǒng)一色彩模式、等比縮放加裁剪、控制編碼體積。方向這件事容易被忽略。手機(jī)拍的 JPEG 里帶 EXIF Orientation 標(biāo)記Image.open讀出來(lái)是原始像素方向直接縮放再上傳模型看到的是躺倒的貓。ImageOps.exif_transpose會(huì)按標(biāo)記旋轉(zhuǎn)并清掉這個(gè)標(biāo)記是一行就能解決的血淚經(jīng)驗(yàn)。色彩模式方面PNG 可能帶 alpha 通道灰度圖只有一個(gè)通道CMYK 的 JPEG 來(lái)自印刷物料這幾種直接送進(jìn)只接受三通道 RGB 的模型都會(huì)報(bào)錯(cuò)或得到詭異結(jié)果convert(RGB)統(tǒng)一掉。from PIL import Image, ImageOps import io def normalize_image(path: str, size(224, 224), quality: int 90) - bytes: with Image.open(path) as im: im ImageOps.exif_transpose(im) # 按 EXIF 擺正避免躺倒的貓 im im.convert(RGB) # 去 alpha、統(tǒng)一三通道 # fit 是等比縮放后居中裁剪resize 是硬拉伸后者會(huì)讓長(zhǎng)圖變形 im ImageOps.fit(im, size, methodImage.BICUBIC) buf io.BytesIO() im.save(buf, formatJPEG, qualityquality, optimizeTrue) return buf.getvalue() # 直接拿 bytes不落盤邏輯說(shuō)明整個(gè)函數(shù)在內(nèi)存里完成返回 bytes 直接喂給 2.2 的上傳函數(shù)省掉一次臨時(shí)文件讀寫(xiě)批量跑的時(shí)候差別很明顯。參數(shù)說(shuō)明size按文檔改不要照抄 224quality90是體積和畫(huà)質(zhì)的折中點(diǎn)壓到 75 以下在細(xì)粒度分類任務(wù)上會(huì)掉點(diǎn)optimizeTrue讓 Pillow 多花一點(diǎn) CPU 換更小的文件對(duì)上傳耗時(shí)是正收益methodImage.BICUBIC比默認(rèn)的最近鄰更適合縮小邊緣不會(huì)出現(xiàn)鋸齒。還有一個(gè)常被忽略的點(diǎn)Image.open是惰性的文件句柄會(huì)一直掛著批量處理幾千張時(shí)不關(guān)會(huì)撞到文件描述符上限。上面用with包住就是為了這個(gè)getvalue()必須在with塊內(nèi)調(diào)用出了塊對(duì)象就關(guān)了。3. 圖像分類調(diào)用的完整實(shí)現(xiàn)從讀文件到解析 label 與 confidence第二章把零件備齊了這一章組裝成能跑的東西。判斷一段調(diào)用代碼合不合格不看它能不能出結(jié)果看它在出錯(cuò)時(shí)能不能告訴你錯(cuò)在哪。所以下面的實(shí)現(xiàn)里超時(shí)、狀態(tài)碼分支、響應(yīng)結(jié)構(gòu)校驗(yàn)三樣都要有缺一樣在批量場(chǎng)景里都會(huì)變成黑匣子。3.1 最小可運(yùn)行腳本與逐行參數(shù)說(shuō)明原料給的主干是requests.post(url, headersheaders, filesfiles)加一個(gè)status_code 200的分支。這個(gè)骨架是對(duì)的但少了三樣?xùn)|西超時(shí)、非 200 分支的細(xì)分、JSON 解析的保護(hù)。網(wǎng)關(guān)返回 HTML 錯(cuò)誤頁(yè)時(shí)response.json()會(huì)拋JSONDecodeError異常信息里看不到狀態(tài)碼排查時(shí)非常難受。import os import requests from requests import Response API_KEY os.environ[DEEPSEEK_API_KEY] # 端點(diǎn)僅作示例請(qǐng)以官方文檔為準(zhǔn) CLASSIFY_URL https://api.deepseek.com/v1/classify def classify_image(image_bytes: bytes, top_k: int 3) - dict: files {image: (image.jpg, image_bytes, image/jpeg)} data {top_k: str(top_k)} headers {Authorization: fBearer {API_KEY}} try: resp: Response requests.post( CLASSIFY_URL, headersheaders, filesfiles, datadata, timeout(3.05, 60), ) except requests.Timeout: return {ok: False, code: TIMEOUT, msg: 請(qǐng)求超時(shí)考慮降分辨率或加重試} except requests.RequestException as e: return {ok: False, code: NETWORK, msg: str(e)} if resp.status_code ! 200: # 保留狀態(tài)碼和響應(yīng)體前 500 字符足夠定位大多數(shù)問(wèn)題 return { ok: False, code: resp.status_code, msg: resp.text[:500], } try: body resp.json() except ValueError: return {ok: False, code: BAD_JSON, msg: resp.text[:500]} # 原料里的響應(yīng)形如 {status:success,data:{label:...,confidence:...}} if body.get(status) ! success: return {ok: False, code: API_ERROR, msg: body.get(message, )} data_obj body.get(data) or {} return { ok: True, label: data_obj.get(label), confidence: float(data_obj.get(confidence) or 0.0), raw: body, }邏輯說(shuō)明返回統(tǒng)一成{ok: bool}的字典調(diào)用方只需要判斷ok不用在每個(gè)業(yè)務(wù)點(diǎn)重復(fù)寫(xiě) try/except失敗分支帶上code日志里聚合一下就能看出是密鑰問(wèn)題還是超時(shí)問(wèn)題占多數(shù)。參數(shù)說(shuō)明top_k轉(zhuǎn)成字符串是因?yàn)?multipart 表單字段只接受字符串超時(shí)元組里讀取段給 60 秒圖像推理冷啟動(dòng)時(shí)可能十幾秒給太短會(huì)誤判成服務(wù)不可用float(... or 0.0)是防御式寫(xiě)法萬(wàn)一服務(wù)端返回字符串0.98也能轉(zhuǎn)換返回 null 時(shí)不會(huì)拋TypeError。提示原料里的響應(yīng)字段status、data.label、data.confidence是示例結(jié)構(gòu)接入前先用一次真實(shí)請(qǐng)求確認(rèn)字段路徑再把這幾個(gè) key 抽成模塊級(jí)常量別散落在業(yè)務(wù)代碼里。3.2 響應(yīng)結(jié)構(gòu)解析與置信度閾值的業(yè)務(wù)用法confidence這個(gè)字段很容易被誤用。它是模型對(duì)本次預(yù)測(cè)的打分不是「這張圖有 98% 概率是貓」這種校準(zhǔn)過(guò)的概率跨類別、跨批次直接比大小并不嚴(yán)謹(jǐn)。但它作為分流信號(hào)是夠用的高分區(qū)自動(dòng)落庫(kù)低分區(qū)轉(zhuǎn)人工復(fù)核中間灰區(qū)打標(biāo)記后置處理。置信度區(qū)間處理策略說(shuō)明≥ 0.90自動(dòng)入庫(kù)抽檢 1% 做質(zhì)量監(jiān)控0.60 ~ 0.90入待復(fù)核隊(duì)列按天批量人工過(guò)一遍 0.60轉(zhuǎn)人工或丟棄重采往往是模糊圖、多主體圖或域外樣本def route(result: dict, high: float 0.90, low: float 0.60) - str: if not result.get(ok): return manual # 調(diào)用失敗一律進(jìn)人工不要靜默丟數(shù)據(jù) conf result[confidence] if conf high: return auto if conf low: return review return manual邏輯說(shuō)明把閾值寫(xiě)成函數(shù)參數(shù)而不是硬編碼是因?yàn)椴煌惸康姆植疾顒e很大做一次小樣本標(biāo)注就能把high和low調(diào)到位。參數(shù)說(shuō)明high調(diào)高會(huì)減少誤判但增加人工量通常先從 0.90 起步low調(diào)低會(huì)讓灰區(qū)變窄適合人力緊張的團(tuán)隊(duì)。這三個(gè)檔位建議先在歷史數(shù)據(jù)上跑一遍分布看灰區(qū)占比再定拍腦袋定閾值是后面返工的主要原因。3.3 批量與并發(fā)Session 復(fù)用、超時(shí)與重試單張調(diào)用跑通之后下一步一定是批量。批量場(chǎng)景里兩個(gè)改動(dòng)收益最大復(fù)用連接、加受控重試。requests.post每次都是一次全新的 TCP 加 TLS 握手批量幾百?gòu)垥r(shí)握手開(kāi)銷能占到總耗時(shí)的一半。用Session復(fù)用連接池配合HTTPAdapter設(shè)置池大小是標(biāo)準(zhǔn)做法。重試這塊有個(gè)真實(shí)的坑urllib3的Retry默認(rèn)allowed_methods不包含 POST所以你不顯式配置的話POST 請(qǐng)求根本不會(huì)重試代碼看起來(lái)加了重試其實(shí)沒(méi)生效。反過(guò)來(lái)如果你把 POST 加進(jìn)重試列表讀超時(shí)后重試又可能造成重復(fù)計(jì)費(fèi)或重復(fù)入庫(kù)。折中做法是只對(duì)連接類錯(cuò)誤和 429、5xx 重試讀超時(shí)不重試。import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry def build_session(pool_size: int 16) - requests.Session: session requests.Session() retry Retry( total3, connect3, # 只重試連接階段 read0, # 讀超時(shí)不重試避免重復(fù)計(jì)費(fèi) status3, # 429 / 5xx 重試 status_forcelist[429, 500, 502, 503, 504], allowed_methodsfrozenset([POST]), # 默認(rèn)不含 POST必須顯式加 backoff_factor0.5, # 退避 0.5s、1s、2s raise_on_statusFalse, ) adapter HTTPAdapter(max_retriesretry, pool_connectionspool_size, pool_maxsizepool_size) session.mount(https://, adapter) return session邏輯說(shuō)明connect和read分開(kāi)配置是關(guān)鍵連接失敗重試是安全的讀超時(shí)重試則可能讓同一張圖被計(jì)費(fèi)兩次。參數(shù)說(shuō)明pool_maxsize要和你開(kāi)的并發(fā)線程數(shù)匹配線程數(shù)大于池大小時(shí)多出來(lái)的線程會(huì)等待連接表現(xiàn)為「并發(fā)上不去」backoff_factor0.5產(chǎn)生指數(shù)退避對(duì) 429 限流場(chǎng)景很有效raise_on_statusFalse讓重試耗盡后把原始響應(yīng)返回給你而不是拋異常方便統(tǒng)一處理。并發(fā)執(zhí)行用ThreadPoolExecutor就夠這類任務(wù)是 IO 密集的協(xié)程或線程都行線程寫(xiě)起來(lái)簡(jiǎn)單。并發(fā)數(shù)別開(kāi)太大先看賬號(hào)的限流配額從 4 到 8 起步撞到 429 就往下調(diào)。4. 文本分類與接口復(fù)用同一套骨架換 payload原料里給的文本分類示例和圖像分類的差別只有兩處URL 不同、body 從 multipart 換成 JSON。這說(shuō)明兩個(gè)接口共享同一套 HTTP 骨架把它抽出來(lái)比復(fù)制兩份代碼劃算得多。抽的時(shí)候注意 JSON 和 multipart 在請(qǐng)求頭上的差異這是唯一不能共用的地方。4.1 文本接口的 JSON 載荷與編碼細(xì)節(jié)requests.post(url, jsondata)和requests.post(url, datajson.dumps(data))看起來(lái)一樣其實(shí)差兩點(diǎn)前者自動(dòng)設(shè)置Content-Type: application/json后者不會(huì)你需要自己在頭里寫(xiě)前者遇到不可序列化的對(duì)象會(huì)直接拋TypeError后者要到dumps階段才報(bào)。統(tǒng)一用json參數(shù)更省心。import requests def classify_text(text: str, url: str, api_key: str, top_k: int 3) - dict: # 超長(zhǎng)文本先截?cái)嗪芏嘟涌趯?duì)長(zhǎng)度有硬限制超了直接 400 if len(text) 4000: text text[:4000] payload {text: text, top_k: top_k} headers { Authorization: fBearer {api_key}, Content-Type: application/json, # 用 json 時(shí) requests 也會(huì)自動(dòng)加 } resp requests.post(url, headersheaders, jsonpayload, timeout(3.05, 15)) resp.raise_for_status() return resp.json()邏輯說(shuō)明jsonpayload讓 requests 用json.dumps序列化并自動(dòng)設(shè)頭中文會(huì)被轉(zhuǎn)成\uXXXX轉(zhuǎn)義這是合法的 JSON服務(wù)端能正確還原不需要加ensure_asciiFalse那個(gè)參數(shù)只在你自己dumps時(shí)有用。參數(shù)說(shuō)明文本截?cái)嚅L(zhǎng)度按接口文檔調(diào)整不要照抄 4000raise_for_status()在原型階段很方便會(huì)讓異常帶上狀態(tài)碼但生產(chǎn)代碼里建議像第 3 章那樣手動(dòng)分支因?yàn)槟阆肽玫巾憫?yīng)體做診斷。還有一點(diǎn)如果文本來(lái)自網(wǎng)頁(yè)抓取先做一次清洗去掉零寬字符、全角空格、HTML 實(shí)體。這些字符在 JSON 里合法但會(huì)讓分類結(jié)果偏移屬于典型的「模型沒(méi)問(wèn)題、數(shù)據(jù)有臟東西」。4.2 把圖像和文本兩類調(diào)用抽象成統(tǒng)一客戶端抽象的目標(biāo)不是少寫(xiě)幾行而是讓重試、日志、錯(cuò)誤碼映射只寫(xiě)一遍。下面的類把公共部分收在_post里兩個(gè)公開(kāi)方法只負(fù)責(zé)準(zhǔn)備 body。import logging import requests log logging.getLogger(__name__) class ClassifyClient: def __init__(self, api_key: str, base_url: str, session: requests.Session): self.api_key api_key self.base_url base_url.rstrip(/) # session 從外部注入方便復(fù)用連接池和重試策略 self.session session def _headers(self, with_json: bool False) - dict: headers {Authorization: fBearer {self.api_key}} if with_json: headers[Content-Type] application/json return headers def _post(self, path: str, **kwargs) - dict: url f{self.base_url}/{path.lstrip(/)} resp self.session.post(url, **kwargs) # 統(tǒng)一把非 200 轉(zhuǎn)成帶狀態(tài)碼的字典調(diào)用方不用各自判斷 if resp.status_code ! 200: log.warning(classify failed status%s body%s, resp.status_code, resp.text[:300]) return {ok: False, code: resp.status_code, msg: resp.text[:300]} try: return {ok: True, **resp.json()} except ValueError: return {ok: False, code: BAD_JSON, msg: resp.text[:300]} def image(self, image_bytes: bytes, top_k: int 3) - dict: return self._post( /v1/classify, # 示例路徑以文檔為準(zhǔn) headersself._headers(with_jsonFalse), files{image: (image.jpg, image_bytes, image/jpeg)}, data{top_k: str(top_k)}, timeout(3.05, 60), ) def text(self, text: str, top_k: int 3) - dict: return self._post( /v1/text_classify, # 示例路徑以文檔為準(zhǔn) headersself._headers(with_jsonTrue), json{text: text[:4000], top_k: top_k}, timeout(3.05, 15), )邏輯說(shuō)明session從構(gòu)造函數(shù)注入而不是在類里 new 一個(gè)這樣測(cè)試時(shí)可以換成 mock生產(chǎn)時(shí)可以復(fù)用第 3 章配好的連接池和重試策略。參數(shù)說(shuō)明_headers的with_json開(kāi)關(guān)是唯一區(qū)分兩類請(qǐng)求的地方multipart 請(qǐng)求不能帶Content-Type這是 2.2 講過(guò)的坑抽象的時(shí)候特別容易統(tǒng)一成「都帶上」然后圖像接口集體 415。base_url用rstrip(/)處理避免路徑拼出雙斜杠有些網(wǎng)關(guān)對(duì)//v1會(huì) 404。4.3 成本與延遲的取舍本地預(yù)處理還是服務(wù)端預(yù)處理圖像走的鏈路里預(yù)處理放哪邊是個(gè)真實(shí)的決策。放本地省帶寬、省服務(wù)端算力但吃客戶端 CPU放服務(wù)端省客戶端邏輯但上傳的是原圖體積可能大十倍。策略上傳體積客戶端 CPU結(jié)果一致性適用本地縮放到目標(biāo)尺寸小中高可控批量任務(wù)、移動(dòng)端上行本地只壓質(zhì)量不縮放中低中需要服務(wù)端統(tǒng)一裁切的場(chǎng)景原圖直傳大無(wú)取決于服務(wù)端實(shí)現(xiàn)需要保留細(xì)節(jié)的細(xì)粒度分類我一般會(huì)先在本地壓到長(zhǎng)邊 1024、質(zhì)量 85 上傳再拿一批樣本對(duì)比「原圖直傳」和「本地壓縮」的分類一致性。如果一致性差異在可接受范圍內(nèi)就固定用壓縮版本單張延遲能降下來(lái)一大截尤其是弱網(wǎng)環(huán)境。這個(gè)對(duì)比實(shí)驗(yàn)花不了多少時(shí)間但能省掉后面反復(fù)懷疑「是不是模型不行」的折騰。5. 避坑與排查401、415、413、超時(shí)重放這四類翻車現(xiàn)場(chǎng)前面幾章都是順著成功路徑寫(xiě)的這一章反過(guò)來(lái)按我踩過(guò)的順序排。每條都按「現(xiàn)象、原因、解決」寫(xiě)遇到類似的直接對(duì)號(hào)入座。5.1 401 Unauthorized密鑰對(duì)了但就是過(guò)不去現(xiàn)象密鑰確認(rèn)沒(méi)復(fù)制錯(cuò)用 curl 試也失敗響應(yīng)體里寫(xiě)著 invalid api key 或 missing authorization。原因通常有三個(gè)。一是Bearer和密鑰之間的空格被編輯器吃掉或者中間混進(jìn)了全角空格二是密鑰從環(huán)境變量讀出來(lái)時(shí)帶了尾部的換行echo復(fù)制的時(shí)候最容易帶上三是用了另一個(gè)產(chǎn)品的密鑰格式看著像但不是同一個(gè)認(rèn)證域。解決先打印repr(API_KEY)看首尾字符把不可見(jiàn)字符暴露出來(lái)如果尾部是\n或者\(yùn)r在讀取時(shí).strip()。再用 curl 獨(dú)立驗(yàn)證一次排除代碼層的干擾# 用環(huán)境變量傳密鑰避免密鑰進(jìn)入 shell history curl -s -o /dev/null -w %{http_code}\n \ -H Authorization: Bearer ${DEEPSEEK_API_KEY} \ https://api.deepseek.com/v1/models返回 200 說(shuō)明密鑰和網(wǎng)絡(luò)都沒(méi)問(wèn)題回到代碼里查頭字典返回 401 就換密鑰或確認(rèn)賬號(hào)權(quán)限。這行命令里的-o /dev/null丟掉響應(yīng)體-w %{http_code}只打狀態(tài)碼輸出干凈。5.2 415 / 400multipart 的 boundary 被自己弄丟了現(xiàn)象圖像上傳返回 415 Unsupported Media Type或者 400 說(shuō)缺少 file 字段但字段名明明寫(xiě)了image。原因頭字典里手寫(xiě)了Content-Type: multipart/form-data。requests 看到你已經(jīng)設(shè)了這個(gè)頭就不再補(bǔ) boundary服務(wù)端拿不到分隔符把整個(gè) body 解析成一個(gè)空字段。這個(gè)坑在把文本和圖像調(diào)用合并成同一個(gè)客戶端時(shí)特別容易犯因?yàn)槟銜?huì)下意識(shí)地給兩類請(qǐng)求都加上Content-Type。解決multipart 請(qǐng)求的頭里只留Authorization讓 requests 自己生成帶 boundary 的完整頭。排查時(shí)打印resp.request.headers看Content-Type里有沒(méi)有boundary這個(gè)參數(shù)沒(méi)有就是這個(gè)問(wèn)題。5.3 413 Payload Too Large圖像沒(méi)壓或者壓了但格式不對(duì)現(xiàn)象小圖能過(guò)大圖報(bào) 413或者本地明明縮放過(guò)上傳后還是 413。原因一是縮放用的resize保留了原始編碼格式PNG 截圖縮到 224 之后體積仍然不小二是只改了尺寸沒(méi)改質(zhì)量JPEG 以 quality100 保存一張 224×224 也能到幾百 KB三是服務(wù)端限制的是字節(jié)數(shù)不是像素?cái)?shù)你盯著尺寸看沒(méi)用。解決統(tǒng)一走 2.3 的normalize_image輸出固定為 JPEG、quality 可控、帶optimizeTrue并在發(fā)送前加一道體積閘門def guard(image_bytes: bytes, max_bytes: int 1_500_000) - bytes: # 超過(guò)閾值就降質(zhì)量重壓最多降三檔避免無(wú)限循環(huán) for q in (85, 70, 55): if len(image_bytes) max_bytes: break from PIL import Image import io buf io.BytesIO() Image.open(io.BytesIO(image_bytes)).save( buf, formatJPEG, qualityq, optimizeTrue) image_bytes buf.getvalue() return image_bytes參數(shù)說(shuō)明max_bytes按接口文檔給1.5 MB 只是個(gè)保守起點(diǎn)三檔質(zhì)量是經(jīng)驗(yàn)值再往下壓細(xì)粒度分類就會(huì)掉點(diǎn)。5.4 超時(shí)后重試導(dǎo)致重復(fù)計(jì)費(fèi)現(xiàn)象賬單上的調(diào)用次數(shù)比實(shí)際圖片數(shù)多或者結(jié)果表里出現(xiàn)重復(fù)記錄且這些記錄的耗時(shí)都集中在某個(gè)時(shí)間窗口。原因讀超時(shí)被算進(jìn)了重試條件。服務(wù)端其實(shí)已經(jīng)處理完了只是響應(yīng)在路上慢了一點(diǎn)客戶端等不及重發(fā)于是同一張圖被處理兩次。原料里的示例沒(méi)有涉及重試但一旦你按 3.3 加了HTTPAdapter這個(gè)問(wèn)題就會(huì)出現(xiàn)。解決Retry里把read設(shè)為 0只對(duì)連接錯(cuò)誤和 429、5xx 重試如果業(yè)務(wù)要求嚴(yán)格冪等就在請(qǐng)求里帶一個(gè)自己生成的request_id落庫(kù)時(shí)用它做唯一鍵重復(fù)的寫(xiě)入直接忽略。這個(gè)字段在服務(wù)端不支持透?jìng)鲿r(shí)也沒(méi)關(guān)系客戶端側(cè)做去重同樣有效。5.5 排查順序從外到內(nèi)別一上來(lái)就懷疑模型遇到分類結(jié)果不對(duì)先別改代碼。按這個(gè)順序走一遍八成問(wèn)題能在前三步定位先用 curl 驗(yàn)證密鑰和端點(diǎn)是否可達(dá)再用固定的一張樣本圖跑一次看響應(yīng)體的原始 JSON 長(zhǎng)什么樣然后比對(duì)預(yù)處理后的圖和原圖確認(rèn)沒(méi)被裁掉主體最后才看 label 和 confidence 的分布。把順序固定下來(lái)之后排查時(shí)間能從半小時(shí)壓到幾分鐘這個(gè)習(xí)慣比任何技巧都值錢。6. 進(jìn)階把分類調(diào)用做成可觀測(cè)的小服務(wù)跑通腳本和能上線之間差的是可觀測(cè)性。分類調(diào)用是個(gè)外部依賴失敗是常態(tài)沒(méi)有埋點(diǎn)的話你只能看到「今天結(jié)果少了」這種結(jié)論看不到是哪一類錯(cuò)誤在漲。我一般會(huì)在客戶端外面再包一層記錄四個(gè)字段請(qǐng)求 ID、端點(diǎn)、狀態(tài)碼、耗時(shí)。加上 label 和 confidence就能回答絕大多數(shù)運(yùn)營(yíng)問(wèn)題比如「昨天的低置信度占比為什么翻倍」。表結(jié)構(gòu)大概是這樣字段類型用途request_idstring客戶端生成的 UUID重試時(shí)復(fù)用用于去重endpointstringimage 或 text區(qū)分兩條鏈路status_codeintHTTP 狀態(tài)碼0 表示網(wǎng)絡(luò)層失敗latency_msint端到端耗時(shí)含重試labelstring分類結(jié)果失敗時(shí)為空confidencefloat置信度用于閾值分布監(jiān)控埋點(diǎn)代碼不用復(fù)雜一個(gè)裝飾器就夠import time import uuid import logging log logging.getLogger(classify) def traced(endpoint: str): def deco(fn): def wrapper(*args, **kwargs): rid kwargs.pop(request_id, None) or str(uuid.uuid4()) start time.perf_counter() status 0 try: result fn(*args, **kwargs) status result.get(code, 200) if result.get(ok) else result.get(code, -1) return result finally: cost int((time.perf_counter() - start) * 1000) # 一行 JSON 日志方便直接被采集器解析 log.info({rid:%s,ep:%s,status:%s,ms:%d}, rid, endpoint, status, cost) return wrapper return deco邏輯說(shuō)明request_id從外部傳入時(shí)復(fù)用重試鏈路里就能對(duì)齊同一次業(yè)務(wù)請(qǐng)求finally保證異常路徑也打點(diǎn)否則失敗樣本全丟監(jiān)控就成了只報(bào)喜不報(bào)憂。參數(shù)說(shuō)明耗時(shí)用perf_counter而不是time.time避免系統(tǒng)時(shí)間調(diào)整帶來(lái)的負(fù)數(shù)狀態(tài)碼在業(yè)務(wù)失敗時(shí)取自定義 code網(wǎng)絡(luò)層失敗統(tǒng)一記 0方便聚合。這套東西的另一個(gè)用法是回歸驗(yàn)證。接口或模型更新后拿一批固定樣本跑一遍比對(duì) label 變化率和置信度均值偏移比肉眼看幾個(gè)案例靠譜得多。我吃過(guò)一次虧換了預(yù)處理里的resize為ImageOps.fit忘了看長(zhǎng)圖樣本結(jié)果一批豎版商品圖被裁掉了底部文字分類整體偏了一檔兩天后才發(fā)現(xiàn)。從那以后我每次改動(dòng)預(yù)處理參數(shù)都強(qiáng)制走一遍固定樣本回歸比對(duì) label 和 confidence 的分布再發(fā)布。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取