跳转到内容
NoviaHub 文档

使用指南

推理与思考

控制模型「想多久」：各协议原生的推理参数，以及 NoviaHub 的模型名修饰符 @thinking、@effort。

很多新模型在回答前会先「思考」一段时间。思考得越多，复杂问题答得越好，但耗时更长，Token 也更多、费用更高。

在 NoviaHub 上有两种方式控制思考：

  1. 用协议原生的参数：在请求体里写该协议自己的推理参数，NoviaHub 会把它交给模型。
  2. 用 NoviaHub 的模型名修饰符：在模型名后面加上 @effort:high 这样的后缀。好处是不用改请求体，只改模型名就行，适合那些只让你填模型名、不能加自定义参数的工具。

方式一：协议原生参数

Section titled “方式一：协议原生参数”
协议 参数 示例
OpenAI Chat Completions reasoning_effort "reasoning_effort": "low"
OpenAI Responses reasoning "reasoning": {"effort": "low"}
Anthropic Messages thinking（以及 output_config） 按 Anthropic 官方文档填写
Gemini generationConfig.thinkingConfig 按 Google 官方文档填写

在测试中，reasoning_effort 会原样转交给上游。每个模型接受哪些取值，由模型厂商决定，请参考对应厂商的文档。

方式二：模型名修饰符

Section titled “方式二：模型名修饰符”

在模型名后面接一个或多个 @键:值，例如：

deepseek-v4-flash@effort:high
claude-sonnet-5@thinking:off
deepseek-v4-flash@temperature:0.2@topp:0.9

NoviaHub 收到请求后，会先把这些后缀从模型名上去掉，再换算成目标模型能理解的参数。上游收到的模型名不带后缀。

可用的修饰符

Section titled “可用的修饰符”
修饰符 可选的值 作用
@effort: none、minimal、low、medium、high、xhigh、max 思考强度，从不思考到最大
@thinking: on、adaptive、off，或一个整数 开启 / 自适应 / 关闭思考；整数表示思考预算（Token 数），0 等同于关闭
@temperature: 数字，例如 0.2 等同于请求参数 temperature
@topp: 数字，例如 0.9 等同于请求参数 top_p

书写规则：

  • 修饰符必须写在模型名的末尾，可以连着写多个，顺序不限。
  • 同一个键写了两次时，以最后一个为准。
  • 键不区分大小写。
  • 修饰符优先于请求体：例如同时写了 @temperature:0.2 和请求参数 "temperature": 1，按 0.2 处理；写了 @effort 或 @thinking 时，请求体里原有的推理参数会被换成修饰符换算出的结果。
  • 写错时请求会失败，返回 HTTP 400，错误码 convert_request_failed。例如：
    • @foo:bar 会提示 unsupported model modifier "foo"；
    • @effort:huge 会提示 invalid effort modifier value "huge"。

它会被换算成什么

Section titled “它会被换算成什么”

下面是在测试环境里观察到的换算结果，也就是 NoviaHub 实际发给上游的参数。具体换算方式取决于目标模型支持哪种思考方式。

你写的 调用方式 上游收到的参数
deepseek-v4-flash@effort:high Chat Completions "reasoning_effort": "high"
gpt-6-sol@effort:low Responses "reasoning": {"effort": "low"}
claude-sonnet-5@effort:high Anthropic Messages "thinking": {"type": "adaptive"}、"output_config": {"effort": "high"}
gemini-3-flash@thinking:off Chat Completions "thinkingConfig": {"thinkingLevel": "minimal"}
deepseek-v4-flash@temperature:0.2@topp:0.9 Chat Completions "temperature": 0.2、"top_p": 0.9

有的模型不能完全关闭思考。例如 Gemini 3 系列：写 @thinking:off 或 @effort:none 时，NoviaHub 会改用该模型最低的思考档位（上表中的 minimal），而不是报错。

注意事项

Section titled “注意事项”
  • 在 Gemini 原生接口的地址里不能用修饰符。 Gemini 原生接口把模型名写在网址里（/v1beta/models/{模型}:generateContent），NoviaHub 会从第一个冒号处截断模型名。写成 gemini-3-flash@thinking:off:generateContent 会被当成模型 gemini-3-flash@thinking，返回 503「没有可用渠道」。用 Gemini 原生接口时，请改用请求体里的 thinkingConfig；或者改用 Chat Completions，把修饰符写在 model 字段里。
  • 计费按原模型。 目前 NoviaHub 没有给修饰符单独定价，按去掉后缀后的模型价格计费。使用日志里记录的也是去掉后缀的模型名，详情里的「推理强度」会显示本次使用的强度。开启思考后模型会多生成思考内容，这部分通常计入输出 Token，费用会相应增加。
  • API 密钥的「模型限制」按原模型判断。 例如一把只允许 deepseek-v4-flash 的密钥，也可以调用 deepseek-v4-flash@effort:high。
  • 有些模型名本来就以 -high、-low 结尾。 例如 NoviaHub 上的 gemini-3.6-flash-high、gemini-3.8-flash-high、gemini-3.1-pro-low，这些是完整的模型名，结尾的 -high、-low 不是修饰符，按原样填写即可。

旧式后缀写法

Section titled “旧式后缀写法”

为了兼容旧的用法，NoviaHub 也认得一些不带 @ 的后缀：

  • GPT 系列模型名后加 -none、-minimal、-low、-medium、-high、-xhigh、-max 这些强度词。例如 gpt-6-sol-high 等同于 gpt-6-sol@effort:high，测试中上游收到的是 "reasoning_effort": "high"。
  • Claude 模型名后加 -thinking，表示开启思考。这种写法是否生效取决于平台设置。

旧式写法更容易和真实模型名混淆，建议新接入时统一使用 @ 写法。