create-entity-app-server 0.0.3

package/docs/plugins/llm.md

@@ -0,0 +1,567 @@
+# LLM(대형 언어 모델) 가이드
+
+OpenAI, Anthropic, Google Gemini, Ollama 등 다양한 LLM 프로바이더를 통한 채팅·RAG 기능 가이드입니다.
+
+이 문서는 플러그인의 개요/설정/운영 가이드를 중심으로 다룹니다.  
+실제 라우트표, 호출 예제, 응답 예제는 [LLM Routes](../routes/llm-routes.md) 문서를 참고하세요.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+    - [지원 드라이버 목록](#지원-드라이버-목록)
+- [API 유형 비교](#api-유형-비교)
+- [Profile Memory](#profile-memory)
+- [프로바이더 비교](#프로바이더-비교)
+    - [클라우드 프로바이더](#클라우드-프로바이더)
+    - [로컬(자체 호스팅) 프로바이더](#로컬자체-호스팅-프로바이더)
+    - [성격·용도별 추천](#성격용도별-추천)
+    - [문서 처리](#-문서-처리)
+    - [대화·챗봇](#-대화--챗봇)
+    - [추론·분석](#-추론--분석)
+    - [코드·개발](#-코드--개발)
+    - [멀티모달·이미지](#️-멀티모달--이미지)
+    - [보안·인프라](#-보안--인프라)
+- [성능 비교](#성능-비교)
+    - [종합 벤치마크](#종합-벤치마크)
+    - [한국어 벤치마크](#한국어-벤치마크)
+    - [코드 벤치마크](#코드-벤치마크)
+    - [추론 벤치마크](#추론-벤치마크)
+    - [속도·비용 효율](#속도비용-효율)
+- [모델 비교](#모델-비교)
+    - [OpenAI](#openai-모델)
+    - [Anthropic](#anthropic-모델)
+    - [Google Gemini](#google-gemini-모델)
+    - [Meta Llama](#meta-llama-모델)
+    - [기타 클라우드 모델](#기타-클라우드-모델)
+    - [한국어 특화 모델](#한국어-특화-모델)
+- [API 레퍼런스](#api-레퍼런스)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+Gateway의 LLM 플러그인은 여러 AI 프로바이더를 단일 API로 추상화합니다.
+
+- 채팅 완성 (단발/스트리밍)
+- 멀티턴 대화 세션 관리
+- RAG (문서 업로드 → 벡터 검색 → 컨텍스트 주입)
+- Profile Memory (사용자별 기억 항목 DB 저장 · 대화 시 system prompt 자동 주입)
+- 사용량 추적
+
+---
+
+## 설정
+
+`configs/plugins/llm.json`:
+
+```json
+{
+    "enabled": false,
+    "default": "main",
+    "providers": {
+        "main": {
+            "driver": "openai",
+            "api_key": "${LLM_OPENAI_API_KEY}",
+            "model": "gpt-4o-mini"
+        },
+        "chatbot": {
+            "driver": "anthropic",
+            "api_key": "${LLM_ANTHROPIC_API_KEY}",
+            "model": "claude-sonnet-4-20250514"
+        },
+        "summary": {
+            "driver": "gemini",
+            "api_key": "${LLM_GEMINI_API_KEY}",
+            "model": "gemini-2.0-flash"
+        },
+        "fast": {
+            "driver": "groq",
+            "api_key": "${LLM_GROQ_API_KEY}",
+            "model": "llama-3.3-70b-versatile"
+        },
+        "ollama": {
+            "driver": "ollama",
+            "base_url": "http://localhost:11434",
+            "model": "llama3.2:3b"
+        }
+    },
+    "cache": {
+        "enabled": true,
+        "ttl_seconds": 3600,
+        "max_entries": 10000
+    }
+}
+```
+
+### 환경변수 (.env)
+
+```env
+LLM_OPENAI_API_KEY=sk-...
+LLM_ANTHROPIC_API_KEY=sk-ant-...
+LLM_GEMINI_API_KEY=AIza...
+LLM_GROQ_API_KEY=gsk_...
+```
+
+### 지원 드라이버 목록
+
+| driver                  | 유형     | 구현 방식   | 설명                             |
+| ----------------------- | -------- | ----------- | -------------------------------- |
+| `openai`                | 클라우드 | 전용        | OpenAI API                       |
+| `anthropic`             | 클라우드 | 전용        | Anthropic Claude                 |
+| `gemini`                | 클라우드 | 전용        | Google Gemini                    |
+| `azure_openai`          | 클라우드 | 전용        | Azure OpenAI (API-Key 헤더 구조) |
+| `groq`                  | 클라우드 | OpenAI 호환 | Groq 초고속 추론                 |
+| `deepseek`              | 클라우드 | OpenAI 호환 | DeepSeek                         |
+| `mistral`               | 클라우드 | OpenAI 호환 | Mistral AI                       |
+| `together`              | 클라우드 | OpenAI 호환 | Together AI                      |
+| `perplexity`            | 클라우드 | OpenAI 호환 | Perplexity AI                    |
+| `ollama`                | 로컬     | 전용        | Ollama 자체 프로토콜             |
+| `vllm`                  | 로컬     | OpenAI 호환 | vLLM (`:8000`)                   |
+| `lmstudio`              | 로컬     | OpenAI 호환 | LM Studio (`:1234`)              |
+| `llamacpp`              | 로컬     | OpenAI 호환 | llama.cpp server (`:8080`)       |
+| `koboldcpp`             | 로컬     | OpenAI 호환 | KoboldCpp (`:5001`)              |
+| `text_generation_webui` | 로컬     | OpenAI 호환 | Text Generation WebUI (`:5000`)  |
+| `localai`               | 로컬     | OpenAI 호환 | LocalAI (`:8080`)                |
+| `tabbyapi`              | 로컬     | OpenAI 호환 | TabbyAPI / ExLlamaV2 (`:5000`)   |
+| `jan`                   | 로컬     | OpenAI 호환 | Jan Desktop (`:1337`)            |
+| `xinference`            | 로컬     | OpenAI 호환 | Xinference (`:9997`)             |
+| `openwebui`             | 로컬     | OpenAI 호환 | Open WebUI 프록시 (`:3000`)      |
+
+> **OpenAI 호환 driver**는 `base_url`을 직접 지정해 다른 호환 API 서버에도 연결할 수 있습니다.
+
+---
+
+## API 유형 비교
+
+| 구분                | `/chat`                 | `/:name/chat` (template)         | `/conversations`                     | `/chatbots/:seq/chat`                 |
+| ------------------- | ----------------------- | -------------------------------- | ------------------------------------ | ------------------------------------- |
+| **용도**            | 자유 형식 단일 요청     | 미리 정의된 프롬프트 패턴 재사용 | 범용 지속 대화 (직접 세션 관리)      | 봇 설정 기반 지속 대화 + RAG 통합     |
+| **대화 히스토리**   | ❌ 없음                 | ❌ 없음                          | ✅ 세션별 누적                       | ✅ 세션별 누적                        |
+| **RAG 검색**        | ❌ 없음                 | ❌ 없음                          | ❌ 없음                              | ✅ 챗봇 설정에 따라 자동 수행         |
+| **시스템 프롬프트** | 요청마다 직접 전달      | 템플릿 파일에 고정               | 세션 생성 시 1회 전달                | `llm_chatbot` 엔티티에 저장           |
+| **봇 설정 (DB)**    | ❌ 없음                 | ❌ 없음                          | ❌ 없음                              | ✅ `llm_chatbot` 엔티티로 관리        |
+| **세션 시작 방법**  | 없음 (매번 독립 호출)   | 없음                             | `POST /conversations` 로 명시적 생성 | `session_seq=0` 전달 시 자동 생성     |
+| **이어 대화 방법**  | 없음                    | 없음                             | `POST /conversations/:seq/messages`  | `session_seq` 재사용, 단일 엔드포인트 |
+| **입력**            | `messages[]` 배열       | `variables` 맵 (`{{var}}` 치환)  | `message` 단일 문자열                | `message` 단일 문자열                 |
+| **주요 사용처**     | 코드 내 단발성 LLM 호출 | 요약·번역 등 반복 작업 자동화    | 사용자별 채팅 로그 직접 구축         | 챗봇 UI, 고객 지원, 사내 Q&A          |
+
+> **선택 가이드**
+>
+> - 단순 프롬프트 → `/chat`
+> - 변수를 주입하는 반복 패턴 → `/:name/chat`
+> - 대화 맥락 유지, 설정 없이 직접 제어 → `/conversations`
+> - 봇 설정 재사용 + 문서 기반 답변 → `/chatbots/:seq/chat`
+
+> **conversations vs chatbots 선택 기준**
+>
+> 봇 페르소나란 챗봇에 부여하는 고정된 역할/성격 설정으로, 시스템 프롬프트·이름·환영 메시지 등을 묶어 DB에 저장한 것을 말한다.  
+> 예: "당신은 친절한 고객 지원 담당자입니다. 제공된 자료를 기반으로만 답변하세요."
+>
+> - **`/conversations`**: 봇 페르소나 없이 순수 대화 이력만 필요한 경우. 시스템 프롬프트·RAG를 직접 제어해야 하는 경우.
+> - **`/chatbots/:seq/chat`**: 봇 설정(시스템 프롬프트·RAG·환영 메시지)을 DB에 저장하고 재사용해야 하는 경우. 여러 봇 인격을 운영할 때.
+
+---
+
+## Profile Memory
+
+사용자별 기억 항목(이름·선호·목표 등)을 `llm_user_profile` 엔티티에 저장하고, 대화 시 system prompt에 자동 주입하는 기능입니다.
+
+### 동작 방식
+
+1. `POST /api/v1/llm/profiles` 로 항목 등록 (`user_seq + scope + key` 기준 upsert)
+2. `POST /api/v1/llm/conversations` 또는 `chatbots/:seq/chat` 호출 시 `user_seq` 전달
+3. 서버가 해당 사용자의 활성 메모리를 조회해 system prompt 뒤에 자동 삽입
+
+### System Prompt 주입 예시
+
+```
+[사용자 메모리]
+- name: 홍길동
+- preference: 답변은 짧고 핵심만
+- goal: React 마스터하기
+```
+
+### Scope (범위)
+
+| scope 값        | 설명                           |
+| --------------- | ------------------------------ |
+| `global`        | 모든 대화에 공통 적용 (기본값) |
+| `chatbot_{seq}` | 특정 챗봇에만 적용             |
+
+챗봇 대화 시 `chatbot_{seq}` scope → `global` scope 순서로 fallback 조회합니다.
+
+### 엔티티: llm_user_profile
+
+| 필드          | 설명                                        |
+| ------------- | ------------------------------------------- |
+| `user_seq`    | 소유 사용자                                 |
+| `scope`       | 메모리 범위 (`global` / `chatbot_{seq}`)    |
+| `chatbot_seq` | scope=chatbot 일 때 연결된 챗봇             |
+| `key`         | 메모리 키 (`name`, `preference` 등)         |
+| `value`       | 메모리 값 (자연어 문장)                     |
+| `source`      | `manual`(직접 입력) / `extracted`(LLM 추출) |
+| `status`      | `active` / `inactive`                       |
+
+> Profile Memory API 상세는 [LLM Routes — Profile Memory](../routes/llm-routes.md#get-v1apillmprofiles) 문서를 참고하세요.
+
+---
+
+## 프로바이더 비교
+
+### 클라우드 프로바이더
+
+| provider      | driver         | 대표 모델                        | 한글 지원 | 비용    | 컨텍스트 창    | 강점                                    | 적합한 용도                               |
+| ------------- | -------------- | -------------------------------- | --------- | ------- | -------------- | --------------------------------------- | ----------------------------------------- |
+| OpenAI        | `openai`       | gpt-4o, gpt-4o-mini, o1, o3      | ★★★★★     | 중~고   | 최대 128K      | 생태계·도구 호환성 최고, 추론 모델 지원 | 범용, 코드 생성, 에이전트, JSON 모드      |
+| Anthropic     | `anthropic`    | claude-opus-4, claude-sonnet-4   | ★★★★★     | 중~고   | 최대 200K      | 긴 문서 처리, 안전성, 지시 준수         | 문서 요약, 고품질 글쓰기, 정교한 지시사항 |
+| Google Gemini | `gemini`       | gemini-2.5-pro, gemini-2.0-flash | ★★★★★     | 저~중   | 최대 1M (Pro)  | 멀티모달, 초장문 컨텍스트               | 이미지·영상 분석, 대문서 처리             |
+| Groq          | `groq`         | llama-3.3-70b, mixtral-8x7b      | ★★★☆☆     | 저      | 최대 128K      | LPU 기반 초고속 추론 (최저 레이턴시)    | 실시간 챗봇, 저지연 API, 빠른 요약        |
+| DeepSeek      | `deepseek`     | deepseek-chat, deepseek-reasoner | ★★★★☆     | 매우 저 | 최대 64K       | 비용 대비 성능 최상, 추론(CoT) 특화     | 비용 최적화, 수학·코드 추론               |
+| Mistral AI    | `mistral`      | mistral-large, mistral-small     | ★★★☆☆     | 저~중   | 최대 128K      | 유럽 GDPR 준수, 경량 고성능             | 유럽 서비스, 유연한 라이선스              |
+| Together AI   | `together`     | Llama-3.3, Qwen-2.5, DBRX 등     | ★★★☆☆     | 저      | 모델 의존      | 다양한 오픈소스 모델 API 제공           | 오픈소스 모델 실험, 비용 절감             |
+| Perplexity    | `perplexity`   | sonar-pro, sonar-reasoning       | ★★★★☆     | 중      | 최대 127K      | 실시간 웹 검색 자동 통합                | 최신 정보 답변, 검색 증강 Q&A             |
+| Azure OpenAI  | `azure_openai` | gpt-4o (배포판)                  | ★★★★★     | 중~고   | 배포 설정 의존 | 엔터프라이즈 SLA, VNet 격리             | 금융·공공 등 컴플라이언스 필요 환경       |
+
+> **비용 기준**: 매우 저 < 저 < 중 < 고 (입력 1M 토큰 기준 상대 비교, 2026년 초 기준)
+
+---
+
+### 로컬(자체 호스팅) 프로바이더
+
+| provider              | driver                  | 추론 백엔드    | GPU 필요  | 처리량 | 한글 지원 | 설치 난이도  | 강점                                | 적합한 용도                       |
+| --------------------- | ----------------------- | -------------- | --------- | ------ | --------- | ------------ | ----------------------------------- | --------------------------------- |
+| Ollama                | `ollama`                | llama.cpp 내장 | ❌ (권장) | ★★★☆☆  | 모델 의존 | ★☆☆☆☆ 쉬움   | 설치 한 줄, 모델 자동 다운로드      | 개발·테스트, 보안 민감 데이터     |
+| vLLM                  | `vllm`                  | PagedAttention | ✅ 필수   | ★★★★★  | 모델 의존 | ★★★★☆ 어려움 | 최고 처리량, OpenAI 호환 서버       | 프로덕션 GPU 서버, 대량 배치 추론 |
+| LM Studio             | `lmstudio`              | llama.cpp 기반 | ❌ (권장) | ★★★☆☆  | 모델 의존 | ★☆☆☆☆ 쉬움   | GUI로 모델 관리, 개발자 친화적      | 로컬 개발 환경, 모델 실험         |
+| llama.cpp             | `llamacpp`              | CPU/Metal/CUDA | ❌        | ★★★☆☆  | 모델 의존 | ★★★☆☆ 보통   | CPU 추론 가능, 경량, GGUF 포맷      | CPU 전용 서버, 저사양 환경        |
+| KoboldCpp             | `koboldcpp`             | llama.cpp 기반 | ❌        | ★★★☆☆  | 모델 의존 | ★★☆☆☆ 쉬움   | 창작/롤플레이 특화 샘플링 옵션      | 창작 보조, 캐릭터 챗봇            |
+| Text Generation WebUI | `text_generation_webui` | 다중 백엔드    | ❌ (권장) | ★★★☆☆  | 모델 의존 | ★★★☆☆ 보통   | 다양한 모델 포맷·백엔드 지원        | 모델 실험·비교, 연구 목적         |
+| LocalAI               | `localai`               | 다중 백엔드    | ❌        | ★★★☆☆  | 모델 의존 | ★★★☆☆ 보통   | OpenAI API 완전 호환, 멀티모달 지원 | 기존 OpenAI 코드 오프라인 전환    |
+| TabbyAPI              | `tabbyapi`              | ExLlamaV2      | ✅ 권장   | ★★★★☆  | 모델 의존 | ★★★☆☆ 보통   | EXL2 양자화로 VRAM 효율 극대화      | 고성능 로컬 서버, 코드 자동완성   |
+
+> **설치 난이도 기준**: ★☆☆☆☆ 매우 쉬움 ~ ★★★★★ 매우 어려움  
+> **한글 지원 (로컬)**: 로컬 서버는 로드하는 모델에 따라 한글 품질이 결정됩니다. 한글에 강한 모델로는 EXAONE-3.5, HyperCLOVA X, Qwen-2.5 (한글 포함 다국어), Llama-3-Korean-Bllossom 계열을 권장합니다.
+
+---
+
+### 성격·용도별 추천
+
+#### 📄 문서 처리
+
+| 용도                          | 1순위 추천                              | 대안                          | 추천 이유                                                       |
+| ----------------------------- | --------------------------------------- | ----------------------------- | --------------------------------------------------------------- |
+| 장문 문서 요약 (10만 자 이상) | Gemini 2.5 Pro                          | Anthropic claude-sonnet-4     | 1M 컨텍스트로 문서 전체를 한 번에 처리                          |
+| 단문 요약 · 뉴스 요약         | Groq (llama-3.3-70b)                    | gpt-4o-mini, gemini-2.0-flash | 저비용 고속, 간단한 요약은 경량 모델로 충분                     |
+| 계약서 · 법률 문서 분석       | Anthropic claude-opus-4                 | gpt-4o                        | 긴 지시사항 준수율·안전성 최고, 섬세한 조건 해석                |
+| PDF/문서 OCR 후 내용 추출     | Gemini 2.0 Flash                        | gpt-4o (vision)               | 멀티모달 + 저비용 고속, 이미지 포함 PDF 처리에 유리             |
+| 다국어 문서 번역 (한↔영↔중)   | DeepSeek V3 또는 Qwen-2.5-72B           | gpt-4o, claude-sonnet-4       | 한·중·영 3개 언어 모두 우수하며 비용 대비 품질 탁월             |
+| 한국어 문서 요약·분류         | EXAONE-3.5-32B (로컬) 또는 Qwen-2.5-72B | claude-sonnet-4, HyperCLOVA X | 한국어 뉘앙스·고유명사 처리 최적, 데이터 보안 필요 시 로컬 권장 |
+
+---
+
+#### 💬 대화 · 챗봇
+
+| 용도                         | 1순위 추천                             | 대안                               | 추천 이유                                                |
+| ---------------------------- | -------------------------------------- | ---------------------------------- | -------------------------------------------------------- |
+| 고객 지원 챗봇 (한국어)      | claude-sonnet-4                        | Kanana-1.5-8B (로컬), HyperCLOVA X | 지시 준수율·자연스러운 한국어 표현 최고                  |
+| 실시간 응답 요구 챗봇        | Groq (llama-3.3-70b)                   | Gemini 2.0 Flash                   | LPU로 평균 0.5초 이하 첫 토큰 응답                       |
+| 다중 봇 인격 운영 (RAG 포함) | Anthropic claude-sonnet-4              | gpt-4o                             | `/chatbots/:seq/chat` + RAG 플로우에 최적                |
+| 창작 · 롤플레이 챗봇         | KoboldCpp + 로컬 모델                  | claude-sonnet-4                    | 창작 특화 샘플링 파라미터, 사내 데이터 유출 없음         |
+| FAQ 자동 응답 (저비용 대량)  | gpt-4o-mini 또는 gemini-2.0-flash-lite | DeepSeek V3                        | 1M 토큰당 $0.075~$0.15 수준, 단순 FAQ는 소형 모델로 충분 |
+| 음성 기반 실시간 대화        | OpenAI gpt-4o-realtime                 | —                                  | 음성 입출력 네이티브 지원, 별도 STT/TTS 불필요           |
+
+---
+
+#### 🧠 추론 · 분석
+
+| 용도                           | 1순위 추천                  | 대안           | 추천 이유                                                  |
+| ------------------------------ | --------------------------- | -------------- | ---------------------------------------------------------- |
+| 복잡한 수학 · 과학 문제        | OpenAI o3                   | DeepSeek R1    | 사고 연쇄(Chain-of-Thought) 추론 성능 최상                 |
+| 비용 효율적 추론               | DeepSeek R1                 | OpenAI o3-mini | o1 수준 추론을 1/10 비용으로, 수학·코드·논리에 특화        |
+| 비즈니스 데이터 분석 · 리포트  | gpt-4o 또는 claude-sonnet-4 | Gemini 2.5 Pro | 구조적 출력(JSON mode)과 긴 컨텍스트 분석 모두 안정적      |
+| 금융 · 법률 컴플라이언스 분석  | Azure OpenAI (gpt-4o)       | claude-opus-4  | 엔터프라이즈 SLA + VNet 격리, 데이터 주권 보장             |
+| 경쟁사 · 시장 조사 (최신 정보) | Perplexity sonar-pro        | —              | 실시간 웹 검색 자동 통합, GPT에 웹 검색 붙이는 것보다 간편 |
+
+---
+
+#### 💻 코드 · 개발
+
+| 용도                     | 1순위 추천                      | 대안                    | 추천 이유                                                   |
+| ------------------------ | ------------------------------- | ----------------------- | ----------------------------------------------------------- |
+| 코드 생성 · 리뷰 (범용)  | gpt-4o 또는 claude-sonnet-4     | DeepSeek V3             | 도구 호출·JSON mode 안정성 최고, 긴 코드 컨텍스트 처리 우수 |
+| 코드 자동완성 (로컬 IDE) | TabbyAPI + Qwen-2.5-Coder-32B   | Ollama + deepseek-coder | ExLlamaV2 양자화로 VRAM 효율 극대화, 저지연 completions     |
+| 코드 추론 · 버그 분석    | DeepSeek R1 또는 OpenAI o3      | claude-opus-4           | CoT 기반 단계적 디버깅, 복잡한 알고리즘 분석에 강점         |
+| SQL/데이터 쿼리 생성     | gpt-4o-mini 또는 Qwen-2.5-Coder | claude-haiku-3.5        | 구조화된 쿼리 생성에 소형 모델도 충분, 비용 절감 가능       |
+| 테스트 코드 자동 생성    | claude-sonnet-4                 | gpt-4o                  | 지시사항 준수율 높고 엣지케이스 자동 식별 능력 우수         |
+
+---
+
+#### 🖼️ 멀티모달 · 이미지
+
+| 용도                        | 1순위 추천                    | 대안                 | 추천 이유                                           |
+| --------------------------- | ----------------------------- | -------------------- | --------------------------------------------------- |
+| 이미지 → 텍스트 설명 (대량) | Gemini 2.0 Flash              | gpt-4o-mini (vision) | 저비용 + 이미지 처리 성능 우수, 배치 처리에 적합    |
+| 정밀 이미지 분석 · OCR      | gpt-4o 또는 Gemini 2.5 Pro    | claude-sonnet-4      | 세밀한 시각 분석, 복잡한 표/그래프 해석             |
+| 영상 프레임 분석            | Gemini 2.0 Flash              | —                    | 영상 직접 입력 지원 (YouTube URL, 업로드 모두 가능) |
+| 로컬 이미지 분석 (보안)     | Ollama + Llama-3.2-11B-Vision | LM Studio + LLaVA    | GPU 없이도 CPU로 동작 가능, 이미지 외부 전송 없음   |
+
+---
+
+#### 🔒 보안 · 인프라
+
+| 용도                      | 1순위 추천                                | 대안                             | 추천 이유                                       |
+| ------------------------- | ----------------------------------------- | -------------------------------- | ----------------------------------------------- |
+| 내부망 전용 (인터넷 차단) | vLLM + EXAONE-3.5 또는 Qwen-2.5           | Ollama (소규모)                  | 완전 오프라인 운영, 외부 API 호출 없음          |
+| 의료 · 금융 개인정보 처리 | Ollama/vLLM 자체 호스팅                   | Azure OpenAI (HIPAA BAA 체결 시) | 데이터가 외부 서버에 전송되지 않음              |
+| 고가용성 프로덕션 서비스  | vLLM (GPU 서버) 또는 Azure OpenAI         | Together AI                      | SLA 보장, 트래픽 스파이크에 수평 확장 가능      |
+| 공공기관 · ISMS-P 준수    | Azure OpenAI (국내 리전) 또는 자체 호스팅 | —                                | 국내 데이터 주권 요건 충족, 감사 로그 보관 가능 |
+
+---
+
+## 성능 비교
+
+> 아래 수치는 공개된 벤치마크 결과 및 리더보드(Chatbot Arena, LMSYS, LiveBench 등) 기준이며, 모델 버전·프롬프트·측정 방법에 따라 달라질 수 있습니다. (2026년 초 기준)
+
+---
+
+### 종합 벤치마크
+
+주요 평가 지표:
+
+- **MMLU** — 57개 분야 지식 측정 (0~100, 높을수록 좋음)
+- **GPQA Diamond** — 과학 전문가 수준 추론 (0~100)
+- **Chatbot Arena ELO** — 인간 선호도 평가 (높을수록 선호)
+- **LiveBench** — 최신 문제 기반 종합 능력 (0~100)
+
+| 모델             | MMLU | GPQA Diamond | Chatbot Arena ELO | LiveBench | 비고                            |
+| ---------------- | ---- | ------------ | ----------------- | --------- | ------------------------------- |
+| OpenAI o3        | 96.7 | 87.7         | ~1400             | 79.3      | 추론 최강, 느린 응답 감수 필요  |
+| claude-opus-4    | 95.0 | 82.1         | ~1380             | 75.8      | 장문 분석·지시 준수 최상        |
+| Gemini 2.5 Pro   | 95.2 | 84.0         | ~1420             | 78.5      | 멀티모달·초장문 컨텍스트 최강   |
+| gpt-4o           | 88.7 | 53.6         | ~1320             | 58.1      | 균형잡힌 범용 모델              |
+| claude-sonnet-4  | 90.2 | 70.3         | ~1350             | 66.4      | 성능·속도·비용 최적 균형        |
+| DeepSeek V3      | 88.5 | 59.1         | ~1310             | 60.2      | 비용 대비 gpt-4o급 성능         |
+| DeepSeek R1      | 90.8 | 71.5         | ~1340             | 67.9      | 오픈소스 추론 모델 최강         |
+| Qwen-2.5-72B     | 86.1 | 49.0         | ~1240             | 52.3      | 다국어(한·중·영) 특화           |
+| Llama-3.3-70B    | 86.0 | 50.7         | ~1250             | 53.1      | 오픈소스 대비 우수한 범용 성능  |
+| Gemini 2.0 Flash | 83.5 | 51.5         | ~1220             | 49.7      | 고속·저비용 실용 모델           |
+| gpt-4o-mini      | 82.0 | 40.2         | ~1190             | 43.5      | 저비용 경량, 단순 작업 최적     |
+| mistral-large-2  | 84.0 | 49.0         | ~1230             | 50.1      | 유럽 GDPR 준수, 범용 균형       |
+| EXAONE-3.5-32B   | 78.5 | 38.0         | —                 | —         | 한국어 특화, 오픈소스 최대 규모 |
+
+---
+
+### 한국어 벤치마크
+
+주요 평가 지표:
+
+- **KoMT-Bench** — 한국어 멀티턴 대화 능력 (0~10)
+- **KMMLU** — 한국어 지식 평가 MMLU (0~100)
+- **Ko-IFEval** — 한국어 지시사항 따르기 (0~100)
+
+| 모델                       | KoMT-Bench | KMMLU | Ko-IFEval | 비고                                   |
+| -------------------------- | ---------- | ----- | --------- | -------------------------------------- |
+| claude-sonnet-4            | 9.1        | 78.2  | 88.5      | 자연스러운 한국어 표현, 지시 준수 최고 |
+| gpt-4o                     | 8.9        | 77.6  | 87.3      | 균형잡힌 한국어 성능                   |
+| Gemini 2.5 Pro             | 9.0        | 79.1  | 86.9      | 한국어 장문 처리 우수                  |
+| HyperCLOVA X               | 9.2        | 82.0  | 90.1      | 한국 문화·비즈니스 맥락 이해 최상      |
+| EXAONE-3.5-32B             | 8.7        | 80.5  | 85.3      | 오픈소스 한국어 모델 최강              |
+| Kanana-1.5-8B              | 8.3        | 76.1  | 82.0      | 경량 한국어 특화, 로컬 실행 가능       |
+| Qwen-2.5-72B               | 8.5        | 73.4  | 80.7      | 한·중·영 다국어 우수                   |
+| DeepSeek V3                | 8.2        | 71.8  | 79.5      | 저비용 대비 한국어 준수                |
+| Llama-3-Korean-Bllossom-8B | 7.8        | 68.5  | 74.2      | 로컬 한국어 경량 파인튜닝 모델         |
+| SOLAR-10.7B                | 7.9        | 69.2  | 75.8      | 상용 가능 한국어 특화 오픈소스         |
+
+> HyperCLOVA X는 별도 API 계약 필요. EXAONE·Kanana·SOLAR는 로컬(Ollama/vLLM) 또는 API 제공 서비스 경유 연동.
+
+---
+
+### 코드 벤치마크
+
+주요 평가 지표:
+
+- **HumanEval** — Python 함수 생성 정확도 (pass@1, %)
+- **SWE-bench Verified** — GitHub 실제 버그 수정 능력 (%)
+- **MBPP** — 기본 Python 프로그래밍 문제 (pass@1, %)
+
+| 모델               | HumanEval | SWE-bench | MBPP | 비고                                 |
+| ------------------ | --------- | --------- | ---- | ------------------------------------ |
+| OpenAI o3          | 99.2      | 71.7      | 95.8 | 코드 추론·버그 수정 최강             |
+| claude-sonnet-4    | 96.4      | 70.3      | 93.5 | 코드 생성·리뷰, 엣지케이스 처리 우수 |
+| gpt-4o             | 90.2      | 49.2      | 87.8 | 범용 코드 생성 안정적                |
+| DeepSeek V3        | 91.6      | 42.0      | 89.3 | 비용 대비 코드 성능 탁월             |
+| DeepSeek R1        | 92.6      | 50.0      | 90.2 | 추론 기반 코드 분석 강점             |
+| Qwen-2.5-Coder-32B | 92.7      | 43.5      | 90.1 | 코드 특화 파인튜닝, GPT-4o 수준      |
+| claude-haiku-3.5   | 87.5      | 40.6      | 84.5 | 빠르고 저렴한 코드 정리·포맷팅       |
+| Llama-3.3-70B      | 85.1      | 37.0      | 82.3 | 오픈소스 코드 모델 중 상위권         |
+| gpt-4o-mini        | 87.2      | 35.5      | 84.0 | 저비용 SQL·단순 스크립트 생성        |
+
+---
+
+### 추론 벤치마크
+
+주요 평가 지표:
+
+- **MATH-500** — 수학 올림피아드 수준 문제 (%)
+- **AIME 2024** — 미국 수학경시대회 (문제 수/30)
+- **ARC-Challenge** — 과학 추론 문제 (%)
+
+| 모델           | MATH-500 | AIME 2024 | ARC-Challenge | 비고                                 |
+| -------------- | -------- | --------- | ------------- | ------------------------------------ |
+| OpenAI o3      | 99.2     | 28.3/30   | 98.0          | 수학·과학 추론 절대 1위              |
+| OpenAI o3-mini | 97.0     | 26.7/30   | 96.4          | o3 대비 빠르고 저렴한 추론           |
+| DeepSeek R1    | 97.3     | 26.0/30   | 96.3          | 오픈소스 추론 모델 o3-mini 수준      |
+| Gemini 2.5 Pro | 97.0     | 27.0/30   | 97.1          | 추론+멀티모달 결합 강점              |
+| claude-opus-4  | 95.0     | 23.4/30   | 96.7          | 복잡한 다단계 추론 우수              |
+| gpt-4o         | 76.6     | 13.4/30   | 96.3          | 범용 추론, 수학은 o-시리즈 대비 약세 |
+| DeepSeek V3    | 90.2     | 20.0/30   | 95.5          | 비추론 모델 중 수학 성능 최상        |
+| Llama-3.3-70B  | 77.0     | 11.0/30   | 94.8          | 오픈소스 범용 추론 상위권            |
+
+---
+
+### 속도·비용 효율
+
+> **TPS**: 초당 출력 토큰 수 (높을수록 빠름, 클라우드 환경 측정값)
+
+| 모델                  | TPS (평균) | 입력 비용<br>($/1M tok) | 출력 비용<br>($/1M tok) | 비용 대비 성능 | 비고                                      |
+| --------------------- | ---------- | ----------------------- | ----------------------- | -------------- | ----------------------------------------- |
+| Groq llama-3.3-70b    | ~1,400     | $0.59                   | $0.79                   | ★★★★★          | 클라우드 최고속 (LPU), 저비용             |
+| Gemini 2.0 Flash      | ~500       | $0.10                   | $0.40                   | ★★★★★          | 저비용·고속 균형, 배치 처리 최적          |
+| gpt-4o-mini           | ~230       | $0.15                   | $0.60                   | ★★★★☆          | OpenAI 경량 모델, 범용 저비용             |
+| DeepSeek V3           | ~200       | $0.27                   | $1.10                   | ★★★★★          | GPT-4o급 성능을 1/10 비용으로             |
+| claude-haiku-3.5      | ~450       | $0.80                   | $4.00                   | ★★★★☆          | 빠른 Anthropic 경량, 요약·분류에 최적     |
+| Gemini 2.0 Flash Lite | ~600       | $0.075                  | $0.30                   | ★★★★★          | 최저 비용, 단순 작업 대량 처리            |
+| Mistral Small 3       | ~350       | $0.10                   | $0.30                   | ★★★★★          | Apache 2.0, 저비용 유럽 서버              |
+| claude-sonnet-4       | ~150       | $3.00                   | $15.00                  | ★★★☆☆          | 고성능 균형, 프리미엄 비용 감수           |
+| gpt-4o                | ~120       | $2.50                   | $10.00                  | ★★★☆☆          | 범용 플래그십, 중간 비용                  |
+| OpenAI o3             | ~30        | $10.00                  | $40.00                  | ★★☆☆☆          | 최고 성능, 최고 비용·느린 응답            |
+| DeepSeek R1           | ~80        | $0.55                   | $2.19                   | ★★★★★          | 추론 모델 중 압도적 비용 효율             |
+| Ollama (로컬 GPU)     | ~50~300    | $0 (전기비)             | $0 (전기비)             | ★★★★★          | 초기 GPU 비용 제외 시 장기 운영 최저 비용 |
+
+> **TPS는 하드웨어·네트워크·프롬프트 길이에 따라 크게 달라집니다.** 위 수치는 표준 프롬프트 기준 참고값입니다.
+
+---
+
+## 모델 비교
+
+> **연동 가능 여부 범례**
+>
+> - ✅ **지원** — 해당 프로바이더 driver로 `model` 필드에 그대로 지정하면 즉시 사용 가능
+> - ⚠️ **조건부** — API 접근 신청·웨이팅리스트·별도 계약 필요, 또는 특정 플랜 이상에서만 사용 가능
+> - 🔶 **로컬만** — 자체 호스팅(Ollama, vLLM 등)을 통해서만 사용 가능
+> - ❌ **불가** — API 미제공 또는 현재 지원하지 않는 프로바이더
+
+---
+
+### OpenAI 모델
+
+| 모델            | 유형          | 컨텍스트 | 입력 비용<br>($/1M tok) | 출력 비용<br>($/1M tok) | 한글 지원 | 특징                              |  연동 가능  |
+| --------------- | ------------- | -------- | ----------------------- | ----------------------- | --------- | --------------------------------- | :---------: |
+| gpt-4o          | 멀티모달      | 128K     | $2.50                   | $10.00                  | ★★★★★     | 이미지 입력, 균형잡힌 성능        |     ✅      |
+| gpt-4o-mini     | 경량          | 128K     | $0.15                   | $0.60                   | ★★★★☆     | 저비용 고속, 일상적 작업에 최적   |     ✅      |
+| gpt-4.1         | 최신 플래그십 | 1M       | $2.00                   | $8.00                   | ★★★★★     | 초장문 컨텍스트, 코드·지시 강화   |     ✅      |
+| gpt-4.1-mini    | 경량          | 1M       | $0.40                   | $1.60                   | ★★★★☆     | gpt-4.1 경량판, 빠른 긴 문서 처리 |     ✅      |
+| o3              | 추론          | 200K     | $10.00                  | $40.00                  | ★★★★★     | 복잡한 수학·과학·코드 추론 최강   |     ✅      |
+| o3-mini         | 추론 경량     | 200K     | $1.10                   | $4.40                   | ★★★★☆     | o3 대비 빠른 추론, 비용 절감      |     ✅      |
+| o4-mini         | 추론 경량     | 200K     | $1.10                   | $4.40                   | ★★★★☆     | 멀티모달 추론, 이미지 분석 가능   |     ✅      |
+| gpt-4o-realtime | 실시간 음성   | 128K     | $5.00 (오디오)          | $20.00 (오디오)         | ★★★★☆     | 저지연 음성 입출력 (WebSocket)    | ⚠️ 별도 API |
+
+> 비용은 2026년 초 기준 공개된 가격이며 변경될 수 있습니다.
+
+---
+
+### Anthropic 모델
+
+| 모델                     | 유형        | 컨텍스트 | 입력 비용<br>($/1M tok) | 출력 비용<br>($/1M tok) | 한글 지원 | 특징                                    | 연동 가능 |
+| ------------------------ | ----------- | -------- | ----------------------- | ----------------------- | --------- | --------------------------------------- | :-------: |
+| claude-opus-4            | 플래그십    | 200K     | $15.00                  | $75.00                  | ★★★★★     | 최고 성능, 복잡한 추론·장문 분석        |    ✅     |
+| claude-sonnet-4          | 균형        | 200K     | $3.00                   | $15.00                  | ★★★★★     | 성능·속도·비용 최적 균형, 실무 주력     |    ✅     |
+| claude-haiku-3.5         | 경량 고속   | 200K     | $0.80                   | $4.00                   | ★★★★☆     | 가장 빠름, 단순 분류·요약에 최적        |    ✅     |
+| claude-opus-4 (extended) | 장시간 추론 | 200K     | $15.00+                 | $75.00+                 | ★★★★★     | 확장 사고(extended thinking), 깊은 분석 |  ⚠️ 베타  |
+
+---
+
+### Google Gemini 모델
+
+| 모델                  | 유형     | 컨텍스트 | 입력 비용<br>($/1M tok) | 출력 비용<br>($/1M tok) | 한글 지원 | 특징                                 | 연동 가능 |
+| --------------------- | -------- | -------- | ----------------------- | ----------------------- | --------- | ------------------------------------ | :-------: |
+| gemini-2.5-pro        | 플래그십 | 1M       | $1.25 (≤200K)           | $10.00                  | ★★★★★     | 최장 컨텍스트, 멀티모달, 딥 추론     |    ✅     |
+| gemini-2.0-flash      | 고속     | 1M       | $0.10                   | $0.40                   | ★★★★★     | 초고속·저비용, 실시간 처리 최적      |    ✅     |
+| gemini-2.0-flash-lite | 경량     | 1M       | $0.075                  | $0.30                   | ★★★★☆     | 최저 비용, 간단한 작업용             |    ✅     |
+| gemini-2.5-flash      | 균형     | 1M       | $0.15                   | $0.60                   | ★★★★★     | Pro 대비 고속·저비용, 추론 기능 포함 |    ✅     |
+| gemini-1.5-pro        | 구세대   | 2M       | $1.25 (≤128K)           | $5.00                   | ★★★★★     | 2M 컨텍스트, 레거시 호환용           |    ✅     |
+
+---
+
+### Meta Llama 모델
+
+| 모델                    | 파라미터 | 컨텍스트 | 한글 지원 | 특징                         | 연동 방법                    | 연동 가능 |
+| ----------------------- | -------- | -------- | --------- | ---------------------------- | ---------------------------- | :-------: |
+| Llama-3.3-70B-Instruct  | 70B      | 128K     | ★★★☆☆     | 오픈소스 최고 성능 중 하나   | Groq, Together, Ollama, vLLM |    ✅     |
+| Llama-3.1-405B-Instruct | 405B     | 128K     | ★★★☆☆     | Meta 최대 규모, GPT-4급 성능 | Together AI, 자체 GPU        |    ✅     |
+| Llama-3.2-11B-Vision    | 11B      | 128K     | ★★★☆☆     | 멀티모달(이미지 입력) 지원   | Together, Groq, Ollama       |    ✅     |
+| Llama-3.2-3B-Instruct   | 3B       | 128K     | ★★☆☆☆     | 엣지/로컬 경량 추론          | Ollama, llama.cpp            |    🔶     |
+| Llama-3.1-8B-Instruct   | 8B       | 128K     | ★★☆☆☆     | 로컬 실행 가능한 균형 모델   | Groq, Ollama, vLLM           |    ✅     |
+
+---
+
+### 기타 클라우드 모델
+
+| 모델                   | 제공사     | 파라미터 | 컨텍스트 | 입력 비용<br>($/1M tok) | 한글 지원 | 특징                                    |        연동 가능         |
+| ---------------------- | ---------- | -------- | -------- | ----------------------- | --------- | --------------------------------------- | :----------------------: |
+| deepseek-chat (V3)     | DeepSeek   | 685B MoE | 64K      | $0.27                   | ★★★★☆     | GPT-4급 성능, 압도적 저비용             |            ✅            |
+| deepseek-reasoner (R1) | DeepSeek   | 685B MoE | 64K      | $0.55                   | ★★★★☆     | o1 수준 추론, 수학·코드 특화            |            ✅            |
+| mistral-large-2        | Mistral AI | ~123B    | 128K     | $2.00                   | ★★★★☆     | 유럽 GDPR 완전 준수, 함수 호출 강화     |            ✅            |
+| mistral-small-3        | Mistral AI | ~22B     | 128K     | $0.10                   | ★★★☆☆     | 저비용 고속, Apache 2.0 오픈소스        |            ✅            |
+| Qwen-2.5-72B-Instruct  | Alibaba    | 72B      | 128K     | $0.40                   | ★★★★★     | 중국어·한국어 최강, 수학·코드 특화      |            ✅            |
+| Qwen-2.5-Coder-32B     | Alibaba    | 32B      | 128K     | $0.20                   | ★★★★☆     | 코드 특화, GPT-4o 대비 코딩 성능 우위   |            ✅            |
+| Command R+             | Cohere     | ~104B    | 128K     | $2.50                   | ★★★☆☆     | RAG·검색 증강 특화, 기업용 엔터프라이즈 | ⚠️ driver 직접 구현 필요 |
+| sonar-pro              | Perplexity | 비공개   | 127K     | $3.00 + 검색비          | ★★★★☆     | 실시간 웹 검색 자동 통합                |            ✅            |
+| DBRX-Instruct          | Databricks | 132B MoE | 32K      | $0.60                   | ★★☆☆☆     | 엔터프라이즈 데이터·파인튜닝 특화       |            ✅            |
+| Mixtral-8x22B-Instruct | Mistral AI | 141B MoE | 64K      | $0.90                   | ★★★☆☆     | 고품질 MoE, 다국어 효율적               |            ✅            |
+
+---
+
+### 한국어 특화 모델
+
+| 모델                       | 제공사         | 파라미터 | 컨텍스트 | 한글 지원 | 특징                                    | 연동 방법                    |   연동 가능    |
+| -------------------------- | -------------- | -------- | -------- | --------- | --------------------------------------- | ---------------------------- | :------------: |
+| EXAONE-3.5-7.8B-Instruct   | LG AI Research | 7.8B     | 32K      | ★★★★★     | 한국어 최강 오픈소스, Apache 2.0        | Ollama, vLLM, llama.cpp      |       🔶       |
+| EXAONE-3.5-32B-Instruct    | LG AI Research | 32B      | 32K      | ★★★★★     | 대형 한국어 모델, GPT-4급 한글 품질     | vLLM, Together AI (일부)     |       🔶       |
+| HyperCLOVA X               | NAVER          | 비공개   | 비공개   | ★★★★★     | 한국 문화·법률·비즈니스 최적화          | CLOVA Studio API (별도 계약) | ⚠️ 별도 driver |
+| SOLAR-10.7B-Instruct       | Upstage        | 11B      | 4K       | ★★★★☆     | 한국어 특화 파인튜닝, 상용 가능         | Together AI, Ollama          |       ✅       |
+| Qwen-2.5-7B-Instruct       | Alibaba        | 7B       | 128K     | ★★★★★     | 한국어 포함 다국어 우수, 로컬 실행 용이 | Ollama, vLLM                 |       🔶       |
+| Llama-3-Korean-Bllossom-8B | Bllossom       | 8B       | 8K       | ★★★★☆     | Llama-3 한국어 파인튜닝, 무료 오픈소스  | Ollama, llama.cpp            |       🔶       |
+| Ko-Gemma-2-9B              | Community      | 9B       | 8K       | ★★★★☆     | Gemma-2 한국어 파인튜닝                 | Ollama, vLLM                 |       🔶       |
+| Kanana-1.5-8B-Instruct     | Kakao          | 8B       | 32K      | ★★★★★     | 카카오 한국어 특화, Apache 2.0 오픈소스 | Ollama, vLLM                 |       🔶       |
+
+> **로컬 모델 연동 방법**: 🔶 표시 모델은 Ollama(`ollama pull <모델명>`) 또는 vLLM으로 서빙 후 해당 driver로 연결합니다.  
+> **별도 driver 필요** 모델은 현재 플러그인에서 직접 지원하지 않으며, OpenAI 호환 API를 제공하는 경우 `openai` driver + `base_url` 지정으로 우회 연동이 가능합니다.
+
+---
+
+## API 레퍼런스
+
+라우트별 파라미터 표, 요청/응답 예제, 상태코드는 [LLM Routes](../routes/llm-routes.md) 문서를 참고하세요.
+
+---
+
+## 운영 팁
+
+- Ollama는 로컬/사내 서버에서 **무료**로 사용 가능 — 보안 민감 데이터 처리에 적합
+- `cache.enabled: true`로 동일 요청에 대한 비용 절감 가능
+- `json_mode: true`는 OpenAI/Anthropic 모두 지원하나 Ollama는 모델 의존적
+- 스트리밍 응답 시 클라이언트는 `EventSource` 또는 `fetch + ReadableStream` 사용
+
+---
+
+## 관련 문서
+
+- [LLM Routes](../routes/llm-routes.md)
+- [설정 예제](../../src/app/plugins/llm/config.example.json)
+- [프롬프트 템플릿](../../templates/llm/prompts/)
+- [Entity Server LLM 가이드](../../../docs/plugins/llm-guide.md)