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