Fireworks Provider — Fireworks 프로바이더

Fireworks의 LLM 실행·테스트 플랫폼을 AI SDK에서 사용하는 방법을 알려드려요. Fireworks는 API를 통해 LLM을 실행·테스트하기 위한 플랫폼이에요.

출처: 문서

본문

Fireworks는 API를 통해 LLM을 실행·테스트하기 위한 플랫폼이에요.

설정 (Setup)

Fireworks 프로바이더는 @ai-sdk/fireworks 모듈을 통해 사용할 수 있어요. 다음으로 설치할 수 있어요:

npm install @ai-sdk/fireworks

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

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

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

맞춤 설정이 필요하면 @ai-sdk/fireworks에서 createFireworks를 import하고 설정으로 프로바이더 인스턴스를 만들 수 있어요:

import { createFireworks } from '@ai-sdk/fireworks';

const fireworks = createFireworks({
  apiKey: proces..._KEY ?? '',
});

Fireworks 프로바이더 인스턴스를 맞춤 설정하는 데 사용할 수 있는 선택적 설정은 다음과 같아요:

baseURL string — API 호출에 다른 URL 접두사를 사용해요 (예: 프록시 서버). 기본 접두사는 https://api.fireworks.ai/inference/v1이에요.
apiKey string — Authorization 헤더로 보내지는 API 키. 기본값은 FIREWORKS_API_KEY 환경 변수예요.
headers Record<string,string> — 요청에 포함할 커스텀 헤더.
fetch (input: RequestInfo, init?: RequestInit) => Promise<Response> — 커스텀 fetch 구현.

언어 모델 (Language Models)

프로바이더 인스턴스로 Fireworks 모델을 만들 수 있어요. 첫 번째 인자는 모델 ID예요 (예: accounts/fireworks/models/firefunction-v1):

const model = fireworks('accounts/fireworks/models/firefunction-v1');

Reasoning 모델 (Reasoning Models)

Fireworks는 deepseek-r1의 thinking을 thinking 태그를 사용해 생성된 텍스트에 노출해요. extractReasoningMiddleware를 사용해 이 reasoning을 추출하고 결과의 reasoning 속성으로 노출할 수 있어요:

import { fireworks } from '@ai-sdk/fireworks';
import { wrapLanguageModel, extractReasoningMiddleware } from 'ai';

const enhancedModel = wrapLanguageModel({
  model: fireworks('accounts/fireworks/models/deepseek-r1'),
  middleware: extractReasoningMiddleware({ tagName: 'think' }),
});

그런 다음 generateText와 streamText 같은 함수에서 이 향상된 모델을 사용할 수 있어요.

예시

generateText 함수로 Fireworks 언어 모델을 사용해 텍스트를 생성할 수 있어요:

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

const { text } = await generateText({
  model: fireworks('accounts/fireworks/models/firefunction-v1'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

Fireworks 언어 모델은 streamText 함수에서도 사용할 수 있어요 (AI SDK Core 참고).

프로바이더 옵션 (Provider Options)

Fireworks 채팅 모델은 표준 호출 설정의 일부가 아닌 추가 프로바이더 옵션을 지원해요. providerOptions 인자로 전달할 수 있어요:

import {
  fireworks,
  type FireworksLanguageModelOptions,
} from '@ai-sdk/fireworks';
import { generateText } from 'ai';

const { text, reasoningText } = await generateText({
  model: fireworks('accounts/fireworks/models/kimi-k2p6'),
  providerOptions: {
    fireworks: {
      thinking: { type: 'enabled', budgetTokens: 4096 },
      reasoningHistory: 'interleaved',
    } satisfies FireworksLanguageModelOptions,
  },
  prompt: 'How many "r"s are in the word "strawberry"?',
});

Fireworks 채팅 모델에 사용할 수 있는 선택적 프로바이더 옵션은 다음과 같아요:

promptCacheKey string — 공유 프롬프트 접두사를 가진 요청을 같은 Fireworks replica로 라우팅해 프롬프트 캐시 적중률을 개선하는 안정적이고 불투명한 키. 한 대화의 모든 단계와 호출에 같은 키를 재사용하고, 관련 없는 대화에는 다른 키를 사용하세요.
serviceTier 'priority' — 피크 트래픽 동안 더 높은 신뢰성을 위해 Fireworks Priority 서빙 경로를 사용해요. 프로바이더는 Fireworks의 service_tier 요청 필드로 보내요.
thinking object — Kimi K2.6 같은 thinking/reasoning 모델에 대한 구성.
- type 'enabled' | 'disabled' — thinking 모드 활성화 여부.
- budgetTokens number — thinking의 최대 토큰 수 (최소 1024).
reasoningHistory 'disabled' | 'interleaved' | 'preserved' — 다중 턴 대화에서 reasoning 이력 처리 방식을 제어해요:
- 'disabled': 이력에서 reasoning 제거
- 'interleaved': 단일 턴 안에서 도구 호출 사이에 reasoning 포함
- 'preserved': 모든 reasoning을 이력에 유지

프롬프트 캐시 선호 (Prompt Cache Affinity)

Fireworks 프롬프트 캐싱은 자동이지만, 캐시된 접두사는 replica에 국한돼요. promptCacheKey를 불투명한 세션 또는 대화 식별자로 설정해 캐시 선호도를 개선하세요. 프로바이더는 이를 Fireworks의 prompt_cache_key 요청 필드로 보내요.

AI SDK는 다중 단계 generateText 또는 streamText 호출의 모든 모델 단계에 대해 같은 프로바이더 옵션을 재사용하므로, 하나의 키가 완전한 도구 루프를 커버해요:

import {
  fireworks,
  type FireworksLanguageModelOptions,
} from '@ai-sdk/fireworks';
import { generateText, isStepCount, tool } from 'ai';
import { z } from 'zod';

const sessionId = 'conversation-123';

const result = await generateText({
  model: fireworks('accounts/fireworks/models/kimi-k2p6'),
  providerOptions: {
    fireworks: {
      promptCacheKey: sessionId,
    } satisfies FireworksLanguageModelOptions,
  },
  tools: {
    weather: tool({
      description: 'Get the weather for a city.',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => `It is sunny in ${city}.`,
    }),
  },
  stopWhen: isStepCount(5),
  prompt: 'What is the weather in San Francisco?',
});

console.log(result.usage.inputTokenDetails.cacheReadTokens);

재사용 가능한 ToolLoopAgent의 경우 호출 옵션을 사용해 각 대화에 키를 제공하세요. 그 대화를 이어가는 이후 에이전트 호출에도 같은 키를 다시 전달하세요:

import {
  fireworks,
  type FireworksLanguageModelOptions,
} from '@ai-sdk/fireworks';
import { ToolLoopAgent } from 'ai';
import { z } from 'zod';
import { weatherTool } from './weather-tool';

const agent = new ToolLoopAgent({
  model: fireworks('accounts/fireworks/models/kimi-k2p6'),
  callOptionsSchema: z.object({
    sessionId: z.string(),
  }),
  prepareCall: ({ options, ...settings }) => ({
    ...settings,
    providerOptions: {
      fireworks: {
        promptCacheKey: options.sessionId,
      } satisfies FireworksLanguageModelOptions,
    },
  }),
  tools: { weather: weatherTool },
});

const result = await agent.generate({
  prompt: 'What is the weather in San Francisco?',
  options: {
    sessionId: 'conversation-123',
  },
});

캐시 키에는 이메일 주소나 다른 개인 정보 대신 식별되지 않는 값을 사용하세요.

우선순위 서비스 티어 (Priority Service Tier)

Fireworks Priority 티어는 지원되는 모델을 Standard 트래픽보다 우선시해요. serviceTier를 'priority'로 설정해 Fireworks의 service_tier 요청 필드를 보내세요:

import {
  fireworks,
  type FireworksLanguageModelOptions,
} from '@ai-sdk/fireworks';
import { generateText } from 'ai';

const result = await generateText({
  model: fireworks('accounts/fireworks/models/glm-5p2'),
  providerOptions: {
    fireworks: {
      serviceTier: 'priority',
    } satisfies FireworksLanguageModelOptions,
  },
  prompt: 'Write a haiku about reliable inference.',
});

완성 모델 (Completion Models)

.completionModel() 팩토리 메서드로 Fireworks completions API를 호출하는 모델을 만들 수 있어요:

const model = fireworks.completionModel(
  'accounts/fireworks/models/firefunction-v1',
);

모델 기능 (Model Capabilities)

Model	Image Input	Object Generation	Tool Usage	Tool Streaming
`accounts/fireworks/models/firefunction-v1`	✗	✓	✓	✓
`accounts/fireworks/models/deepseek-r1`	✗	✓	✗	✗
`accounts/fireworks/models/deepseek-v3`	✗	✓	✓	✗
`accounts/fireworks/models/llama-v3p1-405b-instruct`	✗	✓	✓	✓
`accounts/fireworks/models/llama-v3p1-8b-instruct`	✗	✓	✓	✗
`accounts/fireworks/models/llama-v3p2-3b-instruct`	✗	✓	✓	✗
`accounts/fireworks/models/llama-v3p3-70b-instruct`	✗	✓	✓	✗
`accounts/fireworks/models/mixtral-8x7b-instruct`	✗	✓	✓	✗
`accounts/fireworks/models/mixtral-8x7b-instruct-hf`	✗	✓	✓	✗
`accounts/fireworks/models/mixtral-8x22b-instruct`	✗	✓	✓	✗
`accounts/fireworks/models/qwen2p5-coder-32b-instruct`	✗	✓	✓	✗
`accounts/fireworks/models/qwen2p5-72b-instruct`	✗	✓	✓	✗
`accounts/fireworks/models/qwen-qwq-32b-preview`	✗	✓	✗	✗
`accounts/fireworks/models/qwen2-vl-72b-instruct`	✓	✓	✗	✗
`accounts/fireworks/models/llama-v3p2-11b-vision-instruct`	✓	✓	✓	✗
`accounts/fireworks/models/qwq-32b`	✗	✓	✗	✗
`accounts/fireworks/models/yi-large`	✗	✓	✓	✗
`accounts/fireworks/models/kimi-k2-instruct`	✗	✓	✓	✗
`accounts/fireworks/models/kimi-k2-thinking`	✗	✓	✓	✗
`accounts/fireworks/models/kimi-k2p6`	✓	✓	✓	✗
`accounts/fireworks/models/minimax-m2`	✗	✓	✓	✗

위 표는 인기 모델을 나열한 거예요. 전체 사용 가능 모델 목록은 Fireworks models page를 참고하세요.

임베딩 모델 (Embedding Models)

.embeddingModel() 팩토리 메서드로 Fireworks embeddings API를 호출하는 모델을 만들 수 있어요:

const model = fireworks.embeddingModel('nomic-ai/nomic-embed-text-v1.5');

embed 함수로 Fireworks 임베딩 모델을 사용해 임베딩을 생성할 수 있어요:

import { fireworks } from '@ai-sdk/fireworks';
import { embed } from 'ai';

const { embedding } = await embed({
  model: fireworks.embeddingModel('nomic-ai/nomic-embed-text-v1.5'),
  value: 'sunny day at the beach',
});

모델 기능 (Model Capabilities)

Model	Dimensions	Max Tokens
`nomic-ai/nomic-embed-text-v1.5`	768	8192

더 많은 임베딩 모델은 Fireworks models page에서 사용 가능한 모델 전체 목록을 참고하세요.

이미지 모델 (Image Models)

.image() 팩토리 메서드로 Fireworks 이미지 모델을 만들 수 있어요. AI SDK의 이미지 생성에 대한 자세한 내용은 generateImage()를 참고하세요.

import { fireworks, type FireworksImageModelOptions } from '@ai-sdk/fireworks';
import { generateImage } from 'ai';

const { image } = await generateImage({
  model: fireworks.image('accounts/fireworks/models/flux-1-dev-fp8'),
  prompt: 'A futuristic cityscape at sunset',
  aspectRatio: '16:9',
  providerOptions: {
    fireworks: {
      guidance_scale: 4.5,
      num_inference_steps: 8,
    } satisfies FireworksImageModelOptions,
  },
});

size와 aspectRatio 파라미터에 대한 모델 지원은 다양해요. 지원되는 차원은 아래 모델 기능 섹션을 참고하거나, Fireworks models page에서 모델 문서를 확인하세요.

프로바이더 옵션 (Provider Options)

Fireworks 이미지 모델은 providerOptions.fireworks 객체를 통해 유연한 프로바이더 옵션을 지원해요. FireworksImageModelOptions 타입을 사용해 알려진 Fireworks 이미지 옵션을 검증하면서도 모델 특정 옵션이 통과하도록 허용해요.

다음 타입화된 프로바이더 옵션이 사용 가능해요:

guidance_scale number — 이미지 확산(diffusion) 프로세스의 classifier-free guidance scale.
num_inference_steps number — FLUX 워크플로 이미지 생성을 위한 denoising 단계 수.
output_format 'jpeg' | 'png' — FLUX Kontext 이미지 생성·편집에 원하는 출력 형식.
prompt_upsampling boolean — Fireworks가 더 창의적인 생성을 위해 프롬프트를 자동 수정할지 여부.
safety_tolerance number — 입력·출력에 대한 중재 허용 수준, 0부터 6까지. Fireworks는 이미지-이미지 요청을 2로 제한해요.
webhook_url string — 비동기 Kontext 요청에 대한 웹훅 알림을 받을 URL.
webhook_secret string — 웹훅 서명 검증을 위한 시크릿.
cfg_scale number — 레거시 image_generation 모델에 대한 guidance scale.
steps number — 레거시 image_generation 모델에 대한 생성 단계 수.

이미지 편집 (Image Editing)

Fireworks는 FLUX Kontext 모델(flux-kontext-pro 및 flux-kontext-max)을 통한 이미지 편집을 지원해요. prompt.images로 입력 이미지를 전달해 기존 이미지를 변환하거나 편집해요.

Fireworks Kontext 모델은 명시적 마스크를 지원하지 않아요. 편집은 프롬프트 기반이에요 — 텍스트 프롬프트에서 바꾸고 싶은 것을 설명하세요.

기본 이미지 편집

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

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

const { images } = await generateImage({
  model: fireworks.image('accounts/fireworks/models/flux-kontext-pro'),
  prompt: {
    text: 'Turn the cat into a golden retriever dog',
    images: [imageBuffer],
  },
  providerOptions: {
    fireworks: {
      output_format: 'jpeg',
      safety_tolerance: 2,
    } satisfies FireworksImageModelOptions,
  },
});

스타일 전송 (Style Transfer)

이미지에 예술적 스타일을 적용해요:

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

const { images } = await generateImage({
  model: fireworks.image('accounts/fireworks/models/flux-kontext-pro'),
  prompt: {
    text: 'Transform this into a watercolor painting style',
    images: [imageBuffer],
  },
  aspectRatio: '1:1',
});

입력 이미지는 Buffer, ArrayBuffer, Uint8Array, 또는 base64 인코딩 문자열로 제공할 수 있어요. Fireworks는 요청당 단일 입력 이미지만 지원해요.

모델 기능 (Model Capabilities)

aspect ratio를 지원하는 모든 모델에 대해 다음 aspect ratio가 지원돼요:

1:1 (default), 2:3, 3:2, 4:5, 5:4, 16:9, 9:16, 9:21, 21:9

size를 지원하는 모든 모델에 대해 다음 크기가 지원돼요:

640 x 1536, 768 x 1344, 832 x 1216, 896 x 1152, 1024x1024 (default), 1152 x 896, 1216 x 832, 1344 x 768, 1536 x 640

Model	Dimensions Specification	Image Editing
`accounts/fireworks/models/flux-kontext-pro`	Aspect Ratio	✓
`accounts/fireworks/models/flux-kontext-max`	Aspect Ratio	✓
`accounts/fireworks/models/flux-1-dev-fp8`	Aspect Ratio	✗
`accounts/fireworks/models/flux-1-schnell-fp8`	Aspect Ratio	✗
`accounts/fireworks/models/playground-v2-5-1024px-aesthetic`	Size	✗
`accounts/fireworks/models/japanese-stable-diffusion-xl`	Size	✗
`accounts/fireworks/models/playground-v2-1024px-aesthetic`	Size	✗
`accounts/fireworks/models/SSD-1B`	Size	✗
`accounts/fireworks/models/stable-diffusion-xl-1024-v1-0`	Size	✗

자세한 내용은 Fireworks models page를 참고하세요.

Stability AI 모델

Fireworks는 Stability AI API 키와 엔드포인트로 지원되는 몇 가지 Stability AI 모델도 제공해요. AI SDK Fireworks 프로바이더는 현재 이러한 모델을 지원하지 않아요:

Model ID
`accounts/stability/models/sd3-turbo`
`accounts/stability/models/sd3-medium`
`accounts/stability/models/sd3`

더 알아보기 (Learn more)

AI SDK Core — 코어 기능
OpenAI Provider — OpenAI 프로바이더