349d783fd1
- Remove old review reports (keep latest only) - Move docs/ to deploy/docs-backup/ - Move performance-testing/ to deploy/ - Clean up test output files - Organize root directory
282 lines
7.0 KiB
Markdown
282 lines
7.0 KiB
Markdown
# Sub2API 国产模型接入方案专家审核报告
|
||
|
||
> 审核日期: 2026-03-26
|
||
> 审核团队: 技术专家 + 网关专家 + 测试专家
|
||
> 版本: v1.0
|
||
|
||
---
|
||
|
||
## 一、方案可行性评估
|
||
|
||
### 1.1 技术架构 ✅ 可行
|
||
|
||
| 评估项 | 结论 | 说明 |
|
||
|-------|------|------|
|
||
| 工厂模式 | ✅ 合理 | 与现有 Ent ORM 工厂模式一致 |
|
||
| Provider 接口 | ✅ 可行 | 符合 Go 社区标准实践 |
|
||
| OpenAI 兼容适配器 | ✅ 合理 | 复用现有 apicompat 模块 |
|
||
|
||
**架构优势**:
|
||
- 百度现有的 `apicompat` 模块已实现 Anthropic → OpenAI 格式转换
|
||
- 通义千问/豆包等使用 OpenAI 兼容 API，可直接复用现有 client
|
||
- 自定义协议只需实现统一接口，不影响核心网关逻辑
|
||
|
||
### 1.2 与现有系统兼容性 ✅ 兼容
|
||
|
||
**已有平台处理模式**:
|
||
```
|
||
platform: openai → openai_gateway_service.go
|
||
platform: anthropic → gateway_service.go
|
||
platform: gemini → gemini_v1beta_handler.go
|
||
platform: bedrock → bedrock_stream.go
|
||
```
|
||
|
||
**新增模型接入方式**:
|
||
- 保持现有路由逻辑不变
|
||
- 通过配置动态加载 provider
|
||
- 不修改核心网关代码
|
||
|
||
### 1.3 潜在风险 ⚠️ 需关注
|
||
|
||
| 风险 | 级别 | 应对措施 |
|
||
|-----|------|---------|
|
||
| 各厂商 API 频繁变更 | 中 | 版本化适配器 + 配置热更新 |
|
||
| 认证方式差异大 | 中 | 抽象统一认证层 |
|
||
| 流式响应格式不统一 | 低 | 标准化 StreamReader |
|
||
| 限流策略各不相同 | 低 | 统一限流控制层 |
|
||
|
||
---
|
||
|
||
## 二、网关专家审核
|
||
|
||
### 2.1 请求转发架构 ✅ 无缝集成
|
||
|
||
```go
|
||
// 现有网关路由模式
|
||
func (s *OpenAIGatewayService) HandleChatCompletion(ctx context.Context, req *Request) (*Response, error) {
|
||
// 1. 解析请求
|
||
// 2. 选择账号 (账号调度)
|
||
// 3. 调用上游 API
|
||
// 4. 转发响应
|
||
// 5. 记录用量
|
||
}
|
||
```
|
||
|
||
**新增模型只需**:
|
||
1. 实现 `Provider` 接口
|
||
2. 注册到工厂
|
||
3. 添加配置项
|
||
|
||
**不影响的功能**:
|
||
- ✅ 账号调度 (Account Scheduler)
|
||
- ✅ 负载均衡 (Load Balancing)
|
||
- ✅ 速率限制 (Rate Limiting)
|
||
- ✅ 用量统计 (Usage Tracking)
|
||
- ✅ 错误重试 (Retry Policy)
|
||
|
||
### 2.2 流式响应处理 ✅ 已覆盖
|
||
|
||
**现有实现**:
|
||
```go
|
||
// openai_ws_forwarder.go
|
||
type StreamForwarder struct {
|
||
// 处理 SSE 流式响应
|
||
}
|
||
```
|
||
|
||
**新模型只需**:
|
||
- 实现 `ChatStream()` 方法
|
||
- 返回标准 `*StreamReader` 接口
|
||
|
||
### 2.3 路由配置 ✅ 灵活
|
||
|
||
```yaml
|
||
# 可在账号配置中指定 platform
|
||
accounts:
|
||
- name: "DeepSeek 账号"
|
||
platform: "deepseek"
|
||
type: "api_key"
|
||
credentials:
|
||
api_key: "sk-xxx"
|
||
```
|
||
|
||
---
|
||
|
||
## 三、测试专家审核
|
||
|
||
### 3.1 测试覆盖建议
|
||
|
||
| 测试类型 | 覆盖率目标 | 测试要点 |
|
||
|---------|-----------|---------|
|
||
| 单元测试 | 80%+ | Provider 接口实现 |
|
||
| 集成测试 | 全链路 | 请求 → 转发 → 响应 |
|
||
| E2E 测试 | 核心场景 | 各模型实际调用 |
|
||
| 性能测试 | 基准对比 | 与现有模型对比 |
|
||
|
||
### 3.2 关键测试场景
|
||
|
||
```go
|
||
// 测试矩阵
|
||
TestCases:
|
||
├── 正常请求
|
||
│ ├── 文本生成 (Chat)
|
||
│ ├── 流式输出 (Streaming)
|
||
│ └── 嵌入向量 (Embeddings)
|
||
├── 错误处理
|
||
│ ├── API Key 无效
|
||
│ ├── 配额超限
|
||
│ └── 网络超时
|
||
├── 限流测试
|
||
│ └── 高并发请求
|
||
└── 格式兼容
|
||
└── 不同模型的响应格式转换
|
||
```
|
||
|
||
### 3.3 测试工具
|
||
|
||
- 基准测试: `go test -bench=`
|
||
- 负载测试: Artillery / K6
|
||
- E2E 测试: Playwright (已有)
|
||
|
||
---
|
||
|
||
## 四、主流 AI 编程助手兼容性
|
||
|
||
### 4.1 当前已支持
|
||
|
||
| 助手 | 协议 | 支持状态 |
|
||
|-----|------|---------|
|
||
| **OpenAI Codex** | OpenAI API | ✅ 完全支持 |
|
||
| **Claude Code (Sora)** | Anthropic API | ✅ 完全支持 |
|
||
| **ChatGPT Web** | OAuth + API | ✅ 完全支持 |
|
||
|
||
### 4.2 主流助手接入分析
|
||
|
||
| 助手 | API 兼容性 | 接入方式 |
|
||
|-----|-----------|---------|
|
||
| **Cursor** | OpenAI 兼容 | 直接配置 API Base URL |
|
||
| **Copilot** | OpenAI 兼容 | 同上 |
|
||
| **Windsurf** | OpenAI 兼容 | 同上 |
|
||
| **Tabnine** | OpenAI 兼容 | 同上 |
|
||
| **Codeium** | OpenAI 兼容 | 同上 |
|
||
| **Juniper** | OpenAI 兼容 | 同上 |
|
||
|
||
### 4.3 国产 AI 助手
|
||
|
||
| 助手 | 厂商 | 接入方案 |
|
||
|-----|------|---------|
|
||
| **通义灵码** | 阿里 | 通过 Qwen API |
|
||
| **文心一言** | 百度 | 通过 ERNIE API |
|
||
| **讯飞星火** | 讯飞 | 通过 Spark API |
|
||
| **代码小浣熊** | 商汤 | 需确认协议 |
|
||
|
||
### 4.4 统一接入方式
|
||
|
||
```yaml
|
||
# 用户配置示例
|
||
# Cursor / Windsurf / Copilot 等:
|
||
OpenAI Base URL: https://your-sub2api.com/v1
|
||
API Key: sk-sub2api-xxxx
|
||
|
||
# 通义灵码:
|
||
API Base: https://your-sub2api.com/qwen
|
||
Key: sk-sub2api-xxxx
|
||
```
|
||
|
||
**结论**: ✅ 主流 AI 编程助手都能通过 OpenAI 兼容协议接入
|
||
|
||
---
|
||
|
||
## 五、专家建议与改进
|
||
|
||
### 5.1 技术建议
|
||
|
||
| 建议 | 优先级 | 说明 |
|
||
|-----|--------|------|
|
||
| 1. 先实现 OpenAI 兼容系列 | 高 | DeepSeek/Qwen/豆包 最简单 |
|
||
| 2. 自定义协议放在第二阶段 | 中 | 百度/讯飞需要更多适配工作 |
|
||
| 3. 添加模型发现机制 | 低 | 自动获取厂商模型列表 |
|
||
| 4. 统一错误码映射 | 中 | 各厂商错误码不同 |
|
||
|
||
### 5.2 架构优化建议
|
||
|
||
```go
|
||
// 建议增加配置热更新
|
||
type ProviderRegistry struct {
|
||
providers map[string]Provider
|
||
mu sync.RWMutex
|
||
}
|
||
|
||
func (r *ProviderRegistry) Reload() error {
|
||
// 从配置重新加载 provider
|
||
}
|
||
```
|
||
|
||
### 5.3 安全性建议
|
||
|
||
| 安全项 | 建议 |
|
||
|-------|------|
|
||
| API Key 存储 | 加密存储 (已实现) |
|
||
| 请求验证 | 添加签名验证 |
|
||
| 限流 | 按模型配置不同限流策略 |
|
||
|
||
---
|
||
|
||
## 六、实施方案调整
|
||
|
||
### 6.1 调整后的优先级
|
||
|
||
| 顺序 | 模型 | 难度 | 原因 |
|
||
|-----|------|------|------|
|
||
| 1 | DeepSeek | ⭐ | OpenAI 兼容，最简单 |
|
||
| 2 | 通义千问 | ⭐ | 阿里文档完善 |
|
||
| 3 | 豆包 | ⭐ | 字节新出，兼容好 |
|
||
| 4 | MiniMax | ⭐ | OpenAI 兼容 |
|
||
| 5 | 智谱 | ⭐ | OpenAI 兼容 |
|
||
| 6 | 百川 | ⭐ | OpenAI 兼容 |
|
||
| 7 | 百度文心 | ⭐⭐ | 自定义协议 |
|
||
| 8 | 腾讯混元 | ⭐ | OpenAI 兼容 |
|
||
| 9 | 讯飞星火 | ⭐⭐ | 自定义协议 |
|
||
|
||
### 6.2 工作量估算
|
||
|
||
```
|
||
总工期: 3-4 周
|
||
|
||
Week 1: 基础设施 (接口 + 工厂)
|
||
Week 2: OpenAI 兼容系列 (6个模型)
|
||
Week 3: 自定义协议系列 (3个模型)
|
||
Week 4: 测试 + 文档 + 前端
|
||
```
|
||
|
||
---
|
||
|
||
## 七、结论
|
||
|
||
### 7.1 方案评估
|
||
|
||
| 维度 | 评分 | 说明 |
|
||
|-----|------|------|
|
||
| 技术可行性 | ⭐⭐⭐⭐⭐ | 架构设计合理 |
|
||
| 兼容性 | ⭐⭐⭐⭐⭐ | 不影响现有功能 |
|
||
| 测试完整性 | ⭐⭐⭐⭐ | 需补充测试用例 |
|
||
| AI 助手兼容 | ⭐⭐⭐⭐⭐ | 完全支持 |
|
||
|
||
### 7.2 最终建议
|
||
|
||
**✅ 方案可行，建议按计划实施**
|
||
|
||
1. 先从 DeepSeek 开始 (最简单)
|
||
2. 积累经验后扩展到其他模型
|
||
3. 保持与官方 Sub2API 的兼容性
|
||
|
||
### 7.3 待补充
|
||
|
||
- [ ] 各模型的详细 API 测试用例
|
||
- [ ] 模型定价和计费逻辑
|
||
- [ ] 账号自动验证与国产模型的集成
|
||
|
||
---
|
||
|
||
*审核报告版本: v1.0*
|
||
*审核完成时间: 2026-03-26* |