로컬 LLM OpenAI API: 로컬에서 실행하고 호스팅된 엔드포인트로 전환

해당 구문의 의미

사람들은 "로컬 LLM OpenAI API"를 두 가지 관련된 용도로 사용합니다. 첫 번째는 노트북이나 홈 서버에서 직접 실행하며 로컬 포트에서 수신하고 OpenAI 채팅 형식을 사용하는 언어 모델입니다. 두 번째는 그 뒤에 있는 모델을 교체할 수 있도록 앱이 해당 형식으로 작성되는 습관입니다.

이 형식은 단순한 계약입니다. 앱은 model 이름과 시스템, 사용자, 어시스턴트 역할을 가진 messages 목록이 포함된 JSON 본문을 보냅니다. 서버는 생성된 메시지가 포함된 JSON 객체 또는 스트리밍 요청 시 작은 청크의 스트림으로 응답합니다. Python 및 JavaScript용 공식 SDK는 이를 감싸며 Base URL을 재정의할 수 있습니다. 이것이 핵심입니다.

많은 로컬 도구에서 이 계약을 노출합니다. Ollama, LM Studio, llama.cpp 서버, vLLM은 모두 OpenAI 스타일의 라우트를 제공합니다. 호스팅 서비스도 마찬가지이므로 클라이언트 코드 20줄로 둘 모두에 연결할 수 있습니다. 이 사이트의 엔드포인트는 호스팅 유형 중 하나입니다. POST /v1/chat/completions 및 GET /v1/models을 수락하며 https://api.onekeyllmapi.com/v1에서 접근할 수 있습니다.

로컬과 호스팅의 비교

일반적으로 어느 쪽이 더 낫다고 할 수 없습니다. 제어와 노력을 교환합니다. 이 표는 특정 제품이 아닌 카테고리 전체에 적용되는 차이점에 초점을 맞춥니다.

데이터가 제어하는 머신을 떠나지 않아야 하는 경우 로컬이 승리하며 호스팅은 부적절한 도구입니다. 하드웨어가 수용할 수 있는 것보다 큰 모델이 필요하거나 여러 장소에서 접근 가능한 봇이 필요한 경우 호스팅이 승리합니다. 일반적인 설정은 둘 다 유지하고 작업별로 선택합니다.

로컬에서 호스팅으로 클라이언트 전환

코드가 이미 로컬 러너와 통신한다면 이동은 세 가지 값으로 가능합니다. 메시지 작성 및 스트리밍 청크 읽는 방법을 포함한 나머지 모든 것은 동일하게 유지됩니다.

1. Base URL. 로컬 주소 대신 https://api.onekeyllmapi.com/v1을 사용하세요.
2. API 키. 로컬 서버는 종종 키를 무시합니다. 호스팅된 서버는 Authorization: Bearer <key>로 이를 요구하며 SDK가 자동으로 전송합니다.
3. 모델 ID. 로컬 이름은 다운로드한 내용에 따라 다릅니다. 여기서는 ID가 uncensored입니다.

이것을 유연하게 유지하는 깔끔한 방법은 세 가지 모두를 환경 변수에서 읽는 것입니다. 그러면 하나의 파일이 두 장소 모두에서 작동합니다.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.onekeyllmapi.com/v1"),
    api_key=os.environ.get("LLM_API_KEY", "YOUR_KEY"),
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

models = client.models.list()
print([m.id for m in models.data])

resp = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "system", "content": "Answer in two sentences."},
        {"role": "user", "content": "Why do OpenAI-style endpoints make switching models easy?"},
    ],
    temperature=0.5,
)
print(resp.choices[0].message.content)

명령줄에서 동일한 호출은 빠른 연성 테스트에 유용합니다:

Copycurl https://api.onekeyllmapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "uncensored", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 20}'

Node.js의 경우 패턴이 동일합니다:

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.LLM_BASE_URL ?? "https://api.onekeyllmapi.com/v1",
  apiKey: process.env.LLM_API_KEY,
});

const res = await client.chat.completions.create({
  model: process.env.LLM_MODEL ?? "uncensored",
  messages: [{ role: "user", content: "Name three uses for JSON mode." }],
});
console.log(res.choices[0].message.content);

OpenAI 호환성의 지원 범위와 한계

호환성은 와이어 형식이 일치함을 의미합니다. 원래 서비스가 제공하는 모든 기능이 존재함을 보장하지 않습니다. 실제 앱을 마이그레이션하기 전에 대상에 대해 각각 확인하세요.

이 API의 지원 기능

• POST /v1/chat/completions에서의 채팅 완료 및 GET /v1/models에서의 모델 목록.
• 서버 전송 이벤트를 통한 스트리밍 stream: true, 스트림 끝에 사용량 보고.
• tools 및 tool_choice을 통한 함수 호출, 스트리밍 tool_calls, 그리고 role: "tool" 메시지로 결과 전송.
• response_format: {"type": "json_object"}을 통한 JSON 모드.
• 샘플링 제어: temperature, top_p, stop, seed 및 페널티 매개변수가 전달됩니다.

하지 않는 것

• 이미지, 오디오 또는 비디오 생성 없음. 텍스트 전용입니다.
• 임베딩 엔드포인트 및 파인튜닝 없음. 앱이 벡터 인덱스를 구축하는 경우 별도 임베딩 소스가 필요합니다.
• 단일 모델만 제공합니다. 이 모델은 독립적인 제공업체에서 운영하는 오픈 웨이트 모델입니다. 주요 벤더의 공식 API가 아니며, 벤더 간 라우터도 아니므로 ID를 변경하여 모델 계열 간에 선택할 수 없습니다.

로컬 러너는 때로 그 반대의 경우도 있습니다. 로컬 서버는 임베딩 엔드포인트를 제공하거나 여러 모델을 로드할 수 있으며, 컨텍스트 크기는 사용자가 구성한 대로입니다. 각 대상의 문서를 읽고 앱에서 실제로 사용하는 기능의 짧은 목록을 유지하세요. 퀵스타트 문서에는 요청 필드가 전체적으로 표시됩니다.

컨텍스트, 제한 사항 및 비용 차이

로컬 서버를 떠나면 세 가지 숫자가 변경됩니다. 첫 번째는 창 크기입니다. 로컬 러너의 컨텍스트 길이는 메모리에 연결된 설정입니다. 여기서는 프롬프트와 완료를 합쳐 100,000 토큰으로 고정되어 있으며 max_tokens은 선택 사항입니다. 두 번째는 동시 요청입니다. 자체 머신은 원하는 만큼 대기열에 넣을 수 있지만 전체 키는 여기에서 동시 요청 8개 및 분당 300개, 체험 키는 2개 및 60개를 허용합니다. 세 번째는 청구 금액입니다.

호스팅 사용은 입력 토큰 100만 개당 $0.15, 출력 토큰 100만 개당 $0.50이며 선불 크레딧에서 사용한 만큼 지불합니다. 일일 작업을 예시로 들어보겠습니다. 요약기는 하루에 400개의 문서를 처리하며, 각 문서는 입력 3,000 토큰, 출력 300 토큰입니다. 입력은 400 x 3,000 = 1,200,000 토큰이며, 비용은 1.2 x $0.15 = $0.18입니다. 출력은 400 x 300 = 120,000 토큰이며, 비용은 0.12 x $0.50 = $0.06입니다. 하루 총 비용은 $0.24이며, 30일치 달은 $7.20입니다. 결정하기 전에 GPU 가동 비용과 GPU 카드 자체 비용을 비교해 보세요.

제한을 초과하면 API는 HTTP 429를 코드 rate_limited 또는 concurrency로 반환합니다. 짧은 과부하의 경우 Retry-After: 5을 추가합니다. 기다리고 다시 시도하는 재시도 로직을 유지하세요. 실패하거나 거부된 요청은 청구되지 않습니다. 크레딧은 만료되지 않으므로 유휴 달은 비용이 들지 않습니다.

스트리밍 요청은 스트림이 끝날 때까지 동시성 슬롯을 유지하므로, 읽기를 중지한 스트림은 닫아야 합니다. 충전은 $20부터 시작됩니다. 등급과 보너스는 가격 책정 페이지에서 확인할 수 있습니다.

스위치 오작동 시 디버깅

대부분의 실패한 마이그레이션은 몇 가지 원인에 기인합니다. 다음 순서대로 확인하세요.

• 404 또는 연결 오류. Base URL에 /v1 접미사가 누락되었거나 불필요한 경로가 추가되었을 수 있습니다. https://api.onekeyllmapi.com/v1을 정확히 사용하세요.
• 인증 오류. 키가 누락되었거나 잘못된 헤더로 전송되었습니다. 형식은 Authorization: Bearer <key>입니다. SDK 사용자는 환경 변수가 실제로 로드되었는지 확인하세요.
• 모델을 찾을 수 없음. 이전 로컬 모델 이름이 여전히 구성 파일에 있습니다. GET /v1/models을 호출하고 반환된 ID인 uncensored를 사용하세요.
• 부하 시 429 오류. 전체 키 기준 동시 요청 8개 또는 분당 300개를 초과했습니다. 큐 또는 세마포어를 추가하세요.
• 파라미터가 무시되는 것 같습니다. 해당 파라미터가 위에서 나열된 전달 필드 중 하나인지 확인하고, 고정 seed과 낮은 temperature 설정에서 동작을 비교하세요.

모든 응답에는 X-Request-Id 헤더가 포함됩니다. 나중에 잘못된 응답을 추적할 수 있도록 자체 요청 ID 옆에 이를 로깅하세요. 프로덕션 트래픽을 운영하며 시간 경과에 따른 품질을 측정하려면 LLM Observability: Myths vs Facts 사이트 기사를 읽어보는 것이 좋습니다. 응답 헤더 X-Balance-USD, X-RateLimit-Limit-Requests 및 X-RateLimit-Limit-Concurrency도 캡처해 두는 것이 좋습니다.

부담 없이 사용해 보기

코드가 깔끔하게 포팅되는지 테스트하는 가장 저렴한 방법은 한 번 실행하는 것입니다. Google 또는 이메일과 비밀번호로 계정을 생성한 후, 키 페이지에서 $0.50 체험 크레딧을 청구하세요. 클릭 한 번으로 완료되며, 카드가 필요 없고, 사람당 하나만 제한되며, 7일 동안 유효합니다. API 키 페이지에서 키를 얻고, 위의 세 환경 변수를 설정한 후 기존 테스트 스위트를 실행하세요.

테스트가 통과하고 사용량이 예산에 맞는 경우, 카드(Visa, Mastercard, Apple Pay, Google Pay) 또는 암호화폐(USDT on TRC20, USDC on Base)로 $20부터 충전하세요. 프롬프트는 학습에 사용되지 않습니다. 이 모델은 합법적인 성인 사용을 위해 콘텐츠 거부 없이 답변하도록 조정되었으며, 하나의 고정 규칙이 있습니다: 미성년자를 포함한 성적인 콘텐츠가 없습니다.

더 많은 가이드

• LLM 관측 가능성: 흔한 오해와 사실