Provider 시스템과 다중 LLM 지원 완벽 가이드

AI SDK에서 여러 LLM 프로바이더를 통합 관리하는 방법을 알아봅니다. 네임스페이스 구조부터 커스텀 프로바이더 로더, 인증 시스템까지 실무에서 바로 활용할 수 있는 패턴을 다룹니다.

---

목차

1. Provider_네임스페이스_구조
2. 번들_프로바이더_목록
3. 커스텀_프로바이더_로더
4. 모델_검색과_기본_모델_선택
5. 인증_시스템과_API_키_관리
6. 프로바이더_설정_커스터마이징

---

1. Provider 네임스페이스 구조

김개발 씨는 회사에서 새로운 AI 프로젝트를 맡게 되었습니다. 기획팀에서는 OpenAI의 GPT-4를 쓰고 싶다고 하고, 연구팀에서는 Anthropic의 Claude를 써보자고 합니다.

심지어 비용 절감을 위해 오픈소스 모델도 고려해야 한다는 이야기까지 나왔습니다. "이걸 어떻게 한 프로젝트에서 다 관리하지?"

Provider 네임스페이스란 여러 AI 모델 제공자를 체계적으로 구분하고 관리하는 구조입니다. 마치 대형 쇼핑몰에서 브랜드별로 매장을 구분해 놓은 것과 같습니다.

OpenAI는 A층, Anthropic은 B층, Google은 C층처럼 말이죠. 이 구조를 이해하면 수십 개의 AI 모델을 마치 하나의 시스템처럼 자유롭게 전환하며 사용할 수 있습니다.

다음 코드를 살펴봅시다.

// Provider 레지스트리 구조 정의
interface ProviderRegistry {
  // 네임스페이스: 프로바이더 매핑
  [namespace: string]: Provider;
}

// 프로바이더 등록 및 조회
const registry: ProviderRegistry = {
  'openai': openaiProvider,
  'anthropic': anthropicProvider,
  'google': googleProvider,
};

// 네임스페이스로 모델 접근
function getModel(modelId: string): LanguageModel {
  // "openai:gpt-4" 형식 파싱
  const [namespace, model] = modelId.split(':');
  const provider = registry[namespace];
  return provider.languageModel(model);
}

김개발 씨는 입사 6개월 차 백엔드 개발자입니다. AI 기능을 처음 담당하게 되어 설레기도 하고 걱정되기도 합니다.

특히 여러 AI 모델을 동시에 지원해야 한다는 요구사항이 부담스럽게 느껴졌습니다. 선배 개발자 박시니어 씨가 다가와 화면을 살펴봅니다.

"걱정 마세요. Provider 네임스페이스 구조만 이해하면 생각보다 간단해요." 그렇다면 Provider 네임스페이스란 정확히 무엇일까요?

쉽게 비유하자면, 이것은 마치 국제 전화번호 체계와 같습니다. 한국에 전화하려면 +82를, 미국에 전화하려면 +1을 누르듯이, OpenAI 모델을 쓰려면 "openai:"를, Anthropic 모델을 쓰려면 "anthropic:"를 앞에 붙이면 됩니다.

이 앞부분이 바로 네임스페이스입니다. 네임스페이스가 없던 시절에는 어땠을까요?

개발자들은 각 AI 제공자마다 완전히 다른 코드를 작성해야 했습니다. OpenAI용 코드 따로, Anthropic용 코드 따로.

마치 한국어, 영어, 일본어를 각각 다른 방식으로 배워야 하는 것처럼 비효율적이었습니다. 모델을 바꿀 때마다 코드 전체를 수정해야 하는 악몽 같은 상황이 펼쳐졌습니다.

바로 이런 문제를 해결하기 위해 네임스페이스 구조가 등장했습니다. **"openai:gpt-4"**라는 문자열 하나로 어떤 제공자의 어떤 모델을 사용할지 명확하게 지정할 수 있습니다.

코드에서는 이 문자열을 콜론(:)으로 분리해서 앞부분은 제공자를, 뒷부분은 모델명으로 인식합니다. 위의 코드를 한 줄씩 살펴보겠습니다.

먼저 ProviderRegistry 인터페이스는 네임스페이스를 키로, 프로바이더 객체를 값으로 가지는 구조를 정의합니다. 그 다음 registry 객체에 실제 프로바이더들을 등록합니다.

getModel 함수는 "openai:gpt-4" 같은 문자열을 받아서 적절한 모델 객체를 반환합니다. 실제 현업에서는 이 구조가 어떻게 빛을 발할까요?

예를 들어 챗봇 서비스를 운영한다고 가정해봅시다. 평소에는 비용 효율적인 모델을 사용하다가, VIP 고객에게는 더 강력한 모델을 제공하고 싶을 수 있습니다.

네임스페이스 구조 덕분에 설정 파일에서 모델 ID 문자열만 바꾸면 됩니다. 코드 수정 없이 말이죠.

하지만 주의할 점도 있습니다. 네임스페이스를 잘못 입력하면 런타임 에러가 발생합니다.

"opanai:gpt-4"처럼 오타가 나면 해당 프로바이더를 찾을 수 없다는 에러가 뜹니다. 따라서 상수로 정의해두거나 타입 시스템을 활용해 컴파일 타임에 잡는 것이 좋습니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 설명을 들은 김개발 씨는 환하게 웃었습니다.

"아, 그래서 모델 ID에 콜론이 들어가 있었군요!"

실전 팁

💡 - 네임스페이스는 항상 소문자로 통일하세요

• 자주 사용하는 모델 ID는 상수로 정의해두면 오타를 방지할 수 있습니다

---

2. 번들 프로바이더 목록

김개발 씨가 본격적으로 코드를 작성하려고 보니, 각 AI 제공자마다 SDK를 따로 설치해야 하는지 궁금해졌습니다. "OpenAI SDK, Anthropic SDK, Google SDK...

이걸 다 따로 설치하고 설정해야 하나요?" 박시니어 씨가 빙긋 웃으며 대답했습니다. "AI SDK에는 이미 번들 프로바이더가 준비되어 있어요."

번들 프로바이더란 AI SDK에 기본으로 포함된 주요 AI 제공자용 어댑터입니다. @ai-sdk/openai, @ai-sdk/anthropic 등의 패키지로 제공되며, 설치만 하면 바로 사용할 수 있습니다.

마치 스마트폰에 기본 앱이 설치되어 있는 것처럼, 가장 많이 쓰는 AI 제공자들은 이미 준비되어 있습니다.

다음 코드를 살펴봅시다.

// 번들 프로바이더 임포트
import { openai } from '@ai-sdk/openai';
import { anthropic } from '@ai-sdk/anthropic';
import { google } from '@ai-sdk/google';
import { mistral } from '@ai-sdk/mistral';

// 각 프로바이더의 모델 사용
const gpt4 = openai('gpt-4-turbo');
const claude = anthropic('claude-3-opus-20240229');
const gemini = google('gemini-pro');

// 통합 레지스트리에 등록
import { createProviderRegistry } from 'ai';
const registry = createProviderRegistry({
  openai,
  anthropic,
  google,
  mistral,
});

김개발 씨는 npm에서 AI 관련 패키지를 검색하다가 @ai-sdk로 시작하는 패키지들을 여러 개 발견했습니다. openai, anthropic, google, mistral, cohere...

목록이 꽤 깁니다. 이것들이 바로 번들 프로바이더입니다.

번들 프로바이더란 무엇일까요? 마치 만능 리모컨을 생각해보세요.

삼성, LG, 소니 TV를 각각 다른 리모컨으로 조작하는 대신, 만능 리모컨 하나로 모든 TV를 제어할 수 있습니다. 번들 프로바이더는 이 만능 리모컨의 "TV별 설정 칩" 같은 역할을 합니다.

AI SDK라는 만능 리모컨에 각 AI 제공자용 칩을 끼우면 해당 서비스를 사용할 수 있게 됩니다. 현재 AI SDK에서 공식 지원하는 번들 프로바이더 목록을 살펴보겠습니다.

@ai-sdk/openai는 GPT-4, GPT-3.5 등 OpenAI 모델을 지원합니다. 가장 널리 쓰이는 프로바이더입니다.

@ai-sdk/anthropic은 Claude 시리즈를 지원하며, 긴 컨텍스트 처리에 강점이 있습니다. @ai-sdk/google은 Gemini 모델군을 다루고, @ai-sdk/mistral은 Mistral AI의 오픈소스 기반 모델들을 제공합니다.

이 외에도 @ai-sdk/cohere, @ai-sdk/amazon-bedrock, @ai-sdk/azure 등 다양한 프로바이더가 있습니다. 위 코드에서 주목할 점은 각 프로바이더를 함수처럼 호출한다는 것입니다.

openai('gpt-4-turbo')라고 쓰면 OpenAI의 GPT-4 Turbo 모델 객체가 반환됩니다. 이 객체는 AI SDK의 표준 인터페이스를 따르므로, 어떤 프로바이더의 모델이든 동일한 방식으로 사용할 수 있습니다.

createProviderRegistry 함수는 여러 프로바이더를 하나의 레지스트리로 묶어줍니다. 이렇게 등록해두면 나중에 "openai:gpt-4-turbo" 같은 문자열로 모델을 조회할 수 있습니다.

설정 파일이나 환경 변수에서 모델 ID를 읽어와 동적으로 모델을 선택하는 패턴이 가능해집니다. 실무에서는 어떻게 활용할까요?

대부분의 프로젝트에서는 2~3개의 프로바이더만 사용합니다. 메인 모델로 OpenAI를 쓰고, 특수 목적에 Anthropic을 쓰는 식이죠.

필요한 프로바이더만 설치하면 번들 사이즈도 관리할 수 있습니다. 주의할 점은 각 프로바이더마다 API 키가 필요하다는 것입니다.

프로바이더를 설치했다고 바로 작동하는 게 아닙니다. 해당 서비스의 API 키를 환경 변수로 설정해야 합니다.

이 부분은 뒤에서 자세히 다루겠습니다. 박시니어 씨가 정리해주었습니다.

"필요한 프로바이더 패키지만 설치하고, 레지스트리에 등록하면 끝이에요. 나머지는 AI SDK가 알아서 처리해줍니다."

실전 팁

💡 - 사용할 프로바이더만 설치하여 번들 사이즈를 최적화하세요

• 프로바이더 버전은 AI SDK 코어 버전과 호환성을 확인하세요

---

3. 커스텀 프로바이더 로더

며칠 후, 김개발 씨에게 새로운 요구사항이 들어왔습니다. 회사에서 자체 개발한 AI 모델을 연동해야 한다는 것입니다.

"번들 프로바이더에 없는 모델은 어떻게 하죠?" 박시니어 씨가 답했습니다. "그럴 때 CUSTOM_LOADERS를 사용하면 됩니다."

CUSTOM_LOADERS는 번들 프로바이더에 포함되지 않은 AI 모델을 연동하기 위한 확장 메커니즘입니다. 직접 프로바이더 로더 함수를 작성하여 어떤 AI 서비스든 통합할 수 있습니다.

마치 만능 리모컨에 새로운 TV 설정을 직접 추가하는 것과 같습니다.

다음 코드를 살펴봅시다.

// 커스텀 프로바이더 로더 정의
type ProviderLoader = () => Promise<Provider>;

const CUSTOM_LOADERS: Record<string, ProviderLoader> = {
  // 자체 모델 서버 연동
  'internal': async () => {
    const { createInternalProvider } = await import('./internal-provider');
    return createInternalProvider({
      baseURL: process.env.INTERNAL_AI_URL,
      apiKey: process.env.INTERNAL_AI_KEY,
    });
  },
  // 로컬 Ollama 연동
  'ollama': async () => {
    const { ollama } = await import('ollama-ai-provider');
    return ollama;
  },
};

// 로더 등록 및 사용
async function loadProvider(namespace: string): Promise<Provider> {
  const loader = CUSTOM_LOADERS[namespace];
  if (!loader) throw new Error(`Unknown provider: ${namespace}`);
  return await loader();
}

김개발 씨는 고민에 빠졌습니다. 회사의 자체 AI 모델은 내부 서버에서 돌아가는데, 당연히 공식 번들 프로바이더는 없습니다.

게다가 개발 환경에서는 Ollama로 로컬 테스트도 해야 합니다. 박시니어 씨가 화이트보드에 그림을 그리기 시작했습니다.

"번들 프로바이더는 미리 만들어진 어댑터예요. 하지만 세상의 모든 AI 서비스를 다 지원할 수는 없잖아요?

그래서 커스텀 로더라는 확장 포인트가 있습니다." 커스텀 로더의 구조는 간단합니다. 로더는 프로바이더 객체를 반환하는 비동기 함수입니다.

이 함수 안에서 필요한 설정을 하고, 외부 라이브러리를 동적 임포트하고, 최종적으로 Provider 인터페이스를 따르는 객체를 반환하면 됩니다. 코드를 자세히 살펴보겠습니다.

CUSTOM_LOADERS 객체는 네임스페이스를 키로, 로더 함수를 값으로 가집니다. 'internal' 로더는 회사 내부 AI 서버용이고, 'ollama' 로더는 로컬 개발용입니다.

각 로더는 async 함수여서 필요할 때만 관련 모듈을 로드합니다. 동적 임포트가 왜 중요할까요?

모든 프로바이더를 앱 시작 시점에 로드하면 초기 로딩이 느려집니다. 동적 임포트를 사용하면 해당 프로바이더가 실제로 필요할 때만 코드가 로드됩니다.

사용하지 않는 프로바이더의 코드는 번들에서 분리될 수도 있습니다. 실무에서 커스텀 로더는 다양하게 활용됩니다.

자체 파인튜닝 모델 연동, 프록시 서버를 통한 API 호출, 여러 모델을 조합한 앙상블 프로바이더 등을 구현할 수 있습니다. 심지어 테스트용 목(mock) 프로바이더를 만들어 유닛 테스트에 활용하기도 합니다.

주의할 점은 커스텀 프로바이더도 표준 인터페이스를 따라야 한다는 것입니다. languageModel, textEmbedding 등 AI SDK가 기대하는 메서드들을 구현해야 합니다.

그래야 generateText, streamText 같은 상위 함수들이 정상 작동합니다. 김개발 씨가 질문했습니다.

"그러면 내부 서버용 프로바이더는 직접 구현해야 하나요?" 박시니어 씨가 고개를 끄덕였습니다. "네, 하지만 걱정 마세요.

OpenAI 호환 API라면 openai 프로바이더에 baseURL만 바꿔서 쓸 수도 있어요."

실전 팁

💡 - OpenAI 호환 API는 @ai-sdk/openai의 baseURL 옵션으로 간단히 연동 가능합니다

• 커스텀 로더 작성 시 에러 처리를 꼼꼼히 해두세요

---

4. 모델 검색과 기본 모델 선택

프로젝트가 점점 커지면서 사용하는 모델 수도 늘어났습니다. GPT-4, Claude, Gemini에 내부 모델까지.

김개발 씨는 문득 궁금해졌습니다. "지금 사용 가능한 모델이 뭐가 있는지 어떻게 알 수 있죠?

그리고 기본 모델은 어떻게 정하나요?"

모델 검색 기능을 사용하면 현재 등록된 프로바이더들이 제공하는 모델 목록을 조회할 수 있습니다. 기본 모델 선택은 네임스페이스 없이 모델을 요청했을 때 사용할 폴백 모델을 지정하는 것입니다.

마치 웹 브라우저의 기본 검색엔진 설정과 비슷합니다.

다음 코드를 살펴봅시다.

// 프로바이더 레지스트리에서 모델 조회
const registry = createProviderRegistry({
  openai,
  anthropic,
  google,
});

// 특정 프로바이더의 모델 가져오기
const model = registry.languageModel('openai:gpt-4-turbo');

// 기본 프로바이더 설정
const registryWithDefault = createProviderRegistry({
  openai,
  anthropic,
}, {
  // 네임스페이스 없을 때 기본값
  defaultProvider: 'openai',
  defaultModel: 'gpt-4-turbo',
});

// 기본 모델 사용 (네임스페이스 생략)
const defaultModel = registryWithDefault.languageModel('gpt-4-turbo');

김개발 씨는 코드 리뷰 중에 이상한 점을 발견했습니다. 어떤 코드에서는 'openai:gpt-4'라고 쓰고, 어떤 곳에서는 그냥 'gpt-4'라고만 씁니다.

둘 다 동작하는 것 같은데, 어떻게 가능한 걸까요? 박시니어 씨가 설명을 시작했습니다.

"레지스트리에 기본 프로바이더를 설정할 수 있어요. 네임스페이스 없이 모델명만 적으면 기본 프로바이더에서 찾습니다.

마치 전화번호의 지역번호처럼요. 같은 지역이면 지역번호를 생략해도 되잖아요?" 모델 검색 과정을 단계별로 살펴보겠습니다.

먼저 registry.languageModel('openai:gpt-4-turbo')를 호출하면, 레지스트리는 콜론을 기준으로 문자열을 파싱합니다. 'openai'라는 네임스페이스에서 'gpt-4-turbo' 모델을 찾습니다.

해당 프로바이더의 languageModel 메서드가 호출되어 모델 객체가 반환됩니다. 기본 프로바이더 설정은 createProviderRegistry의 두 번째 인자로 전달합니다.

defaultProvider는 네임스페이스가 없을 때 사용할 프로바이더를, defaultModel은 모델명까지 생략했을 때 사용할 기본 모델을 지정합니다. 이렇게 설정하면 코드가 훨씬 간결해집니다.

실무에서는 환경별로 기본 모델을 다르게 설정하기도 합니다. 개발 환경에서는 비용이 저렴한 모델을, 프로덕션에서는 성능이 좋은 모델을 기본값으로 설정할 수 있습니다.

환경 변수로 기본 모델을 주입하면 코드 수정 없이 환경별 설정이 가능합니다. 모델이 존재하지 않으면 어떻게 될까요?

존재하지 않는 모델을 요청하면 에러가 발생합니다. 따라서 모델 ID의 유효성을 검증하는 로직을 추가하거나, try-catch로 에러를 처리해야 합니다.

일부 프로바이더는 사용 가능한 모델 목록을 조회하는 API를 제공하기도 합니다. 김개발 씨가 정리했습니다.

"그러니까 기본 프로바이더를 설정해두면 매번 'openai:'를 안 써도 되는 거군요. 편하네요!" 박시니어 씨가 덧붙였습니다.

"네, 하지만 협업할 때는 명시적으로 쓰는 게 더 나을 수도 있어요. 코드를 읽는 사람이 어떤 모델인지 바로 알 수 있거든요."

실전 팁

💡 - 협업 프로젝트에서는 명시적으로 네임스페이스를 쓰는 것이 가독성에 좋습니다

• 환경 변수로 기본 모델을 설정하면 환경별 분기가 쉬워집니다

---

5. 인증 시스템과 API 키 관리

드디어 코드 작성을 마친 김개발 씨. 로컬에서 테스트하려고 실행했는데 에러가 뜹니다.

"401 Unauthorized"라는 메시지와 함께요. "아, API 키 설정을 안 했구나!" 인증은 AI API 사용의 가장 기본이자, 가장 중요한 부분입니다.

API 키 관리는 AI 서비스에 접근하기 위한 인증 정보를 안전하게 저장하고 사용하는 것입니다. 각 프로바이더마다 고유한 API 키가 필요하며, 이를 환경 변수로 관리하는 것이 일반적입니다.

API 키가 노출되면 비용 폭탄을 맞거나 서비스가 차단될 수 있으므로 보안에 특히 주의해야 합니다.

다음 코드를 살펴봅시다.

// 환경 변수에서 API 키 읽기
const openaiKey = process.env.OPENAI_API_KEY;
const anthropicKey = process.env.ANTHROPIC_API_KEY;

// 프로바이더 초기화 시 API 키 전달
import { createOpenAI } from '@ai-sdk/openai';
import { createAnthropic } from '@ai-sdk/anthropic';

const openai = createOpenAI({
  apiKey: openaiKey,
  // 선택적: 조직 ID, 베이스 URL 등
  organization: process.env.OPENAI_ORG_ID,
});

const anthropic = createAnthropic({
  apiKey: anthropicKey,
  // 선택적: 헤더 커스터마이징
  headers: { 'X-Custom-Header': 'value' },
});

// API 키 유효성 검증
function validateApiKeys(): void {
  if (!openaiKey) throw new Error('OPENAI_API_KEY is required');
  if (!anthropicKey) throw new Error('ANTHROPIC_API_KEY is required');
}

김개발 씨는 처음에 API 키를 코드에 직접 넣었습니다. 그랬더니 박시니어 씨가 깜짝 놀라며 말했습니다.

"절대 그러면 안 돼요! 그 코드가 Git에 올라가면 큰일 납니다." 왜 API 키를 코드에 직접 쓰면 안 될까요?

API 키는 마치 집 열쇠와 같습니다. 열쇠를 현관문에 테이프로 붙여놓으면 누구나 들어올 수 있겠죠?

코드에 API 키를 적으면 GitHub 같은 공개 저장소에 올라갈 위험이 있습니다. 실제로 이런 실수로 수천만 원의 요금이 청구된 사례가 있습니다.

환경 변수는 이 문제의 표준 해결책입니다. .env 파일에 키를 저장하고, .gitignore에 추가해서 버전 관리에서 제외합니다.

서버에서는 환경 변수를 직접 설정하거나, 비밀 관리 서비스를 사용합니다. AWS Secrets Manager, HashiCorp Vault 같은 도구가 있습니다.

각 프로바이더의 환경 변수 이름은 보통 정해져 있습니다. OpenAI는 OPENAI_API_KEY, Anthropic은 ANTHROPIC_API_KEY, Google은 GOOGLE_GENERATIVE_AI_API_KEY를 기본으로 찾습니다.

프로바이더를 import만 하면 자동으로 해당 환경 변수를 읽습니다. 하지만 명시적으로 전달하는 것이 더 안전합니다.

createOpenAI, createAnthropic 같은 팩토리 함수를 사용하면 apiKey를 직접 전달할 수 있습니다. 이렇게 하면 환경 변수 이름을 자유롭게 정할 수 있고, 어디서 키를 가져오는지 코드에서 명확히 보입니다.

API 키 관리의 모범 사례를 정리해보겠습니다. 첫째, 절대 코드에 하드코딩하지 마세요.

둘째, 환경별로 다른 키를 사용하세요. 개발용과 프로덕션용 키를 분리하면 실수로 인한 피해를 줄일 수 있습니다.

셋째, 키를 주기적으로 교체하세요. 만약 노출되더라도 피해를 최소화할 수 있습니다.

앱 시작 시 키 유효성을 검증하는 것도 좋은 습관입니다. 위 코드의 validateApiKeys 함수처럼, 필수 환경 변수가 설정되었는지 앱 시작 시점에 확인하세요.

런타임 중에 갑자기 인증 에러가 나는 것보다 시작 시점에 명확한 에러 메시지를 보여주는 게 낫습니다. 김개발 씨는 .env 파일을 만들고, .gitignore에 추가했습니다.

"이제 안심이네요. 그런데 팀원들한테는 키를 어떻게 공유하죠?" 박시니어 씨가 답했습니다.

"안전한 채널로 개별 전달하거나, 팀 비밀 관리 도구를 사용하세요. 슬랙이나 이메일로 보내면 안 됩니다!"

실전 팁

💡 - .env.example 파일을 만들어 필요한 환경 변수 목록을 문서화하세요

• 프로덕션에서는 환경 변수보다 시크릿 매니저 사용을 권장합니다

---

6. 프로바이더 설정 커스터마이징

기본 설정만으로 충분할 때도 있지만, 실무에서는 세밀한 조정이 필요한 경우가 많습니다. 타임아웃 설정, 재시도 로직, 프록시 서버 사용 등.

김개발 씨가 물었습니다. "프로바이더 동작을 커스터마이징하려면 어떻게 해야 하나요?"

프로바이더 설정 커스터마이징은 기본 동작을 프로젝트 요구사항에 맞게 조정하는 것입니다. 베이스 URL 변경, 타임아웃 설정, 커스텀 헤더 추가, 재시도 정책 등을 설정할 수 있습니다.

마치 자동차를 구매한 후 자기 취향에 맞게 튜닝하는 것과 같습니다.

다음 코드를 살펴봅시다.

import { createOpenAI } from '@ai-sdk/openai';
import { createAnthropic } from '@ai-sdk/anthropic';

// OpenAI 프로바이더 커스터마이징
const customOpenAI = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: 'https://api.proxy.example.com/v1', // 프록시 서버
  organization: process.env.OPENAI_ORG_ID,
  headers: {
    'X-Request-ID': () => crypto.randomUUID(), // 동적 헤더
  },
  compatibility: 'strict', // API 호환성 모드
});

// Anthropic 프로바이더 커스터마이징
const customAnthropic = createAnthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  headers: {
    'anthropic-beta': 'messages-2024-01-01', // 베타 기능 활성화
  },
});

// 모델별 기본 설정
const gpt4 = customOpenAI('gpt-4-turbo', {
  user: 'user-123', // 사용자 추적용
});

김개발 씨의 회사에서는 보안 정책상 외부 API 호출이 프록시 서버를 거쳐야 합니다. 또한 모든 요청에 추적용 헤더를 붙여야 합니다.

기본 설정으로는 이런 요구사항을 충족할 수 없었습니다. 박시니어 씨가 팩토리 함수의 옵션들을 설명해주었습니다.

"프로바이더를 가져오는 방법이 두 가지 있어요. 하나는 import { openai } from '@ai-sdk/openai'처럼 미리 설정된 인스턴스를 쓰는 거고, 다른 하나는 createOpenAI로 직접 인스턴스를 만드는 거예요.

커스터마이징이 필요하면 후자를 쓰세요." baseURL 옵션은 API 엔드포인트를 변경합니다. 회사 프록시 서버를 거쳐야 하거나, OpenAI 호환 API를 제공하는 다른 서비스를 사용할 때 유용합니다.

Azure OpenAI, Cloudflare AI Gateway, 자체 호스팅 모델 서버 등을 연결할 수 있습니다. headers 옵션으로 커스텀 헤더를 추가합니다.

값으로 문자열을 넣으면 고정 헤더가 되고, 함수를 넣으면 요청마다 동적으로 값이 생성됩니다. 위 코드에서 X-Request-ID는 매 요청마다 새로운 UUID를 생성합니다.

이렇게 하면 로그 추적이 쉬워집니다. Anthropic의 베타 기능도 헤더로 활성화합니다.

Anthropic은 새로운 기능을 베타로 먼저 공개하는 경우가 많습니다. anthropic-beta 헤더에 해당 기능의 버전을 명시하면 사용할 수 있습니다.

공식 문서에서 사용 가능한 베타 기능을 확인하세요. 모델을 가져올 때도 추가 옵션을 전달할 수 있습니다.

customOpenAI('gpt-4-turbo', { user: 'user-123' })처럼 두 번째 인자로 모델별 설정을 넘깁니다. user 필드는 OpenAI에서 사용량을 사용자별로 추적할 때 사용됩니다.

남용 감지에도 활용됩니다. 주의할 점은 프로바이더마다 지원하는 옵션이 다르다는 것입니다.

OpenAI에만 있는 옵션을 Anthropic에 적용하려 하면 무시되거나 에러가 납니다. 각 프로바이더의 타입 정의나 공식 문서를 확인하세요.

TypeScript를 사용하면 자동완성으로 사용 가능한 옵션을 쉽게 확인할 수 있습니다. 김개발 씨가 감탄했습니다.

"와, 이렇게 세밀하게 조정할 수 있군요!" 박시니어 씨가 미소 지었습니다. "네, 처음에는 기본 설정으로 시작하고, 필요할 때 하나씩 커스터마이징하면 됩니다.

과도한 설정은 복잡성만 높이니까요."

실전 팁

💡 - 프록시를 사용할 때는 타임아웃 설정도 함께 검토하세요

• 베타 기능은 언제든 변경될 수 있으므로 프로덕션 사용에 주의하세요

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!