跳到主要内容

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 暴露