New: QVAC SDK now supports Kotlin. Build local AI into your JVM and Android apps.
QVAC Logo
SDKImage classification
v0.23, not the current release

Image classification

Assign one or more class labels to an input image with confidence scores.

Overview

Image classification uses a GGML inference engine (@qvac/classification-ggml). Load a model using modelType: "classification" and a modelSrc. The MOBILENETV3_3CLASS_V3_FP16 constant is a MobileNetV3-Small that classifies images into three labels: "food", "report", and "other". Custom GGUF classifiers are supported by passing your own modelSrc.

Provide an image to classify() as a Uint8Array of either:

  • an encoded JPEG or PNG buffer; or
  • raw RGB bytes, alongside width, height, and channels: 3.

classify() returns ClassificationResult[] — an array of { label, confidence } entries sorted by confidence in descending order. Use topK to limit the number of results returned, either as a load-time default (modelConfig.topK) or as a per-call override.

Functions

Use the following sequence of function calls:

  1. loadModel()
  2. classify()
  3. unloadModel()

For how to use each function, see SDK — API reference.

Models

Supported model families and their file layouts:

  • MobileNetV3-Small: single all-in-one *.gguf file — the base model or any fine-tune of the same architecture (converted to GGUF). Fine-tunes may define their own classes and labels; the label set is sourced from the GGUF metadata.

For models available as constants, see SDK — Models.

Example

The following script classifies a JPEG image with the MOBILENETV3_3CLASS_V3_FP16 model. Pass the path of a JPEG or PNG image as the first argument:

classify-image.js
import fs from 'fs';
import { loadModel, classify, unloadModel, MOBILENETV3_3CLASS_V3_FP16 } from '@qvac/sdk';
/**
 * Classify an image with MobileNetV3-Small, which produces three classes:
 * "food", "report", "other".
 *
 * Usage: npx tsx examples/classification/classify-image.ts <image-path>
 */
async function main() {
    const imagePath = process.argv[2];
    if (!imagePath) {
        console.error('Usage: npx tsx examples/classification/classify-image.ts <image-path>');
        process.exit(1);
    }
    const modelId = await loadModel({
        modelSrc: MOBILENETV3_3CLASS_V3_FP16,
        modelType: 'ggml-classification'
    });
    const image = fs.readFileSync(imagePath);
    const results = await classify({ modelId, image });
    console.log('Classification results:');
    for (const { label, confidence } of results) {
        console.log(`  ${label}: ${(confidence * 100).toFixed(1)}%`);
    }
    await unloadModel({ modelId });
}
main().catch(console.error);

Tip: all examples throughout this documentation are self-contained and runnable. For instructions on how to run them, see the JS/TS quickstart, the Python quickstart, or the Kotlin quickstart.

On this page

Ask anything about QVAC.