DeepSeek V4 — Flash와 Pro로 나뉜 새 API 구조 정리

DeepSeek이 V4를 공개했다. 이번엔 모델 하나가 아니라 **V4-flash**와 **V4-pro** 두 가지 버전으로 분리됐다. 기존의 `deepseek-chat`과 `deepseek-reasoner`가 2026년 7월 24일부로 deprecated되고 V4로 통합된다. API 쓰고 있다면 마이그레이션 필요하다.

공식 API 문서: [platform.deepseek.com/api-docs](https://platform.deepseek.com/api-docs/)

---

## V4 모델 구조

| 모델 | 특징 | 기존 대응 |
|------|------|-----------|
| `deepseek-v4-flash` | 빠른 응답, 일반 대화·코딩 | `deepseek-chat` |
| `deepseek-v4-pro` | 추론 모드 통합, reasoning_effort 제어 | `deepseek-reasoner` |

V4-pro의 핵심은 **thinking 파라미터**다. 같은 모델 내에서 추론 모드를 켜고 끄거나, 추론 강도를 조절할 수 있다.

---

## 기본 사용법

OpenAI SDK 호환 포맷으로 그대로 쓸 수 있다.

```python
from openai import OpenAI

client = OpenAI(
    api_key="your_deepseek_api_key",
    base_url="https://api.deepseek.com"
)

# V4-flash (빠른 응답, 추론 없음)
response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "파이썬에서 비동기 처리 어떻게 해?"}
    ]
)
print(response.choices[0].message.content)
```

---

## V4-pro — 추론 모드 제어

```python
# 추론 모드 ON + 강도 설정
response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "user", "content": "이 알고리즘의 시간복잡도 분석해줘"}
    ],
    extra_body={
        "thinking": {"type": "enabled"},
        "reasoning_effort": "high"   # "low" | "medium" | "high"
    }
)

# 추론 과정 확인
thinking = response.choices[0].message.reasoning_content
answer = response.choices[0].message.content
print("추론 과정:", thinking[:200], "...")
print("최종 답변:", answer)
```

`reasoning_effort` 값에 따라 응답 속도와 품질이 달라진다.
- `low`: 빠름, 간단한 추론
- `medium`: 균형
- `high`: 느리지만 복잡한 문제에 강함

---

## 마이그레이션

기존 코드를 V4로 바꾸는 건 간단하다.

```python
# 기존 (deprecated 예정)
model = "deepseek-chat"      # → deepseek-v4-flash
model = "deepseek-reasoner"  # → deepseek-v4-pro
```

`deepseek-chat`과 `deepseek-reasoner`는 **2026년 7월 24일** deprecated. 미리 바꿔두는 걸 권장한다.

---

## Temperature 매핑

V4는 API temperature와 실제 모델 temperature 사이에 매핑이 있다.

```
T_api ∈ [0, 1]   → T_model = T_api × 0.3
T_api ∈ (1, 2]   → T_model = T_api − 0.7
```

즉 API에서 `temperature=1.0`으로 설정하면 실제 모델은 `0.3`으로 동작한다. DeepSeek 웹/앱 기본값과 동일하게 맞추려면 `temperature=1.0`을 쓰면 된다.

---

## Anthropic SDK 포맷도 지원

OpenAI 포맷 외에 Anthropic SDK 포맷도 쓸 수 있다.

```python
import anthropic

client = anthropic.Anthropic(
    api_key="your_deepseek_api_key",
    base_url="https://api.deepseek.com/anthropic"
)

message = client.messages.create(
    model="deepseek-v4-pro",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)
print(message.content[0].text)
```

Claude Code나 Anthropic SDK 기반 프로젝트에서 DeepSeek으로 스왑할 때 편리하다.

---

## 스트리밍

```python
with client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "긴 설명 써줘"}],
    stream=True
) as stream:
    for chunk in stream:
        delta = chunk.choices[0].delta
        if delta.content:
            print(delta.content, end="", flush=True)
```

---

## 파일 업로드 / 웹 검색 프롬프트 패턴

파일 내용을 컨텍스트로 넘길 때 권장 포맷:

```python
file_template = """[file name]: {file_name}
[file content begin]
{file_content}
[file content end]
{question}"""

prompt = file_template.format(
    file_name="report.txt",
    file_content=open("report.txt").read(),
    question="이 리포트 핵심 요약해줘"
)
```

---

## 요금

DeepSeek API는 여전히 저렴한 편이다. V4-flash는 캐시 히트 시 더 낮은 비용으로 처리된다. 정확한 요금은 [pricing 페이지](https://platform.deepseek.com/api-docs/pricing) 확인.

---

## 정리

- V4-flash: 빠른 일반 작업 (기존 deepseek-chat 대체)
- V4-pro: 추론이 필요한 복잡한 문제 (기존 deepseek-reasoner 대체)
- `thinking` + `reasoning_effort` 파라미터로 추론 강도 세밀하게 제어 가능
- OpenAI · Anthropic SDK 포맷 둘 다 지원
- 2026-07-24 전에 모델 이름 업데이트 필요

DeepSeek V4 — Flash와 Pro로 나뉜 새 API 구조 정리

// COMMENTS

ON THIS PAGE