7월 24일 이전 DeepSeek API 마이그레이션: 기존 모델 이름을 안전하게 교체하기

빠른 답변

DeepSeek는 2026년 7월 24일 15:59 UTC 이후에 deepseek-chat 및 deepseek-reasoner에 대한 접근을 차단할 예정입니다. 마감일 전에 두 별칭(alias)을 모두 교체하십시오:

deepseek-chat을 deepseek-v4-flash로 교체하는 것에서 멈추지 마십시오. DeepSeek 문서에 따르면 V4 모델에서는 사고 모드(thinking mode)가 기본적으로 활성화되어 있으므로, 모델 이름만 변경할 경우 지연 시간(latency), 토큰 사용량 및 응답 형태(response shape)가 변경될 수 있습니다. 모드를 명시적으로 설정한 다음, 스트리밍(streaming), JSON 출력, 도구 호출(tool calls), 그리고 멀티 턴 상태(multi-turn state)를 테스트하십시오.

deepseek-v4-pro는 선택적인 품질 업그레이드 모델이며, deepseek-reasoner의 자동 후속 모델이 아닙니다. 현재의 별칭 동작을 유지하려면 V4 Flash로 시작하고, 평가를 통해 추가 비용을 정당화할 수 있는 특정 작업에 대해서만 Pro로 전환하십시오.

대상 사용자

이 가이드는 공식 DeepSeek API를 직접 호출하거나, OpenAI 호환 SDK, Anthropic 호환 클라이언트, 프로바이더 어댑터(provider adapter) 또는 AI 코딩 도구를 통해 호출하는 개발자를 위한 것입니다. 이 가이드는 자체 호스팅된 DeepSeek 가중치(weights)가 아닌, 프로덕션 마이그레이션에 초점을 맞춥니다.

만약 귀하의 애플리케이션이 이미 여러 프로바이더를 라우팅하고 있다면, GitHub Models retirement checklist에 설명된 것과 동일한 프로바이더 어댑터 패턴을 사용하십시오. 라이브 의존성을 교체하는 것이 아니라 새로운 제품을 위해 모델을 선택하는 중이라면, GPT-5.6 migration checklist에 있는 것과 같이 작고 작업에 특화된 평가부터 시작하십시오.

7월 24일에 변경되는 사항

DeepSeek는 4월 24일에 deepseek-v4-flash와 deepseek-v4-pro를 출시했습니다. 두 공식 API 모델은 모두 OpenAI Chat Completions 및 Anthropic API 형식을 지원하며, 1M-토큰 컨텍스트 윈도우 (context window), 사고 모드 (thinking mode) 및 비사고 모드 (non-thinking mode), JSON 출력, 그리고 도구 호출 (tool calls)을 지원합니다.

전환 기간 동안, 기존 이름들은 호환성을 위한 별칭 (compatibility aliases)으로 작동합니다:

• deepseek-chat은 사고 모드가 비활성화된 V4 Flash로 라우팅됩니다.
• deepseek-reasoner는 사고 모드가 활성화된 V4 Flash로 라우팅됩니다.
• 두 별칭 모두 V4 Pro로는 라우팅되지 않습니다.
• 7월 24일 15:59 UTC 이후에는 두 별칭 모두 접근할 수 없게 됩니다.

이 마감일은 확정된 API 은퇴 (API retirement)입니다. 이는 해당 날짜에 다른 모델이 출시될 것이라는 증거가 아닙니다. 별칭을 대체할 것이라는 루머가 아니라, 문서화된 종료 계획에 맞춰 대비하십시오.

Flash 또는 Pro를 의도적으로 선택하십시오

DeepSeek의 현재 가격 페이지에는 100만 토큰당 다음과 같은 요율이 나열되어 있습니다:

두 모델 모두 현재 1M 컨텍스트와 384K 최대 출력을 제공합니다. 이러한 제한 사항은 상한선 (ceilings)이며, 기본적으로 전체 저장소나 문서를 보내야 한다는 이유가 되지는 않습니다. 귀하의 워크로드에 대해 프롬프트 크기 (prompt size), 캐시 히트율 (cache-hit rate), 첫 번째 토큰까지의 시간 (time to first token), 총 지연 시간 (total latency), 그리고 작업 성공률을 측정하십시오.

A 실용적인 라우팅 규칙은 다음과 같습니다:

이전 요청이 deepseek-chat으로 전송되었습니까?
-> V4 Flash + 사고 모드 비활성화

...

6단계로 마이그레이션하기

1. 모든 모델 이름 의존성 찾기

코드, 배포 변수 (deployment variables), 워크플로 파일 (workflow files), 대시보드, 저장된 에이전트 프로필, 그리고 프록시 설정을 검색하십시오:

rg -n 'deepseek-(chat|reasoner)|DEEPSEEK_MODEL|model.*deepseek' . \
  --glob '!node_modules/**' --glob '!dist/**'

또한 서드파티 통합 (third-party integrations)에 숨겨진 기본값도 점검하십시오. “DeepSeek”와 같은 UI 레이블은 여전히 오래된 모델 ID를 직렬화 (serialize)할 수 있습니다.

2. 모델과 모드를 하나의 어댑터 뒤로 배치하기

OpenAI Python SDK를 사용하여 기존 동작을 명시적으로 보존하십시오:

import os
from openai import OpenAI

...

기존의 reasoner 라우트(route)의 경우, type을 enabled로 설정하고 작업이 필요할 때 reasoning_effort="high" 또는 "max"를 선택하십시오. 모드(mode)를 프롬프트 곳곳에 흩뿌리지 말고 설정(configuration) 내에 유지하십시오.

3. 파라미터 동작 확인

Thinking 모드에서 DeepSeek는 temperature, top_p, presence_penalty, frequency_penalty가 영향을 미치지 않는다고 밝히고 있으나, 호환성 코드(compatibility code)에서는 에러를 받지 않을 수도 있습니다. 해당 필드들이 추론 응답(reasoning response)을 제어한다는 가정을 제거하십시오.

응답에는 reasoning_content도 포함됩니다. 만약 Thinking 턴이 도구 호출(tool call)을 수행한다면, reasoning_content를 포함한 전체 어시스턴트 메시지(assistant message)를 이후의 요청에 다시 전달하십시오. 이를 누락하면 400 에러가 발생할 수 있습니다.

4. 마이그레이션 매트릭스(migration matrix) 실행

비밀 정보가 제거된, 실제 운영 환경과 유사한 형태의 프롬프트를 사용하십시오:

단순한 문구의 유사성이 아니라 작업의 성공 여부를 비교하십시오. 모델 마이그레이션은 문체가 바뀌더라도 올바를 수 있으며, 하나의 샘플이 비슷해 보이더라도 안전하지 않을 수 있습니다.

5. 섀도우(Shadow), 카나리(Canary), 그 다음 전환(Cut over)

출력을 실제로 서비스하지는 않으면서, 민감 정보가 삭제된 작은 샘플을 명시적인 V4 라우트에 대해 재현(replay)해 보십시오. 먼저 실패 사례와 비용을 검토하십시오. 그다음 라이브 트래픽의 작은 일부를 카나리(canary) 방식으로 배포하여 에러율, p95 지연 시간, 출력 토큰, 도구 호출 완료 여부, 사용자에게 보이는 폴백(fallback) 비율을 모니터링하십시오.

마감일 훨씬 전에 명시적인 라우트를 배포하십시오. Flash와 Pro 사이, 또는 Thinking 모드들 사이의 설정 롤백(configuration rollback) 기능은 유지하되, 은퇴하는 별칭(aliases)을 실행 가능한 롤백 대상으로 취급하지 마십시오.

6. 별칭이 사라졌음을 증명하기

배포 후에는 저장소 검색을 반복하고, 배포된 환경 변수(environment values)를 검사하며, 실제 모델 ID를 확인하기 위해 텔레메트리 (telemetry)를 점검하십시오. 마이그레이션 문서에서는 이전 문자열을 허용하되, 실행 가능한 설정 (executable configuration) 내의 이전 문자열은 거부하는 CI 규칙을 추가하십시오.

일반적인 실수

• 모델 문자열만 변경하여 기존 deepseek-chat 트래픽에서 의도치 않게 사고(thinking) 기능이 활성화되는 경우.
• Flash 모델이 이미 해당 작업을 수행할 수 있는지 측정하지 않고 모든 추론기 (reasoner) 트래픽을 V4 Pro로 이동하는 경우.
• 무시된 샘플링 파라미터 (sampling parameters)가 여전히 사고 모드 (thinking-mode) 출력을 제어한다고 가정하는 경우.
• 도구 루프 (tool loop) 중에 reasoning_content를 누락하여 프로덕션 환경에서만 400 에러를 발견하는 경우.
• 단일 프롬프트만 테스트하고 스트리밍 (streaming), 구조화된 출력 (structured output), 도구 (tools), 멀티턴 상태 (multi-turn state), 그리고 에러 핸들링 (error handling)은 테스트하지 않는 경우.
• 7월 24일을 기다리거나 출시 루머를 마이그레이션 계획의 일부로 취급하는 경우.
• 애플리케이션 코드를 업데이트한 후 호스팅된 워크플로 (hosted workflow), 시크릿 매니저 (secret manager), 프록시 (proxy), 또는 제3자 에이전트 프로필에 이전 별칭 (alias)을 남겨두는 경우.

FAQ

동일한 베이스 URL (base URL)과 API 키를 계속 사용할 수 있나요?

네. DeepSeek에 따르면 OpenAI 형식의 베이스 URL은 https://api.deepseek.com으로 유지됩니다. 모델을 업데이트하고 사고 모드 (thinking mode)를 명시적으로 설정하십시오. Anthropic 형식의 엔드포인트는 https://api.deepseek.com/anthropic입니다.

V4 Pro가 deepseek-reasoner의 대체제인가요?

아니요. 문서화된 호환성 매핑 (compatibility mapping)에 따르면 deepseek-reasoner는 사고 기능이 활성화된 V4 Flash로 전달됩니다. Pro는 측정된 품질 향상이 더 높은 토큰 가격만큼의 가치가 있는 작업들을 위한 별도의 선택지입니다.

deepseek-chat의 가장 안전한 대체제는 무엇인가요?

사고 기능을 명시적으로 비활성화한 deepseek-v4-flash를 사용하십시오. V4의 사고 기능은 기본적으로 활성화되어 있으므로, 명시적인 설정을 통해 이전 별칭의 동작을 유지할 수 있습니다.

도구 호출 (tool-call) 코드를 변경해야 하나요?

그럴 가능성이 있습니다. 사고 모드에서는 도구 호출 루프가 이후의 요청에서 어시스턴트의 reasoning_content를 반환해야 합니다. 단순한 채팅 호출이 이미 통과하더라도 다단계 도구 테스트 (multi-step tool test)를 추가하십시오.

출처

출처

• DeepSeek API 변경 로그: [https://api-docs.deepseek.com/updates/]
• DeepSeek V4 Preview 출시: [https://api-docs.deepseek.com/news/news260424/]
• DeepSeek 모델 및 가격 책정: [https://api-docs.deepseek.com/quick_start/pricing/]
• DeepSeek 사고 모드 (thinking mode): [https://api-docs.deepseek.com/guides/thinking_mode/]
• DeepSeek 도구 호출 (tool calls): [https://api-docs.deepseek.com/guides/tool_calls/]
• DeepSeek Anthropic API 호환성: [https://api-docs.deepseek.com/guides/anthropic_api/]