251 lines
9.5 KiB
Markdown
251 lines
9.5 KiB
Markdown
# 架构设计
|
||
|
||
## 🧩 架构总览
|
||
|
||
```css
|
||
[Client] ──HTTP/gRPC──> [Core Service API Layer]
|
||
│
|
||
▼
|
||
[SPI 接口（定义操作）]
|
||
│
|
||
┌────────────┴────────────┐
|
||
▼ ▼
|
||
[LocalModelProviderImpl] [OpenAIProviderImpl]
|
||
(本地部署模型) (远程平台模型)
|
||
```
|
||
|
||
## 🧱 模块划分
|
||
|
||
### `core-service`（核心服务模块）
|
||
|
||
- 定义统一的 AI 接口（API）
|
||
- 定义模型服务的 SPI（接口 + 工厂 + 可能的适配器）
|
||
- SPI 示例：`ModelProvider`、`ChatModelService`、`EmbeddingService` 等
|
||
- 提供自动发现机制（如 Spring SPI 自动注入）
|
||
|
||
### `local-model-impl`（本地模型实现模块）
|
||
|
||
- 实现核心服务定义的 SPI
|
||
- 例如调用本地 llama.cpp、Transformers 或自己封装的模型服务 API
|
||
|
||
### `openai-impl`（远程平台实现模块）
|
||
|
||
- 通过 OpenAI、Azure OpenAI、通义千问等平台接口实现 SPI
|
||
|
||
## 🧱 核心设计目标
|
||
|
||
| 功能 | 说明 |
|
||
| -------------- | ------------------------------------------------------------ |
|
||
| 单模型默认调用 | 默认只调用当前设定好的模型 |
|
||
| 指定模型调用 | 允许按名字、类型、模型id调用特定实现(需要有接口获取当前能使用的模型) |
|
||
| 多模型并行调用 | 调用所有或自定义多个模型实现（如 benchmark） |
|
||
| 策略调度 | 本地优先、平台优先、负载均衡、自定义权重等 |
|
||
| 插件式接入 | 支持新增模型实现模块无需修改主逻辑 |
|
||
|
||
## 🎯 架构核心要素
|
||
|
||
### 1. `ModelProvider` SPI 接口
|
||
|
||
```kotlin
|
||
interface ModelProvider {
|
||
fun getName(): String // 模型名称
|
||
fun getType(): String // 本地 远程
|
||
fun getModelId(): String // 模型id 唯一
|
||
fun getChatService(): ChatModelService // 对话服务
|
||
fun getEmbeddingService(): EmbeddingService // 嵌入服务
|
||
fun isAvailable(): Boolean // 是否可用
|
||
}
|
||
```
|
||
|
||
### 2. `ModelProviderManager` 管理器
|
||
|
||
负责注册、发现、调度所有实现。
|
||
|
||
```kotlin
|
||
@Service
|
||
class ModelProviderManager(
|
||
providers: List<ModelProvider>
|
||
) {
|
||
private val providerMap = providers.filter { it.isAvailable() }
|
||
.associateBy { it.getModelId() }
|
||
|
||
fun getProviderByModelId(modelId: String): ModelProvider? = providerMap[name]
|
||
|
||
fun getByIds(modelIds: List<String>): List<ModelProvider> =
|
||
ids.mapNotNull { idMap[it] }
|
||
|
||
fun getProvidersByType(type: String): List<ModelProvider> =
|
||
providerMap.values.filter { it.getType() == type }
|
||
|
||
fun getAll(): Collection<ModelProvider> = providerMap.values
|
||
}
|
||
```
|
||
|
||
### 3. `ModelFilterStrategy`（策略接口）
|
||
|
||
允许通过策略实现来筛选出所需模型提供者
|
||
|
||
```kotlin
|
||
interface ModelFilterStrategy {
|
||
fun filter(providers: Collection<ModelProvider>): Collection<ModelProvider>
|
||
}
|
||
```
|
||
|
||
实现策略举例：
|
||
|
||
```kotlin
|
||
@Component("localTop2")
|
||
class LocalTop2Strategy : ModelFilterStrategy {
|
||
override fun filter(providers: Collection<ModelProvider>): Collection<ModelProvider> {
|
||
return providers.filter { it.getType() == "local" }.take(2)
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. `ModelDispatcher` 分发器
|
||
|
||
```kotlin
|
||
@Service
|
||
class ModelDispatcher(
|
||
private val providerManager: ModelProviderManager,
|
||
private val strategies: Map<String, ModelFilterStrategy>
|
||
) {
|
||
|
||
fun dispatchById(id: String): ModelProvider {
|
||
return providerManager.getById(id)
|
||
?: throw IllegalArgumentException("Model not found: $id")
|
||
}
|
||
|
||
fun dispatchByIds(ids: List<String>): Collection<ModelProvider> {
|
||
return providerManager.getByIds(ids)
|
||
}
|
||
|
||
fun dispatchByStrategy(strategy: String): Collection<ModelProvider> {
|
||
val strategyImpl = strategies[strategy]
|
||
?: throw IllegalArgumentException("Unknown strategy: $strategy")
|
||
return strategyImpl.filter(providerManager.getAll())
|
||
}
|
||
|
||
fun dispatchAll(): Collection<ModelProvider> = providerManager.getAll()
|
||
}
|
||
```
|
||
|
||
💡 调用方式
|
||
|
||
| 使用方式 | 示例 |
|
||
| -------- | ----------------------------------------------------------- |
|
||
| 单模型 | `dispatcher.dispatchById("openai-gpt4")` |
|
||
| 多模型 | `dispatcher.dispatchByIds(["openai-gpt4", "local-llama3"])` |
|
||
| 策略模型 | `dispatcher.dispatchByStrategy("localTop2")` |
|
||
| 全部模型 | `dispatcher.dispatchAll()` |
|
||
|
||
## 🧩 扩展方向
|
||
|
||
| 功能 | 建议 |
|
||
| ------------ | ------------------------------------------------------ |
|
||
| 模型标签 | 支持用标签分类筛选（如 `"tags": ["fast", "offline"]`） |
|
||
| 权重调度 | 给每个模型配置权重，实现加权随机策略 |
|
||
| 异步聚合调用 | 多模型调用支持并发执行后聚合 |
|
||
| 模型分组 | 通过配置将多个模型划入组（如 benchmark-group） |
|
||
|
||
`api-core`（定义 SPI）
|
||
|
||
`api-core-spring`（定义 Dispatcher、Manager、策略等）
|
||
|
||
`impl-local`, `impl-openai`（示例实现）
|
||
|
||
`starter-server`（Web 接口）
|
||
|
||
## 🧱 单项目多模块结构设计
|
||
|
||
```perl
|
||
ai-core-platform/
|
||
├── api-core/ # 💡 定义 SPI 接口（抽象接口层）
|
||
├── api-core-service/ # 💡 Dispatcher、Manager、策略实现（核心服务逻辑）
|
||
├── model-impl-openai/ # ✅ OpenAI 实现模块（实现 SPI）
|
||
├── model-impl-local/ # ✅ 本地模型实现模块
|
||
├── model-impl-xxx/ # ✅ 其他模型实现模块
|
||
├── sdk-client/ # 📦 封装 HTTP 客户端 SDK（可依赖 core-service）
|
||
├── ai-core-server/ # 🚪 Spring Boot 控制器层（暴露 HTTP 接口）
|
||
└── build.gradle.kts
|
||
```
|
||
|
||
## 🧱 微服务结构设计
|
||
|
||
### ✅ 核心目标
|
||
|
||
| 角色 | 职责 |
|
||
| -------------------------------------------- | ---------------------------------------------------- |
|
||
| 🎯 **核心服务（Core Service）** | 定义模型 SPI，负责模型选择策略、调度逻辑等 |
|
||
| ⚙️ **实现服务（Impl Service）** | 每个模型一个服务，实现核心服务 SPI 的调用接口 |
|
||
| 🧩 **门面服务（Gateway/Federation Service）** | 统一对外暴露接口，调用者只知道它，它向下调度和路由 |
|
||
| 📦 **调用端（SDK / 其他服务）** | 只调用门面服务，看不到内部实现细节 |
|
||
| 🚀 **横向扩展** | 核心服务和实现服务都可部署多个副本，服务注册自动发现 |
|
||
|
||
### 🔁 系统调用流程示意图（简化版）
|
||
|
||
```html
|
||
[前端/调用方]
|
||
↓
|
||
[🧩 门面服务 Gateway]
|
||
↓
|
||
┌────────────────────────────┐
|
||
│ Dispatcher │
|
||
│ │
|
||
│ 查找服务注册表 │
|
||
└────────────────────────────┘
|
||
↓ ↓
|
||
[Core Service A] [Core Service B] <- 可扩展集群
|
||
↓ ↓
|
||
[Impl Service 1] [Impl Service 2] <- 每个模型一个服务（OpenAI、LLaMA等）
|
||
|
||
```
|
||
|
||
#### 🧱 项目结构（服务拆分）
|
||
|
||
```bash
|
||
ai-model-platform/
|
||
├── model-api-core/ # SPI 接口定义（公共模块，所有服务依赖）
|
||
├── model-core-service/ # 核心服务（模型管理、策略、调度）
|
||
├── model-impl-openai-service/ # 实现服务（OpenAI GPT等）
|
||
├── model-impl-llama-service/ # 实现服务（本地模型）
|
||
├── model-gateway-service/ # 门面服务（统一入口，封装核心服务和路由）
|
||
├── model-sdk-client/ # HTTP SDK（封装对 gateway 的访问）
|
||
```
|
||
|
||
### 📌 各服务职责详解
|
||
|
||
#### `model-api-core`（接口层）
|
||
|
||
- 定义 SPI 接口（如 `ModelProvider`、`ChatModelService`）
|
||
- 提供调用参数类、返回类（DTO）
|
||
|
||
#### `model-core-service`（核心服务）
|
||
|
||
- 维护模型注册信息（可注册远程实现）
|
||
- 定义策略组件（如：本地优先、负载均衡）
|
||
- 提供一个「统一调用的客户端」用于远程 HTTP 调用实现服务
|
||
|
||
#### `model-impl-*`（实现服务）
|
||
|
||
- 每个服务注册为一个 Provider，提供模型实际调用能力
|
||
- 实现 SPI 接口，通过 HTTP 接口暴露服务
|
||
|
||
#### `model-gateway-service`（门面服务）
|
||
|
||
- 对外暴露统一 HTTP 接口
|
||
- 请求转发至核心服务，核心服务根据策略调度到目标实现服务
|
||
- 可添加身份鉴权、限流、缓存等网关能力
|
||
|
||
#### `model-sdk-client`（客户端）
|
||
|
||
- 对接 `model-gateway-service` 的 SDK
|
||
- 提供统一调用封装（如 chat、embedding、tokenize）
|
||
|
||
### 🎯 模型调用过程
|
||
|
||
1. 外部发起调用：POST `/api/chat`
|
||
2. 请求被 `model-gateway-service` 接收
|
||
3. 门面服务通过核心服务获取候选模型（本地优先 / 多模型）
|
||
4. 核心服务选择合适实现服务，发起 HTTP 请求
|
||
5. 实现服务完成调用，响应结果回传给前端 |