Groq
Groq 어댑터는 세계에서 가장 빠른 LLM 추론과 Whisper 기반 오디오 트랜스크립션을 제공하는 Groq의 빠른 추론 API에 액세스할 수 있게 합니다.
설치
npm install @tanstack/ai-groq
기본 사용법
import { chat } from "@tanstack/ai";
import { groqText } from "@tanstack/ai-groq";
const stream = chat({
adapter: groqText("llama-3.3-70b-versatile"),
messages: [{ role: "user", content: "Hello!" }],
});
기본 사용법 - 사용자 지정 API 키
import { chat } from "@tanstack/ai";
import { createGroqText } from "@tanstack/ai-groq";
const adapter = createGroqText("llama-3.3-70b-versatile", process.env.GROQ_API_KEY!, {
// ... your config options
});
const stream = chat({
adapter,
messages: [{ role: "user", content: "Hello!" }],
});
구성
import { createGroqText, type GroqTextConfig } from "@tanstack/ai-groq";
const config: Omit<GroqTextConfig, 'apiKey'> = {
baseURL: "https://api.groq.com/openai/v1", // Optional, for custom endpoints
};
const adapter = createGroqText("llama-3.3-70b-versatile", process.env.GROQ_API_KEY!, config);
예제: 채팅 완성
import { chat, toServerSentEventsResponse } from "@tanstack/ai";
import { groqText } from "@tanstack/ai-groq";
export async function POST(request: Request) {
const { messages } = await request.json();
const stream = chat({
adapter: groqText("llama-3.3-70b-versatile"),
messages,
});
return toServerSentEventsResponse(stream);
}
예제: 도구 사용
import { chat, toolDefinition, type ModelMessage } from "@tanstack/ai";
import { groqText } from "@tanstack/ai-groq";
import { z } from "zod";
const searchDatabaseDef = toolDefinition({
name: "search_database",
description: "Search the database",
inputSchema: z.object({
query: z.string(),
}),
});
const searchDatabase = searchDatabaseDef.server(async ({ query }) => {
// Search database
return { results: [] };
});
const messages: Array<ModelMessage> = [{ role: "user", content: "Search for something" }];
const stream = chat({
adapter: groqText("llama-3.3-70b-versatile"),
messages,
tools: [searchDatabase],
});
Groq가 생성된 도구 호출을 tool_use_failed로 거부하고 failed_generation에 재구성 가능한 도구 호출을 포함하면, 어댑터는 호출을 실행하지 않고 해당 도구의 결과로 프로바이더 오류를 반환합니다. 그러면 에이전트 루프가 다음 반복에서 호출을 수정할 수 있습니다. 다른 프로바이더 오류는 계속해서 터미널 실행 오류로 남습니다.
트랜스크립션
Groq는 groqTranscription() 및 generateTranscription() 활동을 통해 Whisper 기반 음성-텍스트 변환을 제공합니다. audio 입력은 File, Blob, ArrayBuffer, base64 문자열, 데이터 URL 또는 https:// URL을 허용합니다(URL은 다시 업로드하지 않고 Groq로 직접 전달됩니다).
import { generateTranscription } from "@tanstack/ai";
import { groqTranscription } from "@tanstack/ai-groq";
const result = await generateTranscription({
adapter: groqTranscription("whisper-large-v3-turbo"),
audio: "https://example.com/recording.mp3",
language: "en",
});
console.log(result.text);
// verbose_json (the default) populates language, duration, and timestamped segments
for (const segment of result.segments ?? []) {
console.log(`[${segment.start}s → ${segment.end}s] ${segment.text}`);
}
지원 모델: whisper-large-v3-turbo, whisper-large-v3. 지원되는 responseFormat 값: json, text, verbose_json(기본값)입니다. Groq에서는 srt와 vtt를 지원하지 않습니다.
트랜스크립션에서 전체 API를 확인할 수 있습니다.
모델 옵션
Groq는 다양한 프로바이더별 옵션을 지원합니다. 샘플링 매개변수인 temperature, top_p, max_completion_tokens(Groq의 토큰 제한 키)도 chat()의 루트 수준 props가 아니라 이곳에 지정합니다.
import { chat } from "@tanstack/ai";
import { groqText } from "@tanstack/ai-groq";
const stream = chat({
adapter: groqText("llama-3.3-70b-versatile"),
messages: [{ role: "user", content: "Hello!" }],
modelOptions: {
temperature: 0.7,
max_completion_tokens: 1024,
top_p: 0.9,
},
});
이전에
chat()의 루트에temperature/topP/maxTokens를 전달했다면 샘플링 옵션을 modelOptions로 이동을 확인하세요.
추론
추론을 지원하는 모델(예: openai/gpt-oss-120b, qwen/qwen3-32b)에서 추론을 활성화합니다. 그러면 모델이 추론 과정을 표시하며, 이 과정은 thinking 청크로 스트리밍됩니다.
modelOptions: {
reasoning_effort: "medium", // "none" | "default" | "low" | "medium" | "high"
}
요약
긴 텍스트 콘텐츠를 요약합니다.
import { summarize } from "@tanstack/ai";
import { groqSummarize } from "@tanstack/ai-groq";
const result = await summarize({
adapter: groqSummarize("llama-3.3-70b-versatile"),
text: "Your long text to summarize...",
maxLength: 100,
style: "concise", // "concise" | "bullet-points" | "paragraph"
});
console.log(result.summary);
지원 모델
Groq는 여러 프로바이더의 다양한 모델을 제공합니다.
Meta Llama
llama-3.3-70b-versatile- 128K 컨텍스트를 지원하는 빠르고 강력한 모델llama-3.1-8b-instant- 빠르고 비용 효율적인 모델meta-llama/llama-4-maverick-17b-128e-instruct- 비전 지원이 포함된 최신 Llama 4meta-llama/llama-4-scout-17b-16e-instruct- 효율적인 Llama 4 모델
보안 모델
meta-llama/llama-guard-4-12b- 콘텐츠 관리meta-llama/llama-prompt-guard-2-86m- 프롬프트 주입 탐지meta-llama/llama-prompt-guard-2-22m- 경량 프롬프트 보호
OpenAI GPT-OSS 모델
openai/gpt-oss-120b- 추론 지원이 포함된 대형 오픈소스 모델openai/gpt-oss-20b- 효율적인 오픈소스 모델openai/gpt-oss-safeguard-20b- 안전성 튜닝이 적용된 오픈소스 모델
다른 공급자
moonshotai/kimi-k2-instruct-0905- 256K 컨텍스트를 지원하는 Kimi K2qwen/qwen3-32b- 추론 지원이 포함된 Qwen 3
환경 변수
환경 변수에 API 키를 설정합니다.
GROQ_API_KEY=gsk_...
API 레퍼런스
groqText(model, config?)
환경 변수를 사용하여 Groq 채팅 어댑터를 생성합니다.
Parameters:
model- 모델 이름(예:llama-3.3-70b-versatile)config(선택 사항) - 선택적 구성 객체입니다.createGroqText와 동일한 옵션을 지원하지만apiKey는 예외이며,GROQ_API_KEY환경 변수에서 자동으로 감지됩니다. 일반 옵션:baseURL- API 요청용 사용자 지정 기본 URL(선택 사항)
Returns: Groq 채팅 어댑터 인스턴스가 반환됩니다.
createGroqText(model, apiKey, config?)
명시적인 API 키를 사용하여 Groq 채팅 어댑터를 생성합니다.
Parameters:
model- 모델 이름 (예:llama-3.3-70b-versatile)apiKey- Groq API 키config(선택 사항) - 선택적 구성 객체:baseURL- API 요청을 위한 커스텀 기본 URL (선택 사항)
Returns: Groq 채팅 어댑터 인스턴스를 반환합니다.
groqSummarize(model, config?)
환경 변수를 사용하여 Groq 요약 어댑터를 생성합니다.
Returns: Groq 요약 어댑터 인스턴스를 반환합니다.
createGroqSummarize(model, apiKey, config?)
명시적인 API 키를 사용하여 Groq 요약 어댑터를 생성합니다.
Returns: Groq 요약 어댑터 인스턴스를 반환합니다.
groqTranscription(model, config?) / createGroqTranscription(model, apiKey, config?)
Groq 트랜스크립션(음성-텍스트 변환) 어댑터를 생성합니다. 짧은 형식은 환경에서 GROQ_API_KEY를 읽고, create* 형식은 명시적인 API 키를 받습니다. 지원 모델: whisper-large-v3-turbo, whisper-large-v3.
제한 사항
- 텍스트-음성 변환: Groq는 현재 TTS 어댑터를 제공하지 않습니다. 음성 생성을 위해 OpenAI, Gemini, ElevenLabs 또는 fal을 사용하세요.
- 이미지 생성: Groq는 이미지 생성을 지원하지 않습니다. 이미지 생성을 위해 OpenAI, Gemini 또는 fal을 사용하세요.
다음 단계
공급자 도구
Groq 는 현재 제공자별 도구 팩토리를 노출하지 않습니다.
toolDefinition() 에서 @tanstack/ai 을 사용하여 자체 도구를 정의하세요.
일반적인 도구 정의 흐름은 도구를, 다른 프로바이더의 네이티브 도구 제공 방식은 프로바이더 도구를 확인하세요.