📚 本系列目录：《OpenCode 深度解析》当前第 9/11 篇 · 上一篇：OpenCode LSP 集成：Language Server Protocol 架构与实现 | 深度解析（七） · 下一篇：OpenCode 安全机制：从代码执行到权限管理的深度剖析 | 深度解析（九）

📚 系列导航

《OpenCode 深度解析》共 11 篇，本篇是第 9 篇。

← 上一篇：OpenCode LSP 集成：Language Server Protocol 架构与实现 | 深度解析（七）

下一篇：OpenCode 安全机制：从代码执行到权限管理的深度剖析 | 深度解析（九） →

OpenCode 多 Provider 架构：从 Zen 到云端大模型的统一抽象

引言

OpenCode 的核心设计理念之一是多 Provider 支持——无论是本地模型还是云端大模型，都通过统一的接口进行调用。这种设计让用户可以：

自由切换：在 Anthropic、OpenAI、Google、HuggingFace 等提供商之间无缝切换
成本优化：根据任务类型选择合适的模型
本地优先：支持本地部署的模型，保护隐私
统一体验：无论使用哪个 Provider，Agent 的行为保持一致

本文将深入剖析 OpenCode 的多 Provider 架构设计。

一、Provider 体系概述

1.1 支持的 Provider 列表

OpenCode 支持 12+ 个 LLM Provider：

Provider	模型	特点
Anthropic	Claude 3.5/4 系列	编程能力强，性价比高
OpenAI	GPT-4o/GPT-4 Turbo	生态成熟，工具调用优秀
GitHub Copilot	GPT-4o	专为代码优化
Google Gemini	Gemini 1.5/2.0	长上下文， multimodal
Groq	Llama/Mixtral	低延迟推理
OpenRouter	聚合多种模型	统一接口访问
xAI	Grok 系列	Elon Musk 的 AI 实验室
AWS Bedrock	Claude/Llama/Titan	企业级安全合规
Azure OpenAI	GPT-4o	企业级微软生态
Google VertexAI	Gemini/Claude	GCP 原生支持
HuggingFace	开源模型	丰富的开源模型生态
Local	本地部署	完全隐私保护

1.2 架构分层

┌─────────────────────────────────────────────────────────────┐
│                        Agent Layer                          │
│  (Coder, Summarizer, Task, Title)                         │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                     LLM Interface Layer                      │
│  (models/models.go - 统一模型接口)                          │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Provider Implementation                  │
├─────────┬──────────┬──────────┬──────────┬────────────────┤
│Anthropic│ OpenAI   │  Copilot │ Gemini   │ ... (其他)     │
└─────────┴──────────┴──────────┴──────────┴────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Network Transport                        │
│  (HTTP/REST - 不同 Provider 的 API 调用)                   │
└─────────────────────────────────────────────────────────────┘

二、模型定义

2.1 ModelID 类型

// internal/llm/models/models.go
type ModelID string

const (
    // Anthropic
    Claude4Opus       ModelID = "claude-4-opus-20250514"
    Claude4Sonnet     ModelID = "claude-4-sonnet-20250514"
    Claude4Haiku      ModelID = "claude-4-haiku-20250620"
    Claude35Sonnet   ModelID = "claude-3-5-sonnet-20241022"
    Claude35Haiku    ModelID = "claude-3-5-haiku-20241022"
    
    // OpenAI
    GPT4o            ModelID = "chatgpt-4o-latest"
    GPT4Turbo        ModelID = "gpt-4-turbo"
    GPT4oMini        ModelID = "gpt-4o-mini"
    
    // GitHub Copilot
    CopilotGPT4o     ModelID = "copilot-gpt-4o"
    CopilotGPT4oMini ModelID = "copilot-gpt-4o-mini"
    
    // Google
    Gemini15Pro      ModelID = "gemini-1.5-pro"
    Gemini15Flash    ModelID = "gemini-1.5-flash"
    Gemini2Flash     ModelID = "gemini-2.0-flash"
    
    // Groq
    GroqLlama70B     ModelID = "llama-3.3-70b-versatile"
    GroqMixtral8x7B ModelID = "mixtral-8x7b-32768"
    
    // OpenRouter
    OpenRouterGPT4o  ModelID = "openrouter/openai/gpt-4o"
    
    // xAI
    XAIGrok2         ModelID = "grok-2-1212"
    XAIGrok2Mini     ModelID = "grok-2-mini"
    
    // Local
    LocalModel       ModelID = "local"
)

2.2 Model 结构

type Model struct {
    ID              ModelID
    Provider        ModelProvider
    Name            string
    ContextWindow   int64
    MaxTokens       int64        // 最大输出 token 数
    DefaultMaxTokens int64       // 默认 max_tokens
    InputCostPer1M  float64      // 输入成本 ($/1M tokens)
    OutputCostPer1M float64      // 输出成本 ($/1M tokens)
    CanReason       bool         // 是否支持推理（思考链）
    SupportsTools   bool         // 是否支持工具调用
    IsVision        bool         // 是否支持视觉
}

type ModelProvider string

2.3 模型映射表

// internal/llm/models/models.go
var SupportedModels = map[ModelID]Model{
    // Anthropic
    Claude4Opus: {
        ID:              Claude4Opus,
        Provider:        ProviderAnthropic,
        Name:            "Claude 4 Opus",
        ContextWindow:   200000,
        MaxTokens:       8192,
        DefaultMaxTokens: 8192,
        InputCostPer1M:  15.0,
        OutputCostPer1M: 75.0,
        CanReason:       true,
        SupportsTools:   true,
    },
    Claude4Sonnet: {
        ID:              Claude4Sonnet,
        Provider:        ProviderAnthropic,
        Name:            "Claude 4 Sonnet",
        ContextWindow:   200000,
        MaxTokens:       8192,
        DefaultMaxTokens: 8192,
        InputCostPer1M:  3.0,
        OutputCostPer1M: 15.0,
        CanReason:       true,
        SupportsTools:   true,
    },
    // ... 更多模型
}

三、Provider 接口定义

3.1 Provider 接口

// internal/llm/provider/provider.go
type Provider interface {
    // 创建聊天完成请求
    CreateChatCompletion(ctx context.Context, modelID models.ModelID, messages []Message, tools []Tool, options Options) (*ChatCompletion, error)
    
    // 获取模型列表
    ListModels(ctx context.Context) ([]models.ModelID, error)
    
    // Provider 名称
    Name() models.ModelProvider
    
    // 检查 API Key 是否有效
    ValidateAPIKey(ctx context.Context, apiKey string) error
}

3.2 通用选项

type Options struct {
    MaxTokens       int64            // 最大 token 数
    Temperature     float64          // 温度参数
    TopP            float64           // Top-P 采样
    ReasoningEffort string            // 推理努力程度 ( Anthropic )
    Stop            []string          // 停止序列
    Stream          bool              // 是否流式输出
}

3.3 聊天消息

type Message struct {
    Role    string   // "user", "assistant", "system", "tool"
    Content string   // 消息内容
    
    // 可选字段
    Name    string   // 用于 tool 角色
    ToolCallID string // 用于 assistant 携带 tool_call
}

3.4 聊天完成响应

type ChatCompletion struct {
    Content       string
    Model         models.ModelID
    StopReason   string  // "stop", "tool_calls", "max_tokens"
    Usage         Usage
    ToolCalls     []ToolCall  // 如果 stop_reason 是 tool_calls
    ReasoningContent string  // 思考链内容 (如果有)
}

type Usage struct {
    PromptTokens     int
    CompletionTokens int
    TotalTokens      int
}

type ToolCall struct {
    ID      string
    Name    string
    Args    string  // JSON 格式的工具参数
}

四、Anthropic Provider 实现

4.1 Provider 定义

// internal/llm/provider/anthropic.go
type AnthropicProvider struct {
    apiKey string
    baseURL string  // 默认 https://api.anthropic.com
}

func NewAnthropic(apiKey string) *AnthropicProvider {
    return &AnthropicProvider{
        apiKey: apiKey,
        baseURL: "https://api.anthropic.com/v1",
    }
}

func (p *AnthropicProvider) Name() models.ModelProvider {
    return models.ProviderAnthropic
}

4.2 API 请求格式

Anthropic 使用自己的消息格式，不同于 OpenAI 的 chat/completions：

func (p *AnthropicProvider) CreateChatCompletion(
    ctx context.Context,
    modelID models.ModelID,
    messages []Message,
    tools []Tool,
    options Options,
) (*ChatCompletion, error) {
    // 1. 转换为 Anthropic 格式
    anthropicMessages := p.convertMessages(messages)
    
    // 2. 构建请求
    req := anthropicRequest{
        Model:         string(modelID),
        Messages:      anthropicMessages,
        MaxTokens:     options.MaxTokens,
        Temperature:   options.Temperature,
        TopP:          options.TopP,
        Tools:         p.convertTools(tools),
    }
    
    // 3. 添加思考链配置
    if options.ReasoningEffort != "" {
        req.Model = strings.Split(string(modelID), "-")[0] + "-4"
        // 注入思考预算
    }
    
    // 4. 发送请求
    body, err := p.doRequest(ctx, req)
    if err != nil {
        return nil, err
    }
    
    // 5. 解析响应
    return p.parseResponse(body)
}

4.3 消息格式转换

func (p *AnthropicProvider) convertMessages(messages []Message) []anthropicMessage {
    var result []anthropicMessage
    
    for _, msg := range messages {
        switch msg.Role {
        case "system":
            // Anthropic 使用专门的 system 消息
            result = append(result, anthropicMessage{
                Role:    "user",
                Content: "<system>" + msg.Content + "</system>",
            })
            
        case "user":
            result = append(result, anthropicMessage{
                Role:    "user",
                Content: msg.Content,
            })
            
        case "assistant":
            // 处理工具调用
            if msg.ToolCallID != "" {
                result = append(result, anthropicMessage{
                    Role:    "assistant",
                    Content: "",
                    ToolCalls: []toolCall{{
                        ID:   msg.ToolCallID,
                        Name: msg.Name,
                        Input: json.RawMessage(msg.Content),
                    }},
                })
            } else {
                result = append(result, anthropicMessage{
                    Role:    "assistant",
                    Content: msg.Content,
                })
            }
            
        case "tool":
            result = append(result, anthropicMessage{
                Role:    "user",
                Content: fmt.Sprintf(
                    "<tool_result id=\"%s\">%s</tool_result>",
                    msg.ToolCallID,
                    msg.Content,
                ),
            })
        }
    }
    
    return result
}

4.4 工具格式转换

func (p *AnthropicProvider) convertTools(tools []Tool) []anthropicTool {
    var result []anthropicTool
    
    for _, tool := range tools {
        result = append(result, anthropicTool{
            Name:        tool.Name,
            Description: tool.Description,
            InputSchema: tool.Parameters,  // JSON Schema 格式
        })
    }
    
    return result
}

五、OpenAI Provider 实现

5.1 Provider 定义

// internal/llm/provider/openai.go
type OpenAIProvider struct {
    apiKey   string
    baseURL  string
    orgID    string
    projectID string
}

func NewOpenAI(apiKey string) *OpenAIProvider {
    return &OpenAIProvider{
        apiKey:  apiKey,
        baseURL: "https://api.openai.com/v1",
    }
}

func (p *OpenAIProvider) Name() models.ModelProvider {
    return models.ProviderOpenAI
}

5.2 API 请求格式

func (p *OpenAIProvider) CreateChatCompletion(
    ctx context.Context,
    modelID models.ModelID,
    messages []Message,
    tools []Tool,
    options Options,
) (*ChatCompletion, error) {
    // 1. 转换为 OpenAI 格式
    openAIMessages := p.convertMessages(messages)
    
    // 2. 构建请求
    req := chatCompletionRequest{
        Model: string(modelID),
        Messages: openAIMessages,
        MaxTokens: options.MaxTokens,
        Temperature: options.Temperature,
        TopP: options.TopP,
        Stop: options.Stop,
        Stream: options.Stream,
    }
    
    // 3. 添加工具定义
    if len(tools) > 0 {
        req.Tools = p.convertTools(tools)
        req.ToolChoice = "auto"
    }
    
    // 4. 发送请求
    body, err := p.doRequest(ctx, req)
    if err != nil {
        return nil, err
    }
    
    // 5. 解析响应
    return p.parseResponse(body)
}

5.3 消息格式转换

func (p *OpenAIProvider) convertMessages(messages []Message) []openaiMessage {
    var result []openaiMessage
    
    for _, msg := range messages {
        openAIMsg := openaiMessage{
            Role: msg.Role,
        }
        
        if msg.Role == "tool" {
            openAIMsg.ToolCallID = msg.ToolCallID
            openAIMsg.Content = msg.Content
        } else if msg.ToolCallID != "" {
            // Assistant 携带工具调用
            openAIMsg.ToolCalls = []toolCall{{
                ID: msg.ToolCallID,
                Type: "function",
                Function: functionCall{
                    Name: msg.Name,
                    Arguments: msg.Content,
                },
            }}
            openAIMsg.Content = ""  // 有 tool_calls 时 content 可以为空
        } else {
            openAIMsg.Content = msg.Content
        }
        
        result = append(result, openAIMsg)
    }
    
    return result
}

六、Provider 管理与选择

6.1 Provider 工厂

// internal/llm/provider/factory.go
func GetProvider(p models.ModelProvider, apiKey string) Provider {
    switch p {
    case models.ProviderAnthropic:
        return NewAnthropic(apiKey)
    case models.ProviderOpenAI:
        return NewOpenAI(apiKey)
    case models.ProviderCopilot:
        return NewCopilot(apiKey)
    case models.ProviderGemini:
        return NewGemini(apiKey)
    case models.ProviderGroq:
        return NewGroq(apiKey)
    case models.ProviderOpenRouter:
        return NewOpenRouter(apiKey)
    case models.ProviderXAI:
        return NewXAI(apiKey)
    case models.ProviderAzure:
        return NewAzure(apiKey)
    case models.ProviderBedrock:
        return NewBedrock(apiKey)
    case models.ProviderVertexAI:
        return NewVertexAI(apiKey)
    default:
        return nil
    }
}

6.2 自动 Provider 选择

当用户没有明确指定模型时，OpenCode 会自动选择可用的 Provider：

// internal/config/config.go
func setProviderDefaults() {
    // 按优先级顺序检查
    providers := []struct {
        name         models.ModelProvider
        envVar       string
        defaultModel models.ModelID
    }{
        {models.ProviderCopilot, "GITHUB_TOKEN", models.CopilotGPT4o},
        {models.ProviderAnthropic, "ANTHROPIC_API_KEY", models.Claude4Sonnet},
        {models.ProviderOpenAI, "OPENAI_API_KEY", models.GPT4o},
        {models.ProviderGemini, "GEMINI_API_KEY", models.Gemma15Pro},
        {models.ProviderGroq, "GROQ_API_KEY", models.GroqLlama70B},
        {models.ProviderOpenRouter, "OPENROUTER_API_KEY", models.OpenRouterGPT4o},
        {models.ProviderXAI, "XAI_API_KEY", models.XAIGrok2},
    }
    
    for _, p := range providers {
        if apiKey := os.Getenv(p.envVar); apiKey != "" {
            viper.SetDefault("providers."+string(p.name)+".apiKey", apiKey)
            viper.SetDefault("agents.coder.model", p.defaultModel)
            return  // 找到第一个有效的就返回
        }
    }
}

6.3 动态 Provider 切换

// 在 Agent 执行过程中动态切换 Provider
func (a *Agent) switchProvider(modelID models.ModelID) error {
    model, ok := models.SupportedModels[modelID]
    if !ok {
        return fmt.Errorf("unsupported model: %s", modelID)
    }
    
    providerCfg, ok := a.cfg.Providers[model.Provider]
    if !ok || providerCfg.Disabled || providerCfg.APIKey == "" {
        return fmt.Errorf("provider %s not available", model.Provider)
    }
    
    a.provider = provider.GetProvider(model.Provider, providerCfg.APIKey)
    a.modelID = modelID
    
    return nil
}

七、成本控制

7.1 Token 使用统计

type CostTracker struct {
    totalPromptTokens     int64
    totalCompletionTokens int64
    mu                    sync.Mutex
}

func (t *CostTracker) Add(usage Usage) {
    t.mu.Lock()
    defer t.mu.Unlock()
    
    t.totalPromptTokens += int64(usage.PromptTokens)
    t.totalCompletionTokens += int64(usage.CompletionTokens)
}

func (t *CostTracker) GetCost(models []models.ModelID) float64 {
    t.mu.Lock()
    defer t.mu.Unlock()
    
    var totalCost float64
    
    for _, modelID := range models {
        model, ok := models.SupportedModels[modelID]
        if !ok {
            continue
        }
        
        // 计算成本
        inputCost := float64(model.InputCostPer1M) / 1_000_000
        outputCost := float64(model.OutputCostPer1M) / 1_000_000
        
        totalCost += float64(t.totalPromptTokens) * inputCost
        totalCost += float64(t.totalCompletionTokens) * outputCost
    }
    
    return totalCost
}

7.2 预算管理

type BudgetManager struct {
    maxBudgetPerSession float64
    maxTokensPerRequest int64
}

func (m *BudgetManager) CanMakeRequest(modelID models.ModelID, estimatedTokens int64) bool {
    // 检查请求 token 限制
    model, ok := models.SupportedModels[modelID]
    if !ok {
        return false
    }
    
    if estimatedTokens > model.MaxTokens {
        return false
    }
    
    if estimatedTokens > m.maxTokensPerRequest {
        return false
    }
    
    return true
}

八、工具调用协议差异

8.1 Anthropic 的 tool_use

Anthropic 使用 tool_use 表示工具调用：

{
  "type": "content_block",
  "name": "tool_use",
  "input": {
    "id": "toolu_123",
    "name": "Bash",
    "input": {"command": "ls -la"}
  }
}

8.2 OpenAI 的 tool_calls

OpenAI 使用 tool_calls：

{
  "id": "call_123",
  "type": "function",
  "function": {
    "name": "Bash",
    "arguments": "{\"command\": \"ls -la\"}"
  }
}

8.3 统一抽象

OpenCode 在 Provider 层处理这些差异：

// internal/llm/provider/provider.go
type ToolCall struct {
    ID   string  // 统一 ID
    Name string  // 工具名
    Args string  // JSON 参数
}

// Provider 实现负责转换为自己 Provider 的格式

九、高级特性

9.1 思考链 (Reasoning)

Anthropic 的 Claude 4 支持思考链：

if options.ReasoningEffort != "" {
    req.Beta = "automated-2025-05-14"
    req.MaxTokens = maxTokens + 16000  // 额外空间存储思考过程
    
    // thinking 块会被追加到响应中
}

思考内容在响应的 thinking 字段中，不会消耗应用的 token 限额。

9.2 流式输出

func (p *AnthropicProvider) CreateChatCompletionStream(
    ctx context.Context,
    modelID models.ModelID,
    messages []Message,
    tools []Tool,
    options Options,
) (<-chan ChatCompletion, error) {
    stream := make(chan ChatCompletion, 100)
    
    go func() {
        defer close(stream)
        
        // 实现流式解析
        reader := p.doStreamRequest(ctx, req)
        decoder := json.NewDecoder(reader)
        
        for decoder.More() {
            var event anthropicEvent
            if err := decoder.Decode(&event); err != nil {
                return
            }
            
            // 发送增量更新
            stream <- ChatCompletion{
                Content: event.Delta,
            }
        }
    }()
    
    return stream, nil
}

9.3 Vision 多模态

支持图像输入的模型：

func (p *AnthropicProvider) CreateVisionRequest(
    ctx context.Context,
    modelID models.ModelID,
    text string,
    imageURLs []string,
) (*ChatCompletion, error) {
    content := []any{
        map[string]string{"type": "text", "text": text},
    }
    
    for _, url := range imageURLs {
        content = append(content, map[string]any{
            "type": "image",
            "source": map[string]string{
                "type":  "url",
                "url":   url,
            },
        })
    }
    
    // ...
}

十、设计哲学

10.1 统一接口

无论底层是哪个 Provider，Agent 只需要调用统一的 CreateChatCompletion 方法：

// Agent 代码不需要关心使用的是哪个 Provider
resp, err := a.provider.CreateChatCompletion(ctx, modelID, messages, tools, options)

10.2 渐进式复杂度

用户可以从最简单的配置开始：

# 只需要设置 API Key
export ANTHROPIC_API_KEY="sk-ant-..."
opencode

系统会自动选择默认的 Provider 和模型。

10.3 可扩展性

添加新的 Provider 只需要：

在 models.go 中添加新的 ModelID
实现 Provider 接口
在工厂函数中注册

结语

OpenCode 的多 Provider 架构是其核心优势之一。通过统一的抽象层，用户可以在不同的 LLM Provider 之间自由切换，享受：

灵活性：根据需求选择最合适的模型
成本效益：平衡性能和成本
可靠性：多个 Provider 作为备份
一致性：统一的用户体验

这套架构让 OpenCode 成为一个真正与模型无关的 AI 编程平台。

本系列下一篇文章将探讨 OpenCode 的未来演进方向，包括 Crush 项目、项目发展路线图、以及开源 AI 编程工具的发展趋势。

📚 系列导航

OpenCode 多 Provider 架构：从 Zen 到云端大模型的统一抽象

引言

一、Provider 体系概述

1.1 支持的 Provider 列表

1.2 架构分层

二、模型定义

2.1 ModelID 类型

2.2 Model 结构

2.3 模型映射表

三、Provider 接口定义

3.1 Provider 接口

3.2 通用选项

3.3 聊天消息

3.4 聊天完成响应

四、Anthropic Provider 实现

4.1 Provider 定义

4.2 API 请求格式

4.3 消息格式转换

4.4 工具格式转换

五、OpenAI Provider 实现

5.1 Provider 定义

5.2 API 请求格式

5.3 消息格式转换

六、Provider 管理与选择

6.1 Provider 工厂

6.2 自动 Provider 选择

6.3 动态 Provider 切换

七、成本控制

7.1 Token 使用统计

7.2 预算管理

八、工具调用协议差异

8.1 Anthropic 的 tool_use

8.2 OpenAI 的 tool_calls

8.3 统一抽象

九、高级特性

9.1 思考链 (Reasoning)

9.2 流式输出

9.3 Vision 多模态

十、设计哲学

10.1 统一接口

10.2 渐进式复杂度

10.3 可扩展性

结语

系列：open-code 源码解析

评论

发表评论

📚 系列导航

OpenCode 多 Provider 架构：从 Zen 到云端大模型的统一抽象

引言

一、Provider 体系概述

1.1 支持的 Provider 列表

1.2 架构分层

二、模型定义

2.1 ModelID 类型

2.2 Model 结构

2.3 模型映射表

三、Provider 接口定义

3.1 Provider 接口

3.2 通用选项

3.3 聊天消息

3.4 聊天完成响应

四、Anthropic Provider 实现

4.1 Provider 定义

4.2 API 请求格式

4.3 消息格式转换

4.4 工具格式转换

五、OpenAI Provider 实现

5.1 Provider 定义

5.2 API 请求格式

5.3 消息格式转换

六、Provider 管理与选择

6.1 Provider 工厂

6.2 自动 Provider 选择

6.3 动态 Provider 切换

七、成本控制

7.1 Token 使用统计

7.2 预算管理

八、工具调用协议差异

8.1 Anthropic 的 tool_use