shai工具调用4大模式解析:auto、fc、fc2、so分别适合什么场景?
shai工具调用4大模式解析:auto、fc、fc2、so分别适合什么场景?
shai 是一款用 Rust 编写的终端 AI 编程助手(coding agent),它内置 4 种工具调用模式:auto、fc、fc2、so。不同 LLM 对 Function Calling 的兼容性不同,选错模式可能导致工具"叫不动"或"乱调用"。本文带你快速搞懂 4 种模式的工作原理,并给出各模式最适场景的一页式选择指南。
shai 的 4 种工具调用模式一览
shai 的界面底部状态栏会实时显示当前模式。运行 shai 进入 TUI 后,可以看到类似这样的界面,右下角标注着 function call (auto):
4 种模式对应源码中的 ToolCallMethod 枚举:
| 模式 | 对应实现 | 工作原理 | 一句话定位 |
|---|---|---|---|
auto |
ToolCallMethod::Auto |
依次尝试 fc → fc2 → so,自动降级 | 省心首选 |
fc |
ToolCallMethod::FunctionCall |
调用 Function Calling API,tool_choice=auto |
标准模式 |
fc2 |
ToolCallMethod::FunctionCallRequired |
同上但 tool_choice=required,并注入 no_op 空操作工具 |
强制每轮都"表态" |
so |
ToolCallMethod::StructuredOutput |
不走 FC API,用 response_format JSON Schema 强制结构化输出 |
兼容性兜底 |
auto:智能降级,适合绝大多数场景
auto 模式的实现位于 chat_with_tools_try_all,逻辑是一条降级链:
- 先按
fc(auto 模式)请求,模型自己决定调不调工具; - 失败则按
fc2(required 模式)重试; - 再失败则回落到
so(结构化输出)。
适合场景:日常使用、不确定当前 LLM 供应商能力时的默认选择。你不需要关心模型支不支持 Function Calling,shai 会帮你找到可用的那条路。
fc:标准 Function Calling,适合主流模型
fc 模式通过 with_function_calling_auto 把工具列表以标准 tools 参数传给 API,并设置 tool_choice=auto。
- ✅ 模型"自愿"选择是否调用工具,行为最自然;
- ✅ 参数校验由 API 层完成,返回的
tool_calls结构规整; - ⚠️ 前提是模型和供应商真正支持 Function Calling(各供应商在 shai-llm/src/providers/ 中通过
supports_functions声明能力)。
适合场景:使用 OpenAI、Anthropic、Mistral 等对 Function Calling 支持成熟的主流模型时,直接选 fc 即可,这也是 shai 的默认配置。
fc2:强制调用模式,适合"模型偷懒不调工具"的疑难杂症
fc2 把 tool_choice 设为 required,强制模型每一轮都必须"调用"某个工具。关键细节在 NoOp 工具:shai 额外注入一个名为 no_op 的空操作工具,描述为"当不想调用任何工具时必须调用它"。模型选中 no_op 时,shai 会把这次调用抹掉(源码处理),于是模型依然可以正常只输出文字。
- ✅ 解决部分小模型在 auto 模式下"该调工具时不调"的问题——现在它每轮都必须表态;
- ✅ 借助
no_op逃生口,又不会误伤纯文字回复; - ⚠️ 每轮强制一次决策,个别模型可能产生多余的
no_op轮次。
适合场景:Agent 执行任务时发现模型明明需要读文件/跑命令却只用文字描述,可以切到 fc2 逼它"动手"。
so:结构化输出兜底,适合不支持 Function Calling 的模型
so 模式完全绕开 FC API:shai 把所有工具的名称、描述和 JSON Schema 文档拼进系统提示词(工具文档生成),再用 response_format 强制模型按 AssistantResponse 这个 Schema 返回 JSON,形如 { content, tools: [{ tool_name, tool_parameter }] },然后由 shai 自行解析成标准工具调用。
- ✅ 对不支持 Function Calling 的开源/小参数模型(如部分 Ollama 本地模型)非常有用;
- ✅ 输出结构由 Schema 严格约束,参数不会跑飞;
- ⚠️ 工具文档占用系统提示词 token,工具很多时开销更高;
- ⚠️ 依赖模型自身的指令遵循能力,表现通常略逊于原生 FC。
适合场景:本地 Ollama 模型、或某些 API 兼容性差的供应商出现"工具调不动"错误时,切换到 so 往往能直接救活。
如何切换模式:/tc 命令与配置文件
TUI 内即时切换
在 shai 界面输入斜杠命令即可热切换(无需重启,详见 TUI 命令文档):
/tc auto # 智能降级
/tc fc # 标准函数调用
/tc fc2 # 强制调用模式
/tc so # 结构化输出
实现见 command.rs 中的 /tc 分支。切换后状态栏会显示当前模式,fc2 和 so 还会带一个特殊前缀符号,方便快速确认。
在配置文件中持久化
每个 Provider 可以在 auth.config.json 中固定 tool_method:
{
"providers": [
{
"provider": "ovhcloud",
"model": "qwen3-32b-instruct",
"tool_method": "function_call" // auto | function_call | function_call_required | structured_output
}
]
}
自定义 Agent 也可以在 agent 配置 的 llm_provider 中单独指定,实现"不同模型不同模式":
echo "make me a hello world in main.py" | shai
配置保存后,用 /auth 重新应用即可。
场景速查表:我该选哪个?
| 你的情况 | 推荐模式 |
|---|---|
| 刚上手、不想折腾 | auto |
| 主流商业模型(OpenAI / Anthropic / Mistral)日常编码 | fc |
| 模型"光说不练",该调工具时不调 | fc2 |
| 本地 Ollama 小模型、API 不支持 FC、频繁报工具错误 | so |
💡 小贴士:先用 auto 跑通流程,再观察 /tools 和 /tokens 输出;如果发现某模型在降级链里绕了很远才成功,就把实测有效的模式写进配置文件固化下来。
延伸阅读:4 种模式的完整实现分别位于 call_fc_auto.rs、call_fc_required.rs、call_structured_output.rs,总调度入口在 call.rs。


