實戰(zhàn)：從零構(gòu)建自定義Tool與函數(shù)調(diào)用)
1. 項目概述為什么我們要親手打造一個DeepSeek插件最近在折騰DeepSeek的API發(fā)現(xiàn)官方提供的工具雖然強大但總有些特定場景下的需求沒法直接滿足。比如我想讓它能一鍵調(diào)用我內(nèi)部系統(tǒng)的數(shù)據(jù)查詢接口或者整合一些只有我們團隊在用的特殊工具鏈。這時候官方的通用工具就顯得有點“隔靴搔癢”了。于是我花了幾天時間深入研究了一下DeepSeek的插件或者說“工具調(diào)用”開發(fā)機制從最基礎(chǔ)的“Hello World”開始一步步實現(xiàn)了一個能根據(jù)我自定義邏輯運行的Tool。整個過程下來感覺就像給一個超級大腦裝上了專屬的“瑞士軍刀”讓它不僅能思考還能直接操作我的“私人工具箱”。這個實戰(zhàn)過程本質(zhì)上是在與大型語言模型的“工具調(diào)用”能力打交道。DeepSeek作為模型本身并不直接執(zhí)行代碼或訪問外部系統(tǒng)但它可以理解你的需求并“決定”在合適的時機調(diào)用你預先定義好的工具函數(shù)。我們開發(fā)者要做的就是按照它約定的格式把這些工具“描述”給它并準備好真正的執(zhí)行后端。這比單純調(diào)用API完成一次對話要復雜一些但帶來的靈活性和自動化潛力是指數(shù)級增長的。無論是想連接數(shù)據(jù)庫、觸發(fā)自動化腳本、還是調(diào)用第三方服務只要你能用代碼實現(xiàn)就能把它封裝成一個Tool讓DeepSeek模型來智能調(diào)度。2. 核心概念與準備工作理解Tool、Function Calling與插件生態(tài)在動手寫代碼之前我們必須先理清幾個關(guān)鍵概念否則很容易在后續(xù)開發(fā)中迷失方向。這些概念是構(gòu)建一切的基礎(chǔ)。2.1 Tool、Function Calling與插件它們到底是什么關(guān)系這幾個詞經(jīng)?；煊玫珖栏駚碚f它們指代的是同一流程的不同層面。Function Calling函數(shù)調(diào)用 這是一種協(xié)議或機制。它規(guī)定了大型語言模型如DeepSeek如何向外部系統(tǒng)“表達”它想要執(zhí)行某個操作的意圖。通常模型會在回復中輸出一個結(jié)構(gòu)化的JSON對象其中包含了它想調(diào)用的函數(shù)名以及傳入的參數(shù)。這不是真正的代碼執(zhí)行只是一個“請求”或“指令”。Tool工具 這是Function Calling機制中被調(diào)用的具體對象。一個Tool就是一個可執(zhí)行單元它對應一個具體的功能。在DeepSeek的語境下我們通過一個JSON Schema來定義一個Tool包括它的名稱、描述、參數(shù)列表等。模型只認識Tool的定義。插件Plugin 這是一個更上層的產(chǎn)品化概念。你可以把一個或多個相關(guān)的Tool打包配上圖標、描述文檔、認證方式等形成一個完整的、可供用戶安裝和使用的功能模塊。我們本次實戰(zhàn)聚焦在Tool的開發(fā)這是構(gòu)建插件最核心的一步。簡單類比Function Calling是“點菜”這個行為Tool是菜單上的一道道“菜”如魚香肉絲而Plugin則是一個完整的“套餐”或“特色菜系”。2.2 開發(fā)環(huán)境與工具鏈選擇工欲善其事必先利其器。為了高效開發(fā)我選擇了以下組合這套組合在靈活性和開發(fā)體驗上取得了很好的平衡。編程語言Python 3.9。這是AI領(lǐng)域事實上的標準語言生態(tài)庫豐富與DeepSeek API的交互有成熟的SDK支持。核心SDK官方deepseek庫。通過pip install deepseek安裝。這是與DeepSeek模型服務通信的官方橋梁。輔助工具Pydantic。這是一個用于數(shù)據(jù)驗證和設置管理的庫。在定義Tool的復雜參數(shù)結(jié)構(gòu)時使用Pydantic的BaseModel會讓代碼清晰、安全且易于維護。通過pip install pydantic安裝。開發(fā)環(huán)境 任意你熟悉的IDE或編輯器即可比如VSCode或PyCharm。關(guān)鍵是要能方便地調(diào)試和查看日志。DeepSeek API密鑰 你需要一個有效的DeepSeek API Key。前往DeepSeek平臺注冊并獲取。請妥善保管不要直接硬編碼在代碼中。注意 API Key是訪問服務的憑證務必通過環(huán)境變量或配置文件來管理。我習慣在項目根目錄創(chuàng)建一個.env文件使用python-dotenv庫加載絕對不要提交到代碼倉庫。# 示例 .env 文件內(nèi)容 DEEPSEEK_API_KEYyour_api_key_here2.3 項目結(jié)構(gòu)規(guī)劃一個清晰的項目結(jié)構(gòu)能讓你后續(xù)的開發(fā)和維護事半功倍。這是我采用的目錄結(jié)構(gòu)deepseek-custom-tool-demo/ ├── .env # 存儲環(huán)境變量API Key等 ├── .gitignore # Git忽略文件 ├── requirements.txt # 項目依賴列表 ├── src/ # 源代碼目錄 │ ├── __init__.py │ ├── tools/ # 存放所有自定義Tool的定義和實現(xiàn) │ │ ├── __init__.py │ │ ├── calculator.py # 示例計算器工具 │ │ └── weather.py # 示例天氣查詢工具 │ ├── schemas/ # 存放Pydantic數(shù)據(jù)模型用于參數(shù)驗證 │ │ ├── __init__.py │ │ └── weather.py # 天氣查詢的參數(shù)模型 │ └── main.py # 主程序入口組裝和運行 └── README.md # 項目說明文檔這個結(jié)構(gòu)將工具定義、數(shù)據(jù)模型和主邏輯分離符合單一職責原則未來添加新工具會非常方便。3. 從零實現(xiàn)第一個ToolHello World與計算器讓我們從一個最簡單的例子開始確保整個鏈路是通的。這個階段的目標不是功能多復雜而是驗證“模型能理解我們的工具描述并能觸發(fā)我們寫的代碼”。3.1 最簡示例Echo Tool回聲工具這個工具的功能是模型讓它說什么它就原樣返回什么。雖然簡單但能完整走通流程。首先在src/tools/目錄下創(chuàng)建echo.py# src/tools/echo.py import json from typing import Any, Dict def echo_tool(arguments: Dict[str, Any]) - str: 一個簡單的回聲工具返回傳入的消息。 這是Tool的執(zhí)行函數(shù)。 # 從模型傳來的參數(shù)中獲取消息 message arguments.get(message, ) # 這里可以加入任何你想執(zhí)行的邏輯 result fEcho: {message} print(f[Tool Log] Echo工具被調(diào)用參數(shù): {arguments}, 結(jié)果: {result}) return result # Tool的定義JSON Schema # 這個定義是給DeepSeek模型“看”的告訴它這個工具叫什么、能干嘛、需要什么參數(shù)。 ECHO_TOOL_SCHEMA { type: function, function: { name: echo, # 工具名稱模型調(diào)用時使用 description: 一個簡單的回聲工具用于測試和驗證工具調(diào)用流程。輸入什么就返回什么。, parameters: { type: object, properties: { message: { type: string, description: 需要被回聲的消息內(nèi)容, } }, required: [message], # 指定哪些參數(shù)是必須的 additionalProperties: False, # 禁止傳入未定義的參數(shù)更安全 }, }, }關(guān)鍵點解析執(zhí)行函數(shù) (echo_tool) 這是實際被執(zhí)行的Python函數(shù)。它接收一個字典arguments里面包含了模型根據(jù)對話內(nèi)容“推斷”并填充好的參數(shù)。函數(shù)最后返回一個字符串結(jié)果。工具定義 (ECHO_TOOL_SCHEMA) 這是一個符合OpenAI Function Calling格式的字典。name是唯一標識description至關(guān)重要模型靠它來理解何時該調(diào)用此工具。parameters定義了輸入?yún)?shù)的JSON Schemarequired數(shù)組聲明了必填參數(shù)。接下來在src/main.py中編寫主邏輯# src/main.py import os from dotenv import load_dotenv from deepseek import DeepSeek # 導入我們定義的工具 from src.tools.echo import echo_tool, ECHO_TOOL_SCHEMA # 加載環(huán)境變量 load_dotenv() def main(): # 1. 初始化DeepSeek客戶端 client DeepSeek(api_keyos.getenv(DEEPSEEK_API_KEY)) # 2. 準備對話歷史和工具列表 messages [{role: user, content: 請讓回聲工具說一句‘你好世界’}] tools [ECHO_TOOL_SCHEMA] # 將工具定義提供給模型 # 3. 發(fā)起第一次對話請求告訴模型有哪些工具可用 response client.chat.completions.create( modeldeepseek-chat, # 指定模型 messagesmessages, toolstools, tool_choiceauto, # 讓模型自行決定是否調(diào)用工具 ) # 4. 處理模型響應 message response.choices[0].message print(f模型原始回復: {message}) # 5. 檢查模型是否決定調(diào)用工具 if message.tool_calls: print(模型決定調(diào)用工具) for tool_call in message.tool_calls: # tool_call是一個對象包含工具名和參數(shù) tool_name tool_call.function.name tool_args json.loads(tool_call.function.arguments) # 參數(shù)是JSON字符串需要解析 # 6. 根據(jù)工具名找到對應的本地執(zhí)行函數(shù)并調(diào)用 if tool_name echo: tool_result echo_tool(tool_args) print(f工具執(zhí)行結(jié)果: {tool_result}) # 7. 將工具執(zhí)行結(jié)果作為新的消息追加到對話歷史中讓模型知曉 messages.append(message) # 先追加模型的消息包含工具調(diào)用請求 messages.append({ role: tool, content: tool_result, tool_call_id: tool_call.id, # 必須對應告訴模型這是哪個調(diào)用的結(jié)果 }) # 8. 再次請求模型讓它基于工具結(jié)果生成最終回復 second_response client.chat.completions.create( modeldeepseek-chat, messagesmessages, ) final_reply second_response.choices[0].message.content print(f\n模型的最終回復: {final_reply}) else: print(f未知工具調(diào)用: {tool_name}) else: # 模型沒有調(diào)用工具直接輸出內(nèi)容 print(f模型直接回復: {message.content}) if __name__ __main__: main()運行這個程序如果你看到類似以下的輸出那么恭喜你第一個Tool已經(jīng)成功跑通了模型原始回復: ChatCompletionMessage(contentNone, roleassistant, function_callNone, tool_calls[ChatCompletionMessageToolCall(idcall_abc123, functionFunction(arguments{message:你好世界}, nameecho), typefunction)]) 模型決定調(diào)用工具 [Tool Log] Echo工具被調(diào)用參數(shù): {message: 你好世界}, 結(jié)果: Echo: 你好世界 工具執(zhí)行結(jié)果: Echo: 你好世界 模型的最終回復: 工具已經(jīng)執(zhí)行并返回了結(jié)果“Echo: 你好世界”。如你所見它成功地將“你好世界”這句話原樣返回了。這個流程是標準的多輪交互用戶請求 - 模型決定調(diào)用工具并返回調(diào)用指令 - 本地執(zhí)行工具 - 將結(jié)果返回給模型 - 模型生成最終回答。3.2 進階示例智能計算器工具現(xiàn)在我們來做一個更有用的工具一個能理解自然語言計算請求的智能計算器。這個例子展示了如何處理更復雜的參數(shù)和邏輯。首先用Pydantic定義參數(shù)模型這能讓參數(shù)驗證和代碼提示更友好。在src/schemas/calculator.py中# src/schemas/calculator.py from pydantic import BaseModel, Field from typing import Literal class CalculatorInput(BaseModel): operation: Literal[add, subtract, multiply, divide] Field( ..., description運算類型加(add)、減(subtract)、乘(multiply)、除(divide) ) a: float Field(..., description第一個運算數(shù)) b: float Field(..., description第二個運算數(shù)) # 可以添加自定義驗證例如除法時除數(shù)不能為0 # 這里為了演示我們在工具函數(shù)里處理然后在src/tools/calculator.py中實現(xiàn)工具# src/tools/calculator.py import json from typing import Any, Dict from src.schemas.calculator import CalculatorInput def calculator_tool(arguments: Dict[str, Any]) - str: 一個智能計算器工具執(zhí)行基礎(chǔ)算術(shù)運算。 try: # 使用Pydantic模型驗證和解析參數(shù) calc_input CalculatorInput(**arguments) a calc_input.a b calc_input.b result None if calc_input.operation add: result a b op_symbol elif calc_input.operation subtract: result a - b op_symbol - elif calc_input.operation multiply: result a * b op_symbol * elif calc_input.operation divide: if b 0: return 錯誤除數(shù)不能為零。 result a / b op_symbol / else: return f錯誤不支持的運算類型 {calc_input.operation}。 return f計算結(jié)果{a} {op_symbol} {result} except Exception as e: # 捕獲參數(shù)驗證錯誤或其他異常 return f工具執(zhí)行出錯{str(e)} # 工具定義 # 注意這里的parameters可以從Pydantic模型自動生成但為清晰起見我們手動寫一份。 # 在實際大型項目中可以使用pydantic的model_json_schema()方法自動生成。 CALCULATOR_TOOL_SCHEMA { type: function, function: { name: calculator, description: 執(zhí)行基礎(chǔ)算術(shù)運算加、減、乘、除。當用戶需要進行數(shù)學計算時使用此工具。, parameters: { type: object, properties: { operation: { type: string, enum: [add, subtract, multiply, divide], description: 運算類型加(add)、減(subtract)、乘(multiply)、除(divide) }, a: { type: number, description: 第一個運算數(shù) }, b: { type: number, description: 第二個運算數(shù) } }, required: [operation, a, b], additionalProperties: False, }, }, }實操心得description字段是工具能否被正確調(diào)用的靈魂。模型完全依賴這個描述來判斷“什么時候該用這個工具”。所以描述要盡可能精確、無歧義并包含典型的使用場景。例如“當用戶需要進行數(shù)學計算時使用此工具”就比“這是一個計算器”要好得多。更新main.py引入計算器工具并進行測試# 在main.py中更新導入和工具列表 from src.tools.calculator import calculator_tool, CALCULATOR_TOOL_SCHEMA # ... 其他導入 ... def main(): client DeepSeek(api_keyos.getenv(DEEPSEEK_API_KEY)) messages [{role: user, content: 請幫我計算一下3.14乘以256等于多少}] # 可以同時提供多個工具給模型選擇 tools [ECHO_TOOL_SCHEMA, CALCULATOR_TOOL_SCHEMA] response client.chat.completions.create( modeldeepseek-chat, messagesmessages, toolstools, tool_choiceauto, ) # ... 后續(xù)處理邏輯與echo示例類似需要根據(jù)tool_name調(diào)用對應的calculator_tool ...運行后模型應該能正確理解“3.14乘以256”這個自然語言請求將其轉(zhuǎn)化為operation: multiply, a: 3.14, b: 256的參數(shù)并調(diào)用我們的calculator_tool得到正確結(jié)果。4. 構(gòu)建復雜且實用的自定義Tool天氣查詢代理現(xiàn)在我們來挑戰(zhàn)一個更接近真實場景的例子一個天氣查詢工具。這個工具需要調(diào)用外部API處理網(wǎng)絡請求和JSON數(shù)據(jù)解析并且參數(shù)結(jié)構(gòu)也更復雜。4.1 設計數(shù)據(jù)模型與工具定義假設我們調(diào)用一個虛擬的天氣API它需要城市名和查詢單位公制/英制。首先在src/schemas/weather.py中定義參數(shù)模型# src/schemas/weather.py from pydantic import BaseModel, Field from typing import Literal, Optional class WeatherQueryInput(BaseModel): city: str Field(..., description需要查詢天氣的城市名稱例如北京、Shanghai、New York) units: Optional[Literal[metric, imperial]] Field( defaultmetric, description溫度單位。metric表示攝氏度(°C)imperial表示華氏度(°F)。默認為metric。 ) # 可以擴展更多參數(shù)如語言、預報天數(shù)等 # forecast_days: Optional[int] Field(default1, ge1, le7, description預報天數(shù)1-7天)接著在src/tools/weather.py中實現(xiàn)工具。這里我們模擬一個API調(diào)用# src/tools/weather.py import json import random import time from typing import Any, Dict from src.schemas.weather import WeatherQueryInput def mock_weather_api(city: str, units: str metric) - Dict[str, Any]: 模擬一個天氣API的響應。 在實際項目中這里應該替換為真實的HTTP請求例如使用requests庫。 # 模擬網(wǎng)絡延遲 time.sleep(0.5) # 生成一些模擬數(shù)據(jù) temp random.uniform(15, 35) if units metric else random.uniform(59, 95) humidity random.randint(30, 90) conditions [晴朗, 多云, 局部多云, 小雨, 雷陣雨] condition random.choice(conditions) return { city: city, temperature: round(temp, 1), units: °C if units metric else °F, humidity: f{humidity}%, condition: condition, timestamp: time.strftime(%Y-%m-%d %H:%M:%S), } def weather_tool(arguments: Dict[str, Any]) - str: 查詢指定城市的當前天氣情況。 try: # 1. 參數(shù)驗證與解析 query WeatherQueryInput(**arguments) city query.city units query.units or metric # 使用默認值 # 2. 調(diào)用模擬外部API print(f[Tool Log] 正在查詢{city}的天氣單位: {units}...) weather_data mock_weather_api(city, units) # 3. 格式化結(jié)果使其對模型和用戶都友好 result_str ( f{weather_data[city]}的當前天氣\n f- 天氣狀況{weather_data[condition]}\n f- 溫度{weather_data[temperature]}{weather_data[units]}\n f- 濕度{weather_data[humidity]}\n f- 數(shù)據(jù)更新時間{weather_data[timestamp]} ) return result_str except Exception as e: # 記錄詳細錯誤日志但返回給模型的錯誤信息要簡潔 print(f[Tool Error] 天氣查詢失敗: {e}) return f抱歉查詢{city}的天氣時出現(xiàn)錯誤。請檢查城市名稱是否正確或稍后再試。 # 工具定義 WEATHER_TOOL_SCHEMA { type: function, function: { name: get_current_weather, description: 獲取指定城市的當前天氣信息包括溫度、濕度和天氣狀況。當用戶詢問天氣、氣候或溫度時使用此工具。, parameters: { type: object, properties: { city: { type: string, description: 城市名稱必須清晰明確。例如‘北京’、‘紐約’、‘London’。 }, units: { type: string, enum: [metric, imperial], description: 溫度單位。metric為攝氏度imperial為華氏度。如果不指定默認使用metric。 } }, required: [city], # units 是可選的 additionalProperties: False, }, }, }4.2 在主程序中集成與測試更新main.py集成天氣工具并嘗試更復雜的對話# 更新main.py的導入和主邏輯 from src.tools.weather import weather_tool, WEATHER_TOOL_SCHEMA def run_conversation(): client DeepSeek(api_keyos.getenv(DEEPSEEK_API_KEY)) # 初始對話可以混合多個工具 tools [CALCULATOR_TOOL_SCHEMA, WEATHER_TOOL_SCHEMA] messages [{role: user, content: 今天杭州天氣怎么樣另外幫我算算去那里出差三天如果每天餐費預算150元總共需要多少}] # 第一輪模型可能會先調(diào)用天氣工具 response client.chat.completions.create( modeldeepseek-chat, messagesmessages, toolstools, tool_choiceauto, ) message response.choices[0].message messages.append(message) # 將模型的回復含工具調(diào)用加入歷史 # 處理可能的多工具調(diào)用循環(huán) while message.tool_calls: for tool_call in message.tool_calls: tool_name tool_call.function.name tool_args json.loads(tool_call.function.arguments) if tool_name get_current_weather: tool_result weather_tool(tool_args) elif tool_name calculator: tool_result calculator_tool(tool_args) else: tool_result f錯誤未知工具 {tool_name}。 # 將工具執(zhí)行結(jié)果追加 messages.append({ role: tool, content: tool_result, tool_call_id: tool_call.id, }) # 再次請求模型讓它基于所有工具結(jié)果繼續(xù)回復或調(diào)用新工具 response client.chat.completions.create( modeldeepseek-chat, messagesmessages, toolstools, # 工具列表在后續(xù)輪次中通常也需要傳遞 ) message response.choices[0].message if message.content or message.tool_calls: messages.append(message) # 打印最終結(jié)果 print(\n 對話完成 ) for msg in messages: if msg[role] assistant and msg.get(content): print(f助理: {msg[content]}) elif msg[role] tool: print(f[工具結(jié)果]: {msg[content]}) if __name__ __main__: run_conversation()這個例子展示了幾個高級特性多工具協(xié)同 模型可以理解一個復雜問題中包含的多個子任務查天氣、做計算并依次或并行調(diào)用不同的工具。循環(huán)處理 通過while循環(huán)可以處理模型可能發(fā)起的連續(xù)多次工具調(diào)用。錯誤處理與友好反饋 在工具函數(shù)內(nèi)部進行了異常捕獲并返回了對用戶友好的錯誤信息而不是崩潰或拋出技術(shù)棧追蹤。5. 工程化與最佳實踐讓自定義Tool更健壯當工具數(shù)量增多、邏輯變復雜后代碼的組織和健壯性就變得至關(guān)重要。以下是我在實踐中總結(jié)的幾個關(guān)鍵點。5.1 工具的動態(tài)注冊與發(fā)現(xiàn)機制手動維護一個tools列表在工具少的時候還行多了就非常麻煩。我們可以建立一個注冊機制。在src/tools/__init__.py中# src/tools/__init__.py 工具注冊中心。 所有工具在此注冊便于主程序統(tǒng)一加載。 import inspect from typing import Dict, Callable, Any # 全局注冊表 _tool_registry: Dict[str, Dict[str, Any]] { # 格式: tool_name: {function: callable, schema: dict} } def register_tool(schema: dict): 裝飾器用于注冊工具。 用法 register_tool(MY_TOOL_SCHEMA) def my_tool_function(arguments): ... def decorator(func: Callable): tool_name schema[function][name] _tool_registry[tool_name] { function: func, schema: schema } return func return decorator def get_all_tool_schemas(): 獲取所有已注冊工具的定義 return [info[schema] for info in _tool_registry.values()] def execute_tool(tool_name: str, arguments: dict) - str: 根據(jù)工具名執(zhí)行對應的工具函數(shù) if tool_name not in _tool_registry: raise ValueError(f工具 {tool_name} 未注冊。) tool_info _tool_registry[tool_name] return tool_info[function](arguments)然后修改我們的工具文件使用裝飾器注冊# src/tools/weather.py (更新版) from src.tools import register_tool # ... 其他導入和WeatherQueryInput ... register_tool(WEATHER_TOOL_SCHEMA) # 使用裝飾器注冊 def weather_tool(arguments: Dict[str, Any]) - str: # ... 函數(shù)實現(xiàn)不變 ...最后主程序可以簡化為# main.py (更新版) from src.tools import get_all_tool_schemas, execute_tool # 只需導入工具模塊裝飾器會自動注冊 import src.tools.echo import src.tools.calculator import src.tools.weather def run_conversation(): client DeepSeek(...) # 動態(tài)獲取所有已注冊的工具定義 tools get_all_tool_schemas() messages [...] # ... 后續(xù)循環(huán)中調(diào)用 execute_tool(tool_name, tool_args) 即可 ...這種方式極大地提高了可維護性新增工具只需創(chuàng)建文件并用裝飾器注冊主程序無需修改。5.2 完善的錯誤處理與日志記錄工具執(zhí)行在外部什么錯誤都可能發(fā)生網(wǎng)絡超時、API限流、參數(shù)無效、數(shù)據(jù)解析失敗等。必須有統(tǒng)一的錯誤處理。工具函數(shù)內(nèi)部的健壯性 如前所述使用try...except包裹核心邏輯返回有意義的錯誤信息。全局執(zhí)行包裝器 可以創(chuàng)建一個包裝函數(shù)統(tǒng)一處理異常和日志。# src/tools/executor.py import traceback from typing import Callable, Any def safe_execute_tool(tool_func: Callable, arguments: dict, tool_name: str) - str: 安全執(zhí)行工具函數(shù)提供統(tǒng)一的錯誤處理和日志。 try: print(f[INFO] 開始執(zhí)行工具: {tool_name}, 參數(shù): {arguments}) result tool_func(arguments) print(f[INFO] 工具執(zhí)行成功: {tool_name}, 結(jié)果長度: {len(str(result))}) return result except Exception as e: error_detail traceback.format_exc() print(f[ERROR] 工具執(zhí)行失敗: {tool_name}, 錯誤: {e}\n{error_detail}) # 返回一個對模型友好的錯誤信息避免暴露內(nèi)部細節(jié) return f工具 {tool_name} 執(zhí)行過程中發(fā)生意外錯誤請稍后重試或聯(lián)系管理員。然后在主循環(huán)中調(diào)用safe_execute_tool。5.3 工具描述的優(yōu)化技巧模型的工具調(diào)用準確性極大依賴于description和parameters的描述質(zhì)量。描述要具體且有場景 不要寫“查詢天氣”要寫“獲取指定城市的當前天氣信息包括溫度、濕度和天氣狀況。當用戶詢問天氣、氣候或溫度時使用此工具?！眳?shù)描述要清晰 對于city參數(shù)描述“城市名稱”是不夠的最好加上“例如‘北京’、‘紐約’、‘London’”。對于枚舉類型明確列出所有選項及其含義。使用required字段 明確哪些參數(shù)是必須的這能幫助模型更準確地詢問用戶缺失的信息如果對話允許。測試與迭代 寫出定義后用各種自然語言問法去測試模型是否會調(diào)用、參數(shù)填充是否準確。根據(jù)測試結(jié)果反復調(diào)整描述。6. 調(diào)試技巧與常見問題排查開發(fā)過程中你肯定會遇到模型不調(diào)用工具、調(diào)用錯誤工具、參數(shù)填充不對等問題。以下是我的排查清單。6.1 模型不調(diào)用工具檢查工具描述 這是最常見的原因。描述是否足夠清晰是否包含了觸發(fā)關(guān)鍵詞嘗試讓描述更貼近用戶可能使用的自然語言。檢查tool_choice參數(shù) 你設置的是auto嗎如果設為none模型將不會調(diào)用任何工具。如果想強制調(diào)用某個工具可以設為{type: function, function: {name: your_tool_name}}。檢查對話上下文 模型是基于整個對話歷史做決策的。如果之前的對話中已經(jīng)包含了答案或者上下文讓模型認為不需要工具它可能就不會調(diào)用。嘗試開啟一個新的對話線程測試。模型能力 確認你使用的模型版本支持函數(shù)調(diào)用Tool Calling。DeepSeek的主流聊天模型通常都支持。6.2 模型調(diào)用了錯誤的工具或參數(shù)填充錯誤工具描述區(qū)分度不夠 如果你有多個計算相關(guān)工具如calculator和currency_converter它們的描述需要有明顯區(qū)分。強調(diào)各自獨特的應用場景。參數(shù)描述模糊 比如一個date參數(shù)描述為“日期”可能讓模型困惑。應該描述為“具體的日期格式為YYYY-MM-DD例如2023-10-27”。查看模型的思考過程如果支持 有些API或平臺會提供模型的“推理過程”或“中間步驟”查看這些日志能幫你理解模型為什么做出了錯誤的選擇。6.3 工具執(zhí)行成功但模型回復不佳工具返回結(jié)果格式 模型需要基于工具返回的文本來生成回復。返回的結(jié)果應該信息完整、格式清晰、易于理解。避免返回純JSON或過于技術(shù)化的錯誤碼。在結(jié)果中提供上下文 例如天氣工具返回“溫度22”不如返回“北京當前溫度22°C體感舒適”。多給模型一些可以組織語言的素材。6.4 網(wǎng)絡與超時問題工具執(zhí)行時間過長 如果工具函數(shù)執(zhí)行HTTP請求且耗時很長可能會導致整個API調(diào)用超時?？紤]對工具函數(shù)設置超時限制或使用異步調(diào)用。異步處理模式 對于耗時任務可以考慮“異步工具調(diào)用”模式。即模型發(fā)起調(diào)用后你立即返回一個“任務已接收”的中間結(jié)果然后在后臺處理處理完成后通過其他方式如回調(diào)、數(shù)據(jù)庫更新通知用戶。但這需要更復雜的架構(gòu)支持。開發(fā)自定義Tool是一個與模型“協(xié)作”的過程需要你在工具設計的嚴謹性和模型理解的靈活性之間找到平衡點。從最簡單的“Hello World”開始逐步增加復雜度并持續(xù)測試和優(yōu)化工具描述是最高效的路徑。當你親手打造的工具被模型準確調(diào)用并解決實際問題時那種成就感是非常獨特的。這不僅僅是調(diào)用一個API而是在塑造一個AI智能體的行為能力。 DeepSeek插件開發(fā)實戰(zhàn)：從零構(gòu)建自定義Tool與函數(shù)調(diào)用
1. 項目概述為什么我們要親手打造一個DeepSeek插件最近在折騰DeepSeek的API發(fā)現(xiàn)官方提供的工具雖然強大但總有些特定場景下的需求沒法直接滿足。比如我想讓它能一鍵調(diào)用我內(nèi)部系統(tǒng)的數(shù)據(jù)查詢接口或者整合一些只有我們團隊在用的特殊工具鏈。這時候官方的通用工具就顯得有點“隔靴搔癢”了。于是我花了幾天時間深入研究了一下DeepSeek的插件或者說“工具調(diào)用”開發(fā)機制從最基礎(chǔ)的“Hello World”開始一步步實現(xiàn)了一個能根據(jù)我自定義邏輯運行的Tool。整個過程下來感覺就像給一個超級大腦裝上了專屬的“瑞士軍刀”讓它不僅能思考還能直接操作我的“私人工具箱”。這個實戰(zhàn)過程本質(zhì)上是在與大型語言模型的“工具調(diào)用”能力打交道。DeepSeek作為模型本身并不直接執(zhí)行代碼或訪問外部系統(tǒng)但它可以理解你的需求并“決定”在合適的時機調(diào)用你預先定義好的工具函數(shù)。我們開發(fā)者要做的就是按照它約定的格式把這些工具“描述”給它并準備好真正的執(zhí)行后端。這比單純調(diào)用API完成一次對話要復雜一些但帶來的靈活性和自動化潛力是指數(shù)級增長的。無論是想連接數(shù)據(jù)庫、觸發(fā)自動化腳本、還是調(diào)用第三方服務只要你能用代碼實現(xiàn)就能把它封裝成一個Tool讓DeepSeek模型來智能調(diào)度。2. 核心概念與準備工作理解Tool、Function Calling與插件生態(tài)在動手寫代碼之前我們必須先理清幾個關(guān)鍵概念否則很容易在后續(xù)開發(fā)中迷失方向。這些概念是構(gòu)建一切的基礎(chǔ)。2.1 Tool、Function Calling與插件它們到底是什么關(guān)系這幾個詞經(jīng)?；煊玫珖栏駚碚f它們指代的是同一流程的不同層面。Function Calling函數(shù)調(diào)用 這是一種協(xié)議或機制。它規(guī)定了大型語言模型如DeepSeek如何向外部系統(tǒng)“表達”它想要執(zhí)行某個操作的意圖。通常模型會在回復中輸出一個結(jié)構(gòu)化的JSON對象其中包含了它想調(diào)用的函數(shù)名以及傳入的參數(shù)。這不是真正的代碼執(zhí)行只是一個“請求”或“指令”。Tool工具 這是Function Calling機制中被調(diào)用的具體對象。一個Tool就是一個可執(zhí)行單元它對應一個具體的功能。在DeepSeek的語境下我們通過一個JSON Schema來定義一個Tool包括它的名稱、描述、參數(shù)列表等。模型只認識Tool的定義。插件Plugin 這是一個更上層的產(chǎn)品化概念。你可以把一個或多個相關(guān)的Tool打包配上圖標、描述文檔、認證方式等形成一個完整的、可供用戶安裝和使用的功能模塊。我們本次實戰(zhàn)聚焦在Tool的開發(fā)這是構(gòu)建插件最核心的一步。簡單類比Function Calling是“點菜”這個行為Tool是菜單上的一道道“菜”如魚香肉絲而Plugin則是一個完整的“套餐”或“特色菜系”。2.2 開發(fā)環(huán)境與工具鏈選擇工欲善其事必先利其器。為了高效開發(fā)我選擇了以下組合這套組合在靈活性和開發(fā)體驗上取得了很好的平衡。編程語言Python 3.9。這是AI領(lǐng)域事實上的標準語言生態(tài)庫豐富與DeepSeek API的交互有成熟的SDK支持。核心SDK官方deepseek庫。通過pip install deepseek安裝。這是與DeepSeek模型服務通信的官方橋梁。輔助工具Pydantic。這是一個用于數(shù)據(jù)驗證和設置管理的庫。在定義Tool的復雜參數(shù)結(jié)構(gòu)時使用Pydantic的BaseModel會讓代碼清晰、安全且易于維護。通過pip install pydantic安裝。開發(fā)環(huán)境 任意你熟悉的IDE或編輯器即可比如VSCode或PyCharm。關(guān)鍵是要能方便地調(diào)試和查看日志。DeepSeek API密鑰 你需要一個有效的DeepSeek API Key。前往DeepSeek平臺注冊并獲取。請妥善保管不要直接硬編碼在代碼中。注意 API Key是訪問服務的憑證務必通過環(huán)境變量或配置文件來管理。我習慣在項目根目錄創(chuàng)建一個.env文件使用python-dotenv庫加載絕對不要提交到代碼倉庫。# 示例 .env 文件內(nèi)容 DEEPSEEK_API_KEYyour_api_key_here2.3 項目結(jié)構(gòu)規(guī)劃一個清晰的項目結(jié)構(gòu)能讓你后續(xù)的開發(fā)和維護事半功倍。這是我采用的目錄結(jié)構(gòu)deepseek-custom-tool-demo/ ├── .env # 存儲環(huán)境變量API Key等 ├── .gitignore # Git忽略文件 ├── requirements.txt # 項目依賴列表 ├── src/ # 源代碼目錄 │ ├── __init__.py │ ├── tools/ # 存放所有自定義Tool的定義和實現(xiàn) │ │ ├── __init__.py │ │ ├── calculator.py # 示例計算器工具 │ │ └── weather.py # 示例天氣查詢工具 │ ├── schemas/ # 存放Pydantic數(shù)據(jù)模型用于參數(shù)驗證 │ │ ├── __init__.py │ │ └── weather.py # 天氣查詢的參數(shù)模型 │ └── main.py # 主程序入口組裝和運行 └── README.md # 項目說明文檔這個結(jié)構(gòu)將工具定義、數(shù)據(jù)模型和主邏輯分離符合單一職責原則未來添加新工具會非常方便。3. 從零實現(xiàn)第一個ToolHello World與計算器讓我們從一個最簡單的例子開始確保整個鏈路是通的。這個階段的目標不是功能多復雜而是驗證“模型能理解我們的工具描述并能觸發(fā)我們寫的代碼”。3.1 最簡示例Echo Tool回聲工具這個工具的功能是模型讓它說什么它就原樣返回什么。雖然簡單但能完整走通流程。首先在src/tools/目錄下創(chuàng)建echo.py# src/tools/echo.py import json from typing import Any, Dict def echo_tool(arguments: Dict[str, Any]) - str: 一個簡單的回聲工具返回傳入的消息。 這是Tool的執(zhí)行函數(shù)。 # 從模型傳來的參數(shù)中獲取消息 message arguments.get(message, ) # 這里可以加入任何你想執(zhí)行的邏輯 result fEcho: {message} print(f[Tool Log] Echo工具被調(diào)用參數(shù): {arguments}, 結(jié)果: {result}) return result # Tool的定義JSON Schema # 這個定義是給DeepSeek模型“看”的告訴它這個工具叫什么、能干嘛、需要什么參數(shù)。 ECHO_TOOL_SCHEMA { type: function, function: { name: echo, # 工具名稱模型調(diào)用時使用 description: 一個簡單的回聲工具用于測試和驗證工具調(diào)用流程。輸入什么就返回什么。, parameters: { type: object, properties: { message: { type: string, description: 需要被回聲的消息內(nèi)容, } }, required: [message], # 指定哪些參數(shù)是必須的 additionalProperties: False, # 禁止傳入未定義的參數(shù)更安全 }, }, }關(guān)鍵點解析執(zhí)行函數(shù) (echo_tool) 這是實際被執(zhí)行的Python函數(shù)。它接收一個字典arguments里面包含了模型根據(jù)對話內(nèi)容“推斷”并填充好的參數(shù)。函數(shù)最后返回一個字符串結(jié)果。工具定義 (ECHO_TOOL_SCHEMA) 這是一個符合OpenAI Function Calling格式的字典。name是唯一標識description至關(guān)重要模型靠它來理解何時該調(diào)用此工具。parameters定義了輸入?yún)?shù)的JSON Schemarequired數(shù)組聲明了必填參數(shù)。接下來在src/main.py中編寫主邏輯# src/main.py import os from dotenv import load_dotenv from deepseek import DeepSeek # 導入我們定義的工具 from src.tools.echo import echo_tool, ECHO_TOOL_SCHEMA # 加載環(huán)境變量 load_dotenv() def main(): # 1. 初始化DeepSeek客戶端 client DeepSeek(api_keyos.getenv(DEEPSEEK_API_KEY)) # 2. 準備對話歷史和工具列表 messages [{role: user, content: 請讓回聲工具說一句‘你好世界’}] tools [ECHO_TOOL_SCHEMA] # 將工具定義提供給模型 # 3. 發(fā)起第一次對話請求告訴模型有哪些工具可用 response client.chat.completions.create( modeldeepseek-chat, # 指定模型 messagesmessages, toolstools, tool_choiceauto, # 讓模型自行決定是否調(diào)用工具 ) # 4. 處理模型響應 message response.choices[0].message print(f模型原始回復: {message}) # 5. 檢查模型是否決定調(diào)用工具 if message.tool_calls: print(模型決定調(diào)用工具) for tool_call in message.tool_calls: # tool_call是一個對象包含工具名和參數(shù) tool_name tool_call.function.name tool_args json.loads(tool_call.function.arguments) # 參數(shù)是JSON字符串需要解析 # 6. 根據(jù)工具名找到對應的本地執(zhí)行函數(shù)并調(diào)用 if tool_name echo: tool_result echo_tool(tool_args) print(f工具執(zhí)行結(jié)果: {tool_result}) # 7. 將工具執(zhí)行結(jié)果作為新的消息追加到對話歷史中讓模型知曉 messages.append(message) # 先追加模型的消息包含工具調(diào)用請求 messages.append({ role: tool, content: tool_result, tool_call_id: tool_call.id, # 必須對應告訴模型這是哪個調(diào)用的結(jié)果 }) # 8. 再次請求模型讓它基于工具結(jié)果生成最終回復 second_response client.chat.completions.create( modeldeepseek-chat, messagesmessages, ) final_reply second_response.choices[0].message.content print(f\n模型的最終回復: {final_reply}) else: print(f未知工具調(diào)用: {tool_name}) else: # 模型沒有調(diào)用工具直接輸出內(nèi)容 print(f模型直接回復: {message.content}) if __name__ __main__: main()運行這個程序如果你看到類似以下的輸出那么恭喜你第一個Tool已經(jīng)成功跑通了模型原始回復: ChatCompletionMessage(contentNone, roleassistant, function_callNone, tool_calls[ChatCompletionMessageToolCall(idcall_abc123, functionFunction(arguments{message:你好世界}, nameecho), typefunction)]) 模型決定調(diào)用工具 [Tool Log] Echo工具被調(diào)用參數(shù): {message: 你好世界}, 結(jié)果: Echo: 你好世界 工具執(zhí)行結(jié)果: Echo: 你好世界 模型的最終回復: 工具已經(jīng)執(zhí)行并返回了結(jié)果“Echo: 你好世界”。如你所見它成功地將“你好世界”這句話原樣返回了。這個流程是標準的多輪交互用戶請求 - 模型決定調(diào)用工具并返回調(diào)用指令 - 本地執(zhí)行工具 - 將結(jié)果返回給模型 - 模型生成最終回答。3.2 進階示例智能計算器工具現(xiàn)在我們來做一個更有用的工具一個能理解自然語言計算請求的智能計算器。這個例子展示了如何處理更復雜的參數(shù)和邏輯。首先用Pydantic定義參數(shù)模型這能讓參數(shù)驗證和代碼提示更友好。在src/schemas/calculator.py中# src/schemas/calculator.py from pydantic import BaseModel, Field from typing import Literal class CalculatorInput(BaseModel): operation: Literal[add, subtract, multiply, divide] Field( ..., description運算類型加(add)、減(subtract)、乘(multiply)、除(divide) ) a: float Field(..., description第一個運算數(shù)) b: float Field(..., description第二個運算數(shù)) # 可以添加自定義驗證例如除法時除數(shù)不能為0 # 這里為了演示我們在工具函數(shù)里處理然后在src/tools/calculator.py中實現(xiàn)工具# src/tools/calculator.py import json from typing import Any, Dict from src.schemas.calculator import CalculatorInput def calculator_tool(arguments: Dict[str, Any]) - str: 一個智能計算器工具執(zhí)行基礎(chǔ)算術(shù)運算。 try: # 使用Pydantic模型驗證和解析參數(shù) calc_input CalculatorInput(**arguments) a calc_input.a b calc_input.b result None if calc_input.operation add: result a b op_symbol elif calc_input.operation subtract: result a - b op_symbol - elif calc_input.operation multiply: result a * b op_symbol * elif calc_input.operation divide: if b 0: return 錯誤除數(shù)不能為零。 result a / b op_symbol / else: return f錯誤不支持的運算類型 {calc_input.operation}。 return f計算結(jié)果{a} {op_symbol} {result} except Exception as e: # 捕獲參數(shù)驗證錯誤或其他異常 return f工具執(zhí)行出錯{str(e)} # 工具定義 # 注意這里的parameters可以從Pydantic模型自動生成但為清晰起見我們手動寫一份。 # 在實際大型項目中可以使用pydantic的model_json_schema()方法自動生成。 CALCULATOR_TOOL_SCHEMA { type: function, function: { name: calculator, description: 執(zhí)行基礎(chǔ)算術(shù)運算加、減、乘、除。當用戶需要進行數(shù)學計算時使用此工具。, parameters: { type: object, properties: { operation: { type: string, enum: [add, subtract, multiply, divide], description: 運算類型加(add)、減(subtract)、乘(multiply)、除(divide) }, a: { type: number, description: 第一個運算數(shù) }, b: { type: number, description: 第二個運算數(shù) } }, required: [operation, a, b], additionalProperties: False, }, }, }實操心得description字段是工具能否被正確調(diào)用的靈魂。模型完全依賴這個描述來判斷“什么時候該用這個工具”。所以描述要盡可能精確、無歧義并包含典型的使用場景。例如“當用戶需要進行數(shù)學計算時使用此工具”就比“這是一個計算器”要好得多。更新main.py引入計算器工具并進行測試# 在main.py中更新導入和工具列表 from src.tools.calculator import calculator_tool, CALCULATOR_TOOL_SCHEMA # ... 其他導入 ... def main(): client DeepSeek(api_keyos.getenv(DEEPSEEK_API_KEY)) messages [{role: user, content: 請幫我計算一下3.14乘以256等于多少}] # 可以同時提供多個工具給模型選擇 tools [ECHO_TOOL_SCHEMA, CALCULATOR_TOOL_SCHEMA] response client.chat.completions.create( modeldeepseek-chat, messagesmessages, toolstools, tool_choiceauto, ) # ... 后續(xù)處理邏輯與echo示例類似需要根據(jù)tool_name調(diào)用對應的calculator_tool ...運行后模型應該能正確理解“3.14乘以256”這個自然語言請求將其轉(zhuǎn)化為operation: multiply, a: 3.14, b: 256的參數(shù)并調(diào)用我們的calculator_tool得到正確結(jié)果。4. 構(gòu)建復雜且實用的自定義Tool天氣查詢代理現(xiàn)在我們來挑戰(zhàn)一個更接近真實場景的例子一個天氣查詢工具。這個工具需要調(diào)用外部API處理網(wǎng)絡請求和JSON數(shù)據(jù)解析并且參數(shù)結(jié)構(gòu)也更復雜。4.1 設計數(shù)據(jù)模型與工具定義假設我們調(diào)用一個虛擬的天氣API它需要城市名和查詢單位公制/英制。首先在src/schemas/weather.py中定義參數(shù)模型# src/schemas/weather.py from pydantic import BaseModel, Field from typing import Literal, Optional class WeatherQueryInput(BaseModel): city: str Field(..., description需要查詢天氣的城市名稱例如北京、Shanghai、New York) units: Optional[Literal[metric, imperial]] Field( defaultmetric, description溫度單位。metric表示攝氏度(°C)imperial表示華氏度(°F)。默認為metric。 ) # 可以擴展更多參數(shù)如語言、預報天數(shù)等 # forecast_days: Optional[int] Field(default1, ge1, le7, description預報天數(shù)1-7天)接著在src/tools/weather.py中實現(xiàn)工具。這里我們模擬一個API調(diào)用# src/tools/weather.py import json import random import time from typing import Any, Dict from src.schemas.weather import WeatherQueryInput def mock_weather_api(city: str, units: str metric) - Dict[str, Any]: 模擬一個天氣API的響應。 在實際項目中這里應該替換為真實的HTTP請求例如使用requests庫。 # 模擬網(wǎng)絡延遲 time.sleep(0.5) # 生成一些模擬數(shù)據(jù) temp random.uniform(15, 35) if units metric else random.uniform(59, 95) humidity random.randint(30, 90) conditions [晴朗, 多云, 局部多云, 小雨, 雷陣雨] condition random.choice(conditions) return { city: city, temperature: round(temp, 1), units: °C if units metric else °F, humidity: f{humidity}%, condition: condition, timestamp: time.strftime(%Y-%m-%d %H:%M:%S), } def weather_tool(arguments: Dict[str, Any]) - str: 查詢指定城市的當前天氣情況。 try: # 1. 參數(shù)驗證與解析 query WeatherQueryInput(**arguments) city query.city units query.units or metric # 使用默認值 # 2. 調(diào)用模擬外部API print(f[Tool Log] 正在查詢{city}的天氣單位: {units}...) weather_data mock_weather_api(city, units) # 3. 格式化結(jié)果使其對模型和用戶都友好 result_str ( f{weather_data[city]}的當前天氣\n f- 天氣狀況{weather_data[condition]}\n f- 溫度{weather_data[temperature]}{weather_data[units]}\n f- 濕度{weather_data[humidity]}\n f- 數(shù)據(jù)更新時間{weather_data[timestamp]} ) return result_str except Exception as e: # 記錄詳細錯誤日志但返回給模型的錯誤信息要簡潔 print(f[Tool Error] 天氣查詢失敗: {e}) return f抱歉查詢{city}的天氣時出現(xiàn)錯誤。請檢查城市名稱是否正確或稍后再試。 # 工具定義 WEATHER_TOOL_SCHEMA { type: function, function: { name: get_current_weather, description: 獲取指定城市的當前天氣信息包括溫度、濕度和天氣狀況。當用戶詢問天氣、氣候或溫度時使用此工具。, parameters: { type: object, properties: { city: { type: string, description: 城市名稱必須清晰明確。例如‘北京’、‘紐約’、‘London’。 }, units: { type: string, enum: [metric, imperial], description: 溫度單位。metric為攝氏度imperial為華氏度。如果不指定默認使用metric。 } }, required: [city], # units 是可選的 additionalProperties: False, }, }, }4.2 在主程序中集成與測試更新main.py集成天氣工具并嘗試更復雜的對話# 更新main.py的導入和主邏輯 from src.tools.weather import weather_tool, WEATHER_TOOL_SCHEMA def run_conversation(): client DeepSeek(api_keyos.getenv(DEEPSEEK_API_KEY)) # 初始對話可以混合多個工具 tools [CALCULATOR_TOOL_SCHEMA, WEATHER_TOOL_SCHEMA] messages [{role: user, content: 今天杭州天氣怎么樣另外幫我算算去那里出差三天如果每天餐費預算150元總共需要多少}] # 第一輪模型可能會先調(diào)用天氣工具 response client.chat.completions.create( modeldeepseek-chat, messagesmessages, toolstools, tool_choiceauto, ) message response.choices[0].message messages.append(message) # 將模型的回復含工具調(diào)用加入歷史 # 處理可能的多工具調(diào)用循環(huán) while message.tool_calls: for tool_call in message.tool_calls: tool_name tool_call.function.name tool_args json.loads(tool_call.function.arguments) if tool_name get_current_weather: tool_result weather_tool(tool_args) elif tool_name calculator: tool_result calculator_tool(tool_args) else: tool_result f錯誤未知工具 {tool_name}。 # 將工具執(zhí)行結(jié)果追加 messages.append({ role: tool, content: tool_result, tool_call_id: tool_call.id, }) # 再次請求模型讓它基于所有工具結(jié)果繼續(xù)回復或調(diào)用新工具 response client.chat.completions.create( modeldeepseek-chat, messagesmessages, toolstools, # 工具列表在后續(xù)輪次中通常也需要傳遞 ) message response.choices[0].message if message.content or message.tool_calls: messages.append(message) # 打印最終結(jié)果 print(\n 對話完成 ) for msg in messages: if msg[role] assistant and msg.get(content): print(f助理: {msg[content]}) elif msg[role] tool: print(f[工具結(jié)果]: {msg[content]}) if __name__ __main__: run_conversation()這個例子展示了幾個高級特性多工具協(xié)同 模型可以理解一個復雜問題中包含的多個子任務查天氣、做計算并依次或并行調(diào)用不同的工具。循環(huán)處理 通過while循環(huán)可以處理模型可能發(fā)起的連續(xù)多次工具調(diào)用。錯誤處理與友好反饋 在工具函數(shù)內(nèi)部進行了異常捕獲并返回了對用戶友好的錯誤信息而不是崩潰或拋出技術(shù)棧追蹤。5. 工程化與最佳實踐讓自定義Tool更健壯當工具數(shù)量增多、邏輯變復雜后代碼的組織和健壯性就變得至關(guān)重要。以下是我在實踐中總結(jié)的幾個關(guān)鍵點。5.1 工具的動態(tài)注冊與發(fā)現(xiàn)機制手動維護一個tools列表在工具少的時候還行多了就非常麻煩。我們可以建立一個注冊機制。在src/tools/__init__.py中# src/tools/__init__.py 工具注冊中心。 所有工具在此注冊便于主程序統(tǒng)一加載。 import inspect from typing import Dict, Callable, Any # 全局注冊表 _tool_registry: Dict[str, Dict[str, Any]] { # 格式: tool_name: {function: callable, schema: dict} } def register_tool(schema: dict): 裝飾器用于注冊工具。 用法 register_tool(MY_TOOL_SCHEMA) def my_tool_function(arguments): ... def decorator(func: Callable): tool_name schema[function][name] _tool_registry[tool_name] { function: func, schema: schema } return func return decorator def get_all_tool_schemas(): 獲取所有已注冊工具的定義 return [info[schema] for info in _tool_registry.values()] def execute_tool(tool_name: str, arguments: dict) - str: 根據(jù)工具名執(zhí)行對應的工具函數(shù) if tool_name not in _tool_registry: raise ValueError(f工具 {tool_name} 未注冊。) tool_info _tool_registry[tool_name] return tool_info[function](arguments)然后修改我們的工具文件使用裝飾器注冊# src/tools/weather.py (更新版) from src.tools import register_tool # ... 其他導入和WeatherQueryInput ... register_tool(WEATHER_TOOL_SCHEMA) # 使用裝飾器注冊 def weather_tool(arguments: Dict[str, Any]) - str: # ... 函數(shù)實現(xiàn)不變 ...最后主程序可以簡化為# main.py (更新版) from src.tools import get_all_tool_schemas, execute_tool # 只需導入工具模塊裝飾器會自動注冊 import src.tools.echo import src.tools.calculator import src.tools.weather def run_conversation(): client DeepSeek(...) # 動態(tài)獲取所有已注冊的工具定義 tools get_all_tool_schemas() messages [...] # ... 后續(xù)循環(huán)中調(diào)用 execute_tool(tool_name, tool_args) 即可 ...這種方式極大地提高了可維護性新增工具只需創(chuàng)建文件并用裝飾器注冊主程序無需修改。5.2 完善的錯誤處理與日志記錄工具執(zhí)行在外部什么錯誤都可能發(fā)生網(wǎng)絡超時、API限流、參數(shù)無效、數(shù)據(jù)解析失敗等。必須有統(tǒng)一的錯誤處理。工具函數(shù)內(nèi)部的健壯性 如前所述使用try...except包裹核心邏輯返回有意義的錯誤信息。全局執(zhí)行包裝器 可以創(chuàng)建一個包裝函數(shù)統(tǒng)一處理異常和日志。# src/tools/executor.py import traceback from typing import Callable, Any def safe_execute_tool(tool_func: Callable, arguments: dict, tool_name: str) - str: 安全執(zhí)行工具函數(shù)提供統(tǒng)一的錯誤處理和日志。 try: print(f[INFO] 開始執(zhí)行工具: {tool_name}, 參數(shù): {arguments}) result tool_func(arguments) print(f[INFO] 工具執(zhí)行成功: {tool_name}, 結(jié)果長度: {len(str(result))}) return result except Exception as e: error_detail traceback.format_exc() print(f[ERROR] 工具執(zhí)行失敗: {tool_name}, 錯誤: {e}\n{error_detail}) # 返回一個對模型友好的錯誤信息避免暴露內(nèi)部細節(jié) return f工具 {tool_name} 執(zhí)行過程中發(fā)生意外錯誤請稍后重試或聯(lián)系管理員。然后在主循環(huán)中調(diào)用safe_execute_tool。5.3 工具描述的優(yōu)化技巧模型的工具調(diào)用準確性極大依賴于description和parameters的描述質(zhì)量。描述要具體且有場景 不要寫“查詢天氣”要寫“獲取指定城市的當前天氣信息包括溫度、濕度和天氣狀況。當用戶詢問天氣、氣候或溫度時使用此工具?！眳?shù)描述要清晰 對于city參數(shù)描述“城市名稱”是不夠的最好加上“例如‘北京’、‘紐約’、‘London’”。對于枚舉類型明確列出所有選項及其含義。使用required字段 明確哪些參數(shù)是必須的這能幫助模型更準確地詢問用戶缺失的信息如果對話允許。測試與迭代 寫出定義后用各種自然語言問法去測試模型是否會調(diào)用、參數(shù)填充是否準確。根據(jù)測試結(jié)果反復調(diào)整描述。6. 調(diào)試技巧與常見問題排查開發(fā)過程中你肯定會遇到模型不調(diào)用工具、調(diào)用錯誤工具、參數(shù)填充不對等問題。以下是我的排查清單。6.1 模型不調(diào)用工具檢查工具描述 這是最常見的原因。描述是否足夠清晰是否包含了觸發(fā)關(guān)鍵詞嘗試讓描述更貼近用戶可能使用的自然語言。檢查tool_choice參數(shù) 你設置的是auto嗎如果設為none模型將不會調(diào)用任何工具。如果想強制調(diào)用某個工具可以設為{type: function, function: {name: your_tool_name}}。檢查對話上下文 模型是基于整個對話歷史做決策的。如果之前的對話中已經(jīng)包含了答案或者上下文讓模型認為不需要工具它可能就不會調(diào)用。嘗試開啟一個新的對話線程測試。模型能力 確認你使用的模型版本支持函數(shù)調(diào)用Tool Calling。DeepSeek的主流聊天模型通常都支持。6.2 模型調(diào)用了錯誤的工具或參數(shù)填充錯誤工具描述區(qū)分度不夠 如果你有多個計算相關(guān)工具如calculator和currency_converter它們的描述需要有明顯區(qū)分。強調(diào)各自獨特的應用場景。參數(shù)描述模糊 比如一個date參數(shù)描述為“日期”可能讓模型困惑。應該描述為“具體的日期格式為YYYY-MM-DD例如2023-10-27”。查看模型的思考過程如果支持 有些API或平臺會提供模型的“推理過程”或“中間步驟”查看這些日志能幫你理解模型為什么做出了錯誤的選擇。6.3 工具執(zhí)行成功但模型回復不佳工具返回結(jié)果格式 模型需要基于工具返回的文本來生成回復。返回的結(jié)果應該信息完整、格式清晰、易于理解。避免返回純JSON或過于技術(shù)化的錯誤碼。在結(jié)果中提供上下文 例如天氣工具返回“溫度22”不如返回“北京當前溫度22°C體感舒適”。多給模型一些可以組織語言的素材。6.4 網(wǎng)絡與超時問題工具執(zhí)行時間過長 如果工具函數(shù)執(zhí)行HTTP請求且耗時很長可能會導致整個API調(diào)用超時?？紤]對工具函數(shù)設置超時限制或使用異步調(diào)用。異步處理模式 對于耗時任務可以考慮“異步工具調(diào)用”模式。即模型發(fā)起調(diào)用后你立即返回一個“任務已接收”的中間結(jié)果然后在后臺處理處理完成后通過其他方式如回調(diào)、數(shù)據(jù)庫更新通知用戶。但這需要更復雜的架構(gòu)支持。開發(fā)自定義Tool是一個與模型“協(xié)作”的過程需要你在工具設計的嚴謹性和模型理解的靈活性之間找到平衡點。從最簡單的“Hello World”開始逐步增加復雜度并持續(xù)測試和優(yōu)化工具描述是最高效的路徑。當你親手打造的工具被模型準確調(diào)用并解決實際問題時那種成就感是非常獨特的。這不僅僅是調(diào)用一個API而是在塑造一個AI智能體的行為能力。