给 Agent 接入新模型的推理模式:从配置开关到协议适配

最近我们给一个 agent 系统接入了新的推理模型。

一开始我以为这会是个很小的工作:模型本身能调通,又是 OpenAI-compatible,按经验补几个配置项,前端把思考模式打开,应该就差不多了。

真正做下来才发现,事情没这么简单。

问题不在"模型能不能回答",而在agent 怎么把模型的推理模式接进自己的多轮对话、工具调用和历史消息链路里 。

这篇文章想讲的就是这件事:给 agent 系统接入一个新模型的 reasoning 模式,到底要改哪些层,代码上又是怎么落地的。


背景:为什么 agent 接入 reasoning 模式比普通聊天更麻烦

如果只是做一个简单聊天页面,很多模型的 reasoning 模式无非是多传一个参数。

比如:

json 复制代码
{
  "extra_body": {
    "thinking": {
      "type": "enabled"
    }
  }
}

或者:

json 复制代码
{
  "enable_thinking": true
}

但 agent 场景不一样。

agent 的一次任务往往会经历这几个步骤:

  1. 用户发消息
  2. 模型决定是否调用工具
  3. 工具返回结果
  4. 模型继续推理
  5. 历史消息被写入线程状态
  6. 下一轮请求再把这些历史发回模型

这时候,reasoning 模式就不只是"这一轮开不开"的问题了。你还得保证:

  • 模型返回的推理字段能被解析出来
  • 这些字段能跟消息一起保存
  • 下一轮重放历史时字段不会丢
  • 前端知道这个模型支持哪些推理档位

所以在 agent 里,reasoning 支持本质上是一条链路,不是一个开关。


这类适配一般要做四层

这次做完以后,我觉得给 agent 接新模型的推理模式,基本都绕不开四层:

  1. 能力声明层

    告诉系统这个模型支不支持 thinking、支不支持 reasoning effort

  2. 响应解析层

    把 provider 返回的推理字段解析出来,放到统一的内部结构里

  3. 历史重放层

    下一轮请求时,把这些推理字段再带回去

  4. 历史兼容层

    旧线程里可能已经有不完整的历史消息,要能兜住

下面就按这四层展开讲。


第一层:先把模型能力声明清楚

这是最表面的一层,但也是最容易漏的。

我们前端之所以会显示 Thinking / Pro / Ultra,不是因为模型"看起来很强",而是因为后端模型配置明确声明了这些能力。

像这次给两个 MIMO 模型开的配置,大概是这样:

yaml 复制代码
- name: mimo-v2-5-pro
  display_name: MiMo-V2.5-Pro
  use: deerflow.models.patched_mimo:PatchedMimoChatModel
  model: mimo-v2.5-pro
  api_key: $MIMO_API_KEY
  base_url: $MIMO_BASE_URL
  max_tokens: 4096
  temperature: 0.7
  supports_thinking: true
  supports_reasoning_effort: true
  when_thinking_enabled:
    extra_body:
      thinking:
        type: enabled
  when_thinking_disabled:
    extra_body:
      thinking:
        type: disabled
    reasoning_effort: minimal
  stream_usage: true

这里有两个关键信号:

  • supports_thinking: true
  • supports_reasoning_effort: true

前者决定这个模型能不能开思考模式。

后者决定前端能不能把 Pro / Ultra 这种强度档位开放出来。

然后运行时工厂会根据这些配置,拼出真正的模型参数:

python 复制代码
if thinking_enabled and has_thinking_settings:
    if not model_config.supports_thinking:
        raise ValueError(...)
    if effective_wte:
        model_settings_from_config.update(effective_wte)

if not thinking_enabled:
    if model_config.when_thinking_disabled is not None:
        model_settings_from_config.update(model_config.when_thinking_disabled)

也就是说,这一层的作用其实有两个:

  • 控制后端怎么发请求
  • 控制前端怎么展示模式

如果这里不补,哪怕底层 provider 已经支持 reasoning,页面上也还是只能看到 flash。


第二层:把 provider 返回的推理字段真正接住

接下来才是核心问题。

这次我们遇到的 provider 会在 assistant message 里返回 reasoning_content。

如果不做特殊处理,默认的 ChatOpenAI 会把正常 content 保留下来,但这个 provider-specific 字段会被忽略。

所以第一步是:在响应解析阶段把它接住。

我们最后做法是加一个专门的适配类 PatchedMimoChatModel,继承 ChatOpenAI,只补 MIMO 这条协议需要的部分。

先看非流式响应的处理:

python 复制代码
def _create_chat_result(
    self,
    response: dict | Any,
    generation_info: dict | None = None,
) -> ChatResult:
    result = super()._create_chat_result(response, generation_info)
    response_dict = response if isinstance(response, dict) else response.model_dump()
    choices = response_dict.get("choices", [])

    generations: list[ChatGeneration] = []
    for index, generation in enumerate(result.generations):
        choice = choices[index] if index < len(choices) else {}
        message = generation.message
        if isinstance(message, AIMessage):
            choice_message = choice.get("message", {}) if isinstance(choice, dict) else {}
            reasoning_content = choice_message.get("reasoning_content")

            if isinstance(reasoning_content, str) and reasoning_content.strip():
                message = _with_reasoning_content(message, reasoning_content)
                generation = ChatGeneration(
                    message=message,
                    generation_info=generation.generation_info,
                )

        generations.append(generation)

    return ChatResult(generations=generations, llm_output=result.llm_output)

关键点就一个:

把 provider 返回的 message.reasoning_content 映射到内部消息对象的 additional_kwargs 上。

这样消息在系统里就变成了:

python 复制代码
AIMessage(
    content="...",
    additional_kwargs={
        "reasoning_content": "..."
    }
)

这一步很重要,因为后面所有逻辑都基于这个统一结构继续走。


第三层:流式场景也要保住 reasoning 内容

非流式场景处理好了还不够,很多 agent 默认是流式输出。

而流式场景下,reasoning_content 不是一次性返回的,而是跟普通文本一样分 chunk 回来。

所以如果只改 _create_chat_result(),第一轮看起来可能没问题,但流式过程中 reasoning 其实还是会悄悄丢掉。

所以还要补流式 chunk 处理:

python 复制代码
def _convert_chunk_to_generation_chunk(
    self,
    chunk: dict,
    default_chunk_class: type,
    base_generation_info: dict | None,
) -> ChatGenerationChunk | None:
    choices = chunk.get("choices", []) or chunk.get("chunk", {}).get("choices", [])
    if len(choices) == 0:
        return ChatGenerationChunk(
            message=default_chunk_class(content=""),
            generation_info=base_generation_info,
        )

    choice = choices[0]
    delta = choice.get("delta")
    if delta is None:
        return None

    message_chunk = _convert_delta_to_message_chunk(delta, default_chunk_class)

    if isinstance(message_chunk, AIMessageChunk):
        if isinstance(delta.get("reasoning_content"), str) and delta["reasoning_content"].strip():
            message_chunk = _with_reasoning_content(
                message_chunk,
                delta["reasoning_content"],
                preserve_whitespace=True,
            )

    return ChatGenerationChunk(
        message=message_chunk,
        generation_info=base_generation_info,
    )

这里做的事也不复杂:

  • 读每个 delta 里的 reasoning_content
  • 把它不断追加到 AIMessageChunk.additional_kwargs["reasoning_content"]

这一步补上之后,流式推理内容和最终消息对象就能对齐了。


第四层:下一轮请求时,把 reasoning 内容带回去

这次真正让问题暴露出来的,其实不是响应解析,而是多轮历史重放。

MIMO 的报错很明确:

text 复制代码
The reasoning_content in the thinking mode must be passed back to the API.

也就是说,模型不光要求你接住上一轮的 reasoning_content,还要求你下一轮把它原样带回去。

这一步就不能只靠配置解决了,因为默认的 ChatOpenAI 在组装历史消息 payload 时,不会自动把 additional_kwargs["reasoning_content"] 再写回 assistant message。

所以我们在 _get_request_payload(...) 里补了这段逻辑:

python 复制代码
def _get_request_payload(
    self,
    input_: LanguageModelInput,
    *,
    stop: list[str] | None = None,
    **kwargs: Any,
) -> dict:
    original_messages = self._convert_input(input_).to_messages()
    payload = super()._get_request_payload(input_, stop=stop, **kwargs)

    payload_messages = payload.get("messages", [])

    if len(payload_messages) == len(original_messages):
        for payload_msg, orig_msg in zip(payload_messages, original_messages):
            if payload_msg.get("role") == "assistant" and isinstance(orig_msg, AIMessage):
                _restore_reasoning_content(payload_msg, orig_msg)
    else:
        ai_messages = [m for m in original_messages if isinstance(m, AIMessage)]
        assistant_payloads = [m for m in payload_messages if m.get("role") == "assistant"]
        for payload_msg, ai_msg in zip(assistant_payloads, ai_messages):
            _restore_reasoning_content(payload_msg, ai_msg)

    payload["messages"] = _drop_legacy_messages_missing_reasoning(payload_messages)
    return payload

其中 _restore_reasoning_content(...) 很直接:

python 复制代码
def _restore_reasoning_content(payload_msg: dict, orig_msg: AIMessage) -> None:
    reasoning_content = orig_msg.additional_kwargs.get("reasoning_content")
    if reasoning_content is not None:
        payload_msg["reasoning_content"] = reasoning_content

这就是整个适配里最关键的一步:

从内部消息对象里取出 reasoning_content,重新写回 provider 期望的 payload 格式。

做到这里,新生成的消息链路才算完整闭环:

  • provider 返回 reasoning_content
  • 我们存下来
  • 下一轮请求再带回去

最麻烦的部分:旧线程里的历史消息怎么办

如果所有线程都是新开的,做到上面基本就够了。

但真实系统里通常不是这样。

这次我们很快就碰到了一个很现实的问题:老线程里已经存在一批旧消息了。

这些消息是在补丁上线前生成的,当时系统还不会保存 reasoning_content。

于是就会出现这种情况:

  • 新代码已经能正确保存和回传 reasoning 字段
  • 但旧线程里某条 assistant message 还是缺字段
  • 下一轮请求一重放这条历史,provider 继续报 400

这类问题很烦,因为它不是"当前代码错了",而是"历史数据不完整"。

我们的处理方式比较务实:
遇到这种不满足新协议的 legacy assistant turn,就在重放时跳过它。

代码是这样的:

python 复制代码
def _drop_legacy_messages_missing_reasoning(payload_messages: list[dict]) -> list[dict]:
    cleaned: list[dict] = []
    skipped_tool_call_ids: set[str] = set()

    for message in payload_messages:
        role = message.get("role")

        if role == "tool":
            tool_call_id = message.get("tool_call_id")
            if isinstance(tool_call_id, str) and tool_call_id in skipped_tool_call_ids:
                continue
            cleaned.append(message)
            continue

        if role == "assistant" and not _has_reasoning_content(message):
            for tool_call in message.get("tool_calls") or []:
                if isinstance(tool_call, dict):
                    tool_call_id = tool_call.get("id")
                    if isinstance(tool_call_id, str) and tool_call_id:
                        skipped_tool_call_ids.add(tool_call_id)
            continue

        cleaned.append(message)

    return cleaned

这段逻辑做了两件事:

  1. 如果旧的 assistant message 没有 reasoning_content,跳过它
  2. 如果它还带了 tool call,把对应的 tool message 一起跳过

这不是最"完美"的方案,但它能解决一个非常实际的问题:
不让旧线程永远卡死在协议错误上。


最后一步:把前端模式也接上

底层协议补完之后,前端还要能把模式显示出来。

我们前端的逻辑大致是这样的:

ts 复制代码
const supportThinking = selectedModel?.supports_thinking ?? false;
const supportReasoningEffort =
  selectedModel?.supports_reasoning_effort ?? false;

模式切换时会把不同 UI 选项映射成不同的 reasoning effort:

ts 复制代码
reasoning_effort:
  mode === "ultra"
    ? "high"
    : mode === "pro"
      ? "medium"
      : mode === "thinking"
        ? "low"
        : "minimal"

所以只要后端模型列表把这两个能力位透出来:

  • supports_thinking
  • supports_reasoning_effort

前端自然就知道该不该显示:

  • Thinking
  • Pro
  • Ultra

这也是为什么这次除了 provider 适配本身,我们还专门补了模型配置和回归测试。


这次我们怎么验证

这类改动如果只测 happy path,其实很容易出假阳性。

所以这次验证我比较看重三件事:

1. 配置能力是不是正确透出

直接测模型配置,确保两个 MIMO 模型声明了 thinking 和 reasoning effort 支持。

2. provider 适配是不是完整

分别测:

  • 非流式 reasoning_content 解析
  • 流式 chunk 中 reasoning_content 的保留
  • 下一轮请求的回传

3. 旧线程是不是不会再炸

这一步最关键。

我们用旧 thread id 复测过,确认原来的 400 reasoning_content must be passed back 已经消失,剩下的是 provider 自己的额度错误。这说明协议层的问题已经摘掉了。


结尾

这次做完之后,我最大的感受是:

给 agent 接入新模型的推理模式,重点不在"模型能不能回答",而在"它的推理协议能不能进入系统的完整生命周期"。

要接住的不只是一个开关,还包括:

  • 响应解析
  • 历史保存
  • 多轮重放
  • 旧数据兼容
  • 前端能力展示

这些层都打通了,才能说这个模型在 agent 里真正支持了 reasoning。

相关推荐
苍何5 分钟前
不用 Opus5.5 ,即梦也能出爆款 vibe 视频了
后端
SimonKing14 分钟前
WorkBuddy又推出新的限免模型(Hy4 flash)了,羊毛可以薅起来了
java·后端·程序员
Rain的Java大神之路27 分钟前
别再死背"三级缓存"了!拿 Spring 7.0.8 源码,把 IoC、AOP、事务、循环依赖四大深水区一次蹚平
java·后端·面试
wno70438 分钟前
springboot整合FastDFS
java·spring boot·后端
程序猿DD7 小时前
OctaFuse 2.20.0:MCP 用业务账号直接登录授权,请求日志合并工具调用
后端
特立独行的猫A9 小时前
别再用 nohup 了:让应用在后台常驻的正确姿势与 systemd 服务详解
java·后端·python
一起_java9 小时前
技术文章-基于Dify-Agent的智能问答系统设计与实现
java·spring boot·后端·agent·dify
码事漫谈11 小时前
2027年火的很可能是AI工作台
后端
伯奥克客服14 小时前
2026年视频综合一体机架构选型:从接口协议到流媒体底层的深度技术解析
架构·音视频
starzy199014 小时前
深入理解Scala隐式函数:自动类型转换
开发语言·后端·scala