# Managing LLM

> LLM 추상화 계층, 프로바이더 어댑터, 가격표, 예산 가드 등 LLM 관련 작업이면 무조건 이 스킬. 모델 변경, 프로바이더 추가, 비용 계산, 토큰 카운트 등 모든 LLM 인프라를 다룬다. Triggers: "LLM 모델 변경", "프로바이더 추가", "비용 추정", "예산 가드", "pricing table", "모델 비교", "LLM 비용", "토큰 사용량", "모델 추가", "LLM 설정", "Gemini", "OpenAI", "API key", "model pricing", "budget cap", "token count", "adapter", "factory".

- Skill: `shren207/managing-llm` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add shren207/managing-llm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shren207/managing-llm/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: shren207 (https://skillmd.com/u/shren207)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/shren207/managing-llm

---


# LLM 프로바이더 관리

## 모듈 구조

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

| 파일 | 역할 |
|------|------|
| `types.ts` | 공유 타입 정의 (`LLMProvider`, `LLMModelId`, `TokenUsage`, `CostEstimate`, `ActualCost`) |
| `factory.ts` | 팩토리 함수 (`createLLMClient`), 기본 모델 결정, 가용 프로바이더 탐색 |
| `gemini.ts` | Gemini 어댑터 (`GeminiAdapter`) - `@google/genai` SDK 사용 |
| `openai.ts` | OpenAI 어댑터 (`OpenAIAdapter`) - Responses API + JSON 안정성 보호 |
| `pricing.ts` | 가격표 (`MODEL_PRICING_TABLE`), 비용 계산, 예산 가드레일 |
| `index.ts` | Barrel export |

## LLMProvider 인터페이스

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

```typescript
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`)

응답:
```json
{
  "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자리

## 환경변수

| 변수 | 용도 | 기본값 |
|------|------|--------|
| `GEMINI_API_KEY` | Gemini API 인증 | (필수) |
| `OPENAI_API_KEY` | OpenAI API 인증 | (선택) |
| `ANKI_SPLITTER_DEFAULT_LLM_PROVIDER` | 기본 프로바이더 | `gemini` |
| `ANKI_SPLITTER_DEFAULT_LLM_MODEL` | 기본 모델 | provider별 기본값 |
| `ANKI_SPLITTER_BUDGET_CAP_USD` | 서버 예산 상한 | `1.0` |

## 상세 참조

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