跳到主要内容

LLM 提供商模块概览

本文档描述 Elftia 中 LLM 提供商子系统的整体架构。该子系统负责管理多 LLM 提供商配置、API 密钥池、模型发现、请求路由和 Completion 调用链。


文件位置​

模块路径
CompletionServicepackages/desktop/app/main/services/capabilities/llm/completion/CompletionService.ts
ApiKeyPoolServicepackages/desktop/app/main/services/capabilities/llm/completion/ApiKeyPoolService.ts
LLMConfigServicepackages/desktop/app/main/services/capabilities/llm/config-service/LLMConfigService.ts
ProviderManagerpackages/desktop/app/main/services/capabilities/llm/config-service/ProviderManager.ts
ModelDiscoveryManagerpackages/desktop/app/main/services/capabilities/llm/config-service/ModelDiscoveryManager.ts
ConfigIOManagerpackages/desktop/app/main/services/capabilities/llm/config-service/ConfigIOManager.ts
AgentModelsManagerpackages/desktop/app/main/services/capabilities/llm/config-service/AgentModelsManager.ts
ThinkingResolverpackages/desktop/app/main/services/capabilities/llm/completion/ThinkingResolver.ts
StreamHandlerpackages/desktop/app/main/services/capabilities/llm/completion/StreamHandler.ts
DirectApiHandlerpackages/desktop/app/main/services/capabilities/llm/completion/DirectApiHandler.ts
ToolHandlerpackages/desktop/app/main/services/capabilities/llm/completion/ToolHandler.ts
TransformerHandlerpackages/desktop/app/main/services/capabilities/llm/completion/TransformerHandler.ts
ProviderSearchInjectorpackages/desktop/app/main/services/capabilities/llm/completion/ProviderSearchInjector.ts
NativeSearchInjectorpackages/desktop/app/main/services/capabilities/llm/completion/NativeSearchInjector.ts
URL Builderpackages/desktop/app/main/services/capabilities/llm/completion/url-builder.ts
Header Builderpackages/desktop/app/main/services/capabilities/llm/completion/header-builder.ts
Message Converterpackages/desktop/app/main/services/capabilities/llm/completion/message-converter.ts
Provider Presetspackages/desktop/app/shared/provider-presets.ts
IPC Routerspackages/desktop/app/main/services/routers/llm/

架构上下文​

graph TB
subgraph 前端 ["前端 (Renderer)"]
UI[Provider Settings UI]
ChatUI[Chat Interface]
end

subgraph IPC层
PR[ProviderRouter]
AKR[ApiKeyRouter]
CR[CompletionRouter]
RCR[RouterConfigRouter]
TR[TransformerRouter]
MPR[ModelParametersRouter]
end

subgraph LLMConfigService ["LLMConfigService (委托模式)"]
PM[ProviderManager]
MDM[ModelDiscoveryManager]
CIOM[ConfigIOManager]
AMM[AgentModelsManager]
end

subgraph CompletionService ["CompletionService (门面模式)"]
DAH[DirectApiHandler]
SH[StreamHandler]
TH[ToolHandler]
THR[TransformerHandler]
TR2[ThinkingResolver]
end

AKPS[ApiKeyPoolService]

subgraph 外部API
OpenAI[OpenAI API]
Anthropic[Anthropic API]
Gemini[Gemini API]
Azure[Azure OpenAI API]
Others[其他提供商...]
end

subgraph 存储
SQLite[(SQLite)]
JSON[(llms-config.json)]
end

UI --> PR
UI --> AKR
ChatUI --> CR

PR --> PM
AKR --> AKPS
CR --> CompletionService

PM --> SQLite
PM --> JSON
MDM --> SQLite
MDM --> JSON

CompletionService --> AKPS
CompletionService --> LLMConfigService
DAH --> OpenAI
DAH --> Anthropic
DAH --> Gemini
DAH --> Azure
SH --> OpenAI
SH --> Anthropic
SH --> Gemini
SH --> Azure

数据结构​

核心类型​

// API 格式枚举
type ApiFormat = 'openai' | 'anthropic' | 'google' | 'azure-openai' | 'openai-response';

// LLM 提供商
interface LLMProvider {
id: string; // 唯一标识
name: string; // 显示名称
apiFormat?: ApiFormat; // API 格式(首选字段)
chatApiFormat?: ApiFormat; // 遗留 API 格式字段
apiType?: string; // 遗留类型字段
api_base_url?: string; // API 基础 URL
api_key: string; // 单密钥(遗留)
models: string[]; // 模型 ID 列表
modelConfigs?: ModelConfig[]; // 模型详细配置
modelGroups?: ModelGroup[]; // 模型分组
modelsEndpoint?: string; // 模型发现端点
enabled: boolean; // 是否启用
transformer?: TransformerConfig; // 转换链配置
icon?: string; // 图标
website?: string; // 官网
docsUrl?: string; // 文档链接
defaultSettings?: CompletionSettings; // 默认补全参数
codingPlan?: CodingPlanConfig; // Coding Plan 配置
isSystem?: boolean; // 系统内置提供商
presetId?: string; // 预设模板 ID
createdAt: string;
updatedAt: string;
}

// Completion 请求选项
interface CompletionOptions {
providerId: string; // 提供商 ID
model: string; // 模型 ID
messages: SimpleChatMessage[]; // 消息列表
maxTokens?: number; // 最大 Token 数
temperature?: number; // 温度
stream?: boolean; // 是否流式
thinkLevel?: ThinkLevel; // 思考级别
nativeSearchAugmentation?: NativeSearchAugmentation; // 原生搜索增强
sessionId?: string; // 会话 ID(用于 API Key Pool 亲和性)
}

// API 密钥池条目
interface ApiKeyEntry {
id: string; // 唯一 ID
providerId: string; // 所属提供商
label?: string; // 显示标签
apiKey: string; // 密钥值
enabled: boolean; // 是否启用
weight: number; // 权重 (1-100)
}

数据流概览​

Completion 请求管线​

sequenceDiagram
participant Frontend as 前端
participant CS as CompletionService
participant LLC as LLMConfigService
participant AKP as ApiKeyPoolService
participant Handler as API Handler
participant API as Provider API

Frontend->>CS: complete() / completeStream()
CS->>LLC: resolveRoutedModel(providerId, model)
LLC-->>CS: actualProviderId + actualModel
CS->>LLC: getProvider(actualProviderId)
LLC-->>CS: provider config
CS->>CS: resolveApiKeyForRequest()
Note right of CS: 优先级: codingPlan > pool > legacy
CS->>AKP: getKeyForSession(providerId, sessionId)
AKP-->>CS: resolved API key
CS->>CS: resolveApiFormat(provider)
CS->>Handler: callDirectHandler / callStreamHandler
Handler->>API: HTTP request
API-->>Handler: response / SSE stream
Handler-->>CS: CompletionResult
alt 429/529 错误
CS->>AKP: reportError(providerId, sessionId, status)
AKP-->>CS: new key
CS->>Handler: retry with new key
end
CS->>AKP: reportSuccess(sessionId)
CS-->>Frontend: result

模块边界与职责​

模块职责不负责
CompletionService请求管线编排、格式分发、重试、Vision 回退Provider CRUD、密钥存储
ApiKeyPoolService多密钥负载均衡、会话亲和性、冷却退避密钥持久化(委托给 DB)
LLMConfigServiceProvider 配置管理、模型发现、路由、Transformer 链API 调用
ProviderManagerProvider CRUD、模板/预设系统、SQLite 持久化模型发现、路由配置
ModelDiscoveryManager模型列表发现、缓存(SQLite + 文件)Provider CRUD
ConfigIOManager配置导入/导出、JSON 文件 I/O数据库操作
AgentModelsManager路由配置、Transformer 管理、全局参数Provider CRUD
ThinkingResolvermax_tokens 解析、思考预算计算请求发送
StreamHandlerSSE 流式处理(OpenAI/Anthropic/Gemini)非流式请求
DirectApiHandler非流式 API 调用流式请求
ToolHandlerAgent 工具调用循环普通 Completion
TransformerHandlerTransformer 链 Completion直接 API 调用

IPC 集成表​

IPC 通道方向Router说明
llmConfig:getProvidersRenderer -> MainProviderRouter获取所有提供商
llmConfig:getProviderRenderer -> MainProviderRouter获取单个提供商
llmConfig:addProviderRenderer -> MainProviderRouter添加提供商
llmConfig:updateProviderRenderer -> MainProviderRouter更新提供商
llmConfig:deleteProviderRenderer -> MainProviderRouter删除提供商
llmConfig:toggleProviderRenderer -> MainProviderRouter启用/禁用提供商
llmConfig:discoverModelsRenderer -> MainProviderRouter发现模型列表
llmConfig:getProviderPresetsRenderer -> MainProviderRouter获取预设模板
llmConfig:addFromPresetRenderer -> MainProviderRouter从预设添加提供商
llmConfig:exportConfigRenderer -> MainProviderRouter导出配置
llmConfig:importConfigRenderer -> MainProviderRouter导入配置
llmConfig:getApiKeysRenderer -> MainApiKeyRouter获取密钥列表
llmConfig:addApiKeyRenderer -> MainApiKeyRouter添加密钥
llmConfig:updateApiKeyRenderer -> MainApiKeyRouter更新密钥
llmConfig:deleteApiKeyRenderer -> MainApiKeyRouter删除密钥
llmConfig:toggleApiKeyRenderer -> MainApiKeyRouter启用/禁用密钥

扩展点​

  • 新增 API 格式:在 url-builder.ts 添加 URL 构建函数,在 DirectApiHandler.ts / StreamHandler.ts 添加处理函数,在 CompletionService 的 switch 中注册
  • 新增提供商预设:在 provider-presets.ts 的 PROVIDER_PRESETS 数组中添加模板
  • 新增搜索配置:在 provider-presets.ts 的 PROVIDER_SEARCH_CONFIGS 中添加条目
  • 自定义 Transformer:通过 AgentModelsManager 注册新的 Transformer 链

关联文件表​

文件用途
packages/desktop/app/shared/llm-config.tsLLM 配置共享类型定义
packages/desktop/app/shared/completion-types.tsCompletion 类型定义
packages/desktop/app/shared/thinking-config.ts思考配置与预算计算
packages/desktop/app/shared/provider-presets.ts提供商预设模板与搜索配置
packages/desktop/app/main/services/routers/llm/schemas.tsIPC 请求 Zod 验证 Schema
packages/desktop/app/main/services/capabilities/llm/config-service/schemas.ts配置服务内部 Zod Schema
packages/desktop/app/main/services/infra/utils/sse-parser.tsSSE 流解析工具
packages/desktop/app/main/workers/db/apiKeys.tsAPI 密钥数据库操作
packages/desktop/app/main/workers/DbClient.ts数据库客户端
packages/desktop/app/preload/index.tsPreload API 暴露