簡(jiǎn)介針對(duì)DeepSeek API調(diào)用的入門示例代碼包該zip壓縮包共4個(gè)文件包含兩個(gè)Python演示腳本、LICENSE與.gitignore整體僅14KB體量輕巧適合剛接觸大模型接口的開發(fā)者快速閱讀與修改。腳本demo.py與demo_loop.py分別演示單次請(qǐng)求與循環(huán)調(diào)用的基本寫法結(jié)合通用API調(diào)用流程查閱官方文檔、獲取密鑰、構(gòu)造HTTP請(qǐng)求、解析響應(yīng)、異常處理、速率限制等可幫助學(xué)習(xí)者建立清晰的調(diào)用框架并將思路遷移到實(shí)際業(yè)務(wù)場(chǎng)景中。示例代碼結(jié)構(gòu)簡(jiǎn)潔注釋直接便于在此基礎(chǔ)上擴(kuò)展為批量調(diào)用或異步任務(wù)無論是個(gè)人試驗(yàn)還是項(xiàng)目預(yù)研都有直接參考價(jià)值。同時(shí)包內(nèi)附帶許可證文件便于確認(rèn)使用范圍.gitignore則提示提交代碼時(shí)需規(guī)避密鑰等敏感信息。目前已有283人學(xué)習(xí)下載對(duì)于想低成本上手DeepSeek開放接口的讀者而言這是一份簡(jiǎn)潔實(shí)用的起步參考。1. DeepSeek API 調(diào)用從 demo 壓縮包到第一行可用代碼如果你下載過“deepseek-demo-master.zip”這種名字的壓縮包大概率是想快速驗(yàn)證 DeepSeek API 怎么調(diào)用。這類包通常在代碼托管平臺(tái)能搜到作者把最小可用示例打包好但你解壓后照著 README 跑第一個(gè)坑就來了不是 401 鑒權(quán)失敗就是缺依賴甚至卡在“模型名寫錯(cuò)了”這種最沒技術(shù)含量的報(bào)錯(cuò)上。DeepSeek API 調(diào)用本身不復(fù)雜它兼容 OpenAI 的報(bào)文協(xié)議核心就三件事鑒權(quán)頭、消息體結(jié)構(gòu)、模型名。這篇筆記直接用這個(gè) demo 包的常見形態(tài)展開講清楚解壓之后怎么跑通、代碼每一行在干什么、參數(shù)怎么調(diào)以及我踩過的幾個(gè)翻車點(diǎn)。適合剛接觸大模型 API 的開發(fā)者也適合想把 demo 改成生產(chǎn)代碼的人。2. 跑通 demo 最小環(huán)境解壓、安裝依賴與第一次請(qǐng)求2.1 解壓后先看骨架哪些文件決定你能不能跑deepseek-demo-master.zip 這種包解壓出來通常不會(huì)只有一兩個(gè)文件。常見做法是包含 README、requirements.txt、一個(gè) .env.example以及 src 或 demo 目錄下的 Python 腳本。很多剛上手的人一上來就找 .py 文件直接python xxx.py結(jié)果要么報(bào)ModuleNotFoundError要么報(bào) API Key 沒設(shè)置。我一般會(huì)先按順序看三樣?xùn)|西README 里標(biāo)注的運(yùn)行步驟、requirements.txt 里的依賴清單、代碼里讀取 API Key 的方式。讀取方式?jīng)Q定了你會(huì)不會(huì)踩“鑒權(quán)失敗”的坑。如果 demo 用的是os.getenv(DEEPSEEK_API_KEY)那你就得先設(shè)置環(huán)境變量或者在調(diào)用腳本前用 export 注入如果它支持從 .env 文件讀取那你要先把 .env.example 復(fù)制成 .env 再填 Key。這兩種方式混著用是 demo 跑不通的頭號(hào)原因。拿到壓縮包第一件事不是改代碼是把 Key 的讀取鏈路捋清楚。2.2 Python 環(huán)境準(zhǔn)備與依賴安裝demo 基本都基于 Python 3 寫的實(shí)測(cè) 3.9 到 3.12 都能跑問題大多出在依賴安裝不完整。先把虛擬環(huán)境建起來避免把本機(jī) Python 環(huán)境搞亂這一步對(duì)要同時(shí)跑多個(gè) demo 的人尤其重要。以下是我本地跑這種 demo 包的固定步驟。python3 -m venv venv source venv/bin/activate pip install -r requirements.txt依賴裝完先別急著跑打開 requirements.txt 看一眼有沒有openai這個(gè)庫。DeepSeek API 調(diào)用最常見的封裝方式就是直接用 openai 的 Python SDK然后把 base_url 指向 DeepSeek 的接口地址這個(gè)庫沒裝上后面所有代碼都會(huì)報(bào)No module named openai。另一個(gè)容易漏的是python-dotenv因?yàn)?demo 里如果寫了load_dotenv()少了它 .env 文件不會(huì)生效API Key 讀出來永遠(yuǎn)是 None。參數(shù)說明venv是虛擬環(huán)境目錄名你可以改成項(xiàng)目名requirements.txt必須在解壓后的根目錄執(zhí)行否則路徑不對(duì)裝不到當(dāng)前環(huán)境。裝完之后用pip list核對(duì) openai 和 python-dotenv 是否在列表里這一步能省掉后面一半的排錯(cuò)時(shí)間。2.3 用手工 Key 發(fā)第一個(gè)請(qǐng)求不依賴 demo 的驗(yàn)證方法我習(xí)慣先把 demo 放一邊自己寫一個(gè)最小腳本驗(yàn)證 Key 和網(wǎng)絡(luò)通不通。這樣做的好處是把問題邊界劃清楚如果這個(gè)腳本通了說明 Key 沒問題、網(wǎng)絡(luò)沒問題剩下就是 demo 代碼的問題如果這個(gè)腳本都報(bào)錯(cuò)那就別去改 demo 了先解決 Key 或網(wǎng)絡(luò)。這個(gè)思維方式在處理任何開源 demo 時(shí)都能用少做無用功。from openai import OpenAI client OpenAI( api_keysk-你實(shí)際的key, # 臨時(shí)測(cè)試可硬編碼生產(chǎn)環(huán)境必須走環(huán)境變量 base_urlhttps://api.deepseek.com ) resp client.chat.completions.create( modeldeepseek-chat, messages[ {role: user, content: 你好用一句話介紹你自己} ], streamFalse, max_tokens100 ) print(resp.choices[0].message.content)這段代碼邏輯很直白先創(chuàng)建客戶端對(duì)象傳 base_url 讓 SDK 知道請(qǐng)求發(fā)到哪里然后調(diào)用chat.completions.create發(fā)聊天補(bǔ)全請(qǐng)求model 指定用 deepseek-chatmessages 傳用戶輸入stream 關(guān)掉表示等完整結(jié)果返回。返回的響應(yīng)對(duì)象里choices[0].message.content就是模型生成的文本。參數(shù)說明base_url一定要和官方文檔保持一致有的老 demo 寫的是https://api.deepseek.com/v1實(shí)際上不帶 v1 也能通但建議以每個(gè)請(qǐng)求里實(shí)際打印出來的 URL 為準(zhǔn)max_tokens100是控制生成長(zhǎng)度的不傳的話模型按默認(rèn)值走可能一次性輸出很長(zhǎng)streamFalse是阻塞式等待拿到完整結(jié)果才會(huì)往下走。Key 硬編碼只適合這種一次性驗(yàn)證腳本跑通后立刻改成讀環(huán)境變量。3. 讀懂 demo 里的調(diào)用鏈路SDK 封裝背后的報(bào)文結(jié)構(gòu)3.1 純 HTTP 調(diào)用Authorization 與請(qǐng)求體逐個(gè)拆開openai SDK 只是把 HTTP 請(qǐng)求包了一層真正發(fā)給 DeepSeek API 的報(bào)文結(jié)構(gòu)你必須看得懂否則出問題你都不知道往哪個(gè)字段查。用最原始的 requests 庫寫一遍效果一樣還能讓你看清鑒權(quán)和消息體的全部細(xì)節(jié)。調(diào)試階段我經(jīng)常用這個(gè)方式把 response 原樣打印出來。import requests url https://api.deepseek.com/chat/completions headers { Authorization: Bearer sk-你實(shí)際的key, # Bearer 后必須有空格 Content-Type: application/json } payload { model: deepseek-chat, messages: [ {role: system, content: 你是一個(gè)Python開發(fā)助手}, {role: user, content: 幫我看一下這段代碼為什么會(huì)內(nèi)存暴漲} ], stream: False, max_tokens: 500 } resp requests.post(url, headersheaders, jsonpayload, timeout30) data resp.json() print(data[choices][0][message][content])這個(gè)代碼每次調(diào)用都把 payload 完整拼一遍適合理解接口但生產(chǎn)環(huán)境不建議這么寫因?yàn)槿绷酥卦嚭彤惓６档?。headers 里最關(guān)鍵的是 Authorization前面固定是Bearer注意 Bearer 后面有個(gè)空格少了空格服務(wù)端解析不出 token直接返回 401Content-Type 告訴服務(wù)端你發(fā)的是 JSON。payload 里的 model、messages、max_tokens 和 SDK 版一一對(duì)應(yīng)沒有任何隱藏字段。參數(shù)說明timeout30是 requests 的請(qǐng)求超時(shí)時(shí)間單位秒不設(shè)的話可能一直掛著等響應(yīng)這在高并發(fā)或服務(wù)端繁忙時(shí)會(huì)拖死你的線程resp.json()解析服務(wù)端返回的 JSON但如果返回的是錯(cuò)誤信息而不是補(bǔ)全結(jié)果字段結(jié)構(gòu)會(huì)不一樣所以生產(chǎn)代碼拿到響應(yīng)后要先判斷status_code再解析這個(gè)在后面的避坑章里細(xì)說。3.2 openai 兼容 SDKdemo 為什么敢只寫幾行demo 里大多數(shù)代碼直接用 openai SDK是因?yàn)?DeepSeek API 和 OpenAI API 的報(bào)文協(xié)議完全兼容你只需要替換 base_url 和 api_key剩下的 SDK 全幫你處理。SDK 封裝了請(qǐng)求序列化、響應(yīng)解析、錯(cuò)誤類型轉(zhuǎn)換還帶了超時(shí)控制和流式迭代器。對(duì)業(yè)務(wù)開發(fā)來說這是效率最高的方式也是我推薦的方式。from openai import OpenAI client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com ) def chat(prompt: str) - str: resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: prompt}], streamFalse ) return resp.choices[0].message.content這里os.getenv(DEEPSEEK_API_KEY)從環(huán)境變量讀 Key比硬編碼安全得多。SDK 在底層幫你做了幾件事把 messages 列表序列化成 JSON、在請(qǐng)求頭里自動(dòng)拼上 Authorization、把 HTTP 錯(cuò)誤映射成 openai 庫的異常類型。所以你只需要關(guān)注 model 和 messages 兩個(gè)字段。注意 base_url 和 api_key 這兩個(gè)參數(shù)名是 SDK 約定的拼錯(cuò)了它不會(huì)報(bào)錯(cuò)但請(qǐng)求會(huì)打到錯(cuò)誤地址或帶不上鑒權(quán)信息表現(xiàn)就是連接超時(shí)或 401。參數(shù)說明messages 是角色消息列表一般只有三類角色——system 用來設(shè)定行為user 是用戶輸入assistant 是模型歷史回復(fù)。多輪對(duì)話就是把這幾類消息按順序往列表里追加。這個(gè)結(jié)構(gòu)是所有兼容 OpenAI 協(xié)議的 API 通用的你在 DeepSeek demo 里看到的結(jié)構(gòu)換到別的服務(wù)商也能直接用只是 base_url 和 model 名不同。3.3 把 stream 打開demo 沒細(xì)講但聊天機(jī)器人必用的模式demo 里常把 stream 設(shè)為 False因?yàn)檫@樣代碼最簡(jiǎn)單拿到完整文本一次性返回。但要做聊天機(jī)器人、流式輸出效果必須開 stream。服務(wù)端會(huì)像打字機(jī)一樣一段一段往外推 token用戶體驗(yàn)好很多而且首字延遲低長(zhǎng)回答不用干等十幾秒。真實(shí)項(xiàng)目的聊天功能幾乎都用流式我這里演示 demo 里很少寫全的部分。from openai import OpenAI client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com ) resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 給我講一個(gè)技術(shù)人相親的笑話}], streamTrue, max_tokens300 ) for chunk in resp: delta chunk.choices[0].delta if delta and delta.content: print(delta.content, end, flushTrue)流式模式下resp不再是完整的響應(yīng)對(duì)象而是一個(gè)可迭代的生成器每個(gè) chunk 包含一小段增量?jī)?nèi)容。增量?jī)?nèi)容在chunk.choices[0].delta.content里可能是空字符串所以要做if delta and delta.content的判空。flushTrue讓內(nèi)容不緩沖立刻打印到終端模擬打字機(jī)效果。參數(shù)說明streamTrue一旦打開返回結(jié)構(gòu)完全變了不能再用resp.choices[0].message.content取文本每個(gè) chunk 里還可能出現(xiàn)delta.role或finish_reason字段finish_reason 在最后一個(gè) chunk 里會(huì)出現(xiàn)stop用來判斷生成是否完整。如果要做 UI 流式展示需要在前端把這段文本追加到緩沖區(qū)而不是每次替換否則會(huì)看到內(nèi)容跳變。4. 按場(chǎng)景調(diào) DeepSeek API 參數(shù)temperature、max_tokens 與 stop 的取舍4.1 參數(shù)速查表先抄這張表再微調(diào)DeepSeek API 調(diào)用過程中模型名只決定能力邊界真正決定輸出風(fēng)格的是一組采樣參數(shù)。demo 里通常只寫了 temperature 和 max_tokens但實(shí)際項(xiàng)目中還需要 top_p、stop、presence_penalty 和 frequency_penalty。這些參數(shù)不是隨便調(diào)的每個(gè)都有明確的行為含義而且和業(yè)務(wù)場(chǎng)景強(qiáng)相關(guān)。參數(shù)取值范圍默認(rèn)值作用適用場(chǎng)景temperature0~21采樣隨機(jī)性值越低越確定代碼生成、數(shù)據(jù)提取用 0~0.3top_p0~11核采樣與 temperature 配合不建議同時(shí)改需要可控創(chuàng)造力時(shí)配合調(diào)max_tokens1~81924096單次生成的最大 token 數(shù)按輸出長(zhǎng)度需求設(shè)置stop字符串?dāng)?shù)組null遇到指定詞立即停止生成防輸出越界如 \n\npresence_penalty-2~20對(duì)已出現(xiàn)過的詞做懲罰值越高越鼓勵(lì)探討新話題頭腦風(fēng)暴frequency_penalty-2~20對(duì)高頻詞做懲罰值越高越避免重復(fù)措辭長(zhǎng)文生成table 里面有幾組參數(shù)要特別注意。temperature 和 top_p 官方建議是改一個(gè)就行兩個(gè)同時(shí)調(diào)容易互相打架輸出變得不可控max_tokens 不是越大越好它直接影響成本和響應(yīng)時(shí)間demo 里給 4096 是為了展示能力上限生產(chǎn)環(huán)境按業(yè)務(wù)給 200~800 就夠stop 參數(shù)對(duì)控制輸出格式極其有用比如讓模型只返回 JSON可以在 stop 里放一個(gè)結(jié)束標(biāo)志。參數(shù)說明temperature0 不代表每次輸出完全一樣在 GPU 上采樣仍有一定隨機(jī)性但語義層面基本穩(wěn)定適合做抽取、分類這種不能瞎發(fā)揮的任務(wù)做創(chuàng)意文案、營(yíng)銷標(biāo)題可以調(diào) 0.8~1.2超過 1.5 之后輸出容易崩壞出現(xiàn)句子斷裂、邏輯混亂。這里有一個(gè)很實(shí)用的調(diào)參順序先固定 temperature再調(diào) presence_penalty 控制話題發(fā)散度最后用 max_tokens 掐長(zhǎng)度不要上來就動(dòng)所有參數(shù)。4.2 對(duì)話任務(wù)里的上下文管理messages 是怎么累積的demo 的多輪對(duì)話示例往往只寫了兩三條消息但真實(shí)聊天機(jī)器人跑幾輪之后messages 數(shù)組會(huì)越來越大最終觸發(fā)上下文長(zhǎng)度限制。這里的關(guān)鍵認(rèn)知是API 調(diào)用是無狀態(tài)的每一次請(qǐng)求都要把全部歷史消息再發(fā)一遍服務(wù)端不會(huì)幫你存任何會(huì)話記憶。所以每輪請(qǐng)求都要重新拼 messages這也是為什么上下文管理直接決定了成本和使用體驗(yàn)。常見做法是維護(hù)一個(gè)滑動(dòng)窗口只保留最近 N 條消息。代碼上就是給 messages 數(shù)組做截?cái)嗟⌒牟荒馨?system 消息截掉否則角色設(shè)定就丟了。我之前踩過這個(gè)坑截?cái)嗪瘮?shù)每次從第 0 條開始砍結(jié)果 system 消息被砍了模型立刻從一個(gè)客服變成另一個(gè)沒性格的角色問答質(zhì)量明顯下降。MAX_TOKENS 4096 def trim_messages(messages, max_history20): system_msgs [m for m in messages if m[role] system] history_msgs [m for m in messages if m[role] ! system] if len(history_msgs) max_history: history_msgs history_msgs[-max_history:] return system_msgs history_msgs這段代碼的做法是先把 system 消息分離出來避免被誤刪再對(duì)非 system 的歷史消息做長(zhǎng)度截?cái)嘀槐Ａ糇詈?20 條。這里截?cái)噙壿嬍前礂l數(shù)算的不是按 token 數(shù)嚴(yán)格一點(diǎn)應(yīng)該統(tǒng)計(jì)每條消息的 token 數(shù)量再截。但大多數(shù)文本場(chǎng)景下按條數(shù)截?cái)嗉右粋€(gè) max_tokens 兜底就夠用。參數(shù)說明max_history是保留消息條數(shù)按你的業(yè)務(wù)量調(diào)整如果每輪回答都很長(zhǎng)20 條可能已經(jīng)超了上下文限制那就要縮到 10 條如果想更精細(xì)可以用 tiktoken 之類的分詞庫把每條消息 token 數(shù)累加超過閾值就從前往后刪。別忘了截?cái)嘀皇菓?yīng)用層策略API 層的上下窗口是模型決定的超了會(huì)直接報(bào)錯(cuò)后面避坑章里有具體現(xiàn)象。4.3 內(nèi)容安全與輸出約束stop、max_tokens 與懲罰項(xiàng)的正確姿勢(shì)業(yè)務(wù)接入 DeepSeek API 調(diào)用后不能把模型輸出當(dāng)黑匣子必須有約束手段。最常見的是用 stop 參數(shù)掐斷生成比如你想讓模型只輸出 JSON不去解釋、不去客氣就可以在 stop 里加 \n\n 或者 。模型生成到 stop 標(biāo)記時(shí)會(huì)立即停下省 token 也省時(shí)間。另一個(gè)被忽略的參數(shù)組合是 presence_penalty 和 frequency_penalty。這兩個(gè)值越高模型越不想重復(fù)已經(jīng)出現(xiàn)過的內(nèi)容但也越容易讓回答顯得跳脫值設(shè)為負(fù)數(shù)模型會(huì)傾向用重復(fù)的表達(dá)反而更有固定風(fēng)格。實(shí)測(cè)做小紅書文案這種需要風(fēng)格統(tǒng)一的場(chǎng)景frequency_penalty 設(shè) 0.2~0.5 效果不錯(cuò)做代碼注釋生成直接設(shè) 0 就好不需要發(fā)散去寫新話術(shù)。resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 把這一段會(huì)議紀(jì)要整理成三個(gè)要點(diǎn)}], temperature0.1, max_tokens300, stop[\n\n], presence_penalty0.2, frequency_penalty0.1 )這里 temperature 給到 0.1 是為了讓要點(diǎn)整理這種抽取式任務(wù)盡量穩(wěn)定出結(jié)果avoid 模型自由發(fā)揮stop 里放了空行標(biāo)記模型寫第一個(gè)要點(diǎn)和第二個(gè)要點(diǎn)之間有空行時(shí)會(huì)停下來你拿到的就是干凈的三點(diǎn)列表。實(shí)際上 stop 的觸發(fā)是匹配到字符串即終止這不代表它會(huì)刪除已經(jīng)生成的部分所以拿到的文本里可能還帶一個(gè)空行解析時(shí)要做 strip。參數(shù)說明stop 數(shù)組最多可以傳 4 個(gè)字符串每個(gè)都要精確匹配常見用法是傳 \n、\n\n、. 這種標(biāo)點(diǎn)符號(hào)但要注意別傳太短的字符比如單傳一個(gè)空格模型幾乎每一兩秒就觸發(fā)一次生成內(nèi)容直接被截?cái)嗟經(jīng)]有意義。調(diào)這個(gè)參數(shù)時(shí)先打印一兩次不帶 stop 的完整輸出看它自然終止在什么位置再去設(shè)置對(duì)應(yīng)的 stop 值這才是靠譜的操作順序。5. DeepSeek API 調(diào)用常見問題與避坑記錄5.1 401 鑒權(quán)失敗Key 復(fù)制少了字符或帶進(jìn)了換行現(xiàn)象是請(qǐng)求發(fā)出后立刻返回 401響應(yīng)體里寫著 Invalid Authentication但代碼檢查了 Key 看著沒問題。這個(gè)問題的隱藏原因基本在兩個(gè)地方復(fù)制 Key 時(shí)少了最后幾個(gè)字符或者終端粘貼時(shí)把換行符帶了進(jìn)去。尤其從網(wǎng)頁控制臺(tái)復(fù)制 Key復(fù)制完末尾會(huì)有一些不可見字符打印出來也不容易發(fā)現(xiàn)。解決方法是不要在代碼里直接比對(duì) Key 的字符串而是打印它的長(zhǎng)度和最后一個(gè)字符。正確 Key 的長(zhǎng)度是固定的少了兩位以上基本就是復(fù)制不完整如果長(zhǎng)度對(duì)但還報(bào)錯(cuò)用repr(key)看末尾是否多了\\n。我在本地調(diào)試時(shí)習(xí)慣把 Key 先寫進(jìn)一個(gè)臨時(shí)文件再用cat讀取確保不經(jīng)過終端剪貼板這種方式能排除絕大部分人為復(fù)制問題。5.2 429 限流與并發(fā)配額demo 壓測(cè)翻車現(xiàn)場(chǎng)現(xiàn)象是腳本單次調(diào)用正常一旦用并發(fā)循環(huán)連續(xù)調(diào)用前面幾次成功后面突然報(bào) 429 Too Many Requests。原因是對(duì) DeepSeek API 調(diào)用頻率和并發(fā)有配額限制demo 不會(huì)把配額寫進(jìn)注釋里很多人把它當(dāng)成無限制接口去跑循環(huán)壓測(cè)很快就打到上限。尤其for循環(huán)里不加 sleep幾秒鐘發(fā)幾十個(gè)請(qǐng)求必被限流。解決方式是先查詢你當(dāng)前賬號(hào)的速率限制然后按限制調(diào)整請(qǐng)求間隔。最簡(jiǎn)單是代碼里加time.sleep(0.5)或用線程池限制最大并發(fā)數(shù)更穩(wěn)的是對(duì) 429 做指數(shù)退避重試。重試前先讀響應(yīng)頭里的Retry-After字段如果服務(wù)端告訴你要等多久就按這個(gè)時(shí)間等否則自己按 1、2、4 秒遞增重試。壓測(cè)之前把配額搞清楚是每個(gè)開發(fā)者的基本素養(yǎng)。5.3 輸出被截?cái)鄊ax_tokens 沒給夠或 stop 設(shè)錯(cuò)位置現(xiàn)象是長(zhǎng)文本生成到一半就停了內(nèi)容最后一句明顯沒寫完檢查返回?cái)?shù)據(jù)里finish_reason為length而不是stop。finish_reason是判斷截?cái)囝愋偷墓俜街笜?biāo)length表示 max_tokens 耗盡或觸頂stop表示正常結(jié)束或命中 stop 標(biāo)記。demo 里如果沒打印這個(gè)字段很多人會(huì)誤以為模型生成完了。原因是 max_tokens 設(shè)置值小于實(shí)際需要的輸出長(zhǎng)度。解決方式先按輸出字符數(shù)估算 token中文字符大概 0.6~1 token 一個(gè)英文約 1 token 一個(gè)單詞再加 20% 余量。如果業(yè)務(wù)上無法預(yù)估長(zhǎng)度就把 max_tokens 調(diào)到模型最大值同時(shí)在前端做“生成中”狀態(tài)提示而不是依賴它一定能一次輸出完。反過來如果 finish_reason 是 stop 但內(nèi)容還是斷了那就是 stop 參數(shù)里的字符串過早匹配把 stop 數(shù)組里太短的條目刪掉再試。5.4 上下文長(zhǎng)度越界多輪對(duì)話歷史堆太多現(xiàn)象是多輪對(duì)話進(jìn)行到十幾輪后突然報(bào)錯(cuò)提示 context length exceeded 或類似的超限錯(cuò)誤。原因是 messages 數(shù)組里累積的歷史太多token 總長(zhǎng)度超過了模型單次請(qǐng)求的上限。demo 的循環(huán)對(duì)話示例幾乎沒有做歷史清理跑幾輪沒問題跑久了必爆。這個(gè)問題在長(zhǎng)文檔問答場(chǎng)景里尤其明顯因?yàn)閱螚l user 消息就可能塞進(jìn)幾千 token兩三輪就超限了。解決方式是在應(yīng)用層做兩層保險(xiǎn)第一層按條數(shù)截?cái)鄽v史保 system 消息第二層按 token 數(shù)估算超過閾值就從最舊消息開始刪。更優(yōu)解是做上下文摘要把早期對(duì)話用模型概括成一段摘要塞到 system 消息里替代原始?xì)v史。這個(gè)方案工程量大但效果好能支持真正長(zhǎng)時(shí)間運(yùn)行的會(huì)話場(chǎng)景。別指望 API 側(cè)會(huì)幫你自動(dòng)精簡(jiǎn)歷史它只按你給的消息列表執(zhí)行。5.5 JSON 解析報(bào)錯(cuò)模型輸出不是合法 JSON現(xiàn)象是你在 prompt 里要求“只輸出 JSON”但返回內(nèi)容里夾了 markdown 代碼塊、開頭有廢話、結(jié)尾多了逗號(hào)json.loads直接拋異常。原因是模型輸出遵循的是概率分布prompt 指令不是硬約束它可能會(huì)帶上 json 標(biāo)記或說明性文字。demo 里如果直接把響應(yīng)交給 json.loads必然不定期翻車。解決方式不是改 prompt 去祈禱而是寫一個(gè)健壯的解析函數(shù)。先把響應(yīng)里兩個(gè) 之間的內(nèi)容提取出來再去掉首尾空白最后用json.loads解析失敗時(shí)用正則摳出最外層大括號(hào)再試一次。我在生產(chǎn)代碼里把這套邏輯封裝成了一個(gè)函數(shù)后續(xù)不管換什么模型都不怕輸出格式漂移。import json, re def parse_json(text: str) - dict: text text.strip() code_block re.search(r(?:json)?\s*(.*?), text, re.DOTALL) if code_block: text code_block.group(1).strip() try: return json.loads(text) except json.JSONDecodeError: start, end text.find({), text.rfind(}) if start ! -1 and end start: return json.loads(text[start:end1]) raise ValueError(無法從模型輸出中解析JSON)這個(gè)函數(shù)先把常見的 json 代碼塊包裹去掉然后嘗試直接解析失敗后用首尾大括號(hào)截取子串再試。re.DOTALL讓正則里的.能匹配換行不然多行 JSON 就匹配不到。參數(shù)上沒太多可調(diào)的核心思路是多級(jí)降級(jí)而不是一次解析定生死。實(shí)測(cè)這個(gè)函數(shù)能消化九成以上的格式漂移輸出剩下的直接拋錯(cuò)并讓上層走重試流程。6. 把 demo 改造成可上線的調(diào)用骨架三個(gè)進(jìn)階技巧6.1 統(tǒng)一請(qǐng)求封裝超時(shí)、重試與日志一次解決demo 里的調(diào)用函數(shù)是裸的沒有超時(shí)控制沒有重試異常只打印不處理。上線前必須包一層統(tǒng)一入口把超時(shí)、重試、日志都收攏。我一般會(huì)封裝一個(gè)ask_deepseek函數(shù)所有模塊調(diào)用它不在業(yè)務(wù)代碼里直接 new OpenAI client。這樣以后改模型名、換接口地址只動(dòng)一處。import logging, time from openai import OpenAI client OpenAI(api_keyos.getenv(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com) def ask_deepseek(messages, retries3, **kwargs): for attempt in range(retries): try: resp client.chat.completions.create( modeldeepseek-chat, messagesmessages, timeout30, **kwargs ) return resp.choices[0].message.content except Exception as e: logging.warning(f第{attempt1}次調(diào)用失敗: {e}) if attempt retries - 1: time.sleep(2 ** attempt) raise RuntimeError(DeepSeek API 調(diào)用失敗)思路是失敗時(shí)按 1、2 秒退避重試最多三次。timeout30在 SDK 里可以直接透?jìng)鞯讓訉?duì)應(yīng) HTTP 超時(shí)。日志統(tǒng)一記到 warning方便后續(xù)排查。這個(gè)封裝犧牲了一點(diǎn)靈活性但換來的是全項(xiàng)目調(diào)用行為的統(tǒng)一線上排查翻日志時(shí)非常舒服。6.2 流式響應(yīng)接入 UI事件回調(diào)與消息解析流式接口返回的 chunk 不是整段文本UI 需要逐段更新。如果直接把 demo 的流式代碼搬到 Flask 里返回給前端前端要自己處理 SSE 協(xié)議比較麻煩。常見做法是后端把流式結(jié)果逐段 push 到消息隊(duì)列前端通過 WebSocket 或 SSE 接收。這里給出一個(gè)最簡(jiǎn)單的生成器版本適合 FastAPI 的 StreamingResponse 或 Flask 的 Response。def stream_chat(messages): resp client.chat.completions.create( modeldeepseek-chat, messagesmessages, streamTrue, temperature0.7 ) for chunk in resp: delta chunk.choices[0].delta if delta and delta.content: yield delta.content.encode(utf-8)這個(gè)生成器每次產(chǎn)出一段二進(jìn)制文本上層可以直接喂給響應(yīng)流。關(guān)鍵點(diǎn)是控制編碼因?yàn)榫W(wǎng)絡(luò)傳輸要字節(jié)流。如果要做更細(xì)粒度的事件類型區(qū)分可以檢查chunk.choices[0].finish_reason等于stop時(shí)推送一個(gè)結(jié)束事件前端借此關(guān)閉 loading 狀態(tài)。6.3 做一個(gè)輕量語義緩存控制成本與重復(fù)調(diào)用demo 里每調(diào)一次接口就計(jì)費(fèi)一次但項(xiàng)目里很多請(qǐng)求是重復(fù)的比如用戶問了同一個(gè)問題兩次、或模板化 prompt 只有變量不同。對(duì)這類場(chǎng)景我習(xí)慣在 API 層之前加一個(gè)語義緩存用嵌入向量的相似度判斷是否命中。先算 prompt 的向量指紋命中就直接返回緩存文本不發(fā)起 API 請(qǐng)求。實(shí)現(xiàn)不用很重一個(gè)內(nèi)存字典加一個(gè)相似度計(jì)算就能應(yīng)付原型階段。cache {} def cached_ask(messages, threshold0.96): user_input messages[-1][content] # 簡(jiǎn)化做法用字符串哈希做精確緩存語義緩存需換成向量相似度 key user_input.strip() if key in cache: return cache[key] result ask_deepseek(messages) cache[key] result return result這段代碼是最原始的精確緩存同一個(gè)問題重復(fù)問會(huì)直接走緩存。生產(chǎn)版要加上向量化語義匹配比如把輸入 embedding 后算余弦相似度超過閾值視為同一問題。這里要特別提醒緩存鍵千萬要包含 messages 的完整上下文只拿最后一條用戶消息做鍵會(huì)導(dǎo)致上下文不同但問題相同的場(chǎng)景誤命中給出答非所問的緩存結(jié)果。這個(gè)坑我踩過后來把 system 消息和用戶消息拼在一起算哈希才解決。以上三個(gè)技巧做完demo 就已經(jīng)從“能跑”變成“能上線”。我一直覺得開源 demo 的價(jià)值不是拿來直接用而是拿來拆解它背后暴露的完整鏈路鑒權(quán)、參數(shù)、流式、異常。每次運(yùn)行它都要問自己一句如果明天流量翻十倍這個(gè)調(diào)用方式還能扛住嗎答案不能的時(shí)候就是該動(dòng)手改造的時(shí)候了。希望這篇筆記能幫你更快走完這條路。本文還有配套的精品資源點(diǎn)擊獲取