最近社區(qū)里聊 Agent 的人越來越多但說實話大部分教程都停留在“調(diào)接口、拼 Prompt”的層面真正能把 Agent 落到生產(chǎn)環(huán)境、讓它穩(wěn)定干活的內(nèi)容很少。我花了大概三周時間在騰訊云上把一個帶技能體系A(chǔ)I Skills的 Agent 從零搭到可用中間踩了容器推送、二級域名、Redis 密碼、模型網(wǎng)關(guān)配置一堆坑。這篇文章就是那次完整實踐的復(fù)盤重點(diǎn)講清 AI Skills 的設(shè)計思路以及在騰訊云上部署時那些文檔里不會寫清楚的細(xì)節(jié)。這篇內(nèi)容適合兩類人一類是已經(jīng)在做 Agent 開發(fā)、想給機(jī)器人增加“干活能力”的工程師另一類是剛把 Agent 概念接入項目、準(zhǔn)備上云部署但不確定基礎(chǔ)設(shè)施怎么選的團(tuán)隊。文章不繞彎子直接從“為什么需要 Skill”講起到騰訊云服務(wù)器、容器鏡像服務(wù)、Redis、域名解析、模型網(wǎng)關(guān)一步步展開最后是所有坑的排查清單。你看完可以直接照著抄。1. 先想清楚Agent 為什么需要 Skill而不是靠 Prompt 硬撐1.1 從“聊天機(jī)器人”到“能干活的人”我先說一個觀察很多團(tuán)隊做 Agent 的第一版本質(zhì)上就是把大模型的 Prompt 寫長了一點(diǎn)讓模型“看起來”會調(diào)用幾個 API。這種方案做 Demo 沒問題但一旦進(jìn)入真實業(yè)務(wù)馬上會遇到三個麻煩第一Prompt 越長模型越容易在關(guān)鍵步驟上“自由發(fā)揮”。你讓它調(diào)兩個接口完成一個流程它可能會跳過第二個或者把參數(shù)傳錯。第二所有邏輯都堆在 Prompt 里運(yùn)維和排錯極其痛苦。線上出問題你根本不知道是模型理解錯了還是接口返回的數(shù)據(jù)格式變了。第三你想給 Agent 加一個新能力比如“查一下訂單物流”就得重新改寫 Prompt反復(fù)調(diào)優(yōu)改完還可能影響原本穩(wěn)定的功能。Skill 解決的就是這個問題。它的本質(zhì)是給 Agent 預(yù)裝一套“操作手冊”把某個能力的調(diào)用方式、參數(shù)約束、輸出格式、異常處理都固化下來。Agent 在運(yùn)行時會根據(jù)用戶需求去檢索和調(diào)用合適的 Skill而不是靠模型現(xiàn)場“猜”。我自己的體會是把 Agent 從“聊天”變成“干活”分水嶺就在于有沒有一套結(jié)構(gòu)化的 Skill 體系。沒有 Skill 的 Agent就像一個新員工只有一堆口頭叮囑干不干得好全看悟性有了 Skill等于給這個員工配了標(biāo)準(zhǔn)作業(yè)流程和工具說明書。1.2 Skill 到底是什么給 Agent 預(yù)裝的操作手冊Skill 可以理解為一段結(jié)構(gòu)化的能力描述加執(zhí)行邏輯。它通常包含三個部分觸發(fā)條件、調(diào)用接口的方式、結(jié)果處理規(guī)則。舉個具體的例子。我給 Agent 注冊了一個“查詢騰訊云服務(wù)器監(jiān)控數(shù)據(jù)”的 Skill。它的觸發(fā)條件是用戶在對話中提到“服務(wù)器負(fù)載”“CPU 使用率”“監(jiān)控”等關(guān)鍵詞接口調(diào)用方式固定為調(diào)用騰訊云監(jiān)控 API參數(shù)從用戶對話中抽取實例 ID、時間范圍結(jié)果處理則是把返回的 JSON 數(shù)據(jù)整理成易于閱讀的指標(biāo)趨勢并給出簡單的閾值判斷。有了這個 SkillAgent 不需要每次都從零推理“如何查監(jiān)控”它只需要做兩件事判斷當(dāng)前需求是否命中了這個 Skill然后按 Skill 里定義的規(guī)則去執(zhí)行。關(guān)鍵點(diǎn)在于Skill 更像是“約定”而不是“提示”。它不是告訴模型“你可以這樣想”而是告訴模型“你必須這么做”。這種確定性帶來的好處是同樣的輸入每次執(zhí)行的結(jié)果都是穩(wěn)定可控的。1.3 Skill 和普通 Prompt、插件、Workflow 的邊界在哪很多人問 Skill、插件Plugin、工作流Workflow到底有什么區(qū)別。我自己的理解是這樣的Prompt 是給模型的指令它是“軟的”模型可以自由解釋插件是給 Agent 的工具調(diào)用接口它解決的是“能用什么工具”的問題Workflow 是把多個步驟編排成固定流程解決的是“按什么順序做”的問題Skill 則是在插件之上再加一層“怎么用、什么時候用、結(jié)果怎么處理”的經(jīng)驗封裝。打個比方。插件相當(dāng)于給你一把電鉆Workflow 是告訴你先量尺寸、再打孔、最后擰螺絲而 Skill 是告訴你“在什么場景下用電鉆、遇到墻面太硬要怎么處理、打出來的孔偏差超過多少就該換方案”。Skill 包含了觸發(fā)判斷、執(zhí)行步驟、異常處理和經(jīng)驗規(guī)則它是插件 使用經(jīng)驗 兜底邏輯的組合體。所以在實際架構(gòu)里Skill 通常會調(diào)用一個或多個插件能力但 Skill 本身攜帶了更多上下文與決策信息。這也是為什么 Skill 能讓 Agent 更接近“專家”而不是“工具集合”。2. 騰訊云上搭 Agent 的基礎(chǔ)設(shè)施選型2.1 服務(wù)器配置怎么選才不浪費(fèi)又不卡先說結(jié)論一個面向內(nèi)部團(tuán)隊測試和中等并發(fā)幾十個用戶同時使用的 Agent 服務(wù)2 核 4G 的輕量應(yīng)用服務(wù)器就能跑起來如果還要在里面運(yùn)行向量庫做長期記憶、跑模型網(wǎng)關(guān)建議直接上 4 核 8G。我最早用 1 核 2G 試過Agent 本身跑得動但一旦啟動 Redis、模型網(wǎng)關(guān)和 Agent 主服務(wù)三個進(jìn)程內(nèi)存直接見底系統(tǒng)開始瘋狂交換分區(qū)響應(yīng)延遲飆升到十幾秒。如果你計劃生產(chǎn)部署我給個參考配置表用途推薦配置說明輕量測試 / Demo2核4GAgent 服務(wù) Redis 可以共存模型調(diào)用走云端 API 沒問題正式環(huán)境 / 對外服務(wù)4核8G起步需要跑容器、網(wǎng)關(guān)、Redis、日志收集建議再加 50G 以上 SSD 數(shù)據(jù)盤高并發(fā) / 多租戶8核16G或更高考慮多副本部署、負(fù)載均衡Redis 獨(dú)立實例做好容器資源限制騰訊云的服務(wù)器地域選哪里也值得說一句。如果用戶群主要在國內(nèi)選離你最近的可用區(qū)就好如果你的業(yè)務(wù)涉及跨境訪問就要考慮合規(guī)和網(wǎng)絡(luò)延遲的問題這個按實際業(yè)務(wù)場景來定我不展開。實際操作時我建議系統(tǒng)盤買大一點(diǎn)。Agent 的依賴鏡像特別占空間一個 Python 基礎(chǔ)鏡像加若干依賴就兩三個 G再加上 Docker 鏡像、日志文件50G 系統(tǒng)盤很快就緊張了。2.2 容器鏡像服務(wù)把 Agent 打包推上云的正確姿勢我部署 Agent 的方式是全部容器化用騰訊云的容器鏡像服務(wù)TCR來托管鏡像。很多人第一步就卡在“本地構(gòu)建好鏡像但推送不上去”。騰訊云容器鏡像服務(wù)的推送邏輯是這樣的先在控制臺創(chuàng)建命名空間和鏡像倉庫然后用 docker login 登錄再把本地鏡像 tag 成騰訊云倉庫的格式最后 docker push。以騰訊云廣州地域的個人版 TCR 為例命令大概是這樣的# 登錄用戶名是你的騰訊云賬號 ID密碼是控制臺臨時登錄指令生成的密鑰 docker login ccr.ccs.tencentyun.com --username your_account_id --password your_temporary_token # 給本地鏡像打標(biāo)簽格式ccr.ccs.tencentyun.com/[命名空間]/[倉庫名]:[版本] docker tag agent-server:latest ccr.ccs.tencentyun.com/mynamespace/agent-server:latest # 推送 docker push ccr.ccs.tencentyun.com/mynamespace/agent-server:latest這里最容易踩三個坑第一個登錄用的密碼不是賬號密碼。個人版 TCR 的登錄密碼需要在控制臺“容器鏡像服務(wù) - 個人版 - 實例信息”里生成臨時登錄指令或者用 API 密鑰。直接拿登錄密碼去 docker login百分之百失敗。第二個命名空間必須提前在控制臺建好而且命名空間有地域?qū)傩?。你在控制臺建的是廣州的命名空間就只能推送到廣州的鏡像地址。第三個鏡像版本管理要養(yǎng)成習(xí)慣。每次構(gòu)建都打上日期或 git commit 號比如 agent-server:20250521-abc1234這樣線上出了問題能精確定位到是哪個代碼版本。2.3 二級域名和 HTTPS讓 Agent 服務(wù)有正式入口Agent 服務(wù)跑在服務(wù)器上總要給用戶一個訪問入口。用裸 IP 加端口號雖然能訪問但特別不方便而且很多現(xiàn)代瀏覽器對非 HTTPS 的接口權(quán)限限制越來越多比如音頻、攝像頭、部分剪貼板 API。所以給 Agent 配一個二級域名和 HTTPS 證書是必須的。騰訊云上申請二級域名的操作其實很簡單就是給主域名添加一條 DNS 解析記錄。比如你的主域名是 example.com想讓 Agent 服務(wù)通過 agent.example.com 訪問就在 DNS 解析面板加一條記錄主機(jī)記錄agent 記錄類型A 記錄值你的服務(wù)器公網(wǎng) IP如果你有多臺服務(wù)器建議用 CNAME 記錄指向負(fù)載均衡域名而不是直接寫 IP這樣以后擴(kuò)容不用改解析。記錄加完之后需要給這個域名申請 SSL 證書。騰訊云有免費(fèi)的證書額度申請之后下載 Nginx 格式的證書然后在服務(wù)器 Nginx 配置里加段server { listen 443 ssl http2; server_name agent.example.com; ssl_certificate /etc/nginx/ssl/agent_example_com.pem; ssl_certificate_key /etc/nginx/ssl/agent_example_com.key; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }有個地方我一開始沒注意如果是國內(nèi)服務(wù)器部署對外服務(wù)域名需要按相關(guān)要求完成合規(guī)備案流程。建議在配置解析之前就確認(rèn)好備案狀態(tài)否則域名雖然解析通但 80 和 443 端口的訪問會被攔截。這個是實際部署中的硬門檻做之前一定要先查清楚自己的域名和服務(wù)器是否符合接入要求。2.4 Redis 安裝和密碼修改一個讓我折騰半天的坑Agent 的會話記憶、緩存、臨時狀態(tài)都離不開 Redis。我直接在服務(wù)器上用 Docker 跑了一個 Redis 容器本來以為很省事結(jié)果在“修改 Redis 密碼”這個操作上栽了個大跟頭。事情是這樣的默認(rèn)安裝的 Redis 沒有密碼我打算加一個強(qiáng)密碼。第一次操作我直接修改了容器里的 redis.conf把 requirepass 加進(jìn)去然后執(zhí)行 redis-cli shutdown 再啟動容器。結(jié)果啟動之后連不上了報錯信息是 NOAUTH Authentication required 或者連接被拒絕。排查了很久問題出在三個方面這里直接列出來給大家避坑第一用 Docker 啟動 Redis 時如果通過命令行指定了 redis-server 啟動參數(shù)比如常見的 --appendonly yes那么配置文件里的 requirepass 會被命令行參數(shù)覆蓋或者根本沒有被加載。我后來直接用環(huán)境變量和命令行參數(shù)來管理配置干凈的寫法是這樣docker run -d \ --name redis-agent \ -p 6379:6379 \ -v /data/redis:/data \ redis:7-alpine \ redis-server --requirepass 你的強(qiáng)密碼 --appendonly yes第二修改密碼之后舊連接不會自動斷開導(dǎo)致新請求還會用舊密碼去訪問。我改了密碼后 Redis 進(jìn)程還活著舊客戶端連接仍然有效但新連接全部失敗看起來就像“Redis 壞了”其實是需要把客戶端連接全部重置。第三如果你用 systemd 管理 Redis 服務(wù)而不是容器那么修改配置文件后必須 systemctl daemon-reload 再重啟服務(wù)。很多人直接改完配置文件重啟服務(wù)但 systemd 讀取的還是舊的 unit 文件改了等于白改。密碼這東西也要注意別用純數(shù)字或弱密碼。我生成隨機(jī)強(qiáng)密碼時用了一段帶特殊字符的字符串結(jié)果在連接 URL 里沒做轉(zhuǎn)義又把服務(wù)搞掛了一次。正確做法是把 Redis 密碼單獨(dú)放環(huán)境變量文件里代碼里用環(huán)境變量拼接連接串避免特殊字符地獄。3. AI Skills 的核心設(shè)計思路與最佳實踐3.1 一個標(biāo)準(zhǔn) Skill 應(yīng)該長什么樣我用了很多種 Skill 設(shè)計方式之后最終沉淀下來一套相對固定的模板。每個 Skill 包含元信息、觸發(fā)條件、輸入?yún)?shù)、執(zhí)行邏輯、輸出處理和異常兜底六塊內(nèi)容。以“查詢騰訊云服務(wù)器監(jiān)控”這個 Skill 為例它的標(biāo)準(zhǔn)結(jié)構(gòu)是skill_name: query_tcloud_monitor description: 查詢騰訊云服務(wù)器 CPU、內(nèi)存、磁盤、帶寬等監(jiān)控指標(biāo) triggers: - 關(guān)鍵詞匹配: [服務(wù)器負(fù)載, CPU, 內(nèi)存使用率, 監(jiān)控] - 語義匹配: 用戶想查看某臺云服務(wù)器當(dāng)前或歷史的資源使用情況 parameters: instance_id: type: string required: true description: 服務(wù)器實例 ID格式如 ins-xxxxxxxx extraction: 從對話中抽取抽取不到時向用戶詢問 start_time: type: datetime required: false default: 最近1小時 description: 監(jiān)控數(shù)據(jù)起始時間 metric_names: type: array required: false default: [CPUUsage, MemUsage] description: 需要查詢的指標(biāo)列表 execution: api: TencentCloud.Monitor.GetMonitorData http_method: POST timeout_ms: 5000 retry: 2 output: format: markdown_table include_threshold_alert: true exception_handling: invalid_instance_id: 提示用戶實例 ID 不存在并列出當(dāng)前賬號下的實例列表供選擇 api_error: 返回錯誤信息并建議稍后重試 timeout: 提示查詢超時引導(dǎo)用戶縮小時間范圍這個結(jié)構(gòu)的核心好處是模型只需要做“填空”和“選擇”不需要做“創(chuàng)造”。參數(shù)怎么抽、調(diào)哪個接口、出錯怎么辦在 Skill 定義里全部寫清楚了模型根本不需要發(fā)揮。3.2 技能拆分“最少夠用”原則剛開始設(shè)計 Skills 時我犯過一個典型錯誤把 Skill 拆得太細(xì)。比如我拆出了“查 CPU”“查內(nèi)存”“查磁盤”“查帶寬”四個獨(dú)立 Skill看起來職責(zé)單一但運(yùn)行起來發(fā)現(xiàn) Agent 經(jīng)常不知道該調(diào)哪個而且用戶說“服務(wù)器有問題”這種模糊話術(shù)時模型會同時匹配多個 Skill導(dǎo)致沖突。后來我把同類操作合并成一個 Skill“查服務(wù)器各項指標(biāo)”通過參數(shù) metric_names 來區(qū)分具體查什么。合并之后匹配準(zhǔn)確率明顯提升誤調(diào)用的情況大幅減少。這就是我想說的“最少夠用”原則Skill 的數(shù)量不是越多越好而是剛好覆蓋用戶的高頻需求就行。判斷標(biāo)準(zhǔn)很簡單——如果兩個 Skill 的觸發(fā)條件和參數(shù)幾乎一樣只是返回值不同那就應(yīng)該合并如果兩個 Skill 觸發(fā)條件差異很大、執(zhí)行邏輯完全不同再拆開。一般來說一個初版 Agent 有 5 到 8 個 Skill 就足夠覆蓋大部分場景了。超過 15 個 Skill 之后模型的召回準(zhǔn)確率會明顯下降因為匹配空間越大迷惑性越強(qiáng)。你要做的是控制 Skill 數(shù)量而不是無限制地增加。3.3 參數(shù)抽取與錯誤回退Skill 好不好用很大程度取決于參數(shù)抽取做得好不好。設(shè)計 Skill 參數(shù)時我總結(jié)出三條經(jīng)驗第一每個參數(shù)都要有明確的抽取來源和兜底策略。比如 instance_id 這種必填參數(shù)如果用戶沒說Agent 應(yīng)該主動詢問而不是猜一個默認(rèn)值。我見過很多 Agent 在參數(shù)不全時硬跑出錯用戶體驗極差。第二參數(shù)類型要盡量嚴(yán)格。把所有參數(shù)都當(dāng)字符串處理看似省事但到了 API 調(diào)用環(huán)節(jié)全是坑。比如時間參數(shù)用戶說“昨天”“凌晨”“這周”如果你不換算成標(biāo)準(zhǔn)時間格式傳給云監(jiān)控 API 直接報錯。我現(xiàn)在的做法是在 Skill 定義里寫清楚每個參數(shù)需要轉(zhuǎn)換成的標(biāo)準(zhǔn)類型以及在對話中如何提取。第三給每個參數(shù)設(shè)置一個合理的取值范圍或校驗規(guī)則。比如時間范圍不能超過 30 天端口號必須在 1 到 65535 之間。參數(shù)校驗放在 Skill 執(zhí)行前可以攔截大量無效請求。錯誤回退也很關(guān)鍵。當(dāng) Agent 調(diào)用的 API 返回錯誤時不要直接把錯誤堆棧拋給用戶而是按 Skill 里定義好的異常處理邏輯給出友好提示。例如實例 ID 不對時主動列出用戶賬號下的所有實例供選擇接口超時時建議縮小查詢范圍重試。這些回退邏輯能極大提升 Agent 的“靠譜感”。3.4 技能的注冊與召回Skill 在系統(tǒng)里通常通過兩種方式被 Agent“看到”一種是在每次對話時把所有 Skill 的描述塞給模型讓模型自己選擇另一種是把 Skill 的描述做成向量索引通過檢索召回相關(guān)技能。前者的缺點(diǎn)是Skill 一多上下文窗口消耗太大而且模型容易受到無關(guān) Skill 干擾。后者的優(yōu)點(diǎn)是擴(kuò)展性好但需要一套檢索系統(tǒng)。我實際用的方案是兩者結(jié)合核心高頻 Skill 常駐在系統(tǒng) Prompt 里長尾 Skill 做成向量檢索。每次用戶輸入進(jìn)來先做語義檢索把相關(guān) Skill 找出來再連同常駐 Skill 一起拼接成當(dāng)前會話可用的技能列表。這樣做的原因很直接核心 Skill 隨時能調(diào)召回速度快不會因為檢索問題導(dǎo)致“明明有技能卻沒用上”長尾 Skill 靠向量召回數(shù)量再多也不占上下文窗口。如果你已經(jīng)用了騰訊云的向量數(shù)據(jù)庫產(chǎn)品可以直接把 Skill 描述向量化放進(jìn)去沒有的話用 Redis 配 embedding 也能實現(xiàn)輕量版。4. 完整實操在騰訊云上部署帶 Skills 的 Agent4.1 實操前需要準(zhǔn)備的東西動手之前先列一個清單避免我在部署時那種“發(fā)現(xiàn)少了這個又少了那個”的尷尬一臺騰訊云服務(wù)器我用的 4 核 8G系統(tǒng) Ubuntu 22.04開放 80、443、22 端口一個已備案的域名DNS 解析面板可以操作騰訊云容器鏡像服務(wù)已開通建好命名空間一個模型 API Key我這次主要用的 DeepSeek 和騰訊混元通過 LiteLLM 網(wǎng)關(guān)統(tǒng)一接入Docker 和 Docker Compose 已安裝在服務(wù)器上Redis 鏡像已拉取到本地建議提前把域名解析加了因為 DNS 解析生效需要時間。我因為等解析浪費(fèi)了將近二十分鐘本來可以并行做的事情排成了串行。4.2 服務(wù)編排主服務(wù)、模型網(wǎng)關(guān)、Redis 一次拉起我習(xí)慣用 Docker Compose 管理整套服務(wù)把 Agent 主服務(wù)、LiteLLM 網(wǎng)關(guān)、Redis 三個服務(wù)編排在一起。Compose 文件核心部分是這樣寫的services: agent-server: image: ccr.ccs.tencentyun.com/mynamespace/agent-server:20250521 ports: - 8000:8000 environment: - REDIS_URLredis://:${REDIS_PASSWORD}redis-agent:6379/0 - LLM_GATEWAY_URLhttp://litellm-gateway:4000 depends_on: - redis-agent - litellm-gateway litellm-gateway: image: ghcr.io/berriai/litellm:main-latest ports: - 4000:4000 volumes: - ./litellm_config.yaml:/app/config.yaml command: [--config, /app/config.yaml, --port, 4000] environment: - LITELLM_MASTER_KEY${LITELLM_MASTER_KEY} - DEEPSEEK_API_KEY${DEEPSEEK_API_KEY} redis-agent: image: redis:7-alpine command: [redis-server, --requirepass, ${REDIS_PASSWORD}, --appendonly, yes] volumes: - redis_data:/data這套編排的好處是服務(wù)之間通過 Docker 內(nèi)部網(wǎng)絡(luò)通信不需要對外暴露 Redis 端口Redis 密碼和模型密鑰都通過環(huán)境變量注入不會明文寫進(jìn)代碼庫。LiteLLM 網(wǎng)關(guān)統(tǒng)一管理模型調(diào)用Agent 主服務(wù)訪問模型只需要記一個地址切換模型廠商時不用改業(yè)務(wù)代碼。LiteLLM 的配置文件也很簡單把要用的模型供應(yīng)商和模型名注冊進(jìn)去就行model_list: - model_name: deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: os.environ/DEEPSEEK_API_KEY - model_name: hunyuan-pro litellm_params: model: tencent/hunyuan-pro api_key: os.environ/HUNYUAN_API_KEY用網(wǎng)關(guān)還有兩個隱藏收益一是可以在網(wǎng)關(guān)層做統(tǒng)一的重試、超時和限流單模型 API 抖動時不會把 Agent 主流程打崩二是可以通過網(wǎng)關(guān)的日志功能記錄每一次模型調(diào)用的 token 消耗月底算成本一目了然。4.3 從本地 Docker 構(gòu)建到服務(wù)器拉取部署本地的鏡像構(gòu)建好推送之后在服務(wù)器上要把整套服務(wù)拉起來。服務(wù)器本身不需要裝代碼倉庫只需要從騰訊云鏡像倉庫拉取鏡像。順序是這樣的# 1. 在服務(wù)器上登錄騰訊云鏡像倉庫 docker login ccr.ccs.tencentyun.com --username your_account_id --password your_temporary_token # 2. 拉取鏡像 docker pull ccr.ccs.tencentyun.com/mynamespace/agent-server:20250521 # 3. 準(zhǔn)備 Compose 文件和環(huán)境變量文件 vim docker-compose.yml vim .env # 寫入 REDIS_PASSWORD、LITELLM_MASTER_KEY、DEEPSEEK_API_KEY 等 # 4. 啟動服務(wù) docker compose up -d啟動之后用 docker compose ps 看三個服務(wù)的狀態(tài)。我建議等十幾秒再訪問接口因為 Agent 主服務(wù)啟動時要加載技能定義、初始化 Redis 連接LiteLLM 網(wǎng)關(guān)也要做健康檢查。第一次訪問 http://agent.example.com 時如果頁面打不開或者返回 502先別慌按順序檢查Nginx 配置里 proxy_pass 指向的后端端口是否對上防火墻是否放行了 80 和 443證書是否綁定正確。我遇到過的 502 大多數(shù)是 Nginx 配置里端口寫錯或者主服務(wù)還沒完全啟動起來導(dǎo)致的。4.4 驗證 Skill 是否真正生效服務(wù)跑起來后最關(guān)鍵的驗證是測試 Skill 會不會被正確觸發(fā)。我有一個固定的測試集快速提問“我的服務(wù)器 CPU 負(fù)載高不高”——期望 Agent 匹配到查詢監(jiān)控的 Skill并返回當(dāng)前 CPU 使用率以及是否有異常提示。對比測試先直接問“你好”再問“幫我看看現(xiàn)在系統(tǒng)狀態(tài)怎么樣”——前者應(yīng)該走普通對話不應(yīng)該誤觸發(fā)監(jiān)控 Skill后者才應(yīng)該觸發(fā)。模糊測試只說“我感覺服務(wù)有點(diǎn)慢”——這種情況下模型可能不會觸發(fā)任何 Skill而是反問用戶是否需要檢查服務(wù)器資源。這也是合理的因為觸發(fā)條件沒有完全命中。測試中如果發(fā)現(xiàn) Skill 沒有被正確觸發(fā)通常是三個原因技能描述寫得太泛和多個 Skill 描述重疊觸發(fā)關(guān)鍵詞沒覆蓋常見說法向量檢索的閾值設(shè)得太高召回不到。定位時可以先在日志里看模型最終收到的技能列表如果列表里就沒有這個技能那么要么是召回問題要么是描述重疊問題如果列表里有了但模型還是沒用那就可能是上下文里技能描述不清楚需要調(diào)整描述措辭。5. 常見問題排查與避坑速查5.1 Redis 修改密碼后重啟失敗完整排查思路這是我這次部署里最典型的“看起來簡單但搞了很久”的問題專門拿出來詳細(xì)說?，F(xiàn)象是修改 redis.conf 添加 requirepass 后重啟 Redis服務(wù)要么起不來要么起來了連不上。第一步先確認(rèn) Redis 到底起來沒有。執(zhí)行 docker ps 看容器狀態(tài)如果容器反復(fù)重啟用 docker logs redis-agent 看日志。日志里如果出現(xiàn)# Warning: config file ... cant be parsed或者Bad directive or wrong number of arguments說明配置語法有錯誤重點(diǎn)檢查 requirepass 這一行有沒有多余空格、是否寫在了錯誤的配置段下。第二步如果你用的是 Docker 啟動且同時給了命令行參數(shù)要明白命令行參數(shù)的優(yōu)先級。我之前遇到過配置文件里寫了 requirepass但 docker run 命令里又追加了 redis-server --appendonly yes導(dǎo)致部分配置被覆蓋。最保險的做法是全部配置都用命令行參數(shù)或者全部用配置文件不要混用。第三步如果 Redis 起來了但客戶端報 NOAUTH檢查你的客戶端連接串是否正確。連接 URL 里密碼包含特殊字符時必須 URL 編碼。比如密碼是Abc123在 URL 里要寫成Abc%40123。我用 Python 的 redis 庫時習(xí)慣用 redis.Redis(host..., password..., port6379) 顯式傳 password繞開 URL 編碼問題。第四步別忘了一個隱藏問題修改密碼后Redis 的主從復(fù)制如果配置了老密碼從節(jié)點(diǎn)會一直認(rèn)證失敗。如果你有從庫必須同步修改所有節(jié)點(diǎn)的密碼配置否則數(shù)據(jù)同步會中斷。5.2 Docker 推送到騰訊云鏡像倉庫失敗推送失敗的常見情況分兩種登錄失敗和上傳超時。登錄失敗先確認(rèn)賬號和密碼來源。騰訊云 TCR 的登錄賬號通常是賬號 ID 而不是自定義用戶名密碼是臨時登錄指令或 API 密鑰。去控制臺重新生成一次臨時登錄指令復(fù)制時注意不要把換行符帶進(jìn)去。上傳超時多半是鏡像太大或網(wǎng)絡(luò)不穩(wěn)定。解決方案有兩個如果是單個鏡像太大檢查 .dockerignore把本地緩存、模型文件、測試數(shù)據(jù)都排除掉如果是網(wǎng)絡(luò)問題可以在 docker 配置里設(shè)置適合國內(nèi)環(huán)境的鏡像加速地址騰訊云控制臺有官方加速器配置照著設(shè)置就行。另外鏡像分層也很重要。每次構(gòu)建時把不變的依賴層寫在前面、頻繁改動的代碼層寫在后面這樣推送增量時速度會快很多。我自己重建鏡像時依賴層只要不變推送基本在幾十秒內(nèi)完成。5.3 模型調(diào)用超時與網(wǎng)關(guān)返回 429Agent 上線后最常遇到的線上問題就是模型調(diào)用變慢、報 429。原因通常有兩類一類是單一模型服務(wù)商限流另一類是網(wǎng)關(guān)層沒有做重試與排隊。用 LiteLLM 網(wǎng)關(guān)之后可以在配置里開啟重試與限流參數(shù)。通用建議是單次請求超時設(shè)置為 30 到 60 秒重試最多 1 到 2 次重試間隔用指數(shù)退避。如果 Agent 是面向多用戶服務(wù)的建議再加上 per-user 級別的限流避免某個用戶刷接口把額度吃光。我還習(xí)慣給不同優(yōu)先級的請求設(shè)置不同的模型路由。比如實時對話走快速模型離線分析走強(qiáng)模型。這種策略在網(wǎng)關(guān)配置里實現(xiàn)非常容易只需要在 model_list 里增加一個模型別名并指向不同后端的模型即可。5.4 Skill 不生效從日志定位召回和選擇問題Skill 已經(jīng)注冊到系統(tǒng)里但模型就是“視而不見”這種情況我遇到過好幾次。定位路徑是這樣的打開 Agent 主服務(wù)的日志查看每次請求時系統(tǒng)最終發(fā)送給模型的技能列表。如果技能列表里沒有目標(biāo) Skill說明召回失敗。檢查 Skill 描述是否太具體、用戶提問用詞和描述差異太大或者向量檢索閾值太高。解決方法可以是增加同義詞觸發(fā)詞或者把 Skill 描述改寫得更通用。如果技能列表里有但模型沒調(diào)用說明模型“判斷不需要”。這種情況要么是 Skill 描述和用戶意圖匹配度不夠要么是技能描述太長被模型忽略了。試著把 Skill 描述精煉到 50 字以內(nèi)把最重要的觸發(fā)條件放在最前面。還有一種情況是并發(fā)沖突兩個 Skill 同時被召回模型猶豫再三選了一個不合適的。這種情況可以在 Skill 定義里加互斥邏輯描述里明確寫“當(dāng)用戶詢問 X 時請勿使用本技能”。雖然略帶粗暴但實測有效。5.5 一套每天都要做的“健康自檢”Agent 這類系統(tǒng)最怕的不是出了大故障而是小問題積累成大坑。我給自己定了一個每日檢查清單內(nèi)容不多但很管用用三到五條標(biāo)準(zhǔn)測試用例跑一遍核心 Skill確認(rèn)召回和執(zhí)行都正常檢查 Redis 內(nèi)存使用量確認(rèn) key 沒有無限增長我會給會話鍵設(shè)置過期時間看一眼模型網(wǎng)關(guān)日志統(tǒng)計請求成功率并且在低于 95% 時排查原因檢查服務(wù)器磁盤占用清理舊的 Docker 鏡像和容器日志確認(rèn) SSL 證書剩余有效期提前一個月更換這套檢查做完大約十分鐘但能避免大多數(shù)“突然線上掛了”的窘境。我在這次部署中最深的感受是Agent 本身的技術(shù)框架已經(jīng)不是稀缺資源真正拉開差距的是 Skill 的設(shè)計質(zhì)量和基礎(chǔ)設(shè)施的穩(wěn)定程度。Skill 設(shè)計得好不好直接決定 Agent 是“看起來很聰明”還是“真的能干活”基礎(chǔ)設(shè)施穩(wěn)固不穩(wěn)固決定這個 Agent 能走多遠(yuǎn)。別急著加各種炫酷技能先把核心場景打磨透再逐步擴(kuò)展這才是做全能 Agent 的穩(wěn)妥路徑。