教学框架与多供应商:统一流程,同时保留能力差异
设计模型抽象类、消息契约、工具注册和能力检测,使ReAct、工作流与多Agent复用同一执行边界。
第一次接入模型时,业务函数里直接拼HTTP请求很快。第二个供应商加入后,响应字段、工具调用、流式事件和usage开始分叉;第三个Agent又复制一次判断逻辑。教学框架应把这些差异集中在适配层,同时让读者看得见控制流,而不是把关键机制藏进一个万能run函数。
抽象基类定义契约,不掩盖能力
模型接口可以表达invoke、stream以及关闭资源的方法,但不应强迫每个后端伪造全部能力。不支持流式时,是显式拒绝还是整段结果包装成单事件,必须在返回契约说明;后者不具备首Token延迟优势。同步和异步应有明确实现,不能在已有事件循环内随意asyncio.run。
Python抽象基类可以防止漏实现方法,Protocol便于结构化适配和测试;二者都不能自动保证返回值语义。仍需契约测试检查文本、工具请求、完成原因、错误与使用量。类型注解不是外部JSON的运行时校验。
内部Message至少保留role、内容块、调用ID和来源。供应商原始响应可作为受控调试信息保留,但不要让业务逻辑依赖某个raw字段。配置把模型名称、base URL、超时、重试策略和能力快照分开,凭据不放消息历史,也不打印进repr。
能力是三态、带版本的事实
能力至少区分支持、不支持、待验证。HTTP200和模型名字包含chat,都不能证明工具调用或严格schema有效。应为模型ID、供应商、接口版本和部署配置保存能力测试结果:工具参数是否完整、是否保留call ID、流式结束标记如何返回、拒绝或截断如何表达。
有些后端接受参数却忽略,或者只能做到JSON语法而非schema约束。适配器静默删掉不支持的参数,会让调用方误以为要求已生效。对影响正确性的能力应提前拒绝;可选能力允许显式降级,并把降级原因写入运行记录。
例如Ollama原生chat与兼容Chat Completions的响应形状不同。统一输出可以抽取文本,但还要保留工具调用、结束状态和usage。不同供应商的Token计数、缓存费用和错误码也不能直接拼成同一数字而不标单位与来源。
工具注册与范式复用
注册表用稳定名称定位工具实现,拒绝重复名称,维护参数模式、权限分类和版本。模型看到的描述来自注册表,但执行器从可信表取函数,不从模型输出动态导入代码。先校验参数,再用应用身份授权,执行后把结构化结果和调用ID放回消息。
ReAct循环、确定性工作流和多Agent调度都可调用同一模型适配器与工具执行器;差异应留在“下一步由谁决定”和“状态如何更新”。若每一种范式都独立实现鉴权和重试,修复一处漏洞很难覆盖其他路径。
生命周期还包括资源初始化、连接复用和关闭。工具结果可缓存,但必须把身份范围、参数、工具版本和数据时效纳入键;模型响应缓存还需考虑随机性与消息模板版本。不能把复用解释为全局共享可变历史。
跟做:统一输出,拒绝未经验证的工具能力
保存 provider_adapter.py 后用Python 3.11+运行 python provider_adapter.py。两个供应商类返回固定字典,不发送网络请求。抽象类和能力拒绝真实执行,响应只是教学夹具,不声称覆盖供应商完整协议。
"""自定义教学接口;两个供应商都是假响应,不模拟网络性能。"""
from abc import ABC, abstractmethod
from dataclasses import dataclass
@dataclass(frozen=True)
class Request:
text: str
needs_tools: bool = False
class Adapter(ABC):
tools: bool | None = None
def invoke(self, request):
if request.needs_tools and self.tools is not True:
raise ValueError('tool support not verified')
return self.normalize(self.send(request))
@abstractmethod
def send(self, request): ...
@abstractmethod
def normalize(self, raw): ...
class ChatFixture(Adapter):
tools = True
def send(self, request):
return {'choices': [{'message': {'content': 'echo:' + request.text}}]}
def normalize(self, raw):
return raw['choices'][0]['message']['content']
class LocalFixture(Adapter):
tools = None
def send(self, request):
return {'message': {'content': 'echo:' + request.text}}
def normalize(self, raw):
return raw['message']['content']
class Registry:
def __init__(self):
self.tools = {}
def register(self, name, fn):
if name in self.tools:
raise ValueError('duplicate tool')
self.tools[name] = fn
if __name__ == '__main__':
for provider in [ChatFixture(), LocalFixture()]:
print(type(provider).__name__, provider.invoke(Request('hello')))
try:
LocalFixture().invoke(Request('search', True))
except ValueError as error:
print(str(error))
registry = Registry()
registry.register('add', lambda a, b: a + b)
print('registered add:', registry.tools['add'](2, 3))实际输出:
ChatFixture echo:hello
LocalFixture echo:hello
tool support not verified
registered add: 5相同Request得到相同内部文本,但原始响应形状不同。LocalFixture的tools为None,需求中要求工具时会在发送之前拒绝。它不是“工具不可用”的永久结论,而是当前没有证据支持调用。把相同名称注册两次,应该抛duplicate tool而不是悄悄覆盖。
真实适配器还应对畸形响应、空choices、拒绝、截断、限流、取消与断线做测试。可以复用本课程C01–C05的消息配对、流式组装和可靠性机制,把模型夹具替换为实际HTTP传输;不要因本例正常输出就跳过这些边界。
验收接口而不是只验收答案
测试分三层:夹具测试证明转换逻辑;本地假服务证明超时、SSE和错误分支;可选供应商测试证明实际能力。后两层成本与条件不同,报告要分开。本文只完成第一层,未调用收费API。
某个供应商换模型后工具失败,先查能力快照过期,再查模板与输出解析;跨后端结果差异,区分算法质量和契约差异;usage缺失标未知,不填零。原始协议可查 Ollama Chat 与 DeepSeek Chat Completions。
课后练习展开习题收起习题
先独立作答,再展开参考思路。检查自己的解释是否包含机制、条件和反例。
通用接口如何保留供应商差异?
参考思路与常见误区
标准化内部请求和结果,但能力三态、完成原因、usage与错误保持显式;关键能力未验证就拒绝或记录降级。
常见误区:静默删掉不支持的参数。
抽象基类能保证外部响应正确吗?
参考思路与常见误区
它只约束实现结构,外部数据仍需运行时校验和契约测试,包括畸形、截断、拒绝与工具ID。
常见误区:类型注解替代JSON校验。
为什么工具注册要拒绝重名?
参考思路与常见误区
名称是模型行动到可信执行函数的映射,静默覆盖会改变权限或行为;版本变更应显式处理。
常见误区:后注册覆盖前注册更方便且无风险。
ReAct与Workflow哪些层可复用?
参考思路与常见误区
模型适配、消息契约、工具执行器、授权、trace与预算;下一步决策与状态推进属于不同编排层。
常见误区:每种范式都另写一套鉴权。
兼容API返回200证明工具能力吗?
参考思路与常见误区
不证明;还需验证具体模型、部署、参数、调用ID、流式工具片段及完成状态。
常见误区:兼容接口等于能力完全相同。