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