Managing LLM

LLM 프로바이더 관리

모듈 구조

packages/core/src/llm/ 디렉토리 (6 파일):

LLMProvider 인터페이스

types.ts에서 정의. 모든 어댑터가 구현하는 공통 인터페이스:

interface LLMProvider {
  readonly name: LLMProviderName;  // "gemini" | "openai"
  generateContent(prompt: string, options: LLMGenerationOptions): Promise<LLMGenerationResult>;
  countTokens(text: string, model?: string): Promise<number>;
}

• LLMGenerationOptions: systemPrompt, responseMimeType, maxOutputTokens, model
• LLMGenerationResult: text, tokenUsage, modelId, actualCost?
• LLMModelId: { provider: LLMProviderName, model: string }

Factory 패턴

factory.ts의 createLLMClient(provider):

• adapterCache (Map)로 어댑터 싱글톤 캐싱
• "gemini" -> GeminiAdapter, "openai" -> OpenAIAdapter
• 지원하지 않는 provider -> Error throw

기본 모델 결정 (getDefaultModelId()):

1. ANKI_SPLITTER_DEFAULT_LLM_PROVIDER 환경변수 확인
2. 해당 provider가 미가용이면 가용 provider로 graceful fallback
3. ANKI_SPLITTER_DEFAULT_LLM_MODEL 환경변수 또는 provider별 기본 모델

가용 프로바이더 확인 (getAvailableProviders()):

• GEMINI_API_KEY 설정 여부 -> gemini
• OPENAI_API_KEY 설정 여부 -> openai

Adapter 패턴

GeminiAdapter (gemini.ts)

• SDK: @google/genai (GoogleGenAI)
• 클라이언트: lazy 싱글톤 (genAI 변수)
• 기본 모델: gemini-3-flash-preview
• countTokens: SDK 네이티브 client.models.countTokens() 사용
• 토큰 사용량: response.usageMetadata에서 추출

OpenAIAdapter (openai.ts)

• SDK: openai (dynamic import)
• API: Responses API (client.responses.create())
• 기본 모델: gpt-5.4-mini
• 시스템 프롬프트 role: developer (OpenAI Responses API에서 system 대신 developer 사용)
• JSON 모드: text.format.type = "json_object" + markdown code fence 제거
• JSON 파싱 실패 시 temperature 0.1로 1회 재시도 (토큰 누적 합산)
• refusal 체크: content.type === "refusal" 감지 시 에러 throw
• countTokens: 휴리스틱 추정 (한국어 보정 x1.5, safety x1.3)

getClient() 차이: GeminiAdapter의 getClient()는 동기(sync), OpenAIAdapter의 getClient()는 비동기(async) -- dynamic import로 번들 최적화하기 때문.

가격 시스템 (pricing.ts)

가격표, 비용 계산, 예산 가드 상세는 references/pricing.md 참조.

핵심 함수:

• getModelPricing(provider, model) -- 가격 조회
• estimateCost() / computeCost() -- 사전/사후 비용 계산
• checkBudget(estimatedCostUsd, clientBudgetCapUsd?) -- 이중 예산 가드
• getServerBudgetCapUsd() -- 서버 사이드 예산 캡 조회 (env 기본 $1.0)

API 엔드포인트

GET /api/llm/models (packages/server/src/routes/llm.ts)

응답:

{
  "models": [
    {
      "provider": "gemini",
      "model": "gemini-3-flash-preview",
      "displayName": "Gemini 3 Flash Preview",
      "inputPricePerMillionTokens": 0.15,
      "outputPricePerMillionTokens": 0.6
    }
  ],
  "defaultModelId": { "provider": "gemini", "model": "gemini-3-flash-preview" },
  "budgetCapUsd": 1.0,
  "availableProviders": ["gemini", "openai"]
}

• API 키가 설정된 provider의 모델만 반환
• 기본 모델이 가용 목록에 없으면 첫 번째 가용 모델로 대체
• budgetCapUsd는 서버에서 getServerBudgetCapUsd() 호출 결과

프론트엔드 컴포넌트

ModelBadge (packages/web/src/components/ui/model-badge.tsx)

• provider별 스타일: gemini(파란색, "G"), openai(에메랄드, "O"), fallback("?")
• props: provider, model?, className?
• 사용처: SplitWorkspace.tsx, SplitHistory.tsx

formatCostUsd (model-badge.tsx에서 export)

• < $0.001 -> 소수점 6자리
• < $0.01 -> 소수점 4자리
• 그 외 -> 소수점 2자리

환경변수

상세 참조

• references/architecture.md -- LLM 모듈 아키텍처 상세, 새 프로바이더 추가 가이드
• references/pricing.md -- MODEL_PRICING_TABLE 전체, 비용 계산/예산 가드 로직
• references/troubleshooting.md -- API 키 미설정, 예산 초과, 지원되지 않는 모델 시 동작