DeepSeek v4 API 연동 가이드: OpenAI SDK 그대로 쓰면서 비용 줄이는 법 (api-docs.deepseek.com)

한줄 요약

OpenAI SDK를 그대로 두고 base_url과 api_key만 바꿔서 DeepSeek v4를 쓸 수 있다.

---

DeepSeek v4 API는 OpenAI 및 Anthropic API 포맷과 호환되는 LLM 서비스로, 기존 OpenAI 기반 코드를 최소한의 수정으로 전환할 수 있다는 점이 가장 큰 실무적 이점이다.

새로운 LLM을 도입할 때마다 SDK 교체, 프롬프트 포맷 재설계, 응답 파싱 로직 수정까지 따라오는 번거로움을 겪어봤다면 이 호환성이 얼마나 의미 있는지 바로 체감할 수 있다.

어떤 상황에서 필요한가?

OpenAI API 비용이 부담되어 대안을 탐색 중인 팀, 혹은 멀티 LLM 전략으로 특정 벤더 의존도를 낮추려는 팀에 가장 적합하다.

현재 OpenAI SDK 또는 Anthropic SDK를 사용 중이라면 전환 비용이 거의 없다. 프로덕션 코드에 손을 거의 대지 않아도 된다는 뜻이다. 특히 추론(reasoning) 기능을 활용 중이라면 deepseek-v4-pro가 thinking 모드를 지원하므로 기존 워크플로우를 그대로 가져올 수 있다.

다만 이미 OpenAI 전용 기능(예: Assistants API, Files API, Fine-tuning 등)에 깊게 의존하고 있다면 호환되지 않는 영역이 있으므로 사전에 범위를 명확히 정의해야 한다.

핵심 구현 방법

설정 변경은 두 가지뿐이다. base_url을 https://api.deepseek.com으로, api_key를 DeepSeek 플랫폼에서 발급받은 키로 교체하면 된다. Anthropic SDK를 쓴다면 base_url은 https://api.deepseek.com/anthropic을 사용한다.

현재 사용 가능한 모델은 네 가지다.

모델명	상태
deepseek-v4-flash	현재 권장 (기본)
deepseek-v4-pro	현재 권장 (고성능)
deepseek-chat	2026/07/24 deprecated 예정
deepseek-reasoner	2026/07/24 deprecated 예정

deepseek-chat은 deepseek-v4-flash의 non-thinking 모드에, deepseek-reasoner는 deepseek-v4-flash의 thinking 모드에 각각 대응된다. 즉, 지금 당장 마이그레이션하지 않아도 동작은 하지만 2026년 7월 24일 이전에 모델명을 교체해두는 것이 안전하다.

thinking 모드와 추론 강도를 직접 제어하고 싶다면 아래처럼 파라미터를 명시한다.

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "thinking": {"type": "enabled"},
    "reasoning_effort": "high",
    "stream": false
  }'

thinking과 reasoning_effort 파라미터는 OpenAI 표준에는 없는 DeepSeek 고유 파라미터다. 이 부분은 OpenAI SDK로 호출할 때 extra body 옵션을 통해 전달하거나, raw HTTP 요청으로 처리해야 한다. Python SDK 기준으로는 extra_body 인자를 활용하면 된다.

스트리밍이 필요한 경우 stream 파라미터를 true로 바꾸면 Server-Sent Events 형식으로 응답이 내려온다. OpenAI SDK의 스트리밍 처리 로직을 그대로 재활용할 수 있다.

실전에서 주의할 점

모델 선택 기준을 먼저 정해라. deepseek-v4-flash는 빠른 응답이 필요한 인터랙티브 용도에, deepseek-v4-pro는 복잡한 추론이 필요한 배치 작업이나 분석 파이프라인에 더 적합해 보인다. 모든 요청에 pro 모델을 쓰는 것은 낭비일 수 있다.

deprecated 모델 알림을 캘린더에 등록해라. deepseek-chat과 deepseek-reasoner는 2026년 7월 24일에 deprecated된다. 프로덕션에서 이 모델명을 하드코딩해뒀다면 그날 이후 장애로 이어질 수 있다. 지금 바로 환경 변수나 설정 파일에서 모델명을 새 값으로 교체해두는 편이 낫다.

API 키 관리는 동일한 원칙으로. OpenAI API 키와 마찬가지로 환경 변수로 관리하고 코드에 직접 삽입하지 않는다. 여러 팀원이 사용하는 경우 키 로테이션 정책도 미리 설계해야 한다.

응답 포맷 차이를 확인하라. 대부분의 응답 구조는 OpenAI와 동일하지만, thinking 모드를 활성화했을 때 reasoning 관련 필드가 추가로 내려올 수 있다. 응답 파싱 코드에서 예상치 못한 필드로 인한 오류가 발생하지 않도록 방어 코드를 넣어두는 것이 좋다.