이 글은 deepseek-v4-pro-0813의 사용 시 참고 사항과 주의점을 다룹니다. AIHubMix에서 이 모델은 Chat Completions, Responses, Claude 호환 Messages API를 통해 사용할 수 있습니다. 함께 보세요: DeepSeek 공식 API 문서.
각 섹션의 "Verified" 결론과 샘플 응답은 2026-08-13에 AIHubMix API(Chat Completions / Responses / Messages)를 통해 실제로 호출한 결과에서 얻은 것입니다. "Verified"로 표시되지 않은 사양 항목은 DeepSeek 공식 문서에서 가져왔습니다.
1. 모델 포지셔닝과 한눈에 보는 사양
V4 Pro는 DeepSeek V4 세대의 고성능 등급입니다(경량 모델 deepseek-v4-flash이 짝을 이룹니다). 출시 계보는 2026-04-24의 DeepSeek-V4 Preview까지 거슬러 올라가며, 0813은 DeepSeek이 현재 빌드에 부여한 MODEL VERSION 라벨입니다. 원시 사양 외에도 이 모델을 차별화하는 네 가지 특징이 있습니다:
- 희소 활성화 프런티어 모델: 총 파라미터 1.6T / 활성 파라미터 49B입니다(MoE, 즉 혼합 전문가 아키텍처로, 각 추론 단계에서는 전문가 네트워크의 일부만 활성화됩니다. 총 파라미터는 지식 용량을, 활성 파라미터는 호출당 연산 비용을 결정합니다). 모델 카드에는 CSA+HCA 하이브리드 어텐션, mHC, Muon 옵티마이저가 명시되어 있습니다.
- MIT 라이선스의 오픈 웨이트:
deepseek-ai/DeepSeek-V4-Pro는 MIT 라이선스(가장 허용적인 오픈소스 라이선스 중 하나로, 상업적 이용과 비공개 소스 재배포가 모두 허용됩니다)로 HuggingFace에 공개되어 있으며 자체 호스팅할 수 있습니다. 이 규모의 모델에 MIT 라이선스를 적용하는 것은 드문 일입니다. 모델 카드의 자체 호스팅 안내는 Think Max(최고 사고 레벨)로 실행할 때 ≥384K 토큰의 컨텍스트 윈도우를 권장하기도 하는데, 이는 자체 호스팅을 위한 배포 가이드이며 호스팅된 API의 사양이 아닙니다. - 다중 프로토콜 지원은 서드파티 변환이 아닌 퍼스트파티 지원입니다: DeepSeek은 OpenAI Chat API, Anthropic 호환 엔드포인트(
/anthropic,claude-opus*를 이 모델에 매핑), 그리고 Responses API를 직접 제공합니다(DeepSeek은 해당 형식을 네이티브로 지원하며 Codex에 맞춘 조정이 포함되어 있다고 설명합니다). 또한 별도의 엔드포인트에서 베타 기능으로 FIM(fill-in-the-middle) 완성도 제공하지만, 이는 AIHubMix의 세 가지 API에 포함되지 않습니다. - 캐시 적중과 캐시 미스 가격 사이의 약 120배 격차: DeepSeek이 공개한 가격 구조는 캐시 적중 $0.003625/M 대 캐시 미스 $0.435/M(출력 $0.87/M)이며, 캐싱은 자동으로 적용되고 설정할 파라미터가 없습니다. 긴 프리픽스(시스템 프롬프트, 긴 문서)를 재사용하는 워크로드에서는 이 격차가 비용을 좌우합니다. 실제 소매 가격은 모델 페이지에 표시된 가격을 따릅니다.
| 항목 | 값 |
|---|---|
| AIHubMix의 모델 이름 | deepseek-v4-pro-0813 |
| 컨텍스트 윈도우 | 1M 토큰 (1,000,000) |
| 최대 출력 | 공식 표기는 MAX OUTPUT MAXIMUM: 384K입니다(정확한 토큰 수와 기본값은 공개되지 않음) |
| 입력 모달리티 | 텍스트만 지원합니다. Responses 호환성 페이지에는 이미지 및 파일 입력이 지원되지 않는다고 명시되어 있고, Messages 페이지에는 type="image" 블록이 Not Supported로 표시되어 있습니다. Chat Completions에서는 user 메시지의 content가 문자열만 허용하며 멀티모달 콘텐츠 파트는 받지 않습니다 |
| 사고 모드 | 하이브리드(thinking / non-thinking), 기본적으로 thinking 켜짐 |
| 사고 레벨 | reasoning_effort는 low / high / max를 받으며 기본값은 high입니다. medium과 xhigh는 호환성을 위해 high로 매핑됩니다 |
| 사용 가능한 API | Chat Completions, Responses, Messages(Claude 호환) |
Verified:max_tokens를 초과하면 조용히 잘리는 대신 유효성 검사에서 거부됩니다.max_tokens=9999999를 보내면 HTTP 400이 반환되며, 오류 본문에는 필드 이름과 상한값393216이 명시됩니다.
# max_tokens=9999999 -> HTTP 400
"...max_tokens... 393216"
❗ 이미지는 오류를 발생시키지 않지만 제거됩니다: Responses API에 대한 공식 문구는 "이미지 및 파일 입력은 지원되지 않습니다(input_image 파트는 오류를 일으키지 않고 플레이스홀더 텍스트로 대체됩니다)"입니다. 즉input_image파트는 요청을 실패시키지 않고 플레이스홀더 텍스트로 바뀝니다. Chat Completions에서 user 메시지의content는 문자열만 받으며, Messages에서는type="image"블록이 Not Supported로 표시됩니다. 멀티모달 라우팅을 구성할 때는 "오류가 없다"를 모델이 실제로 이미지를 보았다는 근거로 해석하지 마십시오.
2. thinking은 어떻게 끄나요? 세 API, 세 가지 필드 형태
V4 Pro는 기본적으로 thinking을 수행합니다. 파라미터를 전혀 보내지 않으면 응답에 thinking 내용이 포함되어 돌아옵니다. thinking을 끄는 방법은 세 API마다 필드 형태가 다릅니다.
Chat Completions
최상위 thinking 객체를 사용합니다.
from openai import OpenAI
client = OpenAI(
base_url="https://aihubmix.com/v1",
api_key="<AIHUBMIX_API_KEY>",
)
completion = client.chat.completions.create(
model="deepseek-v4-pro-0813",
messages=[{"role": "user", "content": "What is 2 + 2?"}],
extra_body={"thinking": {"type": "disabled"}},
)
# Thinking on (default): message.reasoning_content present, reasoning_tokens = 43
# Thinking off (disabled): reasoning_content absent, reasoning_tokens absent
Verified:thinking.type="disabled"를 설정하면message.reasoning_content와usage.completion_tokens_details.reasoning_tokens가 함께 사라지며, 이로써 전환이 적용되었음이 확인됩니다.
Responses
Responses에는 별도의 스위치가 없으며, 사고를 끄려면 레벨을 none으로 설정합니다.
response = client.responses.create(
model="deepseek-v4-pro-0813",
input="What is 2 + 2?",
reasoning={"effort": "none"},
)
# effort="none": usage.output_tokens_details.reasoning_tokens = 0
# output[0] is the message item directly (no reasoning item)
# effort unset : output always starts with a reasoning item
Verified:reasoning.effort="none"은 기본 레벨과 눈에 띄게 다릅니다(thinking 토큰이 0으로 떨어지고reasoning출력 항목이 사라집니다). 이로써 적용되었음이 확인됩니다.
Messages
Chat Completions와 이름과 형태가 같습니다. 최상위 thinking 객체입니다.
from anthropic import Anthropic
client = Anthropic(
api_key="<AIHUBMIX_API_KEY>",
base_url="https://aihubmix.com",
)
response = client.messages.create(
model="deepseek-v4-pro-0813",
max_tokens=1024,
messages=[{"role": "user", "content": "What is 2 + 2?"}],
extra_body={"thinking": {"type": "disabled"}},
)
# Thinking on (default): content = [thinking block, text block]
# Thinking off (disabled): content = [text block]
Verified: 비활성화하면thinking블록이 완전히 사라지고text블록만 남습니다.
사고 레벨에 대하여: 테스트에서 Chat Completions에low와max를 보냈을 때 모두 200이 반환되었습니다(high가 기본값이며 필드를 생략하면 이 값이 적용됩니다). 그러나 같은 질문에 대한 thinking 토큰 수는 레벨 간에 단조로운 차이를 보이지 않았습니다(쉬운 질문: low=43 / max=27, 어려운 질문: low=114 / max=92). 응답에도 레벨이 되돌아오지 않습니다. 즉 레벨은 수락되지만 응답에서 구별되는 신호는 관찰되지 않습니다. Responses에서는none레벨(thinking 끄기)만 응답 측면에서 확인할 수 있습니다.
3. 다중 턴 대화가 갑자기 400을 반환하는 이유는? 사고 기록을 그대로 재전송해야 합니다
이 모델에서 가장 흔한 함정입니다. thinking 모드에서는 다중 턴 대화 시 이전 턴의 thinking 내용을 그대로 되돌려 보내야 하며, 그렇지 않으면 요청이 거부됩니다. 품질이 떨어지는 정도가 아니라 HTTP 400이라는 명확한 오류입니다.
세 API는 같은 thinking 내용을 서로 다른 필드 이름으로 전달합니다:
| API | 재전송 형태 | 누락 시 오류 본문 |
|---|---|---|
| Chat Completions | assistant 메시지의 reasoning_content 필드 |
The `reasoning_content` in the thinking mode must be passed back to the API. |
| Responses | input 배열에 있는 type="reasoning" 출력 항목 |
The `reasoning_text` in the thinking mode must be passed back to the API. |
| Messages | assistant 콘텐츠 블록 안의 thinking 블록 |
The `content[].thinking` in the thinking mode must be passed back to the API. |
Verified(발생 조건): 이 유효성 검사는 tools를 포함한 다중 턴 요청(모델이 도구 호출을 하고, 그 도구 결과를 다시 보내는 경우)에서 일관되게 발생합니다. 도구가 없는 일반 다중 턴 요청에서는, 모델이 직접 답변하는 경우 이번 테스트에서 검사가 발생하지 않았고 요청은 200을 반환했습니다. 즉 도구 오케스트레이션(에이전트 / 함수 호출 워크로드)에서 이 문제를 가장 만나기 쉬우므로, thinking 내용을 유지하고 재생해야 하는 대화 상태의 일부로 취급하십시오.Chat Completions
# Multi-turn: pass the previous assistant message back verbatim, including reasoning_content
messages = [
{"role": "user", "content": "What is 1 + 1? Remember the result."},
{
"role": "assistant",
"content": "2",
"reasoning_content": "<reasoning_content from the previous response>",
},
{"role": "user", "content": "Add 1 to the result."},
]
# Dropping reasoning_content -> HTTP 400 invalid_request_error
Verified: 이전 assistant 메시지에 reasoning_content가 없으면 400이 반환됩니다. 이를 다시 추가하면 동일한 요청이 200을 반환하고 정상적으로 이어집니다.Responses
# Multi-turn: input = previous input + response.output (reasoning item included) + new message
input = previous_input + response.output + [
{"role": "user", "content": "Add 1 to the result."}
]
# Filtering out the type="reasoning" item -> HTTP 400
Verified:response.output을 수정 없이 그대로 다시 넣기만 하면 됩니다. 기록을 조립할 때 출력 항목을type == "message"로 필터링하면reasoning항목이 빠져서 400이 발생합니다. 이것이 가장 흔하게 걸리는 실수입니다.
Messages
# Multi-turn: pass response.content back verbatim as the assistant message
messages = [
{"role": "user", "content": "What's the weather in Paris?"},
{"role": "assistant", "content": response.content}, # thinking + tool_use blocks
{"role": "user", "content": [tool_result_block]},
]
# Stripping the thinking block -> HTTP 400
Verified: 콘텐츠 배열에서thinking블록을 제거하면 400이 반환됩니다(error.type은invalid_request_error로 설정됨).
4. 도구 호출
각 API는 자체 프로토콜 형태로 도구를 선언하며, 이 형태들은 서로 호환되지 않습니다.
Chat Completions
중첩 형태(function 객체가 name / parameters를 감쌉니다). 이름이 지정된 함수의 tool_choice를 사용하면 호출이 강제됩니다.
completion = client.chat.completions.create(
model="deepseek-v4-pro-0813",
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
tools=[{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get weather for a city",
"parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
},
}],
tool_choice={"type": "function", "function": {"name": "get_weather"}},
)
# Observed: finish_reason "tool_calls", tool_calls[0].function.arguments = {"city": "Paris"}
❗ Verified: thinking이 켜져 있는 동안에는tool_choice: "required"를 사용할 수 없습니다. 이 경우 400Thinking mode does not support this tool_choice가 반환되며, thinking을 끄면(thinking.type="disabled") 동일한 요청이 200을 반환합니다. "반드시 도구를 호출해야 한다"는 의미가 필요하다면, 위와 같이 thinking이 켜진 상태에서도 동작하는 이름이 지정된 함수의tool_choice를 사용하거나, thinking을 먼저 끈 뒤required를 사용하십시오.
Responses
평탄한 형태(type / name / parameters가 같은 수준에 위치합니다).
response = client.responses.create(
model="deepseek-v4-pro-0813",
input="What's the weather in Paris?",
tools=[{
"type": "function",
"name": "get_weather",
"description": "Get weather for a city",
"parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}],
)
# Observed output items: ["reasoning", "function_call"]; arguments = {"city": "Paris"}
Verified: Chat Completions의 중첩 형태(function: {...})를 Responses에 그대로 복사하면 400이 반환됩니다. 평탄한 형태를 사용하십시오.tool_choice: "required"도 Chat과 마찬가지로 thinking 모드 제한을 받습니다.
Messages
Anthropic 네이티브 형태(input_schema)를 사용하며, 호출을 강제하려면 tool_choice: {"type": "any"}를 사용합니다.
response = client.messages.create(
model="deepseek-v4-pro-0813",
max_tokens=1024,
tools=[{
"name": "get_weather",
"description": "Get weather for a city",
"input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}],
tool_choice={"type": "any"},
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
# Observed: content contains a tool_use block, name = get_weather, input = {"city": "Paris"}
❗ 병렬 도구 호출은 DeepSeek의 설계상 끌 수 없습니다. 공식 Anthropic 호환성 페이지는tool_choice행에서disable_parallel_tool_use is ignored라고 명시하고 있으며, Responses 페이지에도 마찬가지로parallel_tool_calls | Ignored (parallel tool calling is always enabled)라고 적혀 있습니다. 테스트 결과도 이와 일치합니다.disable_parallel_tool_use: true를 설정하고 두 도시에 대해 동시에 물어봐도tool_use블록이 두 개 반환됩니다. 순차 실행이 필요하다면 첫 번째 호출만 사용하거나, 클라이언트 측에서 직접 큐를 관리하십시오.
도구 개수와 컨텍스트 비용: 단일 요청에 함수 정의 200개를 보내도 200 응답과 정상적인 답변이 돌아왔고 개수 검증에 걸리지 않았습니다(이 경로에서 관찰한 결과이며, 더 많은 개수는 테스트하지 않았습니다). 하지만 해당 요청의 prompt_tokens는 6,105에 달했습니다. 도구 정의는 전체가 컨텍스트에 들어가며 과금됩니다. 도구가 많다면 모든 도구를 무조건 선언하기보다 시나리오별로 도구 세트를 줄이세요.5. 구조화된 출력
Chat Completions
response_format은 JSON 모드를 지원합니다.
completion = client.chat.completions.create(
model="deepseek-v4-pro-0813",
messages=[{"role": "user", "content": "Return {\"a\": 1} as JSON."}],
response_format={"type": "json_object"},
)
# Observed response content: {"a":1}
검증됨: 출력이 유효한 JSON입니다.
Responses
text.format을 통해 JSON Schema를 선언할 수 있으며, strict 모드를 지원합니다.
response = client.responses.create(
model="deepseek-v4-pro-0813",
input="Return the number 1 under key a.",
text={
"format": {
"type": "json_schema",
"name": "extract",
"strict": True,
"schema": {"type": "object", "properties": {"a": {"type": "integer"}}, "required": ["a"]},
}
},
)
# Observed output text: {"a":1}
검증됨: 출력이 주어진 스키마를 엄격하게 따릅니다.
Messages
Messages(Anthropic) 프로토콜에는 response_format / text.format에 해당하는 기능이 없습니다. 일반적인 우회 방법은 스키마를 도구에 담는 것입니다. 목표 스키마를 input_schema로 하는 도구를 선언하고, tool_choice: {"type": "any"}를 설정한 뒤, tool_use 블록의 input에서 구조화된 결과를 읽습니다. 이번 테스트에서는 이 방식을 별도로 검증하지 않았습니다. 스키마를 확실히 보장해야 한다면 Chat Completions나 Responses를 사용하세요.
6. 컨텍스트 캐싱은 어떻게 활성화하나요? 활성화할 필요 없이 자동입니다
컨텍스트 캐싱(동일한 prefix를 재사용하며, 캐시된 부분은 더 낮은 요금으로 과금됨)은 기본적으로 켜져 있으며 별도의 파라미터가 필요하지 않습니다. 동일한 긴 prefix로 두 번째 요청을 보내면 적중 여부가 usage에 보고되며, 필드 이름은 API마다 다릅니다. 캐싱 세부 사항과 최신 요금은 모델 페이지를, 모델 간 캐싱 전략과 적중률을 높이는 기법은 프롬프트 캐싱 실무를 참고하세요.
Chat Completions
# usage of the second call with an identical long prefix
"prompt_tokens_details": {"cached_tokens": 640} # first call: 0
검증됨: 같은 채널에서 동일한 긴 prefix로 연속 두 번 호출했을 때 cached_tokens가 0에서 640으로 바뀌었습니다.Responses
# usage of the second call with identical long instructions
"input_tokens_details": {"cached_tokens": 896} # first call: 0
Messages
# usage of a call whose long system prefix was already warmed
"cache_read_input_tokens": 896
검증됨: 위의 prefix는 동일한 내용의 Responses 요청으로 미리 워밍업되었고, 첫 번째 Messages 호출은 즉시 896 적중을 기록했습니다. 이는 캐싱이 내용 prefix를 기준으로 이루어지며 프로토콜 인터페이스 간에 공유된다는 점과 일치합니다.
7. logprobs: Chat은 두 개의 채널을 반환합니다
logprobs(로그 확률. 모델이 후보 토큰마다 가지는 신뢰도 정보입니다)는 두 API에서 서로 다른 형태로 반환되므로, 파싱 코드는 각각을 따로 처리해야 합니다.
Chat Completions
completion = client.chat.completions.create(
model="deepseek-v4-pro-0813",
messages=[{"role": "user", "content": "Say hi."}],
logprobs=True,
top_logprobs=2,
)
# Observed: choices[0].logprobs contains TWO arrays
# logprobs.content[] -> tokens of the final answer
# logprobs.reasoning_content[] -> tokens of the thinking text
❗ 검증됨: Chat은content와reasoning_content모두에 대한 로그 확률을 반환합니다. 표준 OpenAI 응답 형태에 따라logprobs.content만 읽는 코드는 오류가 나지 않지만 사고(thinking) 채널을 조용히 놓치게 됩니다. 코드가logprobs아래에 단일 배열이 있다고 가정한다면, 먼저 형태를 확인하는 로직을 추가하세요.
Responses
response = client.responses.create(
model="deepseek-v4-pro-0813",
input="Say hi.",
top_logprobs=3,
)
# Observed: logprobs only on the final message item
# output[-1].content[0].logprobs[] with logprob + top_logprobs details
검증됨: Responses는 logprobs를 최종 텍스트 항목에만 붙입니다. Chat에서 보이는 이중 채널 형태는 없습니다.
Messages
Messages(Anthropic) 프로토콜에는 이에 해당하는 필드가 없습니다. 토큰 단위 확률 정보가 필요하다면 Chat Completions나 Responses를 사용하세요.
8. 어떤 API에서 웹 검색을 할 수 있나요?
여기서의 웹 검색은 서버 측 도구입니다(검색은 서버에서 실행되며, 클라이언트가 요청을 직접 보내지 않습니다). 테스트 결과 Responses와 Messages API 모두에서 실제로 실행됩니다.
Responses
response = client.responses.create(
model="deepseek-v4-pro-0813",
input="What is the latest stable version of Python?",
tools=[{"type": "web_search"}],
)
# Observed output item sequence:
# ["reasoning", "web_search_call", "reasoning", "message"]
검증됨: 출력 시퀀스에 web_search_call 항목이 나타났으며, 이는 서버가 실제로 검색을 수행했음을 의미합니다.Messages
response = client.messages.create(
model="deepseek-v4-pro-0813",
max_tokens=1024,
tools=[{"type": "web_search_20250305", "name": "web_search"}],
messages=[{"role": "user", "content": "What is the latest stable version of Python?"}],
)
# Observed content block sequence:
# ["thinking", "server_tool_use", "web_search_tool_result", "thinking", "text"]
# usage.server_tool_use.web_search_requests = 1
검증됨: usage.server_tool_use.web_search_requests가 1로 집계되었습니다. 검색 요청이 실제로 이루어졌고 사용량으로 계량되었습니다.Chat Completions
Chat에서는 웹 검색을 트리거할 수 없습니다. DeepSeek의 공식 Chat API 레퍼런스에는 요청 스키마 어디에도 검색 도구 필드가 없습니다(이는 필드 목록을 하나씩 확인해 얻은 결론이며, DeepSeek가 지원하지 않는다고 명시적으로 밝힌 것은 아닙니다). 서버 측 검색을 공식적으로 명시 지원하는 API는 Responses(web_search)이며, 공식 Messages 호환성 페이지도 검색 관련 콘텐츠 블록을 나열하고 있습니다.
# Three control groups, same question requiring live information, all HTTP 200:
# A no search field -> "cannot retrieve", annotations = null
# B web_search_options -> "cannot retrieve", annotations = null, usage identical to A
# C enable_search -> "cannot retrieve", annotations = null, usage identical to A
검증됨:web_search_options나enable_search를 보내도 오류는 발생하지 않지만, 아무것도 검색하지 않습니다. 응답에는annotations(웹 검색이 실행될 때 응답에 첨부되는 인용 목록)가 없으며, 사용량도 대조군과 모든 필드가 일치합니다. 웹 접근이 필요하다면 Responses 또는 Messages API를 사용하세요.
9. 사용 시 참고 사항: DeepSeek의 설계와 우리 경로에서의 차이
아래 항목은 모두 HTTP 200을 반환하면서도 직관에 반하게 동작합니다. 원인은 서로 다르며, 대응 방법도 다르므로 따로 나열합니다. 첫 번째 그룹은 DeepSeek가 모델을 설계한 방식으로, 제공자를 바꿔도 달라지지 않습니다. 두 번째 그룹은 AIHubMix 경로의 현재 동작으로, 개선 작업을 진행 중입니다.
9.1 DeepSeek 설계에 따른 동작
| 동작 | 공식 설명 | 대응 방법 |
|---|---|---|
| Responses는 세션 상태나 메타데이터를 보관하지 않습니다 | 공식 Responses 호환성 페이지는 행별로 store | Not supported. The response always carries store: false, metadata | Not supported, safety_identifier | Not supported라고 명시합니다(이 네 필드 중 user만 지원됩니다). 테스트 결과도 일치합니다. 요청은 200을 반환하지만 metadata는 null이고, safety_identifier는 없으며, store는 항상 false입니다. |
요청 상관 데이터는 클라이언트에 보관하고, 서버 측 보관에 의존하지 마세요 |
| 사고 모드에서는 샘플링 파라미터가 효과가 없습니다 | DeepSeek는 사고 모드에서 temperature와 top_p가 조용히 무시된다고 명시합니다. 테스트에서도 둘 다 200을 반환했고, 아무 값도 되돌아오지 않았으며 응답 형태도 바뀌지 않았습니다 |
사고 모드에서 출력 안정성을 위해 샘플링 파라미터에 의존하지 마세요. 결정성이 필요하다면 구조화된 출력을 사용하세요 |
| Prefix 이어쓰기 / FIM은 공식 베타 엔드포인트에서만 가능합니다 | prefix의 공식 설명은 "(Beta) … 이 기능을 사용하려면 base_url="https://api.deepseek.com/beta"를 설정해야 합니다"이며, FIM 완성 역시 베타 기능입니다. AIHubMix 운영 환경에서 검증한 결과, 표준 엔드포인트에 prefix: true를 보내면 200이 반환되지만 prefix는 조용히 무시되며, 이는 공식 설명과 방향이 일치합니다 |
출력 형식을 통제하려면 구조화된 출력(5장)이나 stop 절단을 사용하세요 |
| 병렬 도구 호출은 끌 수 없습니다 | 4장을 참고하세요. DeepSeek는 Responses와 Anthropic 페이지 모두에서 해당 스위치가 무시되며 병렬 호출은 항상 켜져 있다고 명시합니다 | 순차 실행이 필요하다면 클라이언트에서 호출을 큐에 넣어 처리하세요 |
9.2 AIHubMix 경로의 현재 동작
| 동작 | 테스트 결과 | 대응 방법 |
|---|---|---|
Responses 오류 객체의 비표준 type |
4xx 응답의 error.type은 Aihubmix_api_error인 반면, Messages에서 같은 종류의 오류는 표준 invalid_request_error를 반환합니다 |
HTTP 상태 코드로 분기하고, error.type 문자열로 분기하지 마세요 |
| Messages에서 사고 토큰이 0으로 집계됨 | 응답에는 thinking 블록이 포함되지만, usage.output_tokens_details.thinking_tokens는 항상 0입니다. 이는 실제로 생성된 사고 내용과 모순됩니다. 우리가 연동하는 Anthropic 규격에서는 해당 필드가 필수이며 output_tokens 이하여야 합니다 |
사고 비용을 계산하려면 Chat에서는 completion_tokens_details.reasoning_tokens을, Responses에서는 output_tokens_details.reasoning_tokens를 사용하세요 |
Messages는 model을 deepseek-v4-pro로 되돌려 보냄 |
요청은 deepseek-v4-pro-0813을 보내지만 응답은 deepseek-v4-pro를 되돌려 줍니다. 원인은 명명 방식에 있습니다. DeepSeek의 공식 API 모델 이름은 deepseek-v4-pro뿐이며, 0813은 버전 표기입니다 |
응답의 model 필드만으로 모델 라우팅 검사나 사용량 귀속을 판단하지 마세요 |
9.3 DeepSeek가 정의하지 않은 항목이라 판단을 내리지 않음
reasoning_effort의 열거값 밖의 값(예: bogus_xyz)을 보내면 오류 없이 정상 답변과 함께 200이 반환되며, 관찰 가능한 효과도 없습니다. 사실 자체는 분명합니다. 이 경로는 현재 reasoning_effort 열거값을 검증하지 않습니다. 불명확한 점은 이것이 검증되어야 하는지입니다. DeepSeek는 허용되는 열거값을 공개하지만 잘못된 수준을 거부해야 하는지는 명시하지 않으므로, 판단할 기준이 없습니다. 따라서 이는 공식 동작으로도, 우리 경로의 결함으로도 볼 수 없습니다. 안전한 방법은 클라이언트에서 직접 수준을 검증하고 API가 이를 잡아주리라 기대하지 않는 것입니다.
10. 기능 × API 지원 매트릭스
아래 셀은 각 API의 파라미터 / 필드 표기를 보여줍니다. DeepSeek의 명시적 표현으로 표시된 경우를 제외하면, 모든 결론은 2026-08-13에 AIHubMix 운영 API를 실제로 호출해 얻은 것입니다.
| 기능 | Chat Completions | Responses | Messages |
|---|---|---|---|
| 기본 채팅 / 시스템 지시 | ✅ messages |
✅ input + instructions |
✅ messages + 최상위 system |
| 스트리밍 | ✅ stream + stream_options |
✅ stream (response.created … response.completed) |
✅ stream (message_start … message_stop) |
| 출력 상한 | ✅ max_tokens(초과 시 400, 상한 393216) |
✅ max_output_tokens |
✅ max_tokens |
| 사고 비활성화 | ✅ thinking: {"type": "disabled"} |
✅ reasoning: {"effort": "none"} |
✅ thinking: {"type": "disabled"} |
| 사고 수준 | 🟡 reasoning_effort은 허용되지만 구별되는 신호는 없음 |
✅ reasoning.effort(none만 확인 가능) |
🟡 output_config.effort은 허용되지만 아무 값도 되돌아오지 않음 |
| 사고 내용 반환 | ✅ reasoning_content 필드 |
✅ reasoning 출력 항목 |
✅ thinking 콘텐츠 블록 |
| 사고 기록의 필수 전달(passback) | ✅ reasoning_content 누락 → 400 |
✅ reasoning 항목 누락 → 400 |
✅ thinking 블록 누락 → 400 |
| 도구 호출 | ✅ 중첩 tools + 이름 지정 tool_choice |
✅ 평탄한 tools |
✅ input_schema + tool_choice: {"type":"any"} |
required로 호출 강제 |
❗ 사고가 켜져 있으면 400. 먼저 사고를 끄세요 | ❗ 왼쪽과 동일 | ✅ {"type": "any"} |
| 병렬 도구 호출(비활성화 불가) | ➖ 공식 Chat API에는 해당 필드가 없음 | ❗ DeepSeek는 parallel_tool_calls이 무시되며 병렬 호출이 항상 켜져 있다고 명시함 |
❗ DeepSeek는 disable_parallel_tool_use이 무시된다고 명시함. 테스트에서도 tool_use 블록이 두 개 반환됨 |
| 구조화된 출력 | ✅ response_format(json_object) |
✅ text.format(json_schema + strict) |
➖ 프로토콜 필드 없음; 스키마는 도구(tool)에 담아 전달 |
| 자동 캐시 적중 계량 | ✅ usage.prompt_tokens_details.cached_tokens |
✅ usage.input_tokens_details.cached_tokens |
✅ usage.cache_read_input_tokens |
| logprobs | ❗ 이중 채널: content + reasoning_content |
✅ 최종 텍스트 항목에만 top_logprobs 지원 |
➖ |
| 웹 검색 | ➖ 공식 Chat API에는 검색 필드가 없으며, 이를 보내도 검색이 실행되지 않음 | ✅ tools: [{"type": "web_search"}] |
✅ web_search_20250305 |
| Stop sequences | ✅ stop |
➖ 프로토콜에 stop sequence 필드 없음 (길이는 max_output_tokens로만 제한) |
✅ stop_sequences (stop_reason: "stop_sequence") |
범례: ✅ 작동 확인됨 · 🟡 허용되지만 실제 적용 여부는 확인 불가 · ❗ 주의 필요(위 설명 참고) · ➖ 이 API에는 해당 개념 없음
FAQ
deepseek-v4-pro-0813은 AIHubMix에서 어떤 API를 지원하나요?
Chat Completions(/v1/chat/completions), Responses(/v1/responses), 그리고 Claude 호환 Messages API(/v1/messages)를 지원합니다.
다중 턴 대화에서 갑자기 400이 반환되는 이유는 무엇인가요?
가장 흔한 원인은 전달되지 않은 사고(thinking) 기록입니다. 사고 모드에서는 이전 턴의 사고 내용을 그대로 다시 전달해야 합니다. Chat에서는 어시스턴트 메시지의 reasoning_content, Responses에서는 type="reasoning" 출력 항목, Messages에서는 thinking 콘텐츠 블록이 해당합니다. 도구를 함께 쓰는 다중 턴에서 문제가 가장 자주 발생합니다. 많은 프레임워크가 기록을 구성할 때 type == "message"로 출력 항목을 걸러내는데, 이 과정에서 reasoning 항목이 빠지기 때문입니다.
사고 기능을 끌 수 있나요?
예. Chat이나 Messages에서는 thinking: {"type": "disabled"}을, Responses에서는 reasoning: {"effort": "none"}을 보내면 됩니다. 꺼지면 사고 내용과 사고 토큰이 모두 사라집니다.
세 가지 reasoning_effort 수준은 서로 차이가 있나요?low / high / max 모두 허용됩니다(기본값 high, medium과 xhigh는 호환성을 위해 high로 매핑됨). 테스트에서 같은 질문에 대한 사고 토큰 수는 수준 간에 일관된 증가 경향이 없었고, 어떤 값도 되돌아오지 않아 호출자 측에서는 차이를 확인할 수 없었습니다. Responses의 none 수준(사고 끄기)만 뚜렷하게 관찰 가능한 차이를 보입니다.
왜 tool_choice: "required"가 400을 반환하나요?
사고가 켜져 있을 때는 이 값이 허용되지 않습니다(오류 본문은 Thinking mode does not support this tool_choice라고 표시됨). 사고가 켜진 상태에서 특정 호출을 강제하려면 이름이 지정된 함수 형식의 tool_choice({"type": "function", "function": {"name": "..."}})를 사용하거나, 먼저 사고를 끈 뒤 required를 사용하세요.
컨텍스트 캐싱은 어떻게 활성화하나요?
따로 활성화할 필요가 없으며 자동으로 적용됩니다. 시스템 프롬프트, 지식 스니펫, 도구 정의처럼 안정적으로 변하지 않는 내용을 요청의 앞부분에 두면 됩니다. 적중 횟수는 usage에 보고되며, Chat에서는 prompt_tokens_details.cached_tokens, Responses에서는 input_tokens_details.cached_tokens, Messages에서는 cache_read_input_tokens에서 확인할 수 있습니다.
가격과 실시간 상태는 deepseek-v4-pro-0813 모델 페이지에서 확인하고, 더 많은 모델은 모델 갤러리를 방문하세요.
관련 실습 가이드: Kimi K3 실습 가이드(새 파라미터와 3-API 지원 매트릭스 포함), GPT-5.6 프롬프트 캐싱 및 과금 변경 사항.
