Runpod

Runpod

공식 Runpod 프로바이더는 공개 및 비공개 엔드포인트에 대한 언어 모델과 이미지 생성 지원을 포함해요.

출처: 문서

본문

Runpod 프로바이더는 @runpod/ai-sdk-provider 모듈에서 사용할 수 있어요. 다음과 같이 설치할 수 있어요:

npm install @runpod/ai-sdk-provider

프로바이더 인스턴스

@runpod/ai-sdk-provider에서 기본 프로바이더 인스턴스 runpod을 import 할 수 있어요:

import { runpod } from '@runpod/ai-sdk-provider';

커스텀 설정이 필요하다면 createRunpod을 import 해서 설정과 함께 프로바이더 인스턴스를 만들 수 있어요:

import { createRunpod } from '@runpod/ai-sdk-provider';

const runpod = createRunpod({
  apiKey: *** // optional, defaults to RUNPOD_API_KEY environment variable
  baseURL: 'custom-url', // optional, for custom endpoints
  headers: {
    /* custom headers */
  }, // optional
});

Runpod 프로바이더 인스턴스를 커스터마이즈하기 위해 다음의 선택적 설정을 사용할 수 있어요:

• baseURL string

  API 호출에 다른 URL 접두사를 사용해요. 예를 들어 프록시 서버나 커스텀 엔드포인트를 사용할 때 유용해요. vLLM 배포, SGLang 서버, 모든 OpenAI 호환 API를 지원해요. 기본 접두사는 https://api.runpod.ai/v2예요.

• apiKey string

  Authorization 헤더로 전송되는 API 키예요. 기본값은 RUNPOD_API_KEY 환경 변수예요. Runpod Console의 "API Keys"에서 API 키를 얻을 수 있어요.

• headers Record<string,string>

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

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

  커스텀 fetch 구현이에요. 요청을 가로채는 미들웨어로 사용하거나, 예를 들어 테스트를 위한 커스텀 fetch 구현을 제공하는 데 사용할 수 있어요.

언어 모델

프로바이더 인스턴스를 사용해 언어 모델을 만들 수 있어요. 첫 번째 인자는 모델 ID예요:

import { runpod } from '@runpod/ai-sdk-provider';
import { generateText } from 'ai';

const { text } = await generateText({
  model: runpod('qwen/qwen3-32b-awq'),
  prompt: 'What is the capital of Germany?',
});

반환값:

• text - 생성된 텍스트 문자열
• finishReason - 생성이 멈춘 이유 ('stop', 'length' 등)
• usage - 토큰 사용량 정보 (prompt, completion, total tokens)

스트리밍

import { runpod } from '@runpod/ai-sdk-provider';
import { streamText } from 'ai';

const { textStream } = await streamText({
  model: runpod('qwen/qwen3-32b-awq'),
  prompt:
    'Write a short poem about artificial intelligence in exactly 4 lines.',
  temperature: 0.7,
});

for await (const delta of textStream) {
  process.stdout.write(delta);
}

모델 기능

모델 ID	설명	스트리밍	객체 생성	도구 사용	추론 참고
qwen/qwen3-32b-awq	강력한 추론 기능을 갖춘 32B 파라미터 다국어 모델				표준 추론 이벤트
openai/gpt-oss-120b	120B 파라미터 오픈소스 GPT 모델				표준 추론 이벤트

참고: 사용 가능한 모든 모델의 최신 목록은 Runpod Public Endpoint Reference에서 찾을 수 있어요.

채팅 대화

const { text } = await generateText({
  model: runpod('qwen/qwen3-32b-awq'),
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is the capital of France?' },
  ],
});

도구 호출 (Tool Calling)

import { generateText, tool } from 'ai';
import { z } from 'zod';

const { text, toolCalls } = await generateText({
  model: runpod('openai/gpt-oss-120b'),
  prompt: 'What is the weather like in San Francisco?',
  tools: {
    getWeather: tool({
      description: 'Get weather information for a city',
      inputSchema: z.object({
        city: z.string().describe('The city name'),
      }),
      execute: async ({ city }) => {
        return `The weather in ${city} is sunny.`;
      },
    }),
  },
});

추가 반환값:

• toolCalls - 모델이 수행한 도구 호출 배열
• toolResults - 실행된 도구의 결과

구조화된 출력

이 프로바이더에 속한 두 모델은 Output을 사용한 구조화된 출력 강제를 지원하지 않아요.

모델에게 JSON을 반환하도록 지시하고 직접 검증하는 방식으로 여전히 구조화된 데이터를 얻을 수 있어요.

import { runpod } from '@runpod/ai-sdk-provider';
import { generateText } from 'ai';
import { z } from 'zod';

const RecipeSchema = z.object({
  name: z.string(),
  ingredients: z.array(z.string()),
  steps: z.array(z.string()),
});

const { text } = await generateText({
  model: runpod('qwen/qwen3-32b-awq'),
  messages: [
    {
      role: 'system',
      content:
        'return ONLY valid JSON matching { name: string; ingredients: string[]; steps: string[] }',
    },
    { role: 'user', content: 'generate a lasagna recipe.' },
  ],
  temperature: 0,
});

const parsed = JSON.parse(text);
const result = RecipeSchema.safeParse(parsed);

if (!result.success) {
  // handle invalid JSON shape
}

console.log(result.success ? result.data : parsed);

이미지 모델

.imageModel() 팩토리 메서드를 사용해 Runpod 이미지 모델을 만들 수 있어요.

기본 사용법

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

const { image } = await generateImage({
  model: runpod.imageModel('qwen/qwen-image'),
  prompt: 'A serene mountain landscape at sunset',
  aspectRatio: '4:3',
});

// Save to filesystem
import { writeFileSync } from 'fs';
writeFileSync('landscape.jpg', image.uint8Array);

반환값:

• image.uint8Array - 바이너리 이미지 데이터 (처리/저장에 효율적)
• image.base64 - Base64 인코딩 문자열 (웹 표시용)
• image.mediaType - MIME 타입 ('image/jpeg' 또는 'image/png')
• warnings - 지원되지 않는 파라미터에 대한 경고 배열

모델 기능

모델 ID	설명	지원되는 가로세로 비율
bytedance/seedream-3.0	고급 텍스트-이미지 모델	1:1, 4:3, 3:4
bytedance/seedream-4.0	텍스트-이미지 (v4)	1:1 (1024, 2048, 4096 지원)
bytedance/seedream-4.0-edit	이미지 편집 (v4, multi-image)	1:1 (1024, 1536, 2048, 4096 지원)
black-forest-labs/flux-1-schnell	빠른 이미지 생성 (4 steps)	1:1, 4:3, 3:4
black-forest-labs/flux-1-dev	고품질 이미지 생성	1:1, 4:3, 3:4
black-forest-labs/flux-1-kontext-dev	컨텍스트 인식 이미지 생성	1:1, 4:3, 3:4
qwen/qwen-image	텍스트-이미지 생성	1:1, 4:3, 3:4
qwen/qwen-image-edit	이미지 편집 (prompt-guided)	1:1, 4:3, 3:4

참고: 프로바이더는 이미지 파라미터에 엄격한 검증을 사용해요. 지원되지 않는 가로세로 비율(예: 16:9, 9:16, 3:2, 2:3)은 지원되는 대안에 대한 명확한 메시지와 함께 InvalidArgumentError를 던져요.

사용 가능한 모든 이미지 모델의 최신 목록은 Runpod Public Endpoint Reference에서 찾을 수 있어요.

고급 파라미터

const { image } = await generateImage({
  model: runpod.imageModel('bytedance/seedream-3.0'),
  prompt: 'A sunset over mountains',
  size: '1328x1328',
  seed: 42,
  providerOptions: {
    runpod: {
      negative_prompt: 'blurry, low quality',
      enable_safety_checker: true,
    },
  },
});

이미지 수정 (Modify Image)

텍스트 프롬프트로 기존 이미지를 변환해요.

// Example: Transform existing image
const { image } = await generateImage({
  model: runpod.imageModel('black-forest-labs/flux-1-kontext-dev'),
  prompt: 'Transform this into a cyberpunk style with neon lights',
  aspectRatio: '1:1',
  providerOptions: {
    runpod: {
      image: 'https://example.com/input-image.jpg',
    },
  },
});

// Example: Using base64 encoded image
const { image } = await generateImage({
  model: runpod.imageModel('black-forest-labs/flux-1-kontext-dev'),
  prompt: 'Make this image look like a painting',
  providerOptions: {
    runpod: {
      image: 'data:image/png;base64,iVBORw0KGgoAAAANS...',
    },
  },
});

고급 설정

// Full control over generation parameters
const { image } = await generateImage({
  model: runpod.imageModel('black-forest-labs/flux-1-dev'),
  prompt: 'A majestic dragon breathing fire in a medieval castle',
  size: '1328x1328',
  seed: 42, // For reproducible results
  providerOptions: {
    runpod: {
      negative_prompt: 'blurry, low quality, distorted, ugly, bad anatomy',
      enable_safety_checker: true,
      num_inference_steps: 50, // Higher quality (default: 28)
      guidance: 3.5, // Stronger prompt adherence (default: 2)
      output_format: 'png', // High quality format
      // Polling settings for long generations
      maxPollAttempts: 30,
      pollIntervalMillis: 4000,
    },
  },
});

// Fast generation with minimal steps
const { image } = await generateImage({
  model: runpod.imageModel('black-forest-labs/flux-1-schnell'),
  prompt: 'A simple red apple',
  aspectRatio: '1:1',
  providerOptions: {
    runpod: {
      num_inference_steps: 2, // Even faster (default: 4)
      guidance: 10, // Higher guidance for simple prompts
      output_format: 'jpg', // Smaller file size
    },
  },
});

프로바이더 옵션

Runpod 이미지 모델은 providerOptions.runpod 객체를 통해 유연한 프로바이더 옵션을 지원해요:

옵션	타입	기본값	설명
negative_prompt	string	""	이미지에 넣고 싶지 않은 것을 설명하는 텍스트
enable_safety_checker	boolean	true	콘텐츠 안전 필터링 활성화
image	string	-	입력 이미지: URL 또는 base64 데이터 URI (Flux Kontext 모델에 필요)
num_inference_steps	number	Auto	디노이징 단계 수 (Flux: schnell은 4, 나머지는 28)
guidance	number	Auto	프롬프트 준수를 위한 guidance scale (Flux: schnell은 7, 나머지는 2)
output_format	string	"png"	출력 이미지 형식 ("png" 또는 "jpg")
maxPollAttempts	number	60	비동기 생성을 위한 최대 폴링 시도 횟수
pollIntervalMillis	number	5000	폴링 간격 (밀리초, 5초)

더 알아보기 (Learn more)

• 출처 문서: Runpod