이 기사는 deepseek-v4-pro-0813의 사용 노트와 주의 사항을 다룹니다. AIHubMix에서 이 모델은 Chat Completions, Responses 및 Claude 호환 Messages API를 통해 사용할 수 있습니다. 또한 DeepSeek 공식 API 문서를 참조하십시오.
각 섹션의 "검증된" 결론과 샘플 응답은 2026-08-13에 AIHubMix API(채팅 완료 / 응답 / 메시지)를 통해 실제로 수행된 호출에서 가져온 것입니다. "검증된"으로 표시되지 않은 사양 항목은 DeepSeek의 공식 문서에서 가져온 것입니다.
1. 모델 포지셔닝 및 사양 개요
V4 Pro는 DeepSeek의 V4 세대의 고급 모델입니다(경량 deepseek-v4-flash는 그 형제 모델입니다). 출시 라인은 2026-04-24의 DeepSeek-V4 미리보기로 거슬러 올라가며, 0813은 DeepSeek가 현재 빌드에 할당한 모델 버전 레이블입니다. 원시 사양을 넘어 네 가지가 차별화됩니다:
- 희소한 프론티어 모델: 총 1.6T 매개변수 / 49B 활성화(전문가 혼합 아키텍처 — 각 추론 패스는 전문가 네트워크의 하위 집합만 활성화합니다: 총 매개변수는 지식 용량을 결정하고, 활성화된 매개변수는 호출당 계산 비용을 결정합니다). 모델 카드에는 CSA+HCA 하이브리드 주의, mHC 및 Muon 최적화기가 나열되어 있습니다.
- MIT 하에 공개된 가중치:
deepseek-ai/DeepSeek-V4-Pro는 MIT 라이센스 하에 HuggingFace에 게시되어 있으며(가장 관대 한 오픈 소스 라이센스 중 하나 — 상업적 사용 및 비공식 재배포가 모두 허용됨) 자체 호스팅이 가능합니다. 이 크기의 모델에 대해 MIT는 드뭅니다. 모델 카드의 자체 호스팅 노트는 Think Max(최고 사고 수준)에서 실행할 때 ≥384K 토큰의 컨텍스트 창을 제안합니다 — 이는 자체 호스팅을 위한 배포 지침이지 호스팅된 API의 사양이 아닙니다. - 다중 프로토콜 지원은 제3자 번역이 아닌 1차 제공: DeepSeek 자체에서 OpenAI Chat API, Anthropic 호환 엔드포인트(
/anthropic, 이 모델에claude-opus*를 매핑) 및 Responses API를 제공합니다(DeepSeek는 Codex에 대한 적응과 함께 형식에 대한 기본 지원을 설명합니다). 또한 별도의 엔드포인트에서 베타 기능으로 FIM(중간 채우기) 완료를 제공하며, 이는 세 가지 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" 블록을 지원하지 않음으로 표시합니다; Chat Completions에서는 사용자 메시지 content가 문자열만 수용하며, 다중 모드 콘텐츠 부분은 없습니다. |
| 사고 모드 | 하이브리드(사고 / 비사고), 기본적으로 사고 활성화 |
| 사고 수준 | reasoning_effort는 low / high / max를 수용하며, 기본값은 high입니다; medium 및 xhigh는 호환성을 위해 high로 매핑됩니다. |
| 사용 가능한 API | Chat Completions, Responses, Messages (Claude 호환) |
검증됨:max_tokens를 초과하면 검증에 의해 거부되며 조용히 잘리지는 않습니다 —max_tokens=9999999를 보내면 HTTP 400이 반환되며, 오류 본문은 필드를 명명하고 상한393216을 제공합니다.
# max_tokens=9999999 -> HTTP 400
"...max_tokens... 393216"
❗ 이미지는 오류를 발생시키지 않지만 삭제됩니다: Responses API에 대한 공식 문구는 "이미지 및 파일 입력은 지원되지 않습니다(입력 이미지 부분은 오류를 발생시키지 않지만 자리 표시자 텍스트로 대체됩니다)"입니다 —input_image부분은 요청을 실패시키지 않으며 자리 표시자 텍스트로 교체됩니다. Chat Completions에서는 사용자 메시지content가 문자열만 수용하며, Messages에서는type="image"블록이 지원되지 않음으로 표시됩니다. 다중 모드 라우팅을 구축할 때 "오류 없음"을 모델이 실제로 이미지를 보았다는 증거로 취급하지 마십시오.
2. 사고를 끄려면 어떻게 하나요? 세 가지 API, 세 가지 필드 형태
V4 Pro는 기본적으로 사고를 활성화합니다: 아무 매개변수도 보내지 않으면 응답이 사고 콘텐츠와 함께 돌아옵니다. 이를 끄려면 세 가지 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": "2 + 2는 얼마인가요?"}],
extra_body={"thinking": {"type": "disabled"}},
)
# 사고 활성화 (기본값): message.reasoning_content 존재, reasoning_tokens = 43
# 사고 비활성화 (비활성화): reasoning_content 없음, reasoning_tokens 없음
검증됨: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="2 + 2는 얼마인가요?",
reasoning={"effort": "none"},
)
# effort="none": usage.output_tokens_details.reasoning_tokens = 0
# output[0]는 메시지 항목 직접 (추론 항목 없음)
# effort 미설정: output은 항상 추론 항목으로 시작합니다.
검증됨:reasoning.effort="none"는 기본 수준과 눈에 띄게 다릅니다(사고 토큰이 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": "2 + 2는 얼마인가요?"}],
extra_body={"thinking": {"type": "disabled"}},
)
# 사고 활성화 (기본값): content = [사고 블록, 텍스트 블록]
# 사고 비활성화 (비활성화): content = [텍스트 블록]
검증됨: 비활성화되면thinking블록이 완전히 사라지고text블록만 남습니다.
사고 수준에 대하여:low와max는 테스트에서 Chat Completions에서 모두 200을 반환했습니다(high가 기본값이며 필드가 생략될 때 적용됨), 그러나 사고 토큰 수는 동일한 질문에 대해 수준 간의 단조로운 차이를 보이지 않으며 응답에서 아무것도 회신되지 않습니다 — 수준은 수용되지만 응답에서 구별 신호는 관찰되지 않습니다. Responses에서는none수준(사고 비활성화)만 응답 측에서 확인할 수 있습니다.
3. 다중 턴 대화가 갑자기 400을 반환하는 이유는 무엇인가요? 사고 기록은 그대로 전달되어야 합니다
이 모델에서 가장 일반적인 트립와이어입니다: 사고 모드에서 다중 턴 대화는 이전 턴의 사고 콘텐츠를 그대로 전달해야 하며, 그렇지 않으면 요청이 거부됩니다. 저하되지 않고, 품질이 낮아지지 않으며 — 하드 HTTP 400입니다.
세 가지 API는 다른 필드 이름 아래 동일한 사고 콘텐츠를 전달합니다:
| API | 패스백 형태 | 누락 시 오류 본문 |
|---|---|---|
| Chat Completions | 어시스턴트 메시지의 reasoning_content 필드 |
사고 모드에서는 `reasoning_content`가 API에 전달되어야 합니다. |
| Responses | 입력 배열의 type="reasoning" 출력 항목 |
사고 모드에서는 `reasoning_text`가 API에 전달되어야 합니다. |
| Messages | 어시스턴트 콘텐츠 블록 내의 thinking 블록 |
사고 모드에서는 `content[].thinking`이 API에 전달되어야 합니다. |
검증됨 (트리거 조건): 이 검증은 도구를 포함한 다중 턴 요청에서 일관되게 발생합니다(모델이 도구 호출을 수행한 후 도구 결과가 다시 전송됨). 도구 없이 일반 다중 턴 요청에서는 모델이 직접 응답할 때 이 검증이 발생하지 않았으며 요청이 200을 반환했습니다. 즉, 도구 오케스트레이션(에이전트 / 함수 호출 워크로드)에서 가장 많이 발생하므로 사고 콘텐츠를 지속하고 재생해야 하는 대화 상태의 일부로 간주하십시오.
Chat Completions
# 다중 턴: 이전 어시스턴트 메시지를 그대로 전달, reasoning_content 포함
messages = [
{"role": "user", "content": "1 + 1은 얼마인가요? 결과를 기억하세요."},
{
"role": "assistant",
"content": "2",
"reasoning_content": "<이전 응답의 reasoning_content>",
},
{"role": "user", "content": "결과에 1을 더하세요."},
]
# reasoning_content를 삭제하면 -> HTTP 400 invalid_request_error
검증됨: 역사적 어시스턴트 메시지에서 reasoning_content가 누락되면 400이 반환되며; 이를 추가하면 동일한 요청이 200을 반환하고 올바르게 계속됩니다.Responses
# 다중 턴: 입력 = 이전 입력 + response.output (추론 항목 포함) + 새 메시지
input = previous_input + response.output + [
{"role": "user", "content": "결과에 1을 더하세요."}
]
# type="reasoning" 항목을 필터링하면 -> HTTP 400
검증됨:response.output를 그대로 다시 삽입하는 것만으로 충분합니다. 역사 조립 중에type == "message"로 출력 항목을 필터링하면reasoning항목이 삭제되어 400이 발생합니다 — 이는 가장 일반적인 방법입니다.
Messages
# 다중 턴: 응답.content를 어시스턴트 메시지로 그대로 전달
messages = [
{"role": "user", "content": "파리의 날씨는 어떤가요?"},
{"role": "assistant", "content": response.content}, # 사고 + 도구 사용 블록
{"role": "user", "content": [tool_result_block]},
]
# 사고 블록을 제거하면 -> HTTP 400
검증됨: 콘텐츠 배열에서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": "파리의 날씨는 어떤가요?"}],
tools=[{
"type": "function",
"function": {
"name": "get_weather",
"description": "도시의 날씨를 가져옵니다",
"parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
},
}],
tool_choice={"type": "function", "function": {"name": "get_weather"}},
)
# 관찰됨: finish_reason "tool_calls", tool_calls[0].function.arguments = {"city": "Paris"}
❗ 검증됨:tool_choice: "required"는 사고가 활성화된 상태에서 사용할 수 없습니다 — 400사고 모드에서는 이 tool_choice를 지원하지 않습니다라는 오류가 반환됩니다; 사고를 비활성화(thinking.type="disabled")하면 동일한 요청이 200을 반환합니다. "반드시 도구를 호출해야 한다"는 의미가 필요할 때는 대신 명명된 함수tool_choice를 사용하십시오(위와 같이 사고가 활성화된 상태에서 작동함), 또는 먼저 사고를 비활성화한 후required를 사용하십시오.
Responses
평면 형태(type / name / parameters가 동일한 수준에 있습니다).
response = client.responses.create(
model="deepseek-v4-pro-0813",
input="파리의 날씨는 어떤가요?",
tools=[{
"type": "function",
"name": "get_weather",
"description": "도시의 날씨를 가져옵니다",
"parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}],
)
# 관찰된 출력 항목: ["reasoning", "function_call"]; arguments = {"city": "Paris"}
검증됨: Chat Completions의 중첩 형태(function: {...})를 Responses에 복사하면 400이 반환됩니다 — 평면 형태를 사용하십시오.tool_choice: "required"는 Chat에서와 같은 사고 모드 제한을 받습니다.
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": "도시의 날씨를 가져옵니다",
"input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}],
tool_choice={"type": "any"},
messages=[{"role": "user", "content": "파리의 날씨는 어떤가요?"}],
)
# 관찰됨: 콘텐츠에 도구 사용 블록이 포함되어 있으며, 이름 = get_weather, 입력 = {"city": "Paris"}
❗ 병렬 도구 호출은 DeepSeek의 설계에 따라 비활성화할 수 없습니다 — 공식 Anthropic 호환성 페이지는tool_choice행에서disable_parallel_tool_use는 무시됩니다라고 명시하고, Responses 페이지에서도parallel_tool_calls | 무시됨 (병렬 도구 호출은 항상 활성화됨)이라고 명시합니다. 테스트 결과: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": "{"a": 1}를 JSON으로 반환하세요."}],
response_format={"type": "json_object"},
)
# 관찰된 응답 콘텐츠: {"a":1}
검증됨: 출력은 유효한 JSON입니다.
Responses
JSON 스키마를 text.format를 통해 선언하며, strict 모드가 지원됩니다.
response = client.responses.create(
model="deepseek-v4-pro-0813",
input="키 a 아래에 숫자 1을 반환하세요.",
text={
"format": {
"type": "json_schema",
"name": "extract",
"strict": True,
"schema": {"type": "object", "properties": {"a": {"type": "integer"}}, "required": ["a"]},
}
},
)
# 관찰된 출력 텍스트: {"a":1}
검증됨: 출력은 주어진 스키마를 엄격하게 준수합니다.
Messages
Messages(Anthropic) 프로토콜에는 response_format / text.format에 해당하는 것이 없습니다. 일반적인 우회 방법은 스키마를 도구에 포함시키는 것입니다 — 목표 스키마가 input_schema인 도구를 선언하고, tool_choice: {"type": "any"}를 설정한 후 tool_use 블록의 input에서 구조화된 결과를 읽는 것입니다. 이번 테스트에서는 해당 패턴을 구체적으로 검증하지 않았습니다; 하드 스키마 보장이 필요한 경우 Chat Completions 또는 Responses를 선호하십시오.
6. 컨텍스트 캐싱을 활성화하려면 어떻게 하나요? 필요 없습니다, 자동입니다
컨텍스트 캐싱(동일한 접두사가 재사용되고 캐시된 부분은 더 낮은 요금으로 청구됨)은 기본적으로 활성화되어 있으며 매개변수가 필요 없습니다. 동일한 긴 접두사로 두 번째 요청을 하면 usage에서 적중을 보고하며, API에 따라 필드 이름이 다릅니다. 캐싱 세부정보 및 현재 가격은 모델 페이지를 참조하십시오; 모델 간 캐싱 전략 및 적중률 기술에 대해서는 프롬프트 캐싱 관행를 참조하십시오.
Chat Completions
# 동일한 긴 접두사로 두 번째 호출의 사용
"prompt_tokens_details": {"cached_tokens": 640} # 첫 번째 호출: 0
검증됨: 동일한 채널에서 동일한 긴 접두사로 두 번 연속 호출하면 cached_tokens가 0에서 640으로 이동합니다.Responses
# 동일한 긴 지침으로 두 번째 호출의 사용
"input_tokens_details": {"cached_tokens": 896} # 첫 번째 호출: 0
Messages
# 이미 워밍업된 긴 시스템 접두사의 호출 사용
"cache_read_input_tokens": 896
검증됨: 위의 접두사는 동일한 콘텐츠로 Responses 요청에 의해 워밍업되었으며, 첫 번째 Messages 호출은 즉시 896에 도달했습니다 — 콘텐츠 접두사에 따라 캐싱이 이루어지고 프로토콜 표면 간에 공유되는 것과 일치합니다.
7. logprobs: Chat은 두 개의 채널을 반환합니다
logprobs (로그 확률 — 모델의 후보 토큰당 신뢰도 세부정보)는 두 API에서 서로 다른 형태로 반환되며, 파싱 코드는 이를 별도로 처리해야 합니다.
Chat Completions
completion = client.chat.completions.create(
model="deepseek-v4-pro-0813",
messages=[{"role": "user", "content": "안녕하세요."}],
logprobs=True,
top_logprobs=2,
)
# 관찰됨: choices[0].logprobs에는 두 개의 배열이 포함되어 있습니다
# logprobs.content[] -> 최종 답변의 토큰
# logprobs.reasoning_content[] -> 사고 텍스트의 토큰
❗ 검증됨: Chat은content와reasoning_content모두에 대한 로그 확률을 반환합니다. 표준 OpenAI 응답 형태에 따라logprobs.content만 읽는 코드는 오류가 발생하지 않지만 사고 채널을 조용히 놓칠 것입니다; 코드가logprobs아래 단일 배열을 가정하는 경우 먼저 형태 검사를 추가하십시오.
Responses
response = client.responses.create(
model="deepseek-v4-pro-0813",
input="안녕하세요.",
top_logprobs=3,
)
# 관찰됨: 로그 확률은 최종 메시지 항목에만 존재
# output[-1].content[0].logprobs[]에 로그 확률 + top_logprobs 세부정보가 포함되어 있습니다
검증됨: Responses는 로그 확률을 최종 텍스트 항목에만 첨부합니다 — Chat에서 보이는 이중 채널 형태는 없습니다.
Messages
Messages(Anthropic) 프로토콜에는 해당 필드가 없습니다. 토큰 수준 확률 세부정보를 원할 경우 Chat Completions 또는 Responses를 사용하십시오.
8. 어떤 API가 웹 검색을 할 수 있나요?
웹 검색은 서버 측 도구입니다(검색이 서버에서 실행되며 클라이언트가 요청을 직접 발행하지 않음)이며, 테스트에서 Responses 및 Messages API 모두에서 실제로 실행됩니다.
Responses
response = client.responses.create(
model="deepseek-v4-pro-0813",
input="최신 안정적인 Python 버전은 무엇인가요?",
tools=[{"type": "web_search"}],
)
# 관찰된 출력 항목 시퀀스:
# ["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": "최신 안정적인 Python 버전은 무엇인가요?"}],
)
# 관찰된 콘텐츠 블록 시퀀스:
# ["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 호환성 페이지에서도 검색 관련 콘텐츠 블록을 나열합니다.
# 세 개의 제어 그룹, 동일한 질문이 실시간 정보를 요구하며, 모두 HTTP 200:
# 검색 필드 없음 -> "검색할 수 없음", 주석 = null
# B web_search_options -> "검색할 수 없음", 주석 = null, 사용량은 A와 동일
# C enable_search -> "검색할 수 없음", 주석 = null, 사용량은 A와 동일
검증됨:web_search_options또는enable_search를 보내도 오류가 발생하지 않지만 아무것도 검색하지도 않습니다 — 응답에는 웹 검색이 실행될 때 응답에 첨부되는 주석이 없습니다, 그리고 사용량은 제어 그룹과 필드별로 일치합니다. 웹 액세스를 원할 경우 대신 Responses 또는 Messages API를 사용하십시오.
9. 사용 노트: DeepSeek의 설계 대 우리의 경로에서의 편차
아래 모든 항목은 HTTP 200을 반환하지만 직관에 반하는 동작을 합니다. 원인은 다르며, 그에 따라 해야 할 일도 다르므로 별도로 나열됩니다: 첫 번째 그룹은 DeepSeek가 모델을 설계한 방식이며, 공급자를 변경해도 변경되지 않습니다; 두 번째 그룹은 AIHubMix 경로에서의 현재 동작으로, 우리는 이를 개선하기 위해 노력하고 있습니다.
9.1 DeepSeek의 설계에 따라
| 동작 | 공식 문구 | 해야 할 일 |
|---|---|---|
| Responses는 세션 상태 또는 메타데이터를 유지하지 않습니다 | 공식 Responses 호환성 페이지는 행별로 store | 지원되지 않음. 응답은 항상 store: false를 포함합니다, metadata | 지원되지 않음, safety_identifier | 지원되지 않음 (이 네 개의 필드 중 user만 지원됨)이라고 명시합니다. 테스트 결과 일치: 요청은 200을 반환하지만 metadata는 null이며, safety_identifier는 없고, store는 항상 false입니다. |
클라이언트에서 요청 상관 데이터를 유지하십시오; 서버 측 보존에 의존하지 마십시오. |
| 사고 모드에서 샘플링 매개변수는 효과가 없습니다 | DeepSeek는 temperature와 top_p가 사고 모드에서 조용히 무효라고 명시적으로 언급합니다. 테스트에서 두 매개변수 모두 200을 반환하며 아무것도 회신되지 않고 응답 형태에 변화가 없습니다. |
사고 모드에서 출력 안정성을 위해 샘플링 매개변수에 의존하지 마십시오; 결정론이 필요한 경우 구조화된 출력을 사용하십시오. |
| 접두사 연속 / FIM은 공식 베타 엔드포인트에서만 가능합니다 | 공식 prefix 설명은 "(베타) … 이 기능을 사용하려면 base_url="https://api.deepseek.com/beta"를 설정해야 합니다"이며, FIM 완료 또한 베타 기능입니다. AIHubMix 프로덕션에서 검증됨: 표준 엔드포인트에 대해 prefix: true를 보내면 200을 반환하지만 접두사는 조용히 삭제됩니다, 이는 공식 문구와 일치합니다. |
제어된 출력 형식을 위해 구조화된 출력을 사용하거나 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 콘텐츠 블록 |
| 필수 사고 기록 패스백 | ✅ 누락된 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) |
➖ 프로토콜 필드 없음; 도구에 스키마를 포함시키십시오 |
| 자동 캐시 적중 측정 | ✅ 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 |
➖ 프로토콜에 중지 시퀀스 필드 없음 (오직 max_output_tokens가 길이를 제한함) |
✅ stop_sequences (stop_reason: "stop_sequence") |
전설: ✅ 검증된 작동 · 🟡 수용되지만 효과를 확인할 수 없음 · ❗ 주의 필요 (위의 노트 참조) · ➖ 이 API에는 해당 개념 없음
FAQ
AIHubMix에서 deepseek-v4-pro-0813은 어떤 API를 지원하나요?
Chat Completions (/v1/chat/completions), Responses (/v1/responses), 및 Claude 호환 Messages API (/v1/messages)입니다.
다중 턴 대화가 갑자기 400을 반환하는 이유는 무엇인가요?
가장 일반적인 원인은 전달되지 않은 사고 기록입니다. 사고 모드에서 이전 턴의 사고 콘텐츠는 그대로 재생되어야 합니다: Chat의 경우 어시스턴트 메시지의 reasoning_content, Responses의 경우 type="reasoning" 출력 항목, Messages의 경우 thinking 콘텐츠 블록입니다. 도구가 있는 다중 턴에서 가장 큰 영향을 미칩니다 — 많은 프레임워크가 역사 조립 중에 출력 항목을 type == "message"로 필터링하여 추론 항목이 삭제됩니다.
사고를 끌 수 있나요?
예. Chat 또는 Messages에서 thinking: {"type": "disabled"}를 보내고, Responses에서는 reasoning: {"effort": "none"}를 보내십시오. 비활성화되면 사고 콘텐츠와 사고 토큰이 모두 사라집니다.
세 가지 reasoning_effort 수준이 다르나요?low / high / max는 모두 수용됩니다 (기본값은 high; medium 및 xhigh는 호환성을 위해 high로 매핑됩니다). 테스트에서 동일한 질문에 대한 사고 토큰 수는 수준 간의 단조로운 차이를 보이지 않으며 아무것도 회신되지 않으므로 호출 측에서 차이를 확인할 수 없습니다. Responses의 경우 none 수준(사고 비활성화)만 명확한 관찰 가능한 차이를 생성합니다.
왜 tool_choice: "required"가 400을 반환하나요?
이 값은 사고가 활성화된 상태에서 수용되지 않습니다 (오류 본문은 사고 모드에서는 이 tool_choice를 지원하지 않습니다라고 읽습니다). 사고가 활성화된 상태에서 특정 호출을 강제하려면 명명된 함수 tool_choice ({"type": "function", "function": {"name": "..."}})를 사용하거나 먼저 사고를 비활성화한 후 required를 사용하십시오.
컨텍스트 캐싱을 활성화하려면 어떻게 하나요?
필요 없습니다 — 자동입니다. 안정적이고 변하지 않는 콘텐츠(시스템 프롬프트, 지식 조각, 도구 정의)를 요청의 앞부분에 두면 적중 수가 보고됩니다: Chat의 경우 prompt_tokens_details.cached_tokens, Responses의 경우 input_tokens_details.cached_tokens, Messages의 경우 cache_read_input_tokens입니다.
가격 및 실시간 상태는 deepseek-v4-pro-0813 모델 페이지를 참조하십시오; 더 많은 모델은 모델 갤러리를 방문하십시오.
관련 핸즈온 가이드: Kimi K3 핸즈온 가이드 (새로운 매개변수 및 세 가지 API 지원 매트릭스) 및 GPT-5.6 프롬프트 캐싱 및 청구 변경입니다.
