KO ▾
API 키 받기

API Migration 가이드: LLM 제공업체 안전하게 전환하기

이 API 마이그레이션 가이드는 기존 OpenAI 스타일 채팅 엔드포인트에 연결되는 앱을 다른 제공업체로 이동하는 방법을 안내합니다. 대부분의 작업은 변경하는 두 줄 코드가 아니라, 기존 제공업체에 우연히 의존하는 항목을 찾는 것입니다.

마지막 업데이트

하나의 파이프라인에서 다른 파이프라인으로 빛의 큐브 스트림의 일부를 우회하는 밸브, 점진적인 마이그레이션을 보여줌

요약

  • OpenAI 호환 대상의 경우 베이스 URL, 키 및 모델 ID를 변경한 후 동작을 확인합니다.
  • 기능을 먼저 목록화하세요: 임베딩, 이미지, 파인튜닝은 텍스트 전용 API로 이동하지 않습니다.
  • 플래그를 사용하여 비율별 롤아웃을 수행하면 롤백 시 구성 변경 한 번으로 완료됩니다.
  • 전환 전 자체 토큰 수를 사용하여 새 청구서를 추정하세요.

6단계 계획

  1. 앱에서 호출하는 모든 API 기능을 목록화하세요.
  2. 제공업체 설정을 구성으로 이동하세요.
  3. 매개변수와 모델 이름을 매핑하세요.
  4. 새 제한에 맞는 오류 및 속도 제한 처리를 추가하세요.
  5. 트래픽의 작은 비율을 새 제공업체로 라우팅하고 비교하세요.
  6. 비용을 확인하고 전환한 후 잠시 동안 이전 경로를 유지하세요.

예시의 대상은 https://api.apimigration.com/v1이며 모델 ID는 uncensored입니다. 동일한 단계는 모든 OpenAI 호환 제공업체에 적용되므로 벤더별 레시피가 아닌 체크리스트로 읽으세요. 중간에 문제가 발생하면 일반적인 LLM 통합 오류에 대한 문제 해결 기사이 일반적인 원인을 다룹니다.

단계 1: 앱이 사용하는 항목 인벤토리 작성

이전 제공업체로의 호출 코드를 모두 검색하고 기능과 엔드포인트를 나열하세요. 단일 채팅 호출에는 여러 의존성이 숨겨져 있을 수 있습니다: 특정 스타일에 의존하는 시스템 프롬프트, 도구 스키마, JSON 응답 형식, 큰 컨텍스트 창.

앱의 기능이 API
채팅 완료, /v1/responses지원됨
SSE를 통한 스트리밍지원됨, 사용량은 마지막에 전송됨
함수 호출지원됨, 스트리밍 tool_calls 포함
JSON 모드response_format을 통해 지원됨
컨텍스트100,000 토큰, 프롬프트 및 생성 포함
임베딩, 이미지, 오디오, 파인튜닝제공하지 않음, 이 기능은 다른 제공업체에 유지하세요

이전 제공업체가 임베딩 또는 이미지 생성도 처리했다면 마이그레이션을 분리하세요: 텍스트 호출만 이동하고 나머지는 원래 위치에 둡니다.

2단계: 제공업체 설정을 구성 파일에 저장하기

하드코딩된 URL은 마이그레이션을 코드 변경으로 만듭니다. 배포 없이 전환할 수 있도록 환경에서 베이스 URL, 키 및 모델을 읽으세요.

export LLM_BASE_URL="https://api.apimigration.com/v1"
export LLM_API_KEY="YOUR_KEY"
export LLM_MODEL="uncensored"
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["LLM_BASE_URL"],
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

인증은 표준 Authorization: Bearer 헤더이며 SDK가 자동으로 설정합니다. 키를 확인하고 서버가 제공하는 기능을 확인하려면 GET /v1/models을 호출하세요.

curl https://api.apimigration.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY"

단계 3: 매개변수와 프롬프트 매핑

이 API에서 통과하는 매개변수: temperature, top_p, stop, seed 및 빈도 페널티와 존재 페널티입니다. max_tokens은 선택사항입니다. 이전 코드가 비용 폭주를 방지하기 위해 이를 설정했다면 유지하세요.

세 가지 항목은 신중하게 확인해야 합니다.

  • 벤더별 필드. OpenAI 요청 형식 밖의 모든 것은 무시되거나 거부될 수 있습니다. 정확한 프로덕션 페이로드를 사용하여 요청을 하나 보내고 응답을 읽으세요.
  • 모델 동작. 다른 모델은 동일한 프롬프트를 다르게 해석합니다. 이전 모델에 맞게 조정된 시스템 프롬프트는 작은 수정이 필요할 수 있습니다. 테스트하고 가정하지 마세요.
  • 거절. 이전 프롬프트에 거절을 피하기 위한 우회 방법이 포함되어 있었다면, 일반적으로 이를 삭제할 수 있으며 이는 프롬프트를 단축시킵니다.

모델은 답변하는 내용에서도 다릅니다. 이 모델은 콘텐츠 거부 없이 합법적인 성인 사용에 맞게 조정되었으며, 미성년자가 관련된 성적 콘텐츠는 금지됩니다.

단계 4: 새 제한에 맞춰 오류 처리 일치시키기

풀 키는 동시 요청 8개와 분당 300개를 허용합니다. 체험 키는 동시 요청 2개와 분당 60개를 허용합니다. 한도를 초과하면 HTTP 429와 오류 코드 rate_limited 또는 concurrency가 반환됩니다. 일시적 과부하 시에도 429가 발생하며, Retry-After: 5가 포함됩니다.

import time
from openai import RateLimitError

def chat(messages, retries=4):
    for attempt in range(retries):
        try:
            return client.chat.completions.create(model=MODEL, messages=messages)
        except RateLimitError:
            time.sleep(5 * (attempt + 1))
    raise RuntimeError("still rate limited after retries")

스트리밍 요청은 스트림이 끝날 때까지 동시 요청 슬롯을 유지하므로, 멈춘 클라이언트가 다른 요청을 기아 상태로 만들 수 있습니다. finally 블록에서 스트림을 닫으세요. 이전 제공업체가 더 많은 병렬 호출을 허용했다면, 새로운 한도에 맞춰 세마포어를 추가하세요. 실패한 요청은 요금이 부과되지 않으므로 재시도가 예산에 안전합니다.

단계 5: 비율별 롤아웃

모든 것을 한 번에 바꾸지 마세요. 사용자 중 작은 비율을 새 제공업체로 보내고 이전 제공업체를 폴백으로 유지하세요. 사용자 ID를 해싱하면 각 사용자가 한쪽에만 고정되므로 대화 중 화자가 바뀌지 않습니다.

import hashlib

def use_new(user_id: str, percent: int) -> bool:
    bucket = int(hashlib.sha256(user_id.encode()).hexdigest(), 16) % 100
    return bucket < percent

# 5 percent, then 25, 50, 100 as metrics hold
new_client = OpenAI(base_url="https://api.apimigration.com/v1", api_key=os.environ["NEW_KEY"])
old_client = OpenAI(base_url=os.environ["OLD_BASE_URL"], api_key=os.environ["OLD_KEY"])

def pick(user_id):
    return new_client if use_new(user_id, int(os.environ.get("ROLLOUT_PERCENT", "0"))) else old_client

직전 단계가 하루 정도 깨끗하게 실행된 후에만 비율을 높이세요. 그러면 롤백은 환경 변수를 0으로 되돌리는 것뿐입니다.

전환 후 팀이 놀라워하는 사항

베이스 URL 변경은 첫 번째 시도에서 작동합니다. 예상치 못한 문제는 나중에 발생합니다.

  • 어조와 형식의 변화. 동일한 프롬프트가 다른 단어로 구성된 답변을 생성합니다. "Answer:" 접두사에 대한 정규식과 같이 자유 텍스트를 구문 분석하는 기능이 먼저 깨집니다. 프로그램이 읽는 데이터에는 JSON 모드나 도구 호출을 선호하세요.
  • 다른 토큰 수 각 모델은 텍스트를 자체적으로 토큰화합니다. 이전 제공업체의 토큰 수를 기반으로 한 비용 추계는 일정 정도 어긋날 수 있으므로 usage 필드를 사용하여 다시 측정하세요.
  • 출력 길이. max_tokens이 없으면 생성된 텍스트가 100,000개 토큰 컨텍스트 창의 나머지 부분을 모두 사용할 수 있습니다. 이전 설정에 기본 상한이 있었다면 의도적으로 설정하세요.
  • 시간 초과. 클라이언트 시간 초과는 이전 제공업체에 맞춰 조정되었습니다. 새로운 제공업체의 긴 답변은 이를 초과할 수 있습니다. 가능한 곳에서는 스트리밍을 사용하고, 비스트리밍 호출의 시간 초과를 높이세요.
  • 무음 거부 변경. 제품에서 거부 메시지를 포착하고 폴백을 표시하던 코드가 더 이상 작동하지 않을 수 있습니다. 해당 코드를 계속 사용할지 결정하세요.

전환 전 확인 체크리스트

  1. 보유한 모든 기능에 테스트된 대체 기능이 있거나 문서화된 격차가 있습니다.
  2. 베이스 URL, 키 및 모델은 API를 호출하는 모든 서비스의 구성에서 가져옵니다.
  3. 코드 내의 속도 제한 및 동시 요청 상한이 새로운 제한과 일치합니다.
  4. 클라이언트 연결이 끊기면 스트림이 종료됩니다.
  5. 로그에는 X-Request-Id 헤더가 포함되어 있어 도움 요청 시 요청을 인용할 수 있습니다.
  6. 잔액은 X-Balance-USD 또는 GET /v1/balance을 통해 모니터링되며, 잔액이 부족해지기 전에 알림이 발생합니다.
  7. 이전 제공업체는 여전히 자금 지원되고 롤백 구성도 유지됩니다.
  8. 명명된 사람이 롤백 결정에 대한 책임을 집니다.

마지막 항목은 새벽 2시에 사고가 발생하기 전까지는 어리석게 들릴 수 있습니다. 누군가는 플래그를 뒤집을 권한이 있어야 합니다.

6단계: 비용 확인 후 전환

자체 트래픽을 기준으로 새로운 요금을 계산하세요. 가격은 입력 토큰 1M당 $0.15, 출력 토큰 1M당 $0.50입니다.

예시: 하루 10,000개 요청, 각 요청당 입력 토큰 1,500개 및 출력 토큰 400개.

  • 입력: 15,000,000 토큰 x $0.15 / 1,000,000 = $2.25.
  • 출력: 4,000,000 토큰 x $0.50 / 1,000,000 = $2.00.
  • 합계: 하루 $4.25.

이전 제공업체의 현재 가격 페이지를 사용하여 이전 청구서와 비교하세요. 여기서는 구독 없이 선불 크레딧으로 청구되며 크레딧은 만료되지 않습니다. 충전 금액은 $20부터 $500까지 정수 금액으로 가능하며, $50부터 5%, $100부터 10%, $200부터 15%의 보너스가 제공됩니다. 암호화폐(USDT on TRC20 또는 USDC on Base)로 결제할 수 있습니다. 잔액은 X-Balance-USD 응답 헤더에 표시되므로 이를 기준으로 알림을 설정할 수 있습니다.

새 계정은 첫 테스트를 위해 $0.50의 무료 체험 크레딧을 청구할 수 있습니다. 가격을 확인한 후 API 키를 발급받으세요. 매개변수 매핑 중에는 문서를 열어두세요.

자주 묻는 질문

Base URL만 변경하여 마이그레이션할 수 있나요?

OpenAI 호환 API의 경우 Base URL, API 키 및 모델 ID 변경이 필요합니다. 다른 모델은 다르게 응답하므로 프롬프트를 여전히 테스트해야 합니다.

함수 호출 및 JSON 모드가 여전히 작동하나요?

함수 호출 및 JSON 모드(response_format json_object)가 지원됩니다. 전환 전 실제 프롬프트로 스키마를 검증하세요.

내 앱이 임베딩을 사용한다면 어떻게 하나요?

이 API는 텍스트 전용이며 임베딩, 이미지 생성 또는 파인튜닝을 제공하지 않습니다. 해당 호출은 현재 제공업체를 사용하세요.

빠르게 롤백하는 방법은 무엇인가요?

롤아웃 비율과 같은 환경 플래그로 라우팅하고, 새 라우트가 며칠 동안 정상적으로 실행될 때까지 이전 클라이언트 구성을 유지하세요.

API 키 받기

등록, 키 복사, base URL 업데이트. 설정이 완료되었습니다.

API 키 받기