OpenAI 호환 API를 사용하는 Vercel AI SDK: 배포 체크리스트

만약 Vercel AI SDK 앱을 OpenAI 호환 API 게이트웨이로 이전하려 한다면, 이 마이그레이션을 단순히 한 줄의 baseURL 변경으로 취급해서는 안 됩니다.

그것이 보통 조용한 운영(production) 버그가 시작되는 지점입니다.

코드는 컴파일될 수 있습니다. 첫 번째 요청은 심지어 작동할 수도 있습니다. 하지만 그 후 스트리밍(streaming), 재시도(retries), 모델 이름(model names), 프로젝트 키(project keys), 또는 에이전트 워크플로우(agent workflows)가 전혀 관련 없어 보이는 곳에서 실패하기 시작합니다.

다음은 제가 OpenAI 호환 제공업체를 통해 실제 트래픽을 보내기 전에 사용하는 체크리스트입니다.

1. OpenAI 호환 제공업체 경로를 사용하세요

Vercel AI SDK 스타일의 프로젝트에서 첫 번째 결정 사항은 제공업체(provider)의 형태입니다.

대상 게이트웨이가 OpenAI 호환 방식이라면, OpenAI 호환 제공업체 패키지를 사용하고 다음을 구성하십시오:

제공업체 이름 (provider name)
API 키 (API key)
기본 URL (base URL)
모델 ID (model ID)

최소 형태:

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText } from "ai";

...

For TackleKey:

const tacklekey = createOpenAICompatible({
  name: "tacklekey",
  apiKey: process.env.TACKLEKEY_API_KEY,
...

2. 키를 서버 측에 유지하세요

API 게이트웨이 키는 비용을 발생시키고 계정의 모델에 접근할 수 있습니다.

즉, 키는 클라이언트 컴포넌트(client components), 공개 데모, 스크린샷, 브라우저 번들, 또는 리포지토리 예제가 아닌 서버 측 환경 변수(server-side environment variables)에 존재해야 합니다.

배포하기 전에 다음 사항을 확인하십시오:

키가 서버에서만 사용 가능한지
로그에 전체 키가 절대 출력되지 않는지
각 환경이 고유한 키를 가지고 있는지
테스트 및 운영(production) 트래픽이 동일한 예산을 공유하지 않는지

3. 현재 게이트웨이에서 정확한 모델 ID를 복사하세요

제공업체에 전달되는 모델(model) 값은 호출하려는 게이트웨이와 동일한 곳에서 복사해야 합니다.

표시 이름(display names)이 API ID라고 가정하지 마십시오.

다른 제공업체의 모델 문자열을 재사용하지 마십시오.

스테이징(staging) 모델 ID를 운영(production) 환경으로 가져가지 마십시오.

만약 앱이 게이트웨이가 알지 못하는 모델 ID를 보내면, 실제 문제는 model_not_found임에도 불구하고 실패 현상은 마치 SDK 문제처럼 보일 수 있습니다.

4. 먼저 아주 작은 비스트리밍(non-streaming) 요청을 테스트하세요

스트리밍 (streaming), 도구 (tools), JSON 출력 (JSON output), RAG, 또는 에이전트 루프 (agent loop)를 테스트하기 전에, 아주 작은 비스트리밍 (non-streaming) 요청을 하나 보내세요.

이를 통해 정확히 다음 네 가지를 증명하게 됩니다:

프로바이더 패키지 (provider package)가 게이트웨이 (gateway)에 도달할 수 있는지;
API 키가 해당 게이트웨이에 속해 있는지;
모델 ID (model ID)가 그곳에서 유효한지;
로그 (logs)에 예상한 요청이 나타나는지.

만약 이 요청이 실패한다면, 아직 앱 전체를 디버깅하지 마세요.

먼저 베이스 URL (base URL), 키 (key), 그리고 모델 ID (model ID)를 디버깅하세요.

5. 한 번에 한 단계씩 복잡성을 추가하세요

최소한의 요청이 작동한 후에는 다음 순서대로 나머지를 추가하세요:

스트리밍 (streaming);
구조화된 출력 (structured output);
도구 호출 (tool calls);
검색 컨텍스트 (retrieval context);
재시도 (retries);
폴백 모델 (fallback models);
프로덕션 에이전트 루프 (production agent loops).

모든 단계는 비용과 실패의 또 다른 원인을 추가합니다.

만약 이 모든 것을 한꺼번에 활성화한다면, 첫 번째 프로덕션 버그는 실제보다 훨씬 더 크게 보일 것입니다.

6. 모델 가격을 비교하기 전에 로그를 확인하세요

목록에 있는 가장 저렴한 모델이 항상 귀하의 앱에 가장 저렴하게 작동하는 경로는 아닙니다.

Vercel AI SDK 워크플로 (workflows)의 경우, 로그는 다음 질문에 답할 수 있어야 합니다:

정확히 어떤 모델 ID가 실행되었는지;
스트리밍 (streaming)이나 도구 호출 (tool calls)이 요청 형태를 변경했는지;
입력 및 출력 토큰 수 (input and output token counts);
재시도 (retry) 또는 폴백 (fallback) 동작;
최종 청구 금액;
어떤 프로젝트 키 (project key)가 해당 요청 비용을 지불했는지.

이러한 필드들이 없다면, 비용 디버깅은 추측에 의존하게 됩니다.

7. 에이전트 흐름 (agent flows)에 예산 경계를 설정하세요

에이전트 워크플로 (agent workflows)는 위험 요소가 있는 부분입니다.

사용자의 단 한 번의 행동이 다음과 같은 현상을 트리거할 수 있습니다:

다수의 모델 호출 (model calls);
검색 (retrieval);
도구 (tools);
재시도 (retries);
폴백 (fallback);
예상보다 긴 출력 (outputs).

프로덕션 트래픽을 활성화하기 전에, 로그만으로 사용자 행동 한 번에 드는 비용을 설명할 수 있는지 확인하세요.

설명할 수 없다면, 그 앱은 확장할 준비가 되지 않은 것입니다.

Practical TackleKey 설정

TackleKey는 OpenAI 호환 엔드포인트 (OpenAI-compatible endpoint)를 제공합니다:

공식 Vercel AI SDK 통합 페이지에는 최소한의 createOpenAICompatible 예제, 모델 ID 가이드, 그리고 로그 및 실시간 가격 확인 방법이 포함되어 있습니다:

[https://tacklekey.com/integrations/vercel-ai-sdk]

Insights