big-AGI LLM 参数验证指南:用 API 实测 Sweep 数据校准模型定义

原创2026-09-16 10:50:251,389 阅读
文章标签:AI 应用人工智能大模型前端后端AI AgentRAG

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 套件,每个模型的能力描述同时存在于两处:

  1. Sweep 结果文件(参数值/取值范围的权威来源):tools/develop/llm-parameter-sweep/llm-{dialect}-parameters-sweep.json。这些文件由仓库维护者通过 sweep.sh 实际调用厂商 API 逐参数探测后生成,运行耗时很长(每个厂商约 15 分钟)。
  2. 模型定义文件(面向用户与应用的权威来源):包含常量、接口(interfaces)、受支持参数(parameterSpecs)以及部分参数的允许取值(enumValues)。五类方言对应文件如下:
方言 模型定义文件
OpenAI src/modules/llms/server/openai/models/openai.models.ts
Anthropic src/modules/llms/server/anthropic/anthropic.models.ts
Gemini src/modules/llms/server/gemini/gemini.models.ts
xAI src/modules/llms/server/openai/models/xai.models.ts
Meta AI src/modules/llms/server/openai/models/metaai.models.ts

验证任务的核心目标:对于 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;
  • 若留空:依次验证全部五个方言,按顺序读取五对文件。

验证时逐模型核对以下几项(不多不少):

  1. 该参数是否存在于模型的 parameterSpecs 中;
  2. paramId 变体的枚举值是否精确覆盖 Sweep 中的取值(若适用);
  3. interfaces 中的 LLM_IF_OAI_Fn 是否与 Sweep 的 fn 数组中的 "roundtrip" 匹配(详见下节);
  4. 其余能力项(如工具型参数 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,即不支持强制工具调用,定义侧不可暴露强制工具选择能力)——这类差异正是验证时需要在表格中列出的具体问题。

六、输出规范:期望值 → 实际值 → 差异表

验证完成后,报告必须按以下结构输出,保证可审计、可追溯:

  1. 期望值:先对每个模型列出 Sweep 中的期望取值(哪些参数、哪些值/值域、fn 探针结果);
  2. 实际值:再列出模型定义文件中的实际取值(parameterSpecs 的 enumValues、interfaces 的接口集合);
  3. 差异:逐项列出两者之间的不一致点;
  4. 汇总表:最后为每个方言生成一张表格,列出所有存在差异的模型及具体问题(如"缺 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 档位)、某模型收紧了能力(如不再支持强制工具调用),还是定义文件引入了笔误,都能在影响客户端之前被准确定位并修正。

登录后查看全文
big-AGI