大模型应用开发 / 系统课时
设计统一模型适配层
设计统一模型适配层
学习目标
完成本课后,你将能够:
- 定义与供应商无关的内部请求和响应
- 实现 Ollama 适配器并转换错误
- 通过能力配置决定结构化输出、视觉和工具支持
- 让应用可以在不修改业务逻辑的情况下切换模型
为什么需要适配层
业务代码直接使用 /api/chat、OpenAI SDK 或某个框架对象,会把字段、异常和能力差异扩散到整个系统。适配层提供稳定内部协议,把供应商差异限制在一个模块中。
内部模型
内部请求可以包含:
text
model
messages
temperature
max_output_tokens
structured_schema
tools
stream
timeout
metadata内部响应:
text
content
thinking
tool_calls
usage
finish_reason
provider
model
raw_id不是所有 Provider 都支持全部字段。适配层应返回能力错误,而不是静默忽略。
Python 适配器示例
保存为 model_adapter.py:
python
from dataclasses import dataclass, field
from typing import Any, Protocol
from ollama import Client, ResponseError
@dataclass
class ChatMessage:
role: str
content: str
@dataclass
class ChatRequest:
model: str
messages: list[ChatMessage]
temperature: float = 0.0
stream: bool = False
options: dict[str, Any] = field(default_factory=dict)
@dataclass
class ChatResponse:
content: str
model: str
prompt_tokens: int
output_tokens: int
provider: str = "ollama"
class ModelError(RuntimeError):
def __init__(self, code: str, message: str) -> None:
super().__init__(message)
self.code = code
class ChatProvider(Protocol):
def chat(self, request: ChatRequest) -> ChatResponse:
...
class OllamaProvider:
def __init__(self, host: str = "http://localhost:11434") -> None:
self.client = Client(host=host)
def chat(self, request: ChatRequest) -> ChatResponse:
if request.stream:
raise ModelError(
"unsupported_mode",
"此同步示例不处理流式响应",
)
options = {
"temperature": request.temperature,
**request.options,
}
try:
result = self.client.chat(
model=request.model,
messages=[
{"role": item.role, "content": item.content}
for item in request.messages
],
stream=False,
options=options,
)
except ResponseError as exc:
code = (
"model_not_found"
if exc.status_code == 404
else "provider_error"
)
raise ModelError(code, exc.error) from exc
except ConnectionError as exc:
raise ModelError(
"provider_unavailable",
"无法连接 Ollama",
) from exc
content = result["message"].get("content", "").strip()
return ChatResponse(
content=content,
model=result.get("model", request.model),
prompt_tokens=result.get("prompt_eval_count", 0),
output_tokens=result.get("eval_count", 0),
)
if __name__ == "__main__":
provider = OllamaProvider()
response = provider.chat(
ChatRequest(
model="gemma3:1b",
messages=[
ChatMessage(
role="user",
content="用一句话说明适配层的价值。",
)
],
)
)
print(response.content)
print(
f"provider={response.provider} "
f"prompt_tokens={response.prompt_tokens} "
f"output_tokens={response.output_tokens}"
)运行:
bash
python model_adapter.py预期输出结构:
text
<MODEL_RESPONSE>
provider=ollama prompt_tokens=<COUNT> output_tokens=<COUNT>能力配置
为模型维护能力:
json
{
"gemma3:1b": {
"chat": true,
"vision": false,
"tools": false,
"thinking": false,
"structured_output": true,
"max_context": 0
}
}示例值必须由实际模型验证后填写。调用前检查能力,可以提前返回稳定错误。
模型映射
业务使用逻辑名称:
text
chat-default
code-review
embedding-default
vision-default配置映射到具体模型:
text
chat-default → gemma3:1b
embedding-default → embeddinggemma更新底层模型时,业务接口不需要变化,但必须通过回归和灰度发布。
错误规范化
内部错误码示例:
provider_unavailablemodel_not_foundrequest_invalidcontext_exceededoverloadedtimeoutcancelledunsupported_capabilityoutput_invalid
保留原始状态和脱敏错误用于诊断,但前端只依赖内部码。
测试策略
适配层需要:
- 单元测试:字段映射和错误转换
- 合约测试:真实 Ollama 响应
- 能力测试:结构化、工具、视觉等
- 回归测试:切换模型后的业务结果
- 故障测试:服务停止、超时和 503
- 流式测试:取消和结束状态
业务层测试应使用假的 Provider,避免每次都依赖大模型。
本课练习
练习 1:扩展流式协议
任务目标:统一流式事件。输入或初始条件:已有同步适配器。
实现要求:定义 content_delta、tool_call 和 completed 事件。验收条件:业务层不依赖 Ollama 原始块。
练习 2:实现模型映射
任务目标:解耦业务名称。输入或初始条件:准备两个聊天模型。
实现要求:通过配置切换 chat-default。验收条件:业务代码不修改且回归通过。
练习 3:测试错误转换
任务目标:输出稳定内部错误。输入或初始条件:模拟 404、连接失败和超时。实现要求:分别映射错误码。验收条件:前端不解析供应商错误文本。
按自己的节奏,确认真正理解。