big-AGI LLM 参数验证指南:用 API 实测 Sweep 数据校准模型定义
big-AGI LLM 参数验证指南:用 API 实测 Sweep 数据校准模型定义
本指南讲解 big-AGI 开源仓库中一项关键的模型维护流程:LLM 参数验证(Verify LLM Parameters)。该流程以 API 实测生成的 Sweep 数据为权威基准,逐一核对模型定义文件(parameterSpecs、interfaces)中的参数能力,确保 UI 展示给用户的参数选项与厂商 API 真实接受的参数完全一致。读完本文,你将掌握 Sweep 数据与模型定义两种"真相来源"的对应关系、参数映射表、函数调用(fn)能力探针的判定规则,以及如何输出规范的验证报告,从而在新增或更新模型时避免向成千上万客户端暴露错误参数。
一、为什么需要参数验证:两种"真相来源"的对账
big-AGI 作为面向多厂商(OpenAI、Anthropic、Gemini、xAI、Meta AI 等)的 AI 套件,每个模型的能力描述同时存在于两处:
- Sweep 结果文件(参数值/取值范围的权威来源):
tools/develop/llm-parameter-sweep/llm-{dialect}-parameters-sweep.json。这些文件由仓库维护者通过 sweep.sh 实际调用厂商 API 逐参数探测后生成,运行耗时很长(每个厂商约 15 分钟)。 - 模型定义文件(面向用户与应用的权威来源):包含常量、接口(
interfaces)、受支持参数(parameterSpecs)以及部分参数的允许取值(enumValues)。五类方言对应文件如下:
验证任务的核心目标:对于 Sweep 中出现的每一个模型,确保模型定义暴露的能力与 Sweep 实测能力"不多不少、精确一致"。Sweep 的目的是给模型定义值提供线索,但对 big-AGI 而言,模型定义才是真正影响成千上万客户端行为的依据,必须谨慎更新,否则可能导致大量客户端请求携带非法参数而失败。
二、Sweep 数据从何而来:sweep 工具链
要理解验证对象,先了解数据源头。sweep.sh 是一个轻量 Shell 包装器:设置 SUPPRESS_FETCHER_LOGS=1 抑制服务端抓取器的噪声日志后,通过 npx -y tsx 直接运行 sweep.ts(免本地安装,按需下载)。
# 运行完整 sweep(非常耗时,每厂商约 15 分钟)
tools/develop/llm-parameter-sweep/sweep.sh --config path/to/sweep-config.json
sweep.ts 的探测逻辑在源码中有明确实现:
- 遍历顺序:
vendors -> models -> sweep parameters -> parameter values,为每个值构造最小化请求(提示词固定为just say \hi`)并上报通过/失败(见 <a href="https://link.gitcode.com/i/deac0327b5a374ec2bc28404d0dcb26a" target="_blank">sweep.ts</a> 的testParameterValue`)。 - 内置 Sweep 定义(
SWEEP_DEFINITIONS,sweep.ts):如 OpenAI 的oai-reasoning-effort(枚举none/minimal/low/medium/high/xhigh/max)、Anthropic 的ant-effort(low/medium/high/xhigh/max)、Gemini 的gemini-thinking-level(minimal/low/medium/high)、gemini-thinking-budget(0/1024/16384/24576/32768/65535)、xAI 的xai-web-search(auto)、Meta 的metaai-reasoning-effort等。 - neutered 判定:若某参数所有通过的取值都属于"默认值/空操作值"(如 reasoning 只通过
medium默认值),则认为该参数并未被真正支持,会被从结果中剔除(isSweepNeutered,sweep.ts)。 - 线缆保真检查(preflightFail):当适配器"热修复"会静默改写参数时(如 Anthropic 自适应模型把 thinking 强制转为
adaptive、把tool_choice: any降级为auto),sweep 会直接记为失败而不浪费 API 调用,避免"假通过"污染数据。 - 结果写入:最终通过
saveDialectResults写入llm-{dialect}-parameters-sweep.json,文件头附带_comment、_evaluated、_modelFilter元数据;连续数值区间(如 temperature)会被折叠为-range数组;图片生成与 Web 搜索等"工具型"参数全量通过时进入tools数组。
配置文件模板见 sweep-config.template.json,可指定各厂商的 API 密钥、modelFilter、sweeps 列表与 baseModelOverrides(如 OpenAI 的 maxTokens: 4096,避免推理模型在探测完成前烧光 token 预算)。
三、验证范围与操作入口
验证命令本体是仓库内 .claude/commands/llms/ 下的开发指令,面向维护者(本指南所依据的指令原文即 verify-parameters.md)。其使用方式为:
Verify LLM Parameters —— 比较模型定义文件中的 parameterSpecs 与 API 实测 Sweep 数据
参数提示:openai | anthropic | gemini | xai | metaai(留空则验证全部五个方言)
执行规则:
- 若提供
$ARGUMENTS:只验证对应方言,读取该方言的"一对"文件——sweep 结果 JSON 与模型定义 TS; - 若留空:依次验证全部五个方言,按顺序读取五对文件。
验证时逐模型核对以下几项(不多不少):
- 该参数是否存在于模型的
parameterSpecs中; paramId变体的枚举值是否精确覆盖 Sweep 中的取值(若适用);interfaces中的LLM_IF_OAI_Fn是否与 Sweep 的fn数组中的"roundtrip"匹配(详见下节);- 其余能力项(如工具型参数
oai-image-generation、oai-web-search对应的tools数组)。
最后报告所有定义与 Sweep 不一致的模型。
四、参数映射表:Sweep Key 与模型 paramId 的对应
Sweep 结果文件中的键名(Sweep Key)与模型定义中的 paramId 命名不同,验证时必须按下表映射。注意:新参数可能同时被加入定义与 Sweep,映射表并非穷尽,应以最新文件为准。
| 方言 | Sweep Key | 模型 paramId |
|---|---|---|
| OpenAI | oai-reasoning-effort |
llmVndOaiEffort |
| OpenAI | oai-reasoning-mode |
llmVndOaiReasoningMode |
| OpenAI | oai-verbosity |
llmVndOaiVerbosity |
| OpenAI | oai-image-generation |
llmVndOaiImageGeneration |
| OpenAI | oai-web-search |
llmVndOaiWebSearchContext |
| Anthropic | ant-effort |
llmVndAntEffort |
| Anthropic | ant-thinking-budget |
llmVndAntThinkingBudget |
| Gemini | gemini-thinking-level |
llmVndGemEffort |
| Gemini | gemini-thinking-budget |
llmVndGeminiThinkingBudget |
| xAI | xai-web-search |
llmVndXaiWebSearch |
| Meta | metaai-reasoning-effort |
llmVndOaiEffort |
| Meta | metaai-web-search |
llmVndOaiWebSearchContext |
从源码可以印证:Anthropic 定义文件 anthropic.models.ts 顶部注释明确 llmVndAntEffort 对应 Anthropic effort,且"各模型通过 enumValues 声明自己的子集"(如 4.7 新增 xhigh);OpenAI 定义文件 openai.models.ts 中 llmVndOaiEffort 的 enumValues 按模型从 ['low','medium','high','xhigh','max'] 到 ['none','low','medium','high','xhigh','max'] 各不相同,甚至存在 hidden: true 的"出厂固定值"场景——这些细节正是验证要重点对账的对象。
五、函数调用能力(fn)探针:roundtrip 是权威信号
Sweep 的 fn 数组是能力探针(capability probe),不是 paramId。其取值由 sweep.ts 中的 TOOL_PROBE_DEFINITIONS 产生:
"auto":单工具、toolsPolicy: auto,模型真实发出参数合法的工具调用(校验函数名与location参数);"required":单工具、toolsPolicy: any(强制工具调用);"roundtrip":权威信号——第一轮模型发出工具调用后,注入预设的工具响应并重新派发第二轮,必须产出连贯文本且文本包含预设信号词(如天气探针的cloudy、18),证明模型真正消费了工具结果,而非忽略或循环调用。该探针需要两次 API 调用。
验证判定规则:
- 必须绑定:
interfaces中的LLM_IF_OAI_Fn必须与fn数组中的"roundtrip"同步存在——Sweep 有"roundtrip"而定义缺LLM_IF_OAI_Fn,或定义有LLM_IF_OAI_Fn而 Sweep 无"roundtrip",均为不一致,需标记; - 部分能力要指出:
fn包含"auto"/"required"但没有"roundtrip"时,属于"部分能力"(能发起工具调用,但无法可靠完成工具结果的消费闭环),必须在报告中单独点名。
从实际数据看,llm-openai-parameters-sweep.json 中 gpt-6-astra 的 fn 为 <a href="https://link.gitcode.com/i/f7ce3563acf3d6b226fd0e9d13e7bcc2" target="_blank">"auto","required","roundtrip"](完整能力),而 [llm-anthropic-parameters-sweep.json 中 claude-fable-5 的 fn 仅为 ["auto","roundtrip"](缺少 required,即不支持强制工具调用,定义侧不可暴露强制工具选择能力)——这类差异正是验证时需要在表格中列出的具体问题。
六、输出规范:期望值 → 实际值 → 差异表
验证完成后,报告必须按以下结构输出,保证可审计、可追溯:
- 期望值:先对每个模型列出 Sweep 中的期望取值(哪些参数、哪些值/值域、
fn探针结果); - 实际值:再列出模型定义文件中的实际取值(
parameterSpecs的enumValues、interfaces的接口集合); - 差异:逐项列出两者之间的不一致点;
- 汇总表:最后为每个方言生成一张表格,列出所有存在差异的模型及具体问题(如"缺 paramId X""enumValues 多出值 Y""LLM_IF_OAI_Fn 缺失"等)。
建议的汇总表结构:
| 方言 | 模型 | 差异类型 | 具体问题 |
|---|---|---|---|
| openai | gpt-... | 参数缺失 | Sweep 有 oai-verbosity,定义中无 llmVndOaiVerbosity |
| anthropic | claude-... | 枚举不一致 | 定义含 'xhigh',Sweep 仅通过 low/medium/high |
| gemini | gemini-... | 接口缺失 | Sweep fn 含 roundtrip,interfaces 缺 LLM_IF_OAI_Fn |
| ... | ... | ... | ... |
七、验证要点与注意事项
- 以最新文件为准:新参数可能已同时进入定义与 Sweep,验证前先确认两边的文件都是仓库最新状态;
- "不多不少"原则:定义暴露的能力既不能少于 Sweep 实测通过的能力(功能缩水),也不能多于 Sweep 实测通过的能力(向客户端暴露 API 会拒绝的选项);
- 区分值域与枚举:Sweep 中连续数值参数(如 temperature、thinking-budget)被折叠为
-range两元数组([min, max]),而离散枚举保持列表形式,验证时要按paramId的语义(枚举 vs 范围)分别核对; - 面向用户的价值:模型定义直接决定 big-AGI 客户端的参数选择器(UI 上能选哪些 effort、verbosity、web-search 选项)与发送给厂商的请求载荷,校准它等于校准所有下游客户端的体验与稳定性;
- 来源约束:Sweep 由
sweep.sh独立运行产生(需要各厂商真实 API 密钥与配额),验证流程本身只读比对文件、输出报告,不修改仓库内容。
通过本指南的核对流程,你可以系统性地发现模型定义与 API 实测能力之间的漂移——无论是厂商新增了参数取值(如 GPT-5.6+ 的 xhigh/max reasoning 档位)、某模型收紧了能力(如不再支持强制工具调用),还是定义文件引入了笔误,都能在影响客户端之前被准确定位并修正。