OpenCode · 第 6 章 LLM 抽象层与多 Provider 集成

文档摘要

OpenCode · 第 6 章 LLM 抽象层与多 Provider 集成章节摘要:OpenCode 支持 20 多家模型厂商——OpenAI、Anthropic、Google、Bedrock、Azure、xAI、OpenRouter、Mistral、Cohere、GitHub Copilot、Cloudflare……这些厂商的 API 签名、认证方式、流式协议、特性开关各不相同,如果每接一家就写一套分支,代码会变成一团乱麻。

OpenCode · 第 6 章 LLM 抽象层与多 Provider 集成

章节摘要:OpenCode 支持 20 多家模型厂商——OpenAI、Anthropic、Google、Bedrock、Azure、xAI、OpenRouter、Mistral、Cohere、GitHub Copilot、Cloudflare……这些厂商的 API 签名、认证方式、流式协议、特性开关各不相同,如果每接一家就写一套分支,代码会变成一团乱麻。OpenCode 的解法是一套 Schema-first 的 LLM 抽象层:把一次模型调用抽象成 provider 中立的纯数据(请求),用「门面 + 路由(Route)+ 协议(Protocol)+ 分帧(Framing)+ 传输(Transport)」的分层把差异收敛,最终所有厂商的响应都被翻译成同一种事件流(LLMEvent)。本章要讲透这套抽象:它怎么用门面模式配置厂商、Route 怎么用 5-15 行加一个新部署、协议怎么解析各家流式响应、提示缓存(Prompt Caching)的三断点策略如何省钱,以及当抽象不够用时,那「三档可移植性逃生口」如何兜底。读完本章,你能新增一个 Provider 并解释跨厂商差异如何被抹平。

学习目标

阅读完本章,你应当能够:

描述门面模式 + Route 抽象:如何先配置端点/认证,再选模型,以及为何 Route 让「加一个新部署只要 5-15 行」。
解释协议/分帧/传输分离:协议负责构造请求体与解析流,分帧管字节流切分,传输管 HTTP 细节——为什么这样切能让支持新协议变简单。
讲清**统一事件流(LLMEvent)**的类型(文本增量/推理/工具调用/工具结果/厂商错误/结束等),以及为什么跨厂商统一事件是上层简洁的关键。
复述提示缓存三断点策略(最后的工具定义、最后的系统消息、最新的用户消息),并用 1.25× 写入 / 0.1× 读取的成本数学论证收益。
列出三档可移植性逃生口(生成参数 < providerOptions < http 透传),说明何时用哪一档。

核心概念速览

一句话总结:LLM 抽象层的全部功力在于「把厂商差异下沉,把统一事件上浮」——请求是纯数据,Route 是配置,Protocol 是翻译官,事件流是通用语;当翻译官也搞不定时,三档逃生口让你不破抽象也能透传任意厂商特性。

子章节导航

01 Provider 门面模式与 Route 抽象

讲门面模式:先 某Provider.configure({...}) 配端点/认证/部署,再 .model(id) 或 .某部署类型(id) 选模型。重点讲 Route(Route.make({...}))——它把「一个部署」抽象成端点+认证+分帧等字段的组合,所以加一个新部署只要 5-15 行。

02 协议、分帧与传输分离

讲三件套的分工:协议(anthropic-messages / openai-chat / openai-responses / gemini / bedrock-converse 等)负责构造请求体与解析流式响应;分帧管字节流如何切成事件;传输管 HTTP 连接细节。理解了这套分离,你就能解释「为何支持一个新协议 mostly 是写一个协议模块」。

03 统一 LLMEvent 事件流

讲跨厂商统一的事件类型:文本增量、推理(reasoning)、工具调用、工具结果、厂商错误、结束等。重点说明:为什么这套统一事件让上层(会话循环、工具派发、UI 渲染)完全不用关心是哪家厂商。

04 提示缓存三断点策略与成本数学

讲默认开启的提示缓存:三个断点放在「最后的工具定义、最后的系统消息、最新的用户消息」——为什么是这三处(它们是稳定前缀)。用成本数学论证:写入成本 1.25× 但读取成本仅 0.1×,长会话里这笔账非常划算。

05 三档可移植性逃生口

讲当抽象不够用时怎么办。三档逃生口:第一档「生成参数」(最大 token、温度等通用项)最可移植;第二档 providerOptions(如某厂商的思维模式、路由偏好)按厂商分组;第三档 http(直接改请求体/头/查询)是最后手段。这一节教你何时该用哪一档。

子章节之间的逻辑关系

本章遵循「配置 → 分层 → 统一 → 优化 → 兜底」的抽象理解路径:


门面与 Route (01) ──怎么配置一个厂商
   │
   ▼
协议分帧传输 (02) ──差异如何被分层吸收
   │
   ▼
统一事件流 (03)   ──差异被翻译成通用语
   │
   ▼
提示缓存 (04)     ──在抽象之上做优化
   │
   ▼
逃生口 (05)       ──抽象不够用时如何兜底
   │
   ▼
第 7 章:LLM 抽象如何被会话核心调用

前三节是「抽象如何工作」,后两节是「抽象之上如何优化、抽象之外如何逃生」。理解完全部五节,你才算既懂这套抽象的力量,也懂它的边界——这正是工程派读源码最该有的态度。

前置知识与后续延伸

前置知识:

第 2 章分层架构(LLM 抽象层在哪一层)
第 5 章工具系统(工具运行时与 LLM 抽象协作)
对 HTTP 流式响应(SSE / chunked)、JSON 的基本了解
「门面模式」「策略模式」等设计模式的基本概念

本章为后续章节奠定的基础:

LLM 请求与事件流是第 7 章会话核心每一「回合」调用的对象
提示缓存为第 9 章上下文压缩理解「为什么稳定前缀重要」铺垫
三档逃生口为第 11 章插件扩展(自定义 Provider)铺路