Groq Upgrade & Migration

Current State

!

npm list groq-sdk 2>/dev/null | grep groq-sdk || echo 'groq-sdk not installed'

pip show groq 2>/dev/null | grep -E "Name|Version" || echo 'groq not installed (python)'

Overview

Guide for upgrading the

groq-sdk

Model Deprecation Timeline

Groq announces deprecations with advance notice. These models have been deprecated:

mixtral-8x7b-32768

llama-3.3-70b-versatile

llama-3.1-8b-instant

gemma2-9b-it

llama-3.1-8b-instant

llama-3.1-70b-versatile

llama-3.3-70b-versatile

llama-3.1-70b-specdec

llama-3.3-70b-specdec

playai-tts

playai-tts-arabic

distil-whisper-large-v3-en

whisper-large-v3-turbo

Current Model IDs (Use These)

llama-3.1-8b-instant

llama-3.3-70b-versatile

llama-3.3-70b-specdec

meta-llama/llama-4-scout-17b-16e-instruct

meta-llama/llama-4-maverick-17b-128e-instruct

whisper-large-v3

whisper-large-v3-turbo

Always verify at:

GET https://api.groq.com/openai/v1/models

Instructions

Step 1: Check Current Version and Models

set -euo pipefail
# SDK version
npm list groq-sdk 2>/dev/null
npm view groq-sdk version  # latest on npm

# Find all model references in your code
grep -rn "model.*['\"]" src/ --include="*.ts" --include="*.js" | grep -i "groq\|llama\|mixtral\|gemma\|whisper"

Step 2: Upgrade SDK

set -euo pipefail
# Create upgrade branch
git checkout -b chore/upgrade-groq-sdk

# Update to latest
npm install groq-sdk@latest

# Check for breaking changes
npm ls groq-sdk

Step 3: Find and Replace Deprecated Models

// Find-and-replace map for deprecated model IDs
const MODEL_MIGRATIONS: Record<string, string> = {
  "mixtral-8x7b-32768": "llama-3.3-70b-versatile",
  "gemma2-9b-it": "llama-3.1-8b-instant",
  "llama-3.1-70b-versatile": "llama-3.3-70b-versatile",
  "llama-3.1-70b-specdec": "llama-3.3-70b-specdec",
  "llama3-70b-8192": "llama-3.3-70b-versatile",
  "llama3-8b-8192": "llama-3.1-8b-instant",
  "distil-whisper-large-v3-en": "whisper-large-v3-turbo",
};

function resolveModel(model: string): string {
  if (model in MODEL_MIGRATIONS) {
    console.warn(`Model ${model} is deprecated. Using ${MODEL_MIGRATIONS[model]} instead.`);
    return MODEL_MIGRATIONS[model];
  }
  return model;
}

Step 4: Run Migration Scanner

set -euo pipefail
# Automated scan for deprecated patterns
echo "=== Deprecated Model IDs ==="
grep -rn "mixtral-8x7b\|gemma2-9b\|llama-3.1-70b-versatile\|llama3-70b\|llama3-8b\|distil-whisper" \
  src/ --include="*.ts" --include="*.js" --include="*.py" || echo "None found"

echo ""
echo "=== Old Import Patterns ==="
grep -rn "from '@groq/sdk'\|from \"@groq/sdk\"\|require('@groq/sdk')" \
  src/ --include="*.ts" --include="*.js" || echo "None found (correct import is 'groq-sdk')"

echo ""
echo "=== Deprecated Method Calls ==="
grep -rn "\.ping()\|\.healthCheck()\|GroqClient\|GroqError" \
  src/ --include="*.ts" --include="*.js" || echo "None found"

Step 5: Validate and Test

set -euo pipefail
# Run tests
npm test

# Verify models are current
curl -s https://api.groq.com/openai/v1/models \
  -H "Authorization: Bearer $GROQ_API_KEY" | \
  jq -r '.data[].id' | sort

# Integration test
node -e "
const Groq = require('groq-sdk').default;
const g = new Groq();
g.chat.completions.create({
  model: 'llama-3.1-8b-instant',
  messages: [{role: 'user', content: 'ping'}],
  max_tokens: 5
}).then(r => console.log('OK:', r.choices[0].message.content));
"

Step 6: Rollback If Needed

set -euo pipefail
# Pin to previous version
npm install groq-sdk@0.11.0 --save-exact
npm test

SDK Changelog Highlights

The

groq-sdk

• New model IDs added to type definitions
• Response type changes (e.g., new

  usage

  fields)
• Constructor options changes
• New endpoint support (vision, audio, TTS)

Always check the GitHub releases.

Error Handling

400 model_not_found

400 model_decommissioned

401

apiKey

key

400

Resources

• Groq Model Deprecations
• Groq Changelog
• groq-sdk GitHub Releases
• Groq Current Models

Next Steps

For CI integration during upgrades, see

groq-ci-integration