OpenAI SDK로 Yeap LLM API 시작하기

Yeap LLM API는 OpenAI와 호환되는 모델 게이트웨이입니다. 목표는 간단합니다. 새 SDK를 배우거나 코드를 다시 작성할 필요 없이 사용하는 것입니다. 기존 OpenAI SDK를 유지한 채 base_url을 https://llm.yeap.cloud/v1로 변경하고 Yeap API 키를 사용하면 바로 시작할 수 있습니다. 사용 요금은 토큰 단위로 Yeap 계정 잔액에서 차감되며, 다른 Yeap 제품과 동일한 잔액을 사용합니다.

사용 가능한 엔드포인트

모든 엔드포인트는 Authorization: Bearer <key>로 인증합니다. 모델과 가격은 시간이 지나면서 바뀌며, 항상 GET /v1/models 또는 콘솔의 모델 목록이 기준입니다. 따라서 아래 예제에서는 특정 모델 이름 대신 자리표시자를 사용합니다.

1단계: API 키 생성

console.yeap.cloud에서 로그인한 뒤 LLM → 토큰으로 이동하여 키를 생성합니다. 다음 항목을 설정할 수 있습니다.

• 이름: blog-summarizer-prod처럼 프로젝트나 환경을 기준으로 이름을 지정하는 것을 권장합니다.
• 할당량: 이 키의 지출 한도를 설정하거나 무제한으로 지정합니다.
• 모델 제한: 특정 모델만 사용하도록 키를 제한합니다.
• IP 제한: 특정 IP에서 보낸 요청만 허용합니다.
• 만료 시점: 이 시점이 지나면 키가 자동으로 작동을 중지합니다.

키는 sk-로 시작합니다. 생성한 즉시 안전하게 저장합니다. 프로젝트별, 환경별로 별도의 키를 사용하고 비프로덕션 키에는 낮은 할당량을 설정하여 키 유출 시 피해 범위를 제한합니다.

키는 저장소에 넣지 않고 환경 변수에 보관합니다.

export YEAP_API_KEY="sk-..."

2단계: curl로 연결 확인

curl https://llm.yeap.cloud/v1/models \
  -H "Authorization: Bearer $YEAP_API_KEY"

JSON 응답에서 각 항목의 id는 요청에 사용할 수 있는 모델 이름이며, 이 항목들은 data 배열에 포함되어 있습니다.

3단계: Python

pip install openai로 공식 SDK를 설치합니다.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["YEAP_API_KEY"],
    base_url="https://llm.yeap.cloud/v1",
)

resp = client.chat.completions.create(
    model="your-model-id",  # pick one from /v1/models
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain what a CDN is in one sentence."},
    ],
)

print(resp.choices[0].message.content)
print(resp.usage)  # prompt_tokens / completion_tokens / total_tokens

스트리밍

채팅 애플리케이션에서는 대개 출력이 생성되는 즉시 표시해야 합니다. stream=True를 설정하면 응답이 서버 전송 이벤트(SSE) 형식으로 점진적으로 도착합니다.

stream = client.chat.completions.create(
    model="your-model-id",
    messages=[{"role": "user", "content": "Write a short poem about cache hits."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

임베딩

emb = client.embeddings.create(
    model="your-embedding-model-id",
    input=["Yeap CDN supports HTTP/3", "How to purge the cache"],
)
vectors = [item.embedding for item in emb.data]
print(len(vectors), len(vectors[0]))

이미지 생성 및 음성 전사

이미지 및 오디오 엔드포인트도 SDK의 표준 메서드를 사용합니다. 해당 유형에 맞는 모델을 지정하면 됩니다.

# Image generation
img = client.images.generate(
    model="your-image-model-id",
    prompt="A minimalist illustration of a server room",
    size="1024x1024",
)
print(img.data[0].url or "base64 image returned")

# Speech to text
with open("meeting.mp3", "rb") as f:
    tr = client.audio.transcriptions.create(
        model="your-transcription-model-id",
        file=f,
    )
print(tr.text)

모델에 따라 이미지가 URL 또는 base64로 반환될 수 있으므로 코드에서 두 가지 형식을 모두 처리하는 것이 좋습니다.

비용을 예측 가능하게 유지하는 습관

• max_tokens를 설정합니다. 출력 토큰은 일반적으로 입력 토큰보다 비용이 높습니다. 요청 유형마다 적절한 출력 한도를 지정하면 모델이 계속 응답을 생성해 예상치 못한 요금이 발생하는 일을 방지할 수 있습니다.
• 컨텍스트를 줄입니다. 여러 차례 주고받는 대화에서는 매번 전체 이력을 다시 전송합니다. 오래된 대화를 요약하거나 잘라내면 입력 토큰을 크게 줄일 수 있습니다.
• 작업에 맞는 모델을 선택합니다. 분류, 추출, 문장 재작성은 작은 모델로도 충분한 경우가 많습니다. 큰 모델은 추론이 꼭 필요한 작업에 사용합니다. 기본 모델을 정하기 전에 Playground에서 몇 가지 모델을 비교합니다.
• 키 할당량을 최종 안전장치로 사용합니다. 버그로 인해 코드가 API를 반복 호출하더라도 키의 할당량이 지출의 무제한 증가를 막아줍니다.

4단계: Node.js

npm install openai로 설치합니다.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.YEAP_API_KEY,
  baseURL: "https://llm.yeap.cloud/v1",
});

const stream = await client.chat.completions.create({
  model: "your-model-id",
  messages: [{ role: "user", content: "List three ways to reduce API latency." }],
  stream: true,
});

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

코드 변경 없이 전환하기

공식 OpenAI SDK는 OPENAI_BASE_URL 및 OPENAI_API_KEY 환경 변수를 읽습니다. 도구나 스크립트가 이미 OpenAI SDK를 사용하고 있으며 코드를 수정하고 싶지 않다면 환경 설정만 변경합니다.

export OPENAI_BASE_URL="https://llm.yeap.cloud/v1"
export OPENAI_API_KEY="$YEAP_API_KEY"

사용자 지정 API 엔드포인트를 지원하는 대부분의 서드파티 도구에서도 같은 방법을 사용할 수 있습니다. 엔드포인트를 https://llm.yeap.cloud/v1로 지정하고 키에는 Yeap 키를 설정합니다.

오류 및 재시도

프로덕션 환경에서는 오류에 대비합니다.

• 401: 키가 유효하지 않거나 만료되었거나, 키의 IP 허용 목록에 없는 주소에서 요청을 보낸 경우입니다. 키 설정을 확인합니다.
• 할당량 부족: 키의 할당량을 소진했거나 계정 잔액이 부족하면 요청이 거부되며, 오류 메시지에 이유가 표시됩니다. 콘솔에서 키의 할당량을 늘리거나 잔액을 충전합니다.
• 429 및 5xx: 일반적으로 일시적인 오류이므로 대기 시간을 늘려가며 재시도해야 합니다. OpenAI SDK는 자동으로 재시도합니다. max_retries로 재시도 횟수를, timeout으로 요청별 제한 시간을 조정합니다.

client = OpenAI(
    api_key=os.environ["YEAP_API_KEY"],
    base_url="https://llm.yeap.cloud/v1",
    max_retries=3,
    timeout=60.0,
)

사용량 모니터링

모든 요청에는 모델, 토큰 수, 비용이 함께 기록됩니다. 콘솔의 LLM 메뉴에서 요청 로그와 통계를 살펴보고 키별 지출을 확인할 수 있으므로 프로젝트별로 쉽게 구분할 수 있습니다. 코드를 작성하기 전에 모델을 비교하려면 브라우저에서 콘솔의 Playground를 바로 사용해 보시기 바랍니다.

정리

Yeap LLM API를 시작하는 데 필요한 것은 키, base_url, /v1/models에서 확인한 모델 이름의 세 가지입니다. 나머지 코드는 이미 작성해 둔 코드를 그대로 사용하면 됩니다.