Groq 프로바이더

Groq 프로바이더

Groq API에 대한 언어 모델 지원을 제공하는 AI SDK 프로바이더예요. @ai-sdk/groq 패키지로 사용할 수 있어요.

출처: 문서

본문

Groq 프로바이더는 Groq API에 대한 언어 모델 지원을 제공해요.

설정 (Setup)

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

npm install @ai-sdk/groq

프로바이더 인스턴스

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

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

커스터마이즈된 설정이 필요하다면 @ai-sdk/groq에서 createGroq를 import하고 설정으로 프로바이더 인스턴스를 만들 수 있어요:

import { createGroq } from '@ai-sdk/groq';

const groq = createGroq({
  // custom settings
});

Groq 프로바이더 인스턴스를 커스터마이즈하려면 다음 선택 설정을 사용할 수 있어요:

  • baseURL string

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

  • apiKey string

    Authorization 헤더로 보내는 API 키. 기본값은 GROQ_API_KEY 환경 변수예요.

  • headers Record<string,string>

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

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

    커스텀 fetch 구현. 기본값은 전역 fetch 함수예요. 요청을 가로채는 미들웨어로 사용하거나, 예를 들어 테스트용 커스텀 fetch 구현을 제공할 수 있어요.

언어 모델 (Language Models)

프로바이더 인스턴스를 사용해 Groq 모델을 만들 수 있어요. 첫 번째 인자는 모델 id예요(예: llama-3.1-8b-instant).

const model = groq('llama-3.1-8b-instant');

추론 모델 (Reasoning Models)

Groq는 qwen/qwen3.6-27b, openai/gpt-oss-120b 같은 추론 모델을 제공해요. reasoningFormat 옵션을 사용해 생성된 텍스트에서 추론이 어떻게 노출되는지 설정할 수 있어요. parsed, hidden, raw 옵션을 지원해요.

import { groq, type GroqLanguageModelChatOptions } from '@ai-sdk/groq';
import { generateText } from 'ai';

const result = await generateText({
  model: groq('qwen/qwen3.6-27b'),
  providerOptions: {
    groq: {
      reasoningFormat: 'parsed',
      reasoningEffort: 'default',
      parallelToolCalls: true, // Enable parallel function calling (default: true)
      user: 'user-123', // Unique identifier for end-user (optional)
      serviceTier: 'flex', // Use flex tier for higher throughput (optional)
    } satisfies GroqLanguageModelChatOptions,
  },
  prompt: 'How many "r"s are in the word "strawberry"?',
});

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

  • reasoningFormat 'parsed' | 'raw' | 'hidden'

    생성된 텍스트에서 추론이 어떻게 노출되는지 제어해요. qwen/qwen3.6-27b 같은 추론 모델에서 지원되며, 사용 가능한 형식은 모델에 따라 달라져요.

    추론 모델 전체 목록과 기능은 Groq의 추론 모델 문서를 참고하세요.

  • reasoningEffort 'low' | 'medium' | 'high' | 'none' | 'default'

    모델이 추론에 투입할 노력 수준을 제어해요.

    • qwen/qwen3.6-27b
      • 지원 값:
        • none: 추론 비활성화. 모델은 추론 토큰을 전혀 사용하지 않아요.
        • default: 추론 활성화.
    • gpt-oss20b/gpt-oss120b
      • 지원 값:
        • low: 낮은 수준의 추론 노력 사용.
        • medium: 중간 수준의 추론 노력 사용.
        • high: 높은 수준의 추론 노력 사용.

    qwen/qwen3.6-27b의 기본값은 default예요.

  • structuredOutputs boolean

    구조화된 출력을 사용할지 여부.

    기본값은 true예요.

    활성화하면 객체 생성이 json_object 형식 대신 json_schema 형식을 사용해 더 안정적인 구조화된 출력을 제공해요.

  • strictJsonSchema boolean

    엄격한 JSON 스키마 검증을 사용할지 여부. true면 모델이 제한된 디코딩(constrained decoding)을 사용해 스키마 준수를 보장해요.

    기본값은 true예요.

    structuredOutputs가 활성화되고 스키마가 제공된 경우에만 사용돼요. 엄격 모드 제한 사항에 대한 자세한 내용은 Groq의 Structured Outputs 문서를 참고하세요.

  • parallelToolCalls boolean

    툴 사용 중 병렬 함수 호출을 활성화할지 여부. 기본값은 true예요.

  • user string

    최종 사용자를 나타내는 고유 식별자. 모니터링과 남용 탐지에 도움이 돼요.

  • serviceTier 'on_demand' | 'performance' | 'flex' | 'auto'

    요청의 서비스 티어. 기본값은 'on_demand'예요.

    • 'on_demand': 일관된 성능과 공정성을 제공하는 기본 티어
    • 'performance': 레이턴시에 민감한 워크로드를 위한 우선순위 티어
    • 'flex': 가끔 요청 실패를 감당할 수 있는 워크로드에 최적화된 더 높은 처리량 티어(10배 rate limit)
    • 'auto': 먼저 on_demand rate limit을 사용하고, 초과하면 flex 티어로 대체

    서비스 티어와 이점에 대한 자세한 내용은 Groq의 서비스 티어 문서를 참고하세요.

추론 모델만 reasoningFormat 옵션을 지원해요.

구조화된 출력 (Structured Outputs)

구조화된 출력은 Groq 모델에서 기본적으로 활성화되어 있어요. structuredOutputs 옵션을 false로 설정하면 비활성화할 수 있어요.

import { groq } from '@ai-sdk/groq';
import { generateText, Output } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: groq('moonshotai/kimi-k2-instruct-0905'),
  output: Output.object({
    schema: z.object({
      recipe: z.object({
        name: z.string(),
        ingredients: z.array(z.string()),
        instructions: z.array(z.string()),
      }),
    }),
  }),
  prompt: 'Generate a simple pasta recipe.',
});

console.log(JSON.stringify(result.output, null, 2));

구조화된 출력을 지원하지 않는 모델에서는 비활성화할 수 있어요:

import { groq, type GroqLanguageModelChatOptions } from '@ai-sdk/groq';
import { generateText, Output } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: groq('llama-3.1-8b-instant'),
  providerOptions: {
    groq: {
      structuredOutputs: false,
    } satisfies GroqLanguageModelChatOptions,
  },
  output: Output.object({
    schema: z.object({
      recipe: z.object({
        name: z.string(),
        ingredients: z.array(z.string()),
        instructions: z.array(z.string()),
      }),
    }),
  }),
  prompt: 'Generate a simple pasta recipe in JSON format.',
});

console.log(JSON.stringify(result.output, null, 2));
구조화된 출력은 `moonshotai/kimi-k2-instruct-0905` 같은 최신 Groq 모델에서만 지원돼요. 지원하지 않는 모델에서는 `structuredOutputs: false`로 설정해 구조화된 출력을 비활성화할 수 있어요. 비활성화하면 Groq는 `json_object` 형식을 사용하는데, 이 경우 메시지에 "JSON"이라는 단어가 포함되어야 해요.

예시

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

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

const { text } = await generateText({
  model: groq('llama-3.1-8b-instant'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

이미지 입력 (Image Input)

meta-llama/llama-4-scout-17b-16e-instruct 같은 Groq의 다중 모달 모델은 이미지 입력을 지원해요. URL 또는 base64 인코딩 데이터를 사용해 메시지에 이미지를 포함할 수 있어요:

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

const { text } = await generateText({
  model: groq('meta-llama/llama-4-scout-17b-16e-instruct'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'What do you see in this image?' },
        {
          type: 'file',
          mediaType: 'image',
          data: 'https://example.com/image.jpg',
        },
      ],
    },
  ],
});

base64 인코딩 이미지도 사용할 수 있어요:

import { groq } from '@ai-sdk/groq';
import { generateText } from 'ai';
import { readFileSync } from 'fs';

const imageData = readFileSync('path/to/image.jpg', 'base64');

const { text } = await generateText({
  model: groq('meta-llama/llama-4-scout-17b-16e-instruct'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Describe this image in detail.' },
        {
          type: 'file',
          mediaType: 'image',
          data: `data:image/jpeg;base64,${imageData}`,
        },
      ],
    },
  ],
});

모델 기능 (Model Capabilities)

Model Image Input Object Generation Tool Usage Tool Streaming
gemma2-9b-it
llama-3.1-8b-instant
llama-3.3-70b-versatile
meta-llama/llama-guard-4-12b
deepseek-r1-distill-llama-70b
meta-llama/llama-4-maverick-17b-128e-instruct
meta-llama/llama-4-scout-17b-16e-instruct
meta-llama/llama-prompt-guard-2-22m
meta-llama/llama-prompt-guard-2-86m
moonshotai/kimi-k2-instruct-0905
qwen/qwen3.6-27b
llama-guard-3-8b
llama3-70b-8192
llama3-8b-8192
mixtral-8x7b-32768
qwen-qwq-32b
qwen-2.5-32b
deepseek-r1-distill-qwen-32b
openai/gpt-oss-20b
openai/gpt-oss-120b
위 표는 가장 흔히 사용되는 모델을 나열한 거예요. 전체 사용 가능한 모델 목록은 [Groq 문서](https://console.groq.com/docs/models)를 참고하세요. 필요하면 사용 가능한 프로바이더 모델 ID를 문자열로 전달할 수도 있어요.

브라우저 검색 툴 (Browser Search Tool)

Groq는 인터랙티브한 웹 브라우징 기능을 제공하는 브라우저 검색 툴을 제공해요. 전통적인 웹 검색과 달리, 브라우저 검색은 웹사이트를 인터랙티브하게 탐색해 더 상세하고 종합적인 결과를 제공해요.

지원 모델

브라우저 검색은 다음 특정 모델에서만 사용할 수 있어요:

  • openai/gpt-oss-20b
  • openai/gpt-oss-120b
브라우저 검색은 위에 나열된 지원 모델에서만 작동해요. 다른 모델에서 사용하면 경고가 생성되고 툴이 무시돼요.

기본 사용법

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

const result = await generateText({
  model: groq('openai/gpt-oss-120b'), // Must use supported model
  prompt:
    'What are the latest developments in AI? Please search for recent news.',
  tools: {
    browser_search: groq.tools.browserSearch({}),
  },
  toolChoice: 'required', // Ensure the tool is used
});

console.log(result.text);

스트리밍 예시

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

const result = streamText({
  model: groq('openai/gpt-oss-120b'),
  prompt: 'Search for the latest tech news and summarize it.',
  tools: {
    browser_search: groq.tools.browserSearch({}),
  },
  toolChoice: 'required',
});

for await (const delta of result.stream) {
  if (delta.type === 'text-delta') {
    process.stdout.write(delta.text);
  }
}

주요 기능

  • 인터랙티브 브라우징: 사람처럼 웹사이트를 탐색해요
  • 종합적인 결과: 전통적인 검색 스니펫보다 더 상세해요
  • 서버 측 실행: Groq 인프라에서 실행되며 별도 설정이 필요 없어요
  • Exa 기반: 최적의 결과를 위해 Exa 검색 엔진을 사용해요
  • 현재 무료: 베타 기간 동안 추가 비용 없이 사용 가능해요

모범 사례

  • 브라우저 검색이 활성화되도록 toolChoice: 'required'를 사용하세요
  • openai/gpt-oss-20b와 openai/gpt-oss-120b 모델에서만 지원돼요
  • 툴은 자동으로 작동하므로 설정 파라미터가 필요 없어요
  • 서버 측 실행이므로 추가 API 키나 설정이 필요 없어요

모델 검증

프로바이더는 모델 호환성을 자동으로 검증해요:

// ✅ Supported - will work
const result = await generateText({
  model: groq('openai/gpt-oss-120b'),
  tools: { browser_search: groq.tools.browserSearch({}) },
});

// ❌ Unsupported - will show warning and ignore tool
const result = await generateText({
  model: groq('llama-3.1-8b-instant'),
  tools: { browser_search: groq.tools.browserSearch({}) },
});
// Warning: "Browser search is only supported on models: openai/gpt-oss-20b, openai/gpt-oss-120b"
브라우저 검색 기능과 제한 사항에 대한 자세한 내용은 [Groq Browser Search Documentation](https://console.groq.com/docs/browser-search)을 참고하세요.

트랜스크립션 모델 (Transcription Models)

.transcription() 팩토리 메서드를 사용해 Groq 트랜스크립션 API를 호출하는 모델을 만들 수 있어요.

첫 번째 인자는 모델 id예요(예: whisper-large-v3).

const model = groq.transcription('whisper-large-v3');

providerOptions 인자를 사용해 추가 프로바이더별 옵션을 전달할 수도 있어요. 예를 들어 입력 언어를 ISO-639-1(예: en) 형식으로 제공하면 정확도와 레이턴시가 개선돼요.

import { transcribe } from 'ai';
import { groq, type GroqTranscriptionModelOptions } from '@ai-sdk/groq';
import { readFile } from 'fs/promises';

const result = await transcribe({
  model: groq.transcription('whisper-large-v3'),
  audio: await readFile('audio.mp3'),
  providerOptions: {
    groq: { language: 'en' } satisfies GroqTranscriptionModelOptions,
  },
});

사용 가능한 프로바이더 옵션은 다음과 같아요:

  • timestampGranularities string[] 트랜스크립션에서 타임스탬프의 세밀도(granularity). 기본값은 ['segment']예요. 가능한 값은 ['word'], ['segment'], ['word', 'segment']이에요. 참고: 세그먼트 타임스탬프는 추가 레이턴시가 없지만, 단어 타임스탬프 생성은 추가 레이턴시가 발생해요. 중요: responseFormat을 'verbose_json'으로 설정해야 해요.

  • responseFormat string 응답의 형식. 오디오 세그먼트에 대한 타임스탬프를 받고 timestampGranularities를 활성화하려면 'verbose_json'으로 설정하세요. 변환된 텍스트만 반환하려면 'text'로 설정하세요. 선택 사항.

  • language string 입력 오디오의 언어. 입력 언어를 ISO-639-1 형식(예: 'en')으로 제공하면 정확도와 레이턴시가 개선돼요. 선택 사항.

  • prompt string 모델의 스타일을 안내하거나 이전 오디오 세그먼트를 이어가는 선택적 텍스트. 프롬프트는 오디오 언어와 일치해야 해요. 선택 사항.

  • temperature number 0과 1 사이의 샘플링 온도. 0.8 같은 높은 값은 출력을 더 무작위로 만들고, 0.2 같은 낮은 값은 더 집중되고 결정적으로 만들어요. 0으로 설정하면 모델이 로그 확률을 사용해 특정 임계값에 도달할 때까지 온도를 자동으로 높여요. 기본값은 0. 선택 사항.

모델 기능

Model Transcription Duration Segments Language
whisper-large-v3
whisper-large-v3-turbo

더 알아보기 (Learn more)

전체 사이트맵