器人接入Ollama本地大模型：對(duì)話功能包完整實(shí)戰(zhàn))
把大語言模型接進(jìn)ROS2機(jī)器人這兩年討論熱度一直很高。但你翻看網(wǎng)上的教程會(huì)發(fā)現(xiàn)大部分內(nèi)容要么停留在概念圖要么只講ROS2基礎(chǔ)的話題收發(fā)真正把Ollama這種本地推理服務(wù)、對(duì)話模型和機(jī)器人通信串成一個(gè)可運(yùn)行功能包的實(shí)操文章非常少。這篇就以ollama_ros_chat功能包為線索把部署和使用整條線拆開講環(huán)境怎么配、功能包怎么建、代碼怎么寫、模型怎么選、聯(lián)調(diào)怎么排坑最后落到你能直接在自己工作空間里跑起來的狀態(tài)。這套方案解決的是很具體的工程問題機(jī)器人端不想依賴云端API對(duì)話數(shù)據(jù)希望留在本地同時(shí)又要能通過ROS2標(biāo)準(zhǔn)話題或服務(wù)被其他節(jié)點(diǎn)調(diào)用。它特別適合正在做輪式底盤、桌面機(jī)械臂、導(dǎo)覽機(jī)器人或者單純想把一個(gè)可對(duì)話的本地大模型裝進(jìn)自己ROS2環(huán)境里驗(yàn)證一下的開發(fā)者。大模型原理不用懂太多只要能照著敲命令、改參數(shù)就能在半小時(shí)內(nèi)把鏈路跑通后面再慢慢往業(yè)務(wù)場(chǎng)景上擴(kuò)展。1. 整體定位與方案設(shè)計(jì)思路1.1 為什么要在機(jī)器人上接本地大模型做機(jī)器人項(xiàng)目時(shí)語音助手、自然語言指令解析這些需求其實(shí)一直存在但過去實(shí)現(xiàn)成本很高。傳統(tǒng)做法是寫一堆規(guī)則匹配用關(guān)鍵詞模板把用戶指令映射成機(jī)器人動(dòng)作維護(hù)起來特別痛苦。只要用戶換一種問法規(guī)則就要補(bǔ)一條而且永遠(yuǎn)補(bǔ)不完。引入大模型之后自然語言理解這部分直接被通用模型接住了開發(fā)者可以把精力放在指令執(zhí)行和業(yè)務(wù)邏輯上。選擇本地部署而不是調(diào)用云端API我主要基于三個(gè)原因。第一是隱私與數(shù)據(jù)邊界機(jī)器人經(jīng)常運(yùn)行在室內(nèi)環(huán)境或者園區(qū)場(chǎng)景采集到的對(duì)話內(nèi)容可能包含具體的環(huán)境信息如果每句話都傳到云端數(shù)據(jù)歸屬和合規(guī)上很難講清楚。第二是網(wǎng)絡(luò)穩(wěn)定性機(jī)器人在運(yùn)行過程中無法保證任何時(shí)候都有可靠網(wǎng)絡(luò)尤其是移動(dòng)底盤在樓道、地下空間這種弱信號(hào)區(qū)域云端方案一旦斷線整個(gè)交互就崩了。第三是延遲和成本高頻的短對(duì)話如果全部走云端單次調(diào)用雖然便宜積累起來也是一筆開銷而本地推理跑起來之后完全可控。用本地大模型還有一個(gè)容易被忽略的好處調(diào)試體驗(yàn)完全不同。你可以直接在終端看模型的完整輸出改提示詞、調(diào)參數(shù)都是本地即時(shí)生效不需要經(jīng)過云端接口的審核和網(wǎng)絡(luò)往返。對(duì)于做原型驗(yàn)證和教學(xué)演示來說這種“所見即所得”的反饋速度比什么都重要。1.2 方案選型推理運(yùn)行時(shí)、模型和通信方式怎么定本地推理運(yùn)行時(shí)我最終選了Ollama原因很實(shí)在。它能用一條命令把模型拉下來然后直接用HTTP接口提供服務(wù)開發(fā)者完全不用接觸底層的模型權(quán)重管理、量化轉(zhuǎn)換、推理加速這些復(fù)雜工作。Ollama自帶了一個(gè)類似OpenAI的REST接口請(qǐng)求結(jié)構(gòu)是messages數(shù)組做過API對(duì)接的人幾乎零成本上手。相比自己用HuggingFace Transformers搭推理服務(wù)Ollama把工程部分收斂得非常干凈機(jī)器人端的代碼因此能保持輕量。模型選擇上中文對(duì)話場(chǎng)景我優(yōu)先推薦qwen2.5:7b。它在中文指令理解和多輪對(duì)話上表現(xiàn)穩(wěn)定模型體積適中量化后在消費(fèi)級(jí)顯卡上能跑得動(dòng)。如果硬件資源緊張可以降到llama3.2:3b或者qwen2.5:3b雖然復(fù)雜推理能力弱一些但日常對(duì)話、簡單指令解析足夠。如果機(jī)器人還要承擔(dān)復(fù)雜的任務(wù)規(guī)劃、結(jié)構(gòu)化輸出那就上qwen2.5:14b代價(jià)是需要更高的顯存和推理延遲。通信方式方面功能包同時(shí)考慮話題和服務(wù)兩種模式。話題適合流式對(duì)話場(chǎng)景比如語音識(shí)別節(jié)點(diǎn)持續(xù)往/chat/request發(fā)消息聊天節(jié)點(diǎn)處理后發(fā)布到/chat/response兩條通道解耦互不阻塞。服務(wù)適合那種請(qǐng)求-響應(yīng)的同步調(diào)用比如導(dǎo)航節(jié)點(diǎn)要問模型“這個(gè)目標(biāo)點(diǎn)應(yīng)該去哪個(gè)房間”模型回答后導(dǎo)航節(jié)點(diǎn)拿到結(jié)果繼續(xù)執(zhí)行。我建議功能包默認(rèn)提供話題接口同時(shí)把自定義服務(wù)接口做好兩邊都能用。1.3 功能包的整體數(shù)據(jù)流設(shè)計(jì)ollama_ros_chat的職責(zé)劃分非常明確它是ROS2世界和Ollama推理服務(wù)之間的橋。ROS2側(cè)它訂閱文本請(qǐng)求、發(fā)布文本回復(fù)Ollama側(cè)它負(fù)責(zé)組拼消息、發(fā)起HTTP調(diào)用、解析返回結(jié)果、維護(hù)多輪對(duì)話上下文。整個(gè)數(shù)據(jù)流是這樣的輸入話題 /chat/request | v ollama_chat_node 收到請(qǐng)求文本 | v 組裝 messages 歷史列表 新請(qǐng)求 | v POST 到 Ollama /api/chat 接口 | v 解析返回的 assistant 內(nèi)容 | v 寫入回復(fù)話題 /chat/response這個(gè)設(shè)計(jì)的核心好處是隔離性。機(jī)器人其他節(jié)點(diǎn)不需要知道模型叫什么、跑在哪里它們只感知“我往這個(gè)話題發(fā)一句話就會(huì)有另一句話回復(fù)回來”。上層是導(dǎo)航還是機(jī)械臂控制跟對(duì)話節(jié)點(diǎn)完全無關(guān)替換模型或者換推理后端也不會(huì)影響機(jī)器人端邏輯。2. 環(huán)境準(zhǔn)備與基礎(chǔ)依賴安裝2.1 ROS2版本與系統(tǒng)環(huán)境核對(duì)我整個(gè)功能包基于ROS2 Humble編寫對(duì)應(yīng)Ubuntu 22.04。如果你用的是Jazzy或更高版本代碼層面基本兼容主要差異在Python版本和部分依賴包版本。開始之前先確認(rèn)三個(gè)基礎(chǔ)環(huán)境系統(tǒng)是Ubuntu 22.04或24.04已經(jīng)裝好ROS2核心組件和colcon構(gòu)建工具。Python版本不低于3.10requests庫用pip install requests安裝即可。機(jī)器上至少有一個(gè)可用GPU或者CPU內(nèi)存足夠大。沒有GPU也能跑但延遲會(huì)明顯上升。驗(yàn)證ROS2環(huán)境很簡單echo $ROS_DISTRO colcon version如果$ROS_DISTRO為空說明ROS2環(huán)境沒有source先執(zhí)行source /opt/ros/humble/setup.bash。我見過不少朋友卡在這一步明明裝了ROS2但終端里找不到命令基本都是因?yàn)闆]source或者source錯(cuò)了路徑。2.2 安裝Ollama本地推理運(yùn)行時(shí)Ollama的安裝非常直接官方腳本一條命令就能完成curl -fsSL https://ollama.com/install.sh | sh安裝完成之后確認(rèn)服務(wù)能正常啟動(dòng)ollama serve正常情況下終端會(huì)監(jiān)聽127.0.0.1:11434。另外打開一個(gè)終端用ollama list查看本地已有的模型列表。如果ollama serve報(bào)端口占用說明之前已經(jīng)跑了一個(gè)實(shí)例直接用就行不需要重復(fù)啟動(dòng)。有幾個(gè)環(huán)境變量建議在部署時(shí)留意。OLLAMA_HOST控制服務(wù)監(jiān)聽地址默認(rèn)是127.0.0.1如果ROS2功能包跑在另一臺(tái)機(jī)器上需要把它改成0.0.0.0并用防火墻限定訪問范圍。OLLAMA_MAX_LOADED_MODELS限制同時(shí)加載的模型數(shù)量避免多個(gè)模型把顯存擠爆。實(shí)際部署時(shí)這些環(huán)境變量寫在systemd服務(wù)配置里比直接在命令行export更可靠。2.3 對(duì)話模型的選擇與拉取模型選擇直接決定對(duì)話效果和顯存占用這塊我給一張實(shí)測(cè)感受的參數(shù)對(duì)照表供參考模型參數(shù)量顯存占用參考INT4量化適合場(chǎng)景l(fā)lama3.2:3b3B2-3GB快速響應(yīng)、簡單指令、資源受限設(shè)備qwen2.5:3b3B2-3GB中文日常對(duì)話、低成本驗(yàn)證qwen2.5:7b7B5-6GB中文指令解析、多輪對(duì)話、結(jié)構(gòu)化輸出qwen2.5:14b14B10-12GB復(fù)雜任務(wù)規(guī)劃、較高質(zhì)量推理llama3.1:8b8B6GB左右英文場(chǎng)景、通用對(duì)話拉取模型用ollama pull比如ollama pull qwen2.5:7b拉取完成后立刻試一下推理是否正常ollama run qwen2.5:7b進(jìn)入交互界面后隨便問一句中文能正?；卦捳f明推理鏈路沒問題。這里有個(gè)重要的經(jīng)驗(yàn)首次運(yùn)行模型時(shí)Ollama需要把權(quán)重加載進(jìn)內(nèi)存耗時(shí)可能達(dá)到十幾秒甚至更久。這會(huì)影響后面ROS2功能包首次請(qǐng)求的超時(shí)設(shè)置所以我的習(xí)慣是先手動(dòng)ollama run一次讓模型預(yù)熱再啟動(dòng)功能包把這個(gè)“冷啟動(dòng)”時(shí)間消耗在聯(lián)調(diào)之前。2.4 Python依賴和工作空間準(zhǔn)備功能包本身的Python依賴很少核心就是rclpy和requests。rclpy由ROS2提供requests單獨(dú)安裝sudo apt-get install python3-requests國內(nèi)網(wǎng)絡(luò)環(huán)境下如果pip源不穩(wěn)定也可以用系統(tǒng)apt源裝版本夠用就行。不要引入額外的OpenAI SDK直接requests調(diào)Ollama接口更直觀依賴越少換機(jī)器部署時(shí)越省心。接著創(chuàng)建ROS2工作空間。假設(shè)你的工作空間目錄是~/ros2_wsmkdir -p ~/ros2_ws/src cd ~/ros2_ws colcon build source install/setup.bash先用一個(gè)空工作空間跑通colcon流程確認(rèn)構(gòu)建環(huán)境沒問題再往src里放功能包。這樣能避免把環(huán)境問題和代碼問題混在一起排查。3. 功能包結(jié)構(gòu)設(shè)計(jì)與接口定義3.1 功能包目錄結(jié)構(gòu)ollama_ros_chat采用ament_python構(gòu)建方式不涉及C編譯整個(gè)包結(jié)構(gòu)比較清爽ollama_ros_chat/ ├── package.xml ├── setup.py ├── setup.cfg ├── resource/ │ └── ollama_ros_chat ├── launch/ │ └── chat.launch.py ├── srv/ │ └── ChatRequest.srv └── ollama_ros_chat/ ├── __init__.py ├── ollama_chat_node.py └── chat_server_node.pypackage.xml里聲明包名、依賴和構(gòu)建類型。setup.py里的entry_points是關(guān)鍵它把可執(zhí)行文件名和Python模塊對(duì)應(yīng)起來ROS2靠它才能找到節(jié)點(diǎn)入口。launch目錄放啟動(dòng)文件srv目錄放自定義服務(wù)接口resource目錄是ament工具鏈的規(guī)范要求。3.2 話題接口與自定義服務(wù)設(shè)計(jì)默認(rèn)對(duì)話鏈路使用ROS2標(biāo)準(zhǔn)消息std_msgs/msg/String訂閱話題/chat/request發(fā)布話題/chat/response這樣設(shè)計(jì)的好處是開箱即用其他節(jié)點(diǎn)不需要引入自定義消息類型直接構(gòu)造一個(gè)String消息發(fā)過來就能觸發(fā)對(duì)話。對(duì)于快速聯(lián)調(diào)和原型驗(yàn)證這種簡單接口非常友好。如果要在代碼里發(fā)起同步問答可以自定義一個(gè)服務(wù)接口ChatRequest.srvstring message --- string response bool success這個(gè)服務(wù)接口的語義是“輸入一句話返回一句話和是否成功”。服務(wù)模式適合那種需要等待模型結(jié)果再執(zhí)行后續(xù)動(dòng)作的場(chǎng)景比如導(dǎo)航?jīng)Q策節(jié)點(diǎn)調(diào)用它判斷目標(biāo)點(diǎn)。實(shí)現(xiàn)服務(wù)端節(jié)點(diǎn)時(shí)注意模型推理期間會(huì)占用回調(diào)線程要給服務(wù)端配置MultiThreadedExecutor否則多個(gè)請(qǐng)求同時(shí)到達(dá)時(shí)會(huì)排隊(duì)串行。3.3 參數(shù)化設(shè)計(jì)思想我強(qiáng)烈建議把模型名、API地址、系統(tǒng)提示詞、歷史輪數(shù)全部做成ROS2參數(shù)而不是硬編碼。原因很現(xiàn)實(shí)換模型、換機(jī)器、換應(yīng)用場(chǎng)景時(shí)你只需要改launch文件里的參數(shù)代碼一行不用動(dòng)。功能包規(guī)劃了下面幾個(gè)核心參數(shù)model模型名稱比如qwen2.5:7bapi_urlOllama接口地址默認(rèn)http://127.0.0.1:11434/api/chatsystem_prompt系統(tǒng)角色提示詞決定模型的回答風(fēng)格和職責(zé)邊界history_len保留的多輪對(duì)話輪數(shù)temperature采樣溫度控制在0到1之間timeoutHTTP請(qǐng)求超時(shí)時(shí)間單位秒這套參數(shù)體系在launch文件里一鍵配置生產(chǎn)環(huán)境更換模型時(shí)只動(dòng)launch文件非常省事。4. 核心節(jié)點(diǎn)實(shí)現(xiàn)與代碼解析4.1 節(jié)點(diǎn)初始化和參數(shù)聲明對(duì)話節(jié)點(diǎn)ollama_chat_node的核心邏輯不復(fù)雜初始化階段主要做兩件事聲明參數(shù)、創(chuàng)建訂閱和發(fā)布器。有一個(gè)細(xì)節(jié)值得注意我用ThreadPoolExecutor把耗時(shí)的大模型調(diào)用丟到線程池里執(zhí)行避免模型推理期間阻塞ROS2的回調(diào)處理。import json import requests import rclpy from rclpy.node import Node from std_msgs.msg import String from concurrent.futures import ThreadPoolExecutor class OllamaChatNode(Node): def __init__(self): super().__init__(ollama_chat_node) self.declare_parameter(model, qwen2.5:7b) self.declare_parameter(api_url, http://127.0.0.1:11434/api/chat) self.declare_parameter(system_prompt, 你是一個(gè)部署在機(jī)器人上的中文助手請(qǐng)用簡潔準(zhǔn)確的語言回答用戶問題。) self.declare_parameter(history_len, 10) self.declare_parameter(temperature, 0.7) self.declare_parameter(timeout, 120.0) self.model self.get_parameter(model).value self.api_url self.get_parameter(api_url).value self.system_prompt self.get_parameter(system_prompt).value self.history_len self.get_parameter(history_len).value self.temperature self.get_parameter(temperature).value self.timeout self.get_parameter(timeout).value self.messages [{role: system, content: self.system_prompt}] self.sub self.create_subscription(String, chat/request, self.chat_callback, 10) self.pub self.create_publisher(String, chat/response, 10) self.pool ThreadPoolExecutor(max_workers2) self.get_logger().info(follama chat node started, model{self.model})ThreadPoolExecutor(max_workers2)的作用是讓模型調(diào)用不占用ROS2主線程。max_workers取2已經(jīng)夠用太多反而會(huì)增加并發(fā)壓力模型推理本來就是串行的并發(fā)請(qǐng)求也只是在排隊(duì)。4.2 訂閱回調(diào)與異步處理收到請(qǐng)求文本后回調(diào)函數(shù)把任務(wù)提交到線程池。這樣即使模型推理耗時(shí)幾十秒節(jié)點(diǎn)仍然能繼續(xù)響應(yīng)其他訂閱消息、日志和參數(shù)服務(wù)。def chat_callback(self, msg): self.get_logger().info(freceive request: {msg.data}) self.pool.submit(self._handle_chat, msg.data) def _handle_chat(self, user_text): try: reply self.call_ollama(user_text) self.pub.publish(String(datareply)) except Exception as e: self.get_logger().error(fchat error: {e}) self.pub.publish(String(dataf[error] {e}))這里要注意一個(gè)ROS2線程模型的問題。rclpy默認(rèn)的spin()是單線程模型如果回調(diào)里直接同步調(diào)用requests.post等待模型返回整個(gè)節(jié)點(diǎn)的所有回調(diào)都會(huì)卡住其他話題消息、服務(wù)請(qǐng)求全部得不到響應(yīng)。線程池方案把耗時(shí)操作放進(jìn)工作線程回調(diào)函數(shù)本身立刻返回節(jié)點(diǎn)保持流暢。發(fā)布動(dòng)作在線程池線程中執(zhí)行實(shí)測(cè)在MultiThreadedExecutor下沒問題。如果你用的是更復(fù)雜的多線程回調(diào)組還需要結(jié)合rclpy.callback_groups來做更細(xì)粒度的調(diào)度但對(duì)這個(gè)功能包的場(chǎng)景線程池方案已經(jīng)夠用了。4.3 Ollama調(diào)用與多輪上下文管理這是功能包最核心的一段邏輯。調(diào)用Ollama的/api/chat接口時(shí)請(qǐng)求體是標(biāo)準(zhǔn)的messages數(shù)組我把系統(tǒng)提示詞、歷史對(duì)話、當(dāng)前用戶輸入一起發(fā)給模型模型返回的內(nèi)容追加進(jìn)歷史形成多輪對(duì)話能力。def call_ollama(self, user_text): self.messages.append({role: user, content: user_text}) payload { model: self.model, messages: self.messages, stream: False, options: { temperature: self.temperature } } resp requests.post( self.api_url, jsonpayload, timeoutself.timeout ) resp.raise_for_status() data resp.json() reply data[message][content] self.messages.append({role: assistant, content: reply}) # 裁剪歷史防止上下文無限增長 if len(self.messages) self.history_len * 2 2: self.messages self.messages[:2] self.messages[-self.history_len * 2:] return reply上下文裁剪那段是防坑的關(guān)鍵。如果不限制歷史輪數(shù)長時(shí)間運(yùn)行后messages數(shù)組會(huì)越來越大每次請(qǐng)求的token數(shù)跟著膨脹推理延遲越來越高最終還可能超出模型的上下文窗口直接報(bào)錯(cuò)。我的裁剪策略是保留系統(tǒng)提示詞和最近history_len輪的對(duì)話把最舊的消息丟掉既控制token量又保持上下文連續(xù)性。streamFalse會(huì)讓Ollama在完整生成完畢后再返回代碼簡單但大模型生成長文本時(shí)等待時(shí)間比較久。如果你想做打字機(jī)效果可以把stream改成True用SSE流式讀取逐段輸出再通過話題增量發(fā)布體驗(yàn)會(huì)更好但代碼復(fù)雜度和話題消息管理成本明顯上升。作為第一版功能包同步返回足夠。4.4 啟動(dòng)文件與參數(shù)傳遞launch文件把參數(shù)配置和節(jié)點(diǎn)啟動(dòng)集中在一處換模型、換提示詞都從這里改from launch import LaunchDescription from launch.actions import DeclareLaunchArgument from launch.substitutions import LaunchConfiguration from launch_ros.actions import Node def generate_launch_description(): model_arg DeclareLaunchArgument(model, default_valueqwen2.5:7b) api_url_arg DeclareLaunchArgument(api_url, default_valuehttp://127.0.0.1:11434/api/chat) system_prompt_arg DeclareLaunchArgument( system_prompt, default_value你是一個(gè)部署在機(jī)器人上的中文助手請(qǐng)用簡潔準(zhǔn)確的語言回答用戶問題。 ) history_len_arg DeclareLaunchArgument(history_len, default_value10) return LaunchDescription([ model_arg, api_url_arg, system_prompt_arg, history_len_arg, Node( packageollama_ros_chat, executableollama_chat_node, nameollama_chat_node, outputscreen, parameters[{ model: LaunchConfiguration(model), api_url: LaunchConfiguration(api_url), system_prompt: LaunchConfiguration(system_prompt), history_len: LaunchConfiguration(history_len) }] ) ])outputscreen讓節(jié)點(diǎn)日志直接打到終端聯(lián)調(diào)時(shí)能實(shí)時(shí)看到請(qǐng)求和報(bào)錯(cuò)信息。注意history_len通過launch傳遞時(shí)是字符串節(jié)點(diǎn)內(nèi)部需要做類型轉(zhuǎn)換這個(gè)我在部署時(shí)踩過坑參數(shù)類型不一致會(huì)導(dǎo)致接口調(diào)用異常。5. 編譯、部署與端到端聯(lián)調(diào)5.1 構(gòu)建功能包把功能包目錄放進(jìn)工作空間src下然后執(zhí)行cd ~/ros2_ws colcon build --packages-select ollama_ros_chat source install/setup.bash--packages-select只編譯目標(biāo)包比全量編譯快很多。編譯成功后用以下命令確認(rèn)節(jié)點(diǎn)可執(zhí)行文件已經(jīng)注冊(cè)ros2 pkg executables ollama_ros_chat輸出里應(yīng)該能看到ollama_chat_node。這一步經(jīng)常有人漏掉如果entry_points配置不正確功能包能編譯但找不到節(jié)點(diǎn)入口運(yùn)行時(shí)直接報(bào)executable not found。5.2 啟動(dòng)Ollama服務(wù)和功能包啟動(dòng)前建議按順序檢查三項(xiàng)Ollama服務(wù)是否在線、模型是否已經(jīng)拉取、工作空間是否source。Ollama服務(wù)在終端跑起來之后用curl驗(yàn)證接口curl http://127.0.0.1:11434/api/tags能返回模型列表JSON就說明服務(wù)正常。接著啟動(dòng)功能包ros2 launch ollama_ros_chat chat.launch.py model:qwen2.5:7b看到類似ollama chat node started, modelqwen2.5:7b的日志說明節(jié)點(diǎn)已就緒。5.3 話題級(jí)聯(lián)調(diào)與日志驗(yàn)證開兩個(gè)新終端一個(gè)發(fā)請(qǐng)求一個(gè)收回復(fù)ros2 topic pub --once /chat/request std_msgs/msg/String {data: 你好請(qǐng)做一個(gè)簡單的自我介紹}ros2 topic echo /chat/response實(shí)際上第一次請(qǐng)求往往要等一段時(shí)間因?yàn)槟Ｐ腿绻麤]預(yù)熱Ollama要現(xiàn)場(chǎng)加載權(quán)重。等/chat/response上出現(xiàn)完整回復(fù)內(nèi)容整條鏈路就算跑通了。聯(lián)調(diào)時(shí)我還習(xí)慣用ros2 node info /ollama_chat_node查看節(jié)點(diǎn)的訂閱和發(fā)布信息確認(rèn)話題名稱、消息類型都對(duì)得上。如果發(fā)現(xiàn)回復(fù)話題一直沒消息優(yōu)先看節(jié)點(diǎn)日志有沒有報(bào)錯(cuò)而不是先懷疑網(wǎng)絡(luò)和模型。整個(gè)端到端驗(yàn)證完成后再把消息源換成真正的業(yè)務(wù)節(jié)點(diǎn)比如把語音識(shí)別結(jié)果發(fā)到/chat/request把回復(fù)發(fā)到語音合成節(jié)點(diǎn)機(jī)器人就能具備完整的對(duì)話能力了。6. 實(shí)戰(zhàn)排障高頻問題與快速排查6.1 首次請(qǐng)求超時(shí)與模型加載慢最常見的問題是功能包啟動(dòng)后發(fā)起第一次對(duì)話等了很久才回復(fù)或者直接報(bào)超時(shí)。原因是Ollama首次請(qǐng)求要先加載模型權(quán)重加載時(shí)間跟模型大小和磁盤速度強(qiáng)相關(guān)7B模型在機(jī)械硬盤上可能要半分鐘以上。解決辦法有三個(gè)層面。第一提前手動(dòng)ollama run qwen2.5:7b做一次預(yù)熱把模型加載進(jìn)內(nèi)存。第二把功能包timeout參數(shù)調(diào)大比如120秒給磁盤加載留足余量。第三如果是生產(chǎn)環(huán)境可以做一個(gè)啟動(dòng)腳本在機(jī)器人上電后先拉模型再啟動(dòng)對(duì)話節(jié)點(diǎn)避免用戶在交互時(shí)等待冷啟動(dòng)。6.2 中文亂碼與顯示異常功能包本身處理的是UTF-8字符串但終端顯示亂碼時(shí)有發(fā)生。原因通常是ROS2節(jié)點(diǎn)的日志輸出終端locale不是UTF-8。在Ubuntu Server上默認(rèn)可能沒有生成中文localeshell運(yùn)行l(wèi)ocale查看如果LANG不是zh_CN.UTF-8或en_US.UTF-8先安裝并配置sudo apt install locales sudo locale-gen en_US.UTF-8 sudo update-locale LANGen_US.UTF-8設(shè)置完locale后重啟終端亂碼問題基本能解決。另一種亂碼場(chǎng)景是消息從其他節(jié)點(diǎn)發(fā)過來時(shí)編碼已經(jīng)壞了這種情況要檢查消息來源節(jié)點(diǎn)的編碼處理問題不在對(duì)話功能包。6.3 顯存不足、OOM與CPU推理瓶頸運(yùn)行過程中報(bào)CUDA out of memory或者直接進(jìn)程被殺是顯存不足的典型表現(xiàn)。顯存占用不僅包括模型權(quán)重還包括KV Cache和推理中間張量上下文越長緩存越大。我的排查順序是用nvidia-smi看當(dāng)前顯存占用和GPU進(jìn)程。確認(rèn)沒有多個(gè)模型同時(shí)加載ollama ps查看當(dāng)前駐留模型。換更小模型或者更低量化的版本比如從7B換到3B。調(diào)整OLLAMA_MAX_LOADED_MODELS1強(qiáng)制每次只保留一個(gè)模型。沒有GPU純CPU推理時(shí)小模型還能勉強(qiáng)接受7B模型基本只能用于離線測(cè)試。實(shí)測(cè)在純CPU環(huán)境跑7B模型單次回復(fù)可能要幾分鐘這種場(chǎng)景建議直接用3B模型配合精簡的system prompt犧牲一部分質(zhì)量換取可用的延遲。6.4 阻塞問題回調(diào)卡死與并發(fā)處理如果你用的是同步調(diào)用模型的代碼結(jié)構(gòu)并且沒有做線程池處理一旦模型推理時(shí)間超過幾秒節(jié)點(diǎn)會(huì)表現(xiàn)為“卡死”日志不再輸出其他話題消息無響應(yīng)。原因是單線程spin模型中回調(diào)函數(shù)阻塞會(huì)拖住整個(gè)節(jié)點(diǎn)。排查方法是看節(jié)點(diǎn)日志如果請(qǐng)求已經(jīng)收到但后續(xù)日志長時(shí)間不出現(xiàn)基本就是阻塞了。解決方案就是第4.2節(jié)展示的線程池異步處理或者給節(jié)點(diǎn)配置rclpy.executors.MultiThreadedExecutor。如果多個(gè)業(yè)務(wù)節(jié)點(diǎn)同時(shí)向?qū)υ捁?jié)點(diǎn)發(fā)請(qǐng)求還需要在服務(wù)端實(shí)現(xiàn)請(qǐng)求隊(duì)列或者限制并發(fā)數(shù)否則大量請(qǐng)求會(huì)把Ollama壓垮。下面是幾個(gè)高頻問題的速查表現(xiàn)象優(yōu)先排查方向典型處理方式首次請(qǐng)求超時(shí)模型冷啟動(dòng)預(yù)熱模型、調(diào)大timeout回復(fù)一直為空Ollama服務(wù)未啟動(dòng)curl /api/tags驗(yàn)證服務(wù)中文亂碼locale配置設(shè)置UTF-8 locale顯存OOM模型過大或多個(gè)模型駐留換小模型、限制加載數(shù)量節(jié)點(diǎn)卡死無響應(yīng)回調(diào)阻塞使用線程池、MultiThreadedExecutor話題收不到消息話題名/QoS不匹配ros2 node info核對(duì)接口7. 后續(xù)演進(jìn)方向與擴(kuò)展建議7.1 語音交互閉環(huán)文本對(duì)話跑通之后最自然的擴(kuò)展方向就是語音。機(jī)器人端接一個(gè)本地語音識(shí)別服務(wù)把麥克風(fēng)音頻轉(zhuǎn)成文本塞進(jìn)/chat/request回復(fù)文本再交給語音合成服務(wù)發(fā)聲就能形成一個(gè)完整的語音交互閉環(huán)。注意語音識(shí)別和對(duì)話是兩條獨(dú)立的異步流語音識(shí)別結(jié)果到達(dá)的時(shí)間和頻率不可控對(duì)話節(jié)點(diǎn)本身不需要做額外改動(dòng)只需要保證消息通道暢通即可。7.2 從對(duì)話走向任務(wù)規(guī)劃與工具調(diào)用對(duì)話只是第一步真正讓大模型在機(jī)器人上有價(jià)值的是任務(wù)規(guī)劃能力。你可以讓模型輸出結(jié)構(gòu)化的指令JSON比如導(dǎo)航目標(biāo)點(diǎn)、機(jī)械臂抓取動(dòng)作參數(shù)然后由機(jī)器人側(cè)解析這個(gè)JSON并執(zhí)行。當(dāng)前大模型普遍支持函數(shù)調(diào)用格式Ollama也提供了工具調(diào)用能力把可用機(jī)器人能力以工具函數(shù)的形式提供給模型模型在回答中“選擇調(diào)用”某個(gè)工具這比單純讓模型輸出自由文本再解析要穩(wěn)定得多。我之前在模擬項(xiàng)目X里測(cè)試過這種模式模型根據(jù)“把桌子上的紅色杯子拿過來”這句指令輸出調(diào)用目標(biāo)識(shí)別和機(jī)械臂規(guī)劃的JSON效果雖然做不到完全可靠但配合簡單的校驗(yàn)和重試機(jī)制已經(jīng)能完成不少受限場(chǎng)景的操控任務(wù)。7.3 多模態(tài)輸入與視覺能力如果要讓機(jī)器人能“看懂”周圍環(huán)境可以把視覺語言模型接進(jìn)這個(gè)架構(gòu)。Ollama支持多模態(tài)模型比如llava系列對(duì)話請(qǐng)求里不僅包含文本還可以攜帶圖像數(shù)據(jù)。真實(shí)場(chǎng)景中機(jī)器人先通過攝像頭采集畫面壓縮到合理尺寸再發(fā)給視覺語言模型讓它描述場(chǎng)景內(nèi)容或者回答關(guān)于畫面中的問題。多模態(tài)的接入點(diǎn)依然是/chat/request只是請(qǐng)求內(nèi)容從純文本變成文本加圖像引用通信架構(gòu)不需要大改。我在實(shí)際部署中有一個(gè)很強(qiáng)烈的體會(huì)先別貪大別一上來就追求對(duì)話質(zhì)量或者復(fù)雜任務(wù)規(guī)劃。用3B或者7B小模型把整條鏈路跑通讓機(jī)器人能穩(wěn)定地用話題跟大模型對(duì)話然后再逐步替換模型、增加功能。很多項(xiàng)目最后做不下去不是因?yàn)槟Ｐ筒粔驈?qiáng)而是基礎(chǔ)鏈路不穩(wěn)定一個(gè)問題套一個(gè)問題根本沒法往下迭代。另外所有參數(shù)盡量走launch文件模型名、API地址、system prompt都不要硬編碼。我當(dāng)時(shí)為了省事寫過一版寫死參數(shù)的代碼結(jié)果換個(gè)機(jī)器人就要改一次源碼改到后面自己都想笑。把這個(gè)經(jīng)驗(yàn)分享出來就是希望大家少走這段彎路。 ROS2機(jī)器人接入Ollama本地大模型：對(duì)話功能包完整實(shí)戰(zhàn)
把大語言模型接進(jìn)ROS2機(jī)器人這兩年討論熱度一直很高。但你翻看網(wǎng)上的教程會(huì)發(fā)現(xiàn)大部分內(nèi)容要么停留在概念圖要么只講ROS2基礎(chǔ)的話題收發(fā)真正把Ollama這種本地推理服務(wù)、對(duì)話模型和機(jī)器人通信串成一個(gè)可運(yùn)行功能包的實(shí)操文章非常少。這篇就以ollama_ros_chat功能包為線索把部署和使用整條線拆開講環(huán)境怎么配、功能包怎么建、代碼怎么寫、模型怎么選、聯(lián)調(diào)怎么排坑最后落到你能直接在自己工作空間里跑起來的狀態(tài)。這套方案解決的是很具體的工程問題機(jī)器人端不想依賴云端API對(duì)話數(shù)據(jù)希望留在本地同時(shí)又要能通過ROS2標(biāo)準(zhǔn)話題或服務(wù)被其他節(jié)點(diǎn)調(diào)用。它特別適合正在做輪式底盤、桌面機(jī)械臂、導(dǎo)覽機(jī)器人或者單純想把一個(gè)可對(duì)話的本地大模型裝進(jìn)自己ROS2環(huán)境里驗(yàn)證一下的開發(fā)者。大模型原理不用懂太多只要能照著敲命令、改參數(shù)就能在半小時(shí)內(nèi)把鏈路跑通后面再慢慢往業(yè)務(wù)場(chǎng)景上擴(kuò)展。1. 整體定位與方案設(shè)計(jì)思路1.1 為什么要在機(jī)器人上接本地大模型做機(jī)器人項(xiàng)目時(shí)語音助手、自然語言指令解析這些需求其實(shí)一直存在但過去實(shí)現(xiàn)成本很高。傳統(tǒng)做法是寫一堆規(guī)則匹配用關(guān)鍵詞模板把用戶指令映射成機(jī)器人動(dòng)作維護(hù)起來特別痛苦。只要用戶換一種問法規(guī)則就要補(bǔ)一條而且永遠(yuǎn)補(bǔ)不完。引入大模型之后自然語言理解這部分直接被通用模型接住了開發(fā)者可以把精力放在指令執(zhí)行和業(yè)務(wù)邏輯上。選擇本地部署而不是調(diào)用云端API我主要基于三個(gè)原因。第一是隱私與數(shù)據(jù)邊界機(jī)器人經(jīng)常運(yùn)行在室內(nèi)環(huán)境或者園區(qū)場(chǎng)景采集到的對(duì)話內(nèi)容可能包含具體的環(huán)境信息如果每句話都傳到云端數(shù)據(jù)歸屬和合規(guī)上很難講清楚。第二是網(wǎng)絡(luò)穩(wěn)定性機(jī)器人在運(yùn)行過程中無法保證任何時(shí)候都有可靠網(wǎng)絡(luò)尤其是移動(dòng)底盤在樓道、地下空間這種弱信號(hào)區(qū)域云端方案一旦斷線整個(gè)交互就崩了。第三是延遲和成本高頻的短對(duì)話如果全部走云端單次調(diào)用雖然便宜積累起來也是一筆開銷而本地推理跑起來之后完全可控。用本地大模型還有一個(gè)容易被忽略的好處調(diào)試體驗(yàn)完全不同。你可以直接在終端看模型的完整輸出改提示詞、調(diào)參數(shù)都是本地即時(shí)生效不需要經(jīng)過云端接口的審核和網(wǎng)絡(luò)往返。對(duì)于做原型驗(yàn)證和教學(xué)演示來說這種“所見即所得”的反饋速度比什么都重要。1.2 方案選型推理運(yùn)行時(shí)、模型和通信方式怎么定本地推理運(yùn)行時(shí)我最終選了Ollama原因很實(shí)在。它能用一條命令把模型拉下來然后直接用HTTP接口提供服務(wù)開發(fā)者完全不用接觸底層的模型權(quán)重管理、量化轉(zhuǎn)換、推理加速這些復(fù)雜工作。Ollama自帶了一個(gè)類似OpenAI的REST接口請(qǐng)求結(jié)構(gòu)是messages數(shù)組做過API對(duì)接的人幾乎零成本上手。相比自己用HuggingFace Transformers搭推理服務(wù)Ollama把工程部分收斂得非常干凈機(jī)器人端的代碼因此能保持輕量。模型選擇上中文對(duì)話場(chǎng)景我優(yōu)先推薦qwen2.5:7b。它在中文指令理解和多輪對(duì)話上表現(xiàn)穩(wěn)定模型體積適中量化后在消費(fèi)級(jí)顯卡上能跑得動(dòng)。如果硬件資源緊張可以降到llama3.2:3b或者qwen2.5:3b雖然復(fù)雜推理能力弱一些但日常對(duì)話、簡單指令解析足夠。如果機(jī)器人還要承擔(dān)復(fù)雜的任務(wù)規(guī)劃、結(jié)構(gòu)化輸出那就上qwen2.5:14b代價(jià)是需要更高的顯存和推理延遲。通信方式方面功能包同時(shí)考慮話題和服務(wù)兩種模式。話題適合流式對(duì)話場(chǎng)景比如語音識(shí)別節(jié)點(diǎn)持續(xù)往/chat/request發(fā)消息聊天節(jié)點(diǎn)處理后發(fā)布到/chat/response兩條通道解耦互不阻塞。服務(wù)適合那種請(qǐng)求-響應(yīng)的同步調(diào)用比如導(dǎo)航節(jié)點(diǎn)要問模型“這個(gè)目標(biāo)點(diǎn)應(yīng)該去哪個(gè)房間”模型回答后導(dǎo)航節(jié)點(diǎn)拿到結(jié)果繼續(xù)執(zhí)行。我建議功能包默認(rèn)提供話題接口同時(shí)把自定義服務(wù)接口做好兩邊都能用。1.3 功能包的整體數(shù)據(jù)流設(shè)計(jì)ollama_ros_chat的職責(zé)劃分非常明確它是ROS2世界和Ollama推理服務(wù)之間的橋。ROS2側(cè)它訂閱文本請(qǐng)求、發(fā)布文本回復(fù)Ollama側(cè)它負(fù)責(zé)組拼消息、發(fā)起HTTP調(diào)用、解析返回結(jié)果、維護(hù)多輪對(duì)話上下文。整個(gè)數(shù)據(jù)流是這樣的輸入話題 /chat/request | v ollama_chat_node 收到請(qǐng)求文本 | v 組裝 messages 歷史列表 新請(qǐng)求 | v POST 到 Ollama /api/chat 接口 | v 解析返回的 assistant 內(nèi)容 | v 寫入回復(fù)話題 /chat/response這個(gè)設(shè)計(jì)的核心好處是隔離性。機(jī)器人其他節(jié)點(diǎn)不需要知道模型叫什么、跑在哪里它們只感知“我往這個(gè)話題發(fā)一句話就會(huì)有另一句話回復(fù)回來”。上層是導(dǎo)航還是機(jī)械臂控制跟對(duì)話節(jié)點(diǎn)完全無關(guān)替換模型或者換推理后端也不會(huì)影響機(jī)器人端邏輯。2. 環(huán)境準(zhǔn)備與基礎(chǔ)依賴安裝2.1 ROS2版本與系統(tǒng)環(huán)境核對(duì)我整個(gè)功能包基于ROS2 Humble編寫對(duì)應(yīng)Ubuntu 22.04。如果你用的是Jazzy或更高版本代碼層面基本兼容主要差異在Python版本和部分依賴包版本。開始之前先確認(rèn)三個(gè)基礎(chǔ)環(huán)境系統(tǒng)是Ubuntu 22.04或24.04已經(jīng)裝好ROS2核心組件和colcon構(gòu)建工具。Python版本不低于3.10requests庫用pip install requests安裝即可。機(jī)器上至少有一個(gè)可用GPU或者CPU內(nèi)存足夠大。沒有GPU也能跑但延遲會(huì)明顯上升。驗(yàn)證ROS2環(huán)境很簡單echo $ROS_DISTRO colcon version如果$ROS_DISTRO為空說明ROS2環(huán)境沒有source先執(zhí)行source /opt/ros/humble/setup.bash。我見過不少朋友卡在這一步明明裝了ROS2但終端里找不到命令基本都是因?yàn)闆]source或者source錯(cuò)了路徑。2.2 安裝Ollama本地推理運(yùn)行時(shí)Ollama的安裝非常直接官方腳本一條命令就能完成curl -fsSL https://ollama.com/install.sh | sh安裝完成之后確認(rèn)服務(wù)能正常啟動(dòng)ollama serve正常情況下終端會(huì)監(jiān)聽127.0.0.1:11434。另外打開一個(gè)終端用ollama list查看本地已有的模型列表。如果ollama serve報(bào)端口占用說明之前已經(jīng)跑了一個(gè)實(shí)例直接用就行不需要重復(fù)啟動(dòng)。有幾個(gè)環(huán)境變量建議在部署時(shí)留意。OLLAMA_HOST控制服務(wù)監(jiān)聽地址默認(rèn)是127.0.0.1如果ROS2功能包跑在另一臺(tái)機(jī)器上需要把它改成0.0.0.0并用防火墻限定訪問范圍。OLLAMA_MAX_LOADED_MODELS限制同時(shí)加載的模型數(shù)量避免多個(gè)模型把顯存擠爆。實(shí)際部署時(shí)這些環(huán)境變量寫在systemd服務(wù)配置里比直接在命令行export更可靠。2.3 對(duì)話模型的選擇與拉取模型選擇直接決定對(duì)話效果和顯存占用這塊我給一張實(shí)測(cè)感受的參數(shù)對(duì)照表供參考模型參數(shù)量顯存占用參考INT4量化適合場(chǎng)景l(fā)lama3.2:3b3B2-3GB快速響應(yīng)、簡單指令、資源受限設(shè)備qwen2.5:3b3B2-3GB中文日常對(duì)話、低成本驗(yàn)證qwen2.5:7b7B5-6GB中文指令解析、多輪對(duì)話、結(jié)構(gòu)化輸出qwen2.5:14b14B10-12GB復(fù)雜任務(wù)規(guī)劃、較高質(zhì)量推理llama3.1:8b8B6GB左右英文場(chǎng)景、通用對(duì)話拉取模型用ollama pull比如ollama pull qwen2.5:7b拉取完成后立刻試一下推理是否正常ollama run qwen2.5:7b進(jìn)入交互界面后隨便問一句中文能正?；卦捳f明推理鏈路沒問題。這里有個(gè)重要的經(jīng)驗(yàn)首次運(yùn)行模型時(shí)Ollama需要把權(quán)重加載進(jìn)內(nèi)存耗時(shí)可能達(dá)到十幾秒甚至更久。這會(huì)影響后面ROS2功能包首次請(qǐng)求的超時(shí)設(shè)置所以我的習(xí)慣是先手動(dòng)ollama run一次讓模型預(yù)熱再啟動(dòng)功能包把這個(gè)“冷啟動(dòng)”時(shí)間消耗在聯(lián)調(diào)之前。2.4 Python依賴和工作空間準(zhǔn)備功能包本身的Python依賴很少核心就是rclpy和requests。rclpy由ROS2提供requests單獨(dú)安裝sudo apt-get install python3-requests國內(nèi)網(wǎng)絡(luò)環(huán)境下如果pip源不穩(wěn)定也可以用系統(tǒng)apt源裝版本夠用就行。不要引入額外的OpenAI SDK直接requests調(diào)Ollama接口更直觀依賴越少換機(jī)器部署時(shí)越省心。接著創(chuàng)建ROS2工作空間。假設(shè)你的工作空間目錄是~/ros2_wsmkdir -p ~/ros2_ws/src cd ~/ros2_ws colcon build source install/setup.bash先用一個(gè)空工作空間跑通colcon流程確認(rèn)構(gòu)建環(huán)境沒問題再往src里放功能包。這樣能避免把環(huán)境問題和代碼問題混在一起排查。3. 功能包結(jié)構(gòu)設(shè)計(jì)與接口定義3.1 功能包目錄結(jié)構(gòu)ollama_ros_chat采用ament_python構(gòu)建方式不涉及C編譯整個(gè)包結(jié)構(gòu)比較清爽ollama_ros_chat/ ├── package.xml ├── setup.py ├── setup.cfg ├── resource/ │ └── ollama_ros_chat ├── launch/ │ └── chat.launch.py ├── srv/ │ └── ChatRequest.srv └── ollama_ros_chat/ ├── __init__.py ├── ollama_chat_node.py └── chat_server_node.pypackage.xml里聲明包名、依賴和構(gòu)建類型。setup.py里的entry_points是關(guān)鍵它把可執(zhí)行文件名和Python模塊對(duì)應(yīng)起來ROS2靠它才能找到節(jié)點(diǎn)入口。launch目錄放啟動(dòng)文件srv目錄放自定義服務(wù)接口resource目錄是ament工具鏈的規(guī)范要求。3.2 話題接口與自定義服務(wù)設(shè)計(jì)默認(rèn)對(duì)話鏈路使用ROS2標(biāo)準(zhǔn)消息std_msgs/msg/String訂閱話題/chat/request發(fā)布話題/chat/response這樣設(shè)計(jì)的好處是開箱即用其他節(jié)點(diǎn)不需要引入自定義消息類型直接構(gòu)造一個(gè)String消息發(fā)過來就能觸發(fā)對(duì)話。對(duì)于快速聯(lián)調(diào)和原型驗(yàn)證這種簡單接口非常友好。如果要在代碼里發(fā)起同步問答可以自定義一個(gè)服務(wù)接口ChatRequest.srvstring message --- string response bool success這個(gè)服務(wù)接口的語義是“輸入一句話返回一句話和是否成功”。服務(wù)模式適合那種需要等待模型結(jié)果再執(zhí)行后續(xù)動(dòng)作的場(chǎng)景比如導(dǎo)航?jīng)Q策節(jié)點(diǎn)調(diào)用它判斷目標(biāo)點(diǎn)。實(shí)現(xiàn)服務(wù)端節(jié)點(diǎn)時(shí)注意模型推理期間會(huì)占用回調(diào)線程要給服務(wù)端配置MultiThreadedExecutor否則多個(gè)請(qǐng)求同時(shí)到達(dá)時(shí)會(huì)排隊(duì)串行。3.3 參數(shù)化設(shè)計(jì)思想我強(qiáng)烈建議把模型名、API地址、系統(tǒng)提示詞、歷史輪數(shù)全部做成ROS2參數(shù)而不是硬編碼。原因很現(xiàn)實(shí)換模型、換機(jī)器、換應(yīng)用場(chǎng)景時(shí)你只需要改launch文件里的參數(shù)代碼一行不用動(dòng)。功能包規(guī)劃了下面幾個(gè)核心參數(shù)model模型名稱比如qwen2.5:7bapi_urlOllama接口地址默認(rèn)http://127.0.0.1:11434/api/chatsystem_prompt系統(tǒng)角色提示詞決定模型的回答風(fēng)格和職責(zé)邊界history_len保留的多輪對(duì)話輪數(shù)temperature采樣溫度控制在0到1之間timeoutHTTP請(qǐng)求超時(shí)時(shí)間單位秒這套參數(shù)體系在launch文件里一鍵配置生產(chǎn)環(huán)境更換模型時(shí)只動(dòng)launch文件非常省事。4. 核心節(jié)點(diǎn)實(shí)現(xiàn)與代碼解析4.1 節(jié)點(diǎn)初始化和參數(shù)聲明對(duì)話節(jié)點(diǎn)ollama_chat_node的核心邏輯不復(fù)雜初始化階段主要做兩件事聲明參數(shù)、創(chuàng)建訂閱和發(fā)布器。有一個(gè)細(xì)節(jié)值得注意我用ThreadPoolExecutor把耗時(shí)的大模型調(diào)用丟到線程池里執(zhí)行避免模型推理期間阻塞ROS2的回調(diào)處理。import json import requests import rclpy from rclpy.node import Node from std_msgs.msg import String from concurrent.futures import ThreadPoolExecutor class OllamaChatNode(Node): def __init__(self): super().__init__(ollama_chat_node) self.declare_parameter(model, qwen2.5:7b) self.declare_parameter(api_url, http://127.0.0.1:11434/api/chat) self.declare_parameter(system_prompt, 你是一個(gè)部署在機(jī)器人上的中文助手請(qǐng)用簡潔準(zhǔn)確的語言回答用戶問題。) self.declare_parameter(history_len, 10) self.declare_parameter(temperature, 0.7) self.declare_parameter(timeout, 120.0) self.model self.get_parameter(model).value self.api_url self.get_parameter(api_url).value self.system_prompt self.get_parameter(system_prompt).value self.history_len self.get_parameter(history_len).value self.temperature self.get_parameter(temperature).value self.timeout self.get_parameter(timeout).value self.messages [{role: system, content: self.system_prompt}] self.sub self.create_subscription(String, chat/request, self.chat_callback, 10) self.pub self.create_publisher(String, chat/response, 10) self.pool ThreadPoolExecutor(max_workers2) self.get_logger().info(follama chat node started, model{self.model})ThreadPoolExecutor(max_workers2)的作用是讓模型調(diào)用不占用ROS2主線程。max_workers取2已經(jīng)夠用太多反而會(huì)增加并發(fā)壓力模型推理本來就是串行的并發(fā)請(qǐng)求也只是在排隊(duì)。4.2 訂閱回調(diào)與異步處理收到請(qǐng)求文本后回調(diào)函數(shù)把任務(wù)提交到線程池。這樣即使模型推理耗時(shí)幾十秒節(jié)點(diǎn)仍然能繼續(xù)響應(yīng)其他訂閱消息、日志和參數(shù)服務(wù)。def chat_callback(self, msg): self.get_logger().info(freceive request: {msg.data}) self.pool.submit(self._handle_chat, msg.data) def _handle_chat(self, user_text): try: reply self.call_ollama(user_text) self.pub.publish(String(datareply)) except Exception as e: self.get_logger().error(fchat error: {e}) self.pub.publish(String(dataf[error] {e}))這里要注意一個(gè)ROS2線程模型的問題。rclpy默認(rèn)的spin()是單線程模型如果回調(diào)里直接同步調(diào)用requests.post等待模型返回整個(gè)節(jié)點(diǎn)的所有回調(diào)都會(huì)卡住其他話題消息、服務(wù)請(qǐng)求全部得不到響應(yīng)。線程池方案把耗時(shí)操作放進(jìn)工作線程回調(diào)函數(shù)本身立刻返回節(jié)點(diǎn)保持流暢。發(fā)布動(dòng)作在線程池線程中執(zhí)行實(shí)測(cè)在MultiThreadedExecutor下沒問題。如果你用的是更復(fù)雜的多線程回調(diào)組還需要結(jié)合rclpy.callback_groups來做更細(xì)粒度的調(diào)度但對(duì)這個(gè)功能包的場(chǎng)景線程池方案已經(jīng)夠用了。4.3 Ollama調(diào)用與多輪上下文管理這是功能包最核心的一段邏輯。調(diào)用Ollama的/api/chat接口時(shí)請(qǐng)求體是標(biāo)準(zhǔn)的messages數(shù)組我把系統(tǒng)提示詞、歷史對(duì)話、當(dāng)前用戶輸入一起發(fā)給模型模型返回的內(nèi)容追加進(jìn)歷史形成多輪對(duì)話能力。def call_ollama(self, user_text): self.messages.append({role: user, content: user_text}) payload { model: self.model, messages: self.messages, stream: False, options: { temperature: self.temperature } } resp requests.post( self.api_url, jsonpayload, timeoutself.timeout ) resp.raise_for_status() data resp.json() reply data[message][content] self.messages.append({role: assistant, content: reply}) # 裁剪歷史防止上下文無限增長 if len(self.messages) self.history_len * 2 2: self.messages self.messages[:2] self.messages[-self.history_len * 2:] return reply上下文裁剪那段是防坑的關(guān)鍵。如果不限制歷史輪數(shù)長時(shí)間運(yùn)行后messages數(shù)組會(huì)越來越大每次請(qǐng)求的token數(shù)跟著膨脹推理延遲越來越高最終還可能超出模型的上下文窗口直接報(bào)錯(cuò)。我的裁剪策略是保留系統(tǒng)提示詞和最近history_len輪的對(duì)話把最舊的消息丟掉既控制token量又保持上下文連續(xù)性。streamFalse會(huì)讓Ollama在完整生成完畢后再返回代碼簡單但大模型生成長文本時(shí)等待時(shí)間比較久。如果你想做打字機(jī)效果可以把stream改成True用SSE流式讀取逐段輸出再通過話題增量發(fā)布體驗(yàn)會(huì)更好但代碼復(fù)雜度和話題消息管理成本明顯上升。作為第一版功能包同步返回足夠。4.4 啟動(dòng)文件與參數(shù)傳遞launch文件把參數(shù)配置和節(jié)點(diǎn)啟動(dòng)集中在一處換模型、換提示詞都從這里改from launch import LaunchDescription from launch.actions import DeclareLaunchArgument from launch.substitutions import LaunchConfiguration from launch_ros.actions import Node def generate_launch_description(): model_arg DeclareLaunchArgument(model, default_valueqwen2.5:7b) api_url_arg DeclareLaunchArgument(api_url, default_valuehttp://127.0.0.1:11434/api/chat) system_prompt_arg DeclareLaunchArgument( system_prompt, default_value你是一個(gè)部署在機(jī)器人上的中文助手請(qǐng)用簡潔準(zhǔn)確的語言回答用戶問題。 ) history_len_arg DeclareLaunchArgument(history_len, default_value10) return LaunchDescription([ model_arg, api_url_arg, system_prompt_arg, history_len_arg, Node( packageollama_ros_chat, executableollama_chat_node, nameollama_chat_node, outputscreen, parameters[{ model: LaunchConfiguration(model), api_url: LaunchConfiguration(api_url), system_prompt: LaunchConfiguration(system_prompt), history_len: LaunchConfiguration(history_len) }] ) ])outputscreen讓節(jié)點(diǎn)日志直接打到終端聯(lián)調(diào)時(shí)能實(shí)時(shí)看到請(qǐng)求和報(bào)錯(cuò)信息。注意history_len通過launch傳遞時(shí)是字符串節(jié)點(diǎn)內(nèi)部需要做類型轉(zhuǎn)換這個(gè)我在部署時(shí)踩過坑參數(shù)類型不一致會(huì)導(dǎo)致接口調(diào)用異常。5. 編譯、部署與端到端聯(lián)調(diào)5.1 構(gòu)建功能包把功能包目錄放進(jìn)工作空間src下然后執(zhí)行cd ~/ros2_ws colcon build --packages-select ollama_ros_chat source install/setup.bash--packages-select只編譯目標(biāo)包比全量編譯快很多。編譯成功后用以下命令確認(rèn)節(jié)點(diǎn)可執(zhí)行文件已經(jīng)注冊(cè)ros2 pkg executables ollama_ros_chat輸出里應(yīng)該能看到ollama_chat_node。這一步經(jīng)常有人漏掉如果entry_points配置不正確功能包能編譯但找不到節(jié)點(diǎn)入口運(yùn)行時(shí)直接報(bào)executable not found。5.2 啟動(dòng)Ollama服務(wù)和功能包啟動(dòng)前建議按順序檢查三項(xiàng)Ollama服務(wù)是否在線、模型是否已經(jīng)拉取、工作空間是否source。Ollama服務(wù)在終端跑起來之后用curl驗(yàn)證接口curl http://127.0.0.1:11434/api/tags能返回模型列表JSON就說明服務(wù)正常。接著啟動(dòng)功能包ros2 launch ollama_ros_chat chat.launch.py model:qwen2.5:7b看到類似ollama chat node started, modelqwen2.5:7b的日志說明節(jié)點(diǎn)已就緒。5.3 話題級(jí)聯(lián)調(diào)與日志驗(yàn)證開兩個(gè)新終端一個(gè)發(fā)請(qǐng)求一個(gè)收回復(fù)ros2 topic pub --once /chat/request std_msgs/msg/String {data: 你好請(qǐng)做一個(gè)簡單的自我介紹}ros2 topic echo /chat/response實(shí)際上第一次請(qǐng)求往往要等一段時(shí)間因?yàn)槟Ｐ腿绻麤]預(yù)熱Ollama要現(xiàn)場(chǎng)加載權(quán)重。等/chat/response上出現(xiàn)完整回復(fù)內(nèi)容整條鏈路就算跑通了。聯(lián)調(diào)時(shí)我還習(xí)慣用ros2 node info /ollama_chat_node查看節(jié)點(diǎn)的訂閱和發(fā)布信息確認(rèn)話題名稱、消息類型都對(duì)得上。如果發(fā)現(xiàn)回復(fù)話題一直沒消息優(yōu)先看節(jié)點(diǎn)日志有沒有報(bào)錯(cuò)而不是先懷疑網(wǎng)絡(luò)和模型。整個(gè)端到端驗(yàn)證完成后再把消息源換成真正的業(yè)務(wù)節(jié)點(diǎn)比如把語音識(shí)別結(jié)果發(fā)到/chat/request把回復(fù)發(fā)到語音合成節(jié)點(diǎn)機(jī)器人就能具備完整的對(duì)話能力了。6. 實(shí)戰(zhàn)排障高頻問題與快速排查6.1 首次請(qǐng)求超時(shí)與模型加載慢最常見的問題是功能包啟動(dòng)后發(fā)起第一次對(duì)話等了很久才回復(fù)或者直接報(bào)超時(shí)。原因是Ollama首次請(qǐng)求要先加載模型權(quán)重加載時(shí)間跟模型大小和磁盤速度強(qiáng)相關(guān)7B模型在機(jī)械硬盤上可能要半分鐘以上。解決辦法有三個(gè)層面。第一提前手動(dòng)ollama run qwen2.5:7b做一次預(yù)熱把模型加載進(jìn)內(nèi)存。第二把功能包timeout參數(shù)調(diào)大比如120秒給磁盤加載留足余量。第三如果是生產(chǎn)環(huán)境可以做一個(gè)啟動(dòng)腳本在機(jī)器人上電后先拉模型再啟動(dòng)對(duì)話節(jié)點(diǎn)避免用戶在交互時(shí)等待冷啟動(dòng)。6.2 中文亂碼與顯示異常功能包本身處理的是UTF-8字符串但終端顯示亂碼時(shí)有發(fā)生。原因通常是ROS2節(jié)點(diǎn)的日志輸出終端locale不是UTF-8。在Ubuntu Server上默認(rèn)可能沒有生成中文localeshell運(yùn)行l(wèi)ocale查看如果LANG不是zh_CN.UTF-8或en_US.UTF-8先安裝并配置sudo apt install locales sudo locale-gen en_US.UTF-8 sudo update-locale LANGen_US.UTF-8設(shè)置完locale后重啟終端亂碼問題基本能解決。另一種亂碼場(chǎng)景是消息從其他節(jié)點(diǎn)發(fā)過來時(shí)編碼已經(jīng)壞了這種情況要檢查消息來源節(jié)點(diǎn)的編碼處理問題不在對(duì)話功能包。6.3 顯存不足、OOM與CPU推理瓶頸運(yùn)行過程中報(bào)CUDA out of memory或者直接進(jìn)程被殺是顯存不足的典型表現(xiàn)。顯存占用不僅包括模型權(quán)重還包括KV Cache和推理中間張量上下文越長緩存越大。我的排查順序是用nvidia-smi看當(dāng)前顯存占用和GPU進(jìn)程。確認(rèn)沒有多個(gè)模型同時(shí)加載ollama ps查看當(dāng)前駐留模型。換更小模型或者更低量化的版本比如從7B換到3B。調(diào)整OLLAMA_MAX_LOADED_MODELS1強(qiáng)制每次只保留一個(gè)模型。沒有GPU純CPU推理時(shí)小模型還能勉強(qiáng)接受7B模型基本只能用于離線測(cè)試。實(shí)測(cè)在純CPU環(huán)境跑7B模型單次回復(fù)可能要幾分鐘這種場(chǎng)景建議直接用3B模型配合精簡的system prompt犧牲一部分質(zhì)量換取可用的延遲。6.4 阻塞問題回調(diào)卡死與并發(fā)處理如果你用的是同步調(diào)用模型的代碼結(jié)構(gòu)并且沒有做線程池處理一旦模型推理時(shí)間超過幾秒節(jié)點(diǎn)會(huì)表現(xiàn)為“卡死”日志不再輸出其他話題消息無響應(yīng)。原因是單線程spin模型中回調(diào)函數(shù)阻塞會(huì)拖住整個(gè)節(jié)點(diǎn)。排查方法是看節(jié)點(diǎn)日志如果請(qǐng)求已經(jīng)收到但后續(xù)日志長時(shí)間不出現(xiàn)基本就是阻塞了。解決方案就是第4.2節(jié)展示的線程池異步處理或者給節(jié)點(diǎn)配置rclpy.executors.MultiThreadedExecutor。如果多個(gè)業(yè)務(wù)節(jié)點(diǎn)同時(shí)向?qū)υ捁?jié)點(diǎn)發(fā)請(qǐng)求還需要在服務(wù)端實(shí)現(xiàn)請(qǐng)求隊(duì)列或者限制并發(fā)數(shù)否則大量請(qǐng)求會(huì)把Ollama壓垮。下面是幾個(gè)高頻問題的速查表現(xiàn)象優(yōu)先排查方向典型處理方式首次請(qǐng)求超時(shí)模型冷啟動(dòng)預(yù)熱模型、調(diào)大timeout回復(fù)一直為空Ollama服務(wù)未啟動(dòng)curl /api/tags驗(yàn)證服務(wù)中文亂碼locale配置設(shè)置UTF-8 locale顯存OOM模型過大或多個(gè)模型駐留換小模型、限制加載數(shù)量節(jié)點(diǎn)卡死無響應(yīng)回調(diào)阻塞使用線程池、MultiThreadedExecutor話題收不到消息話題名/QoS不匹配ros2 node info核對(duì)接口7. 后續(xù)演進(jìn)方向與擴(kuò)展建議7.1 語音交互閉環(huán)文本對(duì)話跑通之后最自然的擴(kuò)展方向就是語音。機(jī)器人端接一個(gè)本地語音識(shí)別服務(wù)把麥克風(fēng)音頻轉(zhuǎn)成文本塞進(jìn)/chat/request回復(fù)文本再交給語音合成服務(wù)發(fā)聲就能形成一個(gè)完整的語音交互閉環(huán)。注意語音識(shí)別和對(duì)話是兩條獨(dú)立的異步流語音識(shí)別結(jié)果到達(dá)的時(shí)間和頻率不可控對(duì)話節(jié)點(diǎn)本身不需要做額外改動(dòng)只需要保證消息通道暢通即可。7.2 從對(duì)話走向任務(wù)規(guī)劃與工具調(diào)用對(duì)話只是第一步真正讓大模型在機(jī)器人上有價(jià)值的是任務(wù)規(guī)劃能力。你可以讓模型輸出結(jié)構(gòu)化的指令JSON比如導(dǎo)航目標(biāo)點(diǎn)、機(jī)械臂抓取動(dòng)作參數(shù)然后由機(jī)器人側(cè)解析這個(gè)JSON并執(zhí)行。當(dāng)前大模型普遍支持函數(shù)調(diào)用格式Ollama也提供了工具調(diào)用能力把可用機(jī)器人能力以工具函數(shù)的形式提供給模型模型在回答中“選擇調(diào)用”某個(gè)工具這比單純讓模型輸出自由文本再解析要穩(wěn)定得多。我之前在模擬項(xiàng)目X里測(cè)試過這種模式模型根據(jù)“把桌子上的紅色杯子拿過來”這句指令輸出調(diào)用目標(biāo)識(shí)別和機(jī)械臂規(guī)劃的JSON效果雖然做不到完全可靠但配合簡單的校驗(yàn)和重試機(jī)制已經(jīng)能完成不少受限場(chǎng)景的操控任務(wù)。7.3 多模態(tài)輸入與視覺能力如果要讓機(jī)器人能“看懂”周圍環(huán)境可以把視覺語言模型接進(jìn)這個(gè)架構(gòu)。Ollama支持多模態(tài)模型比如llava系列對(duì)話請(qǐng)求里不僅包含文本還可以攜帶圖像數(shù)據(jù)。真實(shí)場(chǎng)景中機(jī)器人先通過攝像頭采集畫面壓縮到合理尺寸再發(fā)給視覺語言模型讓它描述場(chǎng)景內(nèi)容或者回答關(guān)于畫面中的問題。多模態(tài)的接入點(diǎn)依然是/chat/request只是請(qǐng)求內(nèi)容從純文本變成文本加圖像引用通信架構(gòu)不需要大改。我在實(shí)際部署中有一個(gè)很強(qiáng)烈的體會(huì)先別貪大別一上來就追求對(duì)話質(zhì)量或者復(fù)雜任務(wù)規(guī)劃。用3B或者7B小模型把整條鏈路跑通讓機(jī)器人能穩(wěn)定地用話題跟大模型對(duì)話然后再逐步替換模型、增加功能。很多項(xiàng)目最后做不下去不是因?yàn)槟Ｐ筒粔驈?qiáng)而是基礎(chǔ)鏈路不穩(wěn)定一個(gè)問題套一個(gè)問題根本沒法往下迭代。另外所有參數(shù)盡量走launch文件模型名、API地址、system prompt都不要硬編碼。我當(dāng)時(shí)為了省事寫過一版寫死參數(shù)的代碼結(jié)果換個(gè)機(jī)器人就要改一次源碼改到后面自己都想笑。把這個(gè)經(jīng)驗(yàn)分享出來就是希望大家少走這段彎路。