OpenAI 호환 API로 DeepSeek 사용하기

By TokuseTokuse
AIAPIDeepSeek튜토리얼

DeepSeek는 이미 OpenAI 스타일 엔드포인트를 제공합니다. 실무적인 질문은 베이스 URL을 어디에 둘지, 모델 이름을 어떻게 처리할지, 프로덕션 트래픽을 옮기기 전에 무엇을 테스트할지입니다.

Tokuse 사용해 보기: 무료 계정 만들기 후 하나의 OpenAI 호환 엔드포인트로 첫 요청을 보내세요.

이 가이드에서는 Tokuse를 게이트웨이 예시로 사용합니다. 공개 모델 카탈로그에 deepseek-flash와 deepseek-v4-pro가 있고, 다음 OpenAI 호환 API를 제공하기 때문입니다.

https://tokuse.com/v1

계정에 표시되는 모델 구성, 할당량, 가격은 달라질 수 있습니다. 배포 전에 현재 카탈로그를 확인하세요.

OpenAI 호환이란 무엇인가

호환이란 기존 OpenAI SDK에서 베이스 URL과 모델 이름만 바꾸면 대개 요청을 보낼 수 있다는 뜻입니다. 애플리케이션은 익숙한 클라이언트 구조를 그대로 유지할 수 있습니다.

SDK -> OpenAI-compatible base URL -> model alias -> provider

게이트웨이가 요청을 받아 모델을 해석하고 공급자 자격 증명을 붙인 뒤 정규화된 응답을 반환합니다. 덕분에 공급자 변경이 제품 코드 밖에 머뭅니다.

호환이라고 해서 공급자별 파라미터가 모두 똑같이 동작하는 것은 아닙니다. 사용할 SDK와 모델 그대로 스트리밍, 도구 호출, JSON 출력, 오류 코드, 토큰 집계를 테스트하세요.

Python 설정

OpenAI SDK를 설치합니다.

pip install openai

서버에 Tokuse 키를 설정합니다.

export TOKUSE_API_KEY="YOUR_KEY"

그다음 일반적인 chat completions 인터페이스를 사용합니다.

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKUSE_API_KEY"],
    base_url="https://tokuse.com/v1",
)

response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {
            "role": "system",
            "content": "Return a compact JSON object. Do not add commentary.",
        },
        {
            "role": "user",
            "content": "Extract the company name and plan from: Acme Pro, billed monthly.",
        },
    ],
    response_format={"type": "json_object"},
    max_tokens=200,
)

print(response.choices[0].message.content)

베이스 URL에 /chat/completions를 붙이지 마세요. 엔드포인트 경로는 SDK가 알아서 추가합니다.

Node.js 설정

npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOKUSE_API_KEY,
  baseURL: "https://tokuse.com/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-flash",
  messages: [
    {
      role: "user",
      content: "Summarize this support ticket in one sentence.",
    },
  ],
  max_tokens: 120,
});

console.log(response.choices[0].message.content);

키는 서버 측 환경 변수에 보관하세요. 브라우저 번들, 모바일 앱, 빌드 로그에 노출하지 마세요.

작업에 따라 모델 선택하기

일상적인 추출, 분류, 요약, 대량 워크플로 단계에는 먼저 deepseek-flash를 사용하세요. 복잡한 추론이나 장기 작업에서 저렴한 경로가 평가를 통과하지 못하면 deepseek-v4-pro를 테스트하세요.

라우팅 결정은 모델의 명성이 아니라 작업 성공을 기준으로 해야 합니다. 품질, 출력 길이, 지연 시간, 재시도, 성공한 작업당 비용을 비교하세요.

DeepSeek의 캐시 적중 가격은 안정적인 프롬프트를 특히 중요하게 만듭니다. 공식 오프피크 요율은 캐시 적중 $0.003/M, 캐시 미스 $0.15/M입니다. Tokuse의 현재 기본 deepseek-flash 요율은 입력 $0.274/M, 출력 $1.096/M이며 캐시 적중은 약 $0.006/M입니다. 예산을 정하기 전에 DeepSeek 가격 및 캐시 모델을 확인하세요.

다음 장애 유형을 테스트하세요

401 또는 잘못된 토큰

키가 게이트웨이 계정의 키인지, 실수로 공백이 들어가지는 않았는지 확인하세요. 커밋되거나 로그에 남은 적이 있다면 키를 교체하세요.

chat completions 404

베이스 URL과 SDK 경로를 모두 확인하세요. https://tokuse.com/v1이 베이스 URL입니다. HTTP 클라이언트가 완전한 엔드포인트를 기대하지 않는 한 SDK의 /chat/completions 경로를 덧붙이지 마세요.

지원되지 않는 모델

현재 모델 카탈로그나 대시보드를 조회하세요. 모델 별칭은 계정과 제공 여부에 따라 달라질 수 있습니다. 파일럿에서 작동하던 모델이 나중에 비활성화될 수 있습니다.

429 또는 할당량 오류

지터를 넣은 상한 있는 지수 백오프를 추가하세요. 무한정 재시도하지 마세요. 분당 요율 제한과 계정 잔액 또는 할당량 오류를 구분하세요.

잘린 출력

finish_reason, 출력 토큰 한도, 요청한 스키마를 확인하세요. 한도를 늘리면 결과는 그대로인데 비용만 늘 수 있습니다. 둘 다 측정하세요.

스트리밍 실패

첫 토큰 지연 시간과 실패 지점을 기록하세요. 토큰이 이미 사용자에게 도달한 뒤 투명하게 재시도하면 텍스트가 중복될 수 있습니다. 사용자에게 보이는 오류나 통제된 이어쓰기를 선호하세요.

프로덕션 체크리스트

  • 개발용과 프로덕션용 키를 분리한다.
  • 공급자나 게이트웨이 키를 클라이언트 코드에 넣지 않는다.
  • 요청 ID, 모델, 상태, 지연 시간, 입력 토큰, 출력 토큰, 재시도 횟수를 기록한다.
  • 기본 로그에서 프롬프트, 응답, 인증 헤더를 가린다.
  • 모델 별칭을 고정하고 롤아웃 전에 변경 사항을 테스트한다.
  • 타임아웃, 재시도 예산, 킬 스위치를 둔다.
  • 요청당 비용이 아니라 성공한 작업당 비용을 비교한다.
  • 적은 비율의 트래픽부터 시작하고 고정된 평가 세트로 품질을 측정한다.

하나의 엔드포인트에서 시작하기

Tokuse는 여러 AI 모델을 평가하는 팀을 위해 OpenAI 호환 엔드포인트 하나, 모델 카탈로그, 사용량 관리, 관리자 대시보드를 제공합니다. 먼저 현재 카탈로그와 테스트 키로 시작하고, 위험도가 낮은 워크로드 하나를 게이트웨이로 옮긴 뒤 확장하세요.

Tokuse 계정을 만들고 현재 모델 확인하기

관련 비용 및 마이그레이션 가이드

출처