Classification Workflow Fresh 🌱

Classify text, images, and documents into predefined categories using embedding similarity.

Classification Architecture

Multi-Label Classification Flow

Implementation

Step 1: Define and Embed Categories

from google import genai
from google.genai import types
import numpy as np

client = genai.Client()

# Define categories with descriptions
CATEGORIES = {
    'technology': 'Technology, software, hardware, programming, AI, machine learning, computers',
    'sports': 'Sports, athletics, games, competitions, fitness, training, teams',
    'finance': 'Finance, money, investing, stocks, banking, economy, markets, trading',
    'health': 'Health, medicine, wellness, fitness, nutrition, disease, treatment',
    'entertainment': 'Entertainment, movies, music, TV shows, celebrities, gaming',
    'science': 'Science, research, physics, chemistry, biology, experiments',
    'politics': 'Politics, government, elections, policy, legislation, democracy',
}

def embed_categories(categories):
    """Embed all category descriptions."""
    category_vectors = {}
    for name, description in categories.items():
        result = client.models.embed_content(
            model='gemini-embedding-2-preview',
            contents=description,
            config=types.EmbedContentConfig(
                task_type='CLASSIFICATION',
                output_dimensionality=768
            )
        )
        vec = np.array(result.embeddings[0].values)
        category_vectors[name] = vec / np.linalg.norm(vec)
    return category_vectors

category_vectors = embed_categories(CATEGORIES)
print(f"Embedded {len(category_vectors)} categories")

Step 2: Classify Text

def classify_text(text, category_vectors, top_k=3, threshold=0.3):
    """Classify text into top-K categories above threshold."""
    result = client.models.embed_content(
        model='gemini-embedding-2-preview',
        contents=text,
        config=types.EmbedContentConfig(
            task_type='CLASSIFICATION',
            output_dimensionality=768
        )
    )
    text_vec = np.array(result.embeddings[0].values)
    text_vec = text_vec / np.linalg.norm(text_vec)

    scores = {}
    for name, cat_vec in category_vectors.items():
        scores[name] = float(np.dot(text_vec, cat_vec))

    # Sort by score, filter by threshold
    ranked = sorted(scores.items(), key=lambda x: x[1], reverse=True)
    results = [(name, score) for name, score in ranked[:top_k] if score >= threshold]

    return results

# Example
text = "Apple announced a new M4 chip with improved neural engine performance"
predictions = classify_text(text, category_vectors)
for category, score in predictions:
    print(f"  {category}: {score:.4f}")

Step 3: Batch Classification

def classify_batch(texts, category_vectors, threshold=0.3):
    """Classify multiple texts efficiently."""
    # Embed all texts
    result = client.models.embed_content(
        model='gemini-embedding-2-preview',
        contents=texts,
        config=types.EmbedContentConfig(
            task_type='CLASSIFICATION',
            output_dimensionality=768
        )
    )

    # Build category matrix
    cat_names = list(category_vectors.keys())
    cat_matrix = np.array([category_vectors[n] for n in cat_names])

    # Classify each text
    all_results = []
    for emb in result.embeddings:
        text_vec = np.array(emb.values)
        text_vec = text_vec / np.linalg.norm(text_vec)

        scores = cat_matrix @ text_vec
        predictions = [
            (cat_names[i], float(scores[i]))
            for i in np.argsort(scores)[::-1]
            if scores[i] >= threshold
        ]
        all_results.append(predictions[:3])

    return all_results

# Batch classify
texts = [
    "The stock market reached all-time highs today",
    "New study reveals benefits of intermittent fasting",
    "Team wins championship in overtime thriller",
]

results = classify_batch(texts, category_vectors)
for text, preds in zip(texts, results):
    print(f"\n{text[:50]}...")
    for cat, score in preds:
        print(f"  {cat}: {score:.4f}")

Step 4: Image Classification

def classify_image(image_path, category_vectors, threshold=0.3):
    """Classify an image into categories."""
    with open(image_path, 'rb') as f:
        result = client.models.embed_content(
            model='gemini-embedding-2-preview',
            contents=[types.Part.from_bytes(
                data=f.read(), mime_type='image/jpeg'
            )],
            config=types.EmbedContentConfig(
                output_dimensionality=768
            )
        )

    img_vec = np.array(result.embeddings[0].values)
    img_vec = img_vec / np.linalg.norm(img_vec)

    scores = {}
    for name, cat_vec in category_vectors.items():
        scores[name] = float(np.dot(img_vec, cat_vec))

    ranked = sorted(scores.items(), key=lambda x: x[1], reverse=True)
    return [(n, s) for n, s in ranked if s >= threshold][:3]

# Classify an image
preds = classify_image('photo.jpg', category_vectors)
for cat, score in preds:
    print(f"  {cat}: {score:.4f}")

Verification Checklist

• [ ] Categories defined with descriptive text
• [ ] Category vectors embedded with CLASSIFICATION task type
• [ ] Single text classification returning correct top categories
• [ ] Batch classification working efficiently
• [ ] Image classification returning meaningful categories
• [ ] Threshold tuned for acceptable precision/recall balance
• [ ] Normalization applied for reduced dimensions

Troubleshooting

Issue	Solution
All categories score similarly	Use more distinctive category descriptions
Wrong top category	Add more specific keywords to category description
Low scores overall	Lower threshold; ensure CLASSIFICATION task type
Batch API errors	Keep batches under 100 items; handle rate limits
Slow classification	Pre-compute category vectors; use reduced dimensions

See Also

• Text Embeddings — Task types explained
• Clustering — Unsupervised grouping
• Benchmarks — MTEB scores for classification
• API Reference — CLASSIFICATION task type details