개발자를 위한 LLM API: 완전 통합 가이드

이 가이드는 개발자가 LLM API를 프로덕션 애플리케이션에 통합하는 데 필요한 모든 것을 다룹니다: 인증, 스트리밍, 도구 사용, 임베딩, RAG 패턴, 비용 관리. 모든 예제는 OpenAI 호환 형식을 사용하며 APIMaster.ai에서 작동합니다.

설정

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_APIMASTER_KEY",
    base_url="https://apimaster.ai/v1",
)

핵심 패턴

1. 기본 채팅 완성

def ask(prompt: str, model: str = "claude-sonnet-4-6") -> str:
    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
    )
    return response.choices[0].message.content

2. 시스템 프롬프트 + 대화

class Conversation:
    def __init__(self, system: str, model: str = "claude-sonnet-4-6"):
        self.model = model
        self.messages = [{"role": "system", "content": system}]
    
    def send(self, user_msg: str) -> str:
        self.messages.append({"role": "user", "content": user_msg})
        resp = client.chat.completions.create(
            model=self.model,
            messages=self.messages,
        )
        reply = resp.choices[0].message.content
        self.messages.append({"role": "assistant", "content": reply})
        return reply

bot = Conversation("당신은 전문 Python 개발자입니다.")
print(bot.send("GIL이 무엇인가요?"))
print(bot.send("어떻게 우회할 수 있나요?"))

3. 스트리밍

def stream(prompt: str, model: str = "gpt-5.4"):
    with client.chat.completions.stream(
        model=model,
        messages=[{"role": "user", "content": prompt}],
    ) as s:
        for text in s.text_stream:
            yield text

for chunk in stream("Python에서 async/await 설명"):
    print(chunk, end="", flush=True)

4. 구조화된 출력

from pydantic import BaseModel
from typing import List

class ExtractedData(BaseModel):
    entities: List[str]
    sentiment: str
    summary: str

import json

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": f"데이터를 추출하고 다음 스키마와 일치하는 JSON을 반환하세요: {ExtractedData.schema()}"},
        {"role": "user", "content": "Apple이 기록적인 매출을 보고했습니다. CEO Tim Cook은 이를 예외적이라고 평가했습니다."},
    ],
    response_format={"type": "json_object"},
)

data = ExtractedData(**json.loads(response.choices[0].message.content))
print(data.entities)    # ["Apple", "Tim Cook"]
print(data.sentiment)   # "positive"

5. 도구 사용 / 함수 호출

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "execute_sql",
            "description": "읽기 전용 SQL 쿼리 실행",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "database": {"type": "string", "enum": ["users", "orders", "products"]},
                },
                "required": ["query", "database"],
            },
        },
    }
]

def handle_tool_call(tool_name: str, args: dict) -> str:
    # 구현 내용
    return json.dumps({"result": "모의 데이터"})

def agent_loop(user_msg: str):
    messages = [{"role": "user", "content": user_msg}]
    
    while True:
        resp = client.chat.completions.create(
            model="gpt-5.4",
            messages=messages,
            tools=tools,
        )
        
        if resp.choices[0].finish_reason != "tool_calls":
            return resp.choices[0].message.content
        
        # 도구 호출 처리
        messages.append(resp.choices[0].message)
        for tc in resp.choices[0].message.tool_calls:
            result = handle_tool_call(tc.function.name, json.loads(tc.function.arguments))
            messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})

6. 임베딩

def embed(texts: list[str]) -> list[list[float]]:
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts,
    )
    return [item.embedding for item in response.data]

# 의미 유사도
import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

vecs = embed(["Python은 훌륭합니다", "저는 Python을 좋아합니다", "Java는 장황합니다"])
print(cosine_similarity(vecs[0], vecs[1]))  # 높음: ~0.95
print(cosine_similarity(vecs[0], vecs[2]))  # 낮음: ~0.70

7. RAG (검색 증강 생성)

from typing import List

def rag_query(user_question: str, knowledge_base: List[str]) -> str:
    # 1단계: 질문 임베딩
    q_embedding = embed([user_question])[0]
    doc_embeddings = embed(knowledge_base)
    
    # 2단계: 가장 관련성 높은 문서 찾기
    similarities = [cosine_similarity(q_embedding, d) for d in doc_embeddings]
    top_indices = sorted(range(len(similarities)), key=lambda i: similarities[i], reverse=True)[:3]
    context = "\n\n".join(knowledge_base[i] for i in top_indices)
    
    # 3단계: 컨텍스트를 사용하여 답변 생성
    response = client.chat.completions.create(
        model="claude-sonnet-4-6",
        messages=[
            {"role": "system", "content": f"다음 컨텍스트만 사용하여 답변하세요:\n\n{context}"},
            {"role": "user", "content": user_question},
        ],
    )
    return response.choices[0].message.content

8. 높은 처리량을 위한 비동기

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI(
    api_key="YOUR_APIMASTER_KEY",
    base_url="https://apimaster.ai/v1",
)

async def process_batch(prompts: list[str]) -> list[str]:
    tasks = [
        async_client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": p}],
            max_tokens=100,
        )
        for p in prompts
    ]
    responses = await asyncio.gather(*tasks)
    return [r.choices[0].message.content for r in responses]

# 50개 프롬프트 동시 처리
results = asyncio.run(process_batch(my_prompts))

프로덕션 체크리스트

• API 키는 소스 코드가 아닌 환경 변수에 저장
• 429/500 오류에 대한 지수 백오프 재시도 로직
• 비용 폭주 방지를 위한 max_tokens 설정
• 2초 이상 걸리는 사용자 응답에 스트리밍 사용
• 비용 추적을 위한 토큰 수가 포함된 요청 로깅
• 제공자 한도 내 유지를 위한 속도 제한기

올바른 모델 선택

사용 사례	모델	비용 등급
프로토타이핑	deepseek-v4-flash 또는 gpt-4o-mini	매우 낮음
프로덕션 챗봇	claude-haiku-4-5	낮음
코드 어시스턴트	deepseek-v4-flash 또는 claude-sonnet-4-6	낮음–중간
복잡한 분석	claude-sonnet-4-6	중간
연구/추론	claude-opus-4-8 또는 o3	높음

자주 묻는 질문

LLM API란 무엇인가요? LLM API는 코드가 텍스트 프롬프트를 보내고 AI 생성 응답을 받을 수 있게 해주는 HTTP 인터페이스입니다. messages 배열을 보내면 API가 완성 결과를 반환합니다. 대부분 OpenAI Chat Completions 형식을 사용합니다.

LLM API 제공자는 어떻게 선택하나요? 모델 성능(벤치마크), 토큰당 비용, 지연 시간, 안정성을 고려하세요. 대부분의 사용 사례에서 DeepSeek V4 Flash(저비용 코딩), Claude Sonnet(글쓰기/분석), 또는 GPT-4o(멀티모달)가 일반적인 경로를 커버합니다. APIMaster를 사용하면 한 줄로 제공자를 전환할 수 있습니다.

OpenAI 호환 API란 무엇인가요? OpenAI와 동일한 /v1/chat/completions 형식을 구현하는 엔드포인트로, openai Python 라이브러리나 OpenAI 호환 도구를 비-OpenAI 모델과 함께 사용할 수 있게 해줍니다.

프로덕션에서 LLM API 오류는 어떻게 처리하나요? RateLimitError(백오프로 재시도), APIConnectionError(재시도), InvalidRequestError(프롬프트 수정)를 처리하세요. 프로덕션 안정성을 위해 타임아웃과 서킷 브레이커를 사용하세요.

여러 LLM 제공자에 하나의 API 키를 사용할 수 있나요? 네—APIMaster는 GPT, Claude, DeepSeek, Gemini를 위한 단일 키와 엔드포인트를 제공합니다. model 매개변수를 변경하여 모델을 전환하세요. 제공자별 키나 SDK가 필요 없습니다.

LLM API 액세스 → · 모델 비교 →