---
title: "Installing ORCA VLMs"
slug: "installing-orca-vlms"
description: "Learn how to install ORCA VLM base models for both internet-connected and air-gapped deployments, ensuring GPU support for optimal performance."
updated: 2026-10-14T19:42:51Z
published: 2026-10-14T19:42:51Z
canonical: "help.hyperscience.ai/installing-orca-vlms"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.hyperscience.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing ORCA VLMs

This article explains how to install ORCA (Optical Reasoning and Cognition Agent) VLM base models.

For information about the capabilities of ORCA VLMs, see our [ORCA (Optical Reasoning and Cognition Agent) VLMs](/v44/docs/orca-vlms) article.

## Prerequisites

To successfully use ORCA VLMs:

> [!NOTE]
> Configure your infrastructure for ORCA VLMs
> 
> Make sure your instance supports GPU-enabled application machines.
> 
> - **On-premise deployment:** follow the instructions in the “Enabling Application Machines with GPUs” article for [Docker](/deployment/docs/enabling-application-machines-with-gpus-in-on-premise-docker-deployments), [Podman](/deployment/docs/enabling-application-machines-with-gpus-in-on-premise-podman-deployments), or [Kubernetes](/deployment/docs/enabling-application-machines-with-gpus-in-on-premise-kubernetes-deployments).
> - **SaaS deployment:** contact your Hyperscience representative to enable GPU support in your instance.
> 
> Learn more about Hyperscience’s GPU requirements in [Infrastructure Requirements](/deployment/docs/infrastructure-requirements#gpu).

Learn how to install ORCA VLM base models in both internet-connected and air-gapped deployments in the sections below.

## Installing an ORCA base model in deployments with internet access

In deployments with internet access (e.g., SaaS deployments and non-air-gapped on-premise deployments), available ORCA base models appear as separate cards in **Administration** > **Assets**. They can be installed through a pre-configured artifact repository, Cloudsmith, or Hyperscience Package Registry.

> [!NOTE]
> ORCA 2 base model
> 
> In v43.2 and later, the **ORCA 2** base model is available in addition to ORCA 1.0. Different base models provide different capabilities, and a specialized model inherits the capabilities of the base model selected for its training run. To learn more, see [TDM for ORCA VLMs](/v44/docs/tdm-for-orca-vlms) and [Training a Specialized Model](/v44/docs/training-a-specialized-model).

![](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/base_models.png?sv=2026-02-06&spr=https&st=2026-10-28T13%3A03%3A15Z&se=2026-10-28T14%3A03%3A15Z&sr=c&sp=r&sig=OPEK%2FqWQdIlR%2BNfGItT7Al8v9nH8rgM4hSiAAQ%2FGDis%3D)

> [!NOTE]
> Installing multiple base models
> 
> In v43.2 and later, multiple ORCA base models can be installed on the same instance. Install one base model at a time. When one installation finishes, you can repeat the procedure for another available base model.

Follow the steps below to install a base model.

1. Go to **Administration** > **Assets**.
2. On the card for the ORCA base model you want to install, click **Install**.
3. Choose how the ORCA base model should be downloaded:
  - **Fetch via Artifact Repository** — Uses the pre-configured repository to download the base model.
  - **Fetch via Cloudsmith** — Downloads the base model using your Cloudsmith key. If you don’t have a key for your account, file a ticket on our [Support portal](https://hyperscience.atlassian.net/helpcenter/customer/).
  - **Fetch via Hyperscience Package Registry** — Downloads the base model from Hyperscience Package Registry.

![](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/image(273).png?sv=2026-02-06&spr=https&st=2026-10-28T13%3A03%3A15Z&se=2026-10-28T14%3A03%3A15Z&sr=c&sp=r&sig=OPEK%2FqWQdIlR%2BNfGItT7Al8v9nH8rgM4hSiAAQ%2FGDis%3D)

1. Click **Start**.

- The selected ORCA base model card indicates that installation is in progress.

![](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/install_in_progress.png?sv=2026-02-06&spr=https&st=2026-10-28T13%3A03%3A15Z&se=2026-10-28T14%3A03%3A15Z&sr=c&sp=r&sig=OPEK%2FqWQdIlR%2BNfGItT7Al8v9nH8rgM4hSiAAQ%2FGDis%3D)

- You’ll receive a notification in the notifications panel (![](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/image-1771517801243.png?sv=2026-02-06&spr=https&st=2026-10-28T13%3A03%3A15Z&se=2026-10-28T14%3A03%3A15Z&sr=c&sp=r&sig=OPEK%2FqWQdIlR%2BNfGItT7Al8v9nH8rgM4hSiAAQ%2FGDis%3D)) once installation is complete.

![](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/image-1771517925792.png?sv=2026-02-06&spr=https&st=2026-10-28T13%3A03%3A15Z&se=2026-10-28T14%3A03%3A15Z&sr=c&sp=r&sig=OPEK%2FqWQdIlR%2BNfGItT7Al8v9nH8rgM4hSiAAQ%2FGDis%3D)

> [!NOTE]
> Base model dependencies
> 
> Keep a base model installed while specialized models depend on it. If a required base model is not installed, the affected Model Definition and specialized model versions are unavailable for deployment. The **History** tab identifies the missing base model and provides an **Install** action. Learn more in [Model Definitions](/v44/docs/model-definitions).

Each installation runs in the background. When it is complete, the selected base model becomes available for document processing and specialized model training.

## Installing an ORCA base model in air-gapped instances

In some on-premise deployments, the instance may be air-gapped, meaning it does not have direct internet access and cannot download assets from external repositories such as Cloudsmith.

In these cases, each ORCA base model must be installed through a manual transfer process. Repeat the process for every base model you want to install. Instead of downloading the model directly on your instance, you will:

- Download the ORCA base model assets on a machine with internet access.
- Transfer the files to your secured internal storage (e.g., S3).
- Configure an Artifacts Repository pointing to that storage.
- Install the ORCA base model from the configured repository.

> [!NOTE]
> Important considerations
> 
> - This process is required only for air-gapped or restricted instances.
> - ORCA model assets are split into multiple chunks to improve reliability in restricted or unstable network conditions:
>   - Each chunk can be downloaded independently.
>   - If a download fails, only the affected chunk needs to be retried. This setup eliminates the need to restart the entire download process.
>   - Downloads and uploads can be performed in parallel (e.g., uploading one chunk while others are still downloading), improving overall transfer efficiency.
>   - Chunked downloads also help mitigate firewall timeouts and bandwidth limitations.

Each step is described in the sections below:

1. Download the selected ORCA base model's assets from Cloudsmith:
  - ORCA VLM assets are split into multiple files (chunks). You need to download all required files before proceeding. You can either download them manually or use a script to retrieve all required assets automatically.
    - All chunk files listed in the selected base model's manifest.
    - The corresponding block-asset definition file.
    - The manifest file: `orca_repo_manifest.json`.

> [!NOTE]
> Automatically download ORCA VLM assets
> 
> You can download the files manually from the Cloudsmith repository. However, because the assets are split into multiple files, we recommend using a script to download them automatically.

- Download ORCA VLM assets using a script:
  - The script downloads all required files directly from the Cloudsmith repository using your access key. It works as follows:
    - First, it downloads the `orca_repo_manifest.json` file.
      - This file contains the list of all required ORCA assets and their locations.
    - The script then uses this list to download all remaining files.
  - The example below is designed for instances that support bash (e.g., Linux or macOS).
    - For Windows instances, you may need to adapt the script (e.g., using PowerShell) or use a compatible shell. For more information, file a ticket on our [Support portal](https://hyperscience.atlassian.net/helpcenter/customer/).

> [!NOTE]
> Before runing the script
> 
> - Ensure you are using a valid Cloudsmith key with access to the `hs-assets` repository.
> - Ensure `curl` and `jq` are installed

```bash
KEY="your-cloudsmith-key"
BASE="https://dl.cloudsmith.io/${KEY}/hyperscience/hs-assets/raw/files"
OUT="./orca_chunks"
mkdir -p "$OUT"

# 1. Download the manifest (query params needed only here)
curl -o "${OUT}/orca_repo_manifest.json" "${BASE}/orca_repo_manifest.json?accept=true&accept_eula=1"

# 2. Download every chunk (NO query params — urljoin drops them, Cloudsmith doesn't need them)
jq -r '.artifacts[].location' "${OUT}/orca_repo_manifest.json" | while read loc; do
  echo "Downloading ${loc} ..."
  curl -o "${OUT}/${loc}" "${BASE}/${loc}"
done
```

1. Prepare ORCA VLM assets for S3 repositories

> [!NOTE]
> S3 bucket with ZIP artifacts
> 
> This step is required only when using an S3 bucket with ZIPs artifact repository. It is not required when installing ORCA directly from Cloudsmith.

Before uploading the downloaded ORCA VLM assets to an S3 bucket, you must prepare them for use with the **S3 bucket with ZIPs** artifact repository type.

The downloaded ORCA package contains:

- Chunk files (`block_asset_chunk__*.zip`)
- A block asset definition file (`block_asset__*.json`)
- A manifest file (`orca_repo_manifest.json`)

To make the assets compatible with the artifact repository, run the provided Python script. The script creates ZIP bundles containing both the artifact and the corresponding manifest information required by the repository.

- Before running the script, ensure that:
  - Python 3 is installed on the machine.
  - The downloaded ORCA assets and `orca_repo_manifest.json` are stored in the same directory.
  - The `wrap_artifacts_for_s3_zips.py` script is available on the machine.
- Run the script

```python
import argparse
import json
import logging
import zipfile
from pathlib import Path

logger = logging.getLogger(__name__)

REPO_MANIFEST_JSON = 'orca_repo_manifest.json'

def wrap_artifacts(input_dir: Path, output_dir: Path) -> None:
    manifest_path = input_dir / REPO_MANIFEST_JSON
    if not manifest_path.is_file():
        raise FileNotFoundError(f'{manifest_path} not found')

    with manifest_path.open('r', encoding='utf-8') as f:
        manifest = json.load(f)

    artifacts = manifest.get('artifacts', [])
    if not artifacts:
        raise ValueError(f'No artifacts found in {manifest_path}')

    output_dir.mkdir(parents=True, exist_ok=True)

    for entry in artifacts:
        location = entry['location']
        source_file = input_dir / location
        if not source_file.is_file():
            raise FileNotFoundError(f'Artifact file missing: {source_file}')

        # Single-entry manifest for this wrapper ZIP
        single_manifest = {'artifacts': [entry]}
        single_manifest_bytes = json.dumps(single_manifest, indent=2).encode('utf-8')

        # Output ZIP name: same stem as the artifact, always `.zip`
        wrapper_name = Path(location).stem + '.zip'
        wrapper_path = output_dir / wrapper_name

        logger.info('Creating %s wrapping %s', wrapper_path.name, location)
        with zipfile.ZipFile(wrapper_path, mode='w', compression=zipfile.ZIP_STORED) as zf:
            zf.writestr(REPO_MANIFEST_JSON, single_manifest_bytes)
            zf.write(source_file, arcname=location)

    logger.info('Wrote %d wrapper ZIPs to %s', len(artifacts), output_dir)

def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        '--input', '-i', required=True, type=Path,
        help='Directory containing orca_repo_manifest.json and the artifact files',
    )
    parser.add_argument(
        '--output', '-o', required=True, type=Path,
        help='Directory where wrapper ZIPs will be written',
    )
    args = parser.parse_args()

    logging.basicConfig(
        level=logging.INFO,
        format='%(asctime)s %(levelname)s %(message)s',
    )

    wrap_artifacts(args.input.expanduser(), args.output.expanduser())

if __name__ == '__main__':
    main()
```

Where:

- `--input` specifies the directory containing the downloaded ORCA assets and `orca_repo_manifest.json`.
- `--output` specifies the directory where the generated ZIP bundles will be created.

The script creates a ZIP file for each ORCA artifact. These generated ZIP files must be uploaded to your S3 bucket and used when configuring the artifact repository.

1. Upload the prepared ORCA VLM assets to internal storage (S3):
  - Go to your S3 bucket (e.g., `s3://hs-build-artifact/block-asset/`).
  - Create a new folder called `orca` .
    - Final path: `s3://hs-build-artifact/block-asset/orca/`
  - Place the assets in the folder.

![](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/s3.jpg?sv=2026-02-06&spr=https&st=2026-10-28T13%3A03%3A15Z&se=2026-10-28T14%3A03%3A15Z&sr=c&sp=r&sig=OPEK%2FqWQdIlR%2BNfGItT7Al8v9nH8rgM4hSiAAQ%2FGDis%3D)

1. Configure the Artifact Repository in your instance:
  - Add `/admin` at the end of your instance’s URL:
    - `instance.hs.ai/admin`
  - Using the browser’s search, find `Artifact repositorys`.
  - Click **Add Artifacts Repository**.
  - Enter a name for the repository.
    - We recommend choosing a human-friendly repository name, for example, **S3**.
  - From the **Repo type** drop-down list, select **S3 bucket with ZIPs**.
  - Enter the following in the **Configs** field:

```json
{
  "s3_path": "s3://hs-build-artifact/block-asset/",
  "s3_region": null
}
```

![](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/repo.gif?sv=2026-02-06&spr=https&st=2026-10-28T13%3A03%3A15Z&se=2026-10-28T14%3A03%3A15Z&sr=c&sp=r&sig=OPEK%2FqWQdIlR%2BNfGItT7Al8v9nH8rgM4hSiAAQ%2FGDis%3D)

1. Go to **Administration** > **Assets**.
2. On the card for the ORCA base model whose assets you transferred, click **Install**.
3. Choose **Fetch via Artifact Repository**. The system will now install the ORCA base model using the files from your internal storage.

> [!NOTE]
> Generated ZIP bundles
> 
> The generated ZIP bundles replace the originally downloaded files for S3 uploads.

## Next steps

After installing an ORCA base model, complete the following steps to use VLM Field Extraction:

1. Create or update a Semi-structured Layout with at least one field. See [Creating Semi-structured Layouts](/v44/docs/creating-semi-structured-layouts).
2. Include the layout in a release, and configure the ORCA subflow in the **Document Processing** flow. See [Document Processing Flow](/v44/docs/document-processing-flow).
3. Optional: To adapt the base model to your specific use case, [create a model definition](/v44/docs/model-definitions) and [train a specialized model](/v44/docs/training-a-specialized-model).

Hyperscience's Vision Language Model (VLM) framework for extracting information from semi-structured documents. ORCA supports multiple base models, such as ORCA 1.0 and ORCA 2. You can use these base models as-is or train specialized models on top of them to improve extraction performance for your specific use case. Learn more in [ORCA Visual Language Models](https://help.hyperscience.ai/latest/docs/orca-optical-reasoning-and-cognition-agent-vlms).

A foundational model that provides core general-purpose capabilities and is not directly trained on customer-specific examples. Use-case specialization is achieved through additional training on top of the base model using customer-specific data.

A configuration object used to manage Vision Language Models (VLMs). Model definitions define a model's scope, task, compatibility, deployment status, and associated model versions. Learn more in [Model Definitions](https://help.hyperscience.ai/latest/docs/model-definitions).

A configuration within Hyperscience designed to process documents where fields and table cells are present, but their positions can vary among documents. Unlike Structured layouts, Semi-structured layouts do not rely on fixed field locations. Instead, a model is trained to find the fields and cells based on provided training examples.