DeepSeek-V4-Flash, 이제 Responses API 및 Codex 지원: 개발자 핵심 가이드

DeepSeek의 7월 31일 V4-Flash 출시 발표에는 중요한 구현 세부 사항이 포함되어 있습니다. 공식 V4-Flash가 Responses API 형식을 기본 지원하며 Codex에 맞춰져 있다는 점입니다. 즉, OpenAI의 에이전트용 API 형식을 DeepSeek 엔드포인트에서 직접 사용할 수 있습니다.

지금 Apidog 사용해 보기

DeepSeek의 변경 로그도 목적을 명확히 설명합니다. Codex 요구 사항을 충족하기 위해 Responses API 형식을 지원한다는 것입니다. 이 글에서는 실제 호환 범위, 무시되는 옵션, Codex 연결 방법, 그리고 구현 시 확인할 점을 정리합니다. 기본 API 호출부터 확인하려면 V4-Flash 공개 베타 가이드를 먼저 참고하세요.

여기서 Responses API가 중요한 이유

OpenAI는 Chat Completions의 후속 인터페이스로 Responses API를 도입했습니다. 에이전트 워크로드를 위해 설계된 단일 API로, 추론 항목, 내장 도구, 의미론적 스트리밍 이벤트를 포함합니다.

OpenAI Responses API 사용 방법에서 형식을 자세히 다뤘지만, 핵심은 간단합니다. Codex를 포함한 OpenAI 에이전트 스택이 기본적으로 사용하는 형식이라는 점입니다.

기존에는 Responses API 클라이언트에서 OpenAI 이외의 모델을 사용하려면 번역 프록시가 필요했습니다. DeepSeek은 이를 서버 측에서 구현해 https://api.deepseek.com에서 직접 제공합니다.

기존 OpenAI SDK도 그대로 사용할 수 있습니다.

# pip3 install openai
from openai import OpenAI

client = OpenAI(
    api_key="<your DeepSeek API key>",
    base_url="https://api.deepseek.com"
)

response = client.responses.create(
    model="deepseek-v4-flash",
    instructions="You are a helpful assistant.",
    input="Hi, how are you?",
)

print(response.output_text)

현재 Responses API는 deepseek-v4-flash에서만 동작합니다. DeepSeek은 deepseek-v4-pro 지원이 2026년 8월 초에 제공될 예정이라고 밝혔습니다.

호환성은 얼마나 완벽한가요?

DeepSeek은 Responses API 호환성 매트릭스를 공개했습니다. 단순히 “OpenAI 호환”이라고 표기하는 대신, 지원·무시·미지원 항목을 구분한다는 점이 중요합니다.

지원 및 동작하는 기능

다음 옵션은 구현되어 있습니다.

• input, instructions: 문자열 또는 항목 목록
• stream: 전체 의미론적 이벤트 시퀀스 지원
• temperature, top_p, max_output_tokens, top_logprobs
• tools: function, web_search
  • 웹 검색은 서버 측에서 실행
• tool_choice: 특정 함수 강제 호출 포함
• reasoning.effort: 추론 깊이 제어

예를 들어 함수 도구를 포함한 요청은 다음과 같이 작성할 수 있습니다.

response = client.responses.create(
    model="deepseek-v4-flash",
    input="서울의 현재 날씨를 확인해줘.",
    tools=[
        {
            "type": "function",
            "name": "get_weather",
            "description": "도시의 현재 날씨를 반환합니다.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"}
                },
                "required": ["city"]
            }
        }
    ],
    tool_choice="auto"
)

허용되지만 효과가 없는 기능

다음 필드는 요청에 포함해도 오류는 발생하지 않지만, 현재 동작에는 영향을 주지 않습니다.

• reasoning.summary: 허용되지만 요약을 생성하지 않음
• text.verbosity: 허용되지만 출력에 영향 없음
• parallel_tool_calls: 병렬 도구 호출이 항상 활성화되어 있으므로 무시됨

기존 Responses API 클라이언트를 쉽게 연결할 수 있다는 장점이 있지만, 특정 옵션의 동작에 의존하는 코드라면 테스트가 필요합니다.

설계상 지원되지 않는 기능

DeepSeek의 Responses API 구현은 상태 비저장 방식입니다. 따라서 다음 기능은 지원하지 않습니다.

• previous_response_id
• conversation
• store
• background
• metadata
• include
• service_tier
• 프롬프트 캐싱 키

모든 응답은 store: false로 반환됩니다. 멀티턴 대화가 필요하다면 애플리케이션에서 기록을 관리하고, 매 요청마다 전체 기록을 입력 항목 목록으로 전송해야 합니다.

response = client.responses.create(
    model="deepseek-v4-flash",
    input=[
        {
            "role": "user",
            "content": "Python으로 CSV 파일을 읽는 방법을 알려줘."
        },
        {
            "role": "assistant",
            "content": "pandas 또는 csv 모듈을 사용할 수 있습니다."
        },
        {
            "role": "user",
            "content": "pandas 예제로 보여줘."
        }
    ]
)

또한 1M 토큰 컨텍스트 창을 넘는 요청은 자동으로 잘리지 않습니다. 대신 HTTP 400 오류를 반환하므로, 대규모 컨텍스트를 전송하는 서비스라면 요청 전 토큰 예산을 관리해야 합니다.

스트리밍 구현 시 주의할 점

스트리밍은 response.created에서 시작해 다음 이벤트 중 하나로 종료됩니다.

• response.completed
• response.incomplete
• response.failed

추론 텍스트 델타인 response.reasoning_text.delta는 일반 출력 텍스트와 별도 이벤트로 도착합니다.

중요한 차이점은 data: [DONE] 종료자가 없다는 점입니다. 기존 SSE 핸들러가 [DONE]만 기다리도록 구현되어 있다면 스트림이 끝나지 않는 것처럼 보일 수 있습니다.

// 이벤트 이름을 기준으로 종료 상태를 처리하세요.
if (
  event.type === "response.completed" ||
  event.type === "response.incomplete" ||
  event.type === "response.failed"
) {
  closeStream();
}

SSE로 API 응답 스트리밍하기 가이드에서 이런 공급자별 이벤트 차이를 처리하는 방어적 파싱 패턴을 확인할 수 있습니다.

DeepSeek-V4-Flash로 Codex 설정하기

Codex는 Responses API를 사용해 모델과 통신합니다. DeepSeek의 Codex 통합 가이드는 CLI, ChatGPT 데스크톱 앱, VS Code 확장에 공통으로 적용되는 설정 방식을 제공합니다.

1. 원클릭 설정 스크립트 실행

먼저 Codex CLI 또는 ChatGPT 데스크톱 앱을 설치하고 한 번 이상 실행합니다.

macOS 또는 Linux에서는 다음 명령을 사용합니다.

bash <(curl -fsSL https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.sh)

Windows PowerShell에서는 다음 명령을 실행합니다.

irm https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1 | iex

스크립트는 첫 실행 시 DeepSeek API 키를 요청하고 다음 작업을 수행합니다.

1. 기존 ~/.codex/config.toml을 ~/.codex/backup-deepseek/에 백업합니다.
2. 모델 카탈로그를 ~/.codex/models.json에 작성합니다.
3. 기존 MCP 서버와 프로젝트 신뢰 설정을 유지한 채 [model_providers.deepseek] 섹션을 추가합니다.
4. 파일을 쓰기 전에 구성 문법을 검증합니다.

스크립트를 다시 실행하면 모델을 전환하거나 원래 설정을 복원할 수 있습니다.

curl 결과를 셸에 직접 파이프하는 명령은 실행 전 내용을 검토하는 것이 좋습니다. 백업과 검증이 포함되어 있어도 Codex 구성 파일을 수정하는 외부 스크립트입니다.

2. 모델 카탈로그 확인

스크립트가 만드는 models.json에는 Codex에서의 V4-Flash 설정이 포함됩니다.

• 컨텍스트 창: 1,048,576 토큰
• 추론 수준: low, high, max
• 기본 추론 수준: high
• 병렬 도구 호출 지원
• Codex 클라이언트 0.144.0 이상 필요

현재 실제로 사용할 수 있는 모델은 deepseek-v4-flash입니다. 카탈로그에는 향후 지원을 위해 deepseek-v4-pro도 포함되어 있습니다.

3. 저장소에 적용하기 전 최소 검증 수행

Codex에 바로 실제 저장소를 맡기기 전에 작은 프로젝트에서 다음을 확인하세요.

codex --version

• Codex 버전이 0.144.0 이상인지 확인합니다.
• DeepSeek 모델 제공업체가 선택되었는지 확인합니다.
• 읽기 전용 작업부터 실행합니다.
• 도구 호출, 파일 수정, 명령 실행 권한을 단계적으로 허용합니다.
• 프로젝트별 비용과 토큰 사용량을 기록합니다.

에이전트 성능 수치는 어떻게 봐야 하나요?

DeepSeek은 0731 재사후 훈련이 에이전트 워크로드를 목표로 했다고 설명합니다. 발표된 수치는 다음과 같습니다.

• Terminal Bench 2.1: 82.7
• Cybergym: 76.7
• Toolathlon: 70.3 검증
• DeepSWE: 54.4

DeepSeek은 이 수치들이 V4-Pro-Preview를 능가한다고 보고합니다. 다만 독립적인 실행 결과가 충분히 나오기 전까지는 공급업체가 제공한 수치로 해석하는 것이 적절합니다. 발표에 따르면 최대 노력 설정과 DeepSeek 자체 하네스가 사용되었고, 일부 벤치마크는 내부 테스트 세트입니다.

비용 측면에서 공개된 가격은 다음과 같습니다.

• 입력 100만 토큰: $0.14, 캐시 미스 기준
• 출력 100만 토큰: $0.28
• 캐시 히트 입력 100만 토큰: $0.0028

전체 가격표는 V4-Flash 공개 베타 가이드의 가격 섹션에서 확인할 수 있습니다. Codex와 다른 에이전트 도구를 비교하려면 Claude Code vs Codex CLI 비교도 참고하세요.

에이전트를 신뢰하기 전에 엔드포인트를 확인하세요

새로운 공개 베타 엔드포인트를 실제 저장소와 연결하기 전에는 API 동작을 직접 검증하는 편이 안전합니다. Apidog에서 다음 요청을 저장해 두면 반복 테스트가 쉬워집니다.

1. 기본 Responses 요청 만들기

엔드포인트를 추가합니다.

POST https://api.deepseek.com/responses
Authorization: Bearer {{DEEPSEEK_API_KEY}}
Content-Type: application/json

요청 본문은 최소 구성으로 시작합니다.

{
  "model": "deepseek-v4-flash",
  "instructions": "You are a helpful assistant.",
  "input": "간단히 자기소개해줘."
}

응답에서 reasoning 항목 뒤에 message 항목이 오는지 확인하세요.

2. SSE 이벤트 순서 확인

stream: true를 추가합니다.

{
  "model": "deepseek-v4-flash",
  "input": "Python으로 피보나치 함수를 작성해줘.",
  "stream": true
}

SSE 이벤트를 관찰하며 다음을 확인합니다.

• response.created가 수신되는지
• response.reasoning_text.delta가 별도 이벤트로 오는지
• 출력 텍스트 델타 이벤트를 클라이언트가 처리하는지
• 종료 이벤트를 [DONE]이 아닌 response.completed 등으로 처리하는지

3. 함수 호출 형식 저장

도구 호출을 사용하는 에이전트라면 function_call 출력 형식을 별도 요청으로 저장하세요. 실제 핸들러가 기대하는 인수 구조와 일치하는지 확인해야 합니다.

V4-Pro Responses API 지원이 출시되면, 같은 요청 모음을 새 모델 이름으로 다시 실행해 결과와 이벤트 차이를 비교할 수 있습니다. Apidog을 무료로 다운로드하면 요청, 환경 변수, 테스트 시나리오를 하나의 프로젝트에서 관리할 수 있습니다.

자주 묻는 질문

Responses API와 함께 작동하는 DeepSeek 모델은 무엇인가요?

현재는 deepseek-v4-flash만 지원합니다. deepseek-v4-pro 지원은 2026년 8월 초로 예정되어 있습니다.

새로운 SDK가 필요한가요?

아니요. 공식 OpenAI SDK를 사용할 수 있습니다. base_url을 https://api.deepseek.com으로 지정한 뒤 client.responses.create를 호출하면 됩니다. 자세한 설정은 V4-Flash 공개 베타 가이드를 참고하세요.

멀티턴 상태가 OpenAI 버전처럼 작동하나요?

아니요. DeepSeek 구현은 상태 비저장입니다. previous_response_id, conversation, store는 지원되지 않습니다. 매 호출마다 전체 대화 기록을 입력 항목으로 보내야 합니다.

OpenAI 계정과 함께 Codex에서 DeepSeek을 사용할 수 있나요?

네. 설정은 DeepSeek을 모델 제공업체로 추가합니다. 스크립트 메뉴에서 모델을 전환할 수 있으며, 기존 구성은 백업되어 복원할 수 있습니다.

Anthropic API 호환성과 동일한 기능인가요?

아니요. 별도 기능입니다. DeepSeek은 https://api.deepseek.com/anthropic에 Anthropic 형식 엔드포인트도 제공하며, 이는 Claude Code 통합에 사용됩니다. Responses API 엔드포인트는 Codex 같은 OpenAI 형식 에이전트 도구를 위한 것입니다.

이 릴리스가 실제로 의미하는 것

모델 품질 경쟁이 계속되는 가운데, 에이전트 통합 레이어의 중요성도 커지고 있습니다. DeepSeek은 Codex가 사용하는 Responses API 형식을 직접 구현하고, 지원하지 않는 매개변수까지 공개했습니다.

실무에서는 호환성 표나 벤치마크만으로 결정하지 마세요. 현재 워크플로에 맞는 프롬프트, 도구 호출, 스트리밍 처리, 컨텍스트 길이, 비용을 기준으로 평가해야 합니다. Apidog에 연결해 동일한 테스트 스위트를 실행하고, 실제 저장소에서 나온 결과로 선택하세요.