如果你最近在C#项目里接了Ollama的ToolCall大概率会有一个很直观的感受这模型怎么这么“笨”。同一个需求远端API版模型一遍就能跑通放到本地Ollama上要么死活不调用工具要么调了之后参数丢三落四甚至会一本正经地编一个不存在的函数名。这篇内容不是讲Ollama怎么安装也不是贴官方文档示例而是从C#接入方的角度把ToolCall“笨”的前因后果拆开揉碎讲清楚是协议没对齐、工具定义没喂饱还是模型选型压根不对路。如果你正在做自然语言调用本地工具的Agent、智能客服、或者内部自动化调度Demo这篇文章大概率能帮你省掉几个晚上的排查时间。1. “笨”在哪先用几个C#接入场景说清现象1.1 官方Demo能跑换到真实业务就崩很多人的第一步都是从Ollama官方示例开始的一个简单的get_weather工具参数就city和date两个字符串跑起来看起来一切正常模型会返回tool_callsC#端也能把参数解析出来。但一旦把工具换成真实业务里的东西比如“查询订单并按状态筛选”“根据用户画像推荐内容”模型就开始犯糊涂。我在一个内部调度项目里就遇到过这种情况工具定义大概有七八个每个参数三到五个嵌套结构两层。结果模型返回的arguments和我在代码里定义的JSON Schema完全对不上该传string的传了数字该传枚举值的传了拼音缩写。当时第一反应是“模型不够聪明”后来才发现问题的根源根本不在模型而在调用方给模型喂的东西。这类现象特别有欺骗性因为Demo能跑会让人误以为链路是通的。实际上链路通只是说明HTTP通信没断模型有没有真正理解你的工具协议完全是另一回事。1.2 四种典型“笨”法一览我总结了一下C#接入Ollama时最常见的“笨”有以下四种。先放在一张表里后面逐一展开。表现具体场景常见误判该调不调用户明确问“帮我查一下天气”模型却直接回答“我无法获取天气信息”误以为是模型能力不行调了但参数错乱工具叫get_weather返回的arguments却少了date或者把“北京”写成“beijing”误以为是序列化问题复读机式回答模型在content里写了一长串JSON而不是在tool_calls里结构化返回误以为是工具定义格式不对多工具串联混乱先调了A工具拿到结果后应该调B结果模型把A的结果当成B的参数又调了一遍A误以为是状态管理有bug每一种“笨”都对应调用链路上不同的断点。我在后面章节会逐个拆。这里想先强调一个观点Ollama的ToolCall不是一个开关而是一套需要调用方主动配合的协议。模型本身只是一个文本生成器它能不能“聪明”地调用工具取决于你给它看到的世界够不够清晰。2. 从调用链看根因Ollama的ToolCall协议到底怎么工作2.1 一条ToolCall请求的完整旅行线路要理解“笨”从哪来先得把一条ToolCall请求的一生走一遍。Ollama的接口路径是/api/chat请求体里除了常规的model和messages还有一个可选字段tools。这个tools字段就是你把函数列表“告诉”模型的地方。C#端通常是这样构造请求的var payload new { model qwen2.5:7b, messages new[] { new { role user, content 帮我查一下北京明天的天气 } }, tools new[] { new { type function, function new { name get_weather, description 查询指定城市在指定日期的天气情况, parameters new { type object, properties new { city new { type string, description 城市名如北京 }, date new { type string, description 日期格式yyyy-MM-dd } }, required new[] { city, date } } } } }, stream false };模型拿到这段文本之后会把它当成“提示词上下文”的一部分来处理。模型内部其实没有“调用工具”这个动作它只是在预测下一个最合理的token序列。如果它判断当前用户问题需要外部数据就会在返回的message里带上tool_calls数组数组里的每一项包含函数名和参数对象。C#端收到响应后解析message.tool_calls逐个执行真正的函数再把执行结果以role tool的消息追加进messages数组发第二轮请求。这一步非常关键工具结果必须以tool角色回传模型才能基于结果继续生成最终回答。这个循环可以多轮直到模型不再返回tool_calls为止。2.2 三个容易翻车的协议细节很多人觉得ToolCall“笨”是因为把Ollama的返回格式和OpenAI的格式混着用。三者之间有几个明显的差异C#端不注意就会出事故。第一Ollama返回的arguments是JSON对象不是JSON字符串。OpenAI的返回里function.arguments是字符串需要二次解析Ollama直接给你对象。有人用OpenAI风格的SDK去连Ollama拿到字符串后硬套解析逻辑反而把好端端的对象搞坏了。第二Ollama没有标准的finish_reason字段或者说不像OpenAI那样稳定地带tool_calls这个终止原因。判断模型这一轮是不是要调用工具最可靠的方式是直接检查message.tool_calls数组存在与否、长度是否大于零而不是看finish_reason。第三Ollama对模型返回的内容几乎不做后处理。模型说参数里有个city: beijingOllama就原样透传给你。它不会帮你修正不会对照你的JSON Schema做校验。所以C#端必须自己做容错否则再小的格式偏差都会变成运行时异常。这三点叠加在一起结论就是Ollama把“理解工具定义”和“结构化生成参数”的压力完全转移给了客户端和模型本身。你用的本地模型越弱客户端给的提示越粗糙ToolCall就越笨。3. 五个最常让ToolCall变“笨”的C#侧写法3.1 根因一工具Schema“营养不良”这是我在项目里排查出最多的原因没有之一。很多人写工具定义时只给name和parametersdescription要么不写要么写一句“查询天气”。模型不知道你这个函数是干什么的、参数取什么值、格式是什么它只能靠猜。我之前在一个Demo里写过这样的工具定义new { type function, function new { name get_weather, description 查询天气, parameters new { type object, properties new { city new { type string }, date new { type string } } } } }模型看到这种定义根本不知道city该填“北京”还是“Beijing”date该填“明天”还是“2025-06-01”。它能给你返回tool_calls就已经算给面子了参数大概率是错的。后来我把定义改成了这样new { type function, function new { name get_weather, description 根据城市和日期查询天气情况用于帮助用户安排出行、运动等决策, parameters new { type object, properties new { city new { type string, description 城市名称使用中文全称例如北京、上海、广州 }, date new { type string, description 查询日期格式为yyyy-MM-dd例如2025-06-01不要使用相对日期 } }, required new[] { city, date } } } }看起来只是多写了几行描述效果天差地别。模型是文本生成模型你给它的描述越像一段真实存在的代码注释它就更能理解参数约束。这个经验我后面还会再强调。3.2 根因二消息历史里少了关键角色第二个高频坑是消息历史的角色顺序不对。Ollama要求工具调用过程遵循一个固定节奏user提问assistant返回tool_calls客户端执行工具然后以roletool回传结果最后assistant再基于结果生成最终回答。有的人图省事拿到工具结果后直接把它拼成一句普通文本塞进user消息或者干脆在客户端本地拼好答案不再发一轮请求。结果就是模型什么都没学到下一轮对话依旧瞎猜。正确的多轮消息序列应该是这样的user: 帮我查一下北京明天的天气 assistant: (tool_calls get_weather(city北京, date2025-06-01)) tool: 晴25度微风 assistant: 北京明天天气晴朗气温25度适合外出如果你在C#端实现的是Listobject拼接消息一定要保证tool角色的消息出现在assistant的tool_calls之后而不是被插到别的位置。Ollama对消息顺序很敏感顺序错了模型就分不清哪些内容是工具返回的哪些是你替它编的。3.3 根因三System.Text.Json序列化选项没对齐这一点是C#特有的坑别的语言里相对少见。System.Text.Json默认序列化枚举时输出的是数字如果你在工具定义和请求体里混用了枚举类型模型看到的可能不是“晴/多云/雨”而是“0/1/2”。举个例子public enum WeatherCondition { Sunny, Cloudy, Rainy } var options new JsonSerializerOptions { PropertyNamingPolicy JsonNamingPolicy.CamelCase, Converters { new JsonStringEnumConverter() } };如果你忘了加JsonStringEnumConverter序列化后的JSON里就是condition: 0模型对这种数字枚举非常不敏感很容易返回一个不存在的值。更麻烦的是属性命名策略默认PascalCase会让CityName变成CityName而不是cityName而你在描述里写的是“城市名”模型可能就直接拿属性名当参数名返回。所以C#端要在入口统一配置好JsonSerializerOptions并且在生成工具Schema时用同一套选项。我建议把options定义成静态单例避免各处各写一份、最后发现序列化结果不一致。3.4 根因四模型选型“小马拉大车”Ollama能跑的模型很多但不是每个模型都擅长工具调用。在本地量化场景里我实测下来的经验是参数越小的模型工具调用越容易翻车而且翻车方式特别统一——漏参数、编参数、拒绝调用。我用过比较典型的几个模型结果如下模型工具调用稳定性踩坑点适用建议llama3.1:8b一般参数一多就漏嵌套对象经常化成平铺只适合单工具、少参数场景qwen2.5:7b较好中文描述友好偶发枚举值偏差常规业务工具推荐qwen2.5:14b好显存占用高首次加载慢复杂多工具场景推荐deepseek-r1:7b一般推理过程会夹带工具调用需要过滤需要先清理reasoningphi4:14b较好英文描述效果更稳英文工具名/参数名更友好如果你的业务工具很多、参数复杂不要指望一个3B的模型能稳定输出几十个字段的arguments。这不是C#代码能补齐的是模型本身的生成能力上限。遇到这种需求要么换大一点的模型要么把工具拆细、接口单薄化让每个工具只管一件事。3.5 根因五流式SSE解析把tool_calls搞丢了最后一个问题比较隐蔽只在开启stream true时出现。Ollama流式返回tool_calls时不是一次性把整个数组吐出来的而是像打字机一样分段输出。你如果每收到一帧就当作完整结果消费就会发现自己拿到的arguments残缺不全。C#里正确做法是先把流式帧缓存起来在请求结束的那个done帧到来之前将每一帧的message.tool_calls增量累积最后再统一解析。简单示意var toolCalls new ListJsonNode(); await foreach (var chunk in streamChunks) { var delta chunk?[message]?[tool_calls]; if (delta is not null) { toolCalls.AddRange(delta.AsArray()); } } // 流结束后再整体处理 toolCalls如果你用的是System.Net.Http.Json里的GetFromJsonAsync做流式读取一定要自己处理SSE格式不要省掉累积那一步。这个坑排查起来特别耗时间日志里看起来像模型“时灵时不灵”分次返回的字段有时全有时缺其实只是解析方式不对。4. 一次“用自然语言查天气并推荐晨跑公园”的排查实录4.1 第一轮跑出来的“笨”日志我从头到尾走一遍当时排查的过程你可以对比着自己的项目看。场景很简单本地Agent接Ollama用户输入的句子是“帮我查一下北京明天早上适不适合跑步如果适合就推荐一个附近的公园”。我预先定义了两个工具get_weather查询天气get_nearby_parks根据城市和天气推荐公园。第一次跑出来的结果是这样的模型压根没走工具直接在content里输出了一堆JSON{ action: get_weather, params: { city: 北京, date: 明天 } }看起来它“知道”该调用工具但它把调用动作表达成了文本而不是结构化返回tool_calls。这种状况最迷惑人因为你会在日志里看到工具调用的名字和参数以为只是格式不对改改解析就行。但实际上模型完全没有进入工具调用模式。4.2 用curl把Ollama的原始返回拉出来看排查的第一步我建议所有C#侧的问题都先用命令行工具复现把C#代码暂时扔到一边。我用curl构造了一个最小请求把同样的messages和tools直接打到Ollama的/api/chat接口上拿到最原始的返回JSON。curl -X POST http://localhost:11434/api/chat -d { model: llama3.1:8b, messages: [{role: user, content: 帮我查一下北京明天早上适不适合跑步如果适合就推荐一个附近的公园}], tools: [{ ... }], stream: false }返回结果显示模型根本没有进入tool_calls分支而是把调用动作写进了content。到这一步我基本确定问题不在C#解析层而在模型对工具定义的理解层。然后我换了qwen2.5:7b再跑同样的请求结果立刻就能输出正常的tool_calls结构。这说明模型选型差异是非常关键的一个变量。4.3 工具定义瘦身后的前后对比接下来我又测试了同一模型下工具定义的影响。把get_weather的description从“查询天气”改成包含取值约束的完整描述把get_nearby_parks的参数从两层嵌套对象改成了扁平字符串和枚举值效果立竿见影。修改后的response长这样{ message: { role: assistant, content: , tool_calls: [ { function: { name: get_weather, arguments: { city: 北京, date: 2025-06-01 } } } ] } }这个结果跟预期完全一致。你可以看到同一个模型在工具定义“营养不良”时糊弄你在定义清晰后就能准确输出。后来我在多个模型上重复测试凡是出现“参数错乱”“该调不调”的八成以上可以通过改造工具定义解决而不是换模型。这个排查链路的核心思路是先绕开C#代码直接看Ollama原始返回再把变量拆开单独控制。很多问题混在一起时看着像玄学拆开之后就发现只是某个环节没对齐。5. 让ToolCall变“靠谱”的落地配置与代码模板5.1 工具定义写作规范这一节给出一个可以直接抄走的工具定义模板你照着这个结构写不敢说一定能保证100%稳定但能把大多数“笨”的问题挡在门外。规范提炼下来是四点函数名用英文驼峰描述用中文写清楚“什么时候该调用、调用后能解决什么问题”每个参数都要有description里面写清楚取值范围、格式、单位、不要用什么值能用枚举就不用自由字符串枚举值也要在description里列全避免过深的嵌套结构能拍平就拍平下面是一个标准模板new { type function, function new { name get_nearby_parks, description 根据城市和天气条件推荐适合晨跑的公园只有用户需要户外运动推荐时才调用, parameters new { type object, properties new { city new { type string, description 城市名称使用中文全称例如北京、上海 }, weather new { type string, description 天气状况取值晴朗、多云、小雨、大雨 } }, required new[] { city, weather } } } }注意description里我写了“只有用户需要户外运动推荐时才调用”这就是在告诉模型触发条件能显著减少“不该调也调”的情况。5.2 C#端调用循环的正确骨架工具调用的核心循环可以封装成一个通用方法五次到十次是合理上限。下面是适合直接复用的C#骨架代码注意消息顺序和tool_calls的累积判断。public static async Task RunToolLoopAsync( HttpClient client, string model, Listobject messages, IReadOnlyListobject tools, int maxTurns 5) { var options new JsonSerializerOptions { PropertyNamingPolicy JsonNamingPolicy.CamelCase, Converters { new JsonStringEnumConverter() } }; for (var turn 0; turn maxTurns; turn) { var payload new { model, messages, tools, stream false }; using var resp await client.PostAsJsonAsync(/api/chat, payload, options); var json await resp.Content.ReadFromJsonAsyncJsonNode(options); var msg json?[message]; var toolCalls msg?[tool_calls]?.AsArray(); if (toolCalls is null || toolCalls.Count 0) { Console.WriteLine(msg?[content]?.GetValuestring()); return; } messages.Add(new { role assistant, content msg?[content]?.GetValuestring() ?? }); foreach (var call in toolCalls) { var name call?[function]?[name]?.GetValuestring(); var argsNode call?[function]?[arguments]; if (argsNode is null) continue; var argsText argsNode.GetValueKind() JsonValueKind.String ? argsNode.GetValuestring() : argsNode.ToJsonString(options); var result await ExecuteToolAsync(name, argsText); messages.Add(new { role tool, content result }); } } throw new InvalidOperationException(工具调用超出最大轮次); }这段代码里有两个细节值得说明。一个是argsNode同时兼容了“字符串”和“对象”两种形态因为不同模型返回的arguments类型不稳定这点容错必须留。另一个是assistant消息必须在执行工具前加入messages这能让模型知道当前轮到它讲话了符合上一节说的角色顺序。5.3 模型、上下文与超时参数推荐最后说运行参数。Ollama默认上下文窗口不一定够用工具定义本身很占token模型要理解十几个工具的描述需要足够的窗口。我个人的经验值是至少把OLLAMA_NUM_CTX设到8192如果工具多直接上16384。推荐配置大概是这样模型优先选qwen2.5:14b或同级别7b也可以但工具数量控制在五个以内上下文窗口不低于8192工具数量控制在十个以内太多的话让模型先做意图分类再挂对应的工具子集单轮ToolCall循环上限五轮超时给到60秒以上本地模型推理慢别急着报错如果工具调用失败不要静默吞掉把原始返回JSON打到日志里方便定位是协议问题还是模型问题我个人的习惯是凡是工具调用相关需求先把工具定义和消息顺序写对再考虑换模型。模型永远是用力的下限你给它的协议越干净它才越稳定。做C#接入本身就是把API、序列化、消息编排这些后端能力变成模型的“脚手架”脚手架搭得越扎实模型“笨”的概率就越低。
如果你最近在C#项目里接了Ollama的ToolCall大概率会有一个很直观的感受这模型怎么这么“笨”。同一个需求远端API版模型一遍就能跑通放到本地Ollama上要么死活不调用工具要么调了之后参数丢三落四甚至会一本正经地编一个不存在的函数名。这篇内容不是讲Ollama怎么安装也不是贴官方文档示例而是从C#接入方的角度把ToolCall“笨”的前因后果拆开揉碎讲清楚是协议没对齐、工具定义没喂饱还是模型选型压根不对路。如果你正在做自然语言调用本地工具的Agent、智能客服、或者内部自动化调度Demo这篇文章大概率能帮你省掉几个晚上的排查时间。1. “笨”在哪先用几个C#接入场景说清现象1.1 官方Demo能跑换到真实业务就崩很多人的第一步都是从Ollama官方示例开始的一个简单的get_weather工具参数就city和date两个字符串跑起来看起来一切正常模型会返回tool_callsC#端也能把参数解析出来。但一旦把工具换成真实业务里的东西比如“查询订单并按状态筛选”“根据用户画像推荐内容”模型就开始犯糊涂。我在一个内部调度项目里就遇到过这种情况工具定义大概有七八个每个参数三到五个嵌套结构两层。结果模型返回的arguments和我在代码里定义的JSON Schema完全对不上该传string的传了数字该传枚举值的传了拼音缩写。当时第一反应是“模型不够聪明”后来才发现问题的根源根本不在模型而在调用方给模型喂的东西。这类现象特别有欺骗性因为Demo能跑会让人误以为链路是通的。实际上链路通只是说明HTTP通信没断模型有没有真正理解你的工具协议完全是另一回事。1.2 四种典型“笨”法一览我总结了一下C#接入Ollama时最常见的“笨”有以下四种。先放在一张表里后面逐一展开。表现具体场景常见误判该调不调用户明确问“帮我查一下天气”模型却直接回答“我无法获取天气信息”误以为是模型能力不行调了但参数错乱工具叫get_weather返回的arguments却少了date或者把“北京”写成“beijing”误以为是序列化问题复读机式回答模型在content里写了一长串JSON而不是在tool_calls里结构化返回误以为是工具定义格式不对多工具串联混乱先调了A工具拿到结果后应该调B结果模型把A的结果当成B的参数又调了一遍A误以为是状态管理有bug每一种“笨”都对应调用链路上不同的断点。我在后面章节会逐个拆。这里想先强调一个观点Ollama的ToolCall不是一个开关而是一套需要调用方主动配合的协议。模型本身只是一个文本生成器它能不能“聪明”地调用工具取决于你给它看到的世界够不够清晰。2. 从调用链看根因Ollama的ToolCall协议到底怎么工作2.1 一条ToolCall请求的完整旅行线路要理解“笨”从哪来先得把一条ToolCall请求的一生走一遍。Ollama的接口路径是/api/chat请求体里除了常规的model和messages还有一个可选字段tools。这个tools字段就是你把函数列表“告诉”模型的地方。C#端通常是这样构造请求的var payload new { model qwen2.5:7b, messages new[] { new { role user, content 帮我查一下北京明天的天气 } }, tools new[] { new { type function, function new { name get_weather, description 查询指定城市在指定日期的天气情况, parameters new { type object, properties new { city new { type string, description 城市名如北京 }, date new { type string, description 日期格式yyyy-MM-dd } }, required new[] { city, date } } } } }, stream false };模型拿到这段文本之后会把它当成“提示词上下文”的一部分来处理。模型内部其实没有“调用工具”这个动作它只是在预测下一个最合理的token序列。如果它判断当前用户问题需要外部数据就会在返回的message里带上tool_calls数组数组里的每一项包含函数名和参数对象。C#端收到响应后解析message.tool_calls逐个执行真正的函数再把执行结果以role tool的消息追加进messages数组发第二轮请求。这一步非常关键工具结果必须以tool角色回传模型才能基于结果继续生成最终回答。这个循环可以多轮直到模型不再返回tool_calls为止。2.2 三个容易翻车的协议细节很多人觉得ToolCall“笨”是因为把Ollama的返回格式和OpenAI的格式混着用。三者之间有几个明显的差异C#端不注意就会出事故。第一Ollama返回的arguments是JSON对象不是JSON字符串。OpenAI的返回里function.arguments是字符串需要二次解析Ollama直接给你对象。有人用OpenAI风格的SDK去连Ollama拿到字符串后硬套解析逻辑反而把好端端的对象搞坏了。第二Ollama没有标准的finish_reason字段或者说不像OpenAI那样稳定地带tool_calls这个终止原因。判断模型这一轮是不是要调用工具最可靠的方式是直接检查message.tool_calls数组存在与否、长度是否大于零而不是看finish_reason。第三Ollama对模型返回的内容几乎不做后处理。模型说参数里有个city: beijingOllama就原样透传给你。它不会帮你修正不会对照你的JSON Schema做校验。所以C#端必须自己做容错否则再小的格式偏差都会变成运行时异常。这三点叠加在一起结论就是Ollama把“理解工具定义”和“结构化生成参数”的压力完全转移给了客户端和模型本身。你用的本地模型越弱客户端给的提示越粗糙ToolCall就越笨。3. 五个最常让ToolCall变“笨”的C#侧写法3.1 根因一工具Schema“营养不良”这是我在项目里排查出最多的原因没有之一。很多人写工具定义时只给name和parametersdescription要么不写要么写一句“查询天气”。模型不知道你这个函数是干什么的、参数取什么值、格式是什么它只能靠猜。我之前在一个Demo里写过这样的工具定义new { type function, function new { name get_weather, description 查询天气, parameters new { type object, properties new { city new { type string }, date new { type string } } } } }模型看到这种定义根本不知道city该填“北京”还是“Beijing”date该填“明天”还是“2025-06-01”。它能给你返回tool_calls就已经算给面子了参数大概率是错的。后来我把定义改成了这样new { type function, function new { name get_weather, description 根据城市和日期查询天气情况用于帮助用户安排出行、运动等决策, parameters new { type object, properties new { city new { type string, description 城市名称使用中文全称例如北京、上海、广州 }, date new { type string, description 查询日期格式为yyyy-MM-dd例如2025-06-01不要使用相对日期 } }, required new[] { city, date } } } }看起来只是多写了几行描述效果天差地别。模型是文本生成模型你给它的描述越像一段真实存在的代码注释它就更能理解参数约束。这个经验我后面还会再强调。3.2 根因二消息历史里少了关键角色第二个高频坑是消息历史的角色顺序不对。Ollama要求工具调用过程遵循一个固定节奏user提问assistant返回tool_calls客户端执行工具然后以roletool回传结果最后assistant再基于结果生成最终回答。有的人图省事拿到工具结果后直接把它拼成一句普通文本塞进user消息或者干脆在客户端本地拼好答案不再发一轮请求。结果就是模型什么都没学到下一轮对话依旧瞎猜。正确的多轮消息序列应该是这样的user: 帮我查一下北京明天的天气 assistant: (tool_calls get_weather(city北京, date2025-06-01)) tool: 晴25度微风 assistant: 北京明天天气晴朗气温25度适合外出如果你在C#端实现的是Listobject拼接消息一定要保证tool角色的消息出现在assistant的tool_calls之后而不是被插到别的位置。Ollama对消息顺序很敏感顺序错了模型就分不清哪些内容是工具返回的哪些是你替它编的。3.3 根因三System.Text.Json序列化选项没对齐这一点是C#特有的坑别的语言里相对少见。System.Text.Json默认序列化枚举时输出的是数字如果你在工具定义和请求体里混用了枚举类型模型看到的可能不是“晴/多云/雨”而是“0/1/2”。举个例子public enum WeatherCondition { Sunny, Cloudy, Rainy } var options new JsonSerializerOptions { PropertyNamingPolicy JsonNamingPolicy.CamelCase, Converters { new JsonStringEnumConverter() } };如果你忘了加JsonStringEnumConverter序列化后的JSON里就是condition: 0模型对这种数字枚举非常不敏感很容易返回一个不存在的值。更麻烦的是属性命名策略默认PascalCase会让CityName变成CityName而不是cityName而你在描述里写的是“城市名”模型可能就直接拿属性名当参数名返回。所以C#端要在入口统一配置好JsonSerializerOptions并且在生成工具Schema时用同一套选项。我建议把options定义成静态单例避免各处各写一份、最后发现序列化结果不一致。3.4 根因四模型选型“小马拉大车”Ollama能跑的模型很多但不是每个模型都擅长工具调用。在本地量化场景里我实测下来的经验是参数越小的模型工具调用越容易翻车而且翻车方式特别统一——漏参数、编参数、拒绝调用。我用过比较典型的几个模型结果如下模型工具调用稳定性踩坑点适用建议llama3.1:8b一般参数一多就漏嵌套对象经常化成平铺只适合单工具、少参数场景qwen2.5:7b较好中文描述友好偶发枚举值偏差常规业务工具推荐qwen2.5:14b好显存占用高首次加载慢复杂多工具场景推荐deepseek-r1:7b一般推理过程会夹带工具调用需要过滤需要先清理reasoningphi4:14b较好英文描述效果更稳英文工具名/参数名更友好如果你的业务工具很多、参数复杂不要指望一个3B的模型能稳定输出几十个字段的arguments。这不是C#代码能补齐的是模型本身的生成能力上限。遇到这种需求要么换大一点的模型要么把工具拆细、接口单薄化让每个工具只管一件事。3.5 根因五流式SSE解析把tool_calls搞丢了最后一个问题比较隐蔽只在开启stream true时出现。Ollama流式返回tool_calls时不是一次性把整个数组吐出来的而是像打字机一样分段输出。你如果每收到一帧就当作完整结果消费就会发现自己拿到的arguments残缺不全。C#里正确做法是先把流式帧缓存起来在请求结束的那个done帧到来之前将每一帧的message.tool_calls增量累积最后再统一解析。简单示意var toolCalls new ListJsonNode(); await foreach (var chunk in streamChunks) { var delta chunk?[message]?[tool_calls]; if (delta is not null) { toolCalls.AddRange(delta.AsArray()); } } // 流结束后再整体处理 toolCalls如果你用的是System.Net.Http.Json里的GetFromJsonAsync做流式读取一定要自己处理SSE格式不要省掉累积那一步。这个坑排查起来特别耗时间日志里看起来像模型“时灵时不灵”分次返回的字段有时全有时缺其实只是解析方式不对。4. 一次“用自然语言查天气并推荐晨跑公园”的排查实录4.1 第一轮跑出来的“笨”日志我从头到尾走一遍当时排查的过程你可以对比着自己的项目看。场景很简单本地Agent接Ollama用户输入的句子是“帮我查一下北京明天早上适不适合跑步如果适合就推荐一个附近的公园”。我预先定义了两个工具get_weather查询天气get_nearby_parks根据城市和天气推荐公园。第一次跑出来的结果是这样的模型压根没走工具直接在content里输出了一堆JSON{ action: get_weather, params: { city: 北京, date: 明天 } }看起来它“知道”该调用工具但它把调用动作表达成了文本而不是结构化返回tool_calls。这种状况最迷惑人因为你会在日志里看到工具调用的名字和参数以为只是格式不对改改解析就行。但实际上模型完全没有进入工具调用模式。4.2 用curl把Ollama的原始返回拉出来看排查的第一步我建议所有C#侧的问题都先用命令行工具复现把C#代码暂时扔到一边。我用curl构造了一个最小请求把同样的messages和tools直接打到Ollama的/api/chat接口上拿到最原始的返回JSON。curl -X POST http://localhost:11434/api/chat -d { model: llama3.1:8b, messages: [{role: user, content: 帮我查一下北京明天早上适不适合跑步如果适合就推荐一个附近的公园}], tools: [{ ... }], stream: false }返回结果显示模型根本没有进入tool_calls分支而是把调用动作写进了content。到这一步我基本确定问题不在C#解析层而在模型对工具定义的理解层。然后我换了qwen2.5:7b再跑同样的请求结果立刻就能输出正常的tool_calls结构。这说明模型选型差异是非常关键的一个变量。4.3 工具定义瘦身后的前后对比接下来我又测试了同一模型下工具定义的影响。把get_weather的description从“查询天气”改成包含取值约束的完整描述把get_nearby_parks的参数从两层嵌套对象改成了扁平字符串和枚举值效果立竿见影。修改后的response长这样{ message: { role: assistant, content: , tool_calls: [ { function: { name: get_weather, arguments: { city: 北京, date: 2025-06-01 } } } ] } }这个结果跟预期完全一致。你可以看到同一个模型在工具定义“营养不良”时糊弄你在定义清晰后就能准确输出。后来我在多个模型上重复测试凡是出现“参数错乱”“该调不调”的八成以上可以通过改造工具定义解决而不是换模型。这个排查链路的核心思路是先绕开C#代码直接看Ollama原始返回再把变量拆开单独控制。很多问题混在一起时看着像玄学拆开之后就发现只是某个环节没对齐。5. 让ToolCall变“靠谱”的落地配置与代码模板5.1 工具定义写作规范这一节给出一个可以直接抄走的工具定义模板你照着这个结构写不敢说一定能保证100%稳定但能把大多数“笨”的问题挡在门外。规范提炼下来是四点函数名用英文驼峰描述用中文写清楚“什么时候该调用、调用后能解决什么问题”每个参数都要有description里面写清楚取值范围、格式、单位、不要用什么值能用枚举就不用自由字符串枚举值也要在description里列全避免过深的嵌套结构能拍平就拍平下面是一个标准模板new { type function, function new { name get_nearby_parks, description 根据城市和天气条件推荐适合晨跑的公园只有用户需要户外运动推荐时才调用, parameters new { type object, properties new { city new { type string, description 城市名称使用中文全称例如北京、上海 }, weather new { type string, description 天气状况取值晴朗、多云、小雨、大雨 } }, required new[] { city, weather } } } }注意description里我写了“只有用户需要户外运动推荐时才调用”这就是在告诉模型触发条件能显著减少“不该调也调”的情况。5.2 C#端调用循环的正确骨架工具调用的核心循环可以封装成一个通用方法五次到十次是合理上限。下面是适合直接复用的C#骨架代码注意消息顺序和tool_calls的累积判断。public static async Task RunToolLoopAsync( HttpClient client, string model, Listobject messages, IReadOnlyListobject tools, int maxTurns 5) { var options new JsonSerializerOptions { PropertyNamingPolicy JsonNamingPolicy.CamelCase, Converters { new JsonStringEnumConverter() } }; for (var turn 0; turn maxTurns; turn) { var payload new { model, messages, tools, stream false }; using var resp await client.PostAsJsonAsync(/api/chat, payload, options); var json await resp.Content.ReadFromJsonAsyncJsonNode(options); var msg json?[message]; var toolCalls msg?[tool_calls]?.AsArray(); if (toolCalls is null || toolCalls.Count 0) { Console.WriteLine(msg?[content]?.GetValuestring()); return; } messages.Add(new { role assistant, content msg?[content]?.GetValuestring() ?? }); foreach (var call in toolCalls) { var name call?[function]?[name]?.GetValuestring(); var argsNode call?[function]?[arguments]; if (argsNode is null) continue; var argsText argsNode.GetValueKind() JsonValueKind.String ? argsNode.GetValuestring() : argsNode.ToJsonString(options); var result await ExecuteToolAsync(name, argsText); messages.Add(new { role tool, content result }); } } throw new InvalidOperationException(工具调用超出最大轮次); }这段代码里有两个细节值得说明。一个是argsNode同时兼容了“字符串”和“对象”两种形态因为不同模型返回的arguments类型不稳定这点容错必须留。另一个是assistant消息必须在执行工具前加入messages这能让模型知道当前轮到它讲话了符合上一节说的角色顺序。5.3 模型、上下文与超时参数推荐最后说运行参数。Ollama默认上下文窗口不一定够用工具定义本身很占token模型要理解十几个工具的描述需要足够的窗口。我个人的经验值是至少把OLLAMA_NUM_CTX设到8192如果工具多直接上16384。推荐配置大概是这样模型优先选qwen2.5:14b或同级别7b也可以但工具数量控制在五个以内上下文窗口不低于8192工具数量控制在十个以内太多的话让模型先做意图分类再挂对应的工具子集单轮ToolCall循环上限五轮超时给到60秒以上本地模型推理慢别急着报错如果工具调用失败不要静默吞掉把原始返回JSON打到日志里方便定位是协议问题还是模型问题我个人的习惯是凡是工具调用相关需求先把工具定义和消息顺序写对再考虑换模型。模型永远是用力的下限你给它的协议越干净它才越稳定。做C#接入本身就是把API、序列化、消息编排这些后端能力变成模型的“脚手架”脚手架搭得越扎实模型“笨”的概率就越低。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
