Groq Upgrade Migration

Current Model IDs (Use These)

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 [email protected] --save-exact
npm test

SDK Changelog Highlights

The groq-sdk package mirrors the OpenAI SDK structure. Key changes to watch:

• 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

Resources

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

Next Steps

For CI integration during upgrades, see groq-ci-integration.