1. 先搞清楚這個(gè)方案到底解決了什么問題如果你最近在折騰 DeepSeek 的 API尤其是想用它來開發(fā) AI Agent 或者讓它“看圖說話”那你很可能被一個(gè)叫CC Switch的東西卡住過。報(bào)錯(cuò)信息五花八門什么local proxy failed、status 404、status 401核心問題往往指向一個(gè)叫reasoning_content的參數(shù)。這個(gè)方案的核心價(jià)值就是繞開 CC Switch 這個(gè)復(fù)雜的代理層直接用官方最簡(jiǎn)潔的 Codex 方案在 2 分鐘內(nèi)把 DeepSeek 的 Agent 能力包括識(shí)圖跑起來。它不是什么全新的框架而是對(duì)現(xiàn)有官方接口的一種正確打開方式。很多人被各種第三方工具、中轉(zhuǎn)站和復(fù)雜配置搞暈了其實(shí) DeepSeek 官方通過 Codex提供的接口本身已經(jīng)足夠強(qiáng)大和直接。這個(gè)方案適合兩類人一是被 CC Switch 報(bào)錯(cuò)勸退的開發(fā)者想找個(gè)更穩(wěn)定的接入路徑二是剛接觸 DeepSeek Agent 開發(fā)希望從官方標(biāo)準(zhǔn)方案入手避免一開始就踩進(jìn)配置陷阱的新手。最關(guān)鍵的幾個(gè)能力點(diǎn)在于第一免去了 CC Switch 的本地代理部署和配置環(huán)境依賴極簡(jiǎn)第二直接支持 DeepSeek 的“思考過程”reasoning輸出這是構(gòu)建復(fù)雜 Agent 邏輯的基礎(chǔ)第三原生支持多模態(tài)識(shí)圖VLM不用再單獨(dú)折騰插件第四整個(gè)流程非常標(biāo)準(zhǔn)化后續(xù)對(duì)接 LangChain、LlamaIndex 或者其他 Agent 框架也更順暢。下面我就以一個(gè)剛踩完坑的過來人身份帶你走一遍從零到一的完整流程。我們會(huì)先準(zhǔn)備好環(huán)境然后用最少的代碼跑通一個(gè)能“思考”和“識(shí)圖”的 Agent最后再聊聊批量處理和常見錯(cuò)誤的排查順序。2. 環(huán)境準(zhǔn)備與核心概念澄清在動(dòng)手寫代碼之前有兩件事必須做對(duì)一是拿到正確的通行證API Key二是理解幾個(gè)關(guān)鍵概念避免后續(xù)配置時(shí)張冠李戴。2.1 獲取 API Key 與確認(rèn)端點(diǎn)DeepSeek 的官方 API 接入主要通過其平臺(tái)進(jìn)行。你需要做的是訪問平臺(tái)打開 DeepSeek 的官方平臺(tái)網(wǎng)站這里不提供具體網(wǎng)址請(qǐng)自行搜索 “DeepSeek platform” 或 “DeepSeek console” 找到官網(wǎng)。注冊(cè)與登錄使用郵箱或手機(jī)號(hào)完成注冊(cè)和登錄。創(chuàng)建 API Key在個(gè)人控制臺(tái)或賬戶設(shè)置中找到 “API Keys” 或 “密鑰管理” 相關(guān)頁面創(chuàng)建一個(gè)新的密鑰。務(wù)必妥善保管它就像你的密碼一旦創(chuàng)建頁面關(guān)閉后可能無法再次查看完整密鑰。拿到 Key 之后記下官方提供的API 基礎(chǔ)端點(diǎn)Base URL。對(duì)于直接調(diào)用這個(gè)地址通常是https://api.deepseek.com。這是后續(xù)所有請(qǐng)求的起點(diǎn)與 CC Switch 的本地代理地址如http://localhost:xxx完全不同。2.2 理解 Codex、Harness 與 Agent 的關(guān)系輸入材料里提到了好幾個(gè)詞容易混淆這里快速厘清DeepSeek模型提供方提供了如deepseek-chat、deepseek-v4-flash、deepseek-reasoner等一系列模型。Codex這通常指的是DeepSeek 的官方 API 平臺(tái)或接口規(guī)范。你可以把它理解為 DeepSeek 對(duì)外提供服務(wù)的“官方窗口”。接入 Codex就意味著你正在使用 DeepSeek 官方的、標(biāo)準(zhǔn)化的 API 調(diào)用方式。Harness這是一個(gè)客戶端工具或 SDK。你可以把它想象成一個(gè)更方便的命令行或圖形界面工具用于和 Codex API 交互。它可能提供聊天界面、文件上傳、歷史記錄等功能但其底層通信依然是調(diào)用 Codex API。“DeepSeek Harness 識(shí)圖”這個(gè)熱搜指的就是通過 Harness 這個(gè)工具調(diào)用具備視覺能力的模型。Agent這指的是智能體應(yīng)用。你利用 Codex API 提供的模型能力聊天、推理、識(shí)圖編寫業(yè)務(wù)邏輯使模型能夠感知、規(guī)劃、執(zhí)行任務(wù)這就是在開發(fā)一個(gè) Agent。Codex 是“能力提供方”你的代碼是“調(diào)度指揮方”兩者結(jié)合就成了 Agent。CC Switch這是一個(gè)本地代理/中轉(zhuǎn)工具。它的設(shè)計(jì)初衷可能是為了管理多個(gè)模型供應(yīng)商、實(shí)現(xiàn)負(fù)載均衡或添加額外功能層。但正如很多錯(cuò)誤信息所示如cc switch local proxy failed它在配置和使用中容易引入額外的復(fù)雜性和故障點(diǎn)。本方案的核心思想就是繞過 CC Switch 這個(gè)可能出問題的中間層讓你的代碼直接與 DeepSeek 的官方 Codex API 對(duì)話。這樣鏈路更短問題更易排查。2.3 安裝必要的 Python 環(huán)境我們使用 Python 進(jìn)行演示因?yàn)樗凶钬S富的 AI 開發(fā)生態(tài)。確保你的環(huán)境有Python 版本建議使用 Python 3.8 到 3.11 之間的版本兼容性最好。包管理工具使用pip。關(guān)鍵依賴庫主要需要openai這個(gè)官方庫。DeepSeek 的 API 與 OpenAI 的格式高度兼容這使得我們可以使用非常熟悉的openai庫來調(diào)用。打開你的終端或命令行安裝必備庫pip install openai requests如果網(wǎng)絡(luò)環(huán)境不佳可以考慮使用國(guó)內(nèi)鏡像源例如pip install openai requests -i https://pypi.tuna.tsinghua.edu.cn/simple環(huán)境準(zhǔn)備好后我們就可以開始寫第一個(gè)能“思考”的請(qǐng)求了。3. 第一步跑通帶“思考過程”的對(duì)話 Agent很多高級(jí) Agent 框架需要模型輸出其內(nèi)部的推理鏈條Chain-of-ThoughtDeepSeek 的 API 通過reasoning相關(guān)參數(shù)支持這一點(diǎn)。這也是之前 CC Switch 報(bào)錯(cuò)the \reasoning_content in the thinking mode must be passed back 的根源——代理層沒有正確處理好這個(gè)模式。我們先實(shí)現(xiàn)一個(gè)最簡(jiǎn)單的、能返回思考過程的對(duì)話。3.1 編寫最小化可運(yùn)行代碼創(chuàng)建一個(gè)新的 Python 文件比如deepseek_agent.py輸入以下代碼import os from openai import OpenAI # 1. 設(shè)置你的 DeepSeek API Key 和 Base URL # 注意這里直接使用 DeepSeek 官方端點(diǎn)而非 CC Switch 的本地地址 api_key os.getenv(DEEPSEEK_API_KEY, 你的實(shí)際API密鑰) base_url https://api.deepseek.com # 官方端點(diǎn) # 2. 初始化客戶端 client OpenAI( api_keyapi_key, base_urlbase_url, ) # 3. 發(fā)起一個(gè)要求返回推理內(nèi)容的對(duì)話請(qǐng)求 def chat_with_reasoning(): try: response client.chat.completions.create( modeldeepseek-chat, # 或 deepseek-reasoner 以獲得更強(qiáng)推理能力 messages[ {role: system, content: 你是一個(gè)樂于助人的助手。}, {role: user, content: 魯迅和周樹人是什么關(guān)系請(qǐng)一步步思考。} ], # 關(guān)鍵參數(shù)啟用推理內(nèi)容返回 reasoningTrue, # 要求模型進(jìn)行推理 reasoning_presentation_details{type: concise}, # 推理內(nèi)容呈現(xiàn)細(xì)節(jié) max_tokens1024, streamFalse # 先使用非流式方便查看完整結(jié)構(gòu) ) # 4. 打印響應(yīng) print( 最終回答 ) print(response.choices[0].message.content) print(\n 思考過程 (reasoning_content) ) # 注意思考內(nèi)容在 response.choices[0].message.reasoning_content if hasattr(response.choices[0].message, reasoning_content): print(response.choices[0].message.reasoning_content) else: print(本次響應(yīng)未包含推理內(nèi)容。) except Exception as e: print(f請(qǐng)求發(fā)生錯(cuò)誤: {e}) if __name__ __main__: chat_with_reasoning()3.2 運(yùn)行與結(jié)果解讀將代碼中的你的實(shí)際API密鑰替換為你在 2.1 步驟中獲取的真實(shí) API Key。然后在終端運(yùn)行python deepseek_agent.py如果一切配置正確你會(huì)看到類似下面的輸出 最終回答 魯迅和周樹人是同一個(gè)人。魯迅是周樹人的筆名。 思考過程 (reasoning_content) 1. 用戶問的是“魯迅和周樹人是什么關(guān)系”。 2. 這是一個(gè)關(guān)于中國(guó)現(xiàn)代文學(xué)人物的問題。 3. 我知道魯迅是中國(guó)著名的文學(xué)家、思想家。 4. 我也記得周樹人是魯迅的本名。 5. 因此魯迅是周樹人使用的筆名兩者指向同一個(gè)人。 6. 所以他們的關(guān)系是魯迅是周樹人的筆名周樹人是魯迅的本名實(shí)為同一人。成功的關(guān)鍵標(biāo)志沒有出現(xiàn)404,401,local proxy failed等與 CC Switch 或網(wǎng)絡(luò)代理相關(guān)的錯(cuò)誤。響應(yīng)中除了常規(guī)的message.content還包含了一個(gè)reasoning_content字段里面是模型內(nèi)部的思考步驟。這個(gè)reasoning_content就是構(gòu)建 Agent 的“靈魂”。你可以把它記錄到日志里用于調(diào)試 Agent 的決策過程也可以把它展示給用戶增加可信度更高級(jí)的用法是讓 Agent 根據(jù)思考結(jié)果來決定調(diào)用哪個(gè)工具函數(shù)調(diào)用。3.3 參數(shù)詳解與避坑點(diǎn)model這里用了deepseek-chat它是一個(gè)通用的對(duì)話模型。如果你需要更強(qiáng)的逐步推理能力可以換成deepseek-reasoner。模型列表請(qǐng)以官方文檔為準(zhǔn)。reasoningTrue這是觸發(fā)思考模式的關(guān)鍵開關(guān)。沒有它即使你提示詞里寫了“請(qǐng)一步步思考”API 也不會(huì)在結(jié)構(gòu)化數(shù)據(jù)中返回推理過程。reasoning_presentation_details這個(gè)參數(shù)控制推理內(nèi)容的呈現(xiàn)方式。{type: concise}表示簡(jiǎn)潔模式。你也可以嘗試{type: detailed}獲取更詳細(xì)的步驟。這個(gè)參數(shù)必須和reasoningTrue配合使用否則可能被忽略或報(bào)錯(cuò)。流式輸出Streaming上面的例子用了streamFalse。如果你需要處理長(zhǎng)文本或?qū)崿F(xiàn)打字機(jī)效果可以設(shè)置streamTrue。但在流式響應(yīng)中reasoning_content的處理邏輯會(huì)稍有不同通常會(huì)在最后一個(gè)流片段或單獨(dú)的事件中返回需要你根據(jù)流式響應(yīng)的數(shù)據(jù)結(jié)構(gòu)進(jìn)行拼接。建議初次接入時(shí)先用非流式確保邏輯正確再升級(jí)到流式。避坑提醒不要一上來就使用最復(fù)雜的模型和最長(zhǎng)的文本進(jìn)行測(cè)試。先用deepseek-chat和短問題驗(yàn)證整個(gè)鏈路API Key、網(wǎng)絡(luò)、參數(shù)格式是否通暢。鏈路通了再換更強(qiáng)大的模型如deepseek-reasoner和更復(fù)雜的任務(wù)。4. 第二步實(shí)現(xiàn)多模態(tài)識(shí)圖能力“識(shí)圖”是 DeepSeek V4 等模型的重要能力。通過 Codex API 接入實(shí)現(xiàn)識(shí)圖非常簡(jiǎn)單本質(zhì)上就是按照多模態(tài) API 的格式來構(gòu)造請(qǐng)求消息。4.1 支持圖片輸入的代碼示例我們修改上面的函數(shù)使其支持上傳本地圖片進(jìn)行分析。這里假設(shè)你有一張名為chart.png的圖表圖片。import base64 import os from openai import OpenAI def analyze_image_with_deepseek(image_path): 分析本地圖片 api_key os.getenv(DEEPSEEK_API_KEY, 你的實(shí)際API密鑰) base_url https://api.deepseek.com client OpenAI(api_keyapi_key, base_urlbase_url) # 1. 將圖片編碼為 Base64 def encode_image_to_base64(image_path): with open(image_path, rb) as image_file: return base64.b64encode(image_file.read()).decode(utf-8) image_base64 encode_image_to_base64(image_path) # 2. 按照多模態(tài)消息格式構(gòu)造請(qǐng)求 try: response client.chat.completions.create( modeldeepseek-v4-flash, # 使用支持視覺的模型 messages[ { role: user, content: [ {type: text, text: 請(qǐng)描述這張圖片的主要內(nèi)容并總結(jié)其中的關(guān)鍵信息。}, { type: image_url, image_url: { # 注意DeepSeek API 目前通常支持直接傳遞 base64 數(shù)據(jù) url: fdata:image/png;base64,{image_base64} } } ] } ], max_tokens1024, # 識(shí)圖任務(wù)也可以結(jié)合 reasoning讓模型解釋它看到了什么 # reasoningTrue, # reasoning_presentation_details{type: concise}, ) print( 圖片分析結(jié)果 ) print(response.choices[0].message.content) except Exception as e: print(f圖片分析請(qǐng)求發(fā)生錯(cuò)誤: {e}) if __name__ __main__: # 替換為你的圖片路徑 analyze_image_with_deepseek(./chart.png)4.2 關(guān)鍵格式與模型選擇消息格式多模態(tài)請(qǐng)求的messages中content字段是一個(gè)列表list里面可以包含多個(gè)字典每個(gè)字典代表一個(gè)內(nèi)容塊type可以是text或image_url。圖片數(shù)據(jù)格式如上例所示最通用的方式是將圖片文件讀取為二進(jìn)制數(shù)據(jù)然后進(jìn)行 Base64 編碼最后拼接上data:image/png;base64,這樣的前綴構(gòu)成 Data URL。對(duì)于 JPEG 圖片前綴則為data:image/jpeg;base64,。模型選擇必須使用支持視覺能力的模型例如deepseek-v4-flash、deepseek-v4等。如果你錯(cuò)誤地使用了純文本模型如deepseek-chatAPI 可能會(huì)返回錯(cuò)誤提示模型不支持該功能。結(jié)合 Reasoning你可以同時(shí)設(shè)置reasoningTrue讓模型在分析圖片時(shí)也輸出其推理步驟例如“我首先看到這是一個(gè)柱狀圖橫軸是...縱軸是...因此可以推斷出...”。4.3 處理網(wǎng)絡(luò)圖片與多圖除了本地文件直接處理網(wǎng)絡(luò)圖片 URL 更簡(jiǎn)單messages[ { role: user, content: [ {type: text, text: 這張圖片里是什么}, { type: image_url, image_url: { url: https://example.com/path/to/your/image.jpg # 直接使用圖片URL } } ] } ]處理多張圖片只需在content列表中添加多個(gè)image_url塊即可。模型會(huì)同時(shí)看到所有圖片并進(jìn)行綜合理解。實(shí)測(cè)建議第一次測(cè)試識(shí)圖功能時(shí)建議使用一張內(nèi)容簡(jiǎn)單、清晰的圖片比如一個(gè)蘋果、一段文字截圖。先確保基礎(chǔ)的圖片上傳、編碼、API 調(diào)用流程能跑通得到正確的文本描述。之后再嘗試復(fù)雜的圖表分析、多圖關(guān)系推理等任務(wù)。這樣可以快速定位問題是出在圖片處理環(huán)節(jié)還是模型理解環(huán)節(jié)。5. 第三步構(gòu)建一個(gè)簡(jiǎn)單的任務(wù)型 Agent 骨架現(xiàn)在我們把對(duì)話和識(shí)圖能力結(jié)合起來形成一個(gè)能根據(jù)用戶指令自主選擇能力的簡(jiǎn)單 Agent 骨架。這個(gè) Agent 會(huì)判斷用戶需求是否需要識(shí)圖然后采取相應(yīng)行動(dòng)。5.1 一個(gè)簡(jiǎn)單的決策循環(huán)示例這個(gè)例子展示了 Agent 的核心循環(huán)理解用戶意圖 - 決定是否使用視覺能力 - 執(zhí)行 - 返回結(jié)果。import base64 import os from openai import OpenAI from typing import Optional class SimpleVisionAgent: def __init__(self): self.api_key os.getenv(DEEPSEEK_API_KEY, 你的實(shí)際API密鑰) self.base_url https://api.deepseek.com self.client OpenAI(api_keyself.api_key, base_urlself.base_url) # 用于存儲(chǔ)當(dāng)前會(huì)話的上下文 self.conversation_history [] def _encode_image(self, image_path): with open(image_path, rb) as f: return base64.b64encode(f.read()).decode(utf-8) def _call_model(self, messages, use_visionFalse, modelNone): 調(diào)用模型的統(tǒng)一方法 if model is None: model deepseek-v4-flash if use_vision else deepseek-chat try: response self.client.chat.completions.create( modelmodel, messagesmessages, max_tokens1024, reasoningTrue, # 讓Agent也輸出它的“思考” reasoning_presentation_details{type: concise}, streamFalse, ) return response except Exception as e: print(f模型調(diào)用失敗: {e}) return None def _needs_vision(self, user_input: str) - bool: 一個(gè)簡(jiǎn)單的意圖判斷用戶是否需要圖片分析 # 這里可以用更復(fù)雜的 NLP 或規(guī)則來判斷 vision_keywords [圖片, 圖像, 照片, 圖, 看看這個(gè), 識(shí)別, 描述一下這張, chart, graph] return any(keyword in user_input.lower() for keyword in vision_keywords) def run(self, user_input: str, image_path: Optional[str] None): 運(yùn)行Agent的主要入口 :param user_input: 用戶文本指令 :param image_path: 可選如果用戶提供了圖片路徑 print(f\n[用戶指令] {user_input}) # 1. 更新對(duì)話歷史 self.conversation_history.append({role: user, content: user_input}) # 2. 判斷是否需要視覺能力 needs_vision self._needs_vision(user_input) or (image_path is not None) use_vision_model needs_vision # 3. 準(zhǔn)備消息 messages_for_api [] # 可以加入系統(tǒng)提示詞定義Agent角色 messages_for_api.append({role: system, content: 你是一個(gè)能處理文本和圖片的智能助手。如果需要分析圖片請(qǐng)?jiān)敿?xì)描述。請(qǐng)一步步思考。}) # 加入歷史對(duì)話這里簡(jiǎn)單起見只用了最新一輪 messages_for_api.extend(self.conversation_history[-3:]) # 保留最近3輪作為上下文 # 如果需要視覺且提供了圖片路徑構(gòu)造多模態(tài)消息 if needs_vision and image_path: image_base64 self._encode_image(image_path) # 構(gòu)造一個(gè)包含圖片的新用戶消息替換或追加到歷史中 multimodal_message { role: user, content: [ {type: text, text: user_input}, { type: image_url, image_url: { url: fdata:image/png;base64,{image_base64} } } ] } # 用多模態(tài)消息替換最后一條用戶消息 messages_for_api[-1] multimodal_message # 4. 調(diào)用模型 print(f[Agent決策] 使用視覺模型: {use_vision_model}) response self._call_model(messages_for_api, use_visionuse_vision_model) if response and response.choices: assistant_message response.choices[0].message final_answer assistant_message.content reasoning assistant_message.reasoning_content if hasattr(assistant_message, reasoning_content) else None print(f\n[Agent思考過程]) print(reasoning if reasoning else 無思考過程) print(f\n[Agent最終回復(fù)]) print(final_answer) # 5. 將助手的回復(fù)加入歷史以便后續(xù)多輪對(duì)話 self.conversation_history.append({role: assistant, content: final_answer}) return final_answer, reasoning else: return 抱歉處理您的請(qǐng)求時(shí)出現(xiàn)了問題。, None # 使用示例 if __name__ __main__: agent SimpleVisionAgent() # 場(chǎng)景1純文本對(duì)話 print( 場(chǎng)景1純文本問答 ) agent.run(魯迅的原名是什么) # 場(chǎng)景2圖片分析假設(shè)當(dāng)前目錄有‘chart.png’ print(\n\n 場(chǎng)景2圖片分析 ) # 注意這里模擬用戶指令包含了圖片關(guān)鍵詞并提供了路徑 agent.run(請(qǐng)分析一下這張圖表告訴我趨勢(shì)。, image_path./chart.png) # 場(chǎng)景3基于歷史的連續(xù)對(duì)話 print(\n\n 場(chǎng)景3連續(xù)對(duì)話 ) agent.run(我上一張圖里哪個(gè)柱子的值最高)5.2 從骨架到真實(shí) Agent上面的代碼是一個(gè)高度簡(jiǎn)化的骨架真實(shí)可用的 Agent 還需要考慮很多方面工具調(diào)用Function Calling這是現(xiàn)代 Agent 的核心。你需要定義一系列工具函數(shù)如搜索、計(jì)算、查數(shù)據(jù)庫并在系統(tǒng)提示詞中告訴模型這些工具的描述。模型在推理后會(huì)返回一個(gè)請(qǐng)求調(diào)用特定工具的結(jié)構(gòu)化信息你的代碼需要解析這個(gè)信息并執(zhí)行對(duì)應(yīng)函數(shù)再將結(jié)果返回給模型進(jìn)行總結(jié)。DeepSeek 的 API 同樣支持類似 OpenAI 的 function calling 或 tool calling 格式。上下文管理上面的例子只保留了最近幾輪對(duì)話。真實(shí)場(chǎng)景需要更智能的上下文窗口管理可能涉及摘要、選擇性記憶等。異步與流式為了更好的用戶體驗(yàn)尤其是處理耗時(shí)任務(wù)時(shí)需要使用異步調(diào)用和流式輸出。錯(cuò)誤處理與重試網(wǎng)絡(luò)波動(dòng)、API 限流、令牌超限等情況都需要有相應(yīng)的重試和降級(jí)機(jī)制。更復(fù)雜的意圖識(shí)別可以用一個(gè)輕量級(jí)分類模型或更復(fù)雜的提示詞工程來替代簡(jiǎn)單的關(guān)鍵詞匹配以更準(zhǔn)確地判斷用戶是否需要視覺、搜索、計(jì)算等能力。關(guān)鍵建議不要試圖一開始就構(gòu)建一個(gè)全能的 Agent。先從解決一個(gè)具體問題開始比如“一個(gè)能分析上傳圖表并總結(jié)的客服機(jī)器人”。把這個(gè)垂直場(chǎng)景下的文本理解、圖片處理、信息提取、格式化回復(fù)的流程完全跑通、跑穩(wěn)定。之后再考慮如何接入更多工具、管理更長(zhǎng)的對(duì)話歷史。這種“單點(diǎn)打透”的方式能幫你積累最實(shí)在的經(jīng)驗(yàn)避開同時(shí)處理多個(gè)未知問題的泥潭。6. 常見問題排查與優(yōu)化建議當(dāng)你按照上述步驟操作時(shí)可能會(huì)遇到一些問題。下面是一個(gè)從外到內(nèi)的排查清單。6.1 網(wǎng)絡(luò)與認(rèn)證問題癥狀連接超時(shí)、401 Unauthorized、403 Forbidden。排查順序API Key確認(rèn)復(fù)制的 API Key 完整無誤沒有多余空格。最好將 Key 設(shè)置在環(huán)境變量中如DEEPSEEK_API_KEY而不是硬編碼在代碼里。Base URL確認(rèn)base_url是https://api.deepseek.com。如果你從其他教程里拷貝了代碼檢查是否不小心包含了 CC Switch 的本地地址如http://127.0.0.1:xxxx。網(wǎng)絡(luò)連通性在終端使用curl或ping命令測(cè)試是否能訪問api.deepseek.com。注意企業(yè)網(wǎng)絡(luò)或某些地區(qū)網(wǎng)絡(luò)可能存在的限制。賬戶狀態(tài)登錄 DeepSeek 平臺(tái)確認(rèn)賬戶是否正常API 調(diào)用額度是否充足。6.2 請(qǐng)求參數(shù)與格式錯(cuò)誤癥狀400 Bad Request、the \reasoning_content in the thinking mode must be passed back、model not found。排查順序模型名稱確認(rèn)model參數(shù)的值是有效的官方模型名如deepseek-chat,deepseek-reasoner,deepseek-v4-flash。模型名是大小寫敏感的且可能隨時(shí)間更新。reasoning參數(shù)確保當(dāng)你需要思考過程時(shí)設(shè)置了reasoningTrue。同時(shí)檢查reasoning_presentation_details的格式是否正確是一個(gè)字典。消息格式對(duì)于純文本messages中的content是字符串。對(duì)于多模態(tài)識(shí)圖content必須是列表且image_url的格式正確包含url字段且是有效的 Data URL 或公網(wǎng) URL。JSON 序列化確保你傳遞給client.chat.completions.create的參數(shù)都是可被 JSON 序列化的 Python 基本類型字典、列表、字符串、數(shù)字、布爾值。自定義對(duì)象會(huì)導(dǎo)致錯(cuò)誤。6.3 圖片處理相關(guān)問題癥狀識(shí)圖請(qǐng)求失敗或返回的結(jié)果似乎沒有看到圖片。排查順序文件路徑與權(quán)限確認(rèn)image_path變量指向的圖片文件真實(shí)存在且當(dāng)前 Python 進(jìn)程有讀取權(quán)限。使用絕對(duì)路徑可以避免歧義。圖片編碼確認(rèn) Base64 編碼函數(shù)工作正常。一個(gè)簡(jiǎn)單的驗(yàn)證方法是編碼后再將 Base64 字符串解碼并保存為新文件看新文件是否能正常打開。圖片大小與格式API 通常對(duì)圖片大小有限制例如小于 20MB。過大的圖片需要先進(jìn)行壓縮或裁剪。確保圖片格式是支持的如 PNG, JPEG, WebP。Data URL 格式確認(rèn)拼接的 Data URL 格式為f“data:image/{格式};base64,{你的base64字符串}”其中{格式}要與圖片實(shí)際格式匹配如png,jpeg。6.4 性能與穩(wěn)定性優(yōu)化當(dāng)你的 Agent 開始處理真實(shí)任務(wù)時(shí)需要考慮以下幾點(diǎn)令牌Token管理關(guān)注請(qǐng)求的max_tokens和實(shí)際消耗的令牌數(shù)響應(yīng)中的usage字段。過長(zhǎng)的上下文和回復(fù)會(huì)消耗更多令牌增加成本和延遲。合理設(shè)置max_tokens并對(duì)過長(zhǎng)的輸入進(jìn)行摘要或截?cái)唷３瑫r(shí)設(shè)置在初始化OpenAI客戶端時(shí)可以設(shè)置timeout參數(shù)單位秒避免因網(wǎng)絡(luò)慢或模型處理時(shí)間長(zhǎng)導(dǎo)致程序長(zhǎng)時(shí)間掛起。client OpenAI(api_keyapi_key, base_urlbase_url, timeout30.0)重試機(jī)制對(duì)于可能因網(wǎng)絡(luò)抖動(dòng)導(dǎo)致的臨時(shí)性失敗可以引入重試邏輯例如使用tenacity庫。但要注意對(duì)于 4xx 客戶端錯(cuò)誤如 400, 401重試通常無效需要先修正請(qǐng)求本身。異步調(diào)用如果你的應(yīng)用需要同時(shí)處理多個(gè)請(qǐng)求或不想阻塞主線程使用openai庫的異步客戶端AsyncOpenAI。日志記錄務(wù)必記錄每次請(qǐng)求的輸入脫敏后、輸出、令牌用量和耗時(shí)。這是后續(xù)分析性能瓶頸、優(yōu)化提示詞、排查異常的基礎(chǔ)。6.5 關(guān)于“CC Switch”遺留問題的徹底解決如果你之前的環(huán)境配置過 CC Switch并且現(xiàn)在想徹底清理確保新代碼不受影響檢查環(huán)境變量在終端中運(yùn)行env | grep -i proxy和env | grep -i http查看是否有HTTP_PROXY、HTTPS_PROXY或ALL_PROXY等環(huán)境變量指向了本地 CC Switch 的代理地址如127.0.0.1:xxxx。如果有在運(yùn)行你的 Python 腳本前可以臨時(shí)取消設(shè)置unset HTTP_PROXY HTTPS_PROXY或者在代碼中讓requests庫openai庫底層使用忽略這些代理import os os.environ[NO_PROXY] api.deepseek.com # 或者更徹底地在創(chuàng)建客戶端時(shí)指定 from openai import OpenAI import requests client OpenAI( api_keyapi_key, base_urlbase_url, http_clientrequests.Session() # 使用一個(gè)不繼承全局代理設(shè)置的session )清理配置文件檢查你的用戶主目錄下是否有.bashrc,.zshrc,.profile或系統(tǒng)級(jí)的配置文件刪掉其中與 CC Switch 代理相關(guān)的設(shè)置行。重啟終端或 IDE修改環(huán)境變量后關(guān)閉所有終端窗口和 IDE重新打開使新環(huán)境生效。遵循“官方 Codex API 直連”這個(gè)方案上述大多數(shù)由中間代理引發(fā)的問題都將不復(fù)存在。你的開發(fā)鏈路會(huì)變得清晰、穩(wěn)定更接近于生產(chǎn)環(huán)境的標(biāo)準(zhǔn)集成方式。