1. 為什么要把 LLM、Tools、MCP、Skills 塞進同一個網(wǎng)關(guān)第一次看到 tsm-hub 這個項目名的時候我腦子里冒出來的第一個念頭是又是一個大一統(tǒng)的抽象層。做后端和 AI 應(yīng)用的人對統(tǒng)一網(wǎng)關(guān)這四個字應(yīng)該都不陌生API Gateway、服務(wù)網(wǎng)格、BFF 層本質(zhì)上都是在解決同一個問題——當系統(tǒng)里的組件越來越多、協(xié)議越來越雜、調(diào)用方越來越懶的時候你需要一個中間人把臟活累活全接過去。但 tsm-hub 要收攏的東西有點特殊LLM、Tools、MCP、Skills。這四個詞放在一起其實代表了當前 AI 應(yīng)用開發(fā)里四條完全不同的技術(shù)脈絡(luò)。LLM 是模型本身是那個會說話的大腦。Tools 是模型能調(diào)用的外部函數(shù)比如查天氣、算數(shù)學、讀數(shù)據(jù)庫。MCP 是 Model Context Protocol一套讓模型和外部工具、數(shù)據(jù)源之間用標準方式對話的協(xié)議。Skills 則是更高層的封裝是把一組工具、提示詞、執(zhí)行邏輯打包成一個可復用的能力單元比如幫我做數(shù)學建模或者幫我寫漫劇腳本。問題在于這四樣東西在傳統(tǒng)架構(gòu)里是各管各的。模型走一套 API工具走另一套注冊中心MCP 服務(wù)端單獨部署Skills 又散落在各個項目的 prompt 目錄里。你每接一個新模型就要重寫一遍工具調(diào)用邏輯每加一個 MCP server就要改一遍路由配置每換一個 Skills 庫就要重新對齊參數(shù)格式。tsm-hub 的核心價值就在這里它把模型、工具、協(xié)議、技能四層抽象收斂到一個統(tǒng)一的入口。調(diào)用方只需要面對一個網(wǎng)關(guān)地址至于背后是哪個模型、走的是原生 function call 還是 MCP 協(xié)議、加載的是哪套 Skills全部由網(wǎng)關(guān)內(nèi)部消化。我實測下來的感受是這種設(shè)計對兩類人特別友好。一類是快速做原型的獨立開發(fā)者不想在基礎(chǔ)設(shè)施上花時間只想把模型和工具拼起來跑通業(yè)務(wù)。另一類是團隊里的平臺工程師需要給多個業(yè)務(wù)線提供統(tǒng)一的 AI 能力出口但又不想讓每個業(yè)務(wù)線都去理解 MCP 和 Skills 的細節(jié)。注意統(tǒng)一網(wǎng)關(guān)不是銀彈。它解決的是接入復雜度問題不解決模型能力問題。如果你的場景只需要調(diào)一個模型做文本生成硬上網(wǎng)關(guān)反而是過度設(shè)計。2. tsm-hub 的四層抽象到底各自管什么要理解 tsm-hub 的設(shè)計得先把 LLM、Tools、MCP、Skills 這四層各自的職責邊界劃清楚。很多人第一次接觸這些概念時容易混淆尤其是 MCP 和 Tools看起來都是讓模型調(diào)用外部能力但它們的抽象層級完全不同。2.1 LLM 層模型接入與路由LLM 層負責的是模型本身的接入。tsm-hub 在這一層做的事情包括統(tǒng)一不同廠商的 API 格式、管理模型列表、處理鑒權(quán)、做請求路由和降級。舉個實際場景。你手上有三個模型來源一個本地部署的開源模型、一個云端商用模型、一個專門做代碼補全的小模型。如果沒有網(wǎng)關(guān)你的業(yè)務(wù)代碼里會散落著三套不同的 SDK 調(diào)用邏輯每套的請求體格式、返回結(jié)構(gòu)、錯誤碼都不一樣。tsm-hub 的做法是在這一層做適配器模式把不同來源的模型統(tǒng)一成一套內(nèi)部接口。路由策略是這一層的重點。我見過比較實用的幾種策略策略類型適用場景實現(xiàn)要點按任務(wù)類型路由代碼任務(wù)走代碼模型對話走通用模型在請求里帶 task_type 字段按成本路由簡單任務(wù)走便宜模型復雜任務(wù)走貴模型需要預估 token 量或復雜度按可用性降級主模型超時自動切備用模型設(shè)置超時閾值和重試次數(shù)按上下文長度路由長文本走長窗口模型請求前統(tǒng)計 token 數(shù)這一層最容易踩的坑是錯誤碼不統(tǒng)一。不同廠商對限流的返回碼不一樣有的是 429有的是自定義錯誤碼。網(wǎng)關(guān)必須把這些統(tǒng)一映射否則上層業(yè)務(wù)沒法做統(tǒng)一的異常處理。2.2 Tools 層函數(shù)注冊與調(diào)用Tools 層管的是模型可以調(diào)用的外部函數(shù)。這一層的核心是注冊機制和參數(shù)校驗。一個工具在 tsm-hub 里的生命周期大概是這樣的先注冊工具定義名稱、描述、參數(shù) schema然后模型在對話中決定調(diào)用哪個工具并生成參數(shù)網(wǎng)關(guān)校驗參數(shù)后執(zhí)行實際函數(shù)最后把結(jié)果回傳給模型。參數(shù)校驗這一步特別關(guān)鍵。模型生成的參數(shù)經(jīng)常不靠譜比如該傳數(shù)字的傳了字符串該傳枚舉值的傳了個不存在的選項。如果不在網(wǎng)關(guān)層攔住錯誤會一路傳到業(yè)務(wù)函數(shù)里排查起來非常痛苦。tsm-hub 在這一層用 JSON Schema 做校驗不通過的直接返回錯誤給模型讓它重新生成。我自己的經(jīng)驗是工具描述寫得好不好直接決定模型調(diào)用準確率。描述里要明確說清楚這個工具做什么、什么時候用、參數(shù)是什么含義、返回什么格式。我見過太多人把工具描述寫成一句話然后抱怨模型老是調(diào)錯工具。2.3 MCP 層協(xié)議適配與連接管理MCP 是這一層里最容易被誤解的。很多人第一次聽到 MCP會以為它是某種硬件協(xié)議或者網(wǎng)絡(luò)傳輸協(xié)議。其實 MCP 是 Model Context Protocol是一套應(yīng)用層協(xié)議規(guī)定的是模型和外部上下文提供者之間怎么交換信息。tsm-hub 在 MCP 層做的事情本質(zhì)上是協(xié)議轉(zhuǎn)換。因為 MCP 有自己的消息格式和交互流程而網(wǎng)關(guān)內(nèi)部用的是統(tǒng)一的工具調(diào)用接口所以需要一個適配層把 MCP 的請求翻譯成內(nèi)部格式再把內(nèi)部結(jié)果翻譯回 MCP 格式。這一層的連接管理是個技術(shù)難點。MCP server 可能是本地進程也可能是遠程服務(wù)連接方式可能是 stdio也可能是 HTTP 或 WebSocket。網(wǎng)關(guān)需要維護這些連接的生命周期處理斷線重連、超時、并發(fā)調(diào)用等問題。提示如果你在配置 MCP 連接時遇到握手失敗先檢查兩件事——協(xié)議版本是否匹配以及 server 端是否真的在監(jiān)聽。我踩過好幾次坑最后發(fā)現(xiàn)是 server 啟動腳本里的端口寫錯了。2.4 Skills 層能力封裝與復用Skills 層是最高層的抽象。一個 Skill 可以理解為一個技能包里面包含了一組工具、一段系統(tǒng)提示詞、一套執(zhí)行流程甚至一些示例對話。為什么需要 Skills 這一層因為 Tools 和 MCP 解決的是模型能做什么而 Skills 解決的是模型應(yīng)該怎么做。同樣是調(diào)用搜索工具做學術(shù)調(diào)研和做新聞?wù)恼{(diào)用方式、結(jié)果處理、輸出格式完全不同。Skills 就是把這些領(lǐng)域知識固化下來讓模型不用每次從零開始理解任務(wù)。tsm-hub 在 Skills 層的設(shè)計思路是聲明式加載。你只需要在配置里聲明要加載哪些 Skills網(wǎng)關(guān)會自動把 Skill 里的工具注冊到 Tools 層把提示詞注入到對話上下文把執(zhí)行流程編排好。這一層最實用的特性是Skills 組合。比如你可以把數(shù)學建模Skill 和數(shù)據(jù)可視化Skill 組合起來模型就能同時具備建模和畫圖的能力。組合的時候要注意工具命名沖突兩個 Skill 里如果有同名工具需要做命名空間隔離。3. 從零搭一個 tsm-hub 實例的完整路徑光講概念沒意思我把自己搭 tsm-hub 的完整過程拆一遍。這套流程我在不同環(huán)境里跑過三次每次都會遇到一些新問題下面把關(guān)鍵步驟和踩坑點都列出來。3.1 環(huán)境準備與依賴確認第一步是確認運行環(huán)境。tsm-hub 本身是個服務(wù)需要 Node.js 或 Python 運行時取決于你選的實現(xiàn)版本還需要能訪問模型 API 的網(wǎng)絡(luò)環(huán)境。我建議在動手之前先列一個清單運行時版本Node.js 18 或 Python 3.10包管理器npm/pnpm 或 pip/uv模型 API 憑證至少一個可用的模型來源存儲如果需要持久化配置和日志準備一個 SQLite 或 PostgreSQL網(wǎng)絡(luò)確認能訪問模型 API 和 MCP server 地址這里有個容易忽略的點時區(qū)和字符編碼。我有一次在容器里跑日志時間全是 UTC排查問題時對不上業(yè)務(wù)時間。還有一次 Skills 里的中文提示詞出現(xiàn)亂碼最后發(fā)現(xiàn)是環(huán)境變量里的 LANG 沒設(shè)置。3.2 配置文件的結(jié)構(gòu)與關(guān)鍵字段tsm-hub 的配置一般分幾塊模型配置、工具配置、MCP 配置、Skills 配置、服務(wù)配置。我用一個簡化版的結(jié)構(gòu)說明server: port: 8080 log_level: info models: - name: default-chat provider: openai-compatible base_url: https://api.example.com/v1 api_key: ${MODEL_API_KEY} model: gpt-4o-mini timeout: 30s tools: - name: get_weather description: 查詢指定城市的當前天氣 parameters: type: object properties: city: type: string description: 城市名稱 required: [city] handler: ./handlers/weather.js mcp: servers: - name: filesystem transport: stdio command: npx args: [-y, modelcontextprotocol/server-filesystem, /data] skills: - name: math-modeling path: ./skills/math-modeling enabled: true幾個關(guān)鍵字段的說明provider字段決定用哪個適配器。如果是標準 OpenAI 兼容接口用openai-compatible就行。如果是特殊廠商可能需要自定義適配器。timeout一定要設(shè)。我見過太多因為沒設(shè)超時導致請求掛死的情況。建議根據(jù)模型響應(yīng)速度設(shè)一般 30 到 60 秒。transport字段在 MCP 配置里很關(guān)鍵。stdio 適合本地進程http 和 websocket 適合遠程服務(wù)。選錯了連不上。3.3 啟動與首次連通性驗證配置寫完后啟動服務(wù)。啟動日志里會打印加載了哪些模型、注冊了哪些工具、連接了哪些 MCP server、啟用了哪些 Skills。這一步一定要仔細看日志很多配置錯誤在啟動階段就會暴露。驗證連通性我一般分三步先調(diào)一個最簡單的對話接口確認模型層通了再調(diào)一個帶工具調(diào)用的請求確認 Tools 層通了最后調(diào)一個需要 MCP 或 Skills 的復雜請求確認全鏈路通了第三步最容易出問題。我遇到過一次模型層和工具層都正常但一走到 MCP 就超時。排查了半天發(fā)現(xiàn)是 MCP server 的啟動命令里路徑寫的是相對路徑而網(wǎng)關(guān)的工作目錄和我想的不一樣。注意首次驗證時把日志級別調(diào)到 debug能看到完整的請求和響應(yīng)鏈路。確認沒問題后再調(diào)回 info否則日志量會很大。3.4 接入第一個真實業(yè)務(wù)場景跑通 demo 之后下一步是接真實業(yè)務(wù)。我建議從一個具體的、邊界清晰的任務(wù)開始不要一上來就做通用助手。比如根據(jù)用戶輸入的城市名查詢天氣并生成出行建議就是一個好場景。它涉及模型調(diào)用、工具調(diào)用、結(jié)果格式化但邏輯不復雜出問題容易定位。接入過程中要重點關(guān)注錯誤處理。模型調(diào)用可能超時工具執(zhí)行可能拋異常MCP 連接可能斷開。這些錯誤在網(wǎng)關(guān)層怎么處理、怎么返回給調(diào)用方需要提前設(shè)計好。我的做法是定義一套統(tǒng)一的錯誤碼上層業(yè)務(wù)根據(jù)錯誤碼決定是重試、降級還是提示用戶。4. 那些文檔里不會寫的踩坑記錄這一節(jié)是我最想寫的部分。官方文檔和 README 通常只講怎么用不講哪里會炸。下面這些坑都是我實際踩過的希望能幫你省點時間。4.1 MCP 連接握手失敗的排查鏈路MCP 連接失敗是最常見的問題而且報錯信息往往很模糊。我的排查鏈路是這樣的先看網(wǎng)關(guān)日志里 MCP 相關(guān)的輸出確認是連接階段失敗還是握手階段失敗。連接階段失敗通常是地址或命令不對握手階段失敗通常是協(xié)議版本或初始化參數(shù)不匹配。如果是 stdio 傳輸檢查啟動命令能不能在命令行里手動跑通。我有一次配的 MCP server 需要特定環(huán)境變量網(wǎng)關(guān)啟動時沒帶上導致 server 啟動就崩了。如果是 HTTP 或 WebSocket 傳輸先用 curl 或 websocket 客戶端工具直接連一下確認服務(wù)端是活的。這一步能排除掉一半的問題。最后檢查協(xié)議版本。MCP 協(xié)議在演進不同版本的 server 和 client 可能不兼容。網(wǎng)關(guān)配置里如果有版本協(xié)商選項確認兩邊對得上。4.2 工具參數(shù)校驗的邊界情況JSON Schema 校驗看起來簡單實際用起來邊界情況很多。模型有時候會傳null給一個非必填但類型是 string 的參數(shù)。嚴格校驗會拒絕但模型的本意可能是不傳這個參數(shù)。這種情況我一般在校驗前先做一層清洗把null轉(zhuǎn)成 undefined。還有枚舉值的問題。模型可能傳一個語義相近但不在枚舉列表里的值。比如枚舉是[北京, 上海, 廣州]模型傳了北京市。嚴格校驗會失敗但用戶意圖是明確的。我的做法是在校驗失敗時先嘗試做一次模糊匹配匹配不上再返回錯誤讓模型重試。數(shù)字類型也有坑。模型可能把數(shù)字傳成字符串25或者傳成浮點數(shù)25.0而 schema 要求 integer。這些都需要在校驗層做兼容處理。4.3 Skills 加載順序與覆蓋規(guī)則Skills 加載順序會影響最終行為這一點很多人沒注意到。如果兩個 Skill 都定義了同名工具后加載的會覆蓋先加載的。如果兩個 Skill 都注入了系統(tǒng)提示詞提示詞會拼接在一起但拼接順序會影響模型的理解。我的建議是顯式聲明加載順序不要依賴默認順序。在配置里按優(yōu)先級從低到高排列高優(yōu)先級的 Skill 放后面。同時給每個 Skill 的工具加命名空間前綴避免沖突。還有一個坑是 Skills 的依賴關(guān)系。有的 Skill 依賴另一個 Skill 提供的工具如果加載順序不對依賴的工具還沒注冊Skill 初始化就會失敗。這種情況需要在配置里聲明依賴讓網(wǎng)關(guān)按依賴順序加載。4.4 高并發(fā)下的連接池與限流單機跑 demo 沒問題一上并發(fā)就原形畢露。MCP 連接是長連接如果每個請求都新建連接很快就會把 server 端打滿。網(wǎng)關(guān)需要維護連接池復用連接。連接池的大小要根據(jù) server 端的承載能力設(shè)置太小會排隊太大會把 server 壓垮。模型 API 一般都有速率限制。網(wǎng)關(guān)需要做限流超過限制的請求要么排隊要么降級。我一般用令牌桶算法桶的大小根據(jù) API 的配額設(shè)置。還有一個容易忽略的點是超時傳遞。如果調(diào)用方設(shè)了 10 秒超時網(wǎng)關(guān)內(nèi)部調(diào)模型設(shè)了 30 秒那調(diào)用方早就超時了網(wǎng)關(guān)還在等模型。正確的做法是網(wǎng)關(guān)的超時時間要小于調(diào)用方的超時時間留出處理余量。5. 把 tsm-hub 用出花來的幾個進階思路基礎(chǔ)功能跑通之后可以玩一些進階的。這些思路有的是我自己實踐過的有的是看到社區(qū)里別人分享的都挺有意思。5.1 用 Skills 做領(lǐng)域知識的固化Skills 最大的價值不是封裝工具而是固化領(lǐng)域知識。舉個例子做醫(yī)療問答場景。通用模型對醫(yī)學術(shù)語的理解可能不夠準確但如果你把一套醫(yī)學知識庫的檢索工具、一套醫(yī)學術(shù)語的標準化處理流程、一套回答格式規(guī)范打包成一個 Skill模型的表現(xiàn)會好很多。再比如做法律文書生成。不同文書的格式要求、引用規(guī)范、措辭習慣都不一樣。把這些做成 Skills模型就不用每次從零學習。我自己的做法是每做一個新場景先花時間把領(lǐng)域知識整理成 Skill。前期投入大但后面復用的時候非常省事。5.2 多模型協(xié)同的路由策略tsm-hub 支持多模型這給了做協(xié)同路由的空間。一種思路是大小模型配合。簡單任務(wù)走小模型復雜任務(wù)走大模型。判斷任務(wù)復雜度可以用規(guī)則也可以用一個小模型做分類。另一種思路是多模型投票。同一個問題發(fā)給多個模型取多數(shù)一致的結(jié)果。適合對準確性要求高的場景但成本會翻倍。還有一種是模型接力。第一個模型做初步處理第二個模型做精修。比如先讓模型生成大綱再讓另一個模型根據(jù)大綱寫正文。這些策略在 tsm-hub 里都可以通過路由配置實現(xiàn)不需要改業(yè)務(wù)代碼。5.3 可觀測性建設(shè)日志、指標、追蹤網(wǎng)關(guān)是流量的必經(jīng)之路天然適合做可觀測性。日志方面我建議記錄每個請求的完整鏈路調(diào)了哪個模型、用了哪些工具、走了哪些 MCP、加載了哪些 Skills、各階段耗時多少。這些信息在排查問題時非常有用。指標方面關(guān)注幾個核心數(shù)據(jù)請求量、成功率、平均延遲、各模型的調(diào)用分布、各工具的調(diào)用頻率。這些指標能幫你發(fā)現(xiàn)瓶頸和異常。追蹤方面如果團隊有分布式追蹤系統(tǒng)把網(wǎng)關(guān)的調(diào)用鏈路接進去。一個請求從進入到返回中間經(jīng)過了哪些環(huán)節(jié)一目了然。提示日志里不要記錄完整的請求和響應(yīng)內(nèi)容尤其是涉及用戶隱私的場景。記錄摘要和元數(shù)據(jù)就夠了。5.4 安全邊界鑒權(quán)、審計、內(nèi)容過濾網(wǎng)關(guān)作為統(tǒng)一入口也是做安全控制的好地方。鑒權(quán)方面可以在網(wǎng)關(guān)層做 API Key 校驗、JWT 驗證、權(quán)限控制。不同調(diào)用方給不同的權(quán)限能訪問哪些模型、哪些工具、哪些 Skills都在網(wǎng)關(guān)層控制。審計方面記錄誰在什么時候調(diào)了什么用于事后追溯。合規(guī)要求高的場景審計日志是必須的。內(nèi)容過濾方面可以在請求進入模型之前和響應(yīng)返回調(diào)用方之前做過濾。輸入過濾防止惡意提示詞注入輸出過濾防止敏感內(nèi)容泄露。這些安全能力如果散落在各個業(yè)務(wù)里維護成本很高。收斂到網(wǎng)關(guān)層統(tǒng)一管理省事很多。6. 關(guān)于統(tǒng)一網(wǎng)關(guān)這件事我的真實看法寫到這里我想說點掏心窩的話。統(tǒng)一網(wǎng)關(guān)這個思路在工程上是對的。它確實能降低接入復雜度提高復用率讓業(yè)務(wù)方專注于業(yè)務(wù)邏輯。tsm-hub 把 LLM、Tools、MCP、Skills 四層收攏到一個入口設(shè)計上是清晰的。但網(wǎng)關(guān)不是沒有代價的。它引入了一個額外的抽象層意味著多一跳網(wǎng)絡(luò)開銷多一個故障點多一層需要維護的配置。如果團隊規(guī)模小、場景簡單硬上網(wǎng)關(guān)可能是負優(yōu)化。我的判斷標準是當你發(fā)現(xiàn)同樣的接入邏輯在三個以上的地方重復出現(xiàn)時就該考慮抽網(wǎng)關(guān)層了。如果只有一個業(yè)務(wù)在用直接在業(yè)務(wù)里調(diào)模型和工具反而更簡單。另外網(wǎng)關(guān)的抽象要適度。我見過一些網(wǎng)關(guān)設(shè)計得過于通用配置項多到?jīng)]人能看懂最后大家還是繞過網(wǎng)關(guān)直接調(diào)底層。好的網(wǎng)關(guān)應(yīng)該是默認配置就能用高級配置才需要看文檔。tsm-hub 目前給我的感覺是抽象層級把握得還不錯四層各司其職沒有過度設(shè)計。但具體到每個團隊還是要根據(jù)自己的場景做取舍。工具是死的人是活的適合自己的才是最好的。最后分享一個小技巧搭網(wǎng)關(guān)的時候先別急著接所有模型和工具。先用一個模型、一個工具、一個 Skill 把全鏈路跑通確認架構(gòu)沒問題再逐步擴展。我見過太多人一上來就配一大堆結(jié)果出了問題根本不知道是哪一層的事。從最小可用開始逐步迭代這個原則在網(wǎng)關(guān)搭建上同樣適用。