AI Agent / 系统课时

设计模型接入层

设计模型接入层

本节解决 Agent 业务逻辑直接依赖具体模型 API 导致难以替换、测试和扩展的问题。通过设计统一 ModelClient 与 Provider Adapter,将鉴权、请求格式、流式输出和工具调用能力封装起来,让 Agent Core 面向稳定接口开发。

学习目标

  • 理解模型接入层在 Agent 架构中的职责边界。
  • 掌握 ModelClient 与 Provider Adapter 的分层设计方式。
  • 能够实现支持多模型切换的基础调用接口。

分离 Agent Core 与模型实现

Agent Core 关注任务规划、状态管理和工具编排,不应该知道当前使用的是哪一家模型服务。

如果核心代码直接调用某个 SDK,会产生以下问题:

  • 更换模型需要修改大量业务代码。
  • 不同模型的鉴权和参数处理散落在各处。
  • 测试时难以替换真实模型。

模型接入层的目标是提供稳定抽象:上层只关心发送消息和获取结果,下层负责适配不同 Provider。

模型接入层分层结构示意图

定义统一 ModelClient 接口

ModelClient 是 Agent 使用的统一入口,它隐藏不同模型服务之间的差异。

一个基础接口可以包含消息发送、流式响应和工具调用参数。

python
from abc import ABC, abstractmethod

class ModelClient(ABC):
    @abstractmethod
    def chat(self, messages: list[dict]) -> str:
        """发送消息并返回模型文本结果"""
        pass


class AgentService:
    def __init__(self, client: ModelClient):
        self.client = client

    def run(self, task: str) -> str:
        return self.client.chat([
            {"role": "user", "content": task}
        ])

预期输出

text
AgentService 只依赖 ModelClient 接口,不依赖具体模型 SDK

接口定义后,Agent Core 可以稳定运行,模型替换只影响实现层。

使用 Provider Adapter 适配模型差异

不同模型服务通常存在请求字段、鉴权方式和返回结构差异,因此需要 Adapter 转换。

例如某个 Provider 返回:

json
{
  "response": "hello"
}

另一个 Provider 可能返回:

json
{
  "choices": [
    {
      "text": "hello"
    }
  ]
}

Adapter 负责把这些差异转换成统一结果。

python
class ProviderAdapter(ModelClient):
    def __init__(self, api_client):
        self.api_client = api_client

    def chat(self, messages: list[dict]) -> str:
        result = self.api_client.generate(messages)
        return result["text"]

预期结果

text
上层收到统一字符串结果,不感知 Provider 返回格式

处理流式输出与工具调用

Agent 场景中,模型能力不仅是文本生成,还包括流式输出和工具调用。

因此接口设计时需要预留扩展能力:

  • 普通对话返回完整结果。
  • 流式模式返回增量内容。
  • 工具调用返回结构化动作请求。

不要把所有能力强行塞进一个简单字符串接口,否则后续扩展会重新修改核心代码。

推荐将结果封装为统一对象:

python
from dataclasses import dataclass

@dataclass
class ModelResponse:
    content: str
    tool_calls: list[dict]
    finished: bool

预期输出

text
ModelResponse(content='...', tool_calls=[], finished=True)

验证模型接入层设计

完成抽象后,可以通过模拟 Provider 测试 Agent Core,而无需调用真实模型服务。

python
class FakeModel(ModelClient):
    def chat(self, messages: list[dict]) -> str:
        return "test response"

agent = AgentService(FakeModel())
print(agent.run("hello"))

预期输出

text
test response

如果未来更换模型,只需要新增新的 Adapter,并保持 ModelClient 接口不变。

本课总结

  • ModelClient 负责提供稳定调用协议,Provider Adapter 负责隐藏模型差异。
  • Agent Core 不应直接依赖具体模型 SDK,否则会降低扩展能力。
  • 流式输出和工具调用需要在接口设计阶段预留扩展空间。

下一课预告

下一节将继续完善 Agent 工程架构,设计工具调用与执行模块,让模型能够安全访问外部能力。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计模型接入层

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通