---
title: "Upgrading ORCA base models"
slug: "upgrading-orca-base-models"
description: "Upgrade from ORCA 1.0 to ORCA 2 in Hyperscience: install, retrain models, switch flows, test results, and safely uninstall ORCA 1.0."
updated: 2026-10-21T17:02:52Z
published: 2026-10-21T17:02:52Z
canonical: "help.hyperscience.ai/upgrading-orca-base-models"
---

> ## 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.

# Upgrading ORCA base models

This guide helps you move your document processing from ORCA (Optical Reasoning and Cognition Agent) 1.0 to ORCA 2. Use it when you want to adopt ORCA 2 on an instance that already runs ORCA 1.0.

> [!NOTE]
> ORCA 2 is available in v43.2 and later
> 
> To learn which features are available to your organization, contact your Hyperscience representative.

Unlike ORCA 1.0, ORCA 2 extracts tables without a Semi-structured layout or a trained Table Identification model. To check which capabilities each base model supports, see [Choosing a base model](/v43/docs/orca-vlms#choosing-a-base-model) in ORCA Vision Language Models.

Hyperscience continues to support ORCA 1.0, so you can upgrade at a time that suits you.

## Before you start

> [!NOTE]
> ORCA 2 can return different extraction results
> 
> ORCA 2 responds differently to the same prompts and field notes, so extraction results can change. Retest your flows, revise prompts and field notes where the results require it, and retrain every specialized model you want to keep using.

You can run ORCA 1.0 and ORCA 2 on the same instance, so your existing processing continues while you prepare and test ORCA 2. The upgrade deletes nothing, and you can return to ORCA 1.0 until you uninstall it.

Make these decisions before you begin:

| Decision | Options | Choose based on |
| --- | --- | --- |
| Whether to train a specialized model on ORCA 2 | Use ORCA 2 on its own; train a specialized model | Train a specialized model when you need higher extraction accuracy than the base model provides, or when you need thresholding. |
| When to uninstall ORCA 1.0 | Uninstall after the upgrade; keep it installed | Uninstall to release the GPU machine that serves it. Keep it installed if you want to roll back. |

### Required permissions

The actions in this guide require the following permissions. To learn more, see [Permission Groups](/v43/docs/permission-groups).

| Permission | Allows you to | Assigned by default to |
| --- | --- | --- |
| **View Models** | Install and uninstall base models on the **Assets** page, and send base model requests through the API. | System admin |

### Prerequisites

To upgrade from ORCA 1.0 to ORCA 2, ensure that:

- ORCA 1.0 is installed.
- You have access to the ORCA 2 model artifact.
- You have a second GPU machine during the upgrade.
  - Each base model needs its own GPU machine, so running both at the same time requires 2 GPU machines.
  - To provision one, see [Enabling application machines with GPUs in on-premise Kubernetes deployments](/deployment/docs/enabling-application-machines-with-gpus-in-on-premise-kubernetes-deployments).
- [Recommended] If you plan to train a specialized model, you have annotated training documents.
  - Your existing ORCA 1.0 training documents also apply to ORCA 2, and the training requirements are the same. To learn more, see [Training a Specialized Model](/v43/docs/training-a-specialized-model).

## Process overview

1. Install ORCA 2
2. Train a specialized model on ORCA 2
3. Switch your flows to ORCA 2
4. Uninstall ORCA 1.0

## 1. Install ORCA 2

Installing ORCA 2 does not affect ORCA 1.0, your existing specialized models, or any running flow.

1. Go to **Administration** > **Assets**.
2. Click **Install** on the ORCA 2 card.
3. If the instance requires credentials, enter your artifact source credentials.

- Leave ORCA 1.0 installed. For the full procedure, including air-gapped instances, see [Installing ORCA VLMs](/v43/docs/installing-orca-vlms).

- **Checkpoint:** ORCA 2 appears as installed on the **Assets** page, and your ORCA 1.0 flows continue to run.

![Administration assets page highlights installed ORCA 1.0 and ORCA 2 base models with uninstall options.](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/orcas.png?sv=2026-02-06&spr=https&st=2026-11-09T19%3A52%3A18Z&se=2026-11-09T20%3A52%3A18Z&sr=c&sp=r&sig=JIe8nosZlff%2FgTdyp0M1V6XMwlMqat4Gi4OhrUvnhv4%3D)

## 2. Train a specialized model on ORCA 2

Complete this step only if you decided to train a specialized model. If you use ORCA 2 on its own, skip to [step 3](/v43/docs/upgrading-orca-base-models#3-switch-your-flows-to-orca-2).

Training produces a new specialized model alongside your existing one. Your ORCA 1.0 model does not change, and it stays live until you deploy the new model.

> [!NOTE]
> Deploying an ORCA 2 specialized model deactivates the model it replaces
> 
> Only one specialized model can be live at a time for each Model Definition. The system does not delete the ORCA 1.0 model. To roll back, deploy it again.

1. In TDM, open the model definition you want to upgrade.
2. Click the page-level **Actions** menu, and then select **Train model**.
3. In the **Select model** dialog, select **ORCA 2**, and then click **Train model**.
  - This dialog appears only when more than one base model is installed.
4. When training completes, review the candidate model on the **Overview** tab.
5. Click the page-level **Actions** menu, and then select **Deploy candidate model**.

For the full procedure, including dataset requirements and validation, see [Training a Specialized Model](/v43/docs/training-a-specialized-model).

![Models page shows the expanded Actions menu with Train model highlighted.](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/tdm-user-guide-44-train-model.png?sv=2026-02-06&spr=https&st=2026-11-09T19%3A52%3A18Z&se=2026-11-09T20%3A52%3A18Z&sr=c&sp=r&sig=JIe8nosZlff%2FgTdyp0M1V6XMwlMqat4Gi4OhrUvnhv4%3D)

- **Checkpoint:** The ORCA 2 specialized model is **Live**, and the ORCA 1.0 model it replaced is **Inactive**.

## 3. Switch your flows to ORCA 2

Each flow specifies which base model it uses.

- A flow set to ORCA 1.0 continues to use ORCA 1.0 until you change the setting.
- If you trained a specialized model in step 2, the flow uses it after you change the base model. The system uses a specialized model only when it was trained on the flow's base model.

> [!NOTE]
> Custom flows can reference a base model directly
> 
> A custom flow can specify a base model ID instead of using the flow setting. Check each custom flow that uses ORCA, and update the ID to the ORCA 2 model ID, `ef3863d8-87d0-4528-999a-00b52fa72cd0`.

1. Open a flow that uses ORCA.
2. Set the **Setting type** to **ORCA**.
3. Select ORCA 2 from the **ORCA Base Model** drop-down.
4. Deploy the flow.
5. Repeat steps 1–3 for each flow that uses ORCA.

![Document processing workflow with ORCA settings dropdown open, showing None, ORCA 1.0, and ORCA 2 options.](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/base_model_select.png?sv=2026-02-06&spr=https&st=2026-11-09T19%3A52%3A18Z&se=2026-11-09T20%3A52%3A18Z&sr=c&sp=r&sig=JIe8nosZlff%2FgTdyp0M1V6XMwlMqat4Gi4OhrUvnhv4%3D)

- **Checkpoint:** Each flow runs on ORCA 2 and new submissions are successfully processed.

## 4. Uninstall ORCA 1.0

Complete this stage only when every flow uses ORCA 2, and you no longer need any specialized model trained on ORCA 1.0. You can also keep ORCA 1.0 installed.

> [!NOTE]
> Uninstalling ORCA 1.0 undeploys flows that still use it
> 
> The uninstall also deactivates every specialized model built on ORCA 1.0. The uninstall dialog lists the affected flows and models.

1. Go to **Administration** > **Assets**.
2. Click **Uninstall** on the ORCA 1.0 card.
3. Review the flows and specialized models that the dialog lists.
4. Click **Uninstall Base Model**.

After you uninstall ORCA 1.0, you can decommission the GPU machine that served it.

- **Checkpoint:** ORCA 1.0 no longer appears as installed, and every flow runs on ORCA 2.

## Recommendations

- **Upgrade one flow at a time**
  - Both base models remain available during the upgrade, so you can confirm each flow before you move the next one.
- **Compare extraction results before you deploy a flow on ORCA 2**
  - Run representative documents through the flow, and revise the prompts and field notes as needed.
- **Set the base model on every new flow**
  - Most ORCA flows default to ORCA 1.0.
  - A flow you create from one of them runs on ORCA 1.0 unless you change the setting.
  - The following table lists the default base model for each template.

| Flow | Default base model |
| --- | --- |
| Document analysis | ORCA 1.0 |
| Optical Reasoning Cognition Agent (ORCA) | ORCA 1.0 |
| VLM | ORCA 1.0 |
| Out-of-the-box table extraction | ORCA 2 |

## Next steps

To measure extraction accuracy on ORCA 2, see [VLM Quality Assurance (QA)](/v43/docs/orca-vlms#vlm-quality-assurance) in ORCA Vision Language Models.

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 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.

A machine learning model in Hyperscience that learns where cells and rows are located in Semi-structured documents. It uses examples from training to predict the position of each cell and row on a page so the system can extract the correct data. Learn more in [Identification models](https://help.hyperscience.ai/latest/docs/identification-models).

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.

**Accuracy** measures the effectiveness of the models based on the proportion of correct predictions out of all predictions made. It helps you understand how often the system correctly predicts values compared to the actual values that reached consensus during QA. Accuracy can be influenced by factors like imbalanced datasets or inconsistent annotations.

**Thresholding** is the process of setting a confidence limit in a system to determine how decisions are made. Predictions above the threshold are automated, while those below are flagged for human review, ensuring accuracy and reliability.

A model created by training on customer-specific, annotated documents on top of a base model. It is tailored to a particular layout and use case to improve extraction accuracy and automation. To learn more, see [Training a Specialized model](https://help.hyperscience.ai/latest/docs/training-a-specialized-model).

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 group of documents used to help the system learn or improve. Datasets are used for training, testing, or evaluating how well the system reads and extracts information.