DeepSeek API 마이그레이션: V4.1 Flash 로 이동 및 설정 가이드

애플리케이션이 여전히 deepseek-v4-flash 를 전송하고 있다면, 성공적인 요청이 원래 V4 Flash 모델을 사용한다는 의미는 더 이상 아닙니다. DeepSeek 의 현재 문서는 해당 호환성 이름을 V4.1 Flash 로 라우팅합니다. 새로운 통합은 deepseek-flash 를 명시적으로 요청해야 합니다.

이 가이드는 2026 년 9 월 23 일 기준 공식 API 마이그레이션 경로를 업데이트합니다. 스크립트, 서버 또는 에이전트 통합을 유지 관리하는 개발자를 위한 것입니다. 웹 채팅 제품 간 대화 이동은 별도의 작업이며, 채팅 기록 복사는 애플리케이션의 API 구성을 변경하지 않습니다.

현재 각 식별자의 의미 확인

공식 변경 로그 및 모델 테이블 은 현재 매핑을 확인합니다:

설정 내 식별자	현재 문서상 상태	권장 조치
`deepseek-flash`	V4.1 Flash	새로운 Flash 통합에 사용
`deepseek-v4-flash`	V4.1 Flash 용 호환성 별칭	유지 관리 중인 예제 및 설정에서 교체
`deepseek-v4-flash-vision-exp`	V4.1 Flash 용 호환성 별칭	이미지 요청을 `deepseek-flash` 로 이동
`deepseek-v4-pro`	V4 Pro 계속 사용 가능	기존 워크플로우 변경 전 평가
`deepseek-chat` / `deepseek-reasoner`	2026 년 7 월 24 일 중단 예정	지속 의존 대신 마이그레이션

이전 채팅 및 이유추론 (reasoner) 이름은 비사고 (non-thinking) 및 사고 (thinking) 동작을 선택하는 장기적인 방법으로 취급해서는 안 됩니다. 유지 관리 중인 코드에서 모델 선택 및 사고 설정을 명시적으로 만드세요. 또한 예약된 작업과 백그라운드 워커를 검사하세요: 인터랙티브 애플리케이션을 변경해도 다른 서비스에 복사 된 모델 이름은 업데이트되지 않습니다.

제공업체와 모델 분리

애플리케이션이 소비하는 엔드포인트, 요청 모델 이름, 요청 형식 및 응답 필드를 기록하세요. 서드파티 게이트웨이는 다른 별칭 또는 가격을 사용할 수 있습니다. 위의 매핑은 DeepSeek 의 공식 서비스를 설명하며, DeepSeek 모델을 제공하는 모든 서비스를 설명하는 것은 아닙니다.

예를 들어, MODEL=deepseek-v4-flash 라는 환경 변수는 이야기의 일부만 알려줍니다. 기본 URL 과 애플리케이션 메시지를 API 요청으로 변환하는 코드도 필요합니다. 어댑터는 기본 모델이 더 많이 지원하더라도 필드를 삭제하거나 더 작은 출력 제한을 부과할 수 있습니다.

편집 전 구성 파일, 배포 변수 및 프롬프트 평가 스크립트를 검색하세요. 첫 번째 마이그레이션 확인 동안 제공업체를 변경하지 말고 유지하세요. 제공업체, 프로토콜, 프롬프트 및 모델을 한 번에 변경하면 실패 결과를 진단하기 훨씬 어려워집니다.

Start using DeepSeek-V4

명시적 모드로 작은 요청 하나 만들기

다음 Python 예제는 OpenAI 호환 클라이언트를 사용하여 공식 Chat Completions 엔드포인트를 호출합니다. 테스트 환경에 openai 패키지를 설치하고 일반적인 비밀 관리 메커니즘을 통해 DEEPSEEK_API_KEY 를 제공하세요. 소스 파일, 브라우저 코드 및 요청 로그에서 키를 제외하세요.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{
        "role": "user",
        "content": "Extract the order ID from: Order A-104 is ready. Return only the ID.",
    }],
    max_tokens=128,
    extra_body={"thinking": {"type": "disabled"}},
)

print(response.choices[0].message.content)
print(response.usage)

이 작업은 명확한 예상 답변인 A-104 를 가집니다. 복잡한 프롬프트 없이 인증, 라우팅, 응답 파싱 및 사용량 보고를 확인합니다. 이는 문서 기반 예제이며, 기록된 라이브 API 테스트가 아닙니다. 예상치 못한 답변이나 오류는 전체 애플리케이션 컨텍스트를 추가하기 전에 요청을 검사해야 하는 이유입니다.

이 작은 비사고 작업에는 128 토큰 캡이 적절합니다. 추론 또는 에이전트 작업에 권장되는 예산은 아닙니다. 실제 워크로드를 복원할 때, 요청된 출력을 허용하는 예산을 선택하고 잘림 (truncation) 에 대한 completion 의 finish reason 을 확인하세요.

사고 설정은 오류 없이 동작을 변경할 수 있음

사고 모드 문서 에 따르면 사고는 기본적으로 높은 노력으로 활성화되어 있습니다. Chat Completions 에서 thinking 은 Python 클라이언트 사용 시 extra_body 를 통해 공급됩니다. 지원되는 노력 수준은 low, high, max 입니다.

사고 모드 시험을 위해 관련 인수를 다음으로 교체하세요:

reasoning_effort="high",
extra_body={"thinking": {"type": "enabled"}},

성공적인 HTTP 응답이 모든 샘플링 설정이 적용되었음을 의미한다고 가정하지 마세요. 문서에 따르면 temperature 는 호환성을 위해 받아들여질 수 있지만 사고 모드에서는 효과가 없습니다. 이전 테스트 스위트가 변형 제어를 위해 temperature 에 의존했다면, 결과를 비교하기 전에 해당 차이를 문서화하세요.

도구 호출 히스토리는 특별한 주의가 필요합니다. tools 를 포함하는 Chat Completions 요청의 경우, 가이드는 도구 호출이 없는 턴을 포함하여 이전 reasoning_content 를 다시 전달하도록 요구합니다. 어시스턴트의 최종 텍스트만 보존하는 어댑터는 따라서 이후 턴을 중단시킬 수 있습니다. 첫 번째 응답만 검증하는 대신 다중 턴 테스트에서 전체 메시지 처리를 검사하세요.

실패 사례를 중심으로 회귀 테스트 세트 구축

예상 결과를 이미 알고 있는 예제로 시작하세요. 누락된 필드가 있는 추출, 스키마에 맞아야 하는 응답, 끝 근처에 답변이 있는 긴 입력, 도구 결과 후 계속되는 도구 워크플로우를 포함하세요. 애플리케이션이 이미지를 사용하는 경우에만 이미지 사례를 추가하세요.

각 작업마다 지연 시간을 측정하기 전에 출력이 사용 가능한지 확인하세요. JSON 처럼 보이는 답변도 파싱 및 스키마 검증이 필요합니다. 코드 변경에도 관련 테스트가 필요합니다. 인용된 값은 제공된 자료에 존재해야 합니다. 출력 형식 회귀와 제공업체 오류를 구분할 수 있도록 실패 카테고리를 저장하세요.

재시도를 포함한 완료된 작업을 측정하세요. 입력, 출력 및 캐시 사용을 별도로 기록하세요. 새로운 동작이 더 긴 답변을 생성하거나 애플리케이션이 재시도하게 하면 가격 인하가 더 저렴한 작업을 보장하지는 않습니다. 비교를 위해 동일한 프롬프트와 명시적 설정을 사용하세요. 프롬프트 최적화는 이후 단계로 남겨두세요.

Pro 가용성 및 롤백은 별도의 결정 필요

9 월 10 일 발표는 Pro 요청을 Flash 로 라우팅하는 계획을 설명했습니다. 현재 변경 로그는 Pro 서비스가 9 월 14 일 이후에도 청구 방법 변경 없이 계속된다고 말합니다. 오래된 종료 계획을 읽었다고 해서 작동하는 Pro 통합을 마이그레이션하지 마세요.

Flash 의 경우, 설정을 deepseek-v4-flash 로 되돌려도 종료 된 모델이 복원되지 않습니다. 해당 식별자는 새 모델의 별칭입니다. 롤백 계획은 실제로 사용 가능한 서비스 이름을 지정해야 하며 해당 기능을 고려해야 합니다. Pro 는 이미지 요청에 대한 즉시 대체 수단이 아닙니다. 현재 공식 모델 테이블은 Pro 에 대한 비전 지원을 나열하지 않습니다.

중단할 명확한 조건과 함께 트래픽의 작은 부분에 먼저 변경 사항을 롤아웃하세요. 평가 결과 및 제공업체 설정을 릴리스 기록과 함께 유지하세요. 새 경로가 애플리케이션의 확인을 통과하면, 다음 통합 동안 이전 식별자가 반환되지 않도록 복사 된 예제 및 내부 문서를 업데이트하세요.