groq-inference

チャット、ビジョン、オーディオ（STT/TTS）、ツール使用、推論モデルなどのリアルタイムアプリケーション向けに、GROQ API を使用して超高速な LLM 推論（標準プロバイダーより 10～100 倍高速）を実現します。音声エージェントや低レイテンシ AI にとって重要です。

<quick_start> GROQ による基本的なチャット:

from groq import Groq
client = Groq(api_key=os.environ.get("GROQ_API_KEY"))

response = client.chat.completions.create(
    model="llama-3.3-70b-versatile",  # Best all-around
    messages=[{"role": "user", "content": prompt}],
)

モデルの選択:

ユースケース	モデル
一般的なチャット	llama-3.3-70b-versatile
ビジョン/OCR	meta-llama/llama-4-scout-17b-16e-instruct
STT	whisper-large-v3（GROQ ホスト、OpenAI ではない）
TTS	playai-tts
</quick_start>

<success_criteria> GROQ 統合が成功したと言えるのは次の場合です:

• ユースケースに応じて正しいモデルを選択している（モデル表を参照）
• API キーを環境変数（GROQ_API_KEY）に設定している
• レート制限に対する tenacity によるリトライロジックがある
• リアルタイムアプリケーション向けにストリーミングを有効にしている
• 並列クエリに非同期パターンを使用している
• OpenAI を使用していない（制約: NO OPENAI） </success_criteria>

<core_content> リアルタイムアプリケーション向けの超高速 LLM 推論。GROQ は標準プロバイダーより 10～100 倍高速な推論を提供します。

クイックリファレンス: モデルの選択

ユースケース	モデル ID	コンテキスト	備考
一般的なチャット	llama-3.3-70b-versatile	128K	総合力が最も高い
高速チャット	llama-3.1-8b-instant	128K	シンプルなタスク、最速
ビジョン/OCR	meta-llama/llama-4-scout-17b-16e-instruct	128K	最大 5 枚の画像
STT	whisper-large-v3	448	GROQ ホスト（OpenAI API ではない）
TTS	playai-tts	-	Fritz-PlayAI 音声
推論	meta-llama/llama-4-maverick-17b-128e-instruct	128K	思考モデル
ツール使用	compound-beta	-	組み込みのウェブ検索、コード実行

コアパターン

1. チャット補完（基本 + ストリーミング）

import os
from groq import Groq, AsyncGroq

client = Groq(api_key=os.environ.get("GROQ_API_KEY"))

def chat(prompt: str, system: str = "You are helpful.") -> str:
    response = client.chat.completions.create(
        model="llama-3.3-70b-versatile",
        messages=[
            {"role": "system", "content": system},
            {"role": "user", "content": prompt}
        ],
        temperature=0.7,
        max_completion_tokens=1024,
    )
    return response.choices[0].message.content

# Streaming
def stream_chat(prompt: str):
    stream = client.chat.completions.create(
        model="llama-3.3-70b-versatile",
        messages=[{"role": "user", "content": prompt}],
        stream=True,
    )
    for chunk in stream:
        if chunk.choices[0].delta.content:
            yield chunk.choices[0].delta.content

2. ビジョン / マルチモーダル

import base64

def analyze_image(image_path: str, prompt: str) -> str:
    with open(image_path, "rb") as f:
        image_b64 = base64.standard_b64encode(f.read()).decode("utf-8")

    response = client.chat.completions.create(
        model="meta-llama/llama-4-scout-17b-16e-instruct",
        messages=[{
            "role": "user",
            "content": [
                {"type": "text", "text": prompt},
                {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_b64}"}}
            ]
        }],
    )
    return response.choices[0].message.content

# URL-based: just pass {"url": "https://..."} instead of base64

3. オーディオ: 音声認識（GROQ ホストの Whisper）

注意: GROQ 上の Whisper は GROQ のハードウェアで動作します - OpenAI の API を呼び出しているのではありません。 Whisper はオープンソースモデルであり、GROQ が高速推論のためにホストしています。

def transcribe(audio_path: str, language: str = "en") -> str:
    with open(audio_path, "rb") as f:
        result = client.audio.transcriptions.create(
            file=f,
            model="whisper-large-v3",  # GROQ-hosted, not OpenAI API
            language=language,
            response_format="verbose_json",  # Includes timestamps
        )
    return result.text

def translate_to_english(audio_path: str) -> str:
    with open(audio_path, "rb") as f:
        result = client.audio.translations.create(file=f, model="whisper-large-v3")
    return result.text

代替 STT プロバイダー（Whisper 以外の選択肢を好む場合）:

• Deepgram - リアルタイムストリーミング、最低レイテンシ（pip install deepgram-sdk）
• AssemblyAI - 高精度、話者ダイアリゼーション（pip install assemblyai）
• Deepgram/AssemblyAI の統合パターンについては voice-ai-skill を参照してください

4. オーディオ: 音声合成（PlayAI）

def text_to_speech(text: str, output_path: str = "output.wav"):
    response = client.audio.speech.create(
        model="playai-tts",
        voice="Fritz-PlayAI",  # Also: Arista-PlayAI
        input=text,
        response_format="wav",
    )
    response.write_to_file(output_path)

# Streaming TTS
def stream_tts(text: str):
    with client.audio.speech.with_streaming_response.create(
        model="playai-tts", voice="Fritz-PlayAI", input=text, response_format="wav"
    ) as response:
        for chunk in response.iter_bytes(1024):
            yield chunk

代替 TTS プロバイダー（GROQ の PlayAI 以外）:

• Cartesia - 超低レイテンシ、感情制御（pip install cartesia）
• ElevenLabs - 最も自然な音声、ボイスクローニング（pip install elevenlabs）
• Deepgram - 高速、コスト効率が高い（pip install deepgram-sdk）
• Cartesia/ElevenLabs/Deepgram の TTS 統合パターンについては voice-ai-skill を参照してください

5. ツール使用 / 関数呼び出し

import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get weather for a location",
        "parameters": {
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"]
        }
    }
}]

def chat_with_tools(prompt: str):
    messages = [{"role": "user", "content": prompt}]
    response = client.chat.completions.create(
        model="llama-3.3-70b-versatile", messages=messages, tools=tools, tool_choice="auto"
    )
    msg = response.choices[0].message

    if msg.tool_calls:
        for tc in msg.tool_calls:
            result = execute_function(tc.function.name, json.loads(tc.function.arguments))
            messages.extend([msg, {"role": "tool", "tool_call_id": tc.id, "content": json.dumps(result)}])
        return client.chat.completions.create(model="llama-3.3-70b-versatile", messages=messages, tools=tools).choices[0].message.content
    return msg.content

6. Compound Beta（組み込みのウェブ検索 + コード実行）

def compound_query(prompt: str):
    """Built-in tools: web_search, code_execution."""
    response = client.chat.completions.create(
        model="compound-beta",
        messages=[{"role": "user", "content": prompt}],
    )
    msg = response.choices[0].message
    # Access msg.executed_tools for tool results
    return msg.content

7. 推論モデル

def reasoning_query(prompt: str, format: str = "parsed"):
    """format: 'parsed' (structured), 'raw' (visible), 'hidden' (no thinking)"""
    response = client.chat.completions.create(
        model="meta-llama/llama-4-maverick-17b-128e-instruct",
        messages=[{"role": "user", "content": prompt}],
        reasoning_format=format,
    )
    msg = response.choices[0].message
    if format == "parsed" and hasattr(msg, 'reasoning'):
        return {"thinking": msg.reasoning, "answer": msg.content}
    return msg.content

8. 非同期パターン

async_client = AsyncGroq(api_key=os.environ.get("GROQ_API_KEY"))

async def async_chat(prompt: str) -> str:
    response = await async_client.chat.completions.create(
        model="llama-3.3-70b-versatile",
        messages=[{"role": "user", "content": prompt}],
    )
    return response.choices[0].message.content

async def parallel_queries(prompts: list[str]) -> list[str]:
    import asyncio
    return await asyncio.gather(*[async_chat(p) for p in prompts])

レート制限

ティア	リクエスト/分	トークン/分	トークン/日
無料	30	15,000	500,000
有料	100+	100,000+	無制限

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
def reliable_chat(prompt: str) -> str:
    return chat(prompt)

統合に関する注意

• 組み合わせ: voice-ai-skill（Whisper STT + PlayAI TTS）、langgraph-agents-skill
• 補完: trading-signals-skill（高速分析）、data-analysis-skill
• プロジェクト: VozLux（音声エージェント）、FieldVault-AI（ドキュメント処理）
• 制約: NO OPENAI - GROQ は高速推論レイヤーです

環境変数

GROQ_API_KEY=gsk_...  # Required - get from console.groq.com

# Optional multi-provider
ANTHROPIC_API_KEY=    # Claude for complex reasoning
GOOGLE_API_KEY=       # Gemini fallback

参照ファイル

• reference/models-catalog.md - 仕様を含む完全なモデルカタログ
• reference/audio-speech.md - Whisper STT と PlayAI TTS の詳細解説
• reference/vision-multimodal.md - マルチモーダルと画像処理
• reference/tool-use-patterns.md - 関数呼び出しと Compound Beta
• reference/reasoning-models.md - 思考モデルと reasoning_format
• reference/cost-optimization.md - Batch API、キャッシュ、プロバイダールーティング

結果サイドカーを出力する

最後のステップとして、~/.claude/skill-analytics/last-outcome-groq-inference.json に書き込みます：

{"ts":"[UTC ISO8601]","skill":"groq-inference","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"requests_made":[n],"tokens_used":[n],"models_used":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

一部のステージが失敗しても結果が生成された場合は、ステータスに「partial」を使用します。出力がまったく生成されなかった場合にのみ「error」を使用します。