API 호환 모델 서비스는 화려하지는 않지만 중요한 역할을 수행합니다. 여러 공개 요청 형식을 모델이 기대하는 정확한 프롬프트로 변환하고, 생성된 토큰을 클라이언트가 기대하는 응답 형태로 다시 변환하는 것입니다. deepseek-recipe 는 DeepSeek V4 및 V4.1 을 위한 해당 변환 계층을 패키징합니다.

이 라이브러리는 모델을 실행하지 않습니다. HTTP 포트를 열거나, 도구를 실행하거나, 웹을 검색하거나, 대화를 저장하지도 않습니다. 이 튜토리얼에서는 그 경계를 명확히 유지하는 것이 시간을 절약해 줍니다. 출력 결과는 추론 백엔드가 소비할 수 있는 렌더링된 프롬프트이지 모델 답변이 아닙니다.

Python 바인딩 설치

공식 패키지는 Python 3.10 이상이 필요합니다:

python3 -m pip install deepseek-recipe

재현 가능한 프로젝트를 위해 가상 환경 내에 설치하고 첫 번째 검증 실행 후 버전을 고정하세요. 이 저장소는 2026 년 9 월에 새로 출판되었으며 API 는 여전히 진화할 수 있습니다. Python 패키지 버전과 애플리케이션에서 선택한 V4/V4.1 인코딩을 모두 기록하세요.

이 패키지는 Rust 크레이트 제품군을 기반으로 합니다. Python 사용자는 서비스를 Rust 로 재작성할 필요가 없습니다. 바인딩은 정상적인 통합에 필요한 변환 및 인코딩 타입을 노출합니다.

최소 V4.1 대화 렌더링

공식 예시를 기반으로 작은 스크립트를 작성하세요:

from deepseek_recipe import (
    ChatCompletionRequest,
    ConversionOptions,
    DeepseekV41Encoding,
)

request = ChatCompletionRequest({
    "model": "deepseek-flash",
    "messages": [
        {"role": "system", "content": "Answer with one short paragraph."},
        {"role": "user", "content": "Explain sparse attention to a Python developer."},
    ],
    "temperature": 0.2,
})

converted = request.convert(ConversionOptions())
encoding = DeepseekV41Encoding()
rendered = encoding.render_conversation(converted.conversation)

print(rendered.prompt)

여기에는 두 가지 의도적인 단계가 있습니다. request.convert(...) 는 Chat Completions 페이로드를 라이브러리의 공유 Conversation 표현으로 매핑합니다. render_conversation(...) 는 V4.1 프롬프트 인코딩을 적용합니다. 이 둘을 분리하면 API 서비스가 모델 특정 토큰 레이아웃을 결정하기 전에 다양한 외부 프로토콜을 정규화할 수 있습니다.

요청의 모델 문자열은 클라이언트 facing 페이로드의 일부입니다. 선택된 인코딩 객체는 정규화된 대화가 어떻게 렌더링되는지를 제어합니다. 임의의 모델 이름이 자동으로 가중치를 다운로드하거나 선택한다고 추론하지 마세요. 주변 서비스는 요청된 모델을 검증하고 프롬프트를 적절한 백엔드로 라우팅해야 합니다.

Try DeepSeek on MidassAI

추론 연결 전 검사

프롬프트는 로컬 개발 환경에서만 출력하고 사용자 데이터가 포함된 프로덕션 로그에는 절대 출력하지 마세요. 시스템 및 사용자 메시지가 의도된 순서대로 표현되는지 확인하세요. 유니코드, 빈 콘텐츠 및 멀티라인 예시를 추가하세요. 서비스가 이미지나 도구를 지원한다면 텍스트 전용 경우가 호환성을 증명한다고 가정하지 말고 각각에 대한 별도 픽스처를 작성하세요.

이 단계는 골든 테스트 (golden tests) 를 수행하기에도 적합합니다. 민감하지 않은 작은 입력 페이로드 세트와 승인된 구조적 기대치를 저장하세요. 정확한 인코딩 출력은 패키지 버전 간에 합법적으로 변경될 수 있으므로, 버전 업그레이드가 스냅샷을 업데이트해야 하는지 아니면 검토될 때까지 실패해야 하는지 결정하세요.

최소한 다음을 테스트하세요:

시스템 메시지 하나와 사용자 메시지 하나;
어시스턴트 응답이 있는 멀티턴 대화;
사고 모드 (thinking mode) 및 노출하는 각 지원되는 추론 노력 (reasoning-effort) 값;
허용된 경계에서의 temperature, top_p 및 출력 토큰 제한;
인수가 있는 클라이언트 함수 도구;
잘못된 역할, 콘텐츠 타입 및 지원되지 않는 옵션.

마지막 그룹은 중요합니다. 프로토콜 호환성은 거부 호환성이기도 하기 때문입니다. 지원되지 않는 필드를 조용히 삭제하는 서비스는 정확한 오류를 반환하는 서비스보다 디버깅이 어렵습니다.

라이브러리 변환 가능 범위

현재 범위는 스트리밍 및 완전한 응답을 포함하여 Messages, Chat Completions 및 Responses 스타일 요청을 다룹니다. 공유 표현은 텍스트, 이미지, 사고 (thinking) 및 클라이언트 도구 호출을 지원합니다. 출력 파싱은 사고 콘텐츠, 도구 호출, JSON 객체 및 정지 시퀀스를 다룹니다.

Responses 요청의 경우, 도구 네임스페이스와 apply_patch 사용자 정의 도구가 지원됩니다. 이는 라이브러리가 패치를 적용한다는 뜻은 아닙니다. 도구 호출을 표현하고 파싱할 뿐이며, 호스트 애플리케이션은 도구의 존재 여부를 결정하고 권한을 요청하며 실행한 후 결과를 모델에 반환합니다.

V4.1 이미지 전처리는 이미지 컴포넌트와 OpenCV 를 통해 이용 가능합니다. 이미지는 base64 데이터나 외부 URL 로 도착할 수 있습니다. 프로덕션 서비스는 원격 콘텐츠를 전처리 코드에 전달하기 전에 크기 제한, 미디어 타입 검사, 다운로드 타임아웃 및 네트워크 제한을 설정해야 합니다.

지원되지 않는 필드 명시적 처리

확인된 릴리스 기준, logprobs 및 top_logprobs 는 지원되지 않습니다. 문서 콘텐츠, 오디오 또는 비디오, file_id 를 통한 파일 검색, n > 1 을 통한 여러 완성, 또는 암호화된 사고 콘텐츠도 지원되지 않습니다.

구조화된 출력 기대치는 주의가 필요합니다. 라이브러리는 JSON 객체 출력을 파싱할 수 있지만 JSON Schema, 정규식 또는 엄격한 도구 정의를 강제하지는 않습니다. API 가 이러한 보장을 광고한다면 검증은 다른 곳에서 이루어져야 합니다. 파싱된 JSON 객체는 여전히 호출자의 스키마를 위반할 수 있습니다.

대화 저장 또한 패키지 범위를 벗어납니다. previous_response_id 는 이전 컨텍스트를 검색하지 않습니다. HTTP 서비스는 저장된 대화 상태를 해결하고 결과 메시지를 변환에 전달하거나 해당 필드를 명확히 거부해야 합니다.

web_search 와 같은 서버 도구는 레시피 계층이 도구를 실행하지 않으므로 지원되지 않습니다. 클라이언트가 그러한 요청을 보내면 의미적 차이를 문서화하지 않고 클라이언트 함수 호출로 변환하지 마세요.

책임 경계 없이 API 서비스에 통합

깔끔한 서비스 파이프라인에는 네 가지 경계가 있습니다:

인증, 속도 제한, 본문 크기 제한 및 공개 API 검증.
deepseek-recipe 정규화 및 V4/V4.1 인코딩.
토큰을 소비하고 생성된 토큰을 생산하는 추론 백엔드.
레시피 파싱, 애플리케이션 소유 도구 오케스트레이션 및 HTTP 스트리밍.

각 경계 주변에서 지표를 유지하세요. 요청 변환 시간, 첫 번째 생성 토큰까지의 시간, 도구 대기 시간 및 응답 직렬화 시간은 서로 다른 운영 질문에 답합니다. 이들을 하나의 지연 시간 숫자로 결합하면 회귀 (regression) 를 locating 하기 어렵습니다.

렌더링된 프롬프트를 기본적으로 로그나 추적 시스템에 통과시키지 마세요. 메시지 수, 콘텐츠 타입, 인코딩 버전, 토큰 수 및 변환 오류와 같은 안전한 메타데이터를 기록하세요. 샘플링된 페이로드 로깅이 불가피하다면 옵트인 (opt-in),redacted, 접근 제어 및 단기 보관으로 설정하세요.

이 튜토리얼이 적합하지 않은 경우

추론 서비스를 구축하거나 적응할 때 DeepSeek 특정 프로토콜 변환이 필요하다면 deepseek-recipe 를 사용하세요. 기존 DeepSeek 호환 엔드포인트를 호출하기만 한다면 해당 서비스의 클라이언트 SDK 또는 HTTP API 를 사용하세요. 애플리케이션 클라이언트에 프롬프트 인코더를 추가하면 서버 동작이 중복되고 업그레이드가 어려워질 수 있습니다.

이 패키지는 올인원 서버가 아니기 때문에 가장 가치가 있습니다. 인프라 팀에게 배포, 스케줄링, 보안 및 도구를 통제하에 둔 채 공유 가능한 테스트 가능한 변환 계층을 제공합니다. 성공적인 첫 통합은 전체 서빙 스택이 완료되었다는 주장이 아니라 검증된 프롬프트와 지원되지 않는 필드 목록으로 끝납니다.

출처 확인: deepseek-recipe 공식 저장소, 2026 년 9 월 14 일 액세스.

Python 으로 DeepSeek V4.1 API 요청 변환하기