Ising Calibration Setup
Purpose
Get a user from zero to a verified working connection to the NVIDIA
Ising Calibration model (Ising-Calibration-1.5-31B), in either of two ways:
- Hosted API on build.nvidia.com -- fastest, no GPU required.
- Self-hosted NIM container -- for on-premises, data-residency, or
high-volume use, requires a supported NVIDIA GPU.
This skill is plumbing-scoped: getting a key, getting a 200 back, and
confirming that connection actually works. It stops there -- it does not
teach how to use the model (prompting it for calibration analysis, building
an agent workflow around it, etc.). See "Next steps" below for where that
guidance lives.
Instructions
Ask the user which they want (or infer it: "I don't have a GPU" -> hosted API;
"I need this on-prem / air-gapped / high volume" -> self-hosted NIM). Note that
the self-hosted container still needs internet access on its first run to
download the model weights. Then follow the matching section below
top-to-bottom. Full command sequences live in references/; this file only
handles routing, prerequisites, and the connectivity checklist.
Getting the credential is where users most often get stuck, and it happens in a
browser where you cannot see what they see. Read the relevant reference doc in
full before starting, then take them through one screen at a time, saying what
they should expect to see and waiting for confirmation before moving on, rather
than handing over a URL and waiting for them to return with a key. Never ask the
user to paste a key into the conversation; have them load it into their own
shell and verify it there.
Name the two setups when talking to the user: "the hosted API at
build.nvidia.com" and "a self-hosted NIM container". Refer to each step by what
it does ("generating an NGC personal key", "pulling the NIM container") rather
than by its number in the lists below.
When to use
- "How do I connect to Ising Calibration?"
- "Set up the Ising Calibration model"
- "Get an API key for build.nvidia.com / Ising"
- "Run / self-host the Ising Calibration NIM" (own hardware or a cloud GPU instance)
- "My Ising Calibration API calls are failing, check my setup"
- "/ising-calibration-setup"
Prerequisites (either setup)
- An NVIDIA account (create one at build.nvidia.com or ngc.nvidia.com if the
user does not have one).
curl available locally for connectivity checks.
jq, only if the user wants the optional hello-world request at the end. The
reference docs give a python3 fallback if it is not installed.
Hosted API (build.nvidia.com)
No GPU needed; requests are billed/rate-limited against the hosted endpoint.
- Sign in at
https://build.nvidia.com.
- Generate a personal API key: profile menu -> Settings -> API keys ->
Generate API Key (or go directly to
https://build.nvidia.com/settings/api-keys).
You will be asked to name the key and set an expiration. The key starts
with nvapi- and is shown only once -- store it immediately without
letting it land in shell history (see
references/hosted-api-quickstart.md
for a read -rs-based method).
- The model page, for rate limits and current terms:
https://build.nvidia.com/nvidia/ising-calibration-1.5-31b.
- Follow
references/hosted-api-quickstart.md
for the endpoint, the request format, and a working curl example.
Governed by the NVIDIA API Trial Terms of Service.
Self-hosted NIM container
Requires an NVIDIA Ada Lovelace, Hopper, or Blackwell GPU with enough memory (see
the reference doc for tested configurations), plus Docker with the NVIDIA
Container Toolkit installed -- docker run --gpus all fails without it.
Walk the user through these rather than summarizing them; the full walkthrough
is in references/self-hosted-nim-quickstart.md,
which you should read before starting.
Sign in at https://org.ngc.nvidia.com.
Go to https://org.ngc.nvidia.com/setup/personal-keys (or: account icon ->
Setup -> Generate Personal Key) and click Generate Personal Key.
Fill in the dialog's three required fields: Key Name, Expiration, and
Services Included -- a dropdown of per-service checkboxes. NGC Catalog
is the only scope needed; it grants pulls from the public nvcr.io catalog,
and without it docker login fails with an auth error even though the key is
valid.
The key is shown once. Have the user copy it and load it into their shell
with read -rs NGC_API_KEY (not export NGC_API_KEY=..., which lands the
raw key in shell history), then confirm it is set with a check that does not
print it: test -n "$NGC_API_KEY" && echo set.
This is a separate credential from the nvapi- key used for the hosted
API. If the user already has an nvapi- key, tell them it will not work here
and they need to generate this one as well.
Log Docker in to the NVIDIA container registry -- this is also the check that
the key and its scopes are right, so do it before pulling anything:
echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
Expect Login Succeeded. If it fails, fix the key here rather than
continuing to the pull.
Pull and run the container, then confirm it is serving. Use the docker run
from the quickstart as written, including -e NGC_API_KEY=$NGC_API_KEY,
which passes the key into the container. Full command, GPU/memory
requirements, health check, and example request are in
references/self-hosted-nim-quickstart.md.
Run the connectivity checklist. You can then offer the optional hello-world
request below, the same as for the hosted API.
Connectivity checklist
Run this for either setup to confirm the connection actually works, and to tell
an auth failure apart from a network/model-not-ready failure. Full checklist
with copy-pasteable commands: references/connectivity-checklist.md.
Summary:
- Hosted API: confirm
NVIDIA_API_KEY is set and non-empty. Self-hosted NIM:
there is no request-time key -- NGC_API_KEY is used for the image pull and
passed into the container at startup, not sent with requests -- so confirm
the container is running and ready instead.
- Send one lightweight request against the endpoint.
- A
401/403 means different things per setup. Hosted API: the key is
missing, wrong, or expired -- regenerate it. Self-hosted NIM: the container
itself never returns 401, so a proxy, gateway, or load balancer in front of
it is rejecting the request -- check that layer, not the NGC key.
- A connection-refused/timeout against a self-hosted NIM means the container
is not up yet or the port mapping is wrong -- check
docker ps and
container logs before assuming an auth problem.
Hello world: an optional first real request
A 200 from the connectivity checklist is the bar for a working connection --
setup is done at that point. A text ping does not exercise the multimodal path
though, so a real calibration-plot request is a useful way to see the connection
do the model's actual job. Offer it for either setup and let the user decide
whether to run it. Each reference has a "Hello world" section with the request:
- Hosted API:
references/hosted-api-quickstart.md
- Self-hosted NIM:
references/self-hosted-nim-quickstart.md
Both pull a real sample image from the public QCalEval benchmark dataset, so no
local test image is needed. The request shape is the same either way; only the
endpoint and model ID differ -- read the self-hosted ID from /v1/models rather
than copying the hosted string across.
Examples
- "I don't have a GPU, how do I try Ising Calibration?" -> hosted API path:
generate an nvapi- key, store it as
NVIDIA_API_KEY, verify with the curl
ping in references/hosted-api-quickstart.md.
- "Run the Ising Calibration NIM on our H200 box" -> self-hosted path: generate
an NGC personal key with the NGC Catalog scope,
docker login, pull and run
the container, wait for /v1/health/ready.
- "My calls return 401" -> connectivity checklist: establish which setup first,
then follow the matching Troubleshooting entry below.
Next steps
Once the connectivity checklist passes, this skill's job is done -- you have a
working, authenticated connection. What to do with it is out of scope here;
go to:
Limitations
- Hosted API rate limits and pricing are not published in this skill; check
the build.nvidia.com model page for current terms.
- GPU memory requirements vary by GPU family -- see
references/self-hosted-nim-quickstart.md for the tested configurations.
Troubleshooting
- Error:
401 Unauthorized on the hosted API. Cause: missing/expired
NVIDIA_API_KEY, or using the NGC key instead of the nvapi- key.
Solution: regenerate at build.nvidia.com/settings/api-keys.
- Error:
docker login or docker pull fails with auth error. Cause:
missing/expired NGC_API_KEY (or set in a different shell than the one
running docker login); using the nvapi- key instead of the NGC key; or a
key whose service scopes omit NGC Catalog. Solution: check the scope
before assuming the key is bad -- a wrongly-scoped key fails identically to an
invalid one. Regenerate at org.ngc.nvidia.com/setup/personal-keys with NGC
Catalog included.
- Error:
docker login succeeds but docker pull returns 401 or
"not found". Cause: the credential is fine but the image is not visible
to the account, typically an unaccepted access agreement on the catalog page.
Solution: have the user open the catalog page while signed in to confirm
the image is visible to their account.
- Error:
401/403 from a self-hosted NIM endpoint. Cause: the
container does not authenticate requests, so the rejection comes from a
reverse proxy, API gateway, or load balancer in front of it. Solution:
check that layer's configuration and credentials. To confirm, bypass it:
on the machine running Docker, curl localhost:<host-port>, where the host
port is the left side of the -p flag shown by docker ps (8000 if the
quickstart command was used unchanged). A 200 there proves the container
is fine and the 401 comes from the layer in front. Regenerating the NGC key
does not help here.
- Error: container starts but the startup weight download fails.
Cause: the weights come from public Hugging Face, so the usual cause is
outbound network access from the container (proxy, firewall, DNS, or
huggingface.co blocked). Solution: check
docker logs <container> for
the failing URL and fix egress.
- Error: connection refused on
localhost:8000 (or whichever host port
was mapped). Cause: NIM container still loading weights, crashed, or the
-p host port does not match the one being curled.
Solution: check docker ps and docker logs <container>; wait for
/v1/health/ready to return 200 before sending requests.
- Error:
Insufficient GPU memory / OOM on container start. Cause: the
GPU does not have enough memory for any configuration the container can run.
Solution: use a GPU with more memory, or more GPUs; see the tested
configurations in references/self-hosted-nim-quickstart.md.
1---2name: ising-calibration-setup3description: >-4 Use when connecting to the NVIDIA Ising Calibration model via the hosted5 API or a self-hosted NIM. Covers auth, keys and connectivity checks only.6license: Apache-2.07version: "0.1.0"8permissions: [env, network, shell]9tags: [nvidia, ising, quantum, calibration, nim, api, setup]10metadata:11 source: https://skillmd.com/skills/nvidia/ising-calibration-setup12 author: "NVIDIA"13 version: "0.1.0"14 github-url: "https://github.com/NVIDIA/Ising"15 tags: [nvidia, ising, quantum, calibration, nim, api, setup]16---1718# Ising Calibration Setup1920## Purpose2122Get a user from zero to a **verified working connection** to the NVIDIA23Ising Calibration model (Ising-Calibration-1.5-31B), in either of two ways:2425- **Hosted API** on build.nvidia.com -- fastest, no GPU required.26- **Self-hosted NIM** container -- for on-premises, data-residency, or27 high-volume use, requires a supported NVIDIA GPU.2829This skill is plumbing-scoped: getting a key, getting a `200` back, and30confirming that connection actually works. It stops there -- it does not31teach how to use the model (prompting it for calibration analysis, building32an agent workflow around it, etc.). See "Next steps" below for where that33guidance lives.3435## Instructions3637Ask the user which they want (or infer it: "I don't have a GPU" -> hosted API;38"I need this on-prem / air-gapped / high volume" -> self-hosted NIM). Note that39the self-hosted container still needs internet access on its first run to40download the model weights. Then follow the matching section below41top-to-bottom. Full command sequences live in `references/`; this file only42handles routing, prerequisites, and the connectivity checklist.4344Getting the credential is where users most often get stuck, and it happens in a45browser where you cannot see what they see. Read the relevant reference doc in46full before starting, then take them through one screen at a time, saying what47they should expect to see and waiting for confirmation before moving on, rather48than handing over a URL and waiting for them to return with a key. Never ask the49user to paste a key into the conversation; have them load it into their own50shell and verify it there.5152Name the two setups when talking to the user: "the hosted API at53build.nvidia.com" and "a self-hosted NIM container". Refer to each step by what54it does ("generating an NGC personal key", "pulling the NIM container") rather55than by its number in the lists below.5657### When to use5859- "How do I connect to Ising Calibration?"60- "Set up the Ising Calibration model"61- "Get an API key for build.nvidia.com / Ising"62- "Run / self-host the Ising Calibration NIM" (own hardware or a cloud GPU instance)63- "My Ising Calibration API calls are failing, check my setup"64- "/ising-calibration-setup"6566### Prerequisites (either setup)6768- An NVIDIA account (create one at build.nvidia.com or ngc.nvidia.com if the69 user does not have one).70- `curl` available locally for connectivity checks.71- `jq`, only if the user wants the optional hello-world request at the end. The72 reference docs give a `python3` fallback if it is not installed.7374## Hosted API (build.nvidia.com)7576No GPU needed; requests are billed/rate-limited against the hosted endpoint.77781. Sign in at `https://build.nvidia.com`.792. Generate a personal API key: profile menu -> Settings -> API keys ->80 **Generate API Key** (or go directly to `https://build.nvidia.com/settings/api-keys`).81 You will be asked to name the key and set an expiration. The key starts82 with `nvapi-` and is shown only once -- store it immediately without83 letting it land in shell history (see84 [`references/hosted-api-quickstart.md`](references/hosted-api-quickstart.md)85 for a `read -rs`-based method).863. The model page, for rate limits and current terms:87 `https://build.nvidia.com/nvidia/ising-calibration-1.5-31b`.884. Follow [`references/hosted-api-quickstart.md`](references/hosted-api-quickstart.md)89 for the endpoint, the request format, and a working `curl` example.9091Governed by the NVIDIA API Trial Terms of Service.9293## Self-hosted NIM container9495Requires an NVIDIA Ada Lovelace, Hopper, or Blackwell GPU with enough memory (see96the reference doc for tested configurations), plus Docker with the **NVIDIA97Container Toolkit** installed -- `docker run --gpus all` fails without it.9899Walk the user through these rather than summarizing them; the full walkthrough100is in [`references/self-hosted-nim-quickstart.md`](references/self-hosted-nim-quickstart.md),101which you should read before starting.1021031. Sign in at `https://org.ngc.nvidia.com`.1042. Go to `https://org.ngc.nvidia.com/setup/personal-keys` (or: account icon ->105 Setup -> Generate Personal Key) and click **Generate Personal Key**.1063. Fill in the dialog's three required fields: **Key Name**, **Expiration**, and107 **Services Included** -- a dropdown of per-service checkboxes. **NGC Catalog**108 is the only scope needed; it grants pulls from the public nvcr.io catalog,109 and without it `docker login` fails with an auth error even though the key is110 valid.1114. The key is shown **once**. Have the user copy it and load it into their shell112 with `read -rs NGC_API_KEY` (not `export NGC_API_KEY=...`, which lands the113 raw key in shell history), then confirm it is set with a check that does not114 print it: `test -n "$NGC_API_KEY" && echo set`.115116 This is a **separate credential** from the `nvapi-` key used for the hosted117 API. If the user already has an `nvapi-` key, tell them it will not work here118 and they need to generate this one as well.1195. Log Docker in to the NVIDIA container registry -- this is also the check that120 the key and its scopes are right, so do it before pulling anything:121 `echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin`122 Expect `Login Succeeded`. If it fails, fix the key here rather than123 continuing to the pull.1246. Pull and run the container, then confirm it is serving. Use the `docker run`125 from the quickstart as written, including `-e NGC_API_KEY=$NGC_API_KEY`,126 which passes the key into the container. Full command, GPU/memory127 requirements, health check, and example request are in128 [`references/self-hosted-nim-quickstart.md`](references/self-hosted-nim-quickstart.md).1297. Run the connectivity checklist. You can then offer the optional hello-world130 request below, the same as for the hosted API.131132## Connectivity checklist133134Run this for either setup to confirm the connection actually works, and to tell135an auth failure apart from a network/model-not-ready failure. Full checklist136with copy-pasteable commands: [`references/connectivity-checklist.md`](references/connectivity-checklist.md).137138Summary:1391401. Hosted API: confirm `NVIDIA_API_KEY` is set and non-empty. Self-hosted NIM:141 there is no request-time key -- `NGC_API_KEY` is used for the image pull and142 passed into the container at startup, not sent with requests -- so confirm143 the container is running and ready instead.1442. Send one lightweight request against the endpoint.1453. A `401`/`403` means different things per setup. Hosted API: the key is146 missing, wrong, or expired -- regenerate it. Self-hosted NIM: the container147 itself never returns 401, so a proxy, gateway, or load balancer in front of148 it is rejecting the request -- check that layer, not the NGC key.1494. A connection-refused/timeout against a self-hosted NIM means the container150 is not up yet or the port mapping is wrong -- check `docker ps` and151 container logs before assuming an auth problem.152153## Hello world: an optional first real request154155A `200` from the connectivity checklist is the bar for a working connection --156setup is done at that point. A text ping does not exercise the multimodal path157though, so a real calibration-plot request is a useful way to see the connection158do the model's actual job. Offer it for either setup and let the user decide159whether to run it. Each reference has a "Hello world" section with the request:160161- **Hosted API**: [`references/hosted-api-quickstart.md`](references/hosted-api-quickstart.md)162- **Self-hosted NIM**: [`references/self-hosted-nim-quickstart.md`](references/self-hosted-nim-quickstart.md)163164Both pull a real sample image from the public QCalEval benchmark dataset, so no165local test image is needed. The request shape is the same either way; only the166endpoint and model ID differ -- read the self-hosted ID from `/v1/models` rather167than copying the hosted string across.168169## Examples170171- "I don't have a GPU, how do I try Ising Calibration?" -> hosted API path:172 generate an nvapi- key, store it as `NVIDIA_API_KEY`, verify with the curl173 ping in `references/hosted-api-quickstart.md`.174- "Run the Ising Calibration NIM on our H200 box" -> self-hosted path: generate175 an NGC personal key with the NGC Catalog scope, `docker login`, pull and run176 the container, wait for `/v1/health/ready`.177- "My calls return 401" -> connectivity checklist: establish which setup first,178 then follow the matching Troubleshooting entry below.179180## Next steps181182Once the connectivity checklist passes, this skill's job is done -- you have a183working, authenticated connection. What to do with it is out of scope here;184go to:185186- **Building an agentic calibration workflow?** Start with the187 [Quantum Calibration Agent Blueprint](https://github.com/NVIDIA/Quantum-Calibration-Agent-Blueprint/)188 -- an end-to-end workflow built on this model.189- **Want the other models in this family (decoders, other calibration190 sizes)?** Browse the191 [Hugging Face collection](https://huggingface.co/collections/nvidia/nvidia-ising).192- **Training or optimizing a predecoder?** See the193 [Ising-Decoding cookbook](https://github.com/NVIDIA/Ising-Decoding).194195## Limitations196197- Hosted API rate limits and pricing are not published in this skill; check198 the build.nvidia.com model page for current terms.199- GPU memory requirements vary by GPU family -- see200 `references/self-hosted-nim-quickstart.md` for the tested configurations.201202## Troubleshooting203204- **Error**: `401 Unauthorized` on the hosted API. **Cause**: missing/expired205 `NVIDIA_API_KEY`, or using the NGC key instead of the `nvapi-` key.206 **Solution**: regenerate at `build.nvidia.com/settings/api-keys`.207- **Error**: `docker login` or `docker pull` fails with auth error. **Cause**:208 missing/expired `NGC_API_KEY` (or set in a different shell than the one209 running `docker login`); using the `nvapi-` key instead of the NGC key; or a210 key whose service scopes omit **NGC Catalog**. **Solution**: check the scope211 before assuming the key is bad -- a wrongly-scoped key fails identically to an212 invalid one. Regenerate at `org.ngc.nvidia.com/setup/personal-keys` with NGC213 Catalog included.214- **Error**: `docker login` succeeds but `docker pull` returns 401 or215 "not found". **Cause**: the credential is fine but the image is not visible216 to the account, typically an unaccepted access agreement on the catalog page.217 **Solution**: have the user open the catalog page while signed in to confirm218 the image is visible to their account.219- **Error**: `401`/`403` from a self-hosted NIM endpoint. **Cause**: the220 container does not authenticate requests, so the rejection comes from a221 reverse proxy, API gateway, or load balancer in front of it. **Solution**:222 check that layer's configuration and credentials. To confirm, bypass it:223 on the machine running Docker, curl `localhost:<host-port>`, where the host224 port is the left side of the `-p` flag shown by `docker ps` (8000 if the225 quickstart command was used unchanged). A `200` there proves the container226 is fine and the 401 comes from the layer in front. Regenerating the NGC key227 does not help here.228- **Error**: container starts but the startup weight download fails.229 **Cause**: the weights come from public Hugging Face, so the usual cause is230 outbound network access from the container (proxy, firewall, DNS, or231 huggingface.co blocked). **Solution**: check `docker logs <container>` for232 the failing URL and fix egress.233- **Error**: connection refused on `localhost:8000` (or whichever host port234 was mapped). **Cause**: NIM container still loading weights, crashed, or the235 `-p` host port does not match the one being curled.236 **Solution**: check `docker ps` and `docker logs <container>`; wait for237 `/v1/health/ready` to return `200` before sending requests.238- **Error**: `Insufficient GPU memory` / OOM on container start. **Cause**: the239 GPU does not have enough memory for any configuration the container can run.240 **Solution**: use a GPU with more memory, or more GPUs; see the tested241 configurations in `references/self-hosted-nim-quickstart.md`.