最近在C#项目里接Ollama的工具调用几乎每个第一次跑通的人都会冒出一句这玩意儿怎么这么“笨”要么让它查天气它直接凭记忆乱编要么工具名和参数传得牛头不对马嘴要么明明调用了工具下一步又开始胡言乱语。排查了大半天我慢慢意识到“笨”这件事锅不能全让模型背大部分问题出在调用链路的实现方式、工具定义的质量以及推理参数上。这篇文章拿我手头一个模拟项目XC#控制台应用 Ollama本地模型当例子把Tool Call“笨”的前因后果彻底捋一遍顺便给出一套我在项目里验证过、能明显降低“笨”感的落地方案。1. 先搞懂“笨”在哪Tool Call的执行链路1.1 大模型不是在执行代码而是在生成JSON很多人第一次接触工具调用会天然觉得模型像写程序一样“判断出需要调用函数然后执行”。实际上完全不是这么回事。大模型在工具调用场景里做的事情本质上依然是“文本生成”只不过它生成的内容结构是JSON而且这个JSON被约束成工具调用格式。模型看到你给的工具列表Tools会在生成回复时计算一个问题“用户当前的需求是否匹配某个工具的description”这个匹配过程依赖模型对自然语言语义的理解能力。能力弱的模型比如3B、4B这一档经常会把“今天杭州天气怎么样”匹配到“获取天气”工具之外或者直接忽略工具、把工具描述当作普通聊天内容回答问题。这不是什么玄学就是模型内部语义表征还不够好。理解了这个底层逻辑才能理解后面所有“笨”的表现。所以当你在C#里发现模型不调用工具时第一反应别是改代码先确认的是模型本身有没有“理解”工具调用的意图。验证方法很简单用curl直接打Ollama的接口把同样的消息和工具发过去看返回里有没有tool_calls字段。如果curl都调不起来那就是模型或工具定义的问题跟C#代码没关系。1.2 C#拿到tool_call之后发生了什么假设模型正确返回了工具调用请求响应里会有一个message.tool_calls数组里面包含工具名称和参数。注意到这里模型的工作就结束了后续真正“执行工具”的动作Ollama不会替你做。OpenAI的云端接口同样不做但它的SDK和一些上层框架帮你封装了执行循环而Ollama这边官方没有提供C# SDK社区方案各搞各的很多情况下需要你自己把循环补齐。一个完整的Tool Call闭环是这样的把用户消息连同工具定义发给模型。模型返回tool_calls或者正常文本回答。你遍历tool_calls在C#代码里调用对应的方法比如GetWeatherAsync(杭州)。把工具执行结果作为一个role: tool的消息追加到对话里再次发给模型。模型看到工具结果生成最终回答。很多人只做到了第2步把tool_calls打出来看了一眼觉得“它调了呀”然后发现后面模型没有下文了就以为模型“笨”。实际上是你没把结果回传模型手头没有任何信息可以继续生成自然只能开始胡编。这个坑占了我遇到问题的六成以上。1.3 Ollama响应和OpenAI体系的微妙差异OpenAI兼容接口的tool_calls格式和Ollama原生接口有一些细节差异。Ollama原生/api/chat接口里tool_calls的结构长这样tool_calls: [ { function: { name: get_weather, arguments: { city: 杭州 } } } ]而OpenAI兼容格式里则有id、type: function这些额外字段。如果你在C#里用OpenAI的SDK去直连Ollama的/v1/chat/completions得到的结构又跟前者的原生接口不一样。一旦解析的模型类写死了某一种格式换接口就炸。这种“同一套业务代码换个SDK或换个端点就开始乱”的体验特别容易让人觉得是Ollama的问题。C#又是强类型语言不像Python那边字典随便接。你拿社区SDK里的ToolCall类去反序列化原生接口的JSON字段对不上就静默赋默认值。结果就是工具名变成空字符串参数变成null整个调用链直接断掉。这种情况我在项目里真实遇到过最后发现是SDK版本跟Ollama的API版本不匹配升级后全好了。2. C#侧接入方式盘点有些组合越用越“笨”2.1 三种常见接入方案的对比裸HttpClient调用、社区SDK比如OllamaSharp、用OpenAI SDK配本地地址这三种方案我都试过各有各的脾气。先看对比再决定用哪种能省很多事。方案上手难度工具调用支持度踩坑点HttpClient 裸调中高完全可控请求和响应的JSON结构要自己维护OllamaSharp低中版本迭代快部分版本对tools解析有BugOpenAI SDK低中高字段兼容不完全参数映射需要调试我现在的推荐顺序是先用裸HttpClient把链路跑通确认模型行为没问题再封装成项目里的公共方法。裸调看起来多写一点代码但你能清楚掌握请求和响应长什么样排查问题时少一层“SDK偷偷改了字段”的干扰。2.2 OllamaSharp的工具调用实现与坑OllamaSharp是目前C#生态里用的人相对多的一个库它把Ollama的/api/chat封装成了IOllamaApiClient。调用工具时可以直接把Tool对象塞进ChatRequest的Tools集合里看起来挺省事。但我实际用下来有两个地方容易栽。第一是版本问题早期版本对tools支持得非常粗糙某些版本里Tool对象只有Name和Description没有参数定义的位置导致模型拿不到参数的JSON Schema只能靠猜效果自然“笨”。第二是响应解析部分版本在反序列化tool_calls时用了一个内部类FunctionCall字段名跟Ollama实际返回的function层级对不齐解析出来永远是空。排查这类问题最耗时间因为代码编译不报错跑起来就是静默失败。如果你非要用OllamaSharp务必确认项目引用版本是较新的并且在跑工具调用前先打一条日志把原始响应JSON完整打印出来确认tool_calls真的解析到了。光靠调试器看对象属性有时会被属性初始化逻辑误导看原始JSON最稳。2.3 最容易漏掉的事把工具结果正确回传给模型工具执行完了结果怎么喂回给模型这里也有讲究。Ollama原生接口里追加一个role: tool的消息{ role: tool, content: {\city\:\杭州\,\weather\:\晴\,\temperature\:28} }注意两点。第一这个content可以是普通文本也可以是JSON字符串但模型对结构化文本的理解更好建议把工具执行结果序列化成简洁的JSON再塞进去。第二必须把上一步模型的assistant消息包括它里面的tool_calls整个保留在发给模型的messages列表里不能只留一个工具结果。否则模型不知道这个工具结果对应的是哪一次调用上下文逻辑断裂结果又开始“笨”。死循环也常见于这一步。有几次我发现模型不停地调用同一个工具看了日志才知道我回传的工具消息里角色写错了或者content是空的模型得到一个空结果后只能再调一次试试。这种问题不仔细看日志完全蒙在鼓里。3. 别急着怪模型模型选型与推理参数也是重灾区3.1 不是所有本地模型都适合做Tool Call本地模型的能力差距比很多人想象中大得多。我实测下来3B到4B参数量级别的模型工具调用基本处于“偶尔蒙对”的水平连续两次稳定调用同一个工具都难。7B到8B这一档比如常见的qwen2.5:7b、llama3.1:8b在简单工具场景下已经“勉强能用”前提是工具数量不超过三五个且参数没有复杂嵌套。14B以上的模型工具调用才会明显可靠起来但显存占用和推理速度又不是普通人能轻松承受的。我做过一个直观对比同一个C#程序同一个get_weather工具让模型回答“杭州今天多少度”模型是否调用工具参数正确性备注一个4B量级模型偶尔调用经常把城市名串改解释性回答居多7B量级模型基本稳定偶尔参数缺失需要描述写清楚14B量级模型稳定准确率高响应较慢但可靠所以如果项目对工具调用稳定性有硬性要求建议至少7B起步预算允许直接上14B。在模型本身能力不够的情况下谈“优化提示词”就像让一个刚学几天编程的人去写高并发架构上限就摆在那里。3.2 temperature、top_p对工具调用稳定性的影响工具调用这个任务跟我们平时聊天的需求不一样。聊天希望模型有点随机性显得生动工具调用希望模型每次都稳定输出同一个JSON结构。你想想如果temperature拉得太高模型在说“是”和“否”之间反复横跳工具调用自然就一会儿灵一会儿不灵。我的建议是专门处理工具调用的请求把temperature调到0到0.2之间。top_p可以保持默认0.9左右但最好别更高。有些模型对temperature0支持得不太稳定保险起见用0.1。repeat_penalty也要注意某些模型如果惩罚设得高可能会把工具名里重复的字母当惩罚对象生成出变形词。这些参数在Ollama的请求里都可以直接传{ model: qwen2.5:7b, messages: [...], tools: [...], options: { temperature: 0.1, top_p: 0.9, repeat_penalty: 1.1 } }一个小细节options是在请求顶层传的不是塞在messages里。我见过不少人放在消息内容里Ollama直接忽略然后一路怀疑模型变笨了。3.3 上下文长度和输出长度限制本地模型现在普遍支持4K、8K甚至更长的上下文但支持归支持每多一轮工具调用都要把历史的工具定义、消息、结果都重新塞进去上下文增长非常快。如果项目里对话历史控制不好模型长上下文注意力会涣散后面的工具调用质量直线下降。表现就是你感觉同一个模型前面调用得好好的第十轮开始瞎调。我的处理方式是把工具调用涉及的历史消息尽量精简。比如每轮工具调用结束后用户原来的问题可以保留但把特别长的系统提示词或多余示例裁掉。Ollama启动时还可以通过num_ctx设置上下文长度不要超过模型实际支持的范围否则它会提示失效或者直接截断。另外要设置num_predict限制模型一次生成的最大token数。你可能觉得这不影响工具调用其实很影响——如果不限制模型可能生成了超长分析文本还没轮到输出tool_calls就撞上了输出上限整个调用直接被中断。把num_predict设定在512左右既能让模型有空间生成工具调用JSON又不会让它啰嗦半天。4. 工具定义与提示词设计从“笨”到“聪明”的分水岭4.1 JSON Schema写不好模型只能瞎猜C#侧定义一个工具最终是转成JSON Schema传给Ollama的。很多人的Schema就写到两层像这样{ type: object, properties: { city: { type: string } } }模型拿到这种Schema只知道有个city参数是字符串类型但不知道city应该填什么内容、格式是什么、必不必须。于是各种离谱参数都出来了填英文的、填国家名不带城市的、把问题里所有词拼一起塞进去的。这不叫笨这叫“没给够信息但强人所难”。一个合格的get_weather工具Schema至少要把每个参数的单位、取值范围、常见示例写清楚{ type: object, properties: { city: { type: string, description: 城市名称使用中文标准名称例如杭州、北京、广州不要附带省市区和天气关键词, maxLength: 20 }, date: { type: string, description: 查询日期格式YYYY-MM-DD缺省为今天, enum: [今天, 明天, 2025-06-15] } }, required: [city] }enum字段特别有用它相当于把一个开放式填空变成了选择题模型的选择难度指数级下降。能用枚举约束的参数就枚举能用格式约束的就写pattern这些都直接影响工具调用成功率。4.2 工具命名和介绍文案里的潜规则工具名要尽量用动词开头语义明确。get_weather比weather好calculate_discount比discount好。模型在内部表示工具时会优先根据工具名的语义做匹配get_weather这个名字本身就向模型传递了“这是一个获取动作”的信号。Description字段则是真正的“说明书”。很多人的description只有一句“获取天气”模型根本不确定这个工具适不适合当前场景。合格的description应该写清楚三件事工具是干什么的、什么时候该使用、参数怎么获取。举个例子description: 根据城市名称和日期获取对应地区的天气实况。当用户询问天气、温度、降水、风力等信息时需要调用。城市名从用户原句中提取不要自行推断。这样模型判断起来就有明确依据了。如果项目里有多个功能相近的工具比如get_weather和get_air_qualitydescription里还要写清楚“空气质量使用后者天气使用前者”避免模型混淆。4.3 System Prompt里把调用规则说清楚虽说模型能根据工具描述自动判断但System Prompt里明确写一遍规则能显著降低“不调用工具”的概率。我在项目里的System Prompt通常包含这么一句你是智能助手。当用户问题需要实时或外部数据时你必须调用工具获取信息。得到工具结果后再根据结果组织回答。未得到工具结果前不得编造数据。这句话的用处在于把“调用工具”从可选变为必选相当于给模型划了一条行为边界。另外在System Prompt里可以给一个简短的调用格式示意例如“如果用户问天气你应当返回工具调用而不是直接回答”。本地模型对这类显式指令的敏感度比我们想象中要高得多。4.4 一个可直接抄的C#工具定义下面是我在模拟项目X里实际用过的完整工具定义代码包含天气工具的Schema构造。你可以直接拿去改造成自己的工具var tool new { type function, function new { name get_weather, description 根据城市名称获取最近天气实况。当用户提到天气、温度、降雨、风力时必须调用城市名从用户句子中提取。, parameters new { type object, properties new { city new { type string, description 城市中文名称例如杭州、北京, maxLength 20 } }, required new[] { city } } } }; var tools new[] { tool };注意我用了匿名对象来构建请求体配合System.Text.Json序列化时属性顺序和大小写都能控制。如果你喜欢强类型风格可以定义ToolDefinition类但匿名对象在调试阶段更直观。5. 从“笨”到“够用”的实战调试记录5.1 最小可运行的Tool Loop这一节给出一套我验证过的最小可运行代码C# 控制台项目通过HttpClient直接调用Ollama原生接口完整跑通“问题 - 工具调用 - 工具执行 - 结果回传 - 最终回答”的闭环。using System.Text; using System.Text.Json; // 序列化请求时保持属性小写方便与Ollama字段对齐 var options new JsonSerializerOptions { PropertyNamingPolicy JsonNamingPolicy.CamelCase }; var httpClient new HttpClient(); var messages new Listobject { new { role user, content 杭州现在多少度 } }; // 第一步发送带tools的请求 var requestObj new { model qwen2.5:7b, messages, tools new object[] { BuildWeatherTool() }, options new { temperature 0.1, num_predict 512 }, stream false }; var content new StringContent( JsonSerializer.Serialize(requestObj, options), Encoding.UTF8, application/json); var response await httpClient.PostAsync(http://localhost:11434/api/chat, content); var responseJson await response.Content.ReadAsStringAsync(); // 这里务必打印原始响应排查时靠它 Console.WriteLine(responseJson); using var doc JsonDocument.Parse(responseJson); var message doc.RootElement.GetProperty(message); var toolCalls message.GetProperty(tool_calls).DeserializeListToolCall(options); messages.Add(message.Deserializeobject(options)); // 第二步逐个执行工具把结果以tool角色加回对话 if (toolCalls?.Count 0) { foreach (var call in toolCalls) { var arg call.Arguments; var result await ExecuteWeatherToolAsync(arg.GetProperty(city).GetString()); messages.Add(new { role tool, content JsonSerializer.Serialize(result, options) }); } // 第三步带着工具结果二次请求 requestObj.messages messages; content new StringContent(JsonSerializer.Serialize(requestObj, options), Encoding.UTF8, application/json); response await httpClient.PostAsync(http://localhost:11434/api/chat, content); responseJson await response.Content.ReadAsStringAsync(); Console.WriteLine(responseJson); } // 本地方法模拟天气工具执行 static async Taskobject ExecuteWeatherToolAsync(string city) { // 真实项目里这里调天气服务API await Task.Delay(50); return new { city, weather 晴, temperature 28 }; } // 工具定义 static object BuildWeatherTool() { return new { type function, function new { name get_weather, description 根据城市中文名称获取当前天气实况用户提到天气时必须调用, parameters new { type object, properties new { city new { type string, description 城市中文名称 } }, required new[] { city } } } }; } public class ToolCall { public string Name { get; set; } public JsonElement Arguments { get; set; } }实际运行时第一步的响应里如果tool_calls为空说明模型直接回答了。这时候把temperature调低或者检查工具定义基本就能解决。整个调试过程我是严格按照“先用curl确认模型-再跑C#最小链路-最后套业务封装”的顺序来的。5.2 一个典型的调试案例天气查询反复失败我调试的时候遇到过一个很典型的现象同一个问题第一次问“杭州天气”模型正常调用了get_weather紧接着问“那北京呢”模型不调了直接编了一个北京的天气答案。连续试好几次都是这样。排查思路很清晰。第一步把第二次请求的完整消息历史打出来发现messages数组里我把第一轮工具结果以role: tool追加进去了但第一轮的assistant消息我没有完整保留只保留了它的content字段丢掉了里面的tool_calls。这在单轮里没问题但多轮时模型的上下文出现了一个“悬空的工具结果”。它不知道该结果对应哪个调用就选择不依赖工具自己编回答。修复方式很简单每次把整个assistant消息对象含tool_calls原样加入历史。代码改完后再测试“那北京呢”也能正确调用工具了。5.3 调试时的正确顺序我整理了一套调试工具调用问题的顺序按照这个顺序排查通常能在半小时内定位到问题根源直接用curl调Ollama接口排除C#代码干扰。确认原始响应里的tool_calls字段是否完整。用最小C#控制台程序跑通闭环不加任何业务逻辑。确认模型二次请求后能否正确引用工具结果。最后再把业务代码套上去。很多人一步到位直接在业务代码里加日志结果被各种无关逻辑干扰半天找不到重点。把链路拆到最小反而定位最快。6. 常见问题排查速查与避坑清单下面这张表基本覆盖了我在C#里接Ollama Tool Call时遇过的典型问题可以直接当排查手册用。现象可能原因处理方法模型完全不调用工具直接回答模型太小、温度过高、工具描述不清晰换7B以上模型temperature降到0.1完善description工具调用了但参数残缺或乱填JSON Schema缺少必填、枚举、示例给每个参数补description、required、enum调用了工具但最终回答还是瞎编工具结果未正确回传或role写错确认追加role: tool消息且保留完整assistant消息不停调用同一个工具形成死循环工具返回空内容、结果未追加到对话检查工具执行方法确保结果序列化为非空JSONtool_calls解析出来全是默认值SDK版本与Ollama API版本不匹配升级SDK或直接用HttpClient裸调前几轮正常多轮后开始“笨”上下文过长模型注意力分散精简历史消息必要时裁剪较早轮次的工具细节报错但无有效提示num_predict过小导致输出被截断num_predict调到512以上限制过长文本生成这里再补充几个我认为值得记下来的避坑心得。第一Ollama的服务端版本和客户端SDK必须一起升级。Ollama更新很频繁工具调用的响应格式偶尔会微调旧SDK解析新格式就出问题。我吃过一次亏后现在每次升级完Ollama都先用curl跑一遍工具示例确认格式没变再继续开发。第二C#侧解析JSON时尽量用JsonDocument或JsonElement保持原始结构不要一口气反序列化成强类型对象。工具调用的响应结构细节比较多用强类型类容易丢失字段。先用JsonElement把关键路径摸清楚再决定哪些地方可以反序列化成POCO。第三不要忽略日志的作用。我在工具调用链路里加了几个关键埋点请求发出前的消息体、Ollama原始响应、工具执行结果、最终回复。每次调试都靠这些日志而不是靠猜。很多“玄学”问题比如偶尔不调用、偶尔参数错乱全都在日志里能看到规律。最后说一点个人体会。Tool Call想从“笨”变“够用”关键不是找一个万能模型或万能SDK而是把链路里的每一个变量都控制住。模型、参数、工具定义、消息历史、排查手段这五样东西我建议做成一套项目内的固定模板每次新项目直接复用遇到问题先跑最小复现路径。按照这套思路实践下来C#里用Ollama做工具调用的体验其实没有刚开始接触时那么“笨”。当然它也确实没有某些托管服务那么省心——动手调试的过程本身就是把这套机制吃透的过程。
