groq-inference

使用 GROQ API 实现超高速大模型推理（比标准提供商快 10–100 倍），适用于聊天、视觉、音频（STT/TTS）、工具调用和推理模型等实时应用。对于语音 Agent 和低延迟 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}],
)

模型选择：

Use Case	Model
通用聊天	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（限制：禁止使用 OPENAI） </success_criteria>

<core_content> 适用于实时应用的超高速大模型推理。GROQ 提供的推理速度比标准提供商快 10–100 倍。

快速参考：模型选择

Use Case	Model ID	Context	Notes
通用聊天	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])

速率限制

Tier	Requests/min	Tokens/min	Tokens/day
免费	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（语音 Agent）、FieldVault-AI（文档处理）
• 限制：禁止使用 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 — 批处理 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"。