본문으로 건너뛰기

LLM 프로바이더 모듈 개요

이 문서는 Elftia 내 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 Frontend ["Frontend (Renderer)"]
        UI[Provider Settings UI]
        ChatUI[Chat Interface]
    end

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

    subgraph LLMConfigService ["LLMConfigService (Delegate Pattern)"]
        PM[ProviderManager]
        MDM[ModelDiscoveryManager]
        CIOM[ConfigIOManager]
        AMM[AgentModelsManager]
    end

    subgraph CompletionService ["CompletionService (Facade Pattern)"]
        DAH[DirectApiHandler]
        SH[StreamHandler]
        TH[ToolHandler]
        THR[TransformerHandler]
        TR2[ThinkingResolver]
    end

    AKPS[ApiKeyPoolService]

    subgraph ExternalAPIs ["External APIs"]
        OpenAI[OpenAI API]
        Anthropic[Anthropic API]
        Gemini[Gemini API]
        Azure[Azure OpenAI API]
        Others[Other Providers...]
    end

    subgraph Storage ["Storage"]
        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 format enum
type ApiFormat = 'openai' | 'anthropic' | 'google' | 'azure-openai' | 'openai-response';

// LLM provider
interface LLMProvider {
  id: string;                       // Unique identifier
  name: string;                     // Display name
  apiFormat?: ApiFormat;            // API format (preferred field)
  chatApiFormat?: ApiFormat;        // Legacy API format field
  apiType?: string;                 // Legacy type field
  api_base_url?: string;           // API base URL
  api_key: string;                 // Single key (legacy)
  models: string[];                // Model ID list
  modelConfigs?: ModelConfig[];    // Per-model detailed config
  modelGroups?: ModelGroup[];      // Model groups
  modelsEndpoint?: string;         // Model discovery endpoint
  enabled: boolean;                // Whether enabled
  transformer?: TransformerConfig; // Transformer chain config
  icon?: string;                   // Icon
  website?: string;                // Official website
  docsUrl?: string;                // Documentation link
  defaultSettings?: CompletionSettings; // Default completion parameters
  codingPlan?: CodingPlanConfig;   // Coding Plan config
  isSystem?: boolean;              // System built-in provider
  presetId?: string;               // Preset template ID
  createdAt: string;
  updatedAt: string;
}

// Completion request options
interface CompletionOptions {
  providerId: string;              // Provider ID
  model: string;                   // Model ID
  messages: SimpleChatMessage[];   // Message list
  maxTokens?: number;              // Max token count
  temperature?: number;            // Temperature
  stream?: boolean;                // Whether streaming
  thinkLevel?: ThinkLevel;         // Thinking level
  nativeSearchAugmentation?: NativeSearchAugmentation; // Native search augmentation
  sessionId?: string;              // Session ID (for API Key Pool affinity)
}

// API key pool entry
interface ApiKeyEntry {
  id: string;                      // Unique ID
  providerId: string;              // Owning provider
  label?: string;                  // Display label
  apiKey: string;                  // Key value
  enabled: boolean;                // Whether enabled
  weight: number;                  // Weight (1-100)
}

데이터 흐름 개요​

Completion 요청 파이프라인​

sequenceDiagram
    participant Frontend as Frontend
    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: Priority: 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 error
        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요청 파이프라인 오케스트레이션, 포맷 디스패치, 재시도, 비전 폴백프로바이더 CRUD, 키 저장
ApiKeyPoolService다중 키 로드 밸런싱, 세션 친화성, 쿨다운 백오프키 영속화 (DB에 위임)
LLMConfigService프로바이더 설정 관리, 모델 검색, 라우팅, Transformer 체인API 호출
ProviderManager프로바이더 CRUD, 템플릿/프리셋 시스템, SQLite 영속화모델 검색, 라우팅 설정
ModelDiscoveryManager모델 목록 검색, 캐싱 (SQLite + 파일)프로바이더 CRUD
ConfigIOManager설정 가져오기/내보내기, JSON 파일 I/O데이터베이스 작업
AgentModelsManager라우팅 설정, Transformer 관리, 전역 파라미터프로바이더 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 유효성 검사 스키마
packages/desktop/app/main/services/capabilities/llm/config-service/schemas.ts설정 서비스 내부 Zod 스키마
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 노출