tokens-reef/deploy/docs-backup/MODEL_PROVIDERS_REFERENCE.md

# Sub2API 模型提供商参考文档

> 版本: v1.0  
> 更新日期: 2026-03-26

---

## 一、概述

本文档详细介绍了 Sub2API 支持的所有模型提供商，包括配置参数、支持的模型列表、API 端点等信息。

---

## 二、架构设计

### 2.1 Provider 接口

```go
// backend/internal/pkg/models/interface.go
type Provider interface {
    Name() string                              // 提供商名称
    BaseURL() string                           // API 基础地址
    Models() []Model                           // 支持的模型列表
    Chat(ctx context.Context, req *ChatRequest) (*ChatResponse, error)
    ChatStream(ctx context.Context, req *ChatRequest) (io.ReadCloser, error)
    Embeddings(ctx context.Context, req *EmbeddingsRequest) (*EmbeddingsResponse, error)
    ValidateKey(ctx context.Context, key string) error
    Close() error
}
```

### 2.2 工厂模式

```go
// backend/internal/pkg/models/factory.go

// 注册提供商
func RegisterProvider(name string, factory ProviderFactory)

// 创建提供商实例
func NewProvider(name string, config *ProviderConfig) (Provider, error)

// 列出所有已注册的提供商
func ListProviders() []string
```

### 2.3 继承结构

```
Provider 接口
├── OpenAICompatProvider (基类)
│   ├── DeepSeekProvider
│   ├── QwenProvider
│   ├── DoubaoProvider
│   ├── IFlytekProvider
│   ├── MiniMaxProvider
│   └── TencentProvider
│
└── 自定义 Provider (非 OpenAI 兼容)
    └── BaiduProvider (文心一言 - 百度 API)
```

---

## 三、提供商详细说明

### 3.1 DeepSeek

**位置**: `backend/internal/pkg/models/deepseek/deepseek.go`

**API 基础地址**: `https://api.deepseek.com/v1`

**认证方式**: Bearer Token

**支持模型**:

| 模型 ID | 名称 | 类型 | 上下文 | 最大输出 | 能力 |
|---------|------|------|--------|----------|------|
| deepseek-chat | DeepSeek Chat | chat | 128K | 8K | streaming, function_call |
| deepseek-coder | DeepSeek Coder | chat | 163K | 8K | streaming, function_call |
| deepseek-reasoner | DeepSeek Reasoner | chat | 128K | 8K | streaming, function_call |
| deepseek-chat-32k | DeepSeek Chat (32K) | chat | 32K | 4K | streaming, function_call |
| deepseek-embedding | DeepSeek Embedding | embedding | 16K | 16K | embeddings |

**注册别名**: 无

**使用示例**:

```go
config := &models.ProviderConfig{
    APIKey:  "sk-xxxxx",
    BaseURL: "https://api.deepseek.com/v1",
    Timeout: 120 * time.Second,
}
provider, _ := models.NewProvider("deepseek", config)
```

---

### 3.2 Qwen (通义千问)

**位置**: `backend/internal/pkg/models/qwen/qwen.go`

**API 基础地址**: `https://dashscope.aliyuncs.com/compatible-mode/v1`

**认证方式**: Bearer Token

**支持模型**:

| 模型 ID | 名称 | 类型 | 上下文 | 最大输出 | 能力 |
|---------|------|------|--------|----------|------|
| qwen-turbo | Qwen Turbo | chat | 131K | 4K | streaming, function_call |
| qwen-plus | Qwen Plus | chat | 131K | 8K | streaming, function_call |
| qwen-max | Qwen Max | chat | 131K | 8K | streaming, function_call |
| qwen-max-long | Qwen Max (Long) | chat | 1M | 8K | streaming, function_call |
| qwen2-72b-instruct | Qwen2 72B Instruct | chat | 32K | 4K | streaming, function_call |
| qwen2-57b-a14b-instruct | Qwen2 57B A14B | chat | 32K | 4K | streaming, function_call |
| qwen2-7b-instruct | Qwen2 7B Instruct | chat | 32K | 4K | streaming, function_call |
| qwen2-1.8b-instruct | Qwen2 1.8B Instruct | chat | 32K | 4K | streaming, function_call |
| qwen-coder-turbo | Qwen Coder Turbo | chat | 131K | 4K | streaming, function_call |
| text-embedding-v3 | Text Embedding V3 | embedding | 8K | 8K | embeddings |

**注册别名**: `tongyi`

**使用示例**:

```go
config := &models.ProviderConfig{
    APIKey:  "sk-xxxxx",
    BaseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
    Timeout: 120 * time.Second,
}
provider, _ := models.NewProvider("qwen", config)
```

---

### 3.3 Doubao (豆包)

**位置**: `backend/internal/pkg/models/doubao/doubao.go`

**API 基础地址**: `https://ark.cn-beijing.volces.com/api/v3`

**认证方式**: Bearer Token

**支持模型**:

| 模型 ID | 名称 | 类型 | 上下文 | 最大输出 | 能力 |
|---------|------|------|--------|----------|------|
| doubao-pro-32k | Doubao Pro 32K | chat | 32K | 8K | streaming, function_call |
| doubao-pro-4k | Doubao Pro 4K | chat | 4K | 4K | streaming, function_call |
| doubao-lite-32k | Doubao Lite 32K | chat | 32K | 8K | streaming, function_call |
| doubao-lite-4k | Doubao Lite 4K | chat | 4K | 4K | streaming, function_call |
| doubao-coder-32k | Doubao Coder 32K | chat | 32K | 8K | streaming, function_call |
| doubao-vision-pro | Doubao Vision Pro | chat | 32K | 4K | streaming, vision, function_call |
| doubao-embedding | Doubao Embedding | embedding | 8K | 8K | embeddings |

**注册别名**: `bytedance`

---

### 3.4 Baidu ERNIE (文心一言)

**位置**: `backend/internal/pkg/models/baidu/baidu.go`

**API 基础地址**: `https://qianfan.baidubce.com/v2`

**认证方式**: Bearer Token

**特点**: 使用百度自有的 API 格式，非完全 OpenAI 兼容

**支持模型**:

| 模型 ID | 名称 | 类型 | 上下文 | 最大输出 | 能力 |
|---------|------|------|--------|----------|------|
| ernie-4.0-8k | ERNIE 4.0 8K | chat | 8K | 8K | streaming, function_call |
| ernie-4.0-32k | ERNIE 4.0 32K | chat | 32K | 8K | streaming, function_call |
| ernie-4.0-8k-preview | ERNIE 4.0 8K Preview | chat | 8K | 4K | streaming, function_call |
| ernie-3.5-8k | ERNIE 3.5 8K | chat | 8K | 4K | streaming, function_call |
| ernie-3.5-8k-preview | ERNIE 3.5 8K Preview | chat | 8K | 4K | streaming, function_call |
| ernie-3.5-32k | ERNIE 3.5 32K | chat | 32K | 4K | streaming, function_call |
| ernie-speed-8k | ERNIE Speed 8K | chat | 8K | 4K | streaming, function_call |
| ernie-speed-32k | ERNIE Speed 32K | chat | 32K | 4K | streaming, function_call |
| ernie-lite-8k | ERNIE Lite 8K | chat | 8K | 4K | streaming |
| ernie-lite-4k | ERNIE Lite 4K | chat | 4K | 4K | streaming |
| embedding-v3 | Embedding V3 | embedding | 8K | 8K | embeddings |
| embedding-v2 | Embedding V2 | embedding | 4K | 4K | embeddings |

**注册别名**: `ernie`, `wenxinyiyan`

---

### 3.5 iFlytek Spark (讯飞星火)

**位置**: `backend/internal/pkg/models/iflytek/iflytek.go`

**API 基础地址**: `https://spark-api.xf-yun.com/v3.5`

**认证方式**: Bearer Token

**支持模型**:

| 模型 ID | 名称 | 类型 | 上下文 | 最大输出 | 能力 |
|---------|------|------|--------|----------|------|
| spark-general-v3.5 | Spark General V3.5 | chat | 8K | 4K | streaming, function_call |
| spark-general-v3.0 | Spark General V3.0 | chat | 8K | 4K | streaming, function_call |
| spark-pro-128k | Spark Pro 128K | chat | 128K | 8K | streaming, function_call |
| spark-pro-32k | Spark Pro 32K | chat | 32K | 4K | streaming, function_call |
| spark-lite-8k | Spark Lite 8K | chat | 8K | 4K | streaming |
| spark-max-32k | Spark Max 32K | chat | 32K | 4K | streaming, function_call |
| spark-reasoning-pro | Spark Reasoning Pro | chat | 32K | 8K | streaming, function_call |
| text-embedding | Text Embedding | embedding | 4K | 4K | embeddings |

**注册别名**: `spark`, `xinghuo`

---

### 3.6 MiniMax

**位置**: `backend/internal/pkg/models/minimax/minimax.go`

**API 基础地址**: `https://api.minimax.chat/v1`

**认证方式**: Bearer Token

**支持模型**:

| 模型 ID | 名称 | 类型 | 上下文 | 最大输出 | 能力 |
|---------|------|------|--------|----------|------|
| abab6.5s-chat | Abab 6.5S Chat | chat | 245K | 8K | streaming, function_call |
| abab6.5g-chat | Abab 6.5G Chat | chat | 245K | 8K | streaming, function_call |
| abab6-chat | Abab 6 Chat | chat | 131K | 4K | streaming, function_call |
| abab5.5s-chat | Abab 5.5S Chat | chat | 131K | 8K | streaming, function_call |
| abab5.5g-chat | Abab 5.5G Chat | chat | 131K | 8K | streaming, function_call |
| abab5.5s-code | Abab 5.5S Code | chat | 131K | 8K | streaming, function_call |
| emb-01 | Embedding 01 | embedding | 8K | 8K | embeddings |
| emb-01-large | Embedding 01 Large | embedding | 8K | 8K | embeddings |

**注册别名**: 无

---

### 3.7 Tencent Hunyuan (腾讯混元)

**位置**: `backend/internal/pkg/models/tencent/tencent.go`

**API 基础地址**: `https://hunyuan.tencentcloudapi.com/v1`

**认证方式**: Bearer Token

**支持模型**:

| 模型 ID | 名称 | 类型 | 上下文 | 最大输出 | 能力 |
|---------|------|------|--------|----------|------|
| hunyuan-pro | Hunyuan Pro | chat | 128K | 8K | streaming, function_call |
| hunyuan-standard | Hunyuan Standard | chat | 32K | 4K | streaming, function_call |
| hunyuan-lite | Hunyuan Lite | chat | 16K | 4K | streaming |
| hunyuan-code | Hunyuan Code | chat | 32K | 4K | streaming, function_call |
| hunyuan-math | Hunyuan Math | chat | 32K | 4K | streaming, function_call |
| hunyuan-vision | Hunyuan Vision | chat | 32K | 4K | streaming, vision, function_call |
| embedding-001 | Embedding 001 | embedding | 4K | 4K | embeddings |

**注册别名**: `hunyuan`

---

### 3.8 Zhipu (智谱)

**位置**: `backend/internal/pkg/models/zhipu/zhipu.go`

**API 基础地址**: `https://open.bigmodel.cn/api/paas/v4`

**认证方式**: Bearer Token

**支持模型**:

| 模型 ID | 名称 | 类型 | 上下文 | 最大输出 | 能力 |
|---------|------|------|--------|----------|------|
| glm-4 | GLM-4 | chat | 128K | 8K | streaming, function_call |
| glm-4-flash | GLM-4 Flash | chat | 128K | 8K | streaming, function_call |
| glm-4-plus | GLM-4 Plus | chat | 128K | 8K | streaming, function_call |
| glm-3-turbo | GLM-3 Turbo | chat | 32K | 4K | streaming, function_call |
| glm-4v | GLM-4V | chat | 32K | 4K | streaming, vision, function_call |
| glm-4v-plus | GLM-4V Plus | chat | 32K | 4K | streaming, vision, function_call |
| codegeex-4 | CodeGeeX-4 | chat | 128K | 8K | streaming, function_call |
| glm-4-long | GLM-4 Long | chat | 200K | 4K | streaming, function_call |
| embedding-2 | Embedding-2 | embedding | 8K | 8K | embeddings |

**注册别名**: `zhipuai`, `glm`

---

### 3.9 Moonshot (Kimi)

**位置**: `backend/internal/pkg/models/moonshot/moonshot.go`

**API 基础地址**: `https://api.moonshot.cn/v1`

**认证方式**: Bearer Token

**支持模型**:

| 模型 ID | 名称 | 类型 | 上下文 | 最大输出 | 能力 |
|---------|------|------|--------|----------|------|
| kimi-dev | Kimi Dev | chat | 128K | 8K | streaming, function_call |
| kimi-preview | Kimi Preview | chat | 128K | 8K | streaming, function_call |
| kimi-thinking | Kimi Thinking | chat | 32K | 8K | streaming, function_call |
| moonshot-v1-8k | Moonshot V1 8K | chat | 8K | 4K | streaming, function_call |
| moonshot-v1-32k | Moonshot V1 32K | chat | 32K | 4K | streaming, function_call |
| moonshot-v1-128k | Moonshot V1 128K | chat | 128K | 4K | streaming, function_call |
| moonshot-code | Moonshot Code | chat | 32K | 4K | streaming, function_call |
| embedding-v1 | Embedding V1 | embedding | 8K | 8K | embeddings |

**注册别名**: `kimi`, `moonshotai`

---

### 3.10 01.AI (零一万物)

**位置**: `backend/internal/pkg/models/zeroone/zeroone.go`

**API 基础地址**: `https://api.01.ai/v1`

**认证方式**: Bearer Token

**支持模型**:

| 模型 ID | 名称 | 类型 | 上下文 | 最大输出 | 能力 |
|---------|------|------|--------|----------|------|
| yi-large | Yi Large | chat | 160K | 8K | streaming, function_call |
| yi-large-preview | Yi Large Preview | chat | 160K | 8K | streaming, function_call |
| yi-medium | Yi Medium | chat | 32K | 4K | streaming, function_call |
| yi-medium-200k | Yi Medium 200K | chat | 200K | 4K | streaming, function_call |
| yi-vision | Yi Vision | chat | 32K | 4K | streaming, vision, function_call |
| yi-lite | Yi Lite | chat | 16K | 4K | streaming |
| yi-lite-200k | Yi Lite 200K | chat | 200K | 4K | streaming |
| yi-coder | Yi Coder | chat | 32K | 4K | streaming, function_call |
| yi-coder-32k | Yi Coder 32K | chat | 32K | 4K | streaming, function_call |
| embedding-01 | Embedding 01 | embedding | 8K | 8K | embeddings |

**注册别名**: `zeroone`, `yi`, `lingwanwu`

---

## 四、ProviderConfig 配置

```go
type ProviderConfig struct {
    APIKey       string                 // API 密钥
    BaseURL      string                 // API 基础地址 (可选)
    Organization string                 // 组织 ID (可选)
    Timeout      time.Duration          // 超时时间 (默认 120s)
    AuthType     string                 // 认证类型: "bearer", "api_key", "oauth"
    Extra        map[string]interface{} // 提供商特定配置
}
```

---

## 五、错误处理

### 5.1 预定义错误

```go
var (
    ErrUnknownProvider   = models.NewError("unknown provider: %s")
    ErrInvalidAPIKey     = models.NewError("invalid API key")
    ErrRateLimited       = models.NewError("rate limited")
    ErrInsufficientQuota = models.NewError("insufficient quota")
    ErrModelNotFound     = models.NewError("model not found: %s")
    ErrInvalidRequest    = models.NewError("invalid request: %s")
    ErrContextCancelled  = models.NewError("context cancelled")
    ErrTimeout           = models.NewError("request timeout")
)
```

### 5.2 错误检查

```go
if err != nil {
    if errors.Is(err, models.ErrInvalidAPIKey) {
        // 处理无效 API Key
    }
}
```

---

## 六、测试

### 6.1 运行提供商测试

```bash
cd backend
go test -v ./internal/pkg/models/...
```

### 6.2 测试输出示例

```
=== RUN   TestFactoryRegistration
    models_test.go:80: Registered providers: [baidu deepseek doubao bytedance 
    iflytek xinghuo qwen tongyi ernie wenxinyiyan spark minimax tencent hunyuan]
--- PASS: TestFactoryRegistration (0.00s)
```

---

## 七、扩展开发

### 7.1 添加新的提供商

1. 在 `backend/internal/pkg/models/` 下创建新目录
2. 实现 Provider 接口
3. 在 `init()` 函数中注册提供商

**示例**:

```go
package newprovider

import (
    "github.com/Wei-Shaw/sub2api/internal/pkg/models"
    "github.com/Wei-Shaw/sub2api/internal/pkg/models/openai_compat"
)

type NewProvider struct {
    *openai_compat.OpenAICompatProvider
}

func NewNewProvider(config *models.ProviderConfig) (models.Provider, error) {
    base := openai_compat.NewOpenAICompatProvider(&openai_compat.OpenAICompatConfig{
        Name:    "newprovider",
        BaseURL: "https://api.newprovider.com/v1",
        APIKey:  config.APIKey,
        Models:  []models.Model{...},
        Timeout: config.Timeout,
    })
    return &NewProvider{OpenAICompatProvider: base}, nil
}

func init() {
    models.RegisterProvider("newprovider", NewNewProvider)
}
```

---

## 八、附录

### 8.1 提供商列表汇总

| 提供商 | 注册名称 | 别名 | 模型数 | API 类型 |
|--------|----------|------|--------|----------|
| DeepSeek | deepseek | - | 5 | OpenAI 兼容 |
| Qwen | qwen | tongyi | 10 | OpenAI 兼容 |
| Doubao | doubao | bytedance | 7 | OpenAI 兼容 |
| Baidu | baidu | ernie, wenxinyiyan | 11 | 百度 API |
| iFlytek | iflytek | spark, xinghuo | 8 | OpenAI 兼容 |
| MiniMax | minimax | - | 7 | OpenAI 兼容 |
| Tencent | tencent | hunyuan | 7 | OpenAI 兼容 |
| Zhipu | zhipu | zhipuai, glm | 9 | OpenAI 兼容 |
| Moonshot | moonshot | kimi, moonshotai | 8 | OpenAI 兼容 |
| 01.AI | 01ai | zeroone, yi, lingwanwu | 10 | OpenAI 兼容 |

---

*文档版本: v1.1*  
*最后更新: 2026-03-27*