徐涛
71 lines
3.8 KiB
Markdown
71 lines
3.8 KiB
Markdown
# 背景与架构总览
|
||
|
||
> 本文档从 `9-llm-provider-unified-interface.md` 拆分而来，包含 §1 背景与目标 + §2 架构总览。
|
||
|
||
## 1. 背景与目标
|
||
|
||
### 1.1 当前状态
|
||
|
||
`LlmProvider` trait 的请求/响应类型直接绑定到 OpenAI Chat Completion API 格式：
|
||
|
||
```rust
|
||
pub type ChatRequest = OpenaiChatRequest; // 类型别名
|
||
pub type ChatResponse = struct { message: OpenaiChatMessage, ... };
|
||
pub type Message = OpenaiChatMessage;
|
||
```
|
||
|
||
所有 "内部统一类型" 都是 OpenAI 格式的直接映射。这导致：
|
||
|
||
| API 类型 | 兼容性 | 代价 |
|
||
|----------|--------|------|
|
||
| OpenAI Chat（DeepSeek、Qwen 等） | ✅ 原生兼容 | 零 |
|
||
| Anthropic Messages | ❌ 语义丢失 | 需逆向映射，丢失 thinking 等特性 |
|
||
| OpenAI Response API | ❌ 范式不兼容 | ChatResponse 无法表达多类型 output |
|
||
| 非标自定义 API | ❌ 无扩展点 | 只能走 extra_body 逃生舱 |
|
||
|
||
### 1.2 目标
|
||
|
||
设计一套**真正与 Provider 无关的内部统一类型（IR）**，使得：
|
||
|
||
1. 所有 Provider 对外暴露的接口完全一致（统一 trait）
|
||
2. 每个 Provider 内部自行完成 IR ↔ 原生格式的映射
|
||
3. 上层（LlmCycle、AgentSession）完全感知不到具体 Provider
|
||
4. 新 Provider 只需实现一次双向映射即可接入
|
||
5. 各 API 的独有特性（thinking、内置工具等）有表达空间
|
||
|
||
### 1.3 非目标
|
||
|
||
- 不追求覆盖所有 API 的每一个参数（90% 核心流程即可）
|
||
- 不追求在不改上层代码的情况下切换 Provider（接口一致足以）
|
||
- 不试图让 OpenAI Response API 的内置工具完全融入消息循环（通过逃生舱 + 可选能力 trait）
|
||
|
||
---
|
||
|
||
## 2. 架构总览
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ 上 层（AgentSession / TaskAgent） │
|
||
│ 只与 IR 类型和 LlmProvider trait 交互 │
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ LlmCycle │
|
||
│ 循环 / 重试 / Tool 循环 / Hook / Compact / CostTracker │
|
||
│ 内部使用 Vec<Message> + MessageRequest │
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ LlmProvider trait（核心接口） │
|
||
│ chat(MessageRequest) → Result<MessageResponse, LlmError> │
|
||
│ chat_stream(MessageRequest) → Stream<StreamEvent> │
|
||
│ capabilities() → ProviderCapabilities │
|
||
├────────────────┬──────────────────────┬──────────────────────┤
|
||
│ OpenaiProvider │ AnthropicProvider │ DeepSeekProvider ... │
|
||
│ IR ↔ OpenAI │ IR ↔ Anthropic │ IR ↔ OpenAI 格式 │
|
||
│ JSON │ JSON │ (兼容 Chat API) │
|
||
└────────────────┴──────────────────────┴──────────────────────┘
|
||
```
|
||
|
||
### 2.1 分层原则
|
||
|
||
- **IR 层**：全项目唯一的内部表示，与任何具体 API 格式无关
|
||
- **Provider 层**：每个 Provider 实现 IR ↔ 原生格式的双向映射，复杂度隔离在此层
|
||
- **上层**：只与 IR 和 `LlmProvider` trait 交互，不感知具体 Provider
|