deepseek-recipe로 다중 형식 AI 요청을 DeepSeek V4.1 프롬프트로 변환하기

deepseek-recipe란?

deepseek-recipe는 API 서비스를 DeepSeek 추론 백엔드에 연결하기 위한 Rust 라이브러리와 Python 바인딩 모음입니다. 지원되는 API 형식의 요청을 공통 Conversation 표현으로 변환하고, 이러한 대화를 DeepSeek V4 또는 V4.1 프롬프트로 렌더링하며, 모델 출력을 해당 응답 형식으로 다시 변환합니다.

이 프로젝트는 완전한 추론 서버가 아니라 프로토콜 및 프롬프트 처리 계층입니다. 모델 추론, HTTP 전송, 도구 실행은 별도로 제공해야 합니다.

처리 파이프라인 작동 방식

1. Messages, Chat Completions 또는 Responses 형식으로 요청을 받습니다.
2. 요청을 라이브러리의 공통 Conversation 형식으로 변환합니다.
3. 대화를 DeepSeek V4 또는 V4.1 프롬프트로 렌더링하거나 토큰 ID로 인코딩합니다.
4. 프롬프트 또는 토큰 ID를 외부 추론 백엔드로 전송합니다.
5. 지원되는 사고 내용, 도구 호출, JSON 객체, 중지 시퀀스를 포함하여 생성된 출력을 파싱합니다.
6. 클라이언트가 기대하는 형식으로 완전한 응답 또는 스트리밍 응답을 반환합니다.

deepseek-recipe는 모델을 실행하거나, 도구를 실행하거나, 자체적으로 HTTP 서비스를 제공하지 않습니다. 통합 참고 자료로 사용할 수 있는 Rust 및 Python 서버 예제가 저장소에 포함되어 있습니다.

주요 기능

• 통합 프로토콜 변환: Messages, Chat Completions, Responses 요청과 응답을 처리합니다.
• DeepSeek 프롬프트 인코딩: DeepSeek V4 및 V4.1 대화를 프롬프트 또는 토큰 ID로 렌더링합니다.
• 스트리밍 및 완전한 응답: 두 응답 형식의 변환을 지원합니다.
• 생성 설정: 사고 모드, 추론 수준, temperature, top_p, 출력 토큰 제한을 전달합니다.
• 출력 파싱: 사고 내용, 클라이언트 도구 호출, JSON 객체 출력, 중지 시퀀스를 인식합니다.
• 멀티모달 입력: base64 데이터 또는 외부 URL로 제공되는 이미지를 허용합니다. 이미지 패키지는 OpenCV를 사용한 DeepSeek V4.1 전처리를 제공합니다.
• 도구 정의: 함수 도구를 지원합니다. Responses API는 도구 네임스페이스와 apply_patch 사용자 지정 도구도 지원합니다.

Python 설치 및 설정

요구 사항

Python 바인딩을 사용하려면 Python 3.10 이상이 필요합니다. pip로 게시된 패키지를 설치합니다.

python3 -m pip install deepseek-recipe

설치된 모듈은 deepseek_recipe로 가져옵니다.

Chat Completions 요청 변환

다음 예제는 Chat Completions 요청을 구성하고, 이를 공통 Conversation 표현으로 변환한 다음, 해당 대화를 DeepSeek V4.1 프롬프트로 렌더링합니다.

from deepseek_recipe import (
    ChatCompletionRequest,
    ConversionOptions,
    DeepseekV41Encoding,
)

request = ChatCompletionRequest({
    "model": "deepseek-flash",
    "messages": [
        {"role": "user", "content": "Hello"}
    ],
})

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

print(rendered.prompt)

각 단계 이해하기

1. ChatCompletionRequest는 들어오는 Chat Completions 데이터를 읽습니다.
2. request.convert(ConversionOptions())는 요청을 Conversation으로 정규화합니다.
3. DeepseekV41Encoding()은 DeepSeek V4.1 인코딩 규칙을 선택합니다.
4. render_conversation은 모델에 사용할 표현을 생성합니다.
5. rendered.prompt에는 외부 추론 백엔드로 보낼 프롬프트가 들어 있습니다.

추론이 완료되면 프로젝트의 응답 변환 및 출력 파싱 구성 요소를 사용하여 생성된 모델 출력을 클라이언트에 필요한 API 형식으로 변환합니다. 구체적인 통합 방식은 백엔드가 완전한 출력을 반환하는지, 생성된 데이터를 스트리밍하는지에 따라 달라집니다.

Rust 설치 및 설정

크레이트 추가

Rust 프로젝트에 프로토콜 변환 및 인코딩 크레이트를 추가합니다.

cargo add deepseek-recipe@0.1 deepseek-recipe-encoding@0.1

소스에서 빌드하거나 이미지 처리를 활성화하려면 빌드 지침과 이미지 종속 항목에 관한 저장소의 개발 가이드를 참조하세요.

DeepSeek V4.1 프롬프트 렌더링

use deepseek_recipe::openai::ChatCompletionRequest;
use deepseek_recipe::request::{ConversionOptions, ProtocolRequest};
use deepseek_recipe_encoding::PromptEncoding;
use deepseek_recipe_encoding::v4::dsv41::DeepseekV41Encoding;
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let request: ChatCompletionRequest = serde_json::from_value(json!({
        "model": "deepseek-flash",
        "messages": [
            {"role": "user", "content": "Hello"}
        ],
    }))?;

    let converted = request.convert(ConversionOptions::default())?;
    let rendered = DeepseekV41Encoding::new()
        .render_conversation(&converted.conversation);

    println!("{}", rendered.prompt);
    Ok(())
}

여기서 Serde는 JSON을 ChatCompletionRequest로 역직렬화합니다. ProtocolRequest 트레이트는 요청 변환을 제공하고, PromptEncoding은 대화 렌더링을 제공합니다. 그런 다음 결과 프롬프트를 별도로 관리되는 추론 엔진에 전달할 수 있습니다.

인코딩 및 디코딩 데모 살펴보기

저장소에는 프롬프트를 렌더링하고, 특수 토큰을 검사하며, 완전한 모델 출력을 Chat Completions, Responses 또는 Messages 형식으로 디코딩할 수 있는 웹 인터페이스가 포함되어 있습니다.

저장소 루트에서 다음을 실행합니다.

From the repository root, run:

cargo run -p encoding-decoding-demo --locked

그런 다음 브라우저에서 http://127.0.0.1:7778을 여세요.

이 데모는 라이브러리를 서버에 통합하기 전에 프롬프트 구조를 확인하고 생성된 출력이 지원되는 API 응답 형식에 어떻게 매핑되는지 이해하는 데 유용합니다.

패키지 개요

• deepseek-recipe: 프로토콜 변환 및 모델 출력 파싱.
• deepseek-recipe-core: 대화, 메시지, 이미지 및 도구를 위한 공통 타입.
• deepseek-recipe-encoding: DeepSeek V4 및 V4.1 프롬프트 렌더링과 토큰 인코딩.
• deepseek-recipe-image: 이미지 가져오기 및 전처리.
• deepseek-recipe-python: deepseek_recipe 가져오기를 통해 제공되는 Python 바인딩.
• encoding-decoding-demo: 브라우저 기반 프롬프트 및 출력 검사.
• server-rs: 모의 추론을 사용하는 Axum API 예제.
• server-py: 모의 추론을 사용하는 FastAPI 예제.

고급 통합 팁

프로토콜 처리와 추론을 분리하세요

애플리케이션의 경계에서 deepseek-recipe를 사용하세요. 추론 전에 들어오는 요청을 변환하고, 이후에 생성된 출력을 파싱하세요. 모델 로딩, 배치 처리, 스케줄링 및 하드웨어 관리는 추론 백엔드 내부에서 처리하세요.

프롬프트 또는 토큰 ID를 신중하게 선택하세요

대화를 텍스트 프롬프트로 렌더링하거나 토큰 ID로 인코딩할 수 있습니다. 백엔드가 형식이 지정된 텍스트를 허용하면 프롬프트 렌더링을 사용하세요. 백엔드가 토크나이저 ID를 직접 사용하면 토큰 인코딩을 사용하세요. 저장소의 토크나이저 가이드에서는 대화를 인코딩하고 백엔드 토큰 ID를 디코딩하는 방법을 설명합니다.

스트리밍을 처음부터 끝까지 제공되는 기능으로 계획하세요

Rust와 Python 모두 모델 출력을 스트리밍 응답으로 변환할 수 있습니다. 전송 계층과 추론 백엔드도 데이터를 스트리밍해야 하며, 이 라이브러리는 해당 계층을 제공하지 않습니다. 증분 모델 출력을 클라이언트용 API에 연결할 때는 스트리밍 응답 가이드를 따르세요.

추론 전에 이미지를 처리하세요

요청은 base64 콘텐츠 또는 외부 URL을 통해 이미지를 참조할 수 있습니다. 전용 이미지 컴포넌트는 OpenCV를 사용한 가져오기와 DeepSeek V4.1 전처리를 지원합니다. 소스에서 빌드할 때 필요한 이미지 의존성이 설치되어 있는지 확인하세요.

도구 실행은 라이브러리 외부에서 처리하세요

이 프로젝트는 도구 정의를 표현하고 클라이언트의 도구 호출을 파싱할 수 있지만, 해당 도구를 실행하지는 않습니다. 애플리케이션에서 각 호출을 검증하고, 적절한 함수 또는 사용자 지정 도구를 실행한 다음, 그 결과를 다음 대화 차례에 추가해야 합니다.

현재 지원 범위를 준수하세요

이 프로젝트를 기반으로 API를 설계하기 전에 아직 지원되지 않는 기능을 고려하세요:

• logprobs 또는 top_logprobs를 통한 토큰 확률.
• 문서 콘텐츠, 오디오 또는 비디오 입력, file_id를 통한 검색.
• web_search와 같은 서버 실행 도구.
• JSON Schema 및 정규 표현식 출력 제약 조건.
• 도구의 strict 설정 적용.
• n > 1일 때 여러 Chat Completions 선택지.
• apply_patch 이외의 Responses 사용자 지정 도구 정의.
• Responses 대화 저장 또는 previous_response_id를 통한 컨텍스트 검색.
• encrypted_content를 통한 암호화된 사고 콘텐츠.

결론

deepseek-recipe는 여러 API 프로토콜을 정규화하고, DeepSeek V4 및 V4.1 입력을 생성하며, 생성된 출력을 클라이언트용 응답으로 다시 변환하는 재사용 가능한 Rust 및 Python 컴포넌트를 제공합니다. 기본 요청 변환 예제로 시작하고, 데모를 통해 동작을 확인한 다음, 변환 파이프라인을 자체 추론, 전송 및 도구 실행 인프라에 연결하세요.

프로젝트 코드와 공개 문서는 MIT 라이선스에 따라 제공됩니다.