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