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.
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 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
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.
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.
[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.
Process overview
Install ORCA 2
Train a specialized model on ORCA 2
Switch your flows to ORCA 2
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.
Go to Administration > Assets.
Click Install on the ORCA 2 card.
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.
Checkpoint: ORCA 2 appears as installed on the Assets page, and your ORCA 1.0 flows continue to run.
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.
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.
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.
In TDM, open the model definition you want to upgrade.
Click the page-level Actions menu, and then select Train model.
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.
When training completes, review the candidate model on the Overview tab.
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.
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.
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.
Open a flow that uses ORCA.
Set the Setting type to ORCA.
Select ORCA 2 from the ORCA Base Model drop-down.
Deploy the flow.
Repeat steps 1–3 for each flow that uses ORCA.
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.
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.
Go to Administration > Assets.
Click Uninstall on the ORCA 1.0 card.
Review the flows and specialized models that the dialog lists.
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) in ORCA Vision Language Models.