DeepSeek API SDK: OpenAI SDK 사용 및 엔드포인트 교체

왜 OpenAI SDK가 DeepSeek API SDK인가

DeepSeek API SDK를 검색하는 사람들은 일반적으로 벤더 이름이 붙은 패키지를 기대합니다. 실제로 DeepSeek의 자체 문서에 따르면 API는 OpenAI 요청 및 응답 형식을 따르므로 OpenAI SDK를 다른 Base URL과 함께 호출합니다. 정확한 Base URL과 모델 이름은 해당 문서에서 확인하세요. 해당 서비스의 공식 정보원입니다.

이로 인해 유용한 결과가 나옵니다. OpenAI 클라이언트 라이브러리를 대상으로 작성된 코드는 동일한 엔드포인트를 구현하는 모든 서버와 통신할 수 있습니다. 여기서는 POST /v1/chat/completions, POST /v1/responses, GET /v1/models 엔드포인트가 해당됩니다. 공급자 간 이동은 리라이팅이 아닌 구성 변경으로 처리할 수 있습니다. 이 문서의 나머지 부분에서는 Python, Node, curl에서의 패턴과 전환을 단순화하는 구조를 보여줍니다.

Python 설정

공식 패키지를 설치하고 엔드포인트를 가리키세요:

Copypip install openai

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.deepseekapi.top/v1",
    api_key="YOUR_KEY",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain idempotency in two sentences."},
    ],
)
print(resp.choices[0].message.content)
print(resp.usage)

API 키 페이지에서 키를 발급하세요. 신규 사용자는 카드 없이 한 번의 클릭으로 $0.50의 무료 체험 크레딧을 받을 수 있습니다. DeepSeek API Python 문서에서는 에러 처리를 포함한 이 언어에 대해 더 자세히 다룹니다.

Node.js 설정

Copynpm install openai

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepseekapi.top/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "List four uses of a message queue." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

패턴은 동일합니다: Base URL, 키, 모델입니다. 스트리밍은 Server-Sent Events를 반환하며 라이브러리는 이를 비동기 이터레이터로 변환합니다. 함수 호출은 다른 OpenAI 호환 API와 동일한 스키마를 따릅니다: tools를 전달하고 스트리밍된 tool_calls을 읽은 후 결과를 role: "tool" 메시지로 반환합니다.

엔드포인트를 교체 가능하게 만들기

세 가지 값을 하드코딩하지 마세요. 환경에서 읽고 클라이언트 생성을 하나의 함수로 감싸세요. 그러면 한 엔드포인트에서 다른 엔드포인트로 이동할 때 소스 코드가 아닌 .env 파일만 수정하면 됩니다.

Copyimport os
from openai import OpenAI

def make_client():
    return OpenAI(
        base_url=os.environ.get("LLM_BASE_URL", "https://api.deepseekapi.top/v1"),
        api_key=os.environ["LLM_API_KEY"],
    )

MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt: str) -> str:
    r = make_client().chat.completions.create(
        model=MODEL,
        messages=[{"role": "user", "content": prompt}],
        temperature=0.7,
    )
    return r.choices[0].message.content

이제 다른 공급자는 환경 변수 세 개만 필요로 합니다. 일부 버전의 공식 SDK는 OPENAI_API_BASE 및 OPENAI_API_KEY도 읽지만, 명시적인 변수가 더 명확하며 여러 공급자를 동시에 실행할 때 예상치 못한 문제를 피할 수 있습니다.

TypeScript나 다른 언어를 사용하는 경우 아이디어는 동일합니다: 팩토리 함수 하나, 변수 세 개, 코드베이스에 공급사 이름이 흩어져 있지 않음. 흔한 실수는 공급사 이름이 함수 이름, 로그 메시지 및 변수에 유출되게 하는 것입니다. 이는 이후 교체 작업을 필요 이상으로 어렵게 만듭니다. 공급사가 아닌 작업에 따라 이름을 지정하세요(ask, summarise).

고정된 프롬프트를 ask()로 전송하고 빈이 아닌 응답이 오는지 확인하는 작은 테스트를 유지하세요. 엔드포인트 변경 후마다 실행하면 잘못된 URL과 키를 몇 초 안에 잡을 수 있습니다.

교체 시 유지되는 부분과 변경되는 부분

마지막 행이 가장 주의해야 할 부분입니다. 엔드포인트는 프로토콜 수준에서는 호환되지만 동작 수준에서는 호환되지 않습니다. 두 공급자는 동일한 요청을 받아도 매우 다른 응답을 줄 수 있습니다. 여기의 모델은 독립적인 공급자의 단일 오픈 웨이트 모델로, 합법적인 성인 사용에 콘텐츠 거절 없이 답변하도록 튜닝되었으며 DeepSeek 또는 다른 연구소의 공식 API가 아닙니다. 다른 모델에 맞게 튜닝한 프롬프트를 다시 테스트하세요.

이 엔드포인트의 기능과 미지원 항목

• 지원: 채팅 완성 API, Responses 형식, 모델 나열, 스트리밍, 함수 호출, JSON 모드(response_format과 json_object 사용), temperature, top_p, stop, seed 및 페널티의 전달.
• 미제공: 이미지, 오디오 또는 비디오 생성, 임베딩, 파인튜닝.
• 제한 사항: 전체 키 기준 토큰 100,000개 창, 최대 본문 크기 8 MB, 동시 요청 8회, 분당 300회(시험용 키는 동시 2회, 분당 60회).
• 에러: HTTP 429, 코드 rate_limited 또는 concurrency, 일시적 과부하 시 Retry-After: 5 헤더.

코드에서 임베딩 엔드포인트를 호출하는 경우 해당 부분에 대해 다른 공급자가 필요하므로 채팅은 여기에서 유지할 수 있습니다. 작업을 기준으로 분할하는 것이 위에서 설명한 환경 변수 패턴의 일반적인 이유입니다.

마이그레이션 체크리스트

기존 프로젝트에서 한 엔드포인트를 다른 엔드포인트로 교체할 때 한 번에 모든 것을 변경하기보다 짧은 목록을 따르세요.

1. 엔드포인트를 증명하세요. curl로 요청 하나를 보내 텍스트가 반환되는지 확인하세요. GET /v1/models을 호출하고 id uncensored가 나열되어 있는지 확인하세요.
2. 세 가지 값을 변경하세요. Base URL, 키, 모델 이름만 변경합니다. 프롬프트는 아직 건드리지 마세요.
3. 기존 테스트를 실행하세요. 프롬프트 회귀 테스트가 있는 경우 실행하고 실패한 항목을 기록하세요. 실패는 일반적으로 프로토콜 오류가 아닌 다른 출력 형식과 같은 동작적 원인입니다.
4. 파라미터를 확인하세요. 엔드포인트에 필요 없는 옵션을 제거하세요. temperature, top_p, stop, seed는 사용하는 경우에만 유지하세요.
5. 스트리밍과 도구를 별도로 테스트하세요. 스트리밍 버그는 특정 청크 레이아웃을 가정하는 클라이언트 코드에 숨어 있는 경우가 많습니다. 도구 호출은 모델이 잘 따르는 스키마가 필요하므로 실제 함수로 테스트하세요.
6. 실제 트래픽에서 비용과 지연 시간을 측정하세요. 단일 프롬프트가 아닌 하루치의 요청을 비교하세요.

브랜치에서 수행하거나 피처 플래그를 사용하여 소량의 트래픽을 새 엔드포인트로 라우팅하세요. 클라이언트 코드가 공유되므로 롤백은 환경 변수 변경입니다.

재시도 처리 및 사용량 확인

SDK는 일부 실패를 기본적으로 재시도하지만, 프로덕션에서는 동시성 제한이 실제 존재하므로 429 오류를 직접 처리해야 합니다. 속도 제한 예외를 캐치하고, Retry-After의 초 수(과부하 시 5초)만큼 대기한 후 몇 번 더 재시도하세요. 실패한 요청은 요금이 청구되지 않으므로 재시도는 잔액에 안전합니다.

모든 호출에서 usage.prompt_tokens 및 usage.completion_tokens을 로깅하세요. 가격은 1M 입력 토큰당 $0.15, 1M 출력 토큰당 $0.50이므로, 입력 2,000개와 출력 600개의 호출 비용은 2,000 × $0.15 / 1M + 600 × $0.50 / 1M = $0.0003 + $0.0003 = $0.0006입니다. 응답 헤더에는 남은 크레딧에 대한 X-Balance-USD도 포함됩니다. 충전 및 보너스에 대해서는 가격 책정 페이지를, 전체 파라미터 목록은 문서를 참조하세요.

편집기 및 기타 도구

세 값은 OpenAI 호환 제공자 설정이 있는 모든 도구로 계속 적용됩니다. Cursor에서 DeepSeek 스타일 API 사용하기에 대한 기사는 이러한 편집기 중 하나의 사용 방법을 안내합니다. 각 도구에서 필드는 약간 다르게 표시되지만, 항상 /v1로 끝나는 기본 URL, 키 및 모델 이름을 입력합니다.

더 많은 가이드

• DeepSeek API 대 OpenAI API 비용: 작업 예시
• DeepSeek API 키: 무검열 LLM API 접근