NVIDIA NIM Overview for NV-Tesseract

NV-Tesseract is available in multiple NIM tags, each providing different capabilities:

Note: Choose the tag that matches your use case.

NV-Tesseract NIM Overview

Description:

This NIM provides inference endpoints for Time Series Forecasting (Forecasting-1.0.0), Diffusion-based Anomaly Detection (AD-Diffusion-1.0.0 / AD-Diffusion-1.1.0), and Univariate Anomaly Detection and Classification (AD-Transformer-1.0.0) capabilities. These containers house the NV-Tesseract family of models, which are foundation time series models that rapidly processes massive time series datasets, uncovers hidden patterns, detects anomalies, performs classification and predicts market shifts quickly and accurately.

The container components are for research and development only.

License/Terms of Use:

GOVERNING TERMS: Use of this model and NIM container is governed by the NVIDIA Software and Model Evaluation License. Additional Information: MIT License.

You are responsible for ensuring that your use of NVIDIA provided models complies with all applicable laws.

Deployment Geography: Global

Program Classes:

The NV-Tesseract Container automatically includes the NV Tesseract Time Series Model.

• Use Case - Forecasting-1.0.1: Perform time series forecasting on numeric data with optional context-enhanced predictions using DARR mode, featuring model caching and optimized weight loading for faster inference and automatic context data mismatch handling.
• Use Case - Forecasting-1.0.0: Perform time series forecasting on numeric data with optional context-enhanced predictions using DARR mode.
• Use Case - AD-Diffusion-1.1.0: Perform anomaly detection on numeric, multivariate data with faster inference and multi GPU support.
• Use Case - AD-Transformer-1.0.0: Perform classification on a single-dimensional tabular data and perform anomaly detection on numeric, univariate data.
• Use Case - AD-Diffusion-1.0.0: Perform anomaly detection on numeric, multivariate data.

Deployment Details:

See Prerequisites for hardware and software requirements.

Our AI models are designed and/or optimized to run on NVIDIA GPU-accelerated systems. By leveraging NVIDIA's hardware (e.g. GPU cores) and software frameworks (e.g., CUDA libraries), the model achieves faster training and inference times compared to CPU-only solutions.

Container Tag(s):

• NV-Tesseract NIM Forecasting-1.0.1
• NV-Tesseract NIM Forecasting-1.0.0
• NV-Tesseract NIM AD-Diffusion-1.1.0
• NV-Tesseract NIM AD-Diffusion-1.0.0
• NV-Tesseract NIM AD-Transformer-1.0.0

Ethical Considerations:

NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal developer team to ensure these software components meet requirements for the relevant industry and use case and address unforeseen product misuse.

Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns here.

Security Common Vulnerabilities and Exposures (CVEs)

Please review the Security Scanning tab on NGC to view the latest security scan results. For certain open-source vulnerabilities listed in the scan results, NVIDIA provides a response in the form of a Vulnerability Exploitability eXchange (VEX) document. The VEX information can be reviewed and downloaded from the Security Scanning tab.

Table of Contents

• NV-Tesseract NIM Overview
• Getting Started
• Prerequisites
  • Quickstart
  • Verify Deployment
• Stopping the Container
• Forecasting-1.0.1 NIM
• Forecasting-1.0.0 NIM
  • Basic Forecasting
  • DARR Mode (Context-Enhanced Predictions)
  • Preprocessing Requirements
• AD-Diffusion-1.1.0 NIM: Multivariate Anomaly Detection with Faster Inference
• AD-Diffusion-1.0.0 NIM: Multivariate Anomaly Detection
• AD-Transformer-1.0.0 NIM
  • Univariate Anomaly Detection
  • Classification
• API Reference
  • Common Endpoints (All Tags)
  • Supported Formats
• Error Handling
• Troubleshooting

Getting Started

Prerequisites

Hardware Requirements

Software Requirements

• Operating System: Linux with glibc 2.35+ (verify with ldd --version)
• Docker: 20.10.0+ (24.0+ recommended) — Installation Guide
• Docker Desktop (optional): v4.10.0+ — Installation Guide
• NVIDIA NGC CLI: Installation Guide

Quickstart

Step 1: Generate an NGC API Key

1. Go to NGC API Keys
2. Create a key with at least NGC Catalog selected from the Services Included dropdown. If this key will be reused for other purposes, more services can be included.
3. Save the key securely

Step 2: Docker Login to NGC

docker login nvcr.io
# Username: $oauthtoken
# Password: <YOUR_NGC_API_KEY>

Step 3: Pull and Run the Container

Choose the tag that matches your use case:

# Forecasting-1.0.1 NIM (Latest)
docker pull nvcr.io/nim/nvidia/nv-tesseract:forecasting-1.0.1

# Forecasting-1.0.0 NIM
docker pull nvcr.io/nim/nvidia/nv-tesseract:forecasting-1.0.0

# AD-Diffusion-1.1.0 NIM (Multivariate Anomaly Detection — faster, multi-GPU; min 40 rows)
docker pull nvcr.io/nim/nvidia/nv-tesseract:ad-diffusion-1.1.0

# AD-Diffusion-1.0.0 NIM (Multivariate Anomaly Detection; min 25 rows)
docker pull nvcr.io/nim/nvidia/nv-tesseract:ad-diffusion-1.0.0

# AD-Transformer-1.0.0 NIM (Univariate Anomaly Detection & Classification)
docker pull nvcr.io/nim/nvidia/nv-tesseract:ad-transformer-1.0.0

Run the container:

# Run with GPU
docker run -p 8000:8000 \
  -e NGC_API_KEY=<your-ngc-api-key> \
  nvcr.io/nim/nvidia/nv-tesseract:<tag>

# Run CPU-only
docker run -p 8000:8000 \
  -e NGC_API_KEY=<your-ngc-api-key> \
  -e NIM_CPU_ONLY=1 \
  nvcr.io/nim/nvidia/nv-tesseract:<tag>

Step 4: Verify Hardware Compatibility (Optional)

Single GPU:

docker run --rm --runtime=nvidia --gpus='"device=0"' \
  --entrypoint list-model-profiles nvcr.io/nim/nvidia/nv-tesseract:<tag>

Multiple GPUs (AD-Diffusion-1.1.0 only):

To use all visible GPUs by default, omit the --gpus flag. To use specific GPUs (e.g., indices 0, 1, and 3):

docker run --rm --runtime=nvidia --gpus='"device=0,1,3"' \
  --entrypoint list-model-profiles nvcr.io/nim/nvidia/nv-tesseract:<tag>

• The NIM uses all GPUs visible to the process via CUDA_VISIBLE_DEVICES or the default GPU visibility.
• If 2 or more GPUs are visible, the multi-GPU path runs: work is split by sliding windows (one subprocess per GPU, each processing a chunk of windows).
• If only 1 GPU is visible, the single-GPU path runs (one process, no subprocess workers).
• Multi-GPU inference is triggered when input size is greater than 100 rows.

CPU:

docker run --rm -it --env NIM_CPU_ONLY=1 \
  --entrypoint list-model-profiles nvcr.io/nim/nvidia/nv-tesseract:<tag>

Verify Deployment

Wait for the startup message:

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Then verify the service is ready:

# Liveness check
curl -X GET 'http://0.0.0.0:8000/v1/health/live'

# Readiness check
curl -X GET 'http://0.0.0.0:8000/v1/health/ready'

Expected response:

{"status":"ok"}

Stopping the Container

docker stop $CONTAINER_NAME
# Or use docker kill if unresponsive
docker kill $CONTAINER_NAME

# Remove the container (optional)
docker rm $CONTAINER_NAME

If you didn't use --name, find the container ID with docker ps.

Forecasting-1.0.1 NIM

Container: nvcr.io/nim/nvidia/nv-tesseract:forecasting-1.0.1

Forecasting-1.0.1 builds upon Forecasting-1.0.0 with the following enhancements:

New Features in 1.0.1

🚀 Model Caching and Optimized Loading for Faster Inference

The NIM now includes caching during model initialization and optimized loading of weights that significantly improves inference speed.

🔧 Automatic Context Data Mismatch Handling

The NIM automatically handles column mismatches between input and context datasets, making DARR mode more robust and user-friendly.

Enhanced Context Data Flexibility

What's New: Context datasets no longer need identical feature columns to input data.

Updated Requirements:

• Both datasets must have the same timestamp_column and target_column
• At least one common feature column must exist (excluding timestamp and target columns)
• Context dataset must have at least seq_len + model_horizon rows

Note: Feature columns refer to all numeric columns except the timestamp and target columns. The target column is required in both datasets but is not considered a "feature column" for alignment purposes.

Column Mismatch Handling Example

Warning: Column mismatch detected between input and context datasets
  Input dataset feature columns: ['HUFL', 'HULL', 'MUFL', 'MULL', 'LUFL', 'OT']
  Context dataset feature columns: ['HULL', 'MULL', 'LUFL']
  Common feature columns: ['HULL', 'MULL', 'LUFL']
  Using only common feature columns for consistent predictions: ['HULL', 'MULL', 'LUFL']

Usage

For basic forecasting, DARR mode usage, request parameters, and examples, see the Forecasting-1.0.0 NIM section. All functionality remains the same except for the enhanced context data handling described above.

Forecasting-1.0.0 NIM

Container: nvcr.io/nim/nvidia/nv-tesseract:forecasting-1.0.0

The /forecast endpoint performs time series forecasting using the Tesseract model with optional DARR (Domain Aware Representation and Retrieval) mode for context-enhanced predictions.

Basic Forecasting

Important: The endpoint requires at least 512 rows of input data and supports a maximum forecast_horizon of 512 steps.

Note: The examples below show abbreviated data for clarity, but your actual requests should contain 512 or more samples. You can use the ETTh Dataset from Kaggle for testing.

Request Parameters

JSON Example

curl -X POST "http://0.0.0.0:8000/forecast" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"date": "2016-7-1 00:00", "LULL": 1.34},
      {"date": "2016-7-1 01:00", "LULL": 1.37}
    ],
    "timestamp_column": "date",
    "target_column": "LULL",
    "forecast_horizon": 24
  }'

Response:

[
  {"date": "2018-6-24 20:00", "LULL_forecast": 1.42},
  {"date": "2018-6-24 21:00", "LULL_forecast": 1.38}
]

CSV Example

curl -X POST "http://0.0.0.0:8000/forecast?timestamp_column=date&target_column=LULL&forecast_horizon=24" \
  -H "Content-Type: text/csv" \
  -H "Accept: text/csv" \
  --data-binary @ETTh1.csv

Response:

date,LULL_forecast
2018-6-24 20:00,1.42
2018-6-24 21:00,1.38

Saving Forecast Output to a File

# Using shell redirection
curl -X POST "http://0.0.0.0:8000/forecast?timestamp_column=date&target_column=LULL&forecast_horizon=24" \
  -H "Content-Type: text/csv" \
  -H "Accept: text/csv" \
  --data-binary @ETTh1.csv > forecast_results.csv

# Using curl's -o option
curl -X POST "http://0.0.0.0:8000/forecast?timestamp_column=date&target_column=LULL&forecast_horizon=24" \
  -H "Content-Type: text/csv" \
  --data-binary @ETTh1.csv \
  -o forecast_results.json

DARR Mode (Context-Enhanced Predictions)

DARR (Domain-Aware Representation and Retrieval) enhances forecasting by combining direct model predictions with pattern retrieval from historical data. When enabled, DARR:

1. Embeds both input and historical context into a shared representation space
2. Retrieves similar historical patterns using k-nearest neighbor (kNN) search
3. Blends the model's prediction with forecasts from retrieved neighbors

This is particularly effective when you have substantial historical data with domain-specific patterns, regime changes, or seasonal variations.

Context Data Requirements

Important: Context data must have at least as many columns as the inference input and more rows: at least 584 rows (512 for sequence length plus 72 for the model horizon), compared to the 512-row minimum for input data.

The context data should contain historical examples that may be similar to patterns in your inference input. For best results:

• Include data from similar time periods (e.g., same season in previous years)
• Ensure consistent data quality and preprocessing
• More context data generally improves retrieval quality

DARR Example

curl -X POST "http://0.0.0.0:8000/forecast" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"date": "2018-6-24 00:00", "LULL": 1.34},
      {"date": "2018-6-24 01:00", "LULL": 1.37}
    ],
    "context_data": [
      {"date": "2017-6-24 00:00", "LULL": 1.32, "LULL_forecast": 1.35},
      {"date": "2017-6-24 01:00", "LULL": 1.35, "LULL_forecast": 1.38}
    ],
    "timestamp_column": "date",
    "target_column": "LULL",
    "forecast_horizon": 24
  }'

Preprocessing Requirements

Before using the Forecasting NIM, ensure your data meets these requirements:

AD-Diffusion-1.1.0 NIM: Multivariate Anomaly Detection with Faster Inference

Container: nvcr.io/nim/nvidia/nv-tesseract:ad-diffusion-1.1.0

The /v2/detect-anomalies endpoint uses the Tesseract diffusion model for multivariate anomaly detection.

Important: Requires at least 40 samples/rows in input for processing.

AD-Diffusion-1.1.0 is the successor to AD-Diffusion-1.0.0 for multivariate anomaly detection. The endpoints and usage are unchanged: both use /v2/detect-anomalies with the same request/response formats. What's new in AD-Diffusion-1.1.0:

• Faster inference — Improved runtime performance
• Multi-GPU support — Run inference across multiple GPUs for higher throughput

You can switch from AD-Diffusion-1.0.0 to AD-Diffusion-1.1.0 by changing the container tag; no API or client changes are required. API usage is the same across tags.

See Interpreting Outputs below for how to read the Anomaly flag and output columns.

AD-Diffusion-1.0.0 NIM: Multivariate Anomaly Detection

Container: nvcr.io/nim/nvidia/nv-tesseract:ad-diffusion-1.0.0

The /v2/detect-anomalies endpoint uses the Tesseract diffusion model for multivariate anomaly detection.

Important: Requires at least 25 samples/rows in input for processing.

Data Format

• Any number of numeric feature columns
• All features are automatically converted to floats
• Column names can be anything (e.g., feature_1, temperature, pressure)
• Column order matters: the first column is treated as the target column (representative of the time-step); all remaining columns are supporting features

Interpreting Outputs

Each response row corresponds to an input row and includes the original feature values plus two anomaly-detection fields:

• Anomaly — Boolean flag indicating whether the time step is anomalous. This flag pertains to the first column of the input series, which is assumed to be the target column and representative of the time-step.
• MAE — Mean Absolute Error; reconstruction error metric used for anomaly detection.

The remaining columns in the response echo the input feature values. Columns after the first are treated as supporting features that provide context for detecting anomalies in the target column.

JSON Example

curl -X POST 'http://0.0.0.0:8000/v2/detect-anomalies' \
  -H "Content-Type: application/json" \
  -d '[
    {"feature_1": 100, "feature_2": 160, "feature_3": 1.6, "feature_4": 0},
    {"feature_1": 20, "feature_2": 83, "feature_3": 4.15, "feature_4": 1}
  ]'

Response:

[
  {"feature_1": 100.0, "feature_2": 160.0, "feature_3": 1.6, "feature_4": 0.0, "Anomaly": false, "MAE": 2.866350},
  {"feature_1": 20.0, "feature_2": 83.0, "feature_3": 4.15, "feature_4": 1.0, "Anomaly": false, "MAE": 3.077732}
]

CSV Example

curl -X POST 'http://0.0.0.0:8000/v2/detect-anomalies' \
  -H "Content-Type: text/csv" \
  -H "Accept: text/csv" \
  --data-binary @test-datasets/anomaly_detection/test_multivariate.csv

Response:

feature_1,feature_2,feature_3,feature_4,Anomaly,MAE
100.0,160.0,1.6,0.0,false,2.866350
20.0,83.0,4.15,1.0,false,3.077732

Saving Anomaly Detection Output to a File

# Using shell redirection
curl -X POST 'http://0.0.0.0:8000/v2/detect-anomalies' \
  -H "Content-Type: text/csv" \
  -H "Accept: text/csv" \
  --data-binary @data.csv > anomaly_results.csv

# Using curl's -o option
curl -X POST 'http://0.0.0.0:8000/v2/detect-anomalies' \
  -H "Content-Type: application/json" \
  -d '[{"feature_1": 100, "feature_2": 160}]' \
  -o anomaly_results.json

AD-Transformer-1.0.0 NIM

Container: nvcr.io/nim/nvidia/nv-tesseract:ad-transformer-1.0.0

This tag provides two endpoints:

• /detect-anomalies — Univariate anomaly detection
• /classify — Tabular data classification

Univariate Anomaly Detection

The /detect-anomalies endpoint performs anomaly detection on univariate time series data.

Data Format

JSON Example

curl -X POST 'http://0.0.0.0:8000/detect-anomalies' \
  -H 'Content-Type: application/json' \
  -d '[
    {"ts": "06-05-2024", "value": 1.9},
    {"ts": "06-06-2024", "value": 21.9},
    {"ts": "06-07-2024", "value": 12.9},
    {"ts": "06-08-2024", "value": 4531.9}
  ]'

Response:

[
  {"ts": 1717545600, "value": 1.9, "Anomaly": 0, "LowerThreshold": 1.21e+18, "MSE": 1.27e+18, "UpperThreshold": 1.33e+18},
  {"ts": 1717632000, "value": 21.9, "Anomaly": 0, "LowerThreshold": 1.21e+18, "MSE": 1.31e+18, "UpperThreshold": 1.33e+18},
  {"ts": 1717718400, "value": 12.9, "Anomaly": 0, "LowerThreshold": 1.21e+18, "MSE": 1.29e+18, "UpperThreshold": 1.33e+18},
  {"ts": 1717804800, "value": 4531.9, "Anomaly": 1, "LowerThreshold": 1.21e+18, "MSE": 1.21e+18, "UpperThreshold": 1.33e+18}
]

CSV Example

curl -X POST 'http://0.0.0.0:8000/detect-anomalies' \
  -H "Content-Type: text/csv" \
  -H "Accept: text/csv" \
  --data-binary @data/test.csv

Classification

The /classify endpoint performs classification on tabular data.

Note: Only supports single-channel (1-dimensional) tabular data. Each feature must be a scalar value.

Data Format

JSON Example

curl -X POST 'http://localhost:8000/classify' \
  -H "Content-Type: application/json" \
  -d '{
    "train_data": [
      {"sepal_length": 5.1, "sepal_width": 3.5, "petal_length": 1.4, "petal_width": 0.2, "species": "setosa"},
      {"sepal_length": 7.0, "sepal_width": 3.2, "petal_length": 4.7, "petal_width": 1.4, "species": "versicolor"},
      {"sepal_length": 6.3, "sepal_width": 3.3, "petal_length": 6.0, "petal_width": 2.5, "species": "virginica"}
    ],
    "test_data": [
      {"sepal_length": 5.0, "sepal_width": 3.4, "petal_length": 1.5, "petal_width": 0.2}
    ],
    "label_col": "species"
  }'

Response:

{
  "predictions": [
    {"sepal_length": 5.0, "sepal_width": 3.4, "petal_length": 1.5, "petal_width": 0.2, "predicted_class": 0, "predicted_class_label": "setosa"}
  ],
  "train_metrics": {"accuracy": 1.0, "f1_score": 1.0, "precision": 1.0, "recall": 1.0},
  "test_metrics": null
}

CSV File Upload

curl -X POST "http://localhost:8000/classify?label_col=species" \
  -H "Accept: application/json" \
  -F "train_data=@train.csv" \
  -F "test_data=@test.csv"

Saving AD-Transformer-1.0.0 Output to a File

# Anomaly detection output
curl -X POST 'http://0.0.0.0:8000/detect-anomalies' \
  -H 'Content-Type: application/json' \
  -d '[{"ts": "06-05-2024", "value": 1.9}]' \
  -o anomaly_results.json

# Classification output
curl -X POST 'http://localhost:8000/classify' \
  -H "Content-Type: application/json" \
  -d '{"train_data": [...], "test_data": [...], "label_col": "species"}' \
  > classification_results.json

API Reference

Common Endpoints (All Tags)

These endpoints are available in all NIM tags:

Inference Endpoints by Tag

Supported Formats

All inference endpoints support content negotiation:

Error Handling

HTTP Status Codes

Common Errors by Endpoint

Troubleshooting

Common Issues (All Tags)

Forecasting NIM Issues

AD-Diffusion NIM Issues

AD-Transformer-1.0.0 NIM Issues

Quick Reference Card

# Health check (all tags)
curl http://0.0.0.0:8000/v1/health/ready

# ============ FORECASTING-1.0.1 / 1.0.0 NIM ============
curl -X POST http://0.0.0.0:8000/forecast \
  -H "Content-Type: application/json" \
  -d '{"data": [...], "timestamp_column": "date", "target_column": "LULL", "forecast_horizon": 24}'

# ============ AD-Diffusion-1.0.0 / AD-Diffusion-1.1.0 NIM ============
curl -X POST http://0.0.0.0:8000/v2/detect-anomalies \
  -H "Content-Type: application/json" \
  -d '[{"feature_1": 100, "feature_2": 200}]'

# ============ AD-Transformer-1.0.0 NIM ============
# Univariate anomaly detection
curl -X POST http://0.0.0.0:8000/detect-anomalies \
  -H "Content-Type: application/json" \
  -d '[{"ts": "2024-01-01", "value": 1.5}]'

# Classification
curl -X POST http://0.0.0.0:8000/classify \
  -H "Content-Type: application/json" \
  -d '{"train_data": [...], "test_data": [...], "label_col": "label"}'

Interactive API Documentation: Visit http://localhost:8000/ after starting the container.

Get Help

NVIDIA Developer Community Forum

For support, Visit the NVIDIA Developer Community Forum

End of Support — "This artifact is no longer supported. NVIDIA strongly recommends artifacts that are up to date and supported"