zhongwei/gh-lucklyric-cc-dev-tools-plugins-gemini

Files

Zhongwei Li d2e5aed820 Initial commit

2025-11-30 08:38:21 +08:00

9.3 KiB

Raw Blame History

Gemini Model Selection Guide

Purpose: Guide for selecting the right Gemini model for your task Version: v0.16.0+ Last Updated: 2025-11-18

Quick Reference

Task Type	Recommended Model	Reason
Complex reasoning, architecture design	`gemini-3-pro-preview`	Latest capabilities, best for hard problems
General reasoning, code review	`gemini-2.5-pro`	Stable, reliable, 1M context
Code editing, refactoring	`gemini-2.5-flash`	Faster, optimized for code
When Gemini 3 quota exhausted	`gemini-2.5-pro` → `gemini-2.5-flash`	Graceful degradation

Version-Based Model Mapping

Concept

When users mention a version number (e.g., "use Gemini 3"), map to the latest model in that family for future-proofing.

Current Mappings (as of Nov 2025)

User Request	Maps To	Actual Model ID	Status	Notes
"Gemini 3" or "use 3"	Latest 3.x Pro	`gemini-3-pro-preview`	Preview	Requires preview access
"Gemini 2.5" (general)	2.5 Pro	`gemini-2.5-pro`	Stable	1M tokens context
"Gemini 2.5" (code editing)	2.5 Flash	`gemini-2.5-flash`	Stable	Optimized for speed
No version specified	Latest Pro	`gemini-3-pro-preview`	Preview	DEFAULT

Future-Proofing Strategy

User says "3" → Plugin maps to latest_3x_pro
                 Currently: gemini-3-pro-preview
                 Future:    gemini-3-pro (when stable)
                           gemini-3.1-pro (when released)

User says "2.5" → Plugin maps based on task:
                  General:  gemini-2.5-pro
                  Code:     gemini-2.5-flash

Maintenance: Update mapping table when new models release

Model Family Overview

Gemini 3 Family (Latest - Preview)

gemini-3-pro-preview

Status: Preview (requires access)
Context: 1M tokens
Strengths: Cutting-edge reasoning, complex problem-solving
Use Cases: System architecture, complex algorithms, research
Access: Google AI Ultra subscribers, paid API keys, or waitlist
Availability: May be quota-limited on free tier

gemini -m gemini-3-pro-preview "Design a distributed caching system"

Gemini 2.5 Family (Stable)

gemini-2.5-pro

Status: Stable, production-ready
Context: 1M tokens
Strengths: General reasoning, balanced performance
Use Cases: Code review, technical writing, general assistance
Access: Free tier (60 req/min, 1000 req/day)

gemini -m gemini-2.5-pro "Review this API design for best practices"

gemini-2.5-flash

Status: Stable, production-ready
Context: Unknown (likely lower than Pro)
Strengths: Speed, code generation/editing
Use Cases: Quick refactoring, syntax fixes, fast iterations
Access: Free tier (60 req/min, 1000 req/day)

gemini -m gemini-2.5-flash "Refactor this function for better performance"

gemini-2.5-flash-lite (if available)

Status: Stable (check CLI for availability)
Strengths: Highest throughput, lowest cost
Use Cases: High-volume simple tasks
Note: May have reduced capabilities

Task-Based Selection

By Task Complexity

High Complexity (System Design, Architecture)
    ↓
    gemini-3-pro-preview
    ↓ (if unavailable)
    gemini-2.5-pro

Medium Complexity (Code Review, Analysis)
    ↓
    gemini-2.5-pro

Low Complexity (Code Editing, Refactoring)
    ↓
    gemini-2.5-flash

By Task Type

Research & Design

Primary: gemini-3-pro-preview
Fallback: gemini-2.5-pro
Example: "Design a microservices architecture"

Code Review & Analysis

Primary: gemini-2.5-pro
Fallback: gemini-2.5-flash
Example: "Review this pull request for bugs"

Code Generation & Editing

Primary: gemini-2.5-flash
Fallback: gemini-2.5-pro
Example: "Refactor this code for readability"

General Questions

Primary: gemini-3-pro-preview
Fallback: gemini-2.5-pro
Example: "Explain the CAP theorem"

Selection Decision Tree

START: User makes request
  │
  ├─> User specifies model? ─────────────────┐
  │   (e.g., -m gemini-2.5-pro)               │
  │   YES ──> Use specified model ──> END     │
  │   NO ───> Continue                        │
  │                                           │
  ├─> User mentions version? ────────────────┤
  │   (e.g., "use 3" or "use 2.5")           │
  │   YES ──> Map to latest in family ──> END│
  │   NO ───> Continue                        │
  │                                           │
  ├─> Classify task type:                    │
  │   - Complex reasoning? ──> gemini-3-pro-preview
  │   - Code editing? ──> gemini-2.5-flash    │
  │   - General? ──> gemini-2.5-pro           │
  │                                           │
  └─> Apply fallback if primary unavailable  │
      (quota exhausted, access denied)        │
      └──────────────────────────────────────┘

Fallback Strategy

When Gemini 3 Pro Unavailable

Reason: Quota exhausted, access denied, or service issue

Fallback Logic:

gemini-3-pro-preview unavailable
  │
  ├─> Task type: General reasoning
  │   └─> Use: gemini-2.5-pro
  │
  └─> Task type: Code editing
      └─> Use: gemini-2.5-flash

Implementation Pattern:

# Try Gemini 3 Pro first
gemini -m gemini-3-pro-preview "Design system" 2>&1

# If fails with quota/access error, retry with fallback
if [ $? -ne 0 ]; then
    gemini -m gemini-2.5-pro "Design system"
fi

Free Tier Considerations

Rate Limits (OAuth Free Tier)

60 requests per minute
1,000 requests per day
Context: 1M tokens with Gemini 2.5 Pro

Quota Management

Gemini 3 Pro (Preview):

May have stricter quotas
May auto-switch to lower tier when exhausted
Monitor for 429 (rate limit) or 403 (quota exceeded) errors

Gemini 2.5 Models:

More generous free tier quotas
Better availability
Recommended for high-volume usage

Cost Optimization

High volume, simple tasks → gemini-2.5-flash (fastest, cheapest)
Moderate volume, general → gemini-2.5-pro (balanced)
Low volume, complex → gemini-3-pro-preview (best quality)

Model Capabilities Comparison

Capability	Gemini 3 Pro	Gemini 2.5 Pro	Gemini 2.5 Flash
Reasoning	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
Code Generation	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Speed	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Context Window	1M tokens	1M tokens	Unknown
Stability	Preview	Stable	Stable
Free Tier Access	Limited	Yes	Yes

Access Requirements

Gemini 3 Pro Access

Preview Features Required:

Update Gemini CLI to v0.16.x+
Enable Preview Features in CLI settings
Have one of:
- Google AI Ultra subscription
- Paid Gemini API key
- Vertex API key with Gemini 3 access
- Waitlist approval (free tier users)

Verification:

gemini -m gemini-3-pro-preview "test" 2>&1

# Success: Model responds
# Failure: 404 "model not found" or 403 "access denied"

Gemini 2.5 Access

Always Available (free tier):

gemini-2.5-pro
gemini-2.5-flash

No special access required.

Best Practices

Default to Latest Pro: Start with gemini-3-pro-preview when available
Implement Graceful Fallback: Always have 2.5 fallback logic
Match Model to Task: Don't use Gemini 3 for simple edits
Monitor Quotas: Track rate limits and switch models proactively
Update Mapping Table: Review quarterly for new model releases
Test Access: Verify Gemini 3 Pro access before defaulting to it
Use Explicit Model Selection: Specify -m rather than relying on CLI defaults

Updating This Guide

When new models are released:

Update "Current Mappings" table
Add new model to "Model Family Overview"
Update "Model Capabilities Comparison"
Revise fallback logic if needed
Update examples with new model IDs
Test all command patterns
Update "Last Updated" date

Example Selection Scenarios

Scenario 1: System Architecture Design

Task: "Design a scalable payment processing system" Selection: gemini-3-pro-preview (complex reasoning) Fallback: gemini-2.5-pro (if quota exhausted)

gemini -m gemini-3-pro-preview "Design a scalable payment processing system"

Scenario 2: Quick Code Fix

Task: "Fix the syntax error in this JavaScript" Selection: gemini-2.5-flash (simple, fast) Fallback: gemini-2.5-pro (if Flash unavailable)

gemini -m gemini-2.5-flash "Fix the syntax error in this code"

Scenario 3: Pull Request Review

Task: "Review this pull request for best practices" Selection: gemini-2.5-pro (balanced, thorough) Fallback: gemini-2.5-flash (if quota tight)

gemini -m gemini-2.5-pro "Review this pull request"

9.3 KiB Raw Blame History