大模型应用开发 / 系统课时

设计统一模型适配层

设计统一模型适配层

学习目标

完成本课后,你将能够:

  • 定义与供应商无关的内部请求和响应
  • 实现 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_unavailable
  • model_not_found
  • request_invalid
  • context_exceeded
  • overloaded
  • timeout
  • cancelled
  • unsupported_capability
  • output_invalid

保留原始状态和脱敏错误用于诊断,但前端只依赖内部码。

测试策略

适配层需要:

  • 单元测试:字段映射和错误转换
  • 合约测试:真实 Ollama 响应
  • 能力测试:结构化、工具、视觉等
  • 回归测试:切换模型后的业务结果
  • 故障测试:服务停止、超时和 503
  • 流式测试:取消和结束状态

业务层测试应使用假的 Provider,避免每次都依赖大模型。

本课练习

练习 1:扩展流式协议

任务目标:统一流式事件。输入或初始条件:已有同步适配器。

实现要求:定义 content_delta、tool_call 和 completed 事件。验收条件:业务层不依赖 Ollama 原始块。

练习 2:实现模型映射

任务目标:解耦业务名称。输入或初始条件:准备两个聊天模型。

实现要求:通过配置切换 chat-default。验收条件:业务代码不修改且回归通过。

练习 3:测试错误转换

任务目标:输出稳定内部错误。输入或初始条件:模拟 404、连接失败和超时。实现要求:分别映射错误码。验收条件:前端不解析供应商错误文本。

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

目录与阅读设置

阅读设置

17

记录一个想法

设计统一模型适配层

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

登录哪都通