Replicate 프로바이더

Replicate 프로바이더

Replicate의 오픈소스 AI 모델 실행 플랫폼을 AI SDK에서 쓸 수 있게 해주는 프로바이더예요. 특히 이미지 생성 모델 실행에 많이 사용돼요.

출처: 문서

본문

Replicate는 오픈소스 AI 모델 실행을 위한 플랫폼이에요. 이미지 생성 모델 실행에 널리 사용되는 선택이에요.

설정 (Setup)

Replicate 프로바이더는 @ai-sdk/replicate 모듈로 제공돼요. 다음과 같이 설치할 수 있어요:

프로바이더 인스턴스 (Provider Instance)

@ai-sdk/replicate에서 기본 프로바이더 인스턴스 replicate를 불러올 수 있어요:

import { replicate } from '@ai-sdk/replicate';

커스터마이즈가 필요하다면 @ai-sdk/replicate에서 createReplicate를 불러와 원하는 설정으로 프로바이더 인스턴스를 만들 수 있어요:

import { createReplicate } from '@ai-sdk/replicate';

const replicate = createReplicate({
  apiToken: process.env.REPLICATE_API_TOKEN ?? '',
});

Replicate 프로바이더 인스턴스를 커스터마이즈할 때 사용할 수 있는 선택적 설정은 다음과 같아요:

  • baseURL string

    API 호출에 다른 URL 접두사를 사용해요. 예를 들어 프록시 서버를 쓸 때 유용해요. 기본 접두사는 https://api.replicate.com/v1이에요.

  • apiToken string

    Authorization 헤더로 보내는 API 토큰이에요. 기본값은 REPLICATE_API_TOKEN 환경 변수예요.

  • headers Record<string,string>

    요청에 포함할 커스텀 헤더예요.

  • fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

    커스텀 fetch 구현이에요.

이미지 모델 (Image Models)

.image() 팩토리 메서드로 Replicate 이미지 모델을 만들 수 있어요. AI SDK에서 이미지 생성에 대해 더 알고 싶다면 generateImage()를 참고하세요.

`size` 및 기타 파라미터의 모델 지원 여부는 모델마다 달라요. 지원되는 옵션과 `providerOptions.replicate`로 전달할 수 있는 추가 파라미터는 [Replicate](https://replicate.com/explore)의 모델 문서를 확인하세요.

지원되는 이미지 모델 (Supported Image Models)

Replicate 프로바이더가 현재 지원하는 이미지 모델은 다음과 같아요:

텍스트-이미지 모델:

인페인팅 및 이미지 편집 모델:

Flux-2 모델 (다중 참조 이미지 생성):

이 모델들은 스타일 전이와 구성을 위해 최대 8개의 입력 참조 이미지를 지원해요:

버전이 있는 모델을 사용할 수도 있어요. 버전 모델의 id는 Replicate 모델 id 뒤에 콜론과 버전 ID가 오는 형태($modelId:$versionId)예요. 예: bytedance/sdxl-lightning-4step:5599ed30703defd1d160a25a63321b4dec97101d98b4674bcc56e41f62f35637.

필요하다면 사용 가능한 Replicate 모델 ID를 문자열로 전달할 수도 있어요.

기본 사용법 (Basic Usage)

import { replicate } from '@ai-sdk/replicate';
import { generateImage } from 'ai';
import { writeFile } from 'node:fs/promises';

const { image } = await generateImage({
  model: replicate.image('black-forest-labs/flux-schnell'),
  prompt: 'The Loch Ness Monster getting a manicure',
  aspectRatio: '16:9',
});

await writeFile('image.webp', image.uint8Array);

console.log('Image saved as image.webp');

모델별 옵션 (Model-specific options)

import { replicate, type ReplicateImageModelOptions } from '@ai-sdk/replicate';
import { generateImage } from 'ai';

const { image } = await generateImage({
  model: replicate.image('recraft-ai/recraft-v3'),
  prompt: 'The Loch Ness Monster getting a manicure',
  size: '1365x1024',
  providerOptions: {
    replicate: {
      style: 'realistic_image',
    } satisfies ReplicateImageModelOptions,
  },
});

버전 모델 (Versioned Models)

import { replicate } from '@ai-sdk/replicate';
import { generateImage } from 'ai';

const { image } = await generateImage({
  model: replicate.image(
    'bytedance/sdxl-lightning-4step:5599ed30703defd1d160a25a63321b4dec97101d98b4674bcc56e41f62f35637',
  ),
  prompt: 'The Loch Ness Monster getting a manicure',
});

이미지 편집 (Image Editing)

Replicate은 다양한 모델을 통한 이미지 편집을 지원해요. prompt.images로 입력 이미지를 전달해 기존 이미지를 변형하거나 편집할 수 있어요.

기본 이미지 편집 (Basic Image Editing)

텍스트 프롬프트로 기존 이미지를 변형해요:

const imageBuffer = readFileSync('./input-image.png');

const { images } = await generateImage({
  model: replicate.image('black-forest-labs/flux-fill-dev'),
  prompt: {
    text: 'Turn the cat into a golden retriever dog',
    images: [imageBuffer],
  },
  providerOptions: {
    replicate: {
      guidance_scale: 7.5,
      num_inference_steps: 30,
    } satisfies ReplicateImageModelOptions,
  },
});

마스크로 인페인팅 (Inpainting with Mask)

마스크를 사용해 이미지의 특정 부분을 편집해요. FLUX Fill 모델의 경우 마스크의 흰색 영역이 편집할 위치를 나타내요:

const image = readFileSync('./input-image.png');
const mask = readFileSync('./mask.png'); // White = inpaint, black = keep

const { images } = await generateImage({
  model: replicate.image('black-forest-labs/flux-fill-pro'),
  prompt: {
    text: 'A sunlit indoor lounge area with a pool containing a flamingo',
    images: [image],
    mask: mask,
  },
  providerOptions: {
    replicate: {
      guidance_scale: 7.5,
      num_inference_steps: 30,
    } satisfies ReplicateImageModelOptions,
  },
});

다중 참조 이미지 생성 (Flux-2) (Multi-Reference Image Generation)

Flux-2 모델은 스타일 전이, 구성, 다중 대상 생성을 위해 최대 8개의 입력 참조 이미지를 지원해요:

import { replicate } from '@ai-sdk/replicate';
import { generateImage } from 'ai';

const reference1 = readFileSync('./style-reference.png');
const reference2 = readFileSync('./subject-reference.png');

const { images } = await generateImage({
  model: replicate.image('black-forest-labs/flux-2-pro'),
  prompt: {
    text: 'Combine the style and subjects from the reference images',
    images: [reference1, reference2],
  },
});
Flux-2 모델은 내부적으로 다른 입력 형식(`input_image`, `input_image_2` 등)을 사용하며 자동으로 처리돼요. Flux-2 모델은 마스크 기반 인페인팅을 지원하지 않는다는 점에 유의하세요. 입력 이미지는 `Buffer`, `ArrayBuffer`, `Uint8Array` 또는 base64로 인코딩된 문자열로 제공할 수 있어요. 각 Replicate 모델은 서로 다른 파라미터 이름과 기능을 가지므로 자세한 내용은 [Replicate](https://replicate.com/explore)의 모델 문서를 확인하세요.

프로바이더 옵션 (Provider Options)

이미지 생성의 일반적인 프로바이더 옵션:

  • maxWaitTimeInSeconds number - 동기 모드에서 예측이 완료될 때까지 기다릴 최대 시간(초). 기본적으로 Replicate는 60초 타임아웃의 동기 모드를 사용해요. 커스텀 기간(예: 2분을 위한 120)을 사용하려면 양수로 설정하세요. 지정하지 않으면 기본 60초 대기를 사용해요.
  • pollIntervalMillis number - 동기 대기 기간 내에 예측이 완료되지 않을 때 폴링 시도 사이의 간격(밀리초). 기본값은 500밀리초.
  • maxPollAttempts number - 포기하기 전 최대 폴링 시도 횟수. 기본값은 240회.
  • guidance_scale number - classifier-free guidance를 위한 가이던스 스케일. 값이 높을수록 출력이 프롬프트와 더 가깝게 일치해요.
  • num_inference_steps number - 디노이징 스텝 수. 스텝이 많을수록 품질은 높아지지만 느려져요.
  • negative_prompt string - 생성에서 피하고 싶은 것을 안내하는 네거티브 프롬프트.
  • output_format 'png' | 'jpg' | 'webp' - 출력 이미지 형식.
  • output_quality number (1-100) - 출력 이미지 품질. jpg와 webp에만 적용돼요.
  • strength number (0-1) - img2img를 위한 변형 강도. 값이 낮을수록 원본 이미지를 더 많이 유지해요.

자세한 내용은 Replicate 모델 페이지를 참고하세요.

더 알아보기 (Learn more)

전체 사이트맵