用途：为 groq-sdk（TypeScript）与 groq（Python）提供生产级集成模式，适合实现 Groq 调用、重构 SDK 用法或统一团队编码规范。Groq SDK 与 OpenAI SDK 接口兼容（chat.completions.create），但需处理 Groq 特有行为：极高速度（500+ tok/s）、免费层严格的速率限制，以及 queue_time、completion_time 等响应元数据。
主要能力：分层构建集成。1）类型化客户端单例，共享一个 Groq 客户端并配置 maxRetries 与 timeout，复用连接池；2）类型安全的补全封装，返回含 queue_time、completion_time、total_time 及计算所得 tokensPerSec 的结果；3）带类型事件的流式输出，以 AsyncGenerator<string> 逐块产出 delta.content；4）基于 Groq 错误类型的处理，区分 Groq.APIError（429、401 等）与 Groq.APIConnectionError，未知错误重新抛出；5）指数退避重试，429 时遵循 retry-after 响应头，否则使用带抖动的退避；6）Python 模式，含同步 Groq()、AsyncGroq() 与流式；7）多租户客户端工厂，按租户缓存客户端以隔离 API 密钥。
使用方式：需先安装 groq-sdk（TypeScript）或 groq（Python），在环境变量中设置 GROQ_API_KEY，并了解 async/await 与错误处理。核心骨架为共享单例：import Groq from "groq-sdk"; 通过 getGroq() 惰性创建客户端，传入 apiKey、maxRetries: 3、timeout: 30_000。完整可复制实现位于 references/typescript-patterns.md（步骤 1–5、7）与 references/python-patterns.md（步骤 6），SDK 差异与错误矩阵见 references/sdk-differences.md。
适用场景：需要稳定调用 Groq 聊天补全的应用、多租户服务、对速率限制与网络错误需统一处理的代码库。
限制：429 在免费层常见，需读取 err.headers["retry-after"] 后等待再重试；401 应提示检查 GROQ_API_KEY 且不重试；APIConnectionError 表示无法访问 api.groq.com，可按上下文重试或快速失败；未知错误应重新抛出。具体模型、价格与配额等资料未提供。