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